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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.tsindex 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.tsindex 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 errdiff --git a/backend/src/lib/adapterTuiPresence.test.ts b/backend/src/lib/adapterTuiPresence.test.tsnew file mode 100644index 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.tsindex 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 adiff --git a/backend/src/lib/bus.test.ts b/backend/src/lib/bus.test.tsindex 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: MockFnmultiCalls: Array<{ cmd: string; args: unknown[] }>; multiResult: unknownpipelines: 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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) returnconst 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.tsindex 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.tsindex 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, runticonst TURN_HEARTBEAT_MS = 5000const 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, runtiif (!heartbeats.has(sessionId)) returnconst 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.tsindex 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.tsindex 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 adiff --git a/cli/src/lib/slimForRelay.spec.ts b/cli/src/lib/slimForRelay.spec.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.pynew file mode 100644index 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])