feat(hub): pane_explain — why the fleet thinks an agent is idle/working/blocked (P4)

[physercoe]

Wedge P4 of docs/plans/pane-state-manifests.md. P2 made screen rules decide an agent's state; P3 made a blocked one raise attention. When either looked wrong there was no way to ask why — the rules are 58 matchers across 19 vendored TOMLs and the only observable was the verdict. Now you can ask, and the answer is the whole evaluation.

Two modes, one route

POST /v1/teams/{team}/pane_explain

• {agent_id} — the owning host captures that pane and evaluates it there. The screen never crosses to the hub; what comes back is the record.
• {family, screen} — evaluate text you already have. Upstream's --file mode: no host, no pane, no agent. It works on a screen pasted out of a bug report, it is how you check a rule change before shipping it, and it is the half CI can actually exercise.

Exclusive, not layered: "what is that agent doing" and "what would the rules say about this text" are different questions, and a body with both would have to pick one silently.

GET on the same route is D-3's coverage table — which families have a manifest at all. Previously that was readable only by opening a YAML compiled into the binary, and it is usually the answer to "why is this agent never classified". Unmapped families are absent, not listed as false; a row would imply a manifest exists.

What the record contains

Every rule, not just the winner — with what it wanted and a bounded preview of the region it read. Without that preview, "did not match" is a claim the reader cannot check. Plus the family→manifest mapping used, the manifest's version and whether it is vendor or overlay, the screen's size, and the OSC title (empty means every osc_title rule read nothing and could not have fired — which otherwise reads as "those rules are broken").

Deliberately absent: the screen. Per-rule previews are bounded at 240 chars; screen_bytes/screen_lines let you see the pane was 60 rows without shipping 60 rows.

Desktop

Inspect → Open → “Explain an agent pane…” lists running agents with a pane; engines with no manifest stay visible and disabled with the reason, because hiding them would leave the reader guessing. For the pasted mode, press “Read as pane state” on a scratch tab. Matched and unmatched rules differ by a glyph as well as a colour; each expands to what it wanted and what it read.

The mutation pass earned its keep

10 mutations, 10 caught — but three only after the pass exposed tests passing for the wrong reason:

Mutation	Why it first survived
delete the agent-token refusal	the test saw 403 — from a different layer. auth.Middleware allowlists bearer kinds and rejects agents outright, so my route test never reached my guard.
delete the mode-exclusivity check	the "both fields" fixture omitted family, so it 400'd for a missing family instead.
delete the winner-first sort	the fixture's winner was also the top-priority rule, so priority order alone produced the same list.

The first one corrected a premise I had written into the code, the plan and the changelog: I claimed the egress proxy's lack of a path allowlist let an agent bearer reach this route. It does forward every path — but the bearer is refused by kind before routing. I had checked two layers of three.

The guard stays, and is now honest about what it backs up. That allowlist deliberately exempts isInProcessDispatch — the hub's own authority-tool self-call, where an agent token is the legitimate credential. The day someone adds an MCP tool that dispatches here, the network guard is not in the path and this one is all that is left. TestPaneExplainRefusesAgentTokensInProcess reaches it by marking the context the way the self-call does.

Smaller notes

• P1 had already built the evidence side. Explain has carried per-rule outcomes with bounded previews since the first wedge ("every rule every pass — explain needs the evidence"). P4 is transport and surface, not evaluation.
• One type, not two. Explain gained json tags rather than growing a parallel wire struct. The price is that a field added for evaluation ships by default — to a payload that already carries pane text — so TestExplainWireKeysAreDeliberate pins the exact key set. Adding a field is fine; adding it silently is not.
• Live mode ignores the capture gate and the startup grace. Both exist to skip work nobody asked for; this call is the asking.
• datasetVerbJSON/datasetVerbError → verbJSON/verbError. Never dataset-specific; P4 is the second caller.

A gap found, not closed

The state-authority order — structured driver > screen manifest > nothing — exists only as this plan's D-2. spine/agent-lifecycle.md is an axiom doc that predates screen rules and does not mention them, so the fleet's real answer to "how is an agent's state decided" is not in the spine. Recorded in the plan rather than patched inside a feature wedge; an axiom edit deserves its own pass.

Verification

• go test ./... green — 33 packages, zero failures.
• Desktop 805/805, npm run typecheck clean, full lint set (12 runnable) clean, token ratchet unchanged (65 baseline, 0 phantom).
• All 37 CSS classes the two new components emit are checked against the stylesheet — no phantom classes.
• New how-to: debug-pane-state.md, indexed in docs/README.md.

Not verified

The Inspect card has never been rendered. No display on this machine. The parsing layer is pure and unit-tested (10 tests), the classes are checked against the stylesheet, and everything past that is unproven — it joins this lane's standing device-verify debt, alongside "no engine has been observed live".

Plan: pane-state-manifests P4. Follows #541 (P3), #536 (P2), #534 (P1+Q1), #533 (N1), #532 (plan review).

🤖 Generated with Claude Code