Everything the console can reach should be reachable over MCP, and nothing checks that — three projection losses in one week

[serge-ivo]

Anything the console can show or do, MCP should reach — and nothing tests that

The console and the MCP server read the same API. So every capability the console has is structurally available to MCP. Where MCP falls short it is either a deliberate exclusion or an accident, and today there is no way to tell which.

The accident that prompted this, measured 2026-08-15

An owner watching a stuck agent in the web UI could see the terminal saying You've hit your weekly limit. Their assistant, connected over MCP, could not:

coding_session_capture(instance_id)                → "No active coding session found."
coding_session_capture(instance_id, session_id)    → { runState: "ended", pane: "" }

The console shows that session's history; MCP returned an empty pane and, without a session id, denied the session existed. coding_timeline (#581, shipped today) now recovers it — objective, instructions, terminal output and per-tool-call inputs/outputs, defaulting to the most recent session. But that gap existed for months and nothing would have flagged it.

Related accidents already found and fixed this week, all the same shape — the console had it, MCP dropped it:

• coding_session_capture stripped runnerConnected/alive/ready/authPrompt (coding_session_capture drops the fields that disambiguate 'idle', advertises two values it cannot emit, and coding_diagnostics scores a refusing engine 0 issues #593)
• instance_board dropped updatedAt, which existed on BoardItemView all along (The board shows attempts:1 for a job that ran 9 times, asks for help with no reason or timestamp, and offers takeover of ended sessions #592)
• instance_board dropped reasoning entirely (A ticket's reasoning can be written over MCP and never read back #574)

Three independent projection losses in one week is not bad luck; it is an unguarded boundary.

The deliberate exclusions, which are fine — but are prose, not a test

platform-docs/mcp.md lists them: the credentials vault, API-key values, permission writes on instance state, Stripe checkout/portal, binary routes, arbitrary shell. Each has a stated reason and most are clearly right (secrets, browser redirects, binaries).

But that list lives in a document. Nothing compares it to reality, so a capability can leave the MCP surface — or never arrive — and land in neither the exclusion list nor anyone's attention.

What to build

A test that enumerates the console's API calls and asserts each is reachable over MCP or appears in an enumerated, justified exclusion list.

• The console's calls are statically discoverable (store/console/src/**), and MCP's tools declare the routes they proxy — so this is a comparison, not a survey.
• Fail on an unlisted gap. A new console feature with no MCP path should fail until someone either exposes it or writes down why not.
• Per ADR 0002 the success line states its denominator: how many console capabilities, how many reachable, how many excluded — so "checked and clean" is distinguishable from "not checked". That distinction is the subject of The vocabulary inventory's own citations are unchecked — three name files or symbols that do not exist #600, docs-drift swept the file and missed a stale 124 — the detector matches phrasings, so its denominator counts files read, not claims checked #603 and docs/ is swept by no gate — 27 findings across 9 files sit behind a green docs:drift #604.

Acceptance criteria

1. Console API surface enumerated with its denominator reported.
2. Each entry: reachable over MCP, or in the exclusion list with a reason.
3. An unlisted gap fails CI. Red demonstrated by removing a tool.
4. The exclusion list lives in code beside the check, and platform-docs/mcp.md renders from it rather than restating it — a second hand-maintained copy is how list_instance_tools and the published docs still tell operators to audit external reach by filtering on connector — the proxy #584 disproved #585 and Agent-facing docs state four numbers the code disproves, and root AGENTS.md predates the output-schema change its first recipe depends on #602 happened.
5. Report the gaps found on first run. That number is the real deliverable; the guard only stops it growing.

Verified vs inferred

• Verified: both coding_session_capture responses above, called live; that coding_timeline returns the full narrative for the same ended session; the three prior projection losses and their issues.
• Inferred: that console calls and MCP tool routes are statically comparable. Both look tractable but no prototype was written — if the mapping needs runtime knowledge, the shape of this check changes and that should be reported rather than forced.

[serge-ivo]

Shipped in 79f1107. CI ran the new gate and it passed; the generated table is live at https://proagentstore.online/docs/mcp/.

AC5 first — the gaps found on the first run

console capabilities : 161   (distinct METHOD + path, 5 call sites unreadable)
MCP routes           : 130   (3 call sites unreadable)
reachable over MCP   : 80/161 (49.7%)
deliberately excluded: 10 across 5 route rules + 6 statement rows
known gaps (ratchet) : 71 across 14 groups
UNLISTED gaps        : 0

Half the console is not reachable from an assistant. The 71 are inventoried by group in KNOWN_GAPS and listed route-by-route on #613. Regenerate with pnpm mcp:parity:gaps.

The clusters an owner is most likely to feel, in rough order:

• Per-run controls — read one task, delete it, resume it, drive a live takeover (end/input/resume), answer a needs_input handoff. This is the same class as the accident in this ticket: the console can act on a stuck agent and MCP can only watch.
• Machines and terminals — the Terminals page (every connected CLI across agents), forgetting a node, pinning an instance to a machine, the terminal session.
• Notifications and preferences — a caller cannot tell an owner what their agents have been trying to tell them.
• Outbound MCP connections — presets, test, consent, elicitation replies.
• Voice settings, loop presets, standing agent-tasks, feedback, knowledge edit / ingest-url, teamwork delivery outbox and replay, trigger + connector metadata, Drive/WorkDrive import, and the agent-template creator surface (15 routes, the largest and least urgent).

The inferred risk, answered

#610 recorded as inferred that the two surfaces are statically comparable, and asked for the shape to be reported rather than forced. They are comparable — but the qualification earned more than the conclusion. The first prototype reported 103 gaps of which 22 were false, all from three parsing shapes:

1. A nested template. agent_trace builds its query string inside the path template; a regex ends the string at the inner backtick and the tool reads as missing.
2. A path held in a variable. instance_runtime_status picks /runtime/status or /runtime by argument.
3. A prefix read off a lookup table. One registration serves both Drive and WorkDrive — six false gaps from one call site.

A false gap is the worst output this check can produce: it sends someone to build a tool that already exists, and the second one gets the check deleted. scripts/lib/api-calls.mjs handles all three, with a test per shape (15 tests). What is still unreadable — 5 console call sites, 3 MCP — is counted and printed on every run, because a coverage figure over a tree with silently skipped calls is not a coverage figure.

AC1–AC4

1. Denominator reported — the block above, printed by every run, green or red.
2. Every entry classified — reachable, excluded with a reason, or a recorded gap with a note. UNLISTED gaps: 0.
3. An unlisted gap fails CI, wired into ci.yml beside the other pre-install guards. Red demonstrated by removing the instance_board registration: ✗ 1 console capability(ies) have no MCP path and no entry: GET /v1/instances/{}/board [store/console/src/pages/RunDetail.tsx].
4. The exclusion list lives in code, and platform-docs/mcp.md is generated from it (--write); the check fails on drift. The published table gained an Enforced by column, because 5 of the 11 rows are route rules the check compares and 6 are statements about the surface with no console call to compare against — a distinction the prose could not make.

Two inventories, deliberately different: EXCLUSIONS is a decision, KNOWN_GAPS is a ceiling. Both fail on a dead entry, so closing a gap means deleting its entry in the same commit — the rule PINS and UNBACKED_CLAIMS already carry.

Watched failing (G4)

All four arms, on the real tree: an unlisted gap (tool removed), doc drift (one cell edited by hand), a dead inventory entry, and the extractor floor.

Not verified

The live MCP tools/list — reading it needs an OAuth token I do not hold. The doc half IS verified live (the table renders at /docs/mcp/ with its Enforced-by column). The check is static, so it has no production behaviour beyond CI.

Closing: the guard is in place and the measurement is reported. The 71 gaps are tracked on #613.