Skip to content

fix(agents): reset a default agent only when its template was removed - #16410

Merged
bolichen97 merged 1 commit into
mainfrom
fix/default-agent-healer-scope
Oct 3, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/default-agent-healer-scope

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: the default-agent healer from #16323 resets the owner's default_agent only when its template really was removed, and only for the owner's own request.

Two defects on main (#16409):

  1. Absence treated as removal. reset_dangling_default_agent (src/kiro_crew/config/loader.py) counted a template as gone when _MATERIALIZED_AGENTS, the scan of ~/.kiro/agents only, did not declare it. Two kinds of binding dispatch without such a file:

    • an agent a project checkout declares, which kiro-cli resolves against the session directory first;
    • an agent the edition contributes (AgentCatalogProvider.builtin_agents, merged by agent_discovery._with_edition_agents).

    A default bound to either kind was reset to default on every refresh: the boot warm, each app registration, and each catalog fetch. It was reset again after the owner restored it.

  2. Non-owner fetch writes owner config. GET /api/agents/catalog (dashboard/handlers/agent_catalog.py) ran refresh_materialized_agents() with healing on before any owner check. So a non-owner subject's or an app token's fetch could write the owner's config.json.

Why it matters

The first defect silently and durably replaces a setting the owner chose, and it recurs, so the owner cannot keep the choice. The second lets a caller who is not the owner trigger a write to the owner's config.

Not a goal

What changed (motivation → approach → change)

Symptom → cause: the healer's only evidence was absence from one directory, which is narrower than where kiro-cli and the edition resolve agents. The catalog's executor call healed for every caller.

  • A new process-wide _MATERIALIZED_SEEN set records every name a landed snapshot or a publish has let a binding dispatch: declared names and file-name bindings (_MATERIALIZED_STEMS keys). It only grows. A name in it that the current snapshot does not declare was removed. Because the evidence is kept, not taken from a diff of two consecutive scans, a refresh that does not heal (a lazy lookup, a non-owner fetch) cannot use it up before one that does.
  • reset_dangling_default_agent acts only when the default's template is such a removed name and is not an edition agent (_edition_agent_names, read through the same platform seam the agent listing uses, failing closed to none). The in-lock re-check now compares the template it found, so a binding changed in the window is not reset on the old evidence.
  • The integration harness clears _MATERIALIZED_SEEN between boots and checks it in its residue witness, like the other snapshot globals.
  • api_agent_catalog computes the owner check once, before the refresh, and passes heal_default=owner. Redaction uses the same value.

Backwards compatibility

Compatible. An uninstall, app disable or file delete seen by a running gateway still resets a default that ran it. A default that dispatches is no longer touched.

Tests

  • test/test_config_loader.py::TestDanglingDefaultAgentReset:
    • New: test_a_template_the_directory_never_declared_is_not_reset, test_a_removed_file_whose_agent_the_edition_supplies_is_not_reset, and test_a_refresh_that_does_not_heal_leaves_the_evidence_for_one_that_does (a non-healing refresh sees the file gone first; the owner's next refresh still resets).
    • The reset, lock-race and missing-alias tests now land a snapshot that declares the template and then remove its file, so each one exercises the guard it names rather than passing on an empty removed. The lock-race test also asserts that the locked write was reached.
  • test/test_agent_execution_catalog.py:
    • New: test_only_the_owner_s_catalog_fetch_may_reset_the_default (non-owner user, anonymous, app token, no state) and test_the_owner_s_catalog_fetch_resets_a_dangling_default.

Regression proof, with the tests kept:

  • loader.py and agent_catalog.py at origin/main (plus an empty _MATERIALIZED_SEEN so the test setup imports): 7 tests fail. They are the two absence tests and all five catalog cases.
  • loader.py at this PR's first revision, which diffed two consecutive scans: test_a_refresh_that_does_not_heal_leaves_the_evidence_for_one_that_does fails, which is the review finding on that revision.

Gates:

  • test_config_loader.py, test_agent_execution_catalog.py and test_config_api.py: 711 passed.
  • Every test file that references the refresh, the healer, default_agent, the catalog or the stem map (141 files), plus test/integration: 12499 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 and flake8 pass. mypy reports no issues (2079 files).
  • The comment-history and agent-SDK boundary gates (base origin/main) and docs-lint pass.

Manual verification

N/A. The loader tests run real refreshes over a real agents directory and config.json, and the catalog tests drive the real route.

Related Issues

Fixes #16409. Follow-up to #16323. Found in review of its release/0.8.0 backport (#16385).

Pattern harvest

Rule candidate: review-prompt
Pattern: a self-healing write that infers "X was removed" from "X is absent from one source" when other sources can also supply X. Require evidence of a transition (seen, then not seen), and gate the write on the caller who owns the state.

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 07:25
@bolichen97
bolichen97 requested a review from CrysisDeu October 3, 2026 07:25
@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

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 3866d16caf95edfc12874adf2306a41ae74a65f0 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 3866d16

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

@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Check that resetting a default whose user-level file was deleted is still right when a project checkout declares an agent with the same name. kiro-cli would still dispatch that agent.

[DESIGN-REVIEWED] 3866d16

Description read

[DESCRIPTION-READ] 819b13141173747391fa98311b1830c8fbc49d2bbacb2cbeb63f4aac699cc1a4

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 3866d16caf95edfc12874adf2306a41ae74a65f0 — 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

_edition_agent_names is a second copy of the edition-agent seam read that agent_discovery._with_edition_agents already does, name filter included.

Not justified as shipped

  • Item 3 — duplicate of src/kiro_crew/agent_discovery.py:1814: the new safe_context_call(lambda: list(current_context().agent_catalog.builtin_agents()), fallback_factory=list, log_message="builtin_agents lookup failed; using none") and its isinstance(name, str) and name filter repeat _with_edition_agents line for line. A grep for builtin_agents() finds 2 callers, and this PR adds the second. If the edition seam's failure handling or row validation changes, one copy will drift and the healer and the listing will disagree on which agents exist.
    Subtraction: delete loader._edition_agent_names and take the names from the existing merge, e.g. {a.name for a in agent_discovery._with_edition_agents([])}.
    Clears when: the loader reads edition agent names through the one existing seam reader, or the PR shows why that import direction can't work.

What this change ships

Inventory (5 items) — 4 justified

Intent: stop the default-agent healer from overwriting the owner's chosen default unless its template really was removed, and only when the owner makes the request. This is a FIX (#16409).

  1. A default bound to an agent this directory never declared (from a project checkout or the edition) is no longer reset on every refresh — justified
  2. A non-owner, anonymous or app-token catalog fetch no longer writes the owner's config.json — justified
  3. A removed file whose agent the edition still supplies keeps the default — duplicate of agent_discovery._with_edition_agents
  4. The in-lock re-check resets only when it finds the same template, so a binding changed in that window is left alone — justified
  5. The integration harness clears and checks the new _MATERIALIZED_SEEN set between boots — justified

[FIRST-PRINCIPLES-REVIEWED] 3866d16

Description read

[DESCRIPTION-READ] 140de3e833792d3b6a65c94fef4e74b84e4d090e7cbdde6f4d9bed85dd914e6d

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 3866d16caf95edfc12874adf2306a41ae74a65f0 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 3866d16

Verdict parsed from the review's SHA-scoped output markers for commit 3866d16caf95edfc12874adf2306a41ae74a65f0.

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

The default-agent healer added in #16323 treated "not declared in
~/.kiro/agents" as "the template is gone". A default bound to an agent that
dispatches without a file there (a project checkout's own spec, or an agent
the edition contributes) was reset to "default" on every snapshot refresh,
including the boot warm, and again after the owner restored it.

The healer now acts only on a REMOVED name: one a landed snapshot (or a
publish) in this process let a binding dispatch, as a declared name or a
file-name binding, and the current snapshot does not. That evidence is kept in
a process-wide set, so a refresh that does not heal (a lazy lookup, a
non-owner fetch) cannot use it up before one that does. A removed name the
edition still supplies is kept. An agent the directory never declared is
never evidence of a removal.

The agent catalog's fetch ran the healer, and its config write, for any
caller. It now heals only on the owner's own fetch; anyone else's still gets a
freshly scanned template list.

Fixes #16409
@bolichen97
bolichen97 force-pushed the fix/default-agent-healer-scope branch from 5a975d4 to 3866d16 Compare October 3, 2026 07:54
@bolichen97
bolichen97 merged commit f16fa23 into main Oct 3, 2026
99 of 108 checks passed
@bolichen97
bolichen97 deleted the fix/default-agent-healer-scope branch October 3, 2026 08:22
@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Oct 3, 2026
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.
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.
bolichen97 added a commit that referenced this pull request 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.
- 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 added a commit that referenced this pull request 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 added a commit that referenced this pull request Oct 3, 2026
…16455)

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 added a commit that referenced this pull request Oct 3, 2026
…ader

The default-agent healer (#16410) read the edition's agent catalog with its own
copy of the seam call and name filter that agent_discovery._with_edition_agents
already performs. It now takes the names from that function, so a change to
the seam's failure handling or row validation reaches the healer and the agent
listing together.
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
…ader (#16448)

The default-agent healer (#16410) read the edition's agent catalog with its own
copy of the seam call and name filter that agent_discovery._with_edition_agents
already performs. It now takes the names from that function, so a change to
the seam's failure handling or row validation reaches the healer and the agent
listing together.
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.

Default-agent healer resets a default that still dispatches, and runs on non-owner catalog fetches

1 participant