nexus_get_status: what needs the operator, fleet-wide (#155) #199

Merged
lz merged 22 commits from feat/mcp-status into main 2026-09-23 18:45:15 +02:00
Owner

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_status answers

  • needs_you: everything that needs the operator to act, each item with an action sentence naming the fix.
    • Sessions whose derived mark is needs-you (blocked on you) or errored (claude not running and no ended report).
    • Workspaces that are provision-failed, removal-failed, exited or unhealthy.
    • Workspace items come first, and a faulted workspace hides its own sessions: when tmux is gone every session reads errored, and N copies of one problem with the wrong remedy help nobody.
  • claude_session (ok | missing) and providers_connected.
  • quota: each window is null when unknown. That covers no report yet, and a resets_at that 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, unreportable and unobserved: warnings, not blockers.
  • In-flight provisioning phases.
  • Deliberately stopped workspaces. stopWorker never touches session rows, so they still read status: running (fact #26); the derivation reads workspace liveness and reports them stopped.

No phase. /api/state's phase describes the caller's cookie. An MCP caller never has one, so it would always read needs-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 review

A workspace whose container stopped without Nexus asking still has status: running, because nothing reconciles that column. live_status is then exited or dead, so its sessions derive stopped and no rule fired. The tool answered "nothing needs you".

With RestartPolicy: unless-stopped a crash restarts by itself, so in practice this is an external docker stop. restarting is 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_sessions gains a derived mark field beside the raw attention_state, which is unchanged: fact #40 forbids redefining it. It also gains id and mark filters.
  • nexus_list_workspaces gains an id filter.
  • There are no getter tools. An id filtered out by another filter returns an empty page. An id that 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_sessions now reads the workspace roster on every call, to derive marks.

Where the rules live

$lib/attention-rollup.ts is browser-safe, like $lib/attention.ts. attentionItems(workers, sessions, markOf, healthOf) takes its two derivation inputs as functions:

  • the server passes serverMarkOf, which has no per-session probe;
  • a web view can pass workspaces.markFor, which has one.

That UI is #197.

Known limitation

There is no probe on read. mark derives from the recorded claude_alive, so a SIGKILLed or OOM'd claude can read live for up to one 60s resync. A clean exit, SIGTERM or SIGHUP reports ended at once. #194 covers the rest. For an errored item, since is the agent's last report before it stopped, not the moment it stopped, and the field description says so.

Deployment

  • Every existing nexus:read grant gains nexus_get_status on deploy. It is read-only and needs no new scope or consent wording.
  • No migration, no worker image release, no new HTTP route.

Verification

  • A live check against node build/server.js covered 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:
    • the roll-up, counts and unknown quota;
    • the mark filter;
    • the stopped workspace's session reading mark: stopped over a raw needs-you;
    • an unknown id returning isError.
  • The browser sidebar showed the same marks for the same sessions.
  • Every new guard was broken on purpose and the named test failed. That includes: the roll-up set against a literal oracle; fault override; stale 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".
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_status` answers - `needs_you`: everything that needs the operator to act, each item with an `action` sentence naming the fix. - **Sessions** whose derived mark is `needs-you` (blocked on you) or `errored` (claude not running and no `ended` report). - **Workspaces** that are `provision-failed`, `removal-failed`, `exited` or `unhealthy`. - Workspace items come first, and a faulted workspace hides its own sessions: when tmux is gone every session reads `errored`, and N copies of one problem with the wrong remedy help nobody. - `claude_session` (`ok` | `missing`) and `providers_connected`. - `quota`: each window is `null` when unknown. That covers no report yet, and a `resets_at` that 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`, `unreportable` and `unobserved`: warnings, not blockers. - In-flight provisioning phases. - Deliberately stopped workspaces. `stopWorker` never touches session rows, so they still read `status: running` (fact #26); the derivation reads workspace liveness and reports them `stopped`. **No `phase`.** `/api/state`'s phase describes the caller's cookie. An MCP caller never has one, so it would always read `needs-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 review A workspace whose container stopped without Nexus asking still has `status: running`, because nothing reconciles that column. `live_status` is then `exited` or `dead`, so its sessions derive `stopped` and no rule fired. The tool answered "nothing needs you". With `RestartPolicy: unless-stopped` a crash restarts by itself, so in practice this is an external `docker stop`. `restarting` is 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_sessions` gains a derived `mark` field beside the raw `attention_state`, which is unchanged: fact #40 forbids redefining it. It also gains `id` and `mark` filters. - `nexus_list_workspaces` gains an `id` filter. - There are no getter tools. An `id` filtered out by another filter returns an empty page. An `id` that 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_sessions` now reads the workspace roster on every call, to derive marks. ## Where the rules live `$lib/attention-rollup.ts` is browser-safe, like `$lib/attention.ts`. `attentionItems(workers, sessions, markOf, healthOf)` takes its two derivation inputs as functions: - the server passes `serverMarkOf`, which has no per-session probe; - a web view can pass `workspaces.markFor`, which has one. That UI is #197. ## Known limitation There is no probe on read. `mark` derives from the recorded `claude_alive`, so a SIGKILLed or OOM'd claude can read live for up to one 60s resync. A clean exit, SIGTERM or SIGHUP reports `ended` at once. #194 covers the rest. For an `errored` item, `since` is the agent's last report before it stopped, not the moment it stopped, and the field description says so. ## Deployment - Every existing `nexus:read` grant gains `nexus_get_status` on deploy. It is read-only and needs no new scope or consent wording. - No migration, no worker image release, no new HTTP route. ## Verification - A live check against `node build/server.js` covered 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: - the roll-up, counts and unknown quota; - the `mark` filter; - the stopped workspace's session reading `mark: stopped` over a raw `needs-you`; - an unknown id returning `isError`. - The browser sidebar showed the same marks for the same sessions. - Every new guard was broken on purpose and the named test failed. That includes: the roll-up set against a literal oracle; fault override; stale `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".
lz added 22 commits 2026-09-23 14:30:02 +02:00
Review fixes for the roll-up:
- New workspace problem 'exited': a container stopped from outside Nexus
  (or one Docker gave up restarting) left status='running' over a dead
  container reporting nothing needed the operator.
- Skip sessions whose workspace isn't in the roster, instead of labelling
  them with the bare workspace id.
- Export WorkspaceAttentionItem / SessionAttentionItem instead of
  Extract<AttentionItem, ...>.
- Sharper wording for the provision-failed action.
- Test comments state what's actually pinned, plus a literal-expectation
  suite that never computes its own oracle.
Code review found that a workspace stopped outside Nexus reported nothing:
its row still reads running, so its sessions derive stopped and no rule fired.
fix(mcp): say what since and live_status actually mean
All checks were successful
ci / nexus (pull_request) Successful in 5m15s
ci / images (pull_request) Successful in 7m29s
pr-image-cleanup / delete-pr-images (pull_request) Successful in 27s
20e2d7030d
since on an errored item is the agent's last report before it stopped, not
the moment it stopped. live_status is the fleet stream's last observation,
not a Docker call made per request.
lz merged commit 100f11d9ef into main 2026-09-23 18:45:15 +02:00
lz deleted branch feat/mcp-status 2026-09-23 18:45:17 +02:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
lz/agent-nexus!199
No description provided.