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.

fix(relay): a team tab's pause is reported nowhere, not to this desktop's mirror

reviewae08516a8a68
diff --git a/docs/hosted-team-relay.md b/docs/hosted-team-relay.md
index 5a312c7ba..6d9ca3857 100644
--- a/docs/hosted-team-relay.md
+++ b/docs/hosted-team-relay.md
@@ -653,6 +653,9 @@ holds for a hosted team's tabs and for a Team Access relay tab alike: both open
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.
+- **A pause made on a team tab is this desktop's own view and is reported nowhere**: not to the
+ host, and not to this desktop's agent-status mirror or the phone that reads it (the tab's store
+ has no `reportHibernated`, as it has no ack).
- **The host's node ids are input.** An event or a snapshot entry whose node id is not a safe id,
or is a name `Object.prototype` owns (`__proto__`, `constructor`, …), is dropped whole
(`isHostNodeId`) before it reaches the tab's table.
@@ -701,6 +704,12 @@ holds for a hosted team's tabs and for a Team Access relay tab alike: both open
reconnect.
- The resume line a team tab's node types builds from THIS machine's permission mode and launch
settings, not the host's.
+- A project shared into a live team mid-session gets no fresh `agent:status-snapshot`, so a Viewer's
+ or Commenter's newly shared nodes read Unknown until their next event; the re-ask belongs in the
+ shared-change path.
+- The relay client keeps frames on channels no relay code subscribes yet (`context:update`,
+ `agent:subagent-activity`, `agent:unread-clear`) in its bounded early buffer (4096 frames); the
+ first relay subscriber of those channels must drain or age out that backlog.
## Hosted tabs
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index d4c95366a..629b45eb6 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -17346,8 +17346,10 @@ export function Canvas() {
// written; what it hands back is the alert, and what that alert DOES is this window's own
// business (above). The account's `remote` flag is stamped here because this listener is the
// first layer that can reach the node and the project that owns it (see `observationIsRemote`).
+ // Asked only when the event carries an account: the reducer reads the flag for nothing else,
+ // and the node/project lookup behind it would otherwise run on every hook event.
const r = applyAgentEvent(useAgentStatus, useAgentNodes, e, {
- observationRemote: observationIsRemote(originOf(e.nodeId))
+ observationRemote: e.account ? observationIsRemote(originOf(e.nodeId)) : false
})
if (r.alert?.kind === 'finished') {
alert('finished', `${agentLabel} finished its turn.`, 'done', { quiet: r.alert.quiet })
diff --git a/src/renderer/canvas/agent-event-listener.source.test.ts b/src/renderer/canvas/agent-event-listener.source.test.ts
index 576afc80a..315b7f9c8 100644
--- a/src/renderer/canvas/agent-event-listener.source.test.ts
+++ b/src/renderer/canvas/agent-event-listener.source.test.ts
@@ -39,6 +39,13 @@ describe('Canvas agent-status listener — reducer split', () => {
expect(body).toContain('suppressDoneAfterHandoff') // local-only side effects stay here
})
+ it('asks whether an observation is remote only for an event that carries an account', () => {
+ // The reducer reads `observationRemote` for `setAccount` and nothing else
+ // (applyAgentEvent.test.ts pins that), so the node/project lookup behind it runs only then.
+ const body = listenerBody(read('canvas/Canvas.tsx'))
+ expect(body).toContain('observationRemote: e.account ? observationIsRemote(originOf(e.nodeId)) : false')
+ })
+
it('alert still marks unread only when not watching, then acks, sounds and notifies locally', () => {
const alertFn = alertBody(listenerBody(read('canvas/Canvas.tsx')))
expect(alertFn).toMatch(/!watching[\s\S]*markUnread/)
diff --git a/src/renderer/state/agentStatus-session.test.ts b/src/renderer/state/agentStatus-session.test.ts
index b81eeb8a4..76d11b7e5 100644
--- a/src/renderer/state/agentStatus-session.test.ts
+++ b/src/renderer/state/agentStatus-session.test.ts
@@ -139,6 +139,57 @@ describe('agentStatusForApi — one store per core, keyed by api identity', () =
expect(ackDone).toHaveBeenCalledWith('nt-y')
})
+ it('a non-local api never reports hibernated: a team tab pause stays off this desktop mirror', async () => {
+ // This desktop's own bridge, as the preload would expose it: the mirror a report would reach.
+ const local = { marker: 'preload', reportHibernated: vi.fn() }
+ vi.stubGlobal('window', { nodeTerminal: local })
+ const { agentStatusForApi, defaultAgentStatus } = await import('./agentStatus')
+ const relay = { marker: 'relay', reportHibernated: vi.fn() }
+ const session = agentStatusForApi(relay as unknown as NodeTerminalApi)
+ expect(session).not.toBe(defaultAgentStatus)
+ const { store } = session
+ // A shallow pause on a team tab's node (TerminalNode writes both flags), then a wake.
+ store.getState().setHibernated('nt-x', true)
+ store.getState().setPaused('nt-x', true)
+ expect(store.getState().byId['nt-x']?.hibernated).toBe(true)
+ expect(store.getState().byId['nt-x']?.paused).toBe(true)
+ store.getState().setHibernated('nt-x', false)
+ store.getState().setPaused('nt-x', false)
+ // Local-only in v1: not this desktop's mirror (under the host's node id), not the host.
+ expect(local.reportHibernated).not.toHaveBeenCalled()
+ expect(relay.reportHibernated).not.toHaveBeenCalled()
+ })
+
+ it('the default instance still reports hibernated to the local api, on each edge', async () => {
+ const reportHibernated = vi.fn()
+ const api = { marker: 'preload', reportHibernated } as unknown as NodeTerminalApi
+ vi.stubGlobal('window', { nodeTerminal: api })
+ const { agentStatusForApi, defaultAgentStatus } = await import('./agentStatus')
+ const session = agentStatusForApi(api)
+ expect(session).toBe(defaultAgentStatus)
+ session.store.getState().setHibernated('nt-y', true)
+ session.store.getState().setHibernated('nt-y', true) // no edge, no report
+ session.store.getState().setHibernated('nt-y', false)
+ expect(reportHibernated.mock.calls).toEqual([
+ ['nt-y', true],
+ ['nt-y', false]
+ ])
+ })
+
+ it('an injected reportHibernated is the only place the flag goes, and a throwing one breaks nothing', async () => {
+ const local = { marker: 'preload', reportHibernated: vi.fn() }
+ vi.stubGlobal('window', { nodeTerminal: local })
+ const { createAgentStatusSession } = await import('./agentStatus')
+ const report = vi.fn(() => {
+ throw new Error('bridge gone')
+ })
+ const { store } = createAgentStatusSession(undefined, undefined, report)
+ store.getState().setHibernated('nt-z', true)
+ expect(report).toHaveBeenCalledWith('nt-z', true)
+ expect(store.getState().byId['nt-z']?.hibernated).toBe(true)
+ expect(local.reportHibernated).not.toHaveBeenCalled()
+ })
+
it('window.nodeTerminal resolves to the default (persisted) instance — the WeakMap seed', async () => {
const api = { marker: 'preload' } as unknown as NodeTerminalApi
vi.stubGlobal('window', { nodeTerminal: api })
diff --git a/src/renderer/state/agentStatus.ts b/src/renderer/state/agentStatus.ts
index b4fe77878..42ef5c290 100644
--- a/src/renderer/state/agentStatus.ts
+++ b/src/renderer/state/agentStatus.ts
@@ -542,10 +542,16 @@ export interface AgentStatusSession {
* instance hydrates from and saves to; `undefined` = in-memory only (load returns nothing,
* save is a no-op — the instance never touches localStorage). See the module docblock for
* why only the default instance has a key today.
+ *
+ * The two callbacks are this store's only reports OUT, and both are injected so that only the
+ * store that describes this machine's own core has them: `ackDone` (a read of a finished session,
+ * see `clearUnread`) and `reportHibernated` (the SLEEPING flag, see `setHibernated`). Absent = the
+ * fact stays in this store. A relay tab's store gets neither (`agentStatusForApi`).
*/
export function createAgentStatusSession(
persistKey?: string,
- ackDone?: (nodeId: string) => void
+ ackDone?: (nodeId: string) => void,
+ reportHibernated?: (nodeId: string, on: boolean) => void
): AgentStatusSession {
if (persistKey === KEY) migrateLegacyKey()
@@ -1003,10 +1009,14 @@ export function createAgentStatusSession(
const prev = s.byId[id] ?? EMPTY
if (!!prev.hibernated === on) return s
// The renderer owns this flag; the core only mirrors it (agent-status mirror → SLEEPING on
- // the phone). Reported on the same edge the store changes, guarded because tests (and any
- // non-preload context) run this store without a bridge.
+ // the phone). Reported on the same edge the store changes, through the injected callback:
+ // only the default store has one, because only its node ids are this desktop's own. A relay
+ // tab's pause reported here put the HOST's node id into THIS desktop's mirror, where a
+ // hibernated entry never expires and survives a restart, and nothing ever reported it
+ // false. Guarded because tests (and any non-preload context) run this store without a
+ // bridge.
try {
- window.nodeTerminal?.reportHibernated?.(id, on)
+ reportHibernated?.(id, on)
} catch {
/* the mirror is a side-channel; a failed report must never break the store */
}
@@ -1272,8 +1282,11 @@ export function agentStatusForApi(api: NodeTerminalApi): AgentStatusSession {
// Keyless — remote status is never persisted (4a) — and with NO done-read ack: reading a remote
// session's finish clears unread on this desktop only (product decision 1). Nothing is sent back
// to that core (no `ackDone`, no `agent:ack-done`), so the host's own read state — its notch,
- // its paired phone's Live Activity — stays as it was.
- const session = createAgentStatusSession(undefined, undefined)
+ // its paired phone's Live Activity — stays as it was. And with NO hibernated report: a pause
+ // made on a team tab is this desktop's own view of the host's node. It is not the host's fact
+ // (v1 never tells the host), and it is not this desktop's either — its mirror (and the phone
+ // that reads it) describes this machine's nodes, and the host's node id has no place there.
+ const session = createAgentStatusSession(undefined, undefined, undefined)
if (api) instanceByApi.set(api, session)
return session
}
@@ -1289,9 +1302,18 @@ export function agentStatusForApi(api: NodeTerminalApi): AgentStatusSession {
*/
// The default (local core) acks the finished-session read to `window.nodeTerminal.ackDone` — guarded
// for node-environment tests where no preload exists (the callback is invoked later, at clear time).
-const defaultAgentStatus = createAgentStatusSession(KEY, (id) => {
- if (typeof window !== 'undefined') window.nodeTerminal?.ackDone?.(id)
-})
+const defaultAgentStatus = createAgentStatusSession(
+ KEY,
+ (id) => {
+ if (typeof window !== 'undefined') window.nodeTerminal?.ackDone?.(id)
+ },
+ // The SLEEPING flag, to this desktop's own mirror. Read at report time, like the ack: `window`
+ // has no bridge in node-environment tests, and the store's own try/catch keeps a throwing one
+ // from breaking the write.
+ (id, on) => {
+ if (typeof window !== 'undefined') window.nodeTerminal?.reportHibernated?.(id, on)
+ }
+)
export { defaultAgentStatus }
if (typeof window !== 'undefined' && window.nodeTerminal) {
instanceByApi.set(window.nodeTerminal as NodeTerminalApi, defaultAgentStatus)
diff --git a/src/renderer/state/applyAgentEvent.test.ts b/src/renderer/state/applyAgentEvent.test.ts
index e0c4ae782..8d8a43550 100644
--- a/src/renderer/state/applyAgentEvent.test.ts
+++ b/src/renderer/state/applyAgentEvent.test.ts
@@ -197,4 +197,33 @@ describe('applyAgentEvent', () => {
applyAgentEvent(status, useAgentNodes, ev({ nodeId: 'term-node-b', state: 'working', newTurn: true, account }), LOCAL)
expect(entry('term-node-b').account?.remote).toBe(false)
})
+
+ it('reads opts.observationRemote only for an event that carries an account', () => {
+ // Canvas computes the flag lazily (`e.account ? observationIsRemote(…) : false`), which is only
+ // correct while the reducer reads it for nothing else. A getter counts the reads.
+ let reads = 0
+ const opts = {
+ get observationRemote() {
+ reads++
+ return false
+ }
+ }
+ for (const e of [
+ ev({ state: 'working', newTurn: true, sessionId: 's1', task: '/loop 5m check' }),
+ ev({ state: 'blocked', pendingId: 'p-1' }),
+ ev({ state: 'done', lastMessage: 'ok', backgroundTaskIds: ['b1'] }),
+ ev({ kind: 'background-task' }),
+ ev({ kind: 'recurring', recurringKind: 'cron', schedule: '0 * * * *', task: 'x' }),
+ ev({ kind: 'subagent-start', toolUseId: 't-1', taskLabel: 'look' }),
+ ev({ kind: 'subagent-end', toolUseId: 't-1' }),
+ ev({ kind: 'session', sessionPhase: 'start', sessionTitle: 'named' }),
+ ev({ kind: 'session', sessionPhase: 'end' })
+ ]) {
+ applyAgentEvent(status, useAgentNodes, e, opts)
+ }
+ expect(reads).toBe(0)
+ const account = { configDir: '/home/u/.claude', accountId: null, known: false }
+ applyAgentEvent(status, useAgentNodes, ev({ state: 'working', account }), opts)
+ expect(reads).toBe(1)
+ })
})