Repository navigation
fix(doctor): explain how Pi sessions receive MCP servers - #36476
Conversation
0b07b44 to
b9d0502
Compare
b9d0502 to
1d7ff21
Compare
UX Review (Opus 5.5, fork) — ⏭️ skippedRevision |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level blockers: the Pi branch is a positive identity check, and it only replaces the no-mirror row Pi already hit. Notes
[DESIGN-REVIEWED] 1d7ff21 Description read[DESCRIPTION-READ] ea8b9e0edb779edf3b0ca08901025dde104e21e00f25ae05ca80a222e7f99794 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 |
First Principles Review (Opus 5.5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The change is a single Pi wording branch in an advisory doctor row. The only point to watch is that this prose restates a mechanism the registry already describes. Notes
What this change shipsInventory (2 items) — 1 justifiedIntent: a Pi user running
[FIRST-PRINCIPLES-REVIEWED] 1d7ff21 Description read[DESCRIPTION-READ] b4de120afedfb7f8d9142b5828318163200d3a9536e0d1c083f5fdf77589b336 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Code change approver recommendation: A person should decideWhy: the decider raised 2 possible problems and estimates a 50% chance that this change introduces a defect; a person should check them. The new Pi doctor row prints no ⏹ glyph, although the PR description says it does and every sibling row has one. Its mcp.json sentence presents a same-named Pi mcp.json server as a possible delivery route, but the gate extension and registry show that in crewmate DMs it causes Crew's tools to be refused. That hides a withholding cause the issue asks doctor to name. The owning spec doc was also not updated, which is a note rather than a blocker. Things to check (possible problems the decider raised; at this confidence many turn out to be fine):
Tier: 2, held for a person: the automated review did not clear it. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approving. On this head the review checked the new Pi wording against the delivery code. Spec servers mount only on crewmate DM sessions, Crew-owned Connections reach every Pi session, and a server with a switched-off tool is withheld whole. The authored-agent row stays silent on Pi, so the two rows cannot contradict each other. Only printed text changes. No delivery path, gate or exit code changes, and refs still go through _safe_display. The new test fails when the Pi branch is reverted, and the merge with current main is textually clean.
Done well: the branch uses a positive backend == ACP_BACKEND_PI identity check, and the PR says "Part of #35753" because the projection half stays open.
Optional:
- After #38843 every sibling
mcp tool refsrow starts with a status word. Printingmcp tool refs: Note: {label} needs a live session to check: {refs}indoctor_checks/mcp.pywould keep the columns aligned and match the body's "advisory" claim. Asserting that prefix in the test, plus"has no mirror" not in out, would also pin that the Pi row replaces the generic row. - "Pi may load the same name from its own mcp.json" can read as a second way to deliver the server. The gate extension marks that name shadowed and refuses its tools. A wording like "A same-named server in Pi's own mcp.json outranks Crew's, and its tools are then refused; rename one of them" states the outcome.
docs/system-specs/modules/agent-host-contract.mdaround line 237 still says a no-mirror backend lists refs as unprojected. One clause there for the Pi row would keep the spec current.
Problem / Motivation
Goal: A Pi user running
kirocrew doctorlearns which Pi sessions receive spec-declared MCP servers, instead of a generic "has no mirror" line.On
agent.acp_backend = "pi", doctor's default-spec check printspi has no mirror; unprojected: '@<server>', ...for every referenced server. That wording was written for harnesses that receive no spec servers at all. Since #30188, Pi does receive them, but only in crewmate DM sessions. Other Pi sessions can still get pooled broker stubs and Crew-owned Connections, and Pi can load a server of the same name from its ownmcp.json. The static check cannot see which of those routes a live session used, so its verdict reads as "nothing reaches Pi". The reporter's own observation was the opposite: stub-wrapped servers and their ownmcp.jsonservers did reach the session.The issue asks for exactly this as one acceptable outcome: "Expected: every server an agent spec declares and references reaches a Pi session, the way #30188 describes, or doctor names why one is withheld."
Why it matters
A user chasing a missing tool on Pi gets a diagnosis that points nowhere: "no mirror" suggests that Pi never receives spec servers. The real question is which session type they are in, whether a switched-off tool withheld the whole server, and whether Pi's own
mcp.jsonsupplies the name. Without that, the user cannot tell a by-design scope from a regression, which is the very question #35753 raises.Not a goal
mcp_ref_guardwarning, which already inspects an actual session's projection.What changed (motivation → approach → change)
Symptom: for Pi, doctor printed the generic
has no mirror; unprojected:line.Cause:
_doctor_unresolved_mcp_refstreats Pi like every mirror-less backend. A check that reads only the default spec cannot know which delivery routes a Pi session has.Change: in
src/kiro_crew/doctor_checks/mcp.py, a Pi backend now gets⏹ pi needs a live session to check: <refs>, followed by a wrapped explanation:mcp.json.The refs are still listed through
_safe_display, and the row stays advisory (⏹, not ⚠). Other backends take the existing path unchanged.Backwards compatibility
Compatible: doctor still lists every unresolved ref and the check stays advisory. Only the Pi wording changes.
Removes nothing: no path, record, key or function is removed. The same refs remain visible, now with a Pi-specific explanation.
Tests
test/test_cli_doctor.py::TestUnresolvedMcpRefs::test_pi_explains_which_sessions_get_spec_mcp_servers: a Pi default spec with an unresolved@reviewref prints the "needs a live session to check" verdict and names each delivery route.Proof: PROVEN test/test_cli_doctor.py::TestUnresolvedMcpRefs::test_pi_explains_which_sessions_get_spec_mcp_servers (head 0b07b44)
0b07b4456e75, Windows Python 3.13, these doctor suites ran:test_cli_doctor.py,test_cli_doctor_refactor_facade.py,test_cli_doctor_refactor_report.py,test_doctor_authored_agent_mcp_refs.pyandtest_doctor_mcp_share_refused.py. Result: 538 passed, 49 skipped, 1 failed.test_every_name_the_module_held_still_resolves[Path]('pathlib._local' == 'pathlib'). It fails identically on the parent00c5418f06without this change. It is a Python 3.13pathliblayout difference, not this diff.doctor_checks/mcp.py. Semgrep 1.78.0 found zero findings on the same diff before the rebase.Manual verification
N/A — unit coverage sufficient: the change is one printed doctor row, and the test drives
_doctor_unresolved_mcp_refsand asserts on the exact text a Pi user sees.Related Issues
Part of #35753 (the "doctor names why one is withheld" half; projection beyond crewmate DMs is not changed). Follows #30188.
Sibling sweep
Swept: git grep -nE "has no mirror|unprojected" -- src/kiro_crew/doctor_checks
Siblings: none -- the default-spec doctor check is the only place that prints this static verdict; the runtime mcp_ref_guard warning inspects a live session's projection and is accurate as is.
Pattern harvest
Not generalizable: the wording depends on Pi's session-type-specific delivery routes added by #30188, which no other backend shares.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
🤖 Generated with Claude Code