Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

docs: agent status on joined team tabs

reviewb4862ca02bf3
diff --git a/CLAUDE.md b/CLAUDE.md
index e09bd3d29..9a943b3b7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2852,7 +2852,11 @@ shared 4-state model, and a **transient** zustand store `state/agentStatus.ts`
**not** persisted — only `unread`/`session`/`sessionId`/`agentId`/`loop`/`hibernated` go to
localStorage under `nodeterm.agentStatus`, migrated once from the legacy `nodeterm.claudeStatus`
key. `agentId` is durable because a hand-launched `claude` in a plain terminal is known nowhere
-else, and its context links must keep classifying across restarts).
+else, and its context links must keep classifying across restarts). That is the DEFAULT instance,
+the local core's. A relay / team tab's session gets its own **keyless** store (`agentStatusForApi`):
+it persists nothing, never acks a read (no `ackDone` callback), and is fed by `applyAgentEvent`
+(`state/applyAgentEvent.ts`), the same reducer Canvas's listener uses — see "A relay session owns
+its agent status" under Hosted team relay.
- **Agent registry + capabilities** — `src/shared/agents/config.ts` holds `AGENT_CONFIG`
(claude/codex/gemini/copilot/opencode/grok: id, label, spawn command, color, `promptInjectionMode`, …) keyed
@@ -3414,8 +3418,12 @@ else, and its context links must keep classifying across restarts).
(`normalizeClaude`/`normalizeCodex`/`normalizeGemini`/`normalizeCopilot`/`normalizeOpencode`/`normalizeGrok`/`normalizeAntigravity`) that map each agent's native hook
events to a `NormalizedAgentEvent` over the shared `AgentState` (`working | waiting | blocked
| done`) plus subagent/recurring/session kinds. Canvas's listener consumes
- `NormalizedAgentEvent` from `agent:status`, drives the `agentStatus` store, fires throttled
- (5s/node) background notifications, and records the session id. Header shows a pulsing
+ `NormalizedAgentEvent` from `agent:status` and hands it to `applyAgentEvent`, the pure reducer
+ that does every store write (state, session id, account, loop, subagent cards) and reports which
+ alert the event raised; the listener keeps what is a fact about THIS window — the unread mark and
+ its ack, the sound, the throttled (5s/node) background notifications, the handoff fold. A relay
+ session feeds the same reducer into its own keyless store (`wireRelayAgentStatus`), with no ack,
+ sound, notification or subagent cards. Header shows a pulsing
**RUNNING** (working) / **NEEDS YOU** (waiting/blocked) badge.
- **DROPPED — the CLI died and nobody told us** (`renderer/terminal/agent-liveness.ts`, issue #616).
Every ORDERLY exit announces itself: Eco's `/exit` sets `hibernated`, "Pause session" sets
@@ -10373,6 +10381,41 @@ invariants:
project keeps the agent status of node ids another project still holds (`nodeIdsHeldElsewhere`).
Deliberately NOT moved to it: `routeControlSource` (a control request comes from a LOCAL agent, so
preferring an open relay tab would route it to another machine).
+- **A relay session owns its agent status** (bug D: a team tab never showed RUNNING / NEEDS YOU /
+ unread, because the joiner's only `agent:status` subscriber was Canvas's listener on the LOCAL
+ api, which writes the DEFAULT store). `wireRelayAgentStatus` (`session/relay-agent-status.ts`,
+ held as a session teardown in `openRelayTab` right after `createSession`, before any further
+ await, so the RpcClient's early buffer flushes into it) subscribes the session's OWN api's `onAgentStatus` for the session's
+ lifetime and feeds `applyAgentEvent` into that session's keyless store
+ (`getSessionStores(id).agentStatus`). Routing is by api, never by a project lookup: two relay
+ sessions may serve one project id. **A reader of a team tab's node must not ask the default
+ store** (the ones that still do are the doc's follow-ups): after Share with team the handed-off
+ SSH project (local session, default store) and its team tab (relay session) hold the SAME node
+ ids, so a reader that asked the default store, or the active project's, shows one project's status
+ on the other's node, and a restart that read it would quit a host session the badge shows as
+ RUNNING. Readers resolve per project
+ (`agentStatusForProject`; `useAgentStatusLookup` / `useAgentStatusSig` re-subscribe inside the
+ session-registry listener, so a reconnect that leaves the signature unchanged still moves them to
+ the new store) or per node (`useSessionStores()`, render-safe for a session disposed a moment
+ ago). **No ack**: a read on a team tab clears unread on this desktop only (`agentStatusForApi`
+ builds the store with no `ackDone` callback), because an `agent:ack-done` would dismiss the
+ OWNER's phone Live Activity for a session they never looked at; the tab subscribes neither
+ `agent:unread-clear` nor `agent:subagent-activity`, and plays no sound and raises no notification.
+ **Snapshot ordering**: subscribe FIRST, then ask `agent:status-snapshot` (served by both shells
+ through `registerAgentStatusSnapshotIpc`, the newest 2000 mirror entries, narrowed for VIEW roles
+ and scoped guests by `narrowResponseForRole` via `sharedNode`), and apply it only to nodes no live
+ event touched in between (`liveSeen`; subagent events do not count, or the subscribe-time subagent
+ replay would hold the busiest nodes blank). A restored or identity-only mirror entry travels with
+ no `state`. A stateful one carries `ageMs` (an age, so no host clock crosses the wire) and sets
+ ONLY `stateAt = now - ageMs`, never `lastEventAt` / `lastSeen`: the joiner saw no transition, and
+ a fabricated one would claim it did. The teardown empties the store, so a dropped tab reads
+ Unknown. The status-driven readers that act on THIS machine are off for a relay node
+ (`relayStatusGates`: Approve/Deny, title sync, transcript search, the ⌘M chat view); only
+ `'local'` runs them, and `'relay'`, `'server'` and an unknown source fail closed. A desktop Team
+ Access host's agent emits go through `corePlatform.broadcast` (its window plus every non-quiet
+ peer); `agent:unread-clear` stays main-window only. Mobile: N/A (the phone speaks the legacy
+ dialect and reads the mirror file). Follow-ups, including the Canvas-level readers still on the
+ default store: docs/hosted-team-relay.md, "Agent status on a joined tab".
- **Admin errors are stable codes, and a `--json` refusal goes to STDOUT.** `E_BAD_KEY`,
`E_BAD_CWD`, `E_HOSTING_OFF`, `E_ADOPT_FAILED`, `E_BAD_REQUEST`, `E_UNSUPPORTED`
(`core/relay/admin-error.ts`); a remote caller branches on the code, never the sentence, and
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 103890f03..df22a4e30 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -697,6 +697,12 @@ anything else. Board-level fields survive every transform — `pullLinks` is one
Do not "fix" this by re-stamping `sshRemoteTmux` onto those nodes: the host would then refuse its
own sessions. CLAUDE.md, "Projects (tabs)".
+- **Read agent status through the node's session — `useSessionStores()` / `agentStatusForProject` —
+ never `useAgentStatus` directly, in any surface that can show a team tab's node.** A team tab
+ keeps its host's status in its own session store and shares node ids with the SSH project it was
+ handed off from, so the default store answers for the wrong project. CLAUDE.md, "A relay session
+ owns its agent status".
+
- **Phone keys and store links are platform-neutral.** New paired keys are stamped
`nodeterm-mobile-<id>`, but revoke must keep matching the legacy `nodeterm-ios-<id>` stamp every
existing iPhone carries (`src/main/pairing-core.ts`). Link to a store only through
diff --git a/docs/hosted-team-relay.md b/docs/hosted-team-relay.md
index de04441b7..3556a18b0 100644
--- a/docs/hosted-team-relay.md
+++ b/docs/hosted-team-relay.md
@@ -515,6 +515,7 @@ session key** in the team store.
| `git:diff` | The cwd (with the repository rule above) **and** the file are jailed; a pathspec starting with `:` is refused; an untracked diff (`git diff --no-index`, which diffs any file) needs a real path inside. The file is relative to the cwd, not the repository's top level. |
| `git:show-file` | The cwd jailed, with the repository rule above; a ref starting with `-` is refused (it would become an option, and `--output=` writes a file). Any other revision is allowed. |
| `agent:subagent-snapshot` | The response is trimmed to shared nodes. |
+| `agent:status-snapshot` | The response is trimmed to shared nodes. |
| `board-log:read/subscribe/unsubscribe` (+ `append` for Commenters) | Shared projects only. A Commenter's `append` must be a comment (`kind: 'comment'`): an activity entry ("moved a card to Done") is Editor-only. The entry is reduced to a comment's own fields (`id`, `ts`, `author`, `kind`, `text`, `nodeId`), and appends are bounded per peer key (one every 2 s, 32 KiB a minute, `core/relay/append-budget.ts`): the log keeps one rotated generation (4 MiB), and a flood used to rotate the project's real history out of it (security audit F3). |
**Which project a node is in** is read from the saved canvases (`WorkspaceStore.projectIdsForNode`).
@@ -616,6 +617,81 @@ request.", "No owner answered the request in time." (a first join waits up to th
pending window) and "Your access to this team was removed by an owner.". While a mount is still
unapproved after 2.5 s, the tab says "Waiting for an owner of X to approve this device…".
+## Agent status on a joined tab
+
+A team tab's agent nodes show the host session's RUNNING / NEEDS YOU badge and unread dot. This
+holds for a hosted team's tabs and for a Team Access relay tab alike: both open through
+`openRelayTab` (`session/relay-tab.ts`).
+
+- **The host sends it.** The Server Edition broadcasts `agent:status` to every attached client
+ (`wireAgentStatus`, `src/server/agent-status.ts`). A desktop Team Access host sends it too: the
+ agent emits in `src/main/index.ts` go through `corePlatform.broadcast`, its own window plus every
+ non-quiet relay peer, while `agent:unread-clear` stays on its own window. A non-editor receives
+ `agent:status` only for shared nodes (see [Roles](#roles)).
+- **The tab keeps it in its own store, never this desktop's.** For its whole lifetime the relay
+ session subscribes the host's `agent:status` on its own api (`wireRelayAgentStatus`,
+ `session/relay-agent-status.ts`, held as one of the session's teardowns) and feeds
+ `applyAgentEvent`, the reducer Canvas's listener uses, into the session's own in-memory store.
+ Nothing reaches this desktop's own agent-status table or its saved `nodeterm.agentStatus`: after
+ Share with team, the handed-off SSH project and the team tab hold the same node ids, and each must
+ show its own status. The v1 readers below ask through the node's project
+ (`agentStatusForProject`) or the session the node renders under (`useSessionStores()`).
+- **It subscribes first, then asks for a snapshot.** State events are not replayed, so a node that
+ started working before the tab joined would stay blank until its next event. Right after
+ subscribing, the tab asks `agent:status-snapshot` once: the host's agent-status mirror, at most
+ 2000 entries, trimmed to the shared nodes for a Viewer, Commenter or scoped guest. A node a live
+ event reached while the request was in flight keeps the live state, and the snapshot fills only
+ the rest. A host entry restored from disk, or one whose state expired, arrives with no state: its
+ agent, session id and account travel, and the node reads Unknown until its next event. A state
+ carries its age on the host (`ageMs`), never a host timestamp, so the tab's 60 s stale-working
+ sweep judges a served `working` by when the host last asserted it instead of decaying it on its
+ first tick. A host without the channel rejects the request, and the tab starts from live events
+ alone. A reconnect is a new session, so it asks again.
+- **Reading a finished session clears unread on this desktop only, and tells the host nothing.**
+ The tab's store has no ack: no `agent:ack-done` is sent, so the host's own read state, its paired
+ phone's Live Activity included, stays as it was. The tab does not subscribe `agent:unread-clear`
+ either, so a read recorded on the host clears nothing here.
+- **No notification and no sound** for a team tab's sessions. A finished turn, or a node that needs
+ input, marks the node unread unless this window has focus on that very node.
+- **Where it shows (v1):** the terminal node (badge, unread dot, session chip), the sessions
+ sidebar, the project tab's unread dot, and kanban cards and the card modal.
+- **What stays off on a team tab's node** (`relayStatusGates`, `terminal/relay-status-gates.ts`):
+ Approve/Deny (they answer this machine's permission server, which holds no ticket for the host's
+ session), the session-title sync (it would rewrite the host's canvas from every tab that shows the
+ node), the find bar's transcript search and the ⌘M chat view (both read this machine's
+ transcripts). ⌘M keeps the Markdown output view.
+- **A dropped or closed tab reads Unknown.** The teardown ends the subscription and empties the
+ store; a frame that arrives afterwards writes nothing.
+- **Mobile:** N/A. The phone speaks the legacy relay dialect and reads the host's agent-status
+ mirror file; nothing here changes what it sees.
+
+**Follow-ups, not built:**
+
+- The minimap's status stroke reads this desktop's own store.
+- The ⌘M chat view's live progress (`ChatPanel`) reads this desktop's own store; the view itself is
+ off on a team tab's node.
+- Issue run chips (`IssueRunChips`) read this desktop's own store.
+- No subagent cards: the tab's reducer writes none, and it does not subscribe
+ `agent:subagent-activity`.
+- The Server Edition's own browser canvas does not ask for the snapshot, so after a reload its
+ nodes start without the host's current states.
+- The context meter: the host sends `context:update` to relay peers, but the tab does not subscribe
+ it, and the meter's store is fed only from this desktop's own api.
+- On a desktop Team Access host, the SSH-project tails (`src/main/remote-context-tail.ts` for
+ Claude, `src/main/remote-subagent-tail.ts`) still send to the window captured at boot, not
+ through `corePlatform.broadcast`, so no peer hears a Claude node's meter or subagent transcript
+ from one of the host's SSH projects.
+- Canvas-level readers still on this desktop's store: the node menu's restart / pause / account
+ switch eligibility (`lib/nodeActionItems.tsx`), bulk pause, the Eco plan, `stationNoticeWiring`,
+ `loopCard`, the app badge count (Dock / taskbar), the sidebar row's account-chip "multiple
+ identities" check, and the focused-node skip of "next needing you".
+- The status-grouped sidebar lists a node id once (`buildStatusList` dedups by bare id), so a
+ shared id shows one row when both the handed-off SSH project and the team tab are open.
+- A shallow pause made on a team tab lives in the tab's in-memory store and does not survive a
+ reconnect.
+- The resume line a team tab's node types builds from THIS machine's permission mode and launch
+ settings, not the host's.
+
## Hosted tabs
A hosted team shows **one tab per shared project**, in the host's workspace order, all served by the
@@ -1177,7 +1253,9 @@ are unchanged.
project does not appear in its facepile at all, not even as "elsewhere".
- **A context meter needs an attributable session.** `context:update` reaches a non-editor only for a
session the host's agent-status mirror attributes to a shared node; a session the mirror has not
- seen a hook event for since the host started shows no meter to a Viewer until it does.
+ seen a hook event for since the host started shows no meter to a Viewer until it does. Delivery
+ aside, a team tab subscribes no `context:update`, so it shows no meter at all (see
+ [Agent status on a joined tab](#agent-status-on-a-joined-tab)).
- **A Viewer can still pause a shared terminal indirectly.** `pty:flow` pauses are refused, but a
relay peer whose socket backlog passes 1 MB takes Stage 2's socket-backpressure ticket, which
pauses the shared pty for every subscriber until that backlog drains below 256 KB or the peer
@@ -1369,3 +1447,9 @@ on a Mac and a second desktop as a teammate. Record `team status --json` at each
it shows the closed-tab notice and opens nothing, and a notification for the shared node now
shows the SSH project's reopen warning. No `nt-<id>` session appears on this computer's own
tmux socket at any point.
+26. **Agent status on a teammate's tab.** On a second desktop joined to the team, a Claude node on
+ the team's tab shows RUNNING while it works and NEEDS YOU on a question, and its sessions-sidebar
+ row moves out of Unknown. Join while the node is already working: the tab shows RUNNING at once.
+ With that desktop's window in the background, a finished turn puts an unread dot on the node
+ and on the project tab, with no notification and no sound. Clicking the node clears the dot,
+ and the host's paired phone's Live Activity for that session is not dismissed.
diff --git a/src/main/index.ts b/src/main/index.ts
index b19d71674..f0dcaa2f6 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -3041,7 +3041,8 @@ app.whenReady().then(async () => {
})
// Every context tail pushes through here, so an agent's meter reaches the renderer, the Notch HUD
// and the phone's context ring identically whichever CLI produced the numbers. `broadcast` is the
- // main window (sendToMain) plus every non-quiet relay peer, so a joined team tab's meter fills too.
+ // main window (sendToMain) plus every non-quiet relay peer. A joined team tab does not subscribe
+ // `context:update`, so its meter stays empty (docs/hosted-team-relay.md, follow-ups).
const pushContextUpdate = (payload: unknown): void => {
corePlatform.broadcast(IPC.contextUpdate, payload)
// Feed the macOS Notch HUD the model name (keyed by sessionId; no-op off/non-darwin).
diff --git a/src/renderer/bridge/relay-api.ts b/src/renderer/bridge/relay-api.ts
index d13da27fb..98d9739f5 100644
--- a/src/renderer/bridge/relay-api.ts
+++ b/src/renderer/bridge/relay-api.ts
@@ -9,9 +9,16 @@
//
// ── The API split (binding, from docs/remote-sessions.md line 70–76) ──────────────────────────────
// • CORE-BOUND namespaces (`pty`, `workspace`, `fs`, `git`, `files`, `context`, `canvas`, `presence`,
-// the `onAgentStatus`/`onSubagentActivity` streams, `claude.cliCaps`, `userDataDir`) route over the
-// relay RpcClient → they hit the REMOTE core. This is what makes the tab actually remote: its
-// terminals, repos, files, canvas and presence all live on the host's machine.
+// the agent members from `buildAgentApi` except `seedAgentIdentity` (below), `claude.cliCaps`,
+// `userDataDir`) route over the relay RpcClient → they hit the REMOTE core. This is what makes the
+// tab actually remote: its terminals, repos, files, canvas and presence all live on the host's
+// machine.
+// Routing an agent stream here subscribes nothing: Canvas's agent listeners run on the LOCAL api
+// only. The relay session subscribes `onAgentStatus` itself, for its lifetime, into its own store,
+// and then asks `agentStatusSnapshot` once (`session/relay-agent-status.ts`, wired in
+// `relay-tab.ts`). `onSubagentActivity` and `onUnreadClear` are deliberately NOT subscribed on a
+// relay tab: it renders no subagent cards, and its unread marks are this desktop's own, so a read
+// recorded on the host (a phone read-ack) clears nothing here, as a read here acks nothing there.
// • APP-GLOBAL namespaces (`updates`, `license`, `clipboard`, `shell`, `dialog`, `media`,
// `settings`, `pairing`, `announcements`, `usage`, `ssh*`, `remote*`, `relay*`, notifications, menu events)
// stay LOCAL (`window.nodeTerminal.*`). Your update banner shows YOUR version, a file picker
@@ -113,7 +120,9 @@ export function buildRelayApi(
context: files.context,
githubIssues: github.githubIssues,
githubControl: local.githubControl,
- ...buildAgentApi(client), // onAgentStatus / onSubagentActivity — the host's agent hooks
+ // The host's agent hooks. Only `onAgentStatus` (+ `agentStatusSnapshot`) is used on a relay tab,
+ // by session/relay-agent-status.ts; `onSubagentActivity` / `onUnreadClear` stay unsubscribed.
+ ...buildAgentApi(client),
...buildCanvasApi(client), // canvas sync against the host's reflector
...buildPresenceApi(client), // the host's presence hub
// `cliCaps` is REAL over the relay so the --permission-mode auto version gate probes the HOST's
diff --git a/src/renderer/session/session.ts b/src/renderer/session/session.ts
index cd1c06dc0..352f295ea 100644
--- a/src/renderer/session/session.ts
+++ b/src/renderer/session/session.ts
@@ -128,7 +128,8 @@ export function createSession(source: SessionSource, api: NodeTerminalApi, label
}
/** Register a teardown the owning tab owes when this session is disposed (obligation 1): the
- * presence `connect()` teardown, the relay socket close. `disposeSession` runs them once, in order.
+ * presence `connect()` teardown, the agent-status subscription (`wireRelayAgentStatus`, which also
+ * clears the session's store), the relay socket close. `disposeSession` runs them once, in order.
* Throws for an unknown id so a caller can never silently strand a live subscription. */
export function holdSessionTeardown(sessionId: string, teardown: () => void): void {
const e = SESSIONS.get(sessionId)
@@ -178,7 +179,8 @@ export function setSessionStatus(sessionId: string, status: WorkspaceSession['st
/** Take a session OFFLINE on an INVOLUNTARY socket drop (host/relay gone) — the counterpart of a
* user close. Unlike disposeSession, this KEEPS the entry and its project binding: run the held
- * teardowns once (presence leaves every peer's facepile; the already-dead relay socket close is a
+ * teardowns once (presence leaves every peer's facepile; the agent-status subscription ends and
+ * empties its store, so the greyed tab reads Unknown; the already-dead relay socket close is a
* safe no-op) and flip status to 'offline', but leave the tab bound to a 'relay' source so the
* greyed "unavailable" tab can reconnect IN PLACE (see relay-tab `handleRelayDrop` / `tabClickAction`).
* Idempotent; no-op once offline/disposed/unknown. */