Skip to content

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

Core boundary, part 1: terminal control, agent announcements and engine state become modules (#716)

Dee64988301bd73
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e7d80029e..329a8d2ce 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -346,6 +346,11 @@ jobs:
- name: Require complete harness updater coverage
run: npm run test:dsh-updates
+ # The daemon's supervisor and its core modules are held to 100% in every file
+ # (docs/design/2026-10-03-harnessd.md#testing).
+ - name: Require complete harnessd and core coverage
+ run: npm run test:harnessd && npm run test:core
+
cli-tests:
if: ${{ contains(fromJSON('["full","cli"]'), inputs.scope || 'full') }}
strategy:
diff --git a/cli/e2e/master.e2e.ts b/cli/e2e/master.e2e.ts
index 936174dde..892aab626 100644
--- a/cli/e2e/master.e2e.ts
+++ b/cli/e2e/master.e2e.ts
@@ -72,16 +72,26 @@ describe('harnessd', () => {
await turnWorks(d, agentId)
})
- it('kills and restarts a core that hangs', async () => {
+ it('kills and restarts a core that hangs, and only one that hangs', async () => {
+ // A timeout shorter than the core's default beat (5 s): the core is told it and beats inside it.
+ // Before, every healthy core here was "hung" three seconds after binding.
const d = await make({ HARNESSD_HEARTBEAT_TIMEOUT_MS: '3000' })
const { agentId } = await withAgent(d)
const hung = d.corePid()!
+ const hangs = () => [...d.log().matchAll(/it is hung/g)].length
+ await new Promise((done) => setTimeout(done, 6_000))
+ expect(hangs(), 'a healthy core outlives twice the timeout').toBe(0)
+ expect(d.corePid()).toBe(hung)
const wired = wiredCount(d)
process.kill(hung, 'SIGSTOP')
- await until('the master to notice', () => d.log().includes('it is hung'), 20_000)
+ await until('the master to notice', () => hangs() > 0, 20_000)
await until('a new core to finish starting', () => wiredCount(d) > wired, 60_000)
expect(IsolatedDaemon.alive(hung)).toBe(false)
await turnWorks(d, agentId)
+ const next = d.corePid()
+ await new Promise((done) => setTimeout(done, 6_000))
+ expect(d.corePid(), 'the new core stays up').toBe(next)
+ expect(hangs()).toBe(1)
})
it('takes the core down with it when the master is killed, and starts clean again', async () => {
diff --git a/cli/package.json b/cli/package.json
index eddc77c32..d4ab5a574 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -18,6 +18,7 @@
"test:dsh-updates": "vitest run --config vitest.dsh-updates.config.ts",
"test:sharing": "vitest run src/sharing --coverage --coverage.include='src/sharing/**' --coverage.thresholds.lines=100 --coverage.thresholds.statements=100 --coverage.thresholds.branches=100 --coverage.thresholds.functions=100",
"test:harnessd": "vitest run --config vitest.harnessd.config.ts",
+ "test:core": "vitest run --config vitest.core.config.ts",
"test:e2e": "vitest run --config vitest.e2e.config.ts",
"test:sharing-e2e": "tsx scripts/share-harness-e2e.ts",
"test:remote-viewers": "vitest run --config vitest.viewer.config.ts",
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 0dc7f12af..8bf742eec 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -173,6 +173,9 @@ import {
import { Watcher, type HistoryEvent, type LineEvent, type RewrittenEvent, type TailHold } from './watcher/watcher.js'
import { chooseHookAgent, startHookServer } from './hookServer.js'
import { connectToMaster } from './harnessd/coreLink.js'
+import { createTerminalControl } from './core/terminals/control.js'
+import { createAgentEvents } from './core/agents/events.js'
+import { createSessionNormalizers } from './core/transcripts/normalizers.js'
import { describeMasterStatus, readStatusFile, runMaster } from './harnessd/master.js'
import { CORE_EXIT_STOP, CORE_EXIT_UPDATE } from './harnessd/protocol.js'
import { isLocalSocketName, localSocketPath, type LocalSocketServer } from './lib/localSocket.js'
@@ -1800,102 +1803,18 @@ async function runForeground(session: AuthSession | null): Promise<void> {
})
}
- const terminalSession = (target: string): RegisteredSession | undefined => registry.resolve(target)
- const controlLeases = new Map<string, { lease: Awaited<ReturnType<typeof terminals.acquireLease>> & { state: 'succeeded' }; expiresAt: number }>()
- const pinnedControls = new Set<string>()
- const invalidControls = new Set<string>()
- const CONTROL_LEASE_IDLE_MS = 15_000
- const leasedTerminal = async (session: RegisteredSession): Promise<Extract<Awaited<ReturnType<typeof terminals.acquireLease>>, { state: 'succeeded' }> | null> => {
- const pinned = pinnedControls.has(session.agentId)
- if (pinned && invalidControls.has(session.agentId)) return null
- const current = controlLeases.get(session.agentId)
- if (current && (pinned || current.expiresAt > Date.now())) {
- if (!await terminals.validateLease(current.lease.value, session)) {
- controlLeases.delete(session.agentId)
- if (pinned) invalidControls.add(session.agentId)
- return null
- }
- current.expiresAt = Date.now() + CONTROL_LEASE_IDLE_MS
- return current.lease
- }
- controlLeases.delete(session.agentId)
- const acquired = await terminals.acquireLease(session)
- if (acquired.state !== 'succeeded') return null
- const value = { lease: acquired, expiresAt: Date.now() + CONTROL_LEASE_IDLE_MS }
- controlLeases.set(session.agentId, value)
- return acquired
- }
- const pinTerminalControl = (target: string): (() => void) | null => {
- const session = terminalSession(target)
- if (!session || pinnedControls.has(session.agentId)) return null
- pinnedControls.add(session.agentId)
- invalidControls.delete(session.agentId)
- return () => {
- pinnedControls.delete(session.agentId)
- invalidControls.delete(session.agentId)
- controlLeases.delete(session.agentId)
- }
- }
- const invalidateTerminalControl = (agentId: string): void => {
- controlLeases.delete(agentId)
- if (pinnedControls.has(agentId)) invalidControls.add(agentId)
- }
- const captureTerminal = async (target: string, historyLines?: number): Promise<string | null> => {
- const session = terminalSession(target)
- if (!session) return null
- const pinned = pinnedControls.has(session.agentId)
- if (pinned && invalidControls.has(session.agentId)) return null
- let activeLease = controlLeases.get(session.agentId)
- if (activeLease && !pinned && activeLease.expiresAt <= Date.now()) {
- controlLeases.delete(session.agentId)
- activeLease = undefined
- }
- const leased = activeLease || pinned ? await leasedTerminal(session) : null
- if ((activeLease || pinned) && !leased) return null
- const result = leased
- ? await terminals.captureLease(leased.value, { historyLines })
- : await terminals.capture(session, { historyLines })
- return result.state === 'succeeded' ? result.value : null
- }
- const terminalActionSucceeded = (result: Awaited<ReturnType<typeof terminals.submitText>>): boolean =>
- result.state === 'succeeded'
- const submitTerminalAction = async (target: string, text: string): Promise<TerminalActionResult> => {
- const session = terminalSession(target)
- if (!session) return terminalActionNotStarted('terminal agent is unavailable')
- const lease = await leasedTerminal(session)
- if (!lease) return terminalActionNotStarted('terminal control lease is unavailable or changed')
- const result = pinnedControls.has(session.agentId)
- ? await terminals.submitTextLease(lease.value, text)
- : await terminals.submitTextForLease(session, lease.value, text)
- if (result.state !== 'succeeded' && pinnedControls.has(session.agentId)) invalidateTerminalControl(session.agentId)
- return result
- }
- const submitTerminal = async (target: string, text: string): Promise<boolean> => {
- return terminalActionSucceeded(await submitTerminalAction(target, text))
- }
- const typeTerminal = async (target: string, text: string): Promise<boolean> => {
- const session = terminalSession(target)
- if (!session) return false
- const lease = await leasedTerminal(session)
- if (!lease) return false
- const succeeded = terminalActionSucceeded(await terminals.typeLiteralLease(lease.value, text))
- if (!succeeded && pinnedControls.has(session.agentId)) invalidateTerminalControl(session.agentId)
- return succeeded
- }
- const keyTerminalAction = async (target: string, key: string): Promise<TerminalActionResult> => {
- const session = terminalSession(target)
- if (!session) return terminalActionNotStarted('terminal session is unavailable')
- const lease = await leasedTerminal(session)
- if (!lease) return terminalActionNotStarted('terminal control lease is unavailable or changed')
- const result = await terminals.sendLegacyKeyLease(lease.value, key)
- if (result.state !== 'succeeded' && pinnedControls.has(session.agentId)) invalidateTerminalControl(session.agentId)
- return result
- }
- const keyTerminal = async (target: string, key: string): Promise<boolean> => {
- return terminalActionSucceeded(await keyTerminalAction(target, key))
- }
- const validateTerminal = async (session: RegisteredSession): Promise<boolean> =>
- (await terminals.validate(session)).state === 'alive'
+ // Reading and writing panes through control leases (core/terminals/control.ts).
+ const terminalControl = createTerminalControl({ resolve: (target) => registry.resolve(target), terminals })
+ const pinnedControls = terminalControl.pinnedControls
+ const pinTerminalControl = terminalControl.pinTerminalControl
+ const invalidateTerminalControl = terminalControl.invalidateTerminalControl
+ const captureTerminal = terminalControl.captureTerminal
+ const submitTerminalAction = terminalControl.submitTerminalAction
+ const submitTerminal = terminalControl.submitTerminal
+ const typeTerminal = terminalControl.typeTerminal
+ const keyTerminalAction = terminalControl.keyTerminalAction
+ const keyTerminal = terminalControl.keyTerminal
+ const validateTerminal = terminalControl.validateTerminal
// Persisted records are not trusted blindly. The process reconciler below adopts a matching live
// runtime, replaces it immediately when PID/start-marker changed, and requires two successful misses
// before removing it. Probe errors leave the registry untouched.
@@ -1909,39 +1828,19 @@ async function runForeground(session: AuthSession | null): Promise<void> {
// NB: hooks are installed AFTER the hook server binds (below), with the port it actually got — the
// server may fall back to a free port if env.PORT is taken, and the hooks must point at the real one.
- const syncSession = createSessionSync({
+ // Telling the app and the dial about agents (core/agents/events.ts). The socket is read when each
+ // frame goes out: until it exists, frames are dropped, and start-up announces every agent again.
+ const agentEvents = createAgentEvents({
+ sink: () => backendRef,
terminalAvailable: (agentId) => registry.terminalAvailable(agentId),
+ resolve: (target) => registry.resolve(target),
+ stopped: (agentId) => stoppedAgents.get(agentId),
project: (s) => projectFrame(s, runtimeProfiles.selectedModel(s)),
- send: (frame) => backendRef?.send(frame),
- sendCommander: (frame) => backendRef?.sendCommander(frame),
- warn: (err) => console.error('[cli] announceSession failed:', err instanceof Error ? err.message : err),
})
- const announceRename = (s: RegisteredSession, opts: { device?: boolean } = {}): void => {
- if (isTerminalEngine(s.engine)) opts = { ...opts, device: false }
- const name = projectDisplayName(s)
- backendRef?.send({ type: 'agent_renamed', payload: { agentId: s.agentId, name, engine: s.engine } })
- if (opts.device !== false) backendRef?.sendCommander({ type: 'agent_renamed', payload: { agentId: s.agentId, name, engine: s.engine } })
- }
- agentTokenUsage.onChanged = (target) => {
- const current = registry.resolve(target.agentId)
- if (current?.sessionId === target.sessionId && current.engine === target.engine) {
- if (registry.terminalAvailable(current.agentId)) syncSession(current, { device: false })
- return
- }
- try {
- const saved = stoppedAgents.get(target.agentId)
- if (saved?.sessionId === target.sessionId && saved.engine === target.engine) {
- void backendRef?.publishStoppedAgent(saved).catch(() => {})
- }
- } catch { /* A concurrently removed archive has nothing to update. */ }
- }
- // New process observations, session bindings, runtime-profile changes, reconnects and periodic
- // reconciliation refresh web and device from the same authoritative snapshot. Device agent_synced is
- // idempotent and can upsert a sessionless tile, so re-announcing at bind is both safe and necessary.
- const announceSession = (s: RegisteredSession, opts: { device?: boolean } = {}): void => {
- syncSession(s, opts)
- announceRename(s, opts)
- }
+ const syncSession = agentEvents.syncSession
+ const announceRename = agentEvents.announceRename
+ agentTokenUsage.onChanged = agentEvents.onTokenUsageChanged
+ const announceSession = agentEvents.announceSession
// ── Domain-specific harness companions ──────────────────────────────────────────────────────────
// A DSH agent has two things beside its pane that the daemon owns for as long as the agent exists:
@@ -2254,12 +2153,13 @@ async function runForeground(session: AuthSession | null): Promise<void> {
void agentReconciler.trigger()
}
- // Per-session web turn-lifecycle state; the device mirror keeps its own state + recap.
- const turnStates = new Map<string, TurnState>()
- const codexNormalizers = new Map<string, CodexNormalizer>()
- const cursorNormalizers = new Map<string, CursorNormalizer>()
- const opencodeReaders = new Map<string, OpencodeReader>()
- const kiloReaders = new Map<string, KiloReader>()
+ // Each session's engine state, in one table (core/transcripts/normalizers.ts).
+ const normalizers = createSessionNormalizers()
+ const turnStates = normalizers.turnStates
+ const codexNormalizers = normalizers.codexNormalizers
+ const cursorNormalizers = normalizers.cursorNormalizers
+ const opencodeReaders = normalizers.opencodeReaders
+ const kiloReaders = normalizers.kiloReaders
/**
* Sessions that attached before their transcript existed, so nothing was folded and nothing has ever
* been streamed for them.
@@ -2283,32 +2183,17 @@ async function runForeground(session: AuthSession | null): Promise<void> {
* time.
*/
const replayedFirstTurn = new Set<string>()
- const piNormalizers = new Map<string, PiNormalizer>()
- const museNormalizers = new Map<string, MuseNormalizer>()
- const ampNormalizers = new Map<string, AmpNormalizer>()
- const grokNormalizers = new Map<string, GrokNormalizer>()
- const agyNormalizers = new Map<string, AgyNormalizer>()
- const copilotNormalizers = new Map<string, CopilotNormalizer>()
- const hermesReaders = new Map<string, HermesReader>()
- const devinReaders = new Map<string, DevinReader>()
- const commandcodeNormalizers = new Map<string, CommandCodeNormalizer>()
- /** Whether this session's engine state says a turn is open right now, whichever engine it is. */
- const sessionTurnState = (sessionId: string): boolean | undefined =>
- turnStates.get(sessionId)?.turnOpen
- ?? codexNormalizers.get(sessionId)?.turnOpen
- ?? cursorNormalizers.get(sessionId)?.turnOpen
- ?? opencodeReaders.get(sessionId)?.turnOpen
- ?? kiloReaders.get(sessionId)?.turnOpen
- ?? piNormalizers.get(sessionId)?.turnOpen
- ?? museNormalizers.get(sessionId)?.turnOpen
- ?? ampNormalizers.get(sessionId)?.turnOpen
- ?? grokNormalizers.get(sessionId)?.turnOpen
- ?? agyNormalizers.get(sessionId)?.turnOpen
- ?? copilotNormalizers.get(sessionId)?.turnOpen
- ?? hermesReaders.get(sessionId)?.turnOpen
- ?? devinReaders.get(sessionId)?.turnOpen
- ?? commandcodeNormalizers.get(sessionId)?.turnOpen
- const sessionTurnOpen = (sessionId: string): boolean => sessionTurnState(sessionId) ?? false
+ const piNormalizers = normalizers.piNormalizers
+ const museNormalizers = normalizers.museNormalizers
+ const ampNormalizers = normalizers.ampNormalizers
+ const grokNormalizers = normalizers.grokNormalizers
+ const agyNormalizers = normalizers.agyNormalizers
+ const copilotNormalizers = normalizers.copilotNormalizers
+ const hermesReaders = normalizers.hermesReaders
+ const devinReaders = normalizers.devinReaders
+ const commandcodeNormalizers = normalizers.commandcodeNormalizers
+ const sessionTurnState = normalizers.sessionTurnState
+ const sessionTurnOpen = normalizers.sessionTurnOpen
const watcher = new Watcher()
const codexActivity = new CodexActivityReader()
const runtimeActivity = new RuntimeActivityReader({
@@ -2415,22 +2300,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
handover: { hold: TailHold | null; next: number | null } = { hold: null, next: null },
): Promise<boolean> => {
if (!await validateTerminal(session)) return false
- if (!reset && (
- turnStates.has(session.sessionId)
- || codexNormalizers.has(session.sessionId)
- || cursorNormalizers.has(session.sessionId)
- || opencodeReaders.has(session.sessionId)
- || kiloReaders.has(session.sessionId)
- || piNormalizers.has(session.sessionId)
- || museNormalizers.has(session.sessionId)
- || ampNormalizers.has(session.sessionId)
- || grokNormalizers.has(session.sessionId)
- || agyNormalizers.has(session.sessionId)
- || copilotNormalizers.has(session.sessionId)
- || hermesReaders.has(session.sessionId)
- || devinReaders.has(session.sessionId)
- || commandcodeNormalizers.has(session.sessionId)
- )) {
+ if (!reset && normalizers.hasState(session.sessionId)) {
if (session.transcriptPath) {
const unseen = neverFoldedHistory.delete(session.sessionId)
await watcher.addSession(
@@ -3320,31 +3190,14 @@ async function runForeground(session: AuthSession | null): Promise<void> {
else if (doomed) registry.removeAgent(doomed.agentId)
else registry.remove(sessionId)
syncRecapPool()
- turnStates.delete(sessionId)
+ normalizers.forget(sessionId)
turnStartedAt.delete(sessionId)
- codexNormalizers.delete(sessionId)
- cursorNormalizers.delete(sessionId)
- opencodeReaders.get(sessionId)?.stop()
- opencodeReaders.delete(sessionId)
- kiloReaders.get(sessionId)?.stop()
- kiloReaders.delete(sessionId)
neverFoldedHistory.delete(sessionId)
// Both sets are per-session and must die with it: left behind they grow without bound in a daemon
// that runs for days, and a session forgotten then re-registered under the same id would inherit a
// stale "already replayed" and lose a first turn it was entitled to.
replayedFirstTurn.delete(sessionId)
- piNormalizers.delete(sessionId)
- museNormalizers.delete(sessionId)
- ampNormalizers.delete(sessionId)
- grokNormalizers.delete(sessionId)
- agyNormalizers.delete(sessionId)
- copilotNormalizers.delete(sessionId)
clearAgyIdleWatch(sessionId)
- hermesReaders.get(sessionId)?.stop()
- hermesReaders.delete(sessionId)
- devinReaders.get(sessionId)?.stop()
- devinReaders.delete(sessionId)
- commandcodeNormalizers.delete(sessionId)
cursorDiscovery.remove(sessionId)
cursorSubagents.forget(sessionId)
void removeCursorPendingTasks(env.ADAPTER_DATA_DIR, sessionId)
@@ -5329,20 +5182,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
const cancelAgent = (id: string, confirmed = false): Promise<boolean> => {
const record = registry.resolve(id)
const sessionId = record?.sessionId ?? id
- const st = turnStates.get(sessionId)
- if (st) st.turnOpen = false
- codexNormalizers.get(sessionId)?.closeTurn()
- cursorNormalizers.get(sessionId)?.closeTurn()
- opencodeReaders.get(sessionId)?.closeTurn()
- piNormalizers.get(sessionId)?.closeTurn()
- museNormalizers.get(sessionId)?.closeTurn()
- ampNormalizers.get(sessionId)?.closeTurn()
- grokNormalizers.get(sessionId)?.closeTurn()
- agyNormalizers.get(sessionId)?.closeTurn()
- copilotNormalizers.get(sessionId)?.closeTurn()
- hermesReaders.get(sessionId)?.closeTurn()
- devinReaders.get(sessionId)?.closeTurn()
- commandcodeNormalizers.get(sessionId)?.closeTurn()
+ normalizers.closeTurns(sessionId)
cursorSubagents.forget(sessionId)
const cancelled = confirmed ? input.cancelConfirmed(record?.agentId ?? sessionId) : (input.cancel(record?.agentId ?? sessionId), Promise.resolve(true))
autonomousDeviceService?.turnEnded(record?.agentId ?? sessionId, true)
@@ -6461,9 +6301,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
for (const t of heartbeats.values()) clearInterval(t)
heartbeats.clear()
cursorSubagents.stop()
- for (const r of opencodeReaders.values()) r.stop()
- for (const r of hermesReaders.values()) r.stop()
- for (const r of devinReaders.values()) r.stop()
+ normalizers.stopPollers()
await cursorDiscovery.stop()
await watcher.stop()
// Fully release the FIXED hook port BEFORE the child binds (no fallback → EADDRINUSE otherwise).
@@ -6581,9 +6419,7 @@ async function runForeground(session: AuthSession | null): Promise<void> {
for (const t of heartbeats.values()) clearInterval(t)
heartbeats.clear()
cursorSubagents.stop()
- for (const r of opencodeReaders.values()) r.stop()
- for (const r of hermesReaders.values()) r.stop()
- for (const r of devinReaders.values()) r.stop()
+ normalizers.stopPollers()
await cursorDiscovery.stop()
await watcher.stop()
shareRelay.close()
diff --git a/cli/src/core/agents/events.spec.ts b/cli/src/core/agents/events.spec.ts
new file mode 100644
index 000000000..cc762d9e7
--- /dev/null
+++ b/cli/src/core/agents/events.spec.ts
@@ -0,0 +1,125 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type { AgentFrame } from '../../lib/agentFrame.js'
+import type { RegisteredSession } from '../../lib/registry.js'
+import { createAgentEvents, type AgentEventDeps, type AnnounceSink } from './events.js'
+
+const agent = (over: Partial<RegisteredSession> = {}): RegisteredSession =>
+ ({ agentId: 'a1', sessionId: 's1', engine: 'claude', cwd: '/work/app', ...over }) as RegisteredSession
+
+function sink() {
+ const app: Array<{ type: string; payload: Record<string, unknown> }> = []
+ const dial: Array<{ type: string; payload: Record<string, unknown> }> = []
+ const published: string[] = []
+ let publishFails = false
+ const socket: AnnounceSink = {
+ send: (frame) => { app.push(frame) },
+ sendCommander: (frame) => { dial.push(frame) },
+ publishStoppedAgent: async (s) => {
+ published.push(s.agentId)
+ if (publishFails) throw new Error('socket closed')
+ },
+ }
+ return { socket, app, dial, published, failPublish: () => { publishFails = true } }
+}
+
+/** Lets the async sync (project → send) finish. */
+const settle = () => new Promise((done) => setTimeout(done, 0))
+
+function events(over: Partial<AgentEventDeps> = {}, socket?: AnnounceSink) {
+ const live = new Map<string, RegisteredSession>([['a1', agent()]])
+ return createAgentEvents({
+ sink: () => socket,
+ terminalAvailable: () => true,
+ resolve: (target) => live.get(target),
+ stopped: () => null,
+ project: async (s) => ({ id: s.agentId }) as unknown as AgentFrame,
+ ...over,
+ })
+}
+
+describe('agent events', () => {
+ afterEach(() => vi.restoreAllMocks())
+
+ it('announces an agent to the app and the dial: its frame, then its name', async () => {
+ const out = sink()
+ events({}, out.socket).announceSession(agent())
+ await settle()
+ expect(out.app.map((frame) => frame.type)).toEqual(['agent_renamed', 'agent_synced'])
+ expect(out.dial.map((frame) => frame.type)).toEqual(['agent_renamed', 'agent_synced'])
+ expect(out.app[0].payload).toEqual({ agentId: 'a1', name: expect.any(String), engine: 'claude' })
+ expect(out.app[1].payload).toEqual({ agent: { id: 'a1' } })
+ })
+
+ it('keeps a plain terminal, and anything told so, off the dial', async () => {
+ const out = sink()
+ const announce = events({}, out.socket)
+ announce.announceRename(agent({ engine: 'terminal' }))
+ announce.announceSession(agent(), { device: false })
+ await settle()
+ expect(out.app.map((frame) => frame.type)).toEqual(['agent_renamed', 'agent_renamed', 'agent_synced'])
+ expect(out.dial).toEqual([])
+ })
+
+ it('drops frames while there is no socket yet', async () => {
+ const announce = events()
+ expect(() => announce.announceSession(agent())).not.toThrow()
+ await settle()
+ })
+
+ it('says so when a frame cannot be built, and carries on', async () => {
+ const out = sink()
+ const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+ const announce = events({ project: async () => { throw new Error('no transcript') } }, out.socket)
+ announce.syncSession(agent())
+ await settle()
+ events({ project: async () => { throw 'gone' } }, out.socket).syncSession(agent())
+ await settle()
+ expect(error.mock.calls).toEqual([
+ ['[cli] announceSession failed:', 'no transcript'],
+ ['[cli] announceSession failed:', 'gone'],
+ ])
+ expect(out.app).toEqual([])
+ })
+
+ it('refreshes a live agent on the app alone when its token usage moves', async () => {
+ const out = sink()
+ events({}, out.socket).onTokenUsageChanged({ agentId: 'a1', sessionId: 's1', engine: 'claude' })
+ await settle()
+ expect(out.app.map((frame) => frame.type)).toEqual(['agent_synced'])
+ expect(out.dial).toEqual([])
+ })
+
+ it('leaves a live agent whose pane is not available yet alone', async () => {
+ const out = sink()
+ events({ terminalAvailable: () => false }, out.socket).onTokenUsageChanged({ agentId: 'a1', sessionId: 's1', engine: 'claude' })
+ await settle()
+ expect(out.app).toEqual([])
+ })
+
+ it('republishes a stopped agent whose usage moved, and nothing for anyone else', async () => {
+ const out = sink()
+ const saved = agent({ agentId: 'a2', sessionId: 's2' })
+ const announce = events({ stopped: (agentId) => agentId === 'a2' ? saved : null }, out.socket)
+ announce.onTokenUsageChanged({ agentId: 'a2', sessionId: 's2', engine: 'claude' })
+ // Another session of the same agent, or an engine it no longer runs: not this record.
+ announce.onTokenUsageChanged({ agentId: 'a2', sessionId: 'older', engine: 'claude' })
+ announce.onTokenUsageChanged({ agentId: 'a2', sessionId: 's2', engine: 'codex' })
+ // The live agent's earlier session: not live, and not archived either.
+ announce.onTokenUsageChanged({ agentId: 'a1', sessionId: 'older', engine: 'claude' })
+ await settle()
+ expect(out.published).toEqual(['a2'])
+ expect(out.app).toEqual([])
+ })
+
+ it('shrugs off a stopped record that is being removed, or a publish that fails', async () => {
+ const out = sink()
+ events({ stopped: () => { throw new Error('archive moved') } }, out.socket)
+ .onTokenUsageChanged({ agentId: 'a2', sessionId: 's2', engine: 'claude' })
+ out.failPublish()
+ const saved = agent({ agentId: 'a2', sessionId: 's2' })
+ events({ stopped: () => saved }, out.socket).onTokenUsageChanged({ agentId: 'a2', sessionId: 's2', engine: 'claude' })
+ events({ stopped: () => saved }).onTokenUsageChanged({ agentId: 'a2', sessionId: 's2', engine: 'claude' })
+ await settle()
+ expect(out.published).toEqual(['a2'])
+ })
+})
diff --git a/cli/src/core/agents/events.ts b/cli/src/core/agents/events.ts
new file mode 100644
index 000000000..f0894822a
--- /dev/null
+++ b/cli/src/core/agents/events.ts
@@ -0,0 +1,72 @@
+/**
+ * Telling the app and the dial about an agent: its frame (sync), its name (rename), both at once
+ * (announce), and a fresh frame when its token usage moves, for a live agent or a stopped one.
+ *
+ * Moved verbatim out of `runForeground` (the core boundary, step 3: docs/design/2026-10-03-harnessd.md);
+ * the registry, the stopped-agent archive and the socket are passed in.
+ */
+import { isTerminalEngine } from '../../engines/types.js'
+import type { AgentFrame } from '../../lib/agentFrame.js'
+import { projectDisplayName, type RegisteredSession } from '../../lib/registry.js'
+import { createSessionSync } from '../../lib/sessionSync.js'
+
+type Frame = { type: string; payload: Record<string, unknown> }
+
+/** Where announcements go: the app (`send`) and the dial (`sendCommander`). */
+export interface AnnounceSink {
+ send(frame: Frame): void
+ sendCommander(frame: Frame): void
+ publishStoppedAgent(s: RegisteredSession): Promise<void>
+}
+
+/** The agent whose token usage changed, as the usage cache names it. */
+export type TokenUsageTarget = Pick<RegisteredSession, 'agentId' | 'sessionId' | 'engine'>
+
+export interface AgentEventDeps {
+ /** The socket, read as each frame goes out; undefined until it exists. */
+ sink: () => AnnounceSink | undefined
+ terminalAvailable: (agentId: string) => boolean
+ resolve: (target: string) => RegisteredSession | undefined
+ /** A stopped agent's archived record (stoppedAgents.get), which may throw while it is being removed. */
+ stopped: (agentId: string) => RegisteredSession | null
+ project: (s: RegisteredSession) => Promise<AgentFrame>
+}
+
+export function createAgentEvents({ sink, terminalAvailable, resolve, stopped, project }: AgentEventDeps) {
+ const syncSession = createSessionSync({
+ terminalAvailable: (agentId) => terminalAvailable(agentId),
+ project: (s) => project(s),
+ send: (frame) => sink()?.send(frame),
+ sendCommander: (frame) => sink()?.sendCommander(frame),
+ warn: (err) => console.error('[cli] announceSession failed:', err instanceof Error ? err.message : err),
+ })
+ const announceRename = (s: RegisteredSession, opts: { device?: boolean } = {}): void => {
+ if (isTerminalEngine(s.engine)) opts = { ...opts, device: false }
+ const name = projectDisplayName(s)
+ sink()?.send({ type: 'agent_renamed', payload: { agentId: s.agentId, name, engine: s.engine } })
+ if (opts.device !== false) sink()?.sendCommander({ type: 'agent_renamed', payload: { agentId: s.agentId, name, engine: s.engine } })
+ }
+ const onTokenUsageChanged = (target: TokenUsageTarget): void => {
+ const current = resolve(target.agentId)
+ if (current?.sessionId === target.sessionId && current.engine === target.engine) {
+ if (terminalAvailable(current.agentId)) syncSession(current, { device: false })
+ return
+ }
+ try {
+ const saved = stopped(target.agentId)
+ if (saved?.sessionId === target.sessionId && saved.engine === target.engine) {
+ void sink()?.publishStoppedAgent(saved).catch(() => {})
+ }
+ } catch { /* A concurrently removed archive has nothing to update. */ }
+ }
+ // New process observations, session bindings, runtime-profile changes, reconnects and periodic
+ // reconciliation refresh web and device from the same authoritative snapshot. Device agent_synced is
+ // idempotent and can upsert a sessionless tile, so re-announcing at bind is both safe and necessary.
+ const announceSession = (s: RegisteredSession, opts: { device?: boolean } = {}): void => {
+ syncSession(s, opts)
+ announceRename(s, opts)
+ }
+ return { syncSession, announceRename, announceSession, onTokenUsageChanged }
+}
+
+export type AgentEvents = ReturnType<typeof createAgentEvents>
diff --git a/cli/src/core/terminals/control.spec.ts b/cli/src/core/terminals/control.spec.ts
new file mode 100644
index 000000000..80133d88a
--- /dev/null
+++ b/cli/src/core/terminals/control.spec.ts
@@ -0,0 +1,213 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { RegisteredSession } from '../../lib/registry.js'
+import type { TerminalActionResult } from '../../lib/terminalTypes.js'
+import { createTerminalControl, type TerminalControlBackend } from './control.js'
+
+const ok: TerminalActionResult = { state: 'succeeded', dispatch: 'executed' }
+const lost: TerminalActionResult = { state: 'unknown', dispatch: 'possibly_executed', reason: 'pane went away' }
+
+/** A backend whose leases are numbered, so a test can tell a reused lease from a new one. */
+function backend() {
+ let issued = 0
+ const calls: string[] = []
+ const fake = {
+ calls,
+ acquire: true,
+ valid: true,
+ action: ok,
+ captured: { state: 'succeeded', value: 'screen' } as { state: 'succeeded'; value: string } | { state: 'failed'; reason: string },
+ alive: true,
+ }
+ const terminals = {
+ acquireLease: vi.fn(async () => {
+ if (!fake.acquire) return { state: 'failed', reason: 'busy' }
+ issued++
+ calls.push(`acquire ${issued}`)
+ return { state: 'succeeded', value: { id: issued } }
+ }),
+ validateLease: vi.fn(async (lease: { id: number }) => { calls.push(`validate ${lease.id}`); return fake.valid }),
+ capture: vi.fn(async (_session: RegisteredSession, options?: { historyLines?: number }) => {
+ calls.push(`capture ${options?.historyLines ?? '-'}`)
+ return fake.captured
+ }),
+ captureLease: vi.fn(async (lease: { id: number }) => { calls.push(`captureLease ${lease.id}`); return fake.captured }),
+ submitText: vi.fn(async () => ok),
+ submitTextLease: vi.fn(async (lease: { id: number }, text: string) => { calls.push(`submitTextLease ${lease.id} ${text}`); return fake.action }),
+ submitTextForLease: vi.fn(async (_session: RegisteredSession, lease: { id: number }, text: string) => {
+ calls.push(`submitTextForLease ${lease.id} ${text}`)
+ return fake.action
+ }),
+ typeLiteralLease: vi.fn(async (lease: { id: number }, text: string) => { calls.push(`type ${lease.id} ${text}`); return fake.action }),
+ sendLegacyKeyLease: vi.fn(async (lease: { id: number }, key: string) => { calls.push(`key ${lease.id} ${key}`); return fake.action }),
+ validate: vi.fn(async () => fake.alive ? { state: 'alive' } : { state: 'gone', reason: 'exited' }),
+ }
+ return { fake, terminals: terminals as unknown as TerminalControlBackend }
+}
+
+const session = { agentId: 'agent-1', sessionId: 'session-1' } as RegisteredSession
+const resolve = (target: string): RegisteredSession | undefined =>
+ target === 'agent-1' || target === 'session-1' ? session : undefined
+
+describe('terminal control', () => {
+ beforeEach(() => vi.useFakeTimers())
+ afterEach(() => vi.useRealTimers())
+
+ it('answers nothing for a pane it cannot find', async () => {
+ const { terminals } = backend()
+ const control = createTerminalControl({ resolve, terminals })
+ expect(await control.captureTerminal('nobody')).toBeNull()
+ expect(await control.submitTerminalAction('nobody', 'hi')).toEqual({ state: 'failed', dispatch: 'not_started', reason: 'terminal agent is unavailable' })
+ expect(await control.submitTerminal('nobody', 'hi')).toBe(false)
+ expect(await control.typeTerminal('nobody', 'hi')).toBe(false)
+ expect(await control.keyTerminalAction('nobody', 'enter')).toEqual({ state: 'failed', dispatch: 'not_started', reason: 'terminal session is unavailable' })
+ expect(await control.keyTerminal('nobody', 'enter')).toBe(false)
+ expect(control.pinTerminalControl('nobody')).toBeNull()
+ })
+
+ it('reads a pane without a lease until one is taken, then through it while it lasts', async () => {
+ const { fake, terminals } = backend()
+ const control = createTerminalControl({ resolve, terminals })
+ expect(await control.captureTerminal('agent-1', 40)).toBe('screen')
+ expect(await control.submitTerminal('agent-1', 'one')).toBe(true)
+ expect(await control.captureTerminal('session-1')).toBe('screen')
+ // Quiet for longer than the lease's idle time: the lease lapses and reads go back to plain capture.
+ vi.advanceTimersByTime(15_001)
+ expect(await control.captureTerminal('agent-1')).toBe('screen')
+ fake.captured = { state: 'failed', reason: 'no pane' }
+ expect(await control.captureTerminal('agent-1')).toBeNull()
+ expect(fake.calls).toEqual([
+ 'capture 40',
+ 'acquire 1', 'submitTextForLease 1 one',
+ 'validate 1', 'captureLease 1',
+ 'capture -',
+ 'capture -',
+ ])
+ })
+
+ it('keeps a lease while it is used, and takes a new one once it lapses or stops validating', async () => {
+ const { fake, terminals } = backend()
+ const control = createTerminalControl({ resolve, terminals })
+ await control.submitTerminal('agent-1', 'a')
+ vi.advanceTimersByTime(10_000)
+ await control.typeTerminal('agent-1', 'b') // within 15 s: the same lease, and its clock starts over
+ vi.advanceTimersByTime(10_000)
+ await control.keyTerminal('agent-1', 'enter') // 20 s after the first use, 10 s after the last
+ vi.advanceTimersByTime(15_001)
+ await control.submitTerminal('agent-1', 'c') // lapsed: a new lease
+ fake.valid = false
+ // No longer valid: this action fails rather than land in a pane that changed, and the lease goes…
+ expect(await control.submitTerminal('agent-1', 'd')).toBe(false)
+ fake.valid = true
+ // …so the next action takes a new one.
+ expect(await control.submitTerminal('agent-1', 'e')).toBe(true)
+ expect(fake.calls).toEqual([
+ 'acquire 1', 'submitTextForLease 1 a',
+ 'validate 1', 'type 1 b',
+ 'validate 1', 'key 1 enter',
+ 'acquire 2', 'submitTextForLease 2 c',
+ 'validate 2',
+ 'acquire 3', 'submitTextForLease 3 e',
+ ])
+ })
+
+ it('reports when no lease can be had', async () => {
+ const { fake, terminals } = backend()
+ const control = createTerminalControl({ resolve, terminals })
+ fake.acquire = false
+ expect(await control.submitTerminalAction('agent-1', 'x')).toEqual({ state: 'failed', dispatch: 'not_started', reason: 'terminal control lease is unavailable or changed' })
+ expect(await control.typeTerminal('agent-1', 'x')).toBe(false)
+ expect(await control.keyTerminalAction('agent-1', 'enter')).toEqual({ state: 'failed', dispatch: 'not_started', reason: 'terminal control lease is unavailable or changed' })
+ expect(fake.calls).toEqual([])
+ })
+
+ it('holds a pinned pane on one lease for as long as it is pinned, however long it is quiet', async () => {
+ const { fake, terminals } = backend()
+ const control = createTerminalControl({ resolve, terminals })
+ const release = control.pinTerminalControl('agent-1')!
+ expect(release).toBeTypeOf('function')
+ expect(control.pinTerminalControl('agent-1'), 'a pane is pinned once at a time').toBeNull()
+ expect(control.pinnedControls.has('agent-1')).toBe(true)
+ expect(await control.captureTerminal('agent-1')).toBe('screen') // pinned: read through a lease
+ vi.advanceTimersByTime(60_000)
+ expect(await control.submitTerminal('agent-1', 'go')).toBe(true) // still the same lease, through the pinned path
+ release()
+ expect(control.pinnedControls.has('agent-1')).toBe(false)
+ expect(await control.submitTerminal('agent-1', 'after')).toBe(true) // the pinned lease went with the pin
+ expect(fake.calls).toEqual([
+ 'acquire 1', 'captureLease 1',
+ 'validate 1', 'submitTextLease 1 go',
+ 'acquire 2', 'submitTextForLease 2 after',
+ ])
+ })
+
+ it('fails every action on a pinned pane whose lease stopped validating, until it is unpinned', async () => {
+ const { fake, terminals } = backend()
+ const control = createTerminalControl({ resolve, terminals })
+ const release = control.pinTerminalControl('agent-1')!
+ await control.submitTerminal('agent-1', 'first')
+ fake.valid = false
+ expect(await control.submitTerminal('agent-1', 'second')).toBe(false)
+ fake.valid = true
+ // Never quietly replaced: the pane may have changed under the sequence.
+ expect(await control.captureTerminal('agent-1')).toBeNull()
+ expect(await control.typeTerminal('agent-1', 'third')).toBe(false)
+ release()
+ expect(await control.typeTerminal('agent-1', 'fourth')).toBe(true)
+ expect(fake.calls).toEqual(['acquire 1', 'submitTextLease 1 first', 'validate 1', 'acquire 2', 'type 2 fourth'])
+ })
+
+ it('a pinned pane that cannot get a lease cannot be read either', async () => {
+ const { fake, terminals } = backend()
+ const control = createTerminalControl({ resolve, terminals })
+ control.pinTerminalControl('agent-1')
+ fake.acquire = false
+ expect(await control.captureTerminal('agent-1')).toBeNull()
+ expect(fake.calls).toEqual([])
+ })
+
+ it('stops a pinned sequence after any action that did not go through', async () => {
+ for (const act of ['submit', 'type', 'key'] as const) {
+ const { fake, terminals } = backend()
+ const control = createTerminalControl({ resolve, terminals })
+ control.pinTerminalControl('agent-1')
+ fake.action = lost
+ const first = act === 'submit' ? await control.submitTerminalAction('agent-1', 'x')
+ : act === 'type' ? await control.typeTerminal('agent-1', 'x')
+ : await control.keyTerminalAction('agent-1', 'enter')
+ expect(first === lost || first === false, act).toBe(true)
+ fake.action = ok
+ expect(await control.submitTerminal('agent-1', 'next'), `${act}: the next action fails`).toBe(false)
+ }
+ })
+
+ it('lets an unpinned pane go on after an action that did not go through', async () => {
+ const { fake, terminals } = backend()
+ const control = createTerminalControl({ resolve, terminals })
+ fake.action = lost
+ expect(await control.submitTerminalAction('agent-1', 'x')).toBe(lost)
+ expect(await control.typeTerminal('agent-1', 'x')).toBe(false)
+ expect(await control.keyTerminalAction('agent-1', 'enter')).toBe(lost)
+ fake.action = ok
+ expect(await control.submitTerminal('agent-1', 'next')).toBe(true)
+ })
+
+ it('invalidates a pane on request: an unpinned one just takes a new lease, a pinned one stops', async () => {
+ const { terminals, fake } = backend()
+ const control = createTerminalControl({ resolve, terminals })
+ await control.submitTerminal('agent-1', 'a')
+ control.invalidateTerminalControl('agent-1')
+ expect(await control.submitTerminal('agent-1', 'b')).toBe(true)
+ control.pinTerminalControl('agent-1')
+ control.invalidateTerminalControl('agent-1')
+ expect(await control.submitTerminal('agent-1', 'c')).toBe(false)
+ expect(fake.calls).toEqual(['acquire 1', 'submitTextForLease 1 a', 'acquire 2', 'submitTextForLease 2 b'])
+ })
+
+ it('says whether a pane is alive', async () => {
+ const { fake, terminals } = backend()
+ const control = createTerminalControl({ resolve, terminals })
+ expect(await control.validateTerminal(session)).toBe(true)
+ fake.alive = false
+ expect(await control.validateTerminal(session)).toBe(false)
+ })
+})
diff --git a/cli/src/core/terminals/control.ts b/cli/src/core/terminals/control.ts
new file mode 100644
index 000000000..02acbbce8
--- /dev/null
+++ b/cli/src/core/terminals/control.ts
@@ -0,0 +1,127 @@
+/**
+ * Terminal control: reading a pane and typing, submitting and sending keys to it, through a control
+ * lease: a short one that lapses after 15 s of quiet, or one pinned for as long as a caller holds the
+ * pane (a question being answered, a sequence of keys). A pinned lease that stops validating is not
+ * quietly replaced: every later action on that pane fails until it is unpinned, so a sequence never
+ * continues in a pane that changed under it.
+ *
+ * Moved verbatim out of `runForeground` (the core boundary, step 2: docs/design/2026-10-03-harnessd.md).
+ */
+import type { RegisteredSession } from '../../lib/registry.js'
+import type { TerminalBackendCoordinator } from '../../lib/terminalBackendCoordinator.js'
+import { terminalActionNotStarted, type TerminalActionResult } from '../../lib/terminalTypes.js'
+
+export type TerminalControlBackend = Pick<TerminalBackendCoordinator,
+ 'acquireLease' | 'validateLease' | 'capture' | 'captureLease' | 'submitText' | 'submitTextLease'
+ | 'submitTextForLease' | 'typeLiteralLease' | 'sendLegacyKeyLease' | 'validate'>
+
+export interface TerminalControlDeps {
+ /** The agent a target names: its agent id, session id or pane. */
+ resolve: (target: string) => RegisteredSession | undefined
+ terminals: TerminalControlBackend
+}
+
+export function createTerminalControl({ resolve, terminals }: TerminalControlDeps) {
+ const terminalSession = (target: string): RegisteredSession | undefined => resolve(target)
+ const controlLeases = new Map<string, { lease: Awaited<ReturnType<typeof terminals.acquireLease>> & { state: 'succeeded' }; expiresAt: number }>()
+ const pinnedControls = new Set<string>()
+ const invalidControls = new Set<string>()
+ const CONTROL_LEASE_IDLE_MS = 15_000
+ const leasedTerminal = async (session: RegisteredSession): Promise<Extract<Awaited<ReturnType<typeof terminals.acquireLease>>, { state: 'succeeded' }> | null> => {
+ const pinned = pinnedControls.has(session.agentId)
+ if (pinned && invalidControls.has(session.agentId)) return null
+ const current = controlLeases.get(session.agentId)
+ if (current && (pinned || current.expiresAt > Date.now())) {
+ if (!await terminals.validateLease(current.lease.value, session)) {
+ controlLeases.delete(session.agentId)
+ if (pinned) invalidControls.add(session.agentId)
+ return null
+ }
+ current.expiresAt = Date.now() + CONTROL_LEASE_IDLE_MS
+ return current.lease
+ }
+ controlLeases.delete(session.agentId)
+ const acquired = await terminals.acquireLease(session)
+ if (acquired.state !== 'succeeded') return null
+ const value = { lease: acquired, expiresAt: Date.now() + CONTROL_LEASE_IDLE_MS }
+ controlLeases.set(session.agentId, value)
+ return acquired
+ }
+ const pinTerminalControl = (target: string): (() => void) | null => {
+ const session = terminalSession(target)
+ if (!session || pinnedControls.has(session.agentId)) return null
+ pinnedControls.add(session.agentId)
+ invalidControls.delete(session.agentId)
+ return () => {
+ pinnedControls.delete(session.agentId)
+ invalidControls.delete(session.agentId)
+ controlLeases.delete(session.agentId)
+ }
+ }
+ const invalidateTerminalControl = (agentId: string): void => {
+ controlLeases.delete(agentId)
+ if (pinnedControls.has(agentId)) invalidControls.add(agentId)
+ }
+ const captureTerminal = async (target: string, historyLines?: number): Promise<string | null> => {
+ const session = terminalSession(target)
+ if (!session) return null
+ const pinned = pinnedControls.has(session.agentId)
+ if (pinned && invalidControls.has(session.agentId)) return null
+ let activeLease = controlLeases.get(session.agentId)
+ if (activeLease && !pinned && activeLease.expiresAt <= Date.now()) {
+ controlLeases.delete(session.agentId)
+ activeLease = undefined
+ }
+ const leased = activeLease || pinned ? await leasedTerminal(session) : null
+ if ((activeLease || pinned) && !leased) return null
+ const result = leased
+ ? await terminals.captureLease(leased.value, { historyLines })
+ : await terminals.capture(session, { historyLines })
+ return result.state === 'succeeded' ? result.value : null
+ }
+ const terminalActionSucceeded = (result: Awaited<ReturnType<typeof terminals.submitText>>): boolean =>
+ result.state === 'succeeded'
+ const submitTerminalAction = async (target: string, text: string): Promise<TerminalActionResult> => {
+ const session = terminalSession(target)
+ if (!session) return terminalActionNotStarted('terminal agent is unavailable')
+ const lease = await leasedTerminal(session)
+ if (!lease) return terminalActionNotStarted('terminal control lease is unavailable or changed')
+ const result = pinnedControls.has(session.agentId)
+ ? await terminals.submitTextLease(lease.value, text)
+ : await terminals.submitTextForLease(session, lease.value, text)
+ if (result.state !== 'succeeded' && pinnedControls.has(session.agentId)) invalidateTerminalControl(session.agentId)
+ return result
+ }
+ const submitTerminal = async (target: string, text: string): Promise<boolean> => {
+ return terminalActionSucceeded(await submitTerminalAction(target, text))
+ }
+ const typeTerminal = async (target: string, text: string): Promise<boolean> => {
+ const session = terminalSession(target)
+ if (!session) return false
+ const lease = await leasedTerminal(session)
+ if (!lease) return false
+ const succeeded = terminalActionSucceeded(await terminals.typeLiteralLease(lease.value, text))
+ if (!succeeded && pinnedControls.has(session.agentId)) invalidateTerminalControl(session.agentId)
+ return succeeded
+ }
+ const keyTerminalAction = async (target: string, key: string): Promise<TerminalActionResult> => {
+ const session = terminalSession(target)
+ if (!session) return terminalActionNotStarted('terminal session is unavailable')
+ const lease = await leasedTerminal(session)
+ if (!lease) return terminalActionNotStarted('terminal control lease is unavailable or changed')
+ const result = await terminals.sendLegacyKeyLease(lease.value, key)
+ if (result.state !== 'succeeded' && pinnedControls.has(session.agentId)) invalidateTerminalControl(session.agentId)
+ return result
+ }
+ const keyTerminal = async (target: string, key: string): Promise<boolean> => {
+ return terminalActionSucceeded(await keyTerminalAction(target, key))
+ }
+ const validateTerminal = async (session: RegisteredSession): Promise<boolean> =>
+ (await terminals.validate(session)).state === 'alive'
+ return {
+ pinnedControls, pinTerminalControl, invalidateTerminalControl, captureTerminal, submitTerminalAction,
+ submitTerminal, typeTerminal, keyTerminalAction, keyTerminal, validateTerminal,
+ }
+}
+
+export type TerminalControl = ReturnType<typeof createTerminalControl>
diff --git a/cli/src/core/transcripts/normalizers.spec.ts b/cli/src/core/transcripts/normalizers.spec.ts
new file mode 100644
index 000000000..5a756b874
--- /dev/null
+++ b/cli/src/core/transcripts/normalizers.spec.ts
@@ -0,0 +1,107 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { TurnState } from '../../lib/normalize.js'
+import { createSessionNormalizers, type SessionNormalizers } from './normalizers.js'
+
+/** Every engine map in the table, in the order a turn's state is looked up. */
+const ENGINE_MAPS = [
+ 'codexNormalizers', 'cursorNormalizers', 'opencodeReaders', 'kiloReaders', 'piNormalizers', 'museNormalizers',
+ 'ampNormalizers', 'grokNormalizers', 'agyNormalizers', 'copilotNormalizers', 'hermesReaders', 'devinReaders',
+ 'commandcodeNormalizers',
+] as const
+type EngineMap = typeof ENGINE_MAPS[number]
+const DATABASE_READERS: EngineMap[] = ['opencodeReaders', 'kiloReaders', 'hermesReaders', 'devinReaders']
+
+/** A normalizer or reader with only what the table touches. */
+const fake = (turnOpen: boolean | undefined = false) => ({ turnOpen, closeTurn: vi.fn(() => []), stop: vi.fn() })
+type Fake = ReturnType<typeof fake>
+
+function put(table: SessionNormalizers, map: EngineMap, sessionId: string, entry: Fake): void {
+ (table[map] as Map<string, unknown>).set(sessionId, entry)
+}
+
+describe('the session normalizer table', () => {
+ it('has state for a session that any engine map holds, and none for one that none does', () => {
+ const table = createSessionNormalizers()
+ expect(table.hasState('s')).toBe(false)
+ table.turnStates.set('s', { turnOpen: false } as TurnState)
+ expect(table.hasState('s')).toBe(true)
+ for (const map of ENGINE_MAPS) {
+ const one = createSessionNormalizers()
+ put(one, map, 's', fake())
+ expect(one.hasState('s'), map).toBe(true)
+ expect(one.hasState('other'), map).toBe(false)
+ }
+ })
+
+ it('reads whether a turn is open from Claude Code\'s state first, then each engine in turn', () => {
+ const table = createSessionNormalizers()
+ expect(table.sessionTurnState('s')).toBeUndefined()
+ expect(table.sessionTurnOpen('s')).toBe(false)
+ for (const map of ENGINE_MAPS) {
+ const one = createSessionNormalizers()
+ put(one, map, 's', fake(true))
+ expect(one.sessionTurnState('s'), map).toBe(true)
+ expect(one.sessionTurnOpen('s'), map).toBe(true)
+ }
+ // The first engine that knows wins, even when it says closed: Claude Code's state before Codex's, Codex
+ // before Cursor, and so on down the list.
+ table.turnStates.set('s', { turnOpen: false } as TurnState)
+ put(table, 'codexNormalizers', 's', fake(true))
+ expect(table.sessionTurnState('s')).toBe(false)
+ table.turnStates.delete('s')
+ put(table, 'cursorNormalizers', 's', fake(false))
+ expect(table.sessionTurnState('s')).toBe(true)
+ })
+
+ it('forgets a session in every map, stopping its database readers, and leaves other sessions alone', () => {
+ const table = createSessionNormalizers()
+ table.turnStates.set('s', { turnOpen: true } as TurnState)
+ table.turnStates.set('keep', { turnOpen: true } as TurnState)
+ const entries = new Map<EngineMap, Fake>()
+ for (const map of ENGINE_MAPS) {
+ entries.set(map, fake())
+ put(table, map, 's', entries.get(map)!)
+ put(table, map, 'keep', fake())
+ }
+ table.forget('s')
+ expect(table.hasState('s')).toBe(false)
+ expect(table.turnStates.has('keep')).toBe(true)
+ for (const map of ENGINE_MAPS) {
+ expect(table[map].has('keep'), map).toBe(true)
+ expect(entries.get(map)!.stop, map).toHaveBeenCalledTimes(DATABASE_READERS.includes(map) ? 1 : 0)
+ }
+ expect(() => table.forget('never-seen')).not.toThrow()
+ })
+
+ it('closes a cancelled turn in every engine', () => {
+ const table = createSessionNormalizers()
+ const state = { turnOpen: true } as TurnState
+ table.turnStates.set('s', state)
+ const entries = new Map<EngineMap, Fake>()
+ for (const map of ENGINE_MAPS) {
+ entries.set(map, fake(true))
+ put(table, map, 's', entries.get(map)!)
+ }
+ table.closeTurns('s')
+ expect(state.turnOpen).toBe(false)
+ for (const map of ENGINE_MAPS) {
+ // Kilo's included: it used to be missed, so a cancelled Kilo agent could go on showing as working.
+ expect(entries.get(map)!.closeTurn, map).toHaveBeenCalledTimes(1)
+ }
+ expect(() => table.closeTurns('never-seen')).not.toThrow()
+ })
+
+ it('stops every database reader\'s poller on shutdown, and touches nothing else', () => {
+ const table = createSessionNormalizers()
+ const entries = new Map<EngineMap, Fake>()
+ for (const map of ENGINE_MAPS) {
+ entries.set(map, fake())
+ put(table, map, 's', entries.get(map)!)
+ }
+ table.stopPollers()
+ for (const map of ENGINE_MAPS) {
+ // Kilo's included: it used to be missed, and its poller ran on through the update handoff.
+ expect(entries.get(map)!.stop, map).toHaveBeenCalledTimes(DATABASE_READERS.includes(map) ? 1 : 0)
+ }
+ })
+})
diff --git a/cli/src/core/transcripts/normalizers.ts b/cli/src/core/transcripts/normalizers.ts
new file mode 100644
index 000000000..b23d73057
--- /dev/null
+++ b/cli/src/core/transcripts/normalizers.ts
@@ -0,0 +1,137 @@
+/**
+ * Each session's engine state: Claude Code's turn state, and the normalizer (an engine with a
+ * transcript file) or reader (an engine with a database) that folds every other engine's history.
+ * One table instead of fourteen maps, so the questions asked of all of them — does this session have
+ * any, is its turn open, forget it, close its turn, stop the pollers — each have one answer.
+ *
+ * The maps themselves stay public: attach and ingest create each engine's entry their own way, lazily
+ * for the file engines and never from ingest for the database readers.
+ *
+ * Moved out of `runForeground` (the core boundary, step 4: docs/design/2026-10-03-harnessd.md).
+ */
+import type { AgyNormalizer } from '../../engines/agy/normalizer.js'
+import type { AmpNormalizer } from '../../engines/amp/normalizer.js'
+import type { CodexNormalizer } from '../../engines/codex/normalizer.js'
+import type { CommandCodeNormalizer } from '../../engines/commandcode/normalizer.js'
+import type { CopilotNormalizer } from '../../engines/copilot/normalizer.js'
+import type { CursorNormalizer } from '../../engines/cursor/normalizer.js'
+import type { DevinReader } from '../../engines/devin/reader.js'
+import type { GrokNormalizer } from '../../engines/grok/normalizer.js'
+import type { HermesReader } from '../../engines/hermes/reader.js'
+import type { KiloReader } from '../../engines/kilo/reader.js'
+import type { MuseNormalizer } from '../../engines/muse/normalizer.js'
+import type { OpencodeReader } from '../../engines/opencode/reader.js'
+import type { PiNormalizer } from '../../engines/pi/normalizer.js'
+import type { TurnState } from '../../lib/normalize.js'
+
+export function createSessionNormalizers() {
+ // Per-session web turn-lifecycle state; the device mirror keeps its own state + recap.
+ const turnStates = new Map<string, TurnState>()
+ const codexNormalizers = new Map<string, CodexNormalizer>()
+ const cursorNormalizers = new Map<string, CursorNormalizer>()
+ const opencodeReaders = new Map<string, OpencodeReader>()
+ const kiloReaders = new Map<string, KiloReader>()
+ const piNormalizers = new Map<string, PiNormalizer>()
+ const museNormalizers = new Map<string, MuseNormalizer>()
+ const ampNormalizers = new Map<string, AmpNormalizer>()
+ const grokNormalizers = new Map<string, GrokNormalizer>()
+ const agyNormalizers = new Map<string, AgyNormalizer>()
+ const copilotNormalizers = new Map<string, CopilotNormalizer>()
+ const hermesReaders = new Map<string, HermesReader>()
+ const devinReaders = new Map<string, DevinReader>()
+ const commandcodeNormalizers = new Map<string, CommandCodeNormalizer>()
+
+ /** Whether this session's engine state says a turn is open right now, whichever engine it is. */
+ const sessionTurnState = (sessionId: string): boolean | undefined =>
+ turnStates.get(sessionId)?.turnOpen
+ ?? codexNormalizers.get(sessionId)?.turnOpen
+ ?? cursorNormalizers.get(sessionId)?.turnOpen
+ ?? opencodeReaders.get(sessionId)?.turnOpen
+ ?? kiloReaders.get(sessionId)?.turnOpen
+ ?? piNormalizers.get(sessionId)?.turnOpen
+ ?? museNormalizers.get(sessionId)?.turnOpen
+ ?? ampNormalizers.get(sessionId)?.turnOpen
+ ?? grokNormalizers.get(sessionId)?.turnOpen
+ ?? agyNormalizers.get(sessionId)?.turnOpen
+ ?? copilotNormalizers.get(sessionId)?.turnOpen
+ ?? hermesReaders.get(sessionId)?.turnOpen
+ ?? devinReaders.get(sessionId)?.turnOpen
+ ?? commandcodeNormalizers.get(sessionId)?.turnOpen
+ const sessionTurnOpen = (sessionId: string): boolean => sessionTurnState(sessionId) ?? false
+
+ /** Whether any engine state exists for this session: an attach that finds some is not a first one. */
+ const hasState = (sessionId: string): boolean =>
+ turnStates.has(sessionId)
+ || codexNormalizers.has(sessionId)
+ || cursorNormalizers.has(sessionId)
+ || opencodeReaders.has(sessionId)
+ || kiloReaders.has(sessionId)
+ || piNormalizers.has(sessionId)
+ || museNormalizers.has(sessionId)
+ || ampNormalizers.has(sessionId)
+ || grokNormalizers.has(sessionId)
+ || agyNormalizers.has(sessionId)
+ || copilotNormalizers.has(sessionId)
+ || hermesReaders.has(sessionId)
+ || devinReaders.has(sessionId)
+ || commandcodeNormalizers.has(sessionId)
+
+ /** Drop all of a forgotten session's engine state, stopping its database readers' pollers. */
+ const forget = (sessionId: string): void => {
+ turnStates.delete(sessionId)
+ codexNormalizers.delete(sessionId)
+ cursorNormalizers.delete(sessionId)
+ opencodeReaders.get(sessionId)?.stop()
+ opencodeReaders.delete(sessionId)
+ kiloReaders.get(sessionId)?.stop()
+ kiloReaders.delete(sessionId)
+ piNormalizers.delete(sessionId)
+ museNormalizers.delete(sessionId)
+ ampNormalizers.delete(sessionId)
+ grokNormalizers.delete(sessionId)
+ agyNormalizers.delete(sessionId)
+ copilotNormalizers.delete(sessionId)
+ hermesReaders.get(sessionId)?.stop()
+ hermesReaders.delete(sessionId)
+ devinReaders.get(sessionId)?.stop()
+ devinReaders.delete(sessionId)
+ commandcodeNormalizers.delete(sessionId)
+ }
+
+ /** Mark the session's turn closed in whichever engine holds it (a cancel). What a closing
+ * normalizer returns is not emitted: a cancel sends no turn end. */
+ const closeTurns = (sessionId: string): void => {
+ const st = turnStates.get(sessionId)
+ if (st) st.turnOpen = false
+ codexNormalizers.get(sessionId)?.closeTurn()
+ cursorNormalizers.get(sessionId)?.closeTurn()
+ opencodeReaders.get(sessionId)?.closeTurn()
+ kiloReaders.get(sessionId)?.closeTurn()
+ piNormalizers.get(sessionId)?.closeTurn()
+ museNormalizers.get(sessionId)?.closeTurn()
+ ampNormalizers.get(sessionId)?.closeTurn()
+ grokNormalizers.get(sessionId)?.closeTurn()
+ agyNormalizers.get(sessionId)?.closeTurn()
+ copilotNormalizers.get(sessionId)?.closeTurn()
+ hermesReaders.get(sessionId)?.closeTurn()
+ devinReaders.get(sessionId)?.closeTurn()
+ commandcodeNormalizers.get(sessionId)?.closeTurn()
+ }
+
+ /** Stop every database reader's poller (shutdown, and the handoff to an update). */
+ const stopPollers = (): void => {
+ for (const r of opencodeReaders.values()) r.stop()
+ for (const r of kiloReaders.values()) r.stop()
+ for (const r of hermesReaders.values()) r.stop()
+ for (const r of devinReaders.values()) r.stop()
+ }
+
+ return {
+ turnStates, codexNormalizers, cursorNormalizers, opencodeReaders, kiloReaders, piNormalizers,
+ museNormalizers, ampNormalizers, grokNormalizers, agyNormalizers, copilotNormalizers, hermesReaders,
+ devinReaders, commandcodeNormalizers,
+ sessionTurnState, sessionTurnOpen, hasState, forget, closeTurns, stopPollers,
+ }
+}
+
+export type SessionNormalizers = ReturnType<typeof createSessionNormalizers>
diff --git a/cli/src/harnessd/coreLink.spec.ts b/cli/src/harnessd/coreLink.spec.ts
index f750f8e5d..184dd8e34 100644
--- a/cli/src/harnessd/coreLink.spec.ts
+++ b/cli/src/harnessd/coreLink.spec.ts
@@ -1,5 +1,5 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { connectToMaster, processChannel, processLoopDelay, type LoopDelay, type MasterChannel } from './coreLink.js'
+import { connectToMaster, HEARTBEAT_INTERVAL_MS, heartbeatInterval, processChannel, processLoopDelay, type LoopDelay, type MasterChannel } from './coreLink.js'
import { HARNESSD_PROTOCOL, type CoreMessage } from './protocol.js'
class FakeChannel implements MasterChannel {
@@ -83,6 +83,16 @@ describe('connectToMaster', () => {
expect(loop.made[0].stopped).toBe(true)
})
+ it('beats well inside the silence its master allows', () => {
+ const channel = new FakeChannel()
+ const link = connectToMaster(channel, { ...supervised, HARNESSD_WATCHDOG_MS: '3000' }, undefined, delays().factory)
+ link.startHeartbeat()
+ vi.advanceTimersByTime(2_999)
+ link.close()
+ // One at once, then one a second: three inside the master's three seconds.
+ expect(channel.sent.filter((message) => message.type === 'harnessd:heartbeat')).toHaveLength(3)
+ })
+
it('says why when start-up gave way to safe mode', () => {
const channel = new FakeChannel()
connectToMaster(channel, supervised).ready('no tmux')
@@ -125,3 +135,17 @@ describe('connectToMaster', () => {
delay.stop()
})
})
+
+describe('heartbeatInterval', () => {
+ it('is a third of the master\'s watchdog, every 5 s at most and every 250 ms at the fastest', () => {
+ expect(heartbeatInterval({ HARNESSD_WATCHDOG_MS: '30000' })).toBe(HEARTBEAT_INTERVAL_MS)
+ expect(heartbeatInterval({ HARNESSD_WATCHDOG_MS: '3000' })).toBe(1000)
+ expect(heartbeatInterval({ HARNESSD_WATCHDOG_MS: '600' })).toBe(250)
+ })
+
+ it('is every 5 s without a watchdog, or with one that is not a positive number', () => {
+ for (const watchdog of [undefined, '', 'soon', '0', '-3000']) {
+ expect(heartbeatInterval(watchdog === undefined ? {} : { HARNESSD_WATCHDOG_MS: watchdog }), String(watchdog)).toBe(HEARTBEAT_INTERVAL_MS)
+ }
+ })
+})
diff --git a/cli/src/harnessd/coreLink.ts b/cli/src/harnessd/coreLink.ts
index 055c0463e..bcafec68a 100644
--- a/cli/src/harnessd/coreLink.ts
+++ b/cli/src/harnessd/coreLink.ts
@@ -33,6 +33,18 @@ export function processLoopDelay(): LoopDelay {
/** How often a core tells its master it is alive. The master's patience is several of these. */
export const HEARTBEAT_INTERVAL_MS = 5_000
+/**
+ * How often this core beats: a third of the silence its master allows (`HARNESSD_WATCHDOG_MS`), so a
+ * busy event loop still lands one inside it — systemd pings at half its WatchdogSec — and never less
+ * often than every 5 s, which keeps the memory figures the beats carry fresh. 250 ms at the fastest.
+ * Without a watchdog (an older master), every 5 s, which its 30 s default allows.
+ */
+export function heartbeatInterval(env: NodeJS.ProcessEnv): number {
+ const watchdog = Number(env.HARNESSD_WATCHDOG_MS)
+ if (!Number.isFinite(watchdog) || watchdog <= 0) return HEARTBEAT_INTERVAL_MS
+ return Math.min(HEARTBEAT_INTERVAL_MS, Math.max(250, Math.floor(watchdog / 3)))
+}
+
export interface MasterChannel {
send?: (message: CoreMessage) => unknown
once(event: 'disconnect', listener: () => void): unknown
@@ -53,7 +65,7 @@ export interface CoreLink {
/** Start-up is done and requests are served — or it gave way to safe mode, and why: the master stops
* waiting for it either way, and rolls back an update whose first core ends up in safe mode. */
ready(safeMode?: string): void
- /** Tell the master, every `HEARTBEAT_INTERVAL_MS`, that this core is alive and how big it is. */
+ /** Tell the master, every `heartbeatInterval`, that this core is alive and how big it is. */
startHeartbeat(): void
/** The master is gone. A core without one stops, so nothing is left holding the port. */
onMasterGone(listener: () => void): void
@@ -74,7 +86,7 @@ export const processChannel: MasterChannel = {
export function connectToMaster(
channel: MasterChannel = processChannel,
env: NodeJS.ProcessEnv = process.env,
- intervalMs = HEARTBEAT_INTERVAL_MS,
+ intervalMs = heartbeatInterval(env),
loopDelay: () => LoopDelay = processLoopDelay,
): CoreLink {
const supervised = env.HARNESSD_SUPERVISED === '1' && typeof channel.send === 'function'
diff --git a/cli/src/harnessd/master.spec.ts b/cli/src/harnessd/master.spec.ts
index 777f4ea69..58b36a06f 100644
--- a/cli/src/harnessd/master.spec.ts
+++ b/cli/src/harnessd/master.spec.ts
@@ -14,13 +14,13 @@ describe('supervisorOptions', () => {
it('reads valid overrides and keeps the defaults for anything unset or invalid', () => {
expect(supervisorOptions({})).toEqual(DEFAULT_SUPERVISOR_OPTIONS)
expect(supervisorOptions({
- HARNESSD_BIND_TIMEOUT_MS: '100', HARNESSD_READY_TIMEOUT_MS: '150', HARNESSD_HEARTBEAT_TIMEOUT_MS: '200',
+ HARNESSD_BIND_TIMEOUT_MS: '100', HARNESSD_READY_TIMEOUT_MS: '150', HARNESSD_HEARTBEAT_TIMEOUT_MS: '1000',
HARNESSD_STOP_GRACE_MS: '300', HARNESSD_INITIAL_BACKOFF_MS: '0', HARNESSD_MAX_BACKOFF_MS: '50',
HARNESSD_BACKOFF_RESET_MS: '0', HARNESSD_HEAP_LIMIT_MIB: '512', HARNESSD_HEAP_RESTART_PERCENT: '90',
HARNESSD_RSS_LIMIT_MIB: '0', HARNESSD_UPDATE_PROBATION_MS: '10', HARNESSD_CRASH_LOOP_CRASHES: '5',
HARNESSD_CRASH_LOOP_WINDOW_MS: '1000',
})).toEqual({
- bindTimeoutMs: 100, readyTimeoutMs: 150, heartbeatTimeoutMs: 200, stopGraceMs: 300, initialBackoffMs: 0,
+ bindTimeoutMs: 100, readyTimeoutMs: 150, heartbeatTimeoutMs: 1000, stopGraceMs: 300, initialBackoffMs: 0,
maxBackoffMs: 50, backoffResetMs: 0, heapLimitMiB: 512, heapRestartPercent: 90, rssLimitMiB: 0,
updateProbationMs: 10, crashLoopCrashes: 5, crashLoopWindowMs: 1000,
})
@@ -30,6 +30,11 @@ describe('supervisorOptions', () => {
})).toEqual(DEFAULT_SUPERVISOR_OPTIONS)
})
+ it('allows no hang timeout under a second, where a GC pause would read as a hang', () => {
+ expect(supervisorOptions({ HARNESSD_HEARTBEAT_TIMEOUT_MS: '999' }).heartbeatTimeoutMs).toBe(DEFAULT_SUPERVISOR_OPTIONS.heartbeatTimeoutMs)
+ expect(supervisorOptions({ HARNESSD_HEARTBEAT_TIMEOUT_MS: '1000' }).heartbeatTimeoutMs).toBe(1000)
+ })
+
it('takes the heap limit from the flags the master was given, unless the environment names one', () => {
expect(supervisorOptions({}, ['--import', 'tsx', '--max-old-space-size=256']).heapLimitMiB).toBe(256)
expect(supervisorOptions({ HARNESSD_HEAP_LIMIT_MIB: '2048' }, ['--max-old-space-size=256']).heapLimitMiB).toBe(2048)
diff --git a/cli/src/harnessd/master.ts b/cli/src/harnessd/master.ts
index 87652f00e..5bcbcf8f0 100644
--- a/cli/src/harnessd/master.ts
+++ b/cli/src/harnessd/master.ts
@@ -66,7 +66,8 @@ export function supervisorOptions(env: NodeJS.ProcessEnv, execArgv: readonly str
return {
bindTimeoutMs: read('HARNESSD_BIND_TIMEOUT_MS', d.bindTimeoutMs, 1),
readyTimeoutMs: read('HARNESSD_READY_TIMEOUT_MS', d.readyTimeoutMs, 1),
- heartbeatTimeoutMs: read('HARNESSD_HEARTBEAT_TIMEOUT_MS', d.heartbeatTimeoutMs, 1),
+ // A second at least: below that a GC pause reads as a hang.
+ heartbeatTimeoutMs: read('HARNESSD_HEARTBEAT_TIMEOUT_MS', d.heartbeatTimeoutMs, 1_000),
stopGraceMs: read('HARNESSD_STOP_GRACE_MS', d.stopGraceMs, 1),
initialBackoffMs: read('HARNESSD_INITIAL_BACKOFF_MS', d.initialBackoffMs, 0),
maxBackoffMs: read('HARNESSD_MAX_BACKOFF_MS', d.maxBackoffMs, 0),
diff --git a/cli/src/harnessd/supervisor.spec.ts b/cli/src/harnessd/supervisor.spec.ts
index f61d523fe..b0b095580 100644
--- a/cli/src/harnessd/supervisor.spec.ts
+++ b/cli/src/harnessd/supervisor.spec.ts
@@ -91,7 +91,7 @@ describe('Supervisor', () => {
supervisor.start()
supervisor.start()
expect(cores).toHaveLength(1)
- expect(core().env).toEqual({ HARNESSD_SUPERVISED: '1', HARNESSD_RESTARTS: '0' })
+ expect(core().env).toEqual({ HARNESSD_SUPERVISED: '1', HARNESSD_RESTARTS: '0', HARNESSD_WATCHDOG_MS: '6000' })
expect(supervisor.status()).toMatchObject({ state: 'starting', corePid: 1000 })
core().bind()
expect(calls).toEqual(['claim'])
@@ -136,7 +136,7 @@ describe('Supervisor', () => {
expect(cores).toHaveLength(1)
vi.advanceTimersByTime(1)
expect(cores).toHaveLength(2)
- expect(core().env).toEqual({ HARNESSD_SUPERVISED: '1', HARNESSD_RESTARTS: '1', HARNESSD_LAST_EXIT: 'signal SIGKILL' })
+ expect(core().env).toEqual({ HARNESSD_SUPERVISED: '1', HARNESSD_RESTARTS: '1', HARNESSD_WATCHDOG_MS: '6000', HARNESSD_LAST_EXIT: 'signal SIGKILL' })
expect(lines.at(-1)).toBe('[harnessd] core started (pid ?) · restart 1')
core().bind()
expect(lines.at(-1)).toBe(`[harnessd] core bound (pid ?, protocol ${HARNESSD_PROTOCOL})`)
diff --git a/cli/src/harnessd/supervisor.ts b/cli/src/harnessd/supervisor.ts
index 8065414bc..3dac90b27 100644
--- a/cli/src/harnessd/supervisor.ts
+++ b/cli/src/harnessd/supervisor.ts
@@ -207,7 +207,11 @@ export class Supervisor {
this.coreSafeMode = null
this.ending = null
this.killReason = null
- const env: Record<string, string> = { HARNESSD_SUPERVISED: '1', HARNESSD_RESTARTS: String(this.restarts) }
+ // The core is told how long a silence the master allows, and beats well inside it (systemd passes
+ // WATCHDOG_USEC the same way): a timeout shorter than the core's own beat would kill a healthy core.
+ const env: Record<string, string> = {
+ HARNESSD_SUPERVISED: '1', HARNESSD_RESTARTS: String(this.restarts), HARNESSD_WATCHDOG_MS: String(this.options.heartbeatTimeoutMs),
+ }
if (this.lastExit) env.HARNESSD_LAST_EXIT = this.lastExit
if (this.safeMode) env.HARNESSD_SAFE_MODE = this.safeMode
const core = this.deps.spawnCore(env)
diff --git a/cli/src/startupOrder.spec.ts b/cli/src/startupOrder.spec.ts
index f16df55fb..703ba68d6 100644
--- a/cli/src/startupOrder.spec.ts
+++ b/cli/src/startupOrder.spec.ts
@@ -146,3 +146,66 @@ describe('cli.ts start-up order', () => {
expect(arm, 'a daemon that exits here can never be updated').not.toContain('catch(onError)')
})
})
+
+// ── The request gate ──────────────────────────────────────────────────────────────────────────────
+// Requests that arrive while the core is starting wait (`BackendSocket.holdRequests`) and are answered
+// in order once start-up is done (`openRequests`). Moving the code that binds the handlers into
+// modules (the core boundary, docs/design/2026-10-03-harnessd.md) must keep these exactly.
+
+/** Every place `runForeground` binds a handler on the socket: a property, an owner command, a setter. */
+const BINDING = /\bbackend\.(?:ownerCommands\.)?(?:[A-Za-z_$][\w$]*\s*=(?!=)|set[A-Z][\w$]*\()/g
+
+/** The test-only hold the end-to-end harness uses for a start-up that hangs after binding. */
+const TEST_HOLD = "if (process.env.HARNESSD_TEST_HOLD_READY === '1') await new Promise<never>(() => {})"
+
+describe('cli.ts request gate', () => {
+ const source = code(SOURCE)
+ const { text, from } = runForegroundBody(source)
+ const at = (needle: string, after = from): number => {
+ const index = source.indexOf(needle, after)
+ expect(index, `runForeground still contains \`${needle}\``).toBeGreaterThan(-1)
+ return index
+ }
+ const opened = at('\n backend.openRequests()')
+
+ it('holds requests from the moment the socket exists', () => {
+ const constructed = at('const backend = new BackendSocket(')
+ const held = at('backend.holdRequests()', constructed)
+ const between = source.slice(source.indexOf('\n', source.indexOf('}, computerId(), autonomousEnv)', constructed)), held)
+ // Only the reference other code reads the socket through may come between them; nothing that yields.
+ expect(between.split('\n').map((line) => line.trim()).filter(Boolean)).toEqual(['backendRef = backend'])
+ })
+
+ it('binds every handler before requests are answered', () => {
+ const bindings = [...text.matchAll(BINDING)]
+ expect(bindings.length, 'the socket is still wired up in runForeground').toBeGreaterThan(40)
+ const late = bindings.filter((binding) => from + binding.index > opened).map((binding) => binding[0])
+ expect(late, 'a handler bound after openRequests misses the requests held until then').toEqual([])
+ })
+
+ it('binds what restore publishes before restore runs, outside the gate', () => {
+ // `publishStoppedAgent` reads these while restoring agents and in the first reconcile, and those
+ // frames go out whether or not requests are open.
+ const restore = at('await restoreAgents({')
+ for (const provider of ['activityFrameProvider', 'runtimeProfileProvider', 'dshFrameProvider']) {
+ expect(at(`backend.${provider} =`), `backend.${provider} must be bound before restoreAgents`).toBeLessThan(restore)
+ }
+ })
+
+ it('never yields between dialing the backend and answering requests', () => {
+ // The relay callbacks (onRevoked, onBusy, onMachineMeta) are bound after `connect()`. That is safe
+ // only while nothing in between lets the socket's first frames run.
+ const dialed = at('backend.connect()')
+ const yields = source.slice(dialed, opened).split('\n')
+ .filter((line) => /^ {2}\S/.test(line) && /\bawait\b/.test(line) && line.trim() !== TEST_HOLD)
+ expect(yields, 'bind the relay callbacks before connect() first').toEqual([])
+ })
+
+ it('opens the gate, tells the master it is ready, then says so — last', () => {
+ const ready = at('coreLink.ready()', opened)
+ const logged = at("console.log('[cli] ready')", ready)
+ const tail = source.slice(opened, from + text.length).split('\n').map((line) => line.trim()).filter(Boolean)
+ expect(tail).toEqual(['backend.openRequests()', 'daemonBoot.openRequests = null', 'coreLink.ready()', "console.log('[cli] ready')"])
+ expect(logged).toBeGreaterThan(ready)
+ })
+})
diff --git a/cli/vitest.core.config.ts b/cli/vitest.core.config.ts
new file mode 100644
index 000000000..63d21e92a
--- /dev/null
+++ b/cli/vitest.core.config.ts
@@ -0,0 +1,20 @@
+import { defineConfig } from 'vitest/config'
+import base from './vitest.config.js'
+
+/** The daemon's core modules (cli/src/core), held to 100% in every file as they move out of
+ * runForeground (docs/design/2026-10-03-harnessd.md, the core boundary). */
+export default defineConfig({
+ test: {
+ ...base.test,
+ include: ['src/core/**/*.spec.ts'],
+ coverage: {
+ enabled: true,
+ provider: 'v8',
+ include: ['src/core/**/*.ts'],
+ exclude: ['src/core/**/*.spec.ts'],
+ reporter: ['text', 'json-summary'],
+ reportsDirectory: 'coverage/core',
+ thresholds: { perFile: true, statements: 100, branches: 100, functions: 100, lines: 100 },
+ },
+ },
+})
diff --git a/docs/design/2026-10-03-harnessd.md b/docs/design/2026-10-03-harnessd.md
index 0a64a4ebf..052654e42 100644
--- a/docs/design/2026-10-03-harnessd.md
+++ b/docs/design/2026-10-03-harnessd.md
@@ -481,8 +481,8 @@ What has to survive the move exactly:
Found while mapping, and fixed on their own rather than inside a move:
-- Kilo's reader is skipped on cancel and on shutdown, so a cancelled Kilo agent can keep showing
- as working.
+- Kilo's reader was skipped on cancel and on shutdown, so a cancelled Kilo agent could keep
+ showing as working. Fixed once the readers became one table (step 4).
- `BackendSocket.onLocalClient` is never wired.
## Testing
diff --git a/docs/research/2026-10-04-whole-history-reads.md b/docs/research/2026-10-04-whole-history-reads.md
new file mode 100644
index 000000000..752b457c3
--- /dev/null
+++ b/docs/research/2026-10-04-whole-history-reads.md
@@ -0,0 +1,191 @@
+# Whole-history reads in the daemon
+
+October 4, 2026, at `076aff72a` (main after #715). Every place the daemon reads an agent's
+whole conversation at once: a read whose cost grows with the conversation, not with what it
+serves. This is the work list for "bounded reads for every other engine" in the
+[harnessd design](../design/2026-10-03-harnessd.md#bounded-work), and the allowlist a guard
+test will start from and shrink.
+
+Paths are under `cli/src`. Specs, `testing/` and `scripts/` are left out. "File engines" means
+Cursor, Muse, Amp, Grok, agy, Copilot, pi and Command Code; Claude Code and Codex take the
+bounded paths.
+
+## The hot paths, first
+
+These run per event, per poll or per page, and grow with the conversation:
+
+1. **Cursor's live tail** (`watcher/watcher.ts:430`, `readCursor`) reads and splits the whole
+ file on every change, every heartbeat drain while a turn is open (twice every 5 s) and every
+ 5-minute reconcile.
+2. **Cursor's sub-agents** (`engines/cursor/subagent.ts:182`) read each whole child transcript
+ on every history page, and poll it every 250 ms to 1 s while a Task runs.
+3. **The recap of every file engine** (`cli.ts:3019`) reads the whole transcript at every turn
+ end, with or without a device.
+4. **History pages of every file engine** (`backendSocket.ts:2368`) read the whole transcript
+ before cutting the page; Muse, Amp, Grok, agy and Copilot have no page cut at all.
+5. **The database engines** (OpenCode, Kilo, Hermes, Devin) load a whole session, synchronously
+ on the event loop, for the recap (`cli.ts:3011–3014`), for search on every turn event
+ (`cli.ts:3042–3047` → `lib/sessionSearch/indexer.ts:467`) and for every history page
+ (`backendSocket.ts:2238`, `:2259`, `:2280`, `:2305`).
+6. **OpenCode's and Kilo's live poll** (`engines/opencode/reader.ts:205`,
+ `engines/kilo/reader.ts:214`) re-reads the whole running turn, tool output included, every
+ second.
+7. **Devin's live poll** (`engines/devin/reader.ts:192`) gets roughly the whole conversation
+ back after each inference, because Devin re-persists the chain.
+8. **Codex's child rollouts** (`engines/codex/subagent.ts:164`) are read whole, synchronously,
+ for each sub-agent completion seen live or on a page.
+9. **Copilot's and Muse's session repair** (`lib/sessionRepair.ts:267`, `:313`) read whole
+ candidate files every 5 s, then every 60 s, while a pane is unbound. Copilot uses five lines of
+ each.
+
+## The low-level readers
+
+- **`tailFile(path, Infinity)`** (`lib/transcriptTail.ts:189–198`) streams every non-blank line
+ into one array. Its only callers are the three file-engine sites below. A finite `n` reads
+ backward in 64 KB chunks.
+- **`tailFileUntil`** (`lib/transcriptTail.ts:167`) reads back to the last prompt, and to the
+ start of the file when there is none. It serves the Claude Code and Codex recaps.
+- **`sqliteReadAll`** (`lib/sqliteRead.ts:249`) runs `node:sqlite`'s `prepare(sql).all()`
+ synchronously on the event loop, with no row or byte limit. Without that module it spawns
+ `sqlite3 -json` (5 s timeout, 32 MB output cap; over the cap reads as nothing).
+
+## The shared file-engine sites
+
+- **Attach** (`cli.ts:2526`, `attachSessionNow` when not from the end): every line through the
+ normalizer, `runtimeProfiles.hydrate`, and for Copilot `copilotHistoryTurnOpen`. Once per
+ attach: restore, re-activation, pane open, reset, rebind.
+- **Recap** (`cli.ts:3019`, `readLastTurn`): every turn end.
+- **History pages** (`backendSocket.ts:2368`): the whole file, then the window
+ (`windowCursorLines`, `windowPiLines`, `windowCommandCodeLines`, `windowRawLines`).
+
+## The database sites
+
+`readOpencodeMessages` (`engines/opencode/reader.ts:40`), `readKiloMessages`
+(`engines/kilo/reader.ts:43`), `readHermesMessages` (`engines/hermes/reader.ts:49`) and
+`readDevinMessages` (`engines/devin/reader.ts:60`) have no limit and run through
+`sqliteReadAll`. Shared callers:
+
+- the recap, per turn end (`cli.ts:3011–3014`);
+- `databaseHistory` (`cli.ts:3042–3047`), which feeds search's `historyPass` on every turn start
+ and end (debounced 1.5 s) and the handoff (`lib/agentHandoff.ts:730` →
+ `lib/sessionSearch/sessionTurns.ts:137`);
+- history pages, windowed in JS after the whole read;
+- the close checkpoint (`lib/sessionCheckpoint.ts:39`, `SELECT *` for the session, stringified
+ whole at `:143`), twice per close;
+- storage size (`lib/purgeAgentService.ts:111`), an aggregate over every byte of the session, from
+ purge review and from storage telemetry at most once a minute per agent.
+
+## Per engine
+
+**Claude Code.** Bounded: attach, history pages, the live tail, the recap, activity (2 MB tail),
+project detection (2 MB head), session repair (256 KB head), external search (32 MB head).
+Edge cases that still read the whole file: a from-start attach (`lib/attachTranscript.ts:132`),
+a transcript with no turn opener (`:197`), a file that shrank under two walks (`:274`); the line
+index's first look at a path (`lib/transcriptPages.ts:169–188`, cached for 256 paths); an unknown
+or stale cursor (`:419–436`); a from-start tail (`watcher/watcher.ts:158`, `:412`); a recap
+with no prompt in the file (`lib/transcriptTail.ts:167`). Elsewhere:
+- sub-agent stats on every history page (`backendSocket.ts:401`, `:411`), streamed, no size
+ bound;
+- the token-usage backfill (`lib/agentTokenUsage.ts:274`, `:333`), from byte 0 on a cold cache
+ or a rewrite, files over 128 MB skipped, incremental after;
+- the search indexer's first pass (`lib/sessionSearch/indexer.ts:395`, `:401`), streamed in 1 MB
+ chunks, incremental after;
+- the handoff (`lib/sessionSearch/sessionTurns.ts:127`), the whole transcript, with a 5 s
+ deadline and no size bound;
+- the close checkpoint's file copy (`lib/sessionCheckpoint.ts:133`), a clone, not a JS read.
+
+**Codex.** Bounded as Claude Code, plus external search (1 MB head, 4 MB tail) and rollout meta
+(128 KB). Also:
+- child rollouts (`engines/codex/subagent.ts:162`), synchronous `readFileSync` and split;
+- resume repair (`engines/codex/portableHistory.ts:150`), which scans the whole rollout with
+ synchronous reads, once to inspect and again to copy, on restore, restart, retarget and resume.
+
+The token usage, search, handoff and checkpoint items above apply too.
+
+**OpenCode.** Attach (`engines/opencode/reader.ts:126`); the 1 s live poll re-reads the running
+turn (`:205`; its cursor moves only past closed messages); sub-agent counts read the whole child
+session per finished task (`:266`); external search (`lib/sessionSearch/externals/opencode.ts:129`);
+the shared database sites.
+
+**Grok.** The file-engine sites, with no page cut. External search reads until the first prompt
+(`lib/sessionSearch/externals/grok.ts:91`, `:94`).
+
+**pi.** The file-engine sites; the page is cut after the whole read. Titles read from 0 the first
+time, then incrementally (`lib/sessionSearch/externals/pi.ts:90`, `:95`).
+
+**agy.** The file-engine sites, with no page cut. External search reads agy's cross-conversation
+`history.jsonl` whole, cached per file stamp (`lib/sessionSearch/externals/agy.ts:35`, `:37`).
+
+**Amp.** The file-engine sites. History pages also run `amp threads export` and parse the whole
+output (`engines/amp/threadExport.ts:50`, `:66`; 32 MB and 20 s caps).
+
+**Command Code.** The file-engine sites; the page is cut after the whole read.
+
+**Copilot.** The file-engine sites, plus `copilotHistoryTurnOpen` at attach. Session repair
+(`lib/sessionRepair.ts:260`, `:267`) reads up to 400 candidate files whole and uses five lines
+of each; it serves reconcile repair, handoff discovery and resume identity. External search reads
+until the first prompt (`lib/sessionSearch/externals/copilot.ts:187`, `:193`).
+
+**Cursor.** The file-engine sites; the live tail (`watcher/watcher.ts:141` keeps the whole file;
+`:428`, `:430` re-read and diff it on every change, heartbeat drain and reconcile); sub-agent
+children (`engines/cursor/subagent.ts:174–183`) read whole on every page and polled during a
+Task. Store metadata reads are bounded (`LIMIT 1`).
+
+**Devin.** Attach reads every row, duplicates included (`engines/devin/reader.ts:135`); the 1 s
+poll (`:192`) is bounded by row id in name only, since the chain is re-persisted each inference;
+external search (`lib/sessionSearch/externals/devin.ts:144`); the shared database sites. The error
+log is bounded.
+
+**Hermes.** Attach (`engines/hermes/reader.ts:138`); the live poll is bounded by id (`:168`);
+external search reads every session in a compression chain (`lib/sessionSearch/externals/hermes.ts:374`);
+the shared database sites.
+
+**Kilo.** As OpenCode: attach (`engines/kilo/reader.ts:135`), the 1 s poll re-reads the running
+turn (`:214`), sub-agent counts (`:275`), external search, the shared database sites.
+
+**Muse.** The file-engine sites, with no page cut. Session repair (`lib/sessionRepair.ts:313`,
+`:322`) reads candidate files whole while a pane is unbound, which is the only way a Muse pane
+gets bound; external search stops at the first run (`lib/sessionSearch/externals/muse.ts:75`,
+`:78`).
+
+There is no Gemini, Qwen, Factory or Kimi engine. `ENGINES`: claude, codex, cursor, opencode, pi,
+hermes, commandcode, devin, muse, amp, kilo, grok, agy, copilot, terminal.
+
+## Left out
+
+Not one agent's conversation, or already bounded: Codex's `session_index.jsonl` readers, the
+daemon's own recap store, harness.log, lock, pid and config files, the external store-listing
+SQL and search store queries (both have `LIMIT`), and artifact hashing.
+
+## Table
+
+| File | Line | Engine | Trigger | Hot path | Bounded |
+|---|---|---|---|---|---|
+| cli.ts | 2526 | file engines | attach | once per attach | no |
+| cli.ts | 3019 | file engines | recap | every turn end | no |
+| backendSocket.ts | 2368 | file engines | history page | every page | no; five engines have no page cut |
+| backendSocket.ts | 411 | Claude Code | page, sub-agent stats | every page | no (streamed) |
+| lib/agentTokenUsage.ts | 333 | Claude Code, Codex | token backfill | once per session | over 128 MB skipped; incremental after |
+| lib/sessionSearch/indexer.ts | 401 | file engines | search first pass, or after a shrink | no | no (streamed; incremental after) |
+| lib/sessionSearch/indexer.ts | 467 | database engines | search, every turn event | yes | no |
+| lib/sessionSearch/sessionTurns.ts | 127, 137 | all | handoff | no | 5 s deadline only |
+| engines/codex/subagent.ts | 164 | Codex | sub-agent done | yes | no; synchronous |
+| engines/codex/portableHistory.ts | 175, 190 | Codex | resume, restore, retarget | no | no; synchronous |
+| engines/opencode/reader.ts | 126, 205, 266 | OpenCode | attach, 1 s poll, sub-agent done | poll: yes | no; the poll re-reads the running turn; synchronous |
+| engines/kilo/reader.ts | 135, 214, 275 | Kilo | as OpenCode | poll: yes | as OpenCode |
+| engines/hermes/reader.ts | 138, 168 | Hermes | attach, poll | poll: yes | attach no; poll yes |
+| engines/devin/reader.ts | 135, 192 | Devin | attach, poll | poll: yes | no; the chain is re-persisted |
+| cli.ts | 3011–3014 | database engines | recap | every turn end | no; synchronous |
+| cli.ts | 3044–3047 | database engines | search, handoff | search: yes | no |
+| backendSocket.ts | 2238, 2259, 2280, 2305 | database engines | history page | every page | no (windowed in JS) |
+| lib/sessionCheckpoint.ts | 39, 143 | database engines | close, twice | no | no; synchronous |
+| lib/purgeAgentService.ts | 111 | database engines | purge review, storage telemetry | at most once a minute per agent | SQL aggregate; synchronous |
+| engines/amp/threadExport.ts | 66 | Amp | history page | every page | 32 MB output cap |
+| watcher/watcher.ts | 141, 430 | Cursor | attach; every change, drain, reconcile | yes | no |
+| watcher/watcher.ts | 158, 412 | any, from the start | first replay | no | no |
+| engines/cursor/subagent.ts | 182 | Cursor | every page; Task poll | yes | no |
+| lib/sessionRepair.ts | 267 | Copilot | repair, discovery, resume identity | repeated | no; uses five lines |
+| lib/sessionRepair.ts | 313 | Muse | repair while unbound | repeated | no |
+| lib/attachTranscript.ts | 132, 197, 274 | Claude Code, Codex | attach edge cases | no | no |
+| lib/transcriptPages.ts | 180, 431 | any with a transcript; Claude Code | first look; stale cursor | no; per request | incremental after; to the start at worst |
+| lib/transcriptTail.ts | 171 | Claude Code, Codex | recap | every turn end | to the last prompt; whole file if none |