Skip to content

fix(agents): harden the default-agent healer and the file-name map - #16455

Merged
bolichen97 merged 1 commit into
mainfrom
fix/materialized-seen-bound
Oct 3, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/materialized-seen-bound

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: the default-agent healer writes the owner's config only on the owner's own request, a local file cannot redirect a binding to an edition agent, and every map the agents-directory scan keeps for the process is bounded where it is kept.

Review of the release/0.8.0 backport of #16323 and #16410 (#16385) found four defects in code that is already on main:

  1. Healing by default. refresh_materialized_agents(*, heal_default=True) (config/loader.py) healed on every caller that did not opt out. Two such callers can be reached from someone other than the owner: schedule_materialized_agents_refresh (app registration, which a turn for an unresolved app slot can trigger) and side_readonly_spec's refresh. So a non-owner's action could set the owner's default_agent to default. The value is fixed and the template had to be gone already, but the write is still the owner's.
  2. Edition agent redirect. dispatch_kiro_agent applies the stem map to any name not declared on disk. An edition-contributed agent is never declared on disk. So a user-level captain.json declaring pilot turned a binding to the edition agent captain into a dispatch of pilot.
  3. Unbounded stem map. _MATERIALIZED_STEMS kept every mismatched stem -> declared-name pair from the user-writable directory, with no count or length bound.
  4. Unbounded removal evidence. _MATERIALIZED_SEEN (fix(agents): reset a default agent only when its template was removed #16410) only grew: no count bound, no name-length bound, no report of what it drops.

The ProviderRegistry.agent_runtime_policy docstring (platform/interfaces.py) and its spec row also said the key is the member's kiro_agent. Since #16323 the catalog passes dispatch_kiro_agent(kiro_agent).

Why it matters

1 lets a non-owner trigger a write to the owner's config. 2 lets a file in a user-writable directory change which agent a binding runs. 3 and 4 are process-lifetime state that a writable directory can grow without limit. The docstring is the companion's contract.

Not a goal

  • No change to what counts as a removal, or to the PUT, the snapshot's contents within the bounds, or the catalog's lookup.
  • The boot warm does not heal. It has no earlier snapshot to compare against, so it never had evidence to act on.

What changed (motivation → approach → change)

  • refresh_materialized_agents defaults to heal_default=False. Only the owner's catalog fetch passes True (heal_default=owner, unchanged). A refresh that does not heal still records the removals it sees, so the next owner fetch acts on them.
  • dispatch_kiro_agent returns a name the edition contributes verbatim. The edition is asked (_edition_agent_names) only when a stem mapping exists, so the common path stays in memory.
  • _MATERIALIZED_SEEN is an insertion-ordered dict used as a set, written through _remember_seen. Each scan or publish moves the names still declared to the end. Past _MATERIALIZED_SEEN_MAX (4096) the oldest entries are evicted, and those are the removals seen longest ago.
  • _scan_materialized_index bounds the stem map where it is built: the same 4096-entry cap, and no stem or name longer than _MATERIALIZED_SEEN_NAME_MAX_CHARS (256). A name past the length bound is kept in neither map. A binding to it dispatches verbatim, and a default bound to it is never reset.
  • _report_dropped writes one aggregate warning per bounded map per scan or publish, and only when the dropped count changes. A landed snapshot records its declared names and its file-name bindings in a single _remember_seen call, so its eviction is counted, and its warning written, once.
  • The agent_runtime_policy docstring and platform-context spec row name the key as the dispatched agent.

Backwards compatibility

  • Compatible for every current caller.
  • The healer's only remaining trigger is the owner's catalog fetch, which is the moment its comment already names.
  • Reader lines that accept a deferred heal: app disable or uninstall (apps.bridges._deregister_agents -> schedule_materialized_agents_refresh) and template delete. These paths still record the removal, but the default is repointed only on the owner's next picker open, not inside the removal. The reason is that these refreshes also run from paths that do not establish an owner caller (a turn's re-registration, for one). Until that fetch, the dangling default fails visibly ("Agent mode ... is not available"), as it did before fix(agents): let an installed agent become the default agent #16323.
  • The drop-count warning stays. AUTOSDE's a-bound-bounds-every-field-it-retains requires overflow to be counted and reported once per snapshot, and the review on this PR's previous head enforced that.
  • Below the bounds, the maps hold exactly what they held before.

Tests

New in test/test_config_loader.py::TestDanglingDefaultAgentReset, each proven by mutating the code it guards:

Test Mutation that makes it fail
test_a_refresh_heals_only_when_its_caller_asks default back to heal_default=True
test_a_local_file_cannot_redirect_a_binding_to_an_edition_agent edition check removed
test_the_file_name_map_is_bounded_where_it_is_built_and_reported_once stem bounds removed; separately, the report-once guard removed
test_the_removal_evidence_is_bounded_and_evicts_the_oldest_removals_first eviction removed
test_a_name_past_the_length_bound_is_not_kept_as_evidence length check removed
test_an_unchanged_oversized_directory_reports_its_evidence_drop_once names and bindings recorded in two calls (6 warnings over 3 refreshes); separately, the report-once guard removed

The existing healer tests now opt in with heal_default=True, which is what they test.

Gates:

  • test_config_loader.py, test_agent_execution_catalog.py and test_config_api.py: 717 passed.
  • Every file referencing the refresh, the healer, default_agent, the catalog, dispatch or the snapshot, plus test/integration: 20772 passed. The 2 failures are in test_chat_runner_composition_contract.py, which fails identically on origin/main.
  • The baselined black and subprocess-encoding gates, isort, flake8, mypy (2079 files), comment-history, agent-SDK boundary and docs-lint gates pass.

Manual verification

N/A. The tests run real refreshes over a real agents directory and a real config.json.

Related Issues

Part of #16409. Follow-up to #16323 and #16410. Found on the backport #16385.

Pattern harvest

Rule candidate: review-prompt
Pattern: a refresh helper that performs an owner-scoped write must default to not writing, with each owner-authorized caller opting in. A name-to-target map built from a user-writable directory must not shadow a namespace it does not own (here, edition agents).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested a review from a team as a code owner October 3, 2026 09:37
@bolichen97
bolichen97 requested a review from buluoray October 3, 2026 09:37
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 3, 2026
@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

Design-level review of 61ea74674079a1f6ab4769c02f9fa9f64382983a — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

Healing is now opt-in, so an owner who disables an app or deletes a template keeps a dangling default_agent until they next open the picker.

Watch

  • The owner's own removal paths no longer heal. The patch changes refresh_materialized_agents(*, heal_default: bool = True) to False. That removes healing from every bare caller, not only the two non-owner ones the description names. The owner disabling or uninstalling an app goes through apps/bridges.py:_deregister_agents → schedule_materialized_agents_refresh(). The owner deleting a template goes through agent_templates.py:979. Both used to reset a default bound to the removed agent right away. Now the default keeps pointing at a missing agent until the owner's next catalog fetch, and every turn on that default is dispatched to a name with no config file. The section "Compatible for every current caller" doesn't mention this. "The healer's only remaining trigger is the owner's catalog fetch" states the narrowing without accounting for these callers.
    Clears when: owner-initiated removal paths (app disable/uninstall, template delete) pass heal_default=True, or the Backwards compatibility section lists them as Reader lines that accept healing being deferred to the catalog fetch.

Suggestions

  • dispatch_kiro_agent is documented as "a pure in-memory lookup", but it now calls _edition_agent_names() through the platform seam (builtin_agents()) whenever a stem mapping exists. Snapshot the edition names during the refresh instead, so dispatch really stays in memory on every edition.

[DESIGN-REVIEWED] 61ea746

Description read

[DESCRIPTION-READ] e2c82e31bbd3f051b131bdfeac3462023753d360b921bb0601ddf6edf8444cc2

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 61ea74674079a1f6ab4769c02f9fa9f64382983a — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The drop-count warning and its _MATERIALIZED_LAST_DROPPED state aren't needed for the Goal. The caps alone keep both maps bounded.

Not justified as shipped

  • Item 5 — oversized: the Goal is that "every map … is bounded where it is kept", and the caps in _remember_seen and _scan_materialized_index achieve that with no warning. The warning adds _report_dropped and another process-lifetime dict, _MATERIALIZED_LAST_DROPPED. It also needed its own fix ("recorded in two calls (6 warnings over 3 refreshes)"), which merged [*snapshot, *stems] into one call. Nothing in the description reports anyone needing this diagnostic.
    Subtraction: delete _report_dropped, _MATERIALIZED_LAST_DROPPED and the dropped counters. Keep the caps, and turn the two report-once tests into bound-only checks.
    Clears when: the warning is removed, or a report names an operator who could not diagnose a dropped mapping without it.

What this change ships

Inventory (6 items) — 5 justified

Intent: stop people other than the owner from rewriting the owner's default agent, stop local files from hijacking edition agents, and bound the state the agents-directory scan keeps for the process. FIX.

  1. A refresh no longer resets default_agent unless its caller opts in. Seven callers that use the default (chat turns, boot, template, side and app-registration refreshes) stop writing config; only the owner's catalog fetch passes True. — justified
  2. A binding to an edition-contributed agent is no longer redirected by a same-named local file. — justified
  3. The file-name map is capped at 4096 entries and 256 characters per name; a binding to an overlong name dispatches verbatim. — justified
  4. The removal evidence is capped and evicts the oldest entries first; a default bound to an overlong name is never reset. — justified
  5. A new warning fires once each time a map's drop count changes, backed by new per-process state. — oversized
  6. The agent_runtime_policy docstring and spec row now name the dispatched agent as the key. — justified

[FIRST-PRINCIPLES-REVIEWED] 61ea746

Description read

[DESCRIPTION-READ] dfb950f72d4e950e57091a237205c433df628a6692610c585a4bb1f1896676cc

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 61ea74674079a1f6ab4769c02f9fa9f64382983a — this comment is updated in place on each push.

Review details

No findings block the merge; the one advisory finding is below.

FINDING — src/kiro_crew/config/loader.py:5615 — Changing the default to heal_default: bool = False turns off default-agent healing for every caller that passes no argument. Those callers are the boot warm (server.py:5875), app deregistration through schedule_materialized_refresh, and the chat and side refreshes. So when the owner disables the app that owns their default agent, or a package's file is removed before a restart, default_agent keeps naming an agent that no longer exists. resolve_agent_bindings then dispatches that missing kiro_agent verbatim, and new chats fail with "Agent mode ... is not available" until the owner opens the agent picker. This is the case the reset_dangling_default_agent docstring says it handles ("a disabled app deregisters its agents"). → Fix: pass heal_default=True on the owner-side refreshes, at least the boot warm and app enable/disable. Those calls live in files this PR does not touch (server.py, apps/bridges.py).

[OPUS-REVIEWED] 61ea746

Verdict parsed from the review's SHA-scoped output markers for commit 61ea74674079a1f6ab4769c02f9fa9f64382983a.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 61ea74674079a1f6ab4769c02f9fa9f64382983a: <one-sentence reason>

bolichen97 added a commit that referenced this pull request Oct 3, 2026
…/0.8.0)

Backport of #16323, #16410 to release/0.8.0, cherry-picked in main's merge order.

* fix(agents): let an installed agent become the default agent (#16323)
  (cherry picked from commit 5c6268a)
  Backport adaptation: test/integration/conftest.py conflicted only on context; the
  source's added reset lines (config_loader import, docstring bullet, the three
  _MATERIALIZED_* resets and checks) were applied, nothing else. Every other file
  applied cleanly.

* fix(agents): reset a default agent only when its template was removed (#16410)
  (cherry picked from commit f16fa23)
  Backport adaptation: test/integration/conftest.py conflicted on context only (a
  main-only updates-loop entry next to it); only this change's _MATERIALIZED_SEEN
  lines were applied. Every other file applied cleanly.

* Also carries the follow-up proposed on main in #16455 (found by review of
  this backport): the healer's removal evidence is bounded at 4096 entries,
  evicting the oldest stale removals first, and a name longer than 256
  characters is not recorded; the agent_runtime_policy docstring and its spec
  row name the key as the dispatched agent.
@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 61ea74674079a1f6ab4769c02f9fa9f64382983a and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 61ea746

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 61ea74674079a1f6ab4769c02f9fa9f64382983a: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 3, 2026
@bolichen97
bolichen97 force-pushed the fix/materialized-seen-bound branch from 3983197 to 496808e Compare October 3, 2026 10:04
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 3, 2026
@bolichen97 bolichen97 changed the title fix(agents): bound the default-agent healer's removal evidence fix(agents): harden the default-agent healer and the file-name map Oct 3, 2026
Follow-ups to #16323 and #16410, found by review of their release/0.8.0
backport.

- Heal on request only. refresh_materialized_agents now defaults to
  heal_default=False, so a refresh reached from someone other than the owner
  (an app token's turn, a lookup, an app registration) can no longer write the
  owner's config.json. Only the owner's catalog fetch opts in. A refresh that
  does not heal still records the removals it sees.
- An edition agent cannot be redirected. dispatch_kiro_agent no longer applies
  the stem map to a name the edition contributes, so a user-level
  "<edition-agent>.json" that declares another name cannot turn a binding to
  the edition agent into a dispatch of that other agent.
- Bounded retained maps. _MATERIALIZED_SEEN is an insertion-ordered dict used
  as a set, capped at 4096 entries; each scan moves the still-declared names
  to the end, so the oldest stale removals are evicted first.
  _MATERIALIZED_STEMS is bounded the same way where it is built. A name longer
  than 256 characters is kept in neither. What a bounded write drops is
  reported in one aggregate warning, written only when the count changes; a
  landed snapshot records its names and its file-name bindings in one call, so
  it is counted and reported once.
- The agent_runtime_policy docstring and its spec row now name the key as the
  agent the member runs (its kiro_agent through dispatch_kiro_agent).
@bolichen97
bolichen97 force-pushed the fix/materialized-seen-bound branch from 496808e to 61ea746 Compare October 3, 2026 10:22
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 3, 2026
@bolichen97
bolichen97 merged commit 4a11ed2 into main Oct 3, 2026
123 of 134 checks passed
@bolichen97
bolichen97 deleted the fix/materialized-seen-bound branch October 3, 2026 11:32
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 3, 2026
bolichen97 added a commit that referenced this pull request Oct 3, 2026
…/0.8.0)

Backport of #16323, #16410, #16455 to release/0.8.0, cherry-picked in main's merge order.

* fix(agents): let an installed agent become the default agent (#16323)
  (cherry picked from commit 5c6268a)
  Backport adaptation: test/integration/conftest.py conflicted only on context; the
  source's added reset lines (config_loader import, docstring bullet, the three
  _MATERIALIZED_* resets and checks) were applied, nothing else. Every other file
  applied cleanly.

* fix(agents): reset a default agent only when its template was removed (#16410)
  (cherry picked from commit f16fa23)
  Backport adaptation: test/integration/conftest.py conflicted on context only (a
  main-only updates-loop entry next to it); only this change's _MATERIALIZED_SEEN
  lines were applied. Every other file applied cleanly.

* fix(agents): harden the default-agent healer and the file-name map (#16455)
  (cherry picked from commit 4a11ed2)
bolichen97 added a commit that referenced this pull request Oct 3, 2026
…/0.8.0)

Backport of #16323, #16410, #16455, #16512 to release/0.8.0, cherry-picked in main's merge order.

* fix(agents): let an installed agent become the default agent (#16323)
  (cherry picked from commit 5c6268a)
  Backport adaptation: test/integration/conftest.py conflicted only on context; the
  source's added reset lines (config_loader import, docstring bullet, the three
  _MATERIALIZED_* resets and checks) were applied, nothing else. Every other file
  applied cleanly.

* fix(agents): reset a default agent only when its template was removed (#16410)
  (cherry picked from commit f16fa23)
  Backport adaptation: test/integration/conftest.py conflicted on context only (a
  main-only updates-loop entry next to it); only this change's _MATERIALIZED_SEEN
  lines were applied. Every other file applied cleanly.

* fix(agents): harden the default-agent healer and the file-name map (#16455)
  (cherry picked from commit 4a11ed2)
* fix(agents): heal a default agent only after a scan that read every spec (#16512)
  (cherry picked from commit 4576a29)
bolichen97 added a commit that referenced this pull request Oct 3, 2026
…/0.8.0) (#16385)

* fix(catalog): restore companion runtime_policy on member rows (#12686)

Co-authored-by: Premshay <28099628+Premshay@users.noreply.github.com>
(cherry picked from commit fa1b47d)

* fix(agents): let an installed agent become the default agent (release/0.8.0)

Backport of #16323, #16410, #16455, #16512 to release/0.8.0, cherry-picked in main's merge order.

* fix(agents): let an installed agent become the default agent (#16323)
  (cherry picked from commit 5c6268a)
  Backport adaptation: test/integration/conftest.py conflicted only on context; the
  source's added reset lines (config_loader import, docstring bullet, the three
  _MATERIALIZED_* resets and checks) were applied, nothing else. Every other file
  applied cleanly.

* fix(agents): reset a default agent only when its template was removed (#16410)
  (cherry picked from commit f16fa23)
  Backport adaptation: test/integration/conftest.py conflicted on context only (a
  main-only updates-loop entry next to it); only this change's _MATERIALIZED_SEEN
  lines were applied. Every other file applied cleanly.

* fix(agents): harden the default-agent healer and the file-name map (#16455)
  (cherry picked from commit 4a11ed2)
* fix(agents): heal a default agent only after a scan that read every spec (#16512)
  (cherry picked from commit 4576a29)

---------

Co-authored-by: Premshay <premshay@gmail.com>
Co-authored-by: Premshay <28099628+Premshay@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant