nexus_get_status: what needs the operator, fleet-wide (#155) #199
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/mcp-status"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Closes #155. Design:
docs/superpowers/specs/2026-09-23-mcp-phone-loop-design.md.A phone asking Claude "does anything need me?" gets the same answer the sidebar would give, with no browser open.
What
nexus_get_statusanswersneeds_you: everything that needs the operator to act, each item with anactionsentence naming the fix.needs-you(blocked on you) orerrored(claude not running and noendedreport).provision-failed,removal-failed,exitedorunhealthy.errored, and N copies of one problem with the wrong remedy help nobody.claude_session(ok|missing) andproviders_connected.quota: each window isnullwhen unknown. That covers no report yet, and aresets_atthat has passed. It is never 0%.counts: running workspaces and live sessions, so "nothing needs you" arrives with context rather than as an empty list.Deliberately excluded:
idle. The UI's own definition is "nothing is waiting on you".nexus_list_sessions mark="idle"finds those sessions.degraded,unreportableandunobserved: warnings, not blockers.stopWorkernever touches session rows, so they still readstatus: running(fact #26); the derivation reads workspace liveness and reports themstopped.No
phase./api/state's phase describes the caller's cookie. An MCP caller never has one, so it would always readneeds-unlock. The two instance-wide facts phase is built from go on the wire instead. The claude-session probe's hint names host paths, so it is withheld.exited, found in code reviewA workspace whose container stopped without Nexus asking still has
status: running, because nothing reconciles that column.live_statusis thenexitedordead, so its sessions derivestoppedand no rule fired. The tool answered "nothing needs you".With
RestartPolicy: unless-stoppeda crash restarts by itself, so in practice this is an externaldocker stop.restartingis excluded, since it passes by itself. The related case of a container removed outside Nexus (live_status: null) is not covered and is filed as #198.List tools
nexus_list_sessionsgains a derivedmarkfield beside the rawattention_state, which is unchanged: fact #40 forbids redefining it. It also gainsidandmarkfilters.nexus_list_workspacesgains anidfilter.idfiltered out by another filter returns an empty page. Anidthat exists nowhere is an error that names the tool to list with, and says it is the id, not the name or label.nexus_list_sessionsnow reads the workspace roster on every call, to derive marks.Where the rules live
$lib/attention-rollup.tsis browser-safe, like$lib/attention.ts.attentionItems(workers, sessions, markOf, healthOf)takes its two derivation inputs as functions:serverMarkOf, which has no per-session probe;workspaces.markFor, which has one.That UI is #197.
Known limitation
There is no probe on read.
markderives from the recordedclaude_alive, so a SIGKILLed or OOM'd claude can read live for up to one 60s resync. A clean exit, SIGTERM or SIGHUP reportsendedat once. #194 covers the rest. For anerroreditem,sinceis the agent's last report before it stopped, not the moment it stopped, and the field description says so.Deployment
nexus:readgrant gainsnexus_get_statuson deploy. It is read-only and needs no new scope or consent wording.Verification
node build/server.jscovered both MCP protocol legs (legacy SSE and 2026-07-28), on a seeded instance with a blocked session, an idle session and a deliberately stopped workspace:markfilter;mark: stoppedover a rawneeds-you;isError.workers.status; the unhealthy path through the tool; host values in the health report against the leak guard; and a failing read falling back to "no providers".