Skip to content

fix(doctor): explain how Pi sessions receive MCP servers - #36476

Merged
KiroCrewCaptain merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/35753-pi-mcp-doctor
Nov 18, 2026
Merged

KiroCrewCaptain merged 1 commit into
kirodotdev:mainfrom
leonlaiyc:fix/35753-pi-mcp-doctor

Conversation

@leonlaiyc

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A Pi user running kirocrew doctor learns 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 prints pi 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 own mcp.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 own mcp.json servers 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.json supplies 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

What changed (motivation → approach → change)

  • Symptom: for Pi, doctor printed the generic has no mirror; unprojected: line.

  • Cause: _doctor_unresolved_mcp_refs treats 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:

    • only crewmate DMs mount spec-declared servers directly;
    • other Pi sessions can receive pooled broker stubs and Crew-owned Connections;
    • a switched-off tool can withhold its whole server from Crew's handoff;
    • Pi may load the same name from its own 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 @review ref 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)

  • On head 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.py and test_doctor_mcp_share_refused.py. Result: 538 passed, 49 skipped, 1 failed.
    • The failure is test_every_name_the_module_held_still_resolves[Path] ('pathlib._local' == 'pathlib'). It fails identically on the parent 00c5418f06 without this change. It is a Python 3.13 pathlib layout difference, not this diff.
  • On the pre-rebase head, Windows Python 3.12: 242 passed for doctor, authored-agent MCP diagnostics and the flake-pattern ratchet. The new test also passed 20 serial repeats, 10 parallel repeats and a reordered run.
  • black, isort and flake8 are clean on both files, and mypy is clean on 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_refs and 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • 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

Contribution License Agreement

🤖 Generated with Claude Code

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Nov 13, 2026
@iamwhatever
iamwhatever force-pushed the fix/35753-pi-mcp-doctor branch from 0b07b44 to b9d0502 Compare November 18, 2026 08:29
@iamwhatever
iamwhatever force-pushed the fix/35753-pi-mcp-doctor branch from b9d0502 to 1d7ff21 Compare November 18, 2026 08:43
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 1d7ff21ad414c8e5310bbf3cc01faffa8c901660 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 1d7ff21ad414c8e5310bbf3cc01faffa8c901660 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 1d7ff21

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 1d7ff21ad414c8e5310bbf3cc01faffa8c901660 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • The description says the row stays advisory with ⏹, but the new print has no ⏹ glyph. Either add it so the row matches the other advisory rows, or correct the description.
  • Hard-coding Pi's delivery routes in the doctor duplicates the BROKER_ONLY reason in providers/mirrors/registry.py (PROJECTIONS). When Pi's projection changes, this text will go stale without anything failing. Branching on ProjectionKind.BROKER_ONLY would stay in step.
  • The registry says Pi's own mcp.json server outranks the extension, and the extension then refuses that name's tools. "Pi may load the same name from its own mcp.json" hides that refusal, which is the exact thing a user chasing a missing tool needs to know.

[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 .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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 1d7ff21ad414c8e5310bbf3cc01faffa8c901660 via the fork AI-review pipeline — 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 does not.

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

  • Item 1 — duplicate of src/kiro_crew/providers/mirrors/registry.py:326-350: the hard-coded prose ("only in crewmate DMs… pooled broker stubs… switched-off tool can withhold its entire server… own mcp.json") restates PROJECTIONS[ACP_BACKEND_PI].reason. There are now two spellings of Pi's delivery routes, and they will drift apart. Subtraction: shrink the wrapped paragraph to a pointer at that registry entry, or derive the text from it, rather than keeping a second copy.
  • Item 1 — one consumer, generalized the other way: the branch keys on backend == ACP_BACKEND_PI, while acp/client_mcp_array.py:505 keys the same routing on ProjectionKind.BROKER_ONLY. A grep for ProjectionKind\.BROKER_ONLY finds exactly one such backend (pi). Subtraction: drop the new ACP_BACKEND_PI import and key on the projection kind that already names this case.

What this change ships

Inventory (2 items) — 1 justified

Intent: a Pi user running kirocrew doctor learns which Pi sessions receive the MCP servers their spec declares. This is a FIX (wording).

  1. On Pi, doctor's "has no mirror; unprojected" line is replaced by "needs a live session to check" plus an explanation of the delivery routes — duplicate of providers/mirrors/registry.py Pi reason
  2. The Pi row loses its ⏹ glyph, which the description says it keeps — undeclared

[FIRST-PRINCIPLES-REVIEWED] 1d7ff21

Description read

[DESCRIPTION-READ] b4de120afedfb7f8d9142b5828318163200d3a9536e0d1c083f5fdf77589b336

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

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 1d7ff21ad414c8e5310bbf3cc01faffa8c901660 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1d7ff21

@iamwhatever
iamwhatever marked this pull request as ready for review November 18, 2026 10:41
@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 18, 2026 10:41
@iamwhatever
iamwhatever requested a review from buluoray November 18, 2026 10:41
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 18, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: 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):

  • The Pi row is printed with no advisory glyph, contradicting the PR's stated output and leaving the row without the status marker every sibling row has. The new test does not assert the glyph, so it would not catch this. (src/⁠kiro_crew/doctor_checks/mcp.py, low)
  • The diagnostic presents a same-named mcp.json server as a possible way the ref gets served. In crewmate DM sessions, the only sessions that receive spec servers, that same-named entry causes Crew's server tools to be refused. The issue asks doctor to name why a server is withheld, and this wording h (src/⁠kiro_crew/doctor_checks/mcp.py, medium)

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 1d7ff21ad4 · 22 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 18, 2026 11:30

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

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 refs row starts with a status word. Printing mcp tool refs: Note: {label} needs a live session to check: {refs} in doctor_checks/mcp.py would 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.md around line 237 still says a no-mirror backend lists refs as unprojected. One clause there for the Pi row would keep the spec current.

@KiroCrewCaptain
KiroCrewCaptain merged commit 2940f5f into kirodotdev:main Nov 18, 2026
97 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants