Skip to content

fix(mcp): reconcile agent-config tool refs against the final server map - #11989

Merged
iamwhatever merged 1 commit into
mainfrom
fix/prune-orphan-mcp-entries-11980
Sep 20, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/prune-orphan-mcp-entries-11980

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

kiro-cli mounts what mcpServers declares, so a @ref in tools or
allowedTools naming a server absent from that map mounts nothing. Several passes
of rebuild_agent_config narrow the server map without touching the ref lists:

  • the resolution pass ends with config["mcpServers"] = valid_servers, so a server
    whose command does not resolve is dropped by OMISSION;
  • the locked app re-merge does del servers[_k] for an app-namespaced entry whose
    app is not confirmed enabled.

Neither strips the refs, and nothing else reconciles them, so the refs stay in the
rendered file indefinitely.

Reported first-hand in #3310's comment of 2026-08-27, reached by renaming MCP
servers: after several renames the reporter's ~/.kiro/agents/kirocrew.json held 21
servers against 9 in ~/.kiro/settings/mcp.json, every orphan matched an
MCP probe failed [...] warning, and each also had dangling @<name> refs in both
tools and allowedTools. Split out of #3310 as #11980 because that issue's
remaining scope is credential-lifecycle decisions while this half is a mechanism.

The invariant is not new to this PR. It is stated twice already, and enforced only
where the deleting code happens to remember it:

  • mcp_cleanup.purge_deleted_proxy_from_config strips refs alongside its own
    deletes, with a comment giving the reason;
  • agent_capabilities._materialize filters allowedTools on exactly this test,
    server-present and not disabled.

Why it matters

Each dangling ref keeps a dead name in front of discovery, so the cost grows with
every rename instead of settling, and the only visible symptom names a server the
user believes they already removed.

The allowedTools side is worse than cosmetic. That list is the one path that never
reaches the PreToolUse gate, which the rebuild's own comments call out. A grant left
there is bound to the NAME, not to the server that earned it, so a server added
under that name later inherits an auto-approval nobody granted for it.

What changed

mcp_cleanup.prune_dangling_tool_refs drops tools/allowedTools refs whose
server the final map does not hold. It is called once inside _finalize_and_write,
the funnel every write path goes through, so one reconcile covers every narrowing
pass including one added later rather than each pass remembering separately. It sits
before _seed_kas_permissions for the reason that call already documents: that
function reads allowedTools to build the KAS policy, so a policy seeded first
would describe refs this then removes.

Two absences are exempt, because the rebuild expects them and a later pass reverses
them while an existing config deliberately never re-adds a template ref:

  • a server whose command failed to resolve on this pass, e.g. a binary missing from
    this rebuild's PATH. This case also reaches the per-tool grant, which nothing
    re-emits: the ref sync only ever writes whole-server @alias refs, so dropping
    @server/search over one bad PATH would lose it for good.
  • a gated-off shipped server. The withhold audit states the decision plainly, that
    its mcpServers entry is withheld while its tools ref is retained, so removing
    that ref would unmount the server permanently once the gate reopened. I did not
    know about this class when I first wrote the pass; an existing test caught it, and
    removing the exemption still fails that test, which is how I know the exemption is
    load-bearing rather than defensive.

Server extraction reuses the spelling agent_capabilities._materialize and
apps.bridges already use, ref[1:].split("/", 1)[0], so the per-tool forms
(@server/tool, @server/*) resolve to the same server in all three. A second
spelling would let the three disagree about which refs dangle.

Fails safe in both directions: a mcpServers that is not a dict yields no readable
verdict so nothing is dropped, and non-string or sigil-less entries are left to the
passes that own them.

What review changed about the change

Three blocking findings, all real, all fixed rather than overridden.

A reserved kiro namespace is not a server ref. @builtin is listed by kiro's
own configuration reference, never appears in mcpServers, and carries the
whole built-in tool surface plus the tool_search loader. The first version of
this reconcile deleted it from both lists at the funnel every write goes
through, on every rebuild, with an existing config that never re-adds the
entry. RESERVED_TOOL_NAMESPACES is now imported from the module documented as
the ONE reader of the tools ref vocabulary, so the two cannot drift, and
@builtin survival is pinned at the helper and through a full rebuild.

The exemption is collected in the one branch that means it -- a command was
declared and did not resolve -- instead of inferred from "declared but missing
from the final map". Inferring swept in a commandless stub, whose retained
allowedTools ref is a grant left sitting on a name that a different server
can be bound to next.

An app-scoped name stays exempt only while its app is still enabled, because a
server can fail to resolve here and have its app deregistered concurrently.

Dropping a ref out of allowedTools revokes an auto-approval, so it now emits
mcp_auto_approve_revoked into the same SEL feed as the withhold in the same
pass, rather than only an INFO log.

Deliberately NOT in scope

The orphaned mcpServers entries themselves are not pruned. rebuild_agent_config
records the opposite decision, that the unmount has no safe lever in this file
because the generated config is simultaneously the mount decision and the only home
for agent-only configuration, so dropping an entry destroys whatever lives only
there. A server defined only in the agent config is documented as supported in the
same function. That decision is parked as #6171 and is a maintainer's call, not
something to reverse inside a ref fix, so #11980's first acceptance item is
deliberately unmet and its comment thread says so.

Tests

test/test_mcp_dangling_tool_refs.py, 14 cases on the helper: both ref forms, the
present-server control, non-@ and non-string passthrough, a bare sigil, repeated
occurrences, surviving order, idempotence, and the four not-a-dict shapes.

test_a_rebuild_drops_a_ref_whose_server_the_map_does_not_declare in
test/test_agent.py pins the CALL SITE through a real install rather than the
helper alone, and measures both sides: the orphan's refs are gone from both lists
and the declared server keeps both its mount and its grant.

Mutation-verified, six mutations, each caught and each by a bounded set:

mutation result
known = set(servers) (drop the exempt union) 1 failed
_ref_server returns the whole ref 2 failed
if not servers instead of isinstance(..., dict) 2 failed
drop the non-string passthrough 1 failed
call site passes {} instead of config 1 failed, the integration test
remove the gated-off exemption 1 failed, the existing withhold test

The declared guard is pinned by a PAIR of tests on the same input, one with the
declaration and one without, so a blanket keep cannot pass as the guard.

Targeted suites: 14/14 new, 255/255 test_agent.py, 374/374 across the four most
affected files, 295/295 across the remaining rebuild-touching files. flake8,
isort, mypy clean; the comment-history gate passes on all four changed files.

One existing fixture had to change and I am flagging it rather than leaving it in
the diff unremarked: test_existing_config_seeds_missing_tool_search declared an
empty mcpServers beside an MCP ref it asserts is preserved, which is the dangling
state itself. Its subject is tool_search seeding and order, so the fixture now
declares that server and every assertion it makes about its own subject is
unchanged. The alternative, asserting the ref is dropped, would have destroyed its
ability to test the governance point it exists for.

Pattern harvest

Rule candidate: semgrep
Pattern: a name-keyed map is narrowed by rebinding it to a filtered copy
(config["mcpServers"] = valid_servers) or by del servers[key], in a function
that never calls the reconcile which strips references naming the removed keys.

This generalizes, and the shape of the miss is the part worth keeping. The
invariant "no tools or allowedTools ref may name an absent server" was
already written down twice in the tree and already enforced twice, and both
enforcement points sit on a path that DELETES a server:
purge_deleted_proxy_from_config strips the refs it orphans, and the capability
builder skips an allowedTools ref whose server is not present. Neither of the
two sites fixed here deletes a server. One drops a server by OMISSION, by
rebinding the map to the subset that resolved, and one removes a locked app
entry during a later re-merge. Both are correct about the server map, and
neither is on the path that carries the cleanup.

That is the class: an invariant maintained at N removal sites is broken by the
N+1th, and a new removal site appears every time there is a new reason to
withhold a server. This fix moves enforcement to one reconcile at the end of the
rebuild, after every writer, so the next narrowing site inherits it instead of
having to remember it. The rule candidate is the ratchet for any future site
that does not flow through that boundary.

Closes #11980

@chenmingwei23
chenmingwei23 requested review from a team and hoang-phan98 September 19, 2026 07:47
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 19, 2026
@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 61c35de68d6e6bb336de87928105e74b1d7e77a1 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 61c35de

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

@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

App-ownership completeness is reconstructed inside agent.py by re-walking the apps directory whose skip semantics apps.manager.list_apps owns — a shadow reader that drifts silently.

Watch

_app_owned_mcp_keys re-derives which records list_apps silently skipped (_occupied, _entry_hides_a_claim, junction probing, INSTALLED_META_FILENAME layout) because — as its own comments say — "list_apps drops an app whose installed record does not read … SILENTLY rather than raising". If apps.manager later changes its record layout or skip behavior, this mirror goes stale without any test failing in the owner's suite, and the failure lands on the unrecoverable side: fully_read misreads as complete → a mount ref is pruned that "an existing config never re-adds". The completeness/claims read belongs behind an apps.manager API next to _absence_is_genuine, which already encodes the same fail-to-unknown rule.
Clears when: apps.manager exposes the claims-plus-completeness read (or list_apps reports skips) and agent.py consumes it instead of walking apps_dir() itself — acceptable as a fast follow given the tests pinning current behavior.

[DESIGN-REVIEWED] 61c35de

@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 61c35de68d6e6bb336de87928105e74b1d7e77a1 — 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: PASS

Verify the deliberate cost: any rebuild while a binary is off PATH now revokes that server's auto-approvals, and a human re-grants after every such hiccup.

Not justified as shipped

  • Item 5 — rides along: SEL event mcp_auto_approve_revoked is not the ref fix; declared, and the harm (a revoked approval leaving no operator record) is named.
  • Item 6 — rides along: WARNING-level logging of dropped mount refs is not the ref fix; declared, and grounded in the shipped agent.log_level default hiding INFO.

What this change ships

Inventory (10 items) — 8 justified

Intent: FIX — stop renamed/uninstalled MCP servers leaving dead @refs and stale auto-approvals in the rendered agent config (#3310 → #11980).

  1. Rebuild removes tools/allowedTools refs naming servers absent from the final map — justified
  2. A disabled or uninstalled app's server loses both its refs — justified
  3. An unresolved-command server keeps its mount refs but loses its auto-approval unless a readable source or enabled app still declares it — justified
  4. @builtin reserved-namespace refs survive every rebuild — justified
  5. Revoking a grant now emits SEL event mcp_auto_approve_revoked — rides along (declared; harm named)
  6. Dropped mount refs log at WARNING, visible at the shipped default — rides along (declared)
  7. New callable prune_dangling_tool_refs with split mount/grant exemption sets — justified (1 counted consumer, agent.py:5494)
  8. App-ownership read with start/end snapshots and link/junction probes keeping grants and mounts apart under read failure — justified
  9. test_existing_config_seeds_missing_tool_search fixture now declares its server — justified (declared; its subject's assertions unchanged)
  10. New "final ref reconcile" section in docs/architecture/mcp.md — justified (AGENTS.md same-commit doc mandate)

[FIRST-PRINCIPLES-REVIEWED] 61c35de

@github-actions

github-actions Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

I've read the full diff, the discovery pass output (no candidates), and verified the load-bearing facts: RESERVED_TOOL_NAMESPACES holds bare names ("builtin") matching _ref_server's stripped output; _narrowed_away/_gated_aliases/_vouched_sources/ownership keys are all alias-normalized to the same spelling the config refs resolve to; the mount/grant split, the tri-state ownership read, the start/end snapshots, family matching, and the fail-safe on a non-dict map all trace consistently to their tests. Nothing crosses the 80+ grounding bar.

No findings.

[OPUS-REVIEWED] 61c35de

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

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

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 19, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/prune-orphan-mcp-entries-11980 branch from d414572 to d8cd455 Compare September 19, 2026 09:35
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 19, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/prune-orphan-mcp-entries-11980 branch from d8cd455 to 1354c2f Compare September 19, 2026 10:03
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 19, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/prune-orphan-mcp-entries-11980 branch from 1354c2f to 062b849 Compare September 19, 2026 10:36
@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 Sep 19, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

On the First Principles CONCERNS, item 6: naming the bypassing path rather than deleting the strip.

purge_deleted_proxy_from_config is a public callable and its own unit tests
call it directly, with no rebuild and no write funnel anywhere in the test. Two
of them assert the ref strip as part of its contract:
test_installer_shim_and_cleanup.py asserts @playwright-mcp leaves both
tools and allowedTools after a bare
mcp_cleanup.purge_deleted_proxy_from_config(config) call, and the sibling test
asserts an operator's own same-named server keeps its ref. That is the path the
review asks me to name: the function is reachable, and measured, outside
_finalize_and_write.

Delegating instead of deleting does not work either. The purge runs before the
funnel, so a prune_dangling_tool_refs(config) call from inside it would see
the narrowed map without the unresolved-command exemption, which is only
assembled at the funnel, and would drop the refs of a server whose command
merely failed to resolve on this pass. The purge's own strip cannot over-reach
by construction: it is scoped to the names it just removed.

The divergence the review names is real and worth stating plainly: the purge's
strip matches @name only, so a @name/tool grant for a purged server is left
for the funnel reconcile to drop. On the rebuild path that happens in the same
pass. A standalone caller keeps the narrower behaviour it has today, which this
change does not alter.

Happy to be overruled if the preference is to delete the strip and adjust its
two tests; I left it because narrowing a public function's measured contract to
remove a duplicate seemed the larger change of the two.

@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 Sep 19, 2026
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Sep 19, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/prune-orphan-mcp-entries-11980 branch from 1d5bf8f to ba88fe9 Compare September 19, 2026 14:44
@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 Sep 19, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Fixed in ba88fe912a, and the fix is the structural one this finding points at rather than another patch to the shared set.

The finding is correct. _base_still_grants fell back to the pre-rebuild answer when _ownership_full_now was false, but that flag is GLOBAL while the question it answers is per-base. So one unrelated unreadable app cleared it, and a genuinely uninstalled app's stale grant survived on the strength of a different app's read failure. The adjudication is right that the trigger is routine: this module's own comment calls an unread app the ordinary shape of the failure.

Why the remedy is worth taking as stated. Every round of findings on this predicate has been an instance of one conflict: tools and allowedTools were sharing a single exemption set while failing in opposite directions.

  • Keeping a MOUNT ref too long costs a mount attempt against a name that holds nothing. Dropping one can unmount a server for good, because an existing config never re-adds a template ref.
  • Keeping a GRANT too long hands the next server on that name an auto-approval nobody granted, on the one list that never reaches the PreToolUse gate. Dropping one costs an approval a human can give again.

One set cannot be right for both, so each compromise produced a new hole. prune_dangling_tool_refs now takes declared_grants beside declared, defaulting to it so every existing caller is unchanged, and the rebuild builds two sets: _exempt_mounts keeps a name whose ownership merely went unread, _exempt_grants requires a positive final answer. The doubt is now resolved in each list's own safe direction instead of one shared direction that had to be wrong somewhere.

Evidence. Collapsing the two predicates back into one reproduces this finding exactly: assert '@live:srv' not in ['@live:srv']. 548 tests green across test_agent, the dangling-ref suite, test_app_manager and test_app_mcp_scoping, including two new helper-level tests -- one that a name in declared but not declared_grants keeps its mount and loses its grant, and one that omitting declared_grants leaves both lists reading declared, so adding the parameter cannot silently start pruning an existing caller's grants.

One test changed its expectation and I am flagging it rather than letting it pass as a rename. test_a_transiently_unread_claim_does_not_revoke_an_enabled_app_grant asserted the grant survived the doubt. Under the split that is no longer the right answer for the grant, only for the mount, so it is now test_a_transiently_unread_claim_keeps_the_mount_and_drops_the_grant and asserts both halves. Its previous form encoded the compromise this finding rejects.

One proof I did not get. I mutation-verified the grant side. The mirror mutation -- making _exempt_mounts use the strict predicate -- was refused four times by the gateway's path resolver, so I have not run it. The same test's two tools assertions do cover that direction, but I have not watched them fail, and I am not claiming otherwise.

flake8, isort, mypy and the comment-history gate clean on all four files. black flags one hunk in mcp_cleanup.py at line 328, inside purge_deleted_proxy_from_config; my hunks end at 302, so it is pre-existing and left alone.

@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 Sep 19, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/prune-orphan-mcp-entries-11980 branch from ba88fe9 to 03b6060 Compare September 19, 2026 15:06
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

03b6060afb fixes F2. F1 I am NOT implementing, because it reverses the instruction this same lane gave one head earlier, and flipping the line back would re-open the finding that produced it.

F2 is real and is fixed. Path.exists() resolves the path, so a dangling installed.json symlink read as absent while list_apps still dropped that app for failing to read it. Those two answers together claim there is no such app while the app is on disk, and its carried-forward server then looks unowned. Presence is now judged without resolving: exists() or is_symlink() or is_link_or_junction(), with anything uninspectable counted as present. The junction term is not decoration -- is_symlink is False for a Windows directory junction, so a dangling junction is invisible to every predicate that follows the target, which is the reasoning _absence_is_genuine already records in apps.manager. Mutation proof, reverting to the bare exists(): assert True is False.

F1 asks for the opposite of the previous round's F1.

  • On 585b455ea7, this lane said: "Let a known disabled exact app claim override _vouched; reserve source precedence for ambiguous suffixed-family matches."
  • I implemented exactly that in b618743008.
  • On ba88fe912a, this lane says: "Let a non-gated _vouched exact name outrank app-family attribution."

Those are mutually exclusive orderings of the same two lines. The adjudication records the conflict rather than resolving it: it notes the in-code comment "states plainly that an EXACT app claim is unambiguous and must NOT be rescued by a co-declaring source", says "the finding argues the opposite ordering", and still upholds on the torn tie-break rather than on the merits.

I am not going to alternate that line each round. Implementing F1 re-opens the round-5 finding by construction, and the round after would presumably raise it again, so the loop has no terminating state. Whichever ordering ships needs to be a decision, and I do not get to make it by being the last one to push.

What each ordering costs, so whoever rules has both sides. Exact-claim-wins (current): a disabled app's grant never lingers on a name a reopened gate could hand to a managed server, at the cost that a user server colliding exactly with a disabled app's alias loses its per-tool refs, and the next successful rebuild restores a whole-server grant instead. Vouched-wins: that user server keeps its narrower refs, at the cost that an app aliasing onto a gated managed name keeps an auto-approval while switched off.

Both sit on allowedTools, which never reaches the PreToolUse gate, so both are governance-class. The difference is which one you would rather be wrong about.

Board otherwise. GPT 5.6 Review is the only failure. 549 tests green across test_agent, the dangling-ref suite, test_app_manager and test_app_mcp_scoping; flake8, isort, black, mypy and the comment-history gate clean. This is the seventh consecutive round of findings in this one predicate, all previously fixed forward with mutation proof and none overridden.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Fixed in 20689bf37f, and I owe a correction on my previous comment.

I was wrong to call round 7 a contradiction. Its remedy said "let a non-gated _vouched exact name outrank app-family attribution". I read past non-gated and treated it as a bare reversal of the round before. It is not: that qualifier is exactly what makes the two rounds compatible, and this round's "apply disabled-app precedence only to entries proven app-contributed" says the same thing again. The fault was my reading, not the review.

The mechanism this round named is real, and it decides the question. I checked it rather than taking it on wording. At agent.py:5074-5077 the shared-server sync appends the bare @alias to allowedTools once the command resolves and _may_auto_approve permits it. So pruning a user's @alias/one-tool does not merely narrow that grant: the next successful rebuild hands back @alias, a whole-server grant. Pruning a source-declared name therefore WIDENS the approval this reconcile exists to keep from widening, which is why a readable source has to outrank a switched-off app's exact claim.

_vouched is now split, because its two members vouch for different things.

  • _vouched_sources, the three shared scopes, means "something still declares this name". That outranks an exact app claim.
  • _gated_aliases means only "a shipped server is withheld at this moment". That does not, so an app whose alias lands exactly on a gated managed name still loses its grant, and reopening the gate cannot hand the managed server an approval nobody granted.

A suffixed sibling stays ambiguous under either, so any vouching still outranks the guess there.

Both halves are pinned and mutation-proven, each killing exactly one test. Letting the gate vouch reproduces the round-6 finding: assert '@gated-claimed' not in ['@gated-claimed', '@gated-alone']. Restricting the rescue to suffixed matches reproduces this round's: assert '@shared-name/one-tool' in []. The two tests are the two halves of one distinction, each carrying its own control on the same input -- a name the source declares beside one only the app claimed, and a gated name the app claimed beside a gated name it did not.

550 tests green across test_agent, the dangling-ref suite, test_app_manager and test_app_mcp_scoping. flake8, isort, black, mypy and the comment-history gate clean.

Worth stating plainly, since I had claimed the opposite one head ago: this predicate has taken eight rounds of findings, every one real, and the last two were the same correct point that I mishandled once. I withdraw the loop claim.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Both items fixed in 4a5b6f8369, and one part of the blocking remedy is deliberately not taken in full -- the reason is below rather than left implicit.

The advisory was right and it was my own doing. agent.py:46 already imports the module, and every other use in the file is platform_compat.X. My function-local import was a workaround from a cycle where I could not read the header, not a decision. It is gone.

F1 is the same blindness I fixed one level down. Last head I stopped Path.exists() from resolving the record path, but left _e.is_dir() gating the entry above it. is_dir() resolves too, so an app root replaced by a dangling junction or symlink is not a directory, is not listed by list_apps for exactly that reason, and its record is unreachable -- every resolving predicate agrees the app is absent while something occupies its name. A link-ish or uninspectable root entry now counts as an unread claim on its own.

What I did not take, and why. The remedy says to treat any occupied unlisted entry that is not a directory as unread. That includes an entry which inspects cleanly as a plain file. I declined that half: an ordinary non-app file in the apps root is indistinguishable from an overwritten app root, so counting it would hold ownership permanently incomplete, and incomplete ownership narrows the exemption for every unclaimed name on every rebuild. I could not establish whether stray files normally live in that directory -- the reads I needed were refused repeatedly by the gateway's path resolver -- so I chose the form that cannot misfire in normal operation over the form that closes one more case.

The residue that leaves: an app root overwritten by a plain regular file reads as absent. It is narrower than what this head fixes, and it is stated here rather than discovered later.

Both halves are pinned as a pair on the same shape of input. A dangling vanished symlink beside a plain notes.txt: the first makes the read incomplete, the second must not. Two mutations, each killing exactly one of them -- never counting a non-directory gives assert True is False, always counting one gives assert False is True.

552 tests green across test_agent, the dangling-ref suite, test_app_manager and test_app_mcp_scoping. flake8, isort, black, mypy and the comment-history gate clean.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Round 10: rebased for freshness, and both Design watch items closed

4a5b6f8369 had a clean board: zero failing lanes, PR Readiness success, and both
blocking review lanes reporting no findings. It was still not mergeable-green, for a
reason no lane measures.

The freshness check, which is why this head exists

green_age.py --pr 11989 exited 30: origin/main had gained 5 commits touching 5
files this PR also touches (conftest.py, dashboard/chat_runner.py,
test_crew_log_projection.py, test_memory_multistore_stress.py,
test_work_ledger.py, all classified import). A PR's green is a verdict about
refs/pull/N/merge at trigger time, and nothing re-derives it when the base moves,
so that green was measured against a base its tests never saw.

Rebased onto 7687d304, one commit, no conflicts. The 257 tests in the three
overlapping test files pass against the rebased tree, and green_age.py now reports
FRESH with zero overlap.

Design item 1: the spec, which AGENTS.md requires in the same commit

AGENTS.md line 31 says to update the owning doc "in the same commit when you change
what it documents", and line 50 routes MCP server and tool changes to
docs/architecture/mcp.md. That doc documented rebuild_agent_config()'s merge
order and the mcp_server_withheld audit, but nothing in this PR. So this was a
compliance gap, not a style preference, and the rebase made it free to close.

docs/architecture/mcp.md gains a ### The final ref reconcile section, placed
before the auto-approve pass to match execution order. It states the pass and why it
reconciles the FINAL map rather than each narrowing pass; both exemption sets and
the opposite directions they fail in; the three classes that populate the mount set;
the double ownership read, the tri-state enablement and the alias-family match; and
both audit outcomes. scripts/docs_lint.py passes, which also confirms every
identifier the new text names is live.

Design item 2: verified, and it was right

The claim was that a dropped mount ref leaves nothing at default log level. That
checks out: AgentConfig().log_level defaults to 'WARNING', and cli.py sets the
kiro_crew logger from it, so the logger.info in prune_dangling_tool_refs was
invisible to the operator who has to debug a tool that stopped being offered.

A tools removal now logs at WARNING; a grant-only removal stays at INFO, because
mcp_auto_approve_revoked already puts that decision in the SEL feed and raising it
here too would show one decision twice. The severity tracks the mount list, not
merely whether anything was dropped.

Two tests pin the pair, and the first reads the shipped default instead of spelling
WARNING, so raising that default in future fails the test rather than silently making
the record invisible again. Mutations: always-INFO gives assert 20 >= 30, and
always-WARNING gives assert 30 == 20. mcp_cleanup.py restored to md5
f0e4e3e96242e44f90b74d7420515c83 after each.

554 tests pass across test_agent.py, test_mcp_dangling_tool_refs.py,
test_app_manager.py and test_app_mcp_scoping.py. flake8, isort, mypy, the
comment-history gate (re-run against the new base 7687d304) and docs_lint are
clean. black flags one hunk in purge_deleted_proxy_from_config, which is
pre-existing and outside this diff.

First Principles item 5, declined with the conflict named

The subtraction asks to exempt grants only for vouched or gated names and delete
_app_owned_mcp_keys, _AppOwnership, the start snapshot and the _is_alias_family
hoist. That machinery exists because the blocking GPT lane raised a fenced finding
against every simpler version of it across nine rounds: keying ownership by the raw
composite, then by base alias, then a single-flag completeness read, then branch
order, then the tri-state. Making this subtraction reopens those findings by
construction, so it is a design ruling about what the exemption owes a disabled app's
grant, not a cleanup. Its own stated residual, the app-alias-on-a-gated-managed-name
corner, is the case round 6 was filed about.

Item 8 is the same duplicate-strip finding dispositioned at 5742013857 and sharpened
at 5742199552: purge_deleted_proxy_from_config is a public callable with two unit
tests that run it with no rebuild in the stack, and it strips only bare @name while
the reconcile also handles @name/tool, so the two spellings are not interchangeable.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

The one red on 15e0e0a419 is not from this change set

Backend Tests (Windows) (8) failed on two tests in
test/test_autonudge_provider_trust.py. This diff is five files
(docs/architecture/mcp.md, agent.py, mcp_cleanup.py, test_agent.py,
test_mcp_dangling_tool_refs.py) and does not include that file, nor anything it
imports: autonudge_authz, autonudge_provider_trust, AutoNudgeService,
monitoring.models.

Both failures are one-second threading.Event handshakes losing the race on a runner
where the shard took 854 seconds. test_failed_restart_activation_preserves_a_concurrent_committed_patch
fails at line 819 on assert await asyncio.to_thread(activation_entered.wait, 1), and
test_failed_update_grant_preserves_a_concurrent_committed_patch fails at line 1026
on asyncio.wait_for(..., timeout=1), with the test's own injected
OSError("transient vault failure") escaping as a second symptom. The whole file
passes 26 of 26 on Linux against this tree, and the same shard was green on the
preceding head 4a5b6f8369, whose only difference is the rebase plus three files that
cannot affect thread scheduling in autonudge authorization.

Filed as #12056 rather than folded in here. The failed job is rerunning once, which is
the only round on this sha.

Every other lane on this head is green, including all four review lanes: GPT 5.6,
Opus 4.8, Design and First Principles.

cixuuz
cixuuz previously approved these changes Sep 19, 2026

@cixuuz cixuuz left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thorough fix for a real reported bug (#3310): dangling @ref entries surviving server renames/removals, with a per-tool allowedTools grant leak on the path that never reaches PreToolUse. The two-exemption-set design (mounts fail-open toward keeping refs since dropping is unrecoverable; grants fail-closed toward revoking since a stale grant is the real risk) is sound and consistently applied. Verified RESERVED_TOOL_NAMESPACES exists as referenced. SEL audit added for grant revocation, matching the standing audit-parity convention. Extensive test coverage of the tricky edges (dangling app-root symlink/junction, transiently-unread ownership claims, revocation audit).

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Round 11: rebased onto current main, no code change

The previous head 15e0e0a419 had a fully clean board: 75 pass, 11 skip, zero
failures, PR Readiness success, mergeable: true, all four review lanes with no
blocking findings, and a human approval. I did not claim green on it, because
green_age.py --pr 11989 exited 30: main had gained 30 commits touching 248 files
this PR also touches, including docs/architecture/mcp.md as a same-file
overlap. A pull request's green is a verdict about refs/pull/N/merge at the
moment each run fired, and nothing re-derives it when the base moves, so that
board was measured against a base its tests never saw.

Rebased onto 1c7f9637, one commit, no conflicts. green_age.py now reports
FRESH with zero overlap. The commit content is unchanged from the approved
revision.

The same-file overlap is genuinely disjoint from my section. Main's change to
docs/architecture/mcp.md is bc0d2b0cfc (refactor(memory): simplify member memory to one SQLite store), which rewrites the member-memory and session-proof
passages at four places. My ### The final ref reconcile section is untouched by
it, and the two texts describe different subsystems.

Scoped tests on the rebased tree: 554 pass. test_agent.py 277,
test_app_manager.py plus test_app_mcp_scoping.py 257, and
test_mcp_dangling_tool_refs.py 20, all with -n0.

Four gates clean, two locally red and both main-owned. flake8, isort,
scripts/docs_lint.py and scripts/check_comment_history.py all pass, the last
re-scoped to the new base so it measures my commit rather than main's. The two
reds reproduce byte-identically on a pristine origin/main worktree at
1c7f963706:

  • mypy reports the same 7 errors in the same 3 files, none of them mine:
    transcribe.py boto3 stub drift, plus context.py and dashboard/state.py
    referring to require_private_memory_execution, private_runtime_log_dir,
    member_essential_context.member_for_store and
    ContextBuilder.live_memory_mode_for_session. Those last four are fallout from
    the same member-memory refactor above, so main is mid-rename.
  • black --check wants the same single hunk in src/kiro_crew/mcp_cleanup.py,
    which is outside my diff and present on main without my commit.

Cost this round, stated rather than buried. The force-push dismisses the
approval recorded on the previous head. That is the unavoidable price of a
measured-fresh green, and re-approval is recoverable where a stale green claim is
not. Nothing else about the revision changed, so the approved content and this
content are the same bytes.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Board on 05e419d772: 24 red lanes, all main-owned, plus one review finding that needs a ruling

The 24 failures are main's, not this branch's

Every Backend Tests shard on 3.12 and Windows, E2E, E2E Gateway Boot,
Real Adapter Contract Tests, Windows Fail-Closed Sandbox Contract, and the
Coverage Gate / PR Readiness aggregates downstream of them. One shard's
annotations give the mechanism and 141 failures on that shard alone:

ImportError: cannot import name 'member_for_store' from 'kiro_crew.member_essential_context'
ImportError: cannot import name 'private_runtime_log_dir' from 'kiro_crew.config.paths'

Both are already tracked: #12082 (main fails collection, every shard on every PR)
and #12083 (context.py imports require_private_memory_execution, which
member_memory_auth does not define). Both of the symbols above appear in
#12082's comments, so the main-side fix is already scoped to the whole family and
this PR adds nothing by filing a third issue.

I predicted this before CI reported it, from the pristine origin/main A/B in my
previous comment: mypy on an untouched origin/main worktree at 1c7f963706
already named member_for_store, private_runtime_log_dir,
require_private_memory_execution and live_memory_mode_for_session as
references to symbols that no longer exist.

The uncomfortable part is worth stating plainly. The previous head was green
because its base predated this break. The rebase that made green_age.py report
FRESH is what pulled the break into this PR's merge ref. A fresh base and a
working base are, right now, not the same base, and no action on this branch can
reconcile them.

A correction to my previous comment

I wrote that the force-push "dismisses the approval recorded on the previous
head". It did not. reviewDecision still reads APPROVED on 05e419d772, so this
repository does not have dismiss-stale-approvals enabled and cixuuz's approval
carried across the force-push. The claim was wrong when I made it, and a wrong
statement about whether a human's approval still stands is worth correcting
rather than leaving in the record.

GPT's new finding is real, and its remedy collides with a green test

GPT 5.6 Review blocks 05e419d772 on agent.py:5450, the elif arm that
handles a candidate no app claims:

elif _n in _vouched or _ownership_fully_read:
    _exempt_mounts.add(_n)
    _exempt_grants.add(_n)

The finding is sound on its own terms. _ownership_fully_read answers whether a
disabled app could be hiding behind an unclaimed name; it does not answer whether
anything still declares that name. Using it to exempt a GRANT conflates the two,
and the comment eight lines above states the rule it breaks: _exempt_grants
requires a positive answer, because a grant kept on doubt leaves an auto-approval
on a name any later server inherits, and allowedTools never reaches the
PreToolUse gate.

Its remedy is "exempt unresolved grants only when a readable source still
declares the server". Applied here, that makes
test_a_declared_command_that_did_not_resolve_keeps_its_refs fail on its last
line. That test is green today, its docstring states a deliberate contract, and
its subject is a server declared only in the carried-over agent config whose
command is merely not installed yet:

assert "@notinstalled" in config["allowedTools"]

So the two positions are: a not-yet-installed command keeps its per-tool grant
across the gap, which is what ships and what that test pins; or it loses the
grant and keeps only the mount, which is what GPT asks for, at the cost of a
re-approval each time a binary is temporarily absent. I am not editing a guard
test to make a reviewer's remedy fit, so this is a ruling rather than a fix.

Two further facts bear on the ruling. This predicate was byte-identical on the
previous head 15e0e0a419, where the same lane reported no blocking findings, so
this is a fresh sample of an unchanged surface rather than a regression. And the
hazard is weaker than the app case the PR was filed for: the declaration and its
command string both survive in the carried-over config, so a different server
inherits the grant only if someone rewrites that entry, where a switched-off
app's declaration disappears on its own.

Opus 4.8, Design, First Principles, UX and Security Scope all pass on
this head. Nothing is pending. The only two things standing are main's break and
the ruling above.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Round 12: the maintainer ruled for GPT's finding, and it is implemented

The decision on agent.py's unclaimed-candidate branch: a server whose command
did not resolve keeps its MOUNT and loses its GRANT. A temporarily absent binary
does not hold an allowedTools auto-approval, and a human can grant it again.

The change is one condition

_exempt_grants is now gated on _n in _vouched; _exempt_mounts keeps the
condition it had. That removes exactly the arm the finding named. Having read
every app claim answers whether a disabled app could be hiding behind an
unclaimed name; it says nothing about whether any source still declares that
name, and the grant side was using it to answer the second question. The comment
a few lines above already stated the rule: the grant needs a positive answer,
because a grant kept on doubt leaves an auto-approval on a name whatever binds to
it next inherits, and allowedTools never reaches the PreToolUse gate.

My first cut followed the remedy's literal wording and was wrong

I gated the grant on _vouched_sources, which also stops the managed gate from
vouching. That broke five tests rather than four, including the gated-alone
control in test_a_closed_gate_does_not_vouch_for_a_disabled_app_claim. The gate
must still vouch in this branch: the app branch refuses gate-vouching because
there the grant belongs to a switched-off app, so reopening the gate would hand
the managed server an approval nobody granted it, while here the grant is the
withheld server's own and revoking it strands a shipped default. _n in _vouched
removes the arm the finding named and leaves that control green.

Four tests carry the contract, three of them controls in tests about other things

test_a_declared_command_that_did_not_resolve_keeps_its_refs is now
..._keeps_its_mount_not_its_grant, asserting both halves on one input so the
pass reads as the two lists diverging rather than as a blanket keep or removal.
The npm:foo, solo and playwright-mcpx controls are each agent-config-only
servers with an unresolved command, so each keeps its original purpose with the
discrimination measured on tools, and each also pins its grant's absence.
test_a_colon_keyed_server_no_app_owns_keeps_its_refs was renamed to
..._keeps_its_mount so its name matches what it asserts.

Both halves are mutation-pinned

Making the grant unconditional again gives four failures of the form
assert '@notinstalled' not in ['@notinstalled']. Narrowing the mount to the same
bar gives four failures of the form
assert '@npm:foo' in ['fs_read', 'tool_search'], the tools list stripped to
builtins. Each mutation kills a different half of the same four tests, and
agent.py was restored to md5 40dc4bed580eb168a275fe33c9df096f after each.

Verification on the rebased tree

554 tests pass across test_agent.py, test_mcp_dangling_tool_refs.py,
test_app_manager.py and test_app_mcp_scoping.py, all with -n0. flake8,
isort, black --check, scripts/docs_lint.py and
scripts/check_comment_history.py are clean, the last re-scoped to the new base.

The comment gate earned its place this round: it caught two phrases I had written
that narrate the change's own history rather than stating behaviour, one in a
docstring and one in a control's comment. Both are rewritten in present tense.

Base

Rebased onto 891e6de8, which carries #12088's fix for the main-wide
ImportError that reddened 24 lanes on the previous head. green_age.py --pr 11989 reports FRESH with zero overlap. One commit, and one push.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Round 13: both reviewers found the mirror of the last fix, independently, and they were right

GPT 5.6 and Opus 4.8 each blocked f4577b61c0 on the same line with the same
remedy, arrived at separately. The previous round narrowed the GRANT in the
unclaimed-candidate branch and left the MOUNT gated on the same completeness flag,
which is the half that cannot be undone.

The defect

elif _n in _vouched or _ownership_fully_read: guarded the whole branch. A
server no app claims and no source declares, whose command did not resolve this
pass, therefore reached NEITHER exempt set whenever an unrelated app's manifest,
record or enablement failed to read. _app_owned_mcp_keys' own docstring calls
those "the ORDINARY shapes of the failure rather than exotic ones". The tools
refs were then pruned, and nothing re-adds them: not a later pass, not a source,
not the binary returning to PATH. A user's own stdio server silently stops being
offered because a different app's metadata was unreadable once.

I verified the chain before acting rather than taking two reviewers' word:
_ownership_fully_read at the old line 5387 is the AND of both snapshots,
_narrowed_away at 5020 is exactly the set of servers whose command failed to
resolve, and the elif was the only thing between them and
prune_dangling_tool_refs.

The fix is the ruling applied to the other list

The branch is now an unconditional else: the mount is exempt for every
unclaimed candidate, and the grant keeps its _n in _vouched gate. That matches
the sibling if _bases: branch, which already keeps a mount on this exact doubt
via _base_may_still_mount, and it matches what the maintainer ruled last round:
the mount survives the doubt, the grant does not.

_ownership_fully_read then had no reader left, so it is gone. One flag fewer,
and the composition it encoded is no longer needed: the concern it was added for
was a switched-off app's grant outliving it, and the vouched-only grant rule
answers that without consulting read completeness at all.

Four existing tests changed on the mount half only

test_an_unreadable_app_claim_does_not_read_as_unowned,
test_an_app_record_list_apps_skipped_is_not_read_as_absent,
test_a_claim_unread_at_the_start_is_not_rescued_by_a_whole_final_read and
test_an_unreadable_manifest_narrows_even_for_an_enabled_app each asserted both
lists pruned. They were written before the two lists took separate exemption sets,
so the mount assertion is incidental over-pinning while the grant assertion is the
one carrying each test's security purpose. Every grant assertion is untouched.

A new test, test_one_apps_read_failure_does_not_unmount_an_unrelated_server,
pins the dimension those four do not isolate: the app whose read fails is
unrelated to the harmed server. nosuch is its other half, a ref whose server is
absent from the config entirely rather than merely unresolved, so a reader that
keeps everything fails there.

Both halves pinned, and each mutation hits only its own half

Re-gating the mount on the completeness flag kills five mount assertions,
including the new test's assert '@mine' in ['fs_read', 'tool_search'] with the
user's server stripped to builtins, and leaves every grant assertion passing.
Making the grant unconditional kills nine grant assertions and leaves every mount
assertion passing. agent.py restored to md5
5dbf85a1a748b344ff2f4629be7404d6 after each.

Verification

555 tests pass across the four suites, all -n0. flake8, isort,
black --check, scripts/docs_lint.py and scripts/check_comment_history.py
clean.

docs/architecture/mcp.md moved with the code, as AGENTS.md requires: its
sentence "Both reads must therefore have seen every claim before an unclaimed name
loses its grant" described the deleted flag and was false after this change. It
now states that an unclaimed name keeps its mount unconditionally and its grant
only while a readable source declares the name.

Base

push_guard refused the first attempt because main advanced mid-round; rebased
onto 179c3187, re-ran the scoped suites and the comment gate against that base,
and push_guard then reported SAFE. green_age.py --pr 11989 reports FRESH. One
commit.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Round 14: the same asymmetry, one branch over

GPT 5.6 blocked 4215665644 on agent.py:5421, the alias-family match in the
app branch. The grant was exempted on family membership alone, so an ENABLED app
owning playwright-mcp lent its answer to an unresolved playwright-mcp-2 that
it may never have declared, and whatever binds to that name next inherits the
auto-approval.

Why this is new rather than a re-litigation

Rounds 2 and 3 were about a base whose app is switched OFF: round 2 added the
family match so a disabled app's grant could not outlive it, round 3 stopped that
match from deleting an independently-named sibling's refs. This round is the
enabled case, which neither touched: family membership was being read as positive
evidence for a grant when the suffix's origin is, by this code's own admission,
unrecoverable.

It is also the rule the maintainer already set, applied one branch over. The
unclaimed branch was fixed in rounds 12 and 13 to keep the mount on doubt and
require positive evidence for the grant. The app branch still used one answer for
both.

The change

_exempt_grants now additionally requires _n in _ever_app_owned, so the candidate
must be a claimed name itself, not merely a family match. _exempt_mounts keeps
the family answer, because being wrong there costs one mount attempt against an
empty name while dropping a mount cannot be undone.

Exactness only ever narrows the grant, so round 2's case is unaffected: a family
sibling whose base is switched off still loses its grant, and now loses it whether
the base is on or off.

No existing test covered this, which is why it survived

All 278 tests passed with the fix applied and nothing changed, so the enabled-base
path had no coverage at all. test_an_enabled_base_does_not_lend_its_grant_to_a_suffixed_sibling
pins it, with the claimed base itself as the other half on the same input: the base
keeps both refs while its app is on, the sibling keeps the mount and loses the
grant.

Both directions are mutation-pinned against that one test. Dropping the exactness
requirement gives assert '@playwright-mcp-2' not in ['@playwright-mcp', '@playwright-mcp-2'],
the finding reproduced. Requiring exactness for the mount too gives
assert '@playwright-mcp-2' in ['fs_read', '@playwright-mcp', ...], the mount
stripped. agent.py restored to md5 0fe4269d61e00ec5867fb8169bae9149 after each.

Verification

556 tests pass across the four suites, all -n0. flake8, isort,
black --check, scripts/docs_lint.py and scripts/check_comment_history.py
clean. The spec needed no change: it already says a name this rebuild is unsure
about is exempted as a mount and not as a grant, which is what this makes true of
the family match too.

push_guard refused once on main drift, as it did last round; rebased onto
080c481f, re-ran the suites and the comment gate there, push_guard then SAFE.
green_age.py --pr 11989 reports FRESH. One commit.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Round 15: the finding is real, and its cited line was the wrong location

GPT 5.6 blocked 02f5c5b9ca on mcp_cleanup.py:290, claiming a disabled
server's per-tool grant survives. Opus 4.8 could not adjudicate it: it could not
confirm from that file whether a disabled entry persists in the final map. That is
checkable, so I checked, and both of my own assumptions were wrong before either
of GPT's claims was.

Two wrong guesses, each disproved by measurement

First I assumed a disabled server is dropped from the final mcpServers map,
which would have made the finding a false positive. The test's opening assertion
disproved it: config["mcpServers"]["notion"] is present carrying
disabled: True. The entry stays so kiro-cli knows not to mount it.

Second I excluded disabled entries from the grant half of
prune_dangling_tool_refs, which is GPT's stated remedy. The test failed
identically. Calling that function directly settled why: given
{"notion": {"disabled": True}} it drops NOTHING, on either list, because the
name is a map key. It is not the deciding pass, so I reverted that change rather
than leave surface that does not do what its comment claims.

The real location

agent.py, the shared-server disable in the rebuild:

ref = f"@{alias}"
if spec.get("disabled") or alias in _disabled_anywhere:
    for key in ("tools", "allowedTools"):
        lst = config.get(key)
        if lst is not None and ref in lst:
            lst.remove(ref)

It removes the exact @alias and nothing else, so @alias/tool survives a
disable on both lists. Measured end to end: tools loses every @notion ref,
allowedTools loses the bare @notion, and @notion/search stays. GPT's harm
statement was right in every respect except the file.

The comment four lines above this block already rules the behaviour out: "under-
matching would let an operator's disable be missed on the one path
(allowedTools) that never reaches the PreToolUse gate. Denying is allowed to be
loose; granting is not." This under-matched by exactly one spelling.

It is also the live consequence of something First Principles raised several
rounds ago, which I confirmed at mcp_cleanup.py:317-323 and recorded as
pre-existing and advisory: the purge strips @{name} and never @{name}/tool.
Treating it as advisory was the wrong call.

The fix

The disable now removes every ref the alias owns, matched on the @alias/ prefix
rather than by splitting the ref, so it adds no second spelling of the ref
grammar. The list is rebuilt rather than remove()d, because list.remove drops
only the first occurrence and a duplicated ref would otherwise survive.

Tests

test_a_disabled_server_loses_its_per_tool_grant_not_only_its_mount was written
as a RED reproduction before any fix, and it asserts the real premise rather than
my wrong one: the entry stays in the map with its flag, and both lists lose both
spellings. An enabled keep server with the same two spellings is its other half,
so a reader that strips everything fails on it.

Mutation: neutralising the per-tool arm reproduces the original failure exactly,
assert not ['@notion/search']. agent.py restored to md5
89b4c69323e464bf2a2208179fb6a139 afterwards.

557 tests pass across the four suites, all -n0. flake8, isort,
black --check, scripts/docs_lint.py and scripts/check_comment_history.py
clean.

Base

push_guard refused once on main drift; rebased onto abedd2ed, re-ran the
suites and the comment gate there, push_guard then SAFE. green_age.py --pr 11989
reports FRESH. One commit.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Split: this PR now keeps only the ref-prune and the grant rule

The maintainer ruled to split rather than keep fixing round by round. This PR
retains the part that has stabilised: one prune_dangling_tool_refs pass over the
final server map, with two exemption sets so the mount survives doubt and the
grant requires positive evidence, plus the app-ownership reads that feed it.

Everything else moves to #12149, with public reproductions and test boundaries.

Removed from this PR

  • The shared-server disable fix from an earlier round, which made a disable remove
    every ref the alias owns rather than only the bare @alias, and its test.
  • The key-normalization rewrite fix, which carried the @oldkey/tool spelling
    across a rename, and its test. Written and verified this round, never pushed.
  • Two findings raised against the previous head: the mount side of the app-family
    attribution, and the normalization rewrite above.

A correction to two earlier comments

My round-15 and round-16 comments describe the disable-path per-tool fix as landed
in this PR. That is no longer true: it is removed here and tracked in #12149
instead. Those comments are accurate about the defect and about how it was found;
they are wrong about where the fix now lives.

Why split rather than continue

The previous head had every review lane clean, GPT included, for the first time on
this predicate. The only change since was renaming a local variable, and two new
blocking findings then appeared against byte-identical logic. Every finding across
these rounds has been real, which is why they kept getting fixed, but a clean
verdict on this surface is a sample rather than proof of absence, so each push
re-rolls and can surface more. The last two were also in adjacent passes rather
than in the reconcile this PR was opened for: one in key normalization, one in
mount-side policy that had already moved three times.

Splitting gives those their own review budget and lets the settled part land.

State

556 tests pass across the four affected suites. flake8, isort,
black --check, scripts/docs_lint.py and scripts/check_comment_history.py
clean, and mypy over the package reports nothing in the changed file. The spec
section needed no edit: it never documented the removed behaviour, which
docs_lint confirms independently.

kiro-cli mounts what mcpServers declares, so a @ref naming a server absent
from that map mounts nothing. Several rebuild passes narrow the map without
touching the ref lists: the resolution pass replaces mcpServers wholesale and
drops unresolvable servers by omission, and the locked app re-merge deletes
app entries whose app is not confirmed enabled. The refs those passes leave
behind are probed on every discovery cycle, and an allowedTools ref is worse
than cosmetic -- that list never reaches the PreToolUse gate, so the grant
sits on the name and a server added under it inherits an auto-approval nobody
granted for it.

prune_dangling_tool_refs runs once over the FINAL map, inside the write
funnel, so it covers every narrowing pass including one added later.

WHAT IS EXEMPT, and why each exemption is narrow:

A reserved kiro namespace is not a server ref at all. RESERVED_TOOL_NAMESPACES
is imported from the module documented as the ONE reader of the tools ref
vocabulary, so the two cannot drift. @Builtin is listed by kiro's own
configuration reference, never appears in mcpServers, and carries the whole
built-in tool surface plus the tool_search loader.

A server whose DECLARED COMMAND did not resolve on this pass keeps its refs,
because the next rebuild reverses that absence once the binary is installed
and an existing config never re-adds a template ref. The set is collected in
the one branch that means it rather than inferred from "declared but missing
from the final map": a commandless stub, a spec that is not a dict, and a
server the locked app re-merge deletes are real absences no later pass
reverses, and inferring would retain exactly the refs this exists to drop.

That exemption ends for a name an app owns unless the app is positively
enabled, since otherwise nothing re-adds the entry and the grant is left
sitting on the name. Ownership is read from the app manifests that MINT these
keys, never inferred from the name: mcp_server_alias returns a slash-free name
unchanged, so a global mcp.json server keyed `npm:foo` reaches the config with
its colon intact, and an installed app called `npm` that declares only `bar`
does not own it. The enumeration covers DISABLED apps deliberately, because "an
app owns this name and is switched off" is the whole case and it is invisible to
a collection that stops at enabled apps. Ownership is read twice, once before
this rebuild's work and once at the reconcile, and a key EITHER read claims
needs a positive enablement answer: an app uninstalled mid-rebuild has left both
the listing and its manifest, so a late read alone cannot tell "its app is gone"
from "no app ever owned this", and the second of those is the permissive answer.

A gated-off shipped server keeps its refs while its entry is withheld, by the
decision the withhold audit records.

Dropping a ref out of allowedTools REVOKES an auto-approval, which is a
permission decision, so it emits mcp_auto_approve_revoked into the same SEL
feed as the withhold in the same pass instead of only an INFO log. Auditing
never fails the rebuild.

The server-name split reuses the spelling agent_capabilities._materialize and
apps.bridges already use, so the per-tool form (@server/tool, @server/*)
resolves to the same server in all three.

Fails safe: a non-dict mcpServers yields no readable verdict and drops
nothing; non-string and sigil-less entries are left to the passes that own
them. An unreadable app registry or manifest claims no ownership, the same
answer as "no app owns this name", because the app path then contributed
nothing to this rebuild either and destroying an ordinary server's
unrecoverable grant is the worse of the two failures.

The install harness stubs command resolution by echoing every command, which
makes the unresolved-command branch unreachable, so _run_install takes an
optional resolver override. Existing callers are unchanged.

One existing fixture declared no server beside an MCP ref it asserts is kept,
which is the dangling state itself; it now declares that server so its
assertions rest on tool_search seeding rather than on the unreconciled state.

Closes #11980
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Round 18 on 61c35de68d. On the previous head e300ae8d01, GPT 5.6 Review was the only blocking lane.

The finding, and why it is in scope. The cited code is the app-family branch this PR added in round 14. When a candidate is itself a claimed alias whose own app is switched ON, the all(...) over the whole alias family still let a sibling's switched-OFF owner decide, and because that AND gates both lists, the exactly-owned server lost its mount refs and its grant together. That is a defect in this PR's own new code rather than one of the four items moved to #12149, so it is fixed here.

The fix. The deciding set is the candidate itself when the candidate is exactly claimed, and the alias family only when nothing claims it exactly. Family matching exists for a name with no claim of its own, where the suffix is the only evidence available; where an exact claim exists, that claim answers. Mount and grant both read the narrowed set, because the harm ran through both.

Test and mutation evidence. test_an_exactly_owned_alias_is_decided_by_its_own_owner_not_a_sibling: one app ON declaring x-y-2 literally, one app OFF declaring @x/y, which aliases to x-y. x-y is the other half on the same input, so the test reads as a discrimination rather than a blanket keep: its own app is off, so it loses its grant, which is what the family rule was added for.

Both halves are pinned independently:

  • widening the mount half back to the family gives assert '@x-y-2' in ['fs_read', 'tool_search'], the server stripped to builtins
  • widening the grant half back to the family gives assert '@x-y-2' in [], the grant list emptied

Each mutation kills only its own assertions. agent.py verified back at md5 4f8cf066ef3f724e4c576615a13eb19e after each, restored from a file copy rather than from git, so the uncommitted work was never at risk.

The fixture needed two attempts, which is worth recording. mcp_server_alias() leaves a slash-free name unchanged, so a bare app-manifest key keeps its app: prefix and never produces the collision under test; @x/y-2 is the spelling that aliases to x-y-2. The first fixture asserted against a name no code path can mint.

Verification. 557 tests green: 280 in test_agent.py, 277 across test_mcp_dangling_tool_refs.py, test_app_manager.py and test_app_mcp_scoping.py. flake8, isort, black --check and docs_lint clean. The comment-history gate passes diff-scoped against this round's own delta, which is the only mode in which it enforces anything. mypy over src/kiro_crew reports zero errors in the changed file.

The spec moved with the code. docs/architecture/mcp.md said a base-2 sibling "has to inherit its base's answer", which this change makes false. It now states that family matching applies to a name no source claims exactly, and that a name claimed exactly answers to its own claimant on both lists.

No rebase was needed this round: origin/main had not moved since the previous round's rebase, so push_guard reported SAFE with merge-base equal to origin/main at e8b94aaef7f3. One push, carrying a literal lease naming e300ae8d01, which was accepted. green_age reports FRESH.

Scope is unchanged: a finding naming key normalization, the shared-server disable pass, the deleted-proxy purge, or app-family mount policy belongs to #12149.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Design Review's CONCERNS on 61c35de68d is advisory, and it is dispositioned rather than fixed here.

The watch item is correct. _app_owned_mcp_keys reconstructs the skip rules apps.manager.list_apps owns so it can tell a failed ownership read from a genuine absence, and that mirror can go stale with nothing failing in the apps-manager suite. It fails on the unrecoverable side: a completeness flag that wrongly reads fully-read prunes a mount ref that the next rebuild never re-adds. Its own clearing condition names a fast follow as acceptable, because the tests here pin the current behaviour, so it is filed as #12169 with the test boundary, including a mutation check that the moved read is load-bearing rather than decorative.

Board on this head: 77 lanes success, 11 skipped, zero failing-class conclusions after deduplicating to the newest attempt per lane, and mergeable true. GPT 5.6 Review and Opus 4.8 Review both report no blocking findings with their verdict markers naming this exact commit, First Principles Review is PASS, and UX Review and Security Scope Review are success. The GPT run's own step list shows both the discovery and falsification passes executed and the adjudication steps skipped for want of a blocking finding, so this is a real verdict rather than a deferred pass.

The one thing outstanding is the PR Readiness status, which still reads 1 readiness check(s) still pending; waiting on CI (in_progress). That was computed at 03:14Z while CI was in flight. CI concluded success on this head at 03:34:37Z, no run on this head is in flight now, and no readiness recompute or sweep has run since, so that status is a stale reading rather than an outstanding check. The sweep is alive, so it is left to republish on its own rather than anything being re-dispatched.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Review-ready on 61c35de68d, verified at 2026-09-20T04:01:42Z

Every automated criterion holds, measured at that instant on that exact head:

  • 88 check-runs deduplicated to the newest attempt per lane: 77 success, 11 skipped, zero failing-class conclusions and zero pending.
  • PR Readiness status success, reading Eligible automated validation passed for this revision. It had been frozen on a 03:14Z reading taken while CI was still in flight, and republished on its own once a recompute ran; nothing was re-dispatched to clear it.
  • mergeable true.
  • Zero BLOCK-MERGE markers anywhere on the PR. All four verdict markers name this exact commit: GPT, Opus, Design and First Principles.
  • Freshness: base moved one commit with no overlap in anything this PR touches.

The 11 skipped lanes are the ones this diff cannot reach: the frontend lint, test and coverage-merge lanes, the bundle-size gate, the lockfile floor, Linux packaging, macOS tests, the two fork guards and the two conditional security-scope stages. This change is Python and one doc.

Review verdicts on this head: GPT 5.6 Review and Opus 4.8 Review report no blocking findings, First Principles Review is PASS, UX Review and Security Scope Review are success, and Design Review is an advisory CONCERNS whose single watch item is dispositioned above and filed as #12169.

What remains is the required human review, which is not mine to satisfy: mergeable_state is blocked on that alone, with one reviewer requested. Not merged, not approved.

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.

Rendered agent config never prunes an mcpServers entry no source declares: renames leave orphans that are probed every cycle

3 participants