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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs: agent status on joined team tabs
reviewb4862ca02bf3
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 tolocalStorage 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 hookevents 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, sopreferring 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, anddiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 103890f03..df22a4e30 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -697,6 +697,12 @@ anything else. Board-level fields survive every transform — `pullLinks` is oneDo not "fix" this by re-stamping `sshRemoteTmux` onto those nodes: the host would then refuse itsown 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 everyexisting iPhone carries (`src/main/pairing-core.ts`). Link to a store only throughdiff --git a/docs/hosted-team-relay.md b/docs/hosted-team-relay.mdindex 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 thpending window) and "Your access to this team was removed by an owner.". While a mount is stillunapproved 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 tabsA 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 asession 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 arelay peer whose socket backlog passes 1 MB takes Stage 2's socket-backpressure ticket, whichpauses 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 eachit shows the closed-tab notice and opens nothing, and a notification for the shared node nowshows the SSH project's reopen warning. No `nt-<id>` session appears on this computer's owntmux 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.tsindex 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.tsindex 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'sdiff --git a/src/renderer/session/session.ts b/src/renderer/session/session.tsindex 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. */