Skip to content

feat(pi): report handed-off MCP servers pi did not register - #31121

Merged
bolichen97 merged 1 commit into
mainfrom
fix/19774-pi-mcp-registration-receipt
Nov 6, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/19774-pi-mcp-registration-receipt

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A pi session whose own pi process did not register a handed-off Crew MCP server shows that server as failed, with the cause pi named, before its first prompt.

On pi, Crew's MCP servers reach the session only through the gate extension's per-session handoff file, because pi-acp drops the session/new array. Nothing comes back from the pi process to say whether it registered them. When the handoff file is missing, unreadable or sealed for another session, or a name is shadowed by pi's own mcp.json, the server simply never reports: the MCP card shows it as not reported with no cause, and the routing read-back cannot help because it runs a separate pi child without the handoff.

Why it matters

Every Crew capability on pi (send_message, memory, cron, crew tools) is an MCP tool. A server pi never registered leaves the agent without those tools and the user with no named cause. The session-open mount check covers only pooled broker stubs (not the member mounts pi execs directly), cannot say why a stub never arrived, and reports up to 30 s after the session opens, after a subagent's one spawn-time reading of the report.

Not a goal

  • Refusing a pi session. A missing receipt is only logged: the ordering is measured on the pinned pi-acp and pi, and the version floor is not a pin.
  • Changing how the handoff file is sealed, published or read.
  • Making the routing read-back prove registration; it stays a load check for the gate.
  • Any other harness.

What changed (motivation → approach → change)

Only the session's own pi process knows what it registered, so it now says so. During session_start the gate extension writes a small receipt into the session's scratch window, bound to the session nonce, exclusive-create, mode 0600. The host reads and removes it right after session/new or session/load and before the first prompt, with a non-blocking open of a regular file only, since other agents of the session tree can write that window.

The receipt says The MCP report shows
server registered nothing new; its own frames and the mount check speak for it
handoff none / unreadable / malformed / unsealed every handed-off server failed, with a reason naming that handoff problem (never mcp.json)
per-server mcp_json / mcp_json_unreadable / refused / replaced that server failed, with a reason naming the cause and what to rename or remove
no scratch window, or no valid receipt a WARNING log line only; the card keeps showing it as not reported

The unknown case stays off the failed bucket on purpose: the subagent spawn notice reads that bucket as "do not retry", and the task and webhook notices print it as "unusable". Rows past the bucket's cap are dropped, as the mount check's are. A load-to-new retry clears the previous child's receipt before it republishes the handoff.

Code: in agent_sdk/gate_extensions/pi/kiro_crew_tool_gate.ts, readMcpHandoff returns a status beside the servers and session_start writes the receipt (PI_GATE_EXTENSION_SHA256 re-pinned); acp/pi_mcp_registration.py validates and applies it; harness/pi.py points KIROCREW_PI_MCP_RECEIPT at a nonce-named file in the allocated scratch window, dropping an inherited value; client_start._initialize_session calls it before discarding the handoff; client_mcp_array clears it on retry; harness/base.py declares work_scratch_dir on the ProcessSession protocol. docs/system-specs/modules/harness-parity.md documents the receipt and the three outcomes.

Backwards compatibility

Compatible: no pi session is refused and the MCP report payload gains no key; a session whose receipt is missing opens exactly as before. The receipt's one writer is the sealed gate extension in this diff, verified by digest at every spawn. Sessions with no handed-off servers, and every non-pi harness, are unaffected.

Removes nothing: the change adds a receipt and failed rows for servers pi confirmed it did not register; no field, path or behaviour is taken away.

Tests

  • test/test_pi_mcp_registration.py (new): a full receipt records nothing and sends no request; each per-server cause and each handoff status gives failed rows with its own reason (no handoff reason mentions mcp.json); invalid shapes (wrong version, wrong types, unknown status or cause, unhashable values, a name both registered and unregistered), unparseable or too-deeply-nested JSON, another nonce, no receipt and no scratch window each give no failed row and a warning naming the cause, and the receipt is removed; a FIFO at the receipt path is not read and does not block; a confirmed refusal reaches the subagent spawn notice; a load-to-new retry deletes the old receipt; the spawn env names the allocated scratch window, not an inherited value; _initialize_session opens with or without a receipt and drops the handoff either way.
  • test/test_pi_gate_extension_mcp.py: the real .ts under Node writes loaded with the server registered for a clean handoff, mcp_json / mcp_json_unreadable for a shadowed or broken mcp.json, refused when pi holds nothing under the name, unsealed for another key or nonce, malformed for a non-handoff file.
  • test/test_pi_real_adapter.py: test_real_pi_confirms_its_mcp_registration_before_session_new_returns drives the pinned pi-acp and pi through Crew's own launch and asserts the receipt is already there, loaded with the probe server registered, when session/new returns.
  • Negative controls: with the verify_registration call taken out of _initialize_session, test_session_start_without_a_receipt_opens_and_reports_before_the_first_prompt goes red; with the non-blocking open and the type guards taken out, the FIFO test times out and the unhashable-value case raises TypeError.

Local: black, isort, flake8, mypy (changed modules), subprocess-encoding, comment-history, brand, harness-parity, feature-map, file-line cap, docs-lint, flake-pattern ratchet (66 passed), semgrep 1.78.0 on the diff (0 findings). 1635 passed, 2 skipped across the pi, ACP harness, MCP report, subagent report and client-binding suites.

Manual verification

Ran the Real Adapter lane's pi tests locally against the pinned pair installed from test/real_adapters/package-lock.json (pi-acp 0.0.34, pi 1.4.0), with PI_ACP_BIN and PI_ACP_PI_COMMAND set as ci.yml does: 8 passed, including the new receipt check, the MCP handoff mount and the gated tool calls (21 with the Node-driven extension tests).

Screenshots / video

N/A — no frontend change: the MCP card already renders a failed row with its reason.

Related Issues

Closes #19774

Builds on #22400 by @leonlaiyc.

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

Contributed under the project's Apache-2.0 license.

On pi, Crew's MCP servers reach the session only through the gate
extension's per-session handoff file. Nothing came back from the pi
process to say whether it registered them, so a handoff that did not
open, or a name shadowed by pi's own mcp.json, left the server with no
cause on the MCP card and nothing in the subagent's spawn-time reading.

The extension now writes a nonce-bound receipt to the session's scratch
window during session_start, and the host reads it before the first
prompt: a server pi confirms it did not register becomes a failed row
naming the cause; no valid receipt is only a warning, never a failed
row. The Real Adapter lane measures that the receipt exists when pi-acp
answers session/new.

Closes #19774

Co-authored-by: Leon <leon.lai.yc@gmail.com>
@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 06:00
@bolichen97
bolichen97 requested a review from Zedmor November 6, 2026 06:00
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 73168164c567bedbe9f4170c8fbd9efab4d7f217 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the receipt is additive and read once, an unconfirmed result is only logged, and no session is refused.

Notes

  • Another agent of the session tree can write the scratch window. If it creates kirocrew_pi_mcp_<nonce>.json before pi does, the extension's flag: "wx" write fails, and the host then reads the planted file. That file can only add failed rows, but the subagent spawn notice reads a failed row as "do not retry". It is worth stating in the spec that the nonce is the only thing binding the receipt to this session.

[DESIGN-REVIEWED] 7316816

Description read

[DESCRIPTION-READ] 80b99012f15be55e4d752e468e8b2711f957a208a80a05b62e2cc70fc10f5d53

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

@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 73168164c567bedbe9f4170c8fbd9efab4d7f217 — 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. Each item answers the problem in #19774: servers pi never registered show up with no named cause. Each one reuses the existing failed-row path (McpSessionReport.record_pruned) and the scratch window that is already there.

What this change ships

Inventory (8 items) — 8 justified

Intent: on pi, a user should see which Crew MCP servers pi did not register, and why, before the first prompt. ADDITION (closes #19774).

  1. The MCP card shows a handed-off server as failed when pi confirms it did not register it, with a per-server cause (mcp.json shadow, unreadable mcp.json, refused, replaced) — justified
  2. The MCP card shows every handed-off server as failed, with a reason naming the handoff problem, when the handoff was missing, unreadable, malformed or unsealed — justified
  3. An unconfirmed registration (no receipt, or no scratch window) logs only a WARNING and never refuses the session — justified
  4. The gate extension writes a nonce-bound receipt into the session's scratch window during session_start — justified
  5. A new env var, KIROCREW_PI_MCP_RECEIPT, is set from the allocated scratch window and drops any inherited value — justified
  6. The extension's session_start handler now runs when no servers loaded, so a failed handoff can still report — justified
  7. A load-to-new retry deletes the previous child's receipt — justified
  8. ProcessSession declares work_scratch_dir, and PI_GATE_EXTENSION_SHA256 is re-pinned — justified

[FIRST-PRINCIPLES-REVIEWED] 7316816

Description read

[DESCRIPTION-READ] 73991f4435e7fd50bbebaa78af4dff7b24141818723315536eba9a779e18cb9b

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.

@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 06:13
@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 Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 73168164c567bedbe9f4170c8fbd9efab4d7f217 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 7316816

Verdict parsed from the review's SHA-scoped output markers for commit 73168164c567bedbe9f4170c8fbd9efab4d7f217.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 73168164c567bedbe9f4170c8fbd9efab4d7f217 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 73168164c567bedbe9f4170c8fbd9efab4d7f217 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 7316816

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 73168164c567bedbe9f4170c8fbd9efab4d7f217 false-positive: <reason, 20 to 500 characters>

@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 6, 2026

@buluoray buluoray 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.

🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:

APPROVE at 7316816.

What it does for users: on pi, a handed-off Crew MCP server that pi did not register now appears on the MCP card as failed before the first prompt, with the cause pi named (a same-named entry in pi's own mcp.json, an unreadable mcp.json, a refused or replaced registration, or a handoff that did not load). Until now that server only showed as "not reported", with no cause.

Harness parity. Every behaviour change sits in a branch that was already pi-only. In client_start.py around line 1115 the existing if self._is_pi: block now calls verify_registration before it discards the handoff. _republish_pi_mcp_handoff (client_mcp_array.py:1093) is pi-only. The receipt path is set in harness/pi.py:1093-1099. Identity is stated positively throughout: _is_pi appears everywhere and no not is_kiro check was added. The work reuses seams that already existed: the session tree's shared work directory, the gate nonce, and McpSessionReport.record_pruned for the failed rows. The one protocol addition on ProcessSession (harness/base.py:153), the work-directory property, declares a property that AcpClient already exposes (client_class.py:1271), so the seam is described more precisely without being widened. The Kiro path is unchanged.

Security. The receipt reader (pi_mcp_registration.py:89-138) opens the file with O_NOFOLLOW and O_NONBLOCK, accepts only a regular file, caps the read, requires the marker, version and nonce, and accepts only known statuses and causes. It removes the file whatever it contains. A missing or invalid receipt produces a warning log line and no failed row (lines 154-161), so an unknown is never reported as "unavailable". The spawn env drops an inherited receipt path before setting its own (pi.py:1097). No session is refused on any outcome. Nothing is loosened.

Evidence:

  • Targeted tests: test_pi_mcp_registration.py, test_pi_gate_extension_mcp.py, test_pi_real_adapter.py, test_acp_pi_backend.py and test_acp_refactor_facade.py gave 550 passed and 9 skipped. The skips are the real pi-acp cases, which need the pinned npm install, and one Windows-only codec case.
  • Mutation: removing the nonce check from read_registration turned test_another_sessions_receipt_reports_unconfirmed red, and the other 30 tests in the file stayed green. The tree was restored and git status was clean afterwards.
  • CI on this head: 77 success and 16 skipped, with Real Adapter Contract Tests green and PR Readiness green. All five review lanes pass on this head. merge-tree against main is clean (exit 0).

Source-only: I did not run the measured ordering locally (that pi finishes session_start before pi-acp answers session/new). I relied on the green Real Adapter Contract Tests job for it.

Follow-ups (non-blocking):

  • The Backwards compatibility section says the receipt's one writer is the sealed gate extension. Other agents of the same session tree can also write that shared work directory, as the description notes elsewhere. The design lane points out that a planted file can only add failed rows, but the spawn notice reads those rows as "do not retry". Please state in harness-parity.md that the nonce in the file name and body is the only thing binding the receipt to this session, and reword that sentence to match.

@bolichen97
bolichen97 merged commit c7c0498 into main Nov 6, 2026
97 of 101 checks passed
@bolichen97
bolichen97 deleted the fix/19774-pi-mcp-registration-receipt branch November 6, 2026 17:38
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 6, 2026
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.

pi: confirm the gate extension registered Crew's MCP servers

2 participants