Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Fewer relay frames: one heartbeat a beat, slim transcript events, terminal-app-only events held while none is open (#2416)

0xken15b56138f73192
diff --git a/backend/src/lib/adapterAccountPushes.test.ts b/backend/src/lib/adapterAccountPushes.test.ts
index 1261907e1..d74549b5c 100644
--- a/backend/src/lib/adapterAccountPushes.test.ts
+++ b/backend/src/lib/adapterAccountPushes.test.ts
@@ -3,12 +3,13 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
const m = vi.hoisted(() => ({
desk: vi.fn(), zoo: vi.fn(), machines: vi.fn(), keys: vi.fn(), vault: vi.fn(),
deskUnsub: vi.fn(), zooUnsub: vi.fn(), machinesUnsub: vi.fn(), keysUnsub: vi.fn(), vaultUnsub: vi.fn(),
- swarms: vi.fn(), swarmsUnsub: vi.fn(),
+ swarms: vi.fn(), swarmsUnsub: vi.fn(), tui: vi.fn(), tuiUnsub: vi.fn(), tuiOpenNow: vi.fn(),
}))
vi.mock('./swarmClientPushes.js', () => ({ relaySwarmChanges: m.swarms }))
vi.mock('./bus.js', () => ({
subscribeDeskChanged: m.desk, subscribeZooChanged: m.zoo, subscribeDeviceMachineListChanged: m.machines,
- subscribeDeviceKeysChanged: m.keys, subscribeConnectorsChanged: m.vault,
+ subscribeDeviceKeysChanged: m.keys, subscribeConnectorsChanged: m.vault, subscribeTuiOpen: m.tui, tuiOpenNow: m.tuiOpenNow,
+ TUI_OPEN_FOR_MS: 180_000,
}))
import { relayAccountPushes } from './adapterAccountPushes.js'
@@ -25,6 +26,8 @@ describe('account pushes on a daemon socket', () => {
m.keys.mockResolvedValue(m.keysUnsub)
m.vault.mockResolvedValue(m.vaultUnsub)
m.swarms.mockResolvedValue(m.swarmsUnsub)
+ m.tui.mockResolvedValue(m.tuiUnsub)
+ m.tuiOpenNow.mockResolvedValue(false)
})
// WS roadmap Phase 2a: the windows read a Swarm when told (lib/swarmClientPushes.ts), through this daemon.
@@ -86,6 +89,7 @@ describe('account pushes on a daemon socket', () => {
it('hands the daemon a zoo change the same way, as its own frame', async () => {
const send = vi.fn()
await relayAccountPushes('user-1', send, on)
+ send.mockClear() // the attach word about terminal apps (change 5)
m.zoo.mock.calls[0][1]({ revision: 3 })
expect(send).toHaveBeenCalledWith({ t: 'down', connId: '', frame: { type: 'zoo_changed', payload: { revision: 3 } } })
expect(send).toHaveBeenCalledOnce()
@@ -124,4 +128,38 @@ describe('account pushes on a daemon socket', () => {
expect(m.deskUnsub).toHaveBeenCalledOnce()
expect(m.zooUnsub).not.toHaveBeenCalled()
})
+
+ // Change 5 of docs/plans/2026-10-31-live-events-relay-design.md: events only the terminal app reads are held back while
+ // the account has none open; the daemon learns it here.
+ const tuiOpen = (forMs: number) => ({ t: 'down', connId: '', frame: { type: '__tui_open', payload: { forMs } } })
+ it('tells the daemon at attach whether a terminal app of the account is open, and when one is', async () => {
+ m.tuiOpenNow.mockResolvedValue(true)
+ let heard: () => void = () => {}
+ m.tui.mockImplementation(async (_user: string, cb: () => void) => { heard = cb; return m.tuiUnsub })
+ const send = vi.fn()
+ const stop = await relayAccountPushes('kim', send, on)
+ expect(m.tui).toHaveBeenCalledWith('kim', expect.any(Function))
+ expect(send).toHaveBeenCalledWith(tuiOpen(180_000))
+ send.mockClear(); heard()
+ expect(send).toHaveBeenCalledWith(tuiOpen(180_000))
+ stop()
+ expect(m.tuiUnsub).toHaveBeenCalled()
+ })
+ it('says none is open at attach, so the daemon starts holding events back', async () => {
+ const send = vi.fn()
+ await relayAccountPushes('kim', send, on)
+ expect(send).toHaveBeenCalledWith(tuiOpen(0))
+ })
+ it('says nothing at attach when it cannot read whether one is open, so the daemon relays everything', async () => {
+ m.tuiOpenNow.mockResolvedValue(null)
+ const send = vi.fn()
+ await relayAccountPushes('kim', send, on)
+ expect(send.mock.calls.some(([f]) => (f as { frame: { type: string } }).frame.type === '__tui_open')).toBe(false)
+ })
+ it('tells a team machine nothing about terminal apps', async () => {
+ const send = vi.fn()
+ await relayAccountPushes('kim', send, { ...on, team: true })
+ expect(m.tui).not.toHaveBeenCalled()
+ expect(send.mock.calls.some(([f]) => (f as { frame: { type: string } }).frame.type === '__tui_open')).toBe(false)
+ })
})
diff --git a/backend/src/lib/adapterAccountPushes.ts b/backend/src/lib/adapterAccountPushes.ts
index 3055541c2..59aec314d 100644
--- a/backend/src/lib/adapterAccountPushes.ts
+++ b/backend/src/lib/adapterAccountPushes.ts
@@ -1,4 +1,4 @@
-import { subscribeConnectorsChanged, subscribeDeskChanged, subscribeDeviceKeysChanged, subscribeDeviceMachineListChanged, subscribeZooChanged } from './bus.js'
+import { subscribeConnectorsChanged, subscribeDeskChanged, subscribeDeviceKeysChanged, subscribeDeviceMachineListChanged, subscribeTuiOpen, subscribeZooChanged, TUI_OPEN_FOR_MS, tuiOpenNow } from './bus.js'
import { relaySwarmChanges } from './swarmClientPushes.js'
/**
@@ -21,6 +21,9 @@ import { relaySwarmChanges } from './swarmClientPushes.js'
* for the daemon: it re-reads the envelope and merges it into this computer's connections.
* - `swarm_changed` — a Swarm the account is in changed (lib/swarmClientPushes.ts): the
* windows read it again instead of every 3 s.
+ * - `__tui_open` — a terminal app of the account is open, good for `forMs` (bus.ts noteTuiPresence); said at
+ * attach too, with 0 when none is. For the daemon itself: it holds back from the relay the events only a terminal
+ * app reads while none is open (cli gateway.ts). `__` so a daemon from before it drops it without a word.
*
* `zoo` is the server's daemons switch (lib/daemonsSwitch.ts): off, the zoo channel is not even listened
* on, since nothing publishes it.
@@ -57,6 +60,11 @@ export async function relayAccountPushes(userId: string, send: (frame: unknown)
send({ t: 'down', connId: '', frame: { type: 'connectors_changed', payload: { revision: msg.revision } } })
}))
unsubs.push(await relaySwarmChanges(userId, (frame) => send({ t: 'down', connId: '', frame })))
+ const tuiOpen = (forMs: number) => send({ t: 'down', connId: '', frame: { type: '__tui_open', payload: { forMs } } })
+ unsubs.push(await subscribeTuiOpen(userId, () => tuiOpen(TUI_OPEN_FOR_MS)))
+ // Unreadable (null): no word at all, so the daemon relays every event rather than hold a terminal app's back.
+ const open = await tuiOpenNow(userId)
+ if (open !== null) tuiOpen(open ? TUI_OPEN_FOR_MS : 0)
} catch (err) {
stop()
throw err
diff --git a/backend/src/lib/adapterTuiPresence.test.ts b/backend/src/lib/adapterTuiPresence.test.ts
new file mode 100644
index 000000000..0ac352ed6
--- /dev/null
+++ b/backend/src/lib/adapterTuiPresence.test.ts
@@ -0,0 +1,83 @@
+import { EventEmitter } from 'node:events'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+// A terminal app's presence on the real machine socket (change 5 of docs/plans/2026-10-31-live-events-relay-design.md):
+// the account's daemons are told one is open. The socket harness is adapterShortTurns.test.ts's.
+const m = vi.hoisted(() => ({
+ auth: vi.fn(), upgrade: vi.fn(), noteTui: vi.fn(), resolve: vi.fn(), publishUp: vi.fn(), recordTurn: vi.fn(), nodeRole: vi.fn(), warn: vi.fn(), info: vi.fn(),
+}))
+vi.mock('./ssoAuth.js', async original => ({ ...await original<typeof import('./ssoAuth.js')>(), authenticateAccessToken: m.auth }))
+vi.mock('./wsServer.js', async original => ({ ...await original<typeof import('./wsServer.js')>(), createWss: () => ({ handleUpgrade: m.upgrade }) }))
+vi.mock('../services/MachineService.js', () => ({ machineService: { resolveOrCreateForComputer: m.resolve } }))
+vi.mock('./prisma.js', () => ({
+ prisma: { machine: { update: vi.fn(async () => ({})), findUnique: vi.fn(async () => null) }, user: { findUnique: vi.fn(async () => null) } },
+ machineAlive: { OR: [{ deletedAt: null }, { deletedAt: { isSet: false } }] },
+}))
+vi.mock('./bus.js', () => ({
+ publishUp: m.publishUp, claimMachineOwner: vi.fn(async () => true), releaseMachineOwner: vi.fn(), publishDeviceE2eePair: vi.fn(),
+ publishTerminalUp: vi.fn(), noteTuiPresence: m.noteTui, subscribeTerminalDown: vi.fn(async () => () => {}), setMachineAppState: vi.fn(), clearMachineAppState: vi.fn(),
+}))
+vi.mock('./adapterAccountPushes.js', () => ({ relayAccountPushes: vi.fn(async () => () => {}) }))
+vi.mock('./deviceKeyLog.js', () => ({ appendDeviceKey: vi.fn(), touchDeviceKey: vi.fn() }))
+vi.mock('./nodeRole.js', () => ({ attachNodeRole: m.nodeRole, PRESENCE_TTL_SEC: 30 }))
+vi.mock('./hub.js', () => ({
+ CLIENTS_FRAME: '__clients', CLIENTS_DIRTY: '__clients_dirty', LIVENESS_TICK_MS: 5_000, CLIENT_IDLE_DEADLINE_MS: 75_000,
+ DEVICE_IDLE_DEADLINE_MS: 35_000, CLIENT_HEARTBEAT_MS: 25_000, deliverTerminalUpLocal: vi.fn(), deliverUpLocal: vi.fn(),
+ pushDeviceRevoked: vi.fn(), sendClientsControl: vi.fn(), recomputeAndSendClients: vi.fn(), attachHubClient: vi.fn(),
+ trackSocketLiveness: () => () => {},
+}))
+vi.mock('./dailyTracking.js', async original => ({ ...await original<typeof import('./dailyTracking.js')>(),
+ touchMachineOnlineDay: vi.fn(async () => {}), touchUserOnlineDay: vi.fn(async () => {}), touchClientOnlineDay: vi.fn(async () => {}),
+ recordTurnStarted: m.recordTurn }))
+vi.mock('../utils/logger.js', () => ({ logger: { warn: m.warn, info: m.info, error: vi.fn(), debug: vi.fn() } }))
+
+import { handleAdapterUpgrade } from './adapterWs.js'
+
+const flush = async () => { for (let i = 0; i < 400; i++) await Promise.resolve() }
+
+class Socket extends EventEmitter {
+ readyState = 1; bufferedAmount = 0
+ send = vi.fn()
+ close = vi.fn((code?: number, reason?: string) => { this.readyState = 3; this.emit('close', code, Buffer.from(reason ?? '')) })
+ terminate = vi.fn(() => this.close())
+ frame(body: unknown) { this.emit('message', Buffer.from(JSON.stringify(body)), false) }
+}
+
+async function machineSocket(query = ''): Promise<Socket> {
+ const ws = new Socket()
+ m.upgrade.mockImplementation((_r, _s, _h, done) => done(ws))
+ handleAdapterUpgrade({ url: `/api/adapter-ws?computer=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&label=Mac&autonomousEnv=prod${query}`,
+ headers: { 'sec-websocket-protocol': 'access-token' } } as never,
+ { write: vi.fn(), destroy: vi.fn(), destroyed: false, on: vi.fn(), once: vi.fn() } as never, Buffer.alloc(0))
+ await flush()
+ return ws
+}
+
+beforeEach(() => {
+ vi.clearAllMocks()
+ m.auth.mockResolvedValue({ sub: 'owner', email: '[email protected]', role: 'user', autonomousEnv: 'prod' })
+ m.resolve.mockResolvedValue({ machine: { machineId: 'looping-mac', userId: 'owner', name: 'Mac', billingStatus: 'not_required', sessionKind: null }, created: false })
+ m.publishUp.mockResolvedValue(1)
+ m.recordTurn.mockResolvedValue(undefined)
+ m.nodeRole.mockResolvedValue({ touch: vi.fn(), detach: vi.fn(async () => {}) })
+})
+
+describe('a terminal app\'s presence', () => {
+ const presence = (payload: Record<string, unknown>) => ({ t: 'up', webEligible: false, commanderEligible: false, frame: { type: 'app_presence', payload } })
+
+ it('tells the account a terminal app is open, on Harness OS too, with its open or ping', async () => {
+ const ws = await machineSocket()
+ ws.frame(presence({ kind: 'open', surface: 'tui' }))
+ ws.frame(presence({ kind: 'ping', surface: 'harness-os-pi' }))
+ await flush()
+ expect(m.noteTui.mock.calls).toEqual([['owner', 'open'], ['owner', 'ping']])
+ })
+
+ it('says nothing for the desktop app or a surface it does not know', async () => {
+ const ws = await machineSocket()
+ ws.frame(presence({ kind: 'open' }))
+ ws.frame(presence({ kind: 'ping', surface: 'toaster' }))
+ await flush()
+ expect(m.noteTui).not.toHaveBeenCalled()
+ })
+})
diff --git a/backend/src/lib/adapterWs.ts b/backend/src/lib/adapterWs.ts
index dd0a87c48..8d11a36ea 100644
--- a/backend/src/lib/adapterWs.ts
+++ b/backend/src/lib/adapterWs.ts
@@ -25,7 +25,7 @@ import { prisma } from './prisma.js'
import {
publishUp, claimMachineOwner, releaseMachineOwner, publishDeviceE2eePair,
subscribeTerminalDown,
- setMachineAppState, clearMachineAppState,
+ setMachineAppState, clearMachineAppState, noteTuiPresence,
} from './bus.js'
import { deliverUpLocal, trackSocketLiveness } from './hub.js'
import { PROCESS_ID } from './registry.js'
@@ -509,7 +509,11 @@ async function attachAdapter(ws: WebSocket, machineId: string, userId: string, c
// TUI says where it runs (TUI_SURFACES); a name this backend does not know counts as nothing,
// never as the desktop app.
if (surface === undefined) touchUserPresence(kind as 'open' | 'ping')
- else if (typeof surface === 'string' && TUI_SURFACES.has(surface)) touchTuiPresence(surface as ClientSurface, kind as 'open' | 'ping')
+ else if (typeof surface === 'string' && TUI_SURFACES.has(surface)) {
+ touchTuiPresence(surface as ClientSurface, kind as 'open' | 'ping')
+ // Its account's daemons relay the events only a terminal app reads while one is open (bus.ts noteTuiPresence).
+ void noteTuiPresence(userId, kind as 'open' | 'ping')
+ }
return
}
// The machine appending to its account's device key log (lib/deviceKeyLog.ts): its own key, or a
diff --git a/backend/src/lib/bus.test.ts b/backend/src/lib/bus.test.ts
index a35c44167..f200352c8 100644
--- a/backend/src/lib/bus.test.ts
+++ b/backend/src/lib/bus.test.ts
@@ -39,6 +39,8 @@ vi.mock('ioredis', () => {
on = vi.fn()
eval = vi.fn(async () => 0)
get = vi.fn(async (_key: string): Promise<string | null> => null)
+ set = vi.fn(async (..._args: unknown[]): Promise<string | null> => 'OK')
+ exists = vi.fn(async (_key: string): Promise<number> => 0)
pipelines: FakePipeline[] = []
pipeline() { const p = new FakePipeline(); this.pipelines.push(p); return p }
multiCalls: Array<{ cmd: string; args: unknown[] }> = []
@@ -68,7 +70,7 @@ const bus = await import('./bus.js')
type MockFn = ReturnType<typeof vi.fn>
const pub = state.instances[0] as unknown as {
publish: MockFn; subscribe: MockFn; opts: unknown
- eval: MockFn; get: MockFn
+ eval: MockFn; get: MockFn; set: MockFn; exists: MockFn
multiCalls: Array<{ cmd: string; args: unknown[] }>; multiResult: unknown
pipelines: Array<{ calls: Array<{ cmd: string; args: unknown[] }> }>
}
@@ -341,3 +343,42 @@ describe('Swarm stamps', () => {
expect(heard).toEqual([['tab-2', ['machine']]])
})
})
+
+// Change 5 of docs/plans/2026-10-31-live-events-relay-design.md: a terminal app open on the account, told to its daemons.
+describe('terminal app presence', () => {
+ beforeEach(() => { pub.publish.mockClear(); pub.set.mockReset(); pub.set.mockResolvedValue('OK'); pub.exists.mockReset() })
+
+ it('refreshes the account\'s key for 150 s on every open and ping, and tells the daemons at once on an open', async () => {
+ await bus.noteTuiPresence('kim', 'open')
+ expect(pub.set).toHaveBeenCalledWith('tui_open:kim', '1', 'EX', 150)
+ expect(pub.publish.mock.calls.map((c: unknown[]) => c[0])).toEqual(['tui:kim'])
+ expect(bus.TUI_OPEN_FOR_MS).toBe(180_000)
+ })
+
+ it('tells the daemons on a ping at most once a minute', async () => {
+ pub.set.mockImplementation(async (...args: unknown[]) => (args[0] === 'tui_open_said:kim' ? 'OK' : 'OK'))
+ await bus.noteTuiPresence('kim', 'ping')
+ expect(pub.set).toHaveBeenCalledWith('tui_open_said:kim', '1', 'EX', 60, 'NX')
+ expect(pub.publish).toHaveBeenCalledTimes(1)
+ pub.set.mockImplementation(async (...args: unknown[]) => (args[0] === 'tui_open_said:kim' ? null : 'OK'))
+ await bus.noteTuiPresence('kim', 'ping')
+ expect(pub.publish).toHaveBeenCalledTimes(1)
+ })
+
+ it('reads whether one is open now, and cannot say (null) when Redis fails', async () => {
+ pub.exists.mockResolvedValueOnce(1)
+ await expect(bus.tuiOpenNow('kim')).resolves.toBe(true)
+ pub.exists.mockResolvedValueOnce(0)
+ await expect(bus.tuiOpenNow('kim')).resolves.toBe(false)
+ pub.exists.mockRejectedValueOnce(new Error('ECONNREFUSED'))
+ await expect(bus.tuiOpenNow('kim')).resolves.toBeNull()
+ })
+
+ // Final review: without Redis (single-pod mode, bus.ts) the daemons on this pod must still hear a terminal app opened.
+ it('still tells the daemons when Redis refuses its keys', async () => {
+ pub.set.mockRejectedValue(new Error('ECONNREFUSED'))
+ await expect(bus.noteTuiPresence('kim', 'open')).resolves.toBeUndefined()
+ await expect(bus.noteTuiPresence('kim', 'ping')).resolves.toBeUndefined()
+ expect(pub.publish.mock.calls.map((c: unknown[]) => c[0])).toEqual(['tui:kim', 'tui:kim'])
+ })
+})
diff --git a/backend/src/lib/bus.ts b/backend/src/lib/bus.ts
index 9d1b668b6..587f6b9f5 100644
--- a/backend/src/lib/bus.ts
+++ b/backend/src/lib/bus.ts
@@ -923,6 +923,50 @@ export function subscribeDeskChanged(userId: string, cb: (msg: DeskChangedMsg) =
return addSub(deskChannel(userId), cb as Cb)
}
+// ── a terminal app open on the account (docs/plans/2026-10-31-live-events-relay-design.md, change 5) ─────────────────
+// Few people run `harness tui` (or Harness OS, which runs it), and only it reads some transcript events in full: a daemon
+// holds those back from the relay while none of its account's is open (one Desktop's day, 2026-10-30: about 12,700 of
+// its 170,666 frames). A daemon with one attached sends app_presence `open` at once and a `ping` at most once a minute
+// (cli gateway/upstream.ts APP_PRESENCE_UP_MS); the key outlives two and a half pings, and the daemons are told at once on
+// an open and at most once a minute after, each word good for three minutes: closing one needs no message.
+const tuiOpenKey = (userId: string): string => `tui_open:${userId}`
+const tuiSaidKey = (userId: string): string => `tui_open_said:${userId}`
+const tuiChannel = (userId: string): string => `tui:${userId}`
+/** How long a daemon takes one word that a terminal app is open (cli gateway.ts `__tui_open`). */
+export const TUI_OPEN_FOR_MS = 180_000
+const TUI_OPEN_KEY_SEC = 150
+const TUI_SAID_SEC = 60
+
+/** A terminal app of [userId]'s is open (its daemon's `open`) or still is (`ping`). Never throws. Without Redis its keys
+ * cannot be kept, but the daemons are told anyway (final review: in single-pod mode `safePublish` still reaches this
+ * pod's daemons, and holding a terminal app's events back is what must not happen silently). */
+export async function noteTuiPresence(userId: string, kind: 'open' | 'ping'): Promise<void> {
+ let tell = kind === 'open'
+ try {
+ await pub.set(tuiOpenKey(userId), '1', 'EX', TUI_OPEN_KEY_SEC)
+ if (!tell) tell = await pub.set(tuiSaidKey(userId), '1', 'EX', TUI_SAID_SEC, 'NX') === 'OK'
+ } catch (err) {
+ tell = true
+ logger.warn('[bus] terminal app presence not kept', { userId, error: err instanceof Error ? err.message : String(err) })
+ }
+ if (tell) await safePublish(tuiChannel(userId), '1')
+}
+
+/** Whether a terminal app of [userId]'s is open now; null when Redis cannot say, and then the daemon is told nothing and
+ * relays every event, which costs frames, never a terminal app its events. */
+export async function tuiOpenNow(userId: string): Promise<boolean | null> {
+ try {
+ return await pub.exists(tuiOpenKey(userId)) > 0
+ } catch (err) {
+ logger.warn('[bus] terminal app presence unreadable', { userId, error: err instanceof Error ? err.message : String(err) })
+ return null
+ }
+}
+
+export function subscribeTuiOpen(userId: string, cb: () => void): Promise<() => void> {
+ return addSub(tuiChannel(userId), (() => cb()) as Cb)
+}
+
// Per-USER zoo invalidation: the account's daemons or eggs changed (routes/zoo.ts). The same path as
// the desk and a separate channel, so a desk change never re-fetches the zoo and the other way round.
export interface ZooChangedMsg { revision: number }
diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.ts
index 75153071b..92dadc337 100644
--- a/cli/src/backendSocket.spec.ts
+++ b/cli/src/backendSocket.spec.ts
@@ -2679,6 +2679,21 @@ describe('BackendSocket outbound queue', () => {
await socket.stop()
})
+ it('sends apps away from this desk a slim transcript event, and the windows here the whole one', async () => {
+ const socket = relaySocket('token')
+ const broadcast = vi.spyOn(gatewayOf(socket), 'broadcast')
+ const frames: Record<string, unknown>[] = []
+ socket.registerLocalClient('local:window', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
+ const ended = { type: 'tool_end', agentId: 'a1', dbSessionId: 's1', payload: { id: 'u1', tool: 'Bash', output: 'the whole output',
+ isError: false, summary: 'ok', agentId: 'a1', sessionId: 's1' } }
+ const whole = structuredClone(ended)
+ socket.send(ended)
+ expect(frames.filter((frame) => frame.type === 'tool_end')).toEqual([whole])
+ expect(broadcast).toHaveBeenCalledExactlyOnceWith({ ...ended, payload: { id: 'u1', tool: 'Bash', isError: false, agentId: 'a1', sessionId: 's1' } }, undefined)
+ await socket.unregisterLocalClient('local:window')
+ await socket.stop()
+ })
+
it('says whether an app away from this desk holds a session: a web one, never a device', async () => {
const socket = relaySocket('token')
expect(socket.hasRemoteApp()).toBe(false)
diff --git a/cli/src/backendSocket.teamApps.spec.ts b/cli/src/backendSocket.teamApps.spec.ts
index 973132615..82f328603 100644
--- a/cli/src/backendSocket.teamApps.spec.ts
+++ b/cli/src/backendSocket.teamApps.spec.ts
@@ -70,9 +70,9 @@ describe('the account\'s own apps under a remote app policy', () => {
it('withholds from the apps the events the policy withholds, and still tells the windows here', async () => {
const { socket, gw } = session()
const broadcast = vi.spyOn(gw, 'broadcast').mockImplementation(() => {})
- socket.send({ type: 'text_delta', payload: { agentId: 'pm', text: 'private' } })
- socket.send({ type: 'text_delta', payload: { agentId: 'worker', text: 'hello' } })
- expect(broadcast.mock.calls.map(([frame]) => frame)).toEqual([{ type: 'text_delta', payload: { agentId: 'worker', text: 'hello' } }])
+ socket.send({ type: 'text_delta', payload: { agentId: 'pm', content: 'private' } })
+ socket.send({ type: 'text_delta', payload: { agentId: 'worker', content: 'hello' } })
+ expect(broadcast.mock.calls.map(([frame]) => frame)).toEqual([{ type: 'text_delta', payload: { agentId: 'worker', content: 'hello' } }])
})
it('holds the account\'s own apps to watching their terminals, and no guest, window here or daemon without a policy', () => {
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index dabd6f2f4..17edf760c 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -1,6 +1,7 @@
import { messageReceipt, productObservation, productUsageIntent, productUsageLaunch, productUsageRequest, productUsageSource } from './lib/productUsageSignals.js'
import type { MessageReceipt } from './lib/sessionInput.js'
import { isLocalOnly, withoutUpdate } from './lib/cardUpdate.js'
+import { slimForRelay } from './lib/slimForRelay.js'
import type { PurgeAgentService } from './lib/purgeAgentService.js'
import { MESSAGES_REQUESTS, SHARE_REQUESTS, type Asker, type LocalWindows, type WindowSurface, type BackendNotice, type GatewayEvents, type GatewayPort, type ModelsPort, type RemoteAppPolicy, type RemoteClient, type RemoteRole, type RemoteTransport, type TabFrame } from './core/api.js'
import { ServiceUnavailableError } from './core/serviceHost.js'
@@ -620,9 +621,11 @@ export class BackendSocket {
return this.remoteAppPolicy ? this.remoteAppPolicy.event(frame) : frame
}
+ /** Apps away from this desk get transcript events slim (lib/slimForRelay.ts), cut before the frame crosses to the
+ * gateway's process: no tool output, thinking text or image goes up the relay. The windows here got the whole event. */
private toRemoteApps(given: Frame): void {
if (this.thisComputerOnly) return
- const frame = this.forApps(given)
+ const frame = this.forApps(slimForRelay(given))
if (!frame) return
const guest = this.frameGuest(frame)
this.toGateway('web', (gateway) => gateway.broadcast(frame, guest ?? undefined))
diff --git a/cli/src/core/turns/heartbeats.spec.ts b/cli/src/core/turns/heartbeats.spec.ts
index ad8753f7e..f00e96286 100644
--- a/cli/src/core/turns/heartbeats.spec.ts
+++ b/cli/src/core/turns/heartbeats.spec.ts
@@ -45,13 +45,50 @@ describe('turn heartbeats', () => {
expect(deps.turnActivity.check).not.toHaveBeenCalled()
await vi.advanceTimersByTimeAsync(1)
expect(deps.turnActivity.check).toHaveBeenCalledWith('s1')
- expect(sentTypes(deps)).toEqual(['agent_activity', 'turn_heartbeat'])
+ expect(sentTypes(deps)).toEqual(['turn_heartbeat'])
set({ activity: { state: 'idle' } as ActivityFrame })
await vi.advanceTimersByTimeAsync(5_000)
- expect(sentTypes(deps)).toEqual(['agent_activity', 'turn_heartbeat', 'agent_activity'])
+ expect(sentTypes(deps)).toEqual(['turn_heartbeat', 'agent_activity'])
set({ activity: undefined })
await vi.advanceTimersByTimeAsync(5_000)
- expect(sentTypes(deps)).toHaveLength(3)
+ expect(sentTypes(deps)).toHaveLength(2)
+ beats.stopHeartbeat('s1')
+ })
+
+ it('sends only turn_heartbeat, with its activity, while working', async () => {
+ const { deps, beats, set } = setup()
+ set({ activity: { state: 'working', epoch: 'e', revision: 1, validForMs: 30_000 } })
+ beats.startHeartbeat('s1')
+ await vi.advanceTimersByTimeAsync(15_000)
+ expect(sentTypes(deps)).toEqual(['turn_heartbeat', 'turn_heartbeat', 'turn_heartbeat'])
+ expect(vi.mocked(deps.clients.send).mock.calls[0]![0]).toMatchObject({ payload: { activity: { state: 'working' } } })
+ beats.stopHeartbeat('s1')
+ })
+
+ it('sends an idle activity once while it waits, however often a probe renews it, and again when it changes or restarts', async () => {
+ const { deps, beats, set } = setup()
+ // Every probe of an idle open turn moves the revision (TurnActivity.check): nothing new for the apps.
+ let revision = 1
+ vi.mocked(deps.turnActivity.snapshot).mockImplementation(() => ({ state: 'idle', epoch: 'e', revision: ++revision, validForMs: 0 }))
+ beats.startHeartbeat('s1')
+ await vi.advanceTimersByTimeAsync(600_000)
+ expect(sentTypes(deps)).toEqual(['agent_activity'])
+ vi.mocked(deps.turnActivity.snapshot).mockImplementation(() => ({ state: 'working', epoch: 'e', revision: ++revision, validForMs: 30_000 }))
+ await vi.advanceTimersByTimeAsync(5_000)
+ vi.mocked(deps.turnActivity.snapshot).mockImplementation(() => ({ state: 'idle', epoch: 'e', revision: ++revision, validForMs: 0 }))
+ await vi.advanceTimersByTimeAsync(10_000)
+ expect(sentTypes(deps)).toEqual(['agent_activity', 'turn_heartbeat', 'agent_activity'])
+ vi.mocked(deps.turnActivity.snapshot).mockImplementation(() => ({ state: 'unknown', epoch: 'e', revision: ++revision, validForMs: 0 }))
+ await vi.advanceTimersByTimeAsync(5_000)
+ // A daemon restart starts a new epoch: the apps hear it.
+ vi.mocked(deps.turnActivity.snapshot).mockImplementation(() => ({ state: 'unknown', epoch: 'e2', revision: 1, validForMs: 0 }))
+ await vi.advanceTimersByTimeAsync(5_000)
+ expect(sentTypes(deps).slice(3)).toEqual(['agent_activity', 'agent_activity'])
+ beats.stopHeartbeat('s1')
+ beats.startHeartbeat('s1')
+ await vi.advanceTimersByTimeAsync(5_000)
+ expect(sentTypes(deps)).toHaveLength(6)
+ expect(sentTypes(deps).at(-1)).toBe('agent_activity')
beats.stopHeartbeat('s1')
})
diff --git a/cli/src/core/turns/heartbeats.ts b/cli/src/core/turns/heartbeats.ts
index 67059ecaf..ab32ab3bf 100644
--- a/cli/src/core/turns/heartbeats.ts
+++ b/cli/src/core/turns/heartbeats.ts
@@ -1,7 +1,7 @@
/**
* Turn heartbeats: while a turn is open, every few seconds, check what the agent is really doing, tell
- * the app (activity, and a heartbeat while working) and keep the dial's card alive; stop once the turn
- * is closed and the dial no longer needs it.
+ * the app (a heartbeat while working, else its activity when it changed) and keep the dial's card alive;
+ * stop once the turn is closed and the dial no longer needs it.
*
* Moved verbatim out of `runForeground` (the core boundary, step 7: docs/design/2026-10-03-harnessd.md).
*/
@@ -29,8 +29,14 @@ export function createHeartbeats({ bySession, sessionTurnOpen, agentIdFor, runti
const TURN_HEARTBEAT_MS = 5000
const heartbeats = new Map<string, NodeJS.Timeout>()
const turnStartedAt = new Map<string, number>()
+ // One frame a beat. One Desktop's day (2026-10-30) had 32,819 agent_activity and 28,411 turn_heartbeat, the same
+ // activity twice while working, and an idle or waiting session's every 5 s. Working goes as turn_heartbeat alone (the
+ // phone reads only it; every app reads `activity` from it). Anything else goes as agent_activity when it changed since
+ // the last one sent: by state and epoch, not revision, which every probe of an idle open turn moves with nothing new.
+ const lastSent = new Map<string, string>()
const stopHeartbeat = (sessionId: string): void => {
runtimeActivity.forget(sessionId)
+ lastSent.delete(sessionId)
const timer = heartbeats.get(sessionId)
if (timer) { clearInterval(timer); heartbeats.delete(sessionId) }
}
@@ -44,8 +50,10 @@ export function createHeartbeats({ bySession, sessionTurnOpen, agentIdFor, runti
if (!heartbeats.has(sessionId)) return
const activity = turnActivity.snapshot(sessionId)
if (activity) {
- clients.send(correlateAgentEvent({ type: 'agent_activity', payload: { activity } }, sessionId, agentIdFor(sessionId)))
+ const said = `${activity.state}:${activity.epoch}`
if (activity.state === 'working') clients.send(turnHeartbeatFrame(sessionId, agentIdFor(sessionId), activity))
+ else if (lastSent.get(sessionId) !== said) clients.send(correlateAgentEvent({ type: 'agent_activity', payload: { activity } }, sessionId, agentIdFor(sessionId)))
+ lastSent.set(sessionId, said)
}
const deviceBusy = mirror.heartbeat(sessionId)
if (!sessionTurnOpen(sessionId) && !deviceBusy) stopHeartbeat(sessionId)
diff --git a/cli/src/gateway/gateway.spec.ts b/cli/src/gateway/gateway.spec.ts
index 544727a98..24733c1c0 100644
--- a/cli/src/gateway/gateway.spec.ts
+++ b/cli/src/gateway/gateway.spec.ts
@@ -191,6 +191,68 @@ describe('sealing, guarded', () => {
})
})
+// Change 5 of docs/plans/2026-10-31-live-events-relay-design.md: events only the terminal app reads go to the relay only
+// while a terminal app of the account is open, once the backend has said whether one is.
+describe('events only a terminal app reads', () => {
+ const events = ['tool_end', 'subagent_finished', 'done', 'context_compact', 'tool_start', 'text_delta', 'thinking_delta', 'thinking_title', 'turn_ended']
+ const others = ['tool_start', 'text_delta', 'thinking_delta', 'thinking_title', 'turn_ended']
+ const setup = () => {
+ const socket = relaySocket(MACHINE), gateway = gatewayOf(socket)
+ const queue = upstreamOf(socket).queue
+ const relayed = () => {
+ queue.length = 0
+ for (const type of events) gateway.broadcast({ type, agentId: 'a1', payload: {} })
+ return queue.map(item => (item.msg as { frame: { type: string } }).frame.type)
+ }
+ return { socket, gateway, relayed }
+ }
+ afterEach(() => vi.useRealTimers())
+
+ it('relays them only while a terminal app is open, once the backend has said, and again everything after the link drops', async () => {
+ vi.useFakeTimers()
+ const { socket, gateway, relayed } = setup()
+ expect(relayed()).toEqual(events)
+ await dispatchDown(socket, { type: '__tui_open', payload: { forMs: 0 } }, '')
+ expect(relayed()).toEqual(others)
+ await dispatchDown(socket, { type: '__tui_open', payload: { forMs: 180_000 } }, '')
+ expect(relayed()).toEqual(events)
+ await vi.advanceTimersByTimeAsync(180_001)
+ expect(relayed()).toEqual(others)
+ ;(gateway as unknown as { linkGone(): void }).linkGone()
+ expect(relayed()).toEqual(events)
+ })
+
+ it('ignores the word from a window on this computer, reads a bad span as 0 and caps a long one at 180 s', async () => {
+ vi.useFakeTimers()
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+ const { socket, relayed } = setup()
+ socket.registerLocalClient('local:tool', { sendFrame: () => true, sendBinary: () => true })
+ await dispatchDown(socket, { type: '__tui_open', payload: { forMs: 0 } }, 'local:tool', 'local')
+ expect(relayed()).toEqual(events)
+ for (const forMs of [-5, 'x', Number.NaN]) {
+ await dispatchDown(socket, { type: '__tui_open', payload: { forMs } }, '')
+ expect(relayed(), String(forMs)).toEqual(others)
+ }
+ await dispatchDown(socket, { type: '__tui_open', payload: { forMs: 10 * 86_400_000 } }, '')
+ await vi.advanceTimersByTimeAsync(180_001)
+ expect(relayed()).toEqual(others)
+ warn.mockRestore()
+ await socket.unregisterLocalClient('local:tool')
+ })
+
+ it('always sends a guest its sealed copy, held or not', async () => {
+ const { socket, gateway } = setup()
+ const e2ee = (gateway as unknown as { e2ee: { guestSessions(g: string): string[]; wrapFor(c: string, f: unknown): unknown } }).e2ee
+ vi.spyOn(e2ee, 'guestSessions').mockReturnValue(['guest-conn'])
+ vi.spyOn(e2ee, 'wrapFor').mockReturnValue({ type: 'tool_end', payload: { __e2e: 'sealed' } })
+ await dispatchDown(socket, { type: '__tui_open', payload: { forMs: 0 } }, '')
+ const queue = upstreamOf(socket).queue
+ queue.length = 0
+ gateway.broadcast({ type: 'tool_end', agentId: 'a1', payload: {} }, '[email protected]')
+ expect(queue.map(item => (item.msg as { targetConnId?: string }).targetConnId)).toEqual(['guest-conn'])
+ })
+})
+
describe('the trust edges the split made visible', () => {
it('a process on this computer cannot send the backend hub\'s own frames: it once could set how many devices watch', async () => {
const socket = relaySocket(MACHINE)
diff --git a/cli/src/gateway/gateway.ts b/cli/src/gateway/gateway.ts
index d595225c1..d5ddc23a5 100644
--- a/cli/src/gateway/gateway.ts
+++ b/cli/src/gateway/gateway.ts
@@ -50,6 +50,14 @@ export interface RelayGatewayOptions {
core: GatewayEvents
}
+/** Transcript events only the terminal app (`harness tui`, Harness OS) reads in full. Desktop, the web and the phone take
+ * them only as "the model is working" or to clear a preview line, which the next text, tool or turn end does too; so while
+ * the account has no terminal app open they stay off the relay (one Desktop's day, 2026-10-30: about 12,700 of its
+ * 170,666 frames). Thinking stays: Desktop's "Starting up…" chip for a resting grid model ends on it. */
+export const TUI_ONLY_EVENTS: ReadonlySet<string> = new Set(['tool_end', 'subagent_finished', 'done', 'context_compact'])
+/** The longest the backend's word that a terminal app is open is taken for (backend bus.ts TUI_OPEN_FOR_MS). */
+export const TUI_OPEN_MAX_MS = 180_000
+
export class RelayGateway implements GatewayPort {
/** Optional scalar-only measurement hooks. Never hand a frame or user payload to the collector. */
productUsage?: {
@@ -92,6 +100,9 @@ export class RelayGateway implements GatewayPort {
private readonly liveStreams = new Map<string, Set<string>>()
/** Cross-instance commander (device) client count, from backend `__clients` frames. */
private commanderCount = 0
+ /** Until when a terminal app of the account counts as open, from the backend's `__tui_open`; null until it has said
+ * (an older backend, a team account, the link not yet back), when every event is relayed as before. */
+ private tuiUntil: number | null = null
/** Subset of commanderCount whose device is ACTIVELY rendering this machine (multi-attach). null = the
* backend doesn't send the signal (old build). */
private commanderActive: number | null = null
@@ -223,6 +234,7 @@ export class RelayGateway implements GatewayPort {
this.routeCounters.clear()
this.staleRouteLogged.clear()
this.replayCommanderOnNextSnapshot = true
+ this.tuiUntil = null
}
/** The ONE place commander presence changes. Both callers — the `__clients` snapshot and the link going
@@ -295,7 +307,7 @@ export class RelayGateway implements GatewayPort {
} catch { /* Work continues without metrics. */ }
}
if (this.link.servesThisComputerOnly()) return
- this.link.enqueue({ t: 'up', frame: this.e2ee.wrapUp(frame) })
+ if (!this.heldForNoTerminalApp(frame.type)) this.link.enqueue({ t: 'up', frame: this.e2ee.wrapUp(frame) })
if (guest) {
for (const connId of this.e2ee.guestSessions(guest)) {
const sealed = this.e2ee.wrapFor(connId, frame)
@@ -304,6 +316,12 @@ export class RelayGateway implements GatewayPort {
}
}
+ /** Whether [type] is an event only a terminal app reads and the account has none open now, once the backend has said
+ * (docs/plans/2026-10-31-live-events-relay-design.md, change 5). A guest's own sealed copy is never held. */
+ private heldForNoTerminalApp(type: unknown): boolean {
+ return this.tuiUntil !== null && Date.now() >= this.tuiUntil && typeof type === 'string' && TUI_ONLY_EVENTS.has(type)
+ }
+
/** The guest a remote connection's session is (gateway/sharedTrust.ts), '' when its store did not
* record the account; undefined for everyone else. */
private guestOf(connId: string): string | undefined {
@@ -638,6 +656,12 @@ export class RelayGateway implements GatewayPort {
}
return
}
+ // A terminal app of the account is open for `forMs` (backend bus.ts noteTuiPresence), or none is (0).
+ if (type === '__tui_open') {
+ const forMs = Number((frame.payload as { forMs?: unknown } | undefined)?.forMs)
+ this.tuiUntil = Date.now() + (Number.isFinite(forMs) && forMs > 0 ? Math.min(forMs, TUI_OPEN_MAX_MS) : 0)
+ return
+ }
if (type === '__client_disconnected') {
// The backend is authoritative for the outer connId. Drop both kinds of
// connection-scoped state immediately; otherwise a dead Desktop keeps a
diff --git a/cli/src/lib/slimForRelay.spec.ts b/cli/src/lib/slimForRelay.spec.ts
new file mode 100644
index 000000000..68a237ed0
--- /dev/null
+++ b/cli/src/lib/slimForRelay.spec.ts
@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest'
+import { slimForRelay } from './slimForRelay.js'
+
+const activity = { state: 'working', epoch: 'e', revision: 4, validForMs: 30_000 }
+/** A transcript event as the core sends it: its envelope, and a payload carrying the ids every app reads. */
+const event = (type: string, payload: Record<string, unknown>, envelope: Record<string, unknown> = {}) => ({
+ type, agentId: 'a1', dbSessionId: 's1', replay: false, ...envelope,
+ payload: { ...payload, activity, agentId: 'a1', sessionId: 's1', replay: false },
+})
+const ids = { activity, agentId: 'a1', sessionId: 's1', replay: false }
+
+describe('slimForRelay', () => {
+ it('keeps turn_started and turn_ended whole, and any frame that is not a transcript event', () => {
+ for (const frame of [event('turn_started', { userMessage: 'Fix it' }), event('turn_ended', { aborted: true }),
+ { type: 'agent_synced', payload: { agent: { id: 'a1' } } }, { type: 'turn_heartbeat', payload: { activity } }]) {
+ expect(slimForRelay(frame)).toBe(frame)
+ }
+ })
+
+ it('keeps what each event\'s readers read, and the ids, activity and replay of every one', () => {
+ const cases: Array<[string, Record<string, unknown>, Record<string, unknown>]> = [
+ ['user_message', { content: 'Look', images: [{ media_type: 'image/png', data: 'x'.repeat(10_000) }] }, { content: 'Look' }],
+ ['text_delta', { content: 'Done.' }, { content: 'Done.' }],
+ ['thinking_delta', { content: 'private thoughts', thinkingId: 't1' }, {}],
+ ['thinking_title', { title: 'Planning', thinkingId: 't1', extra: 1 }, { title: 'Planning', thinkingId: 't1' }],
+ ['tool_end', { id: 'u1', tool: 'Bash', output: 'secret output', outputTail: 'tail', isError: false, summary: 'ok', parentToolUseId: 'p1',
+ subagent: { totalTokens: 9 }, durationSeconds: 3 }, { id: 'u1', tool: 'Bash', parentToolUseId: 'p1', isError: false }],
+ ['subagent_finished', { id: 'u2', status: 'completed', summary: 'what the sub-agent said' }, { id: 'u2', status: 'completed' }],
+ ['done', { result: 'r'.repeat(600) }, { result: 'r'.repeat(500) }],
+ ['context_compact', { message: 'Compacted 40k tokens', trigger: 'auto' }, {}],
+ ]
+ for (const [type, payload, kept] of cases) {
+ expect(slimForRelay(event(type, payload)), type).toEqual({ type, agentId: 'a1', dbSessionId: 's1', replay: false, payload: { ...kept, ...ids } })
+ }
+ })
+
+ it('bounds a tool\'s input: strings to 200 characters, lists to 50 items, objects to 50 keys and nesting to 4 levels', () => {
+ const deep = { a: { b: { c: { d: 'gone' }, kept: 'yes' } } }
+ const slim = slimForRelay(event('tool_start', { id: 'u1', tool: 'Grep', parentToolUseId: 'p1',
+ input: { pattern: 'p'.repeat(300), paths: Array.from({ length: 80 }, (_, i) => `f${i}`), deep, n: 3, ok: true, none: null,
+ wide: Object.fromEntries(Array.from({ length: 70 }, (_, i) => [`k${i}`, i])) } }))
+ const input = (slim.payload as { input: Record<string, unknown> }).input
+ expect(input.pattern).toBe('p'.repeat(200))
+ expect(input.paths).toEqual(Array.from({ length: 50 }, (_, i) => `f${i}`))
+ expect(input.deep).toEqual({ a: { b: { kept: 'yes' } } })
+ expect([input.n, input.ok, input.none]).toEqual([3, true, null])
+ expect(Object.keys(input.wide as object)).toHaveLength(50)
+ expect(slim.payload).toMatchObject({ id: 'u1', tool: 'Grep', parentToolUseId: 'p1', ...ids })
+ })
+
+ it('sends a 2 MB Write in under 2 KB, keeps a TodoWrite\'s list whole, and never cuts a character in half', () => {
+ const write = slimForRelay(event('tool_start', { id: 'u1', tool: 'Write', input: { file_path: '/repo/big.txt', content: 'x'.repeat(2 * 1024 * 1024) } }))
+ expect(JSON.stringify(write).length).toBeLessThan(2_048)
+ expect((write.payload as { input: { file_path: string } }).input.file_path).toBe('/repo/big.txt')
+ const todos = Array.from({ length: 10 }, (_, i) => ({ content: `Step ${i}`, status: i < 3 ? 'completed' : 'pending', activeForm: `Doing step ${i}` }))
+ expect((slimForRelay(event('tool_start', { id: 'u2', tool: 'TodoWrite', input: { todos } })).payload as { input: unknown }).input).toEqual({ todos })
+ const emoji = `${'a'.repeat(199)}😀tail`
+ expect((slimForRelay(event('tool_start', { id: 'u3', tool: 'Bash', input: { command: emoji } })).payload as { input: { command: string } }).input.command)
+ .toBe('a'.repeat(199))
+ })
+
+ it('keeps the end of a long path, where its file name is', () => {
+ const path = `/Users/dev/${'deep/'.repeat(60)}src/handler.ts`
+ const input = (slimForRelay(event('tool_start', { id: 'u1', tool: 'Edit', input: { file_path: path, notebook_path: path, path, old_string: path } }))
+ .payload as { input: Record<string, string> }).input
+ for (const key of ['file_path', 'notebook_path', 'path']) expect(input[key], key).toBe(path.slice(-200))
+ expect(input.old_string).toBe(path.slice(0, 200))
+ })
+
+ it('passes on a frame whose type is a name every object has', () => {
+ for (const type of ['constructor', 'toString', '__proto__', 'hasOwnProperty']) {
+ const frame = { type, payload: { agentId: 'a1' } }
+ expect(slimForRelay(frame)).toBe(frame)
+ }
+ })
+
+ it('keeps a tool input that is not an object as it is, bounded', () => {
+ expect((slimForRelay(event('tool_start', { id: 'u1', tool: 'Raw', input: 'z'.repeat(500) })).payload as { input: unknown }).input).toBe('z'.repeat(200))
+ expect(slimForRelay(event('tool_start', { id: 'u1', tool: 'None' })).payload).toEqual({ id: 'u1', tool: 'None', ...ids })
+ })
+
+ it('never touches the envelope, never changes what it was given, and passes a frame without a payload on', () => {
+ const given = event('tool_end', { id: 'u1', tool: 'Bash', output: 'out', isError: true, summary: 's' }, { subagent: 'u0', replay: true })
+ const copy = structuredClone(given)
+ const slim = slimForRelay(given)
+ expect(given).toEqual(copy)
+ expect({ ...slim, payload: undefined }).toEqual({ ...given, payload: undefined })
+ const bare = { type: 'text_delta' }
+ expect(slimForRelay(bare)).toBe(bare)
+ })
+})
diff --git a/cli/src/lib/slimForRelay.ts b/cli/src/lib/slimForRelay.ts
new file mode 100644
index 000000000..b2cdf4663
--- /dev/null
+++ b/cli/src/lib/slimForRelay.ts
@@ -0,0 +1,87 @@
+/**
+ * Transcript events as apps away from this computer get them: what their readers read, and nothing the engine wrote
+ * for itself (docs/plans/2026-10-31-live-events-relay-design.md, change 4).
+ *
+ * A transcript event carries a tool's whole input, its output's head, thinking text and pasted images, and every one
+ * crossed the relay: the backend parses it, publishes it to Redis and writes it again to each socket, and the phone,
+ * the browser and the terminal app read little of it (one Desktop's day of 2026-10-30: about 31,900 such frames,
+ * 19% of all it received). No app away from here reads `tool_end.output`, `.summary`, `.subagent`,
+ * `.durationSeconds`, `thinking_delta.content`, `context_compact`, `subagent_finished.summary` or
+ * `user_message.images`. A tool's input stays, bounded: the terminal app draws a plan, a command, a path or a query
+ * from it. `subagent_finished` is not sealed (lib/e2ee/core.ts, pinned with other repositories' clients), so its
+ * summary, a sub-agent's own words, no longer crosses in the clear.
+ *
+ * Only the remote path uses it (backendSocket.ts `toRemoteApps`): windows on this computer and everything inside the
+ * daemon keep the full event. Pure; never changes what it is given.
+ */
+type Frame = Record<string, unknown>
+
+/** In every payload: what every app reads to place an event (its agent, its session, a replayed history) and the
+ * activity it shows. */
+const ALWAYS = ['activity', 'agentId', 'sessionId', 'replay'] as const
+
+/** The payload fields each transcript event keeps. An event not listed (turn_started, turn_ended, everything else)
+ * goes whole. */
+const KEEP: Record<string, readonly string[]> = {
+ user_message: ['content'],
+ text_delta: ['content'],
+ thinking_delta: [],
+ thinking_title: ['title', 'thinkingId'],
+ tool_start: ['id', 'tool', 'parentToolUseId', 'input'],
+ tool_end: ['id', 'tool', 'parentToolUseId', 'isError'],
+ subagent_finished: ['id', 'status'],
+ done: ['result'],
+ context_compact: [],
+}
+
+/** A tool input's bounds: a 2 MB Write goes as a path and 200 characters. */
+const INPUT_STRING = 200
+const INPUT_ITEMS = 50
+const INPUT_DEPTH = 4
+const DONE_RESULT = 500
+
+/** `text` cut to `max` UTF-16 units, never between the two halves of a character. */
+function cut(text: string, max: number): string {
+ if (text.length <= max) return text
+ const end = /[\uD800-\uDBFF]/.test(text[max - 1]!) ? max - 1 : max
+ return text.slice(0, end)
+}
+
+/** The last `max` UTF-16 units of `text`, never starting inside a character. */
+function tail(text: string, max: number): string {
+ if (text.length <= max) return text
+ const start = text.length - max
+ return text.slice(/[\uDC00-\uDFFF]/.test(text[start]!) ? start + 1 : start)
+}
+
+/** A path keeps its end: the file name is what the terminal app shows ("Editing handler.ts"), and a deep
+ * worktree or node_modules path is longer than 200 characters. */
+const PATH_KEY = /path$/i
+
+/** A tool input within its bounds: strings cut, lists and objects to their first 50 entries, and nothing nested past
+ * four levels (`input` itself is the first). */
+function bounded(value: unknown, depth = 1, key = ''): unknown {
+ if (typeof value === 'string') return PATH_KEY.test(key) ? tail(value, INPUT_STRING) : cut(value, INPUT_STRING)
+ if (value === null || typeof value !== 'object') return value
+ if (depth > INPUT_DEPTH) return undefined
+ if (Array.isArray(value)) return value.slice(0, INPUT_ITEMS).map((item) => bounded(item, depth + 1)).filter((item) => item !== undefined)
+ const kept: Record<string, unknown> = {}
+ for (const [key, item] of Object.entries(value).slice(0, INPUT_ITEMS)) {
+ const inner = bounded(item, depth + 1, key)
+ if (inner !== undefined) kept[key] = inner
+ }
+ return kept
+}
+
+export function slimForRelay(frame: Frame): Frame {
+ // Own keys only: a frame typed `constructor` must not read Object.prototype's (a throw here reaches the event funnel).
+ const keep = typeof frame.type === 'string' && Object.hasOwn(KEEP, frame.type) ? KEEP[frame.type] : undefined
+ const payload = frame.payload
+ if (!keep || !payload || typeof payload !== 'object' || Array.isArray(payload)) return frame
+ const given = payload as Record<string, unknown>
+ const slim: Record<string, unknown> = {}
+ for (const key of [...keep, ...ALWAYS]) if (key in given) slim[key] = given[key]
+ if ('input' in slim) slim.input = bounded(slim.input)
+ if (frame.type === 'done' && typeof slim.result === 'string') slim.result = cut(slim.result, DONE_RESULT)
+ return { ...frame, payload: slim }
+}
diff --git a/docs/plans/2026-10-31-live-events-relay-design.md b/docs/plans/2026-10-31-live-events-relay-design.md
new file mode 100644
index 000000000..feb13a715
--- /dev/null
+++ b/docs/plans/2026-10-31-live-events-relay-design.md
@@ -0,0 +1,310 @@
+# Fewer frames between daemons, backend and apps
+
+Status: design, 2026-10-31. Requested by Ken.
+
+> **Status after the builder check (2026-10-31):** changes 2 (heartbeats) and 4 (slim transcript events) stand and
+> are built on branch `fewer-relay-frames` (2026-10-31; not released). Changes 1 (`swarm_changed`) and 3 (`agent_synced`) are **on hold** for the reasons in "On hold" below;
+> change 1 needs its own design with a client change, which Ken has not yet decided on. Change 5 (TUI-only events not
+> sent while no terminal app is open) was added on 2026-10-31 at Ken's request and is built on the same branch
+> (backend f90a30727, CLI d8a2b1d0f; not released). Release order: backend first, then the CLI.
+
+## Why
+
+Every frame a daemon sends its apps away from the computer crosses the backend: the daemon's link is
+`/api/adapter-ws` (`backend/src/lib/adapterWs.ts`, `env.t === 'up'`), which parses it, runs its taps and PUBLISHes it
+to Redis on `up:{machineId}` (`bus.ts` `publishUp`); the instances with clients for the machine stringify it again for
+each socket (`hub.ts` `deliverUpLocal`). The backend's own pushes to apps (`swarm_changed`) go out on every socket of
+every member. Fewer and smaller frames is less backend CPU, Redis traffic, sealing on the daemon and work on the
+apps' UI threads.
+
+## What was measured (before)
+
+Ken's Desktop log for 2026-10-30 (`~/.harness/logs/app-20261030.log`, 75 MB): every frame the app received in a day,
+from this computer's daemon and, through the relay, from the account's other machines. Desktop was open about 22 of
+the 24 hours. Values in the log are cut, so byte counts understate tool payloads.
+
+| Frame | Per day | Share |
+|---|---|---|
+| `swarm_changed` | 54,282 | 31.8% |
+| `agent_activity` | 32,819 | 19.2% |
+| `turn_heartbeat` | 28,411 | 16.6% |
+| `agent_synced` | 17,099 | 10.0% (about 44% of the logged bytes) |
+| transcript events (`tool_start`, `tool_end`, `text_delta`, `thinking_*`, `subagent_finished`, `context_compact`) | about 31,900 | about 19% |
+| `turn_started`, `turn_ended`, `turn_summary` | about 3,800 | 2% |
+| all frames | 170,666 | |
+
+Findings behind each change:
+
+- **`swarm_changed`**: all 54k are for one Swarm (openharness), one about every second (median gap 1.07 s), at the
+ backend's cap of one push per Swarm a second (`backend/src/lib/swarmClientPushes.ts` `COALESCE_MS`). Their source is
+ each machine's reading every 15 s (`cli/src/superTabs/machines.ts` `MACHINE_HEARTBEAT_MS`): each is a Swarm write
+ that pushes `parts: ['machine']` to every socket of every member (`backend/src/superTabs/store.ts` ~2503); ten
+ machines make about 57,600 a day. Desktop reads a Swarm at most once per its read gap (3 s) and makes a machine-only
+ change wait for that tick anyway (`desktop/lib/super_tabs/controller.dart` `told`), so pushes faster than that buy
+ it nothing.
+- **Heartbeats**: while a turn is open, every 5 s, the daemon sends `agent_activity` and, while working, also
+ `turn_heartbeat`, both carrying the same `activity` (`cli/src/core/turns/heartbeats.ts`). Desktop and the terminal
+ app read `activity` from any frame that has it (`app_state.dart`, `tui/src/app.rs` `on_frame`); the phone reads only
+ `turn_heartbeat` and ignores `agent_activity` (`mobile/lib/state/app_state.dart`). An idle or waiting session sends
+ the same `agent_activity` every 5 s.
+- **`agent_synced`**: the daemon sends the whole agent (1-2 KB) whenever anything touches the registry
+ (`cli/src/lib/sessionSync.ts`, 13 callers), with no check that anything changed. Of 17,099: 680 first sends, 4,239
+ identical to the previous one for that agent, 181 that differ only in `activity`, 11,999 with another change
+ (mostly `updatedAt`, which the phone sorts agents by: `mobile/lib/phone/agent_index.dart`).
+- **Transcript events** carry what the engine wrote (a tool's whole input, its output's head, thinking text, pasted
+ images) to apps that read little of it:
+
+| Client | Reads |
+|---|---|
+| Desktop and web (`app_state.dart`, `session_preview.dart`) | the event type, `turn_started.userMessage`, `user_message.content`, `text_delta.content`, the tool's name, `turn_ended.aborted` |
+| Phone (`state/session_preview.dart`, `state/app_state.dart`, `notify/done_notice.dart`) | the same preview fields; `turn_started`, `turn_heartbeat`, `turn_ended`; `aborted` and the envelope's `subagent`/`replay` |
+| Terminal app (`tui/src/app.rs` ~1705-1853), over the relay too | the above, plus `tool_start.id`, `.parentToolUseId`, `.input` (`todos`, `description`, `command`, `file_path`/`path`/`notebook_path`, `pattern`, `query`, `url`), `tool_end.id`, `thinking_title.title`, `done.result` |
+| Every client | `payload.agentId`, `payload.sessionId`, `payload.replay`, `payload.activity` |
+| Backend | the envelope of `turn_started` (`agentId`, `replay`) for the daily turn count |
+
+ No client reads `tool_end.output`, `.summary`, `.subagent`, `.durationSeconds`, `thinking_delta.content`,
+ `context_compact`, `subagent_finished.summary` or `user_message.images`.
+
+Not pursued: holding transcript events back while no remote app is attached. Desktop dials every machine of the
+account (`desktop/lib/state/app_state.dart` ~9899), as the terminal app does when it runs, so on Ken's machines someone
+is attached about 22 hours a day (his Desktop); and those events are about 19% of frames. Sending events only for the agent a
+client is looking at would need every client changed, for at most that 19%.
+
+## The changes
+
+### 1. `swarm_changed`: a machine's reading pushed at most every 30 s (backend)
+
+Where the server publishes a commit to its people (`announceSwarmChanges`, `backend/src/lib/swarmClientPushes.ts`,
+design call: there it also saves the Redis PUBLISH per person, not only the socket frame), a change whose parts are
+only `machine` goes at once if none went for that Swarm in the last `MACHINE_COALESCE_MS = 30_000`, else waits, merged
+with any others, until that window ends. A change with `main` keeps today's rule (the first at once, the next within
+`COALESCE_MS = 1_000` merged) and carries any held machine part with it, so nothing is told twice. The per-socket
+coalescing in `relaySwarmChanges` and the repeat that keeps apps on pushes (`PUSHES_REPEAT_MS`) are unchanged.
+
+Effect: from about 54,000 to at most about 2,880 machine pushes a day per socket for a Swarm of any size, plus its
+`main` changes. A machine card (CPU, slots, quota) on Desktop, web or phone is at most 30 s behind, against readings
+taken every 15 s.
+
+### 2. Heartbeats: one per beat, and an unchanged activity not repeated (CLI)
+
+In `createHeartbeats` (`cli/src/core/turns/heartbeats.ts`), each beat sends one frame:
+
+- working: `turn_heartbeat` carrying `activity` (every client keeps working from it; the phone needs this one);
+- not working (`idle` or `unknown`, the only other states, `cli/src/lib/turnActivity.ts`, while the turn is still
+ open or the device still needs the beat): `agent_activity`, only when the activity differs from the last one sent
+ for that session, a working one included (by `state` and `epoch`; `validForMs` ignored). Not by `revision`: every
+ probe of an idle open turn sets it again (`TurnActivity.check`), so it moves each beat with nothing new; and that
+ move is what keeps a stale probe from overwriting a newer state, so it stays. The last sent is forgotten with the
+ heartbeat (`stopHeartbeat`).
+
+Effect: about 30,000 fewer frames a day on the measured account.
+
+### 3. `agent_synced`: not sent when nothing but activity changed (CLI)
+
+In `createSessionSync` (`cli/src/lib/sessionSync.ts`), the daemon remembers, per agent, the last agent frame it sent
+to the apps, without `activity`. A frame equal to it is not sent to the apps (`deps.send`). The dial's copy
+(`deps.sendCommander`) is unchanged. No reset is needed (design call): an app that connects, or reconnects after the
+relay dropped, lists agents itself (`agents_list`); a connected app missed nothing, since a frame is delivered or its
+connection ends; and an agent created again has a new `createdAt`, so it never equals the old one. The memory forgets
+an agent on the unavailable path it already has, and keeps at most 2,000 agents (oldest first).
+
+Effect: about 4,400 fewer frames a day, among the largest frames there are.
+
+### 4. Transcript events: a slim frame for apps away from the computer (CLI)
+
+On the remote path only (`cli/src/backendSocket.ts` `toRemoteApps`, before the frame crosses to the gateway's
+process), a pure `slimForRelay(frame)` (in `cli/src/lib/slimForRelay.ts`: the core's process may not import
+`gateway/`, `cli/src/architecture.spec.ts`) keeps:
+
+| Event | Payload kept |
+|---|---|
+| `turn_started`, `turn_ended` | everything |
+| `user_message` | `content`; `images` dropped |
+| `text_delta` | `content` |
+| `thinking_delta` | nothing |
+| `thinking_title` | `title`, `thinkingId` |
+| `tool_start` | `id`, `tool`, `parentToolUseId`, `input` with every string value cut to 200 characters, arrays and objects to 50 entries, depth to 4 |
+| `tool_end` | `id`, `tool`, `parentToolUseId`, `isError` |
+| `subagent_finished` | `id`, `status` |
+| `done` | `result` cut to 500 characters |
+| `context_compact` | nothing |
+
+Every one keeps `activity`, `agentId`, `sessionId` and `replay` in its payload; the envelope (`type`, `agentId`,
+`dbSessionId`, `replay`, `subagent`) is never touched. Windows on this computer and everything inside the daemon (the
+dial's cards, recaps, the Swarm, search, the orchestrator, local tool clients) keep the full event. The gateway's
+`productUsage.observe` reads only fields the slim frame keeps.
+
+Security: `subagent_finished`, `turn_heartbeat` and `agent_activity` are not in `ENCRYPTED_UP_TYPES`
+(`cli/src/lib/e2ee/core.ts`), so they cross the relay in the clear today, `subagent_finished.summary` (a sub-agent's
+own words) included. The slim frame drops the summary, so only ids and a status remain in the clear. Sealing the type
+is left out (design call): `core.ts` is pinned by hash with the browser client and the paired device in other
+repositories (`core.test.ts` "interop keystone"), and any edit to it forces those to be re-derived.
+
+### 5. Events only the terminal app reads: not sent while no terminal app is open (backend and CLI)
+
+Ken, 2026-10-31: few people install the terminal app (`harness tui`), and the goal is fewer frames, not only smaller
+ones. Desktop, web and phone use five transcript events, and only for the preview, the working state and the end of a
+turn: `turn_started`, `turn_ended`, `user_message`, `text_delta` and `tool_start` (its tool name, "running Bash").
+The others are read in full only by the terminal app (its plan, sub-agents and what an agent did); Desktop and the
+phone take them only as "the model is working" or to clear a line:
+
+| Event | Per day (2026-10-30) | Readers besides the terminal app | While no terminal app is open |
+|---|---|---|---|
+| `tool_end` | 12,113 | Desktop's and the phone's previews clear their "running X" line (`session_preview.dart`); both also clear it on the next text, tool or turn end | not sent |
+| `subagent_finished` | 628 | the event type only | not sent |
+| `done`, `context_compact` | under 100 | the event type only | not sent |
+| `thinking_delta`, `thinking_title` | 1,866 | Desktop's and the web's "Starting up…" chip for a resting grid model ends on the first answer event (`_watchModelStart`, `_modelAnswerEvents`); a reasoning model's first output is its thinking | **kept** (design call: released apps cannot change, and the chip would stay through a model's thinking) |
+
+While no terminal app of the account is open, the daemon does not hand the first three rows to the relay: about
+12,700 fewer frames a day (7.5%) at the measured day's rate, counted from Ken's Desktop log, which also holds its own
+daemon's events (those still arrive there locally); the backend's saving is on the relayed share. Windows on the same
+computer, a terminal app on it included, still get every event (the local loop in `backendSocket.ts` `send`), and
+everything inside the daemon is unchanged. Minor effect: those events are sealed, and the phone counts sealed frames
+as a machine's proof of life (`lastHeardFromMachineAt`); `text_delta` and `tool_start`, also sealed, still go.
+
+**How a daemon knows a terminal app is open (design call: pushed only while one is, so no one else pays a frame).**
+
+- A daemon with a terminal app attached sends `app_presence` with a TUI surface (`tui`, `harness-os`,
+ `harness-os-pi`: backend `dailyTracking.ts` `TUI_SURFACES`): `open` at once when one attaches, then `ping` at most
+ once a minute while it stays (`cli/src/gateway/upstream.ts` `APP_PRESENCE_UP_MS = 60_000`, checked every
+ `APP_PING_MS = 15_000`). Harness OS counts (design call): it runs the same terminal app (`hn`), watching every
+ machine of the account, and would show stale tools and plans otherwise.
+- On each such `open` or `ping` the backend refreshes a Redis key `tui_open:{userId}` (`EX 150`, two and a half
+ pings), and publishes an account push `__tui_open` `{ forMs: 180000 }` at most once a minute per account (a second
+ key `tui_open_said:{userId}` `SET NX EX 60`), and always on an `open`. It goes through the account channel every
+ daemon of the account listens on (`backend/src/lib/adapterAccountPushes.ts`, beside `desk_changed`,
+ `machines_changed`). A team socket (`opts.team`) does not get it.
+- On every daemon socket's attach, the backend also says whether one is open now: `__tui_open` `{ forMs: 180000 }` if
+ `tui_open:{userId}` exists, else `{ forMs: 0 }`. A zero still says "this server tells you", which is what turns
+ the rule on.
+- The name starts with `__` so an older daemon drops it silently (`gateway.ts` `backendControl` ignores the backend's
+ `__` frames); a plain name would be refused as plaintext and logged on every push. The newer daemon reads it in
+ `backendControl` beside `__clients`.
+- The daemon's gateway keeps `tuiUntil` (`now + forMs` on each `__tui_open`, `null` before it hears one, and `null`
+ again when the link drops). The rule applies only once one was heard: with no word (an older backend, a team
+ account, the link down and not yet re-attached) every event is sent, as today. While `now < tuiUntil` every event
+ is sent; after, the first three rows of the table are not.
+- A terminal app closed is noticed within 180 s, with no message for it; one opened is noticed at once (its `open`).
+ A daemon attaching while one is open hears it at attach.
+- A frame sealed for a guest (a shared harness, `gateway.ts` `broadcast` `guestSessions`) is always sent whole: a
+ guest's terminal app is not the owner's.
+
+Where: the gate sits in the gateway's `broadcast` after `productUsage.observe` (which reads `text_delta` and turn
+events, all kept) and before sealing, so a dropped frame costs no seal and no backend work. `slimForRelay` (change 4)
+still applies to what is sent.
+
+## On hold (builder check, 2026-10-31)
+
+**Change 1 would show machines late or offline.** Desktop and the web build judge a machine by how old its last
+reading is (now minus `observation.receivedAt`, `desktop/lib/super_tabs/machine_status.dart`): late after 20 s
+(`kSuperTabMachineLateAfter`), offline after 35 s (`kSuperTabMachineOfflineAfter`). Today a reading is at most about
+19 s old when shown (about 1 s of push batching, Desktop's 3 s read gap, a reading every 15 s). Held 30 s, it reaches
+about 48 s: dots flap between late and offline. The same 35 s decides which machines can take a Buddy
+(`buddy_machines.dart`), whether team work can launch (`launch.dart`), and `terminal_unavailable.dart`,
+`agent_mark.dart`, `message_receipt.dart` and the dimming in `machines.dart`. Released apps cannot change those
+thresholds. Any saving here needs its own design: the server judges a machine's freshness and says so, apps stop
+deriving it from read timing, and older apps keep today's pushes. The phone is unaffected either way (it ignores
+`swarm_changed` and reads the Swarm every 5 s on screen, `mobile/lib/swarm/swarm_reader.dart`).
+
+**Change 3 saves little that is safe to drop.** Most identical `agent_synced` come from the deliberate full
+republish every 5 minutes (`cli/src/core/main.ts` ~2617, `RUNTIME_RECONCILE_MS`, "safety passes"), which Desktop and the
+phone use to re-attach panes stuck on "Attaching…" (`app_state.dart` ~21850, phone ~10725), and which the phone counts
+as proof that a machine's session is alive (a sealed frame; `agent_activity` and `turn_heartbeat` are not sealed,
+`lastHeardFromMachineAt` in `mobile/lib/ws/ws_conn.dart`). The 181 activity-only frames are the ones that carry the
+corrected `idle` after a heartbeat stopped. Not every `agent_synced` goes through `createSessionSync` either
+(`core/agents/update.ts`, `core/agents/cloud.ts`, `backendSocket.ts` `publishStoppedAgent`), and the 13 callers are 7
+direct ones plus about 40 through `announceSession`.
+
+## Expected effect on the measured day
+
+| Change | Frames a day |
+|---|---|
+| 1. `swarm_changed` | on hold (about -48,000 if it can be done safely) |
+| 2. heartbeats | about -30,000 |
+| 3. `agent_synced` | on hold |
+| 4. transcript events | none fewer; smaller |
+| 5. TUI-only events while no terminal app is open | about -12,700 |
+| total with 2, 4 and 5 | about -44,700 of 170,666 (about 26%), plus smaller transcript frames |
+
+## Goals
+
+- About half the frames on the measured account, with every app showing what it shows today.
+- No live event carries tool output, thinking text or an image across the relay, and no sub-agent text crosses in the
+ clear. (A history read, `session_get`, still returns whole events, sealed, to an app that asks; no app in this
+ repository asks.)
+
+## Non-goals
+
+- Holding events back while no remote app is attached, or per-agent subscriptions (see Not pursued).
+- Changing what windows on the same computer receive.
+- The apps' own read timers.
+
+## Anti-goals
+
+- A phone or window showing an agent idle while it works, or missing a turn's end.
+- A phone's agent order going stale (`updatedAt` changes are always sent).
+- The daily turn count or the daemon's product metrics changing.
+- A dial card losing anything.
+
+## Measure after
+
+The same count from a Desktop log of a comparable day after release (the script reads `~/.harness/logs/app-*.log`,
+counting `↓` frames by type), written into this document beside the "before" table.
+
+## Results
+
+Counted with `python3 -I scripts/desktop-frame-count.py <Desktop log>` (received `↓` frames by type, the
+`swarm_changed` gap, and each `agent_synced` against the previous one for its agent).
+
+| Log | Window | Frames | `swarm_changed` | `agent_activity` | `turn_heartbeat` | `agent_synced` (identical / activity only, as logged) |
+|---|---|---|---|---|---|---|
+| Before: Ken's Desktop, 2026-10-30 (the table above) | about 22 h open | 170,666 | 54,282 | 32,819 | 28,411 | 17,099 (4,239 / 181) |
+| Before: the build Mac's Desktop, 2026-10-30 | 03:05-17:02 | 161,203 | 40,344 (median gap 1 s) | 22,670 | 18,980 | 59,467 (35,601 / 147) |
+| After | pending: a comparable day after the release | | | | | |
+
+The build Mac's Desktop had far more identical `agent_synced` (60% of them, against 25% on Ken's): worth weighing if
+change 3 is taken up again. "Identical" is as the log shows them: Desktop logs a frame's first 1,200 characters, each
+value's first 120 and a list as its length, so fields further in (`dsh`, `verdict`, `permissionMode`) are not compared
+and both counts are upper bounds.
+
+## Design
+
+- **Growth**: one held change per Swarm per socket (backend); one small object per live session and per agent
+ (daemon); all dropped with their session, agent or socket. Change 5: two Redis keys per account with a terminal
+ app open (150 s and 60 s TTL); one timestamp in each daemon.
+- **Concurrency**: the held machine part is per socket and merged into the next send; the daemon's memories are
+ per process and only decide whether to send.
+- **Read cost**: none added; each change removes work per frame.
+- **Scale**: `swarm_changed` stops growing with the number of machines in a Swarm (30 s per Swarm per socket);
+ heartbeats stop growing with idle sessions. The warning metrics are the frame counts above and backend CPU.
+- **Compatibility**: older Desktop, web, phone and terminal apps read only fields that stay (change 4), keep their
+ working state from `turn_heartbeat` and `activity` (change 2), read the Swarm on their own timers when not told
+ (change 1), and list agents themselves on connect (change 3). An older backend keeps pushing every second; an older
+ daemon keeps sending everything.
+- **Migration and rollback**: none; a rollback restores today's frames.
+- **Audience**: unchanged; `subagent_finished` no longer carries a sub-agent's words in the clear.
+- **Identity**: unchanged.
+- **Failure**: a held machine push lost with its socket is replaced by the app's own read; a heartbeat or
+ `agent_synced` skipped wrongly is corrected by the next change or the next `agents_list`.
+- **Platforms**: daemon and backend, the same everywhere.
+
+## Tests
+
+- Change 5, backend: a TUI-surface `app_presence` `open` publishes `__tui_open` at once, a `ping` at most once a minute
+ per account, never for the desktop surface; `tui_open:{userId}` lives 150 s; an attaching daemon socket hears
+ `__tui_open` with 180,000 when the key exists and 0 when not; a team socket hears neither.
+- Change 5, CLI gateway: before any `__tui_open` every event is relayed; with `forMs: 0`, or 180 s after the last
+ `forMs: 180000`, `tool_end`, `subagent_finished`, `done` and `context_compact` are not enqueued while the others
+ (thinking included) are; a link drop resets to "no word"; a guest-sealed copy is always sent; local windows always
+ get every event; product usage still observes `text_delta` and turn events.
+
+- Backend: `swarmClientPushes` unit tests: machine-only changes within 30 s give one push; a `main` change goes at once
+ and carries a held machine part; the repeat still goes.
+- CLI: heartbeats unit tests: working sends only `turn_heartbeat` with `activity`; an unchanged waiting activity is
+ sent once; a change sends again; a restarted heartbeat sends again.
+- CLI: `sessionSync` unit tests: an identical or activity-only frame is not sent to the apps but still to the dial; any
+ other change sends in full; an agent forgotten on the unavailable path sends in full next; the memory stays bounded.
+- CLI: `slimForRelay` unit tests for each row, the bounded input (a large `Write` cut, `TodoWrite` kept), envelope and
+ payload ids untouched; a socket test that windows here still get the full event.
+- The terminal app's fleet view against slim frames (`tui/tests/mock-daemon.mjs`): plan, sub-agents and "doing" still
+ render.
diff --git a/docs/plans/2026-10-31-live-events-relay-plan.md b/docs/plans/2026-10-31-live-events-relay-plan.md
new file mode 100644
index 000000000..a2a44202a
--- /dev/null
+++ b/docs/plans/2026-10-31-live-events-relay-plan.md
@@ -0,0 +1,412 @@
+# Fewer Frames Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** About half the frames between daemons, backend and apps, with every app showing what it shows today.
+
+**Architecture:** Four independent changes: the backend publishes a machine's Swarm reading at most every 30 s; the
+daemon's heartbeat sends one frame per beat and repeats no unchanged activity; the daemon skips an `agent_synced` that
+changes nothing but activity; and apps away from the computer get slim transcript events. A measuring script runs
+before and after.
+
+**Tech Stack:** backend Node/TypeScript (vitest), CLI Node/TypeScript (vitest), Python 3 for the log count.
+
+**Spec:** `docs/plans/2026-10-31-live-events-relay-design.md`
+
+## Status and handoff (2026-10-31)
+
+- Spec and plan written. Tasks 0, 2, 4 and 5 built on branch `fewer-relay-frames` (2026-10-31), not pushed;
+ tasks 1 and 3 still on hold. Built differently from the steps below, each for the reason given:
+ - Task 0: the build Mac's Desktop log of 2026-10-30 is not Ken's (161,203 frames, 03:05-17:02); both are in the
+ spec's Results.
+ - Task 2: an unchanged activity is compared by `state` and `epoch`, not `revision` (spec, change 2).
+ - Task 4: `slimForRelay` is `cli/src/lib/slimForRelay.ts`, not `src/gateway/` (the core may not import it); a tool
+ input's objects are bounded to 50 keys as its lists are; the terminal app's mock sends only fields the slim
+ frame keeps, so it needs no change, and `tui/tests/e2e.sh` could not be run on a current build (no Rust here).
+ - Task 5: `docs/swarms.md` is unchanged: its 30 s rule is task 1's, on hold.
+- **Run tasks 0, 2, 4 and 5.** Tasks 1 and 3 are **on hold** (spec, "On hold"): task 1 would make Desktop and the web
+ show machines late or offline, and needs its own design with a client change, not yet decided by Ken; task 3 saves
+ little that is safe to drop. Skip them; do not delete them, they are the starting point if Ken decides.
+- A first version of task 0's script is in `scripts/desktop-frame-count.py` (counts by type); task 0 adds the
+ `swarm_changed` gap and the `agent_synced` classes, then runs it on a Desktop log to reproduce the "before" table.
+- Task 2: activity states are only `working`, `idle` and `unknown` (`cli/src/lib/turnActivity.ts`); write the tests
+ with those (the plan's "waiting" example becomes `idle`).
+
+## Global Constraints
+
+- Windows on this computer and everything inside the daemon (the dial's cards, recaps, the Swarm, search, the
+ orchestrator, local tool clients) keep full events; only frames for apps away from the computer change (task 4).
+- `cli/src/lib/e2ee/core.ts` is not edited (its hash is pinned with other repositories' clients).
+- `updatedAt` changes are always sent in `agent_synced` (the phone sorts agents by it).
+- `turn_heartbeat` stays the frame sent while working (the phone reads only it).
+- Backend tests: `cd backend && NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= npx vitest run <file>`.
+- CLI tests: `cd cli && npx vitest run <file>`; files under `src/core/` need `npm run test:core` (100% per file).
+- Commits end with `Co-Authored-By: Claude Opus 5.5 <[email protected]>`; no push, PR, merge or release
+ without Ken.
+
+## Review Focus
+
+- A Swarm whose only changes are machine readings for an hour: apps still see machine cards update at least every
+ 30 s. (Task 1 test.)
+- A main change 5 s after a machine push: it goes at once and also carries any machine part held since. (Task 1 test.)
+- An agent waiting on a question for 10 minutes: one `agent_activity` when it starts waiting, none after, and
+ `turn_heartbeat` again when it resumes working. (Task 2 test.)
+- The same agent synced 100 times with only `activity` moving: one frame to the apps, every one to the dial. (Task 3
+ test.)
+- A `Write` tool whose input is 2 MB: the remote frame is under 2 KB, the window here gets all 2 MB. (Task 4 test.)
+
+---
+
+### Task 0: The frame count script, and the "before" number
+
+**Files:**
+- Create: `scripts/desktop-frame-count.py`
+- Modify: `docs/plans/2026-10-31-live-events-relay-design.md` (Results section)
+
+**Interfaces:**
+- Produces: `python3 -I scripts/desktop-frame-count.py <app-log>` prints, for one Desktop log, the window, the total
+ `↓` frames, and per type the count, share and logged bytes, most frequent first; plus `swarm_changed` median gap and
+ `agent_synced` classes (first, identical, activity-only, other) as in the spec.
+
+- [ ] **Step 1:** Write the script (stdlib only; read the file as bytes and decode with `errors='replace'`; the line
+ format is `[YYYY-MM-DD HH:MM:SS] DEBUG ws ↓ <type> {...}`).
+- [ ] **Step 2:** Run it on `~/.harness/logs/app-20261030.log`.
+ Expected: 170,666 frames; `swarm_changed` 54,282; `agent_activity` 32,819; `turn_heartbeat` 28,411; `agent_synced`
+ 17,099 with 4,239 identical and 181 activity-only.
+- [ ] **Step 3:** Add a "Results" section to the spec with the command and the "before" table; leave an "after" row.
+- [ ] **Step 4:** Commit: `git add scripts/desktop-frame-count.py docs/plans/2026-10-31-live-events-relay-design.md`,
+ message "Frame count: a script that counts a Desktop log's frames by type, and the before number".
+
+### Task 1: A machine's Swarm reading published at most every 30 s (backend)
+
+**Files:**
+- Modify: `backend/src/lib/swarmClientPushes.ts` (`coalescer`, `announced`, `announceSwarmChanges`)
+- Test: `backend/src/lib/swarmClientPushes.test.ts` (beside "publishes at most once per Swarm a second")
+
+**Interfaces:**
+- Produces: `MACHINE_COALESCE_MS = 30_000` (exported for the test); `coalescer(merge, emit, windowMs)` takes its window
+ instead of the module constant; `announceSwarmChanges(change)` keeps its signature.
+
+- [ ] **Step 1: Write the failing tests** (each uses a Swarm id of its own, as the existing publish test does):
+
+```ts
+it('publishes a machine reading at most every 30 s per Swarm, the first at once', async () => {
+ announceSwarmChanges({ tabId: 'tab-readings', userIds: ['kim'], lastChangedAt: 1, parts: ['machine'] })
+ expect(bus.published).toEqual([['kim', { tabId: 'tab-readings', lastChangedAt: 1, parts: ['machine'] }]])
+ for (let at = 2; at <= 20; at++) {
+ await vi.advanceTimersByTimeAsync(1_000)
+ announceSwarmChanges({ tabId: 'tab-readings', userIds: ['kim', 'lee'], lastChangedAt: at, parts: ['machine'] })
+ }
+ expect(bus.published).toHaveLength(1)
+ await vi.advanceTimersByTimeAsync(MACHINE_COALESCE_MS)
+ expect(bus.published.slice(1)).toEqual([['kim', { tabId: 'tab-readings', lastChangedAt: 20, parts: ['machine'] }],
+ ['lee', { tabId: 'tab-readings', lastChangedAt: 20, parts: ['machine'] }]])
+})
+it('sends a main change at once, carrying the machine reading it held', async () => {
+ announceSwarmChanges({ tabId: 'tab-mixed', userIds: ['kim'], lastChangedAt: 1, parts: ['machine'] })
+ await vi.advanceTimersByTimeAsync(5_000)
+ announceSwarmChanges({ tabId: 'tab-mixed', userIds: ['kim'], lastChangedAt: 2, parts: ['machine'] })
+ announceSwarmChanges({ tabId: 'tab-mixed', userIds: ['kim'], lastChangedAt: 3, parts: ['main'] })
+ expect(bus.published.slice(1)).toEqual([['kim', { tabId: 'tab-mixed', lastChangedAt: 3, parts: ['main', 'machine'] }]])
+ // The machine reading went with it: none is left for the end of its window.
+ await vi.advanceTimersByTimeAsync(MACHINE_COALESCE_MS)
+ expect(bus.published).toHaveLength(2)
+})
+```
+
+- [ ] **Step 2: Run them**: `… npx vitest run src/lib/swarmClientPushes.test.ts`. Expected: FAIL (the 1 s coalescer
+ publishes the readings every second; `MACHINE_COALESCE_MS` undefined).
+- [ ] **Step 3: Implement.** Give `coalescer` a `windowMs` parameter (`relaySwarmChanges` and `announced` pass
+ `COALESCE_MS`). Add a second process-level coalescer `announcedReadings` with `MACHINE_COALESCE_MS` for changes whose
+ parts are only `machine`. In `announceSwarmChanges`: a machine-only change goes to `announcedReadings`; any other
+ change takes what `announcedReadings` holds for that Swarm (a `take(key)` on the coalescer that returns and clears the
+ held value, leaving its window open), merges it, and goes to `announced`. Update the comment above `COALESCE_MS`
+ with the measurement (54,282 machine pushes a day for one Swarm of ten machines, 2026-10-30).
+- [ ] **Step 4: Run the file.** Expected: PASS, the existing tests included (the old "publishes at most once per Swarm
+ a second" test still passes: its machine part rides with the main change).
+- [ ] **Step 5: Commit** `backend/src/lib/swarmClientPushes.ts backend/src/lib/swarmClientPushes.test.ts`, message
+ "Swarm pushes: a machine's reading is published at most every 30 s; main changes still at once".
+
+### Task 2: One heartbeat frame per beat, and no unchanged activity repeated (CLI core)
+
+**Files:**
+- Modify: `cli/src/core/turns/heartbeats.ts` (`createHeartbeats`, `beat`, `stopHeartbeat`)
+- Test: `cli/src/core/turns/heartbeats.spec.ts`
+
+**Interfaces:**
+- Produces: no new export; `createHeartbeats` keeps its deps and return value.
+
+- [ ] **Step 1: Write the failing tests** with the file's `setup()` and `sentTypes()`:
+
+```ts
+it('sends only turn_heartbeat, with its activity, while working', async () => {
+ const { deps, beats, set } = setup()
+ set({ activity: { state: 'working', epoch: 'e', revision: 1, validForMs: 30_000 } as ActivityFrame })
+ beats.startHeartbeat('s1')
+ await vi.advanceTimersByTimeAsync(15_000)
+ expect(sentTypes(deps)).toEqual(['turn_heartbeat', 'turn_heartbeat', 'turn_heartbeat'])
+ expect(vi.mocked(deps.clients.send).mock.calls[0]![0]).toMatchObject({ payload: { activity: { state: 'working' } } })
+})
+it('sends a waiting activity once, and again only when it changes or the heartbeat restarts', async () => {
+ const { deps, beats, set } = setup()
+ set({ activity: { state: 'waiting', epoch: 'e', revision: 2, validForMs: 0 } as ActivityFrame })
+ beats.startHeartbeat('s1')
+ await vi.advanceTimersByTimeAsync(600_000)
+ expect(sentTypes(deps)).toEqual(['agent_activity'])
+ set({ activity: { state: 'working', epoch: 'e', revision: 3, validForMs: 30_000 } as ActivityFrame })
+ await vi.advanceTimersByTimeAsync(5_000)
+ set({ activity: { state: 'waiting', epoch: 'e', revision: 4, validForMs: 0 } as ActivityFrame })
+ await vi.advanceTimersByTimeAsync(10_000)
+ expect(sentTypes(deps)).toEqual(['agent_activity', 'turn_heartbeat', 'agent_activity'])
+ beats.stopHeartbeat('s1'); beats.startHeartbeat('s1')
+ await vi.advanceTimersByTimeAsync(5_000)
+ expect(sentTypes(deps).at(-1)).toBe('agent_activity')
+})
+```
+
+ Use the activity shape `ActivityFrame` really has (`lib/turnActivity.ts`); compare by `state`, `epoch`, `revision`.
+- [ ] **Step 2: Run**: `cd cli && npx vitest run src/core/turns/heartbeats.spec.ts`. Expected: FAIL (both frames every
+ beat). Update existing tests in the file that expect both frames to the new rule.
+- [ ] **Step 3: Implement.** A `lastActivity = new Map<string, string>()` keyed by session, holding
+ `${state}:${epoch}:${revision}`; working → send only `turnHeartbeatFrame(...)`; otherwise send `agent_activity` only
+ when the key differs, then store it; `stopHeartbeat` deletes the entry. Comment why (2026-10-30: 32,819
+ `agent_activity` and 28,411 `turn_heartbeat` a day, the same activity twice; the phone reads only `turn_heartbeat`).
+- [ ] **Step 4: Run** the file, then `npm run test:core`. Expected: PASS, 100% for `heartbeats.ts`.
+- [ ] **Step 5: Commit** `cli/src/core/turns/heartbeats.ts cli/src/core/turns/heartbeats.spec.ts`, message
+ "Heartbeats: one frame a beat, turn_heartbeat while working; an unchanged activity is not repeated".
+
+### Task 3: `agent_synced` skipped when nothing but activity changed (CLI)
+
+**Files:**
+- Modify: `cli/src/lib/sessionSync.ts` (`createSessionSync`)
+- Test: `cli/src/lib/sessionSync.spec.ts`
+
+**Interfaces:**
+- Produces: `createSessionSync` keeps its signature and callers; exported `SYNC_MEMORY_LIMIT = 2_000`.
+
+- [ ] **Step 1: Write the failing tests** with the file's `harness()` and `row()`:
+
+```ts
+it('sends the apps an agent only when something besides its activity changed, and the dial every time', async () => {
+ let activity = { state: 'working', epoch: 'e', revision: 1 }
+ const h = harness({ project: vi.fn(async (session) => ({ ...agentFrame(session, { selectedModel: null, terminalAvailable: true }), activity })) as never })
+ await h.sync(row())
+ await h.sync(row())
+ activity = { state: 'idle', epoch: 'e', revision: 2 }
+ await h.sync(row())
+ expect(h.send).toHaveBeenCalledTimes(1)
+ expect(h.sendCommander).toHaveBeenCalledTimes(3)
+ await h.sync(row({ title: 'Renamed' }))
+ expect(h.send).toHaveBeenCalledTimes(2)
+})
+it('sends in full after the agent was unavailable, and remembers at most SYNC_MEMORY_LIMIT agents', async () => {
+ let available = true
+ const h = harness({ terminalAvailable: () => available })
+ await h.sync(row()); available = false; await h.sync(row()); available = true; await h.sync(row())
+ expect(h.send).toHaveBeenCalledTimes(2)
+ for (let i = 0; i <= SYNC_MEMORY_LIMIT; i++) await h.sync(row({ agentId: `agent-${i}` }))
+ await h.sync(row({ agentId: 'agent-0' })) // the oldest was forgotten: sent again
+ expect(h.send).toHaveBeenCalledTimes(2 + SYNC_MEMORY_LIMIT + 2)
+})
+```
+
+- [ ] **Step 2: Run**: `npx vitest run src/lib/sessionSync.spec.ts`. Expected: FAIL (every sync is sent).
+- [ ] **Step 3: Implement.** A `Map<string, string>` agentId → `JSON.stringify` of the agent without `activity`
+ (insertion order = age; on a set, delete then set; above the limit delete the first key). Skip `deps.send` when equal;
+ always call `deps.sendCommander` as today. On the unavailable branch, delete the agent's entry. Comment why
+ (2026-10-30: 4,239 of 17,099 `agent_synced` identical to the one before).
+- [ ] **Step 4: Run** the file and `npx vitest run src/lib src/core/agents` (callers' tests). Expected: PASS.
+- [ ] **Step 5: Commit** `cli/src/lib/sessionSync.ts cli/src/lib/sessionSync.spec.ts`, message
+ "Agent sync: an agent is not sent to the apps again when only its activity changed".
+
+### Task 4: Slim transcript events for apps away from the computer (CLI)
+
+**Files:**
+- Create: `cli/src/gateway/slimForRelay.ts`, `cli/src/gateway/slimForRelay.spec.ts`
+- Modify: `cli/src/backendSocket.ts` (`toRemoteApps`, ~620)
+- Test: `cli/src/backendSocket.spec.ts` (or the relay socket tests that cover `send`)
+
+**Interfaces:**
+- Produces: `export function slimForRelay(frame: Frame): Frame` — pure; returns the same object for a type not in the
+ spec's table; never mutates its input.
+
+- [ ] **Step 1: Write the failing unit tests**, one per table row of the spec ("4. Transcript events"), with these
+ exact values: string values in `tool_start.input` cut to 200 characters, arrays to 50 items, nesting to depth 4;
+ `done.result` cut to 500; `user_message.images` dropped; `thinking_delta` and `context_compact` keep no payload field
+ but `activity`, `agentId`, `sessionId`, `replay`; `tool_end` keeps `id`, `tool`, `parentToolUseId`, `isError`;
+ `subagent_finished` keeps `id`, `status`; the envelope (`type`, `agentId`, `dbSessionId`, `replay`, `subagent`) is
+ identical; a 2 MB `Write` input yields a frame whose `JSON.stringify` is under 2,048 bytes; `TodoWrite`'s `todos`
+ (10 items) survive whole; an `agent_synced` frame is returned unchanged (`toBe`).
+- [ ] **Step 2: Run**: `npx vitest run src/gateway/slimForRelay.spec.ts`. Expected: FAIL (module missing).
+- [ ] **Step 3: Implement** `slimForRelay` with a per-type table of kept payload keys plus the four always-kept ones.
+- [ ] **Step 4: Write the failing socket test**: a `tool_end` with `output` sent through `socket.send` reaches a local
+ client with `output` and reaches the gateway (`upstreamOf(socket).queue`, unsealed in the test's setup or read
+ through the gateway's `broadcast` spy) without it. Run it; expected FAIL.
+- [ ] **Step 5: Implement** in `toRemoteApps`: `const frame = this.forApps(slimForRelay(given))`.
+- [ ] **Step 6: Run** `npx vitest run src/gateway src/backendSocket.spec.ts` and the gateway product-usage test
+ ("passes only lifecycle scalars to product reporting"). Expected: PASS.
+- [ ] **Step 7: The terminal app**: run `tui/tests/e2e.sh` (it uses `tui/tests/mock-daemon.mjs`) after making the mock
+ send slim frames (pass them through the same table, by hand, for the frames it sends). Expected: plan, sub-agents and
+ "doing" still render.
+- [ ] **Step 8: Commit** the new files, `cli/src/backendSocket.ts`, the socket test and any `tui/tests` change, message
+ "Relay: apps away from the computer get slim transcript events, no tool output, thinking text or images".
+
+### Task 5: Docs, and the "after" number
+
+**Files:**
+- Modify: `docs/swarms.md` (the push section: machine readings at most every 30 s), the spec's Results section.
+
+- [ ] **Step 1:** Update `docs/swarms.md` where it describes Swarm pushes (search "swarm_changed" / "push") with the
+ 30 s rule and why.
+- [ ] **Step 2:** After release, on a comparable day, run Task 0's script on that day's Desktop log and fill the
+ "after" row in the spec. (Done after release; leave the row marked pending until then.)
+- [ ] **Step 3: Commit** `docs/swarms.md docs/plans/2026-10-31-live-events-relay-design.md`, message
+ "Docs: Swarm machine readings pushed every 30 s; frame counts before".
+
+## Validation and release
+
+- Backend unit (`src/lib`), CLI unit (`src/core/turns`, `src/lib`, `src/gateway`, `src/backendSocket.spec.ts`),
+ `npm run test:core`, both `tsc`, `tui/tests/e2e.sh`.
+- Release order: backend (task 1), CLI (tasks 2-4); each is compatible alone.
+
+---
+
+# Change 5: events only the terminal app reads (added 2026-10-31)
+
+**Goal:** While no terminal app of the account is open, a daemon does not relay `tool_end`, `subagent_finished`,
+`done` and `context_compact`.
+
+**Architecture:** The backend turns the TUI presence it already receives into an account push `__tui_open
+{ forMs }` (at once on an `open`, at most once a minute on a `ping`, and on every daemon socket's attach); the daemon's
+gateway keeps `tuiUntil` and, once it has heard one, holds those four event types back from the relay after it passes.
+
+**Spec:** `docs/plans/2026-10-31-live-events-relay-design.md`, "5. Events only the terminal app reads".
+
+## Global Constraints (change 5)
+
+- Values: key `tui_open:{userId}` `EX 150`; push gate `tui_open_said:{userId}` `SET NX EX 60`; `forMs` 180000 (open)
+ or 0 (none); frame type `__tui_open`; held types exactly `tool_end`, `subagent_finished`, `done`, `context_compact`.
+- TUI surfaces are the backend's `TUI_SURFACES` (`tui`, `harness-os`, `harness-os-pi`); the desktop surface never
+ counts. A team socket neither gets the push nor the attach word.
+- No word heard (older backend, team account, link not re-attached) means every event is relayed, as today.
+- Guest-sealed copies, windows on this computer and `productUsage.observe` are never affected.
+
+## Review Focus (change 5)
+
+- A daemon that attaches while a terminal app has been open for 50 s (between pings): it hears 180,000 at attach,
+ not 0. (Task 6 test: key set by an earlier ping, attach reads it.)
+- A Harness OS box (`harness-os-pi`) pinging: counts as a terminal app. (Task 6 test.)
+- The relay link drops and comes back before the backend's attach word: everything is relayed in between. (Task 7
+ test.)
+- A `__tui_open` sent by a window on this computer (`local` connection): ignored, as `__clients` is. (Task 7 test.)
+- A `forMs` that is negative, not a number or huge (over a day): read as 0, ignored, and capped at 180,000. (Task 7
+ test.)
+
+### Task 6: Backend: TUI presence becomes an account push
+
+**Files:**
+- Modify: `backend/src/lib/bus.ts` (beside `publishDeskChanged`/`subscribeDeskChanged`, ~853)
+- Modify: `backend/src/lib/adapterWs.ts` (`app_presence` branch, ~491)
+- Modify: `backend/src/lib/adapterAccountPushes.ts` (`relayAccountPushes`)
+- Test: `backend/src/lib/bus.test.ts`, `backend/src/lib/adapterAccountPushes.test.ts`, a new
+ `backend/src/lib/adapterTuiPresence.test.ts` (the socket harness of `adapterShortTurns.test.ts`)
+
+**Interfaces:**
+- Produces in `bus.ts`: `export const TUI_OPEN_FOR_MS = 180_000`;
+ `export async function noteTuiPresence(userId: string, kind: 'open' | 'ping'): Promise<void>` (refreshes
+ `tui_open:{userId}` `EX 150`; publishes on channel `tui:{userId}` when `kind === 'open'` or when
+ `SET tui_open_said:{userId} 1 EX 60 NX` succeeds; logs and swallows Redis errors);
+ `export async function tuiOpenNow(userId: string): Promise<boolean>` (EXISTS; false on error);
+ `export function subscribeTuiOpen(userId: string, cb: () => void): Promise<() => void>`.
+- `relayAccountPushes` sends `{ t: 'down', connId: '', frame: { type: '__tui_open', payload: { forMs } } }`.
+
+- [ ] **Step 1: Failing tests.** In `bus.test.ts` (its `FakeRedis` gains `set` and `exists` mocks; `set` returns
+ `'OK'` or `null` as the test arranges): an `open` sets `tui_open:{userId}` with `EX 150` and publishes on
+ `tui:{userId}` at once; a `ping` publishes only when `SET tui_open_said:{userId} 1 EX 60 NX` returns `'OK'`;
+ `tuiOpenNow` is true when `exists` returns 1, false on 0 and on a throw.
+ In `adapterAccountPushes.test.ts` (add `subscribeTuiOpen` and `tuiOpenNow` to its `bus.js` mock):
+
+```ts
+it('tells the daemon at attach whether a terminal app of the account is open, and when one is', async () => {
+ m.tuiOpenNow.mockResolvedValue(true)
+ let heard: () => void = () => {}
+ m.tui.mockImplementation(async (_user: string, cb: () => void) => { heard = cb; return m.tuiUnsub })
+ const send = vi.fn()
+ await relayAccountPushes('kim', send, on)
+ expect(send).toHaveBeenCalledWith({ t: 'down', connId: '', frame: { type: '__tui_open', payload: { forMs: 180_000 } } })
+ send.mockClear(); heard()
+ expect(send).toHaveBeenCalledWith({ t: 'down', connId: '', frame: { type: '__tui_open', payload: { forMs: 180_000 } } })
+})
+it('says none is open at attach, so the daemon starts holding events back', async () => { /* tuiOpenNow false → forMs 0 */ })
+it('tells a team machine nothing about terminal apps', async () => { /* team: no subscribeTuiOpen, no __tui_open */ })
+```
+
+ In `adapterTuiPresence.test.ts` (copy the socket harness of `adapterShortTurns.test.ts`, its `bus.js` mock gaining
+ `noteTuiPresence`): an `app` frame `{ type: 'app_presence', payload: { kind: 'open', surface: 'tui' } }` and one with
+ `surface: 'harness-os-pi'` call `noteTuiPresence(<the socket's user>, 'open')`; `kind: 'ping'` passes `'ping'`; no
+ surface (the desktop app) and an unknown surface call nothing.
+- [ ] **Step 2: Run** `cd backend && NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= npx vitest run src/lib/bus.test.ts src/lib/adapterAccountPushes.test.ts src/lib/adapterTuiPresence.test.ts`.
+ Expected: FAIL (functions missing).
+- [ ] **Step 3: Implement** the three `bus.ts` functions, the `adapterWs.ts` call (`void noteTuiPresence(userId,
+ kind)` in the TUI-surface branch), and in `relayAccountPushes` (not for `opts.team`): subscribe, then send the
+ attach word (`forMs: await tuiOpenNow(userId) ? TUI_OPEN_FOR_MS : 0`). Comment why (spec change 5).
+- [ ] **Step 4: Run** the files, then `npx tsc --noEmit -p .`. Expected: PASS, clean.
+- [ ] **Step 5: Commit** the six files, message "Account pushes: a terminal app open on the account is told to its
+ daemons (__tui_open), at once on open and at most once a minute while it stays".
+
+### Task 7: Daemon gateway: hold terminal-app-only events while none is open
+
+**Files:**
+- Modify: `cli/src/gateway/gateway.ts` (`backendControl` before the `__` drop; `linkGone`; `broadcast` before
+ enqueue)
+- Test: `cli/src/gateway/gateway.spec.ts`
+
+**Interfaces:**
+- Produces: `export const TUI_ONLY_EVENTS = new Set(['tool_end', 'subagent_finished', 'done', 'context_compact'])`
+ and `export const TUI_OPEN_MAX_MS = 180_000` in `gateway.ts`; private `tuiUntil: number | null = null`.
+
+- [ ] **Step 1: Failing test** (with `relaySocket`, `gatewayOf`, `dispatchDown`, `upstreamOf`, fake timers):
+
+```ts
+it('relays terminal-app-only events only while a terminal app of the account is open, once the backend says', async () => {
+ vi.useFakeTimers()
+ const socket = relaySocket(MACHINE), gateway = gatewayOf(socket)
+ const sent = () => upstreamOf(socket).queue.map(i => ((i.msg as { frame: { type: string } }).frame).type)
+ const events = ['tool_end', 'subagent_finished', 'done', 'context_compact', 'tool_start', 'text_delta', 'thinking_delta', 'turn_ended']
+ const relayAll = () => { upstreamOf(socket).queue.length = 0; for (const type of events) gateway.broadcast({ type, agentId: 'a1', payload: {} }) ; return sent() }
+ expect(relayAll()).toEqual(events) // no word yet: everything
+ await dispatchDown(socket, { type: '__tui_open', payload: { forMs: 0 } }, '')
+ expect(relayAll()).toEqual(['tool_start', 'text_delta', 'thinking_delta', 'turn_ended'])
+ await dispatchDown(socket, { type: '__tui_open', payload: { forMs: 180_000 } }, '')
+ expect(relayAll()).toEqual(events)
+ await vi.advanceTimersByTimeAsync(180_001)
+ expect(relayAll()).toEqual(['tool_start', 'text_delta', 'thinking_delta', 'turn_ended'])
+ ;(gateway as unknown as { linkGone(): void }).linkGone()
+ expect(relayAll()).toEqual(events) // link dropped: no word again
+ vi.useRealTimers()
+})
+it('ignores __tui_open from a window on this computer, and reads a bad forMs as 0, capped at 180 s', async () => { /* local:tool → no effect; forMs -5, 'x' → 0; 10 days → 180 s */ })
+it('always sends a guest\'s sealed copy, held or not', async () => { /* guest session present: targeted copy enqueued for a held type */ })
+```
+
+ If the queue drains in the test setup, read what `link.enqueue` received through a spy instead.
+- [ ] **Step 2: Run** `cd cli && npx vitest run src/gateway/gateway.spec.ts`. Expected: FAIL.
+- [ ] **Step 3: Implement.** In `backendControl`, before the `__` drop: `__tui_open` → `forMs` a finite number ≥ 0,
+ else 0, capped at `TUI_OPEN_MAX_MS`; `this.tuiUntil = Date.now() + forMs`. In `linkGone`: `this.tuiUntil = null`.
+ In `broadcast`, after the product-usage reads and before `this.link.enqueue` of the group copy: skip that enqueue
+ when `this.tuiUntil !== null && Date.now() >= this.tuiUntil && TUI_ONLY_EVENTS.has(frame.type)`; the guest loop
+ runs either way. Comment why (spec change 5; the counts).
+- [ ] **Step 4: Run** the file, `npx vitest run src/gateway src/backendSocket.spec.ts`, `npx tsc --noEmit -p .`.
+ Expected: PASS, clean.
+- [ ] **Step 5: Commit** `cli/src/gateway/gateway.ts cli/src/gateway/gateway.spec.ts`, message "Relay: events only the
+ terminal app reads are not relayed while the account has none open".
+
+### Task 8: Docs
+
+- [ ] Update the spec's status line (change 5 built) and `docs/swarms.md` if it describes relayed events (search
+ "relay"); commit.
+
+## Validation (change 5)
+
+Backend: `src/lib` unit, `tsc`. CLI: `src/gateway`, `src/backendSocket.spec.ts`, `tsc`. Then the final independent
+review of the whole branch (changes 2, 4 and 5).
diff --git a/scripts/desktop-frame-count.py b/scripts/desktop-frame-count.py
new file mode 100644
index 000000000..6e11dc15a
--- /dev/null
+++ b/scripts/desktop-frame-count.py
@@ -0,0 +1,93 @@
+"""Counts the frames a Harness Desktop log received, by type.
+
+Usage: python3 -I scripts/desktop-frame-count.py ~/.harness/logs/app-YYYYMMDD.log
+
+Reads lines like `[YYYY-MM-DD HH:MM:SS] DEBUG ws ↓ <type> {...}` and prints the window, the total of received
+(↓) frames and, per type, its count, share and logged bytes (values in the log are cut, so bytes understate large
+payloads); then the median gap between `swarm_changed` frames, and each `agent_synced` against the one before it for
+the same agent: first, identical, differing only in `activity`, or other. Measures
+docs/plans/2026-10-31-live-events-relay-design.md before and after.
+"""
+import collections
+import re
+import statistics
+import sys
+from datetime import datetime
+
+LINE = re.compile(r'^\[(\S+ \S+)\] DEBUG ws\s+(\S)\s+([a-z_]+)\s?(.*)$')
+AGENT_ID = re.compile(r'^\{agent: \{id: ([^,}]+)')
+
+
+ACTIVITY = re.compile(r'(?:(?<=\{)|(?<=, ))activity: ')
+
+
+def without_activity(text):
+ """The logged agent with its `activity: …` entry removed (a value is `null` or one `{…}`, possibly nested). Only an
+ entry's own key matches: a title like "Reactivity: tests" does not."""
+ found = ACTIVITY.search(text)
+ if not found:
+ return text
+ at = found.start()
+ end = found.end()
+ if text.startswith('{', end):
+ depth = 0
+ while end < len(text):
+ depth += {'{': 1, '}': -1}.get(text[end], 0)
+ end += 1
+ if depth == 0:
+ break
+ else:
+ while end < len(text) and text[end] not in ',}':
+ end += 1
+ if text.startswith(', ', end):
+ end += 2
+ return text[:at] + text[end:]
+
+
+def main(path):
+ count, size, directions = collections.Counter(), collections.Counter(), collections.Counter()
+ changed_at, synced = [], collections.Counter()
+ last_agent = {}
+ first = last = None
+ with open(path, 'rb') as log:
+ for raw in log:
+ match = LINE.match(raw.decode('utf-8', 'replace').rstrip('\n'))
+ if not match:
+ continue
+ at, direction, kind, rest = match.groups()
+ directions[direction] += 1
+ if direction != '↓':
+ continue
+ first = first or at
+ last = at
+ count[kind] += 1
+ size[kind] += len(rest.encode())
+ if kind == 'swarm_changed':
+ changed_at.append(datetime.strptime(at, '%Y-%m-%d %H:%M:%S'))
+ elif kind == 'agent_synced':
+ agent = AGENT_ID.match(rest)
+ key = agent.group(1) if agent else None
+ before = last_agent.get(key)
+ if before is None:
+ synced['first'] += 1
+ elif before == rest:
+ synced['identical'] += 1
+ elif without_activity(before) == without_activity(rest):
+ synced['activity only'] += 1
+ else:
+ synced['other'] += 1
+ last_agent[key] = rest
+ total, total_bytes = sum(count.values()), sum(size.values())
+ print('window', first, '->', last, '| directions', dict(directions))
+ print('received frames', total, 'logged bytes (cut)', total_bytes)
+ for kind, n in count.most_common(25):
+ print(f'{n:8d} {100 * n / total:5.1f}% {size[kind]:10d}B {kind}')
+ if len(changed_at) > 1:
+ gaps = [(b - a).total_seconds() for a, b in zip(changed_at, changed_at[1:])]
+ print(f'swarm_changed: median gap {statistics.median(gaps):.2f} s (log times are whole seconds)')
+ if synced:
+ print('agent_synced:', ', '.join(f'{kind} {synced[kind]}' for kind in ('first', 'identical', 'activity only', 'other')))
+
+
+if __name__ == '__main__':
+ main(sys.argv[1])