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
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.ymlindex e7d80029e..329a8d2ce 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -346,6 +346,11 @@ jobs:- name: Require complete harness updater coveragerun: 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.tsindex 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.jsonindex 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.tsindex 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.sessionTurnOpenconst 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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) => unknownonce(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.tsindex 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.tsindex 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 strreturn {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.tsindex 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.tsindex 8065414bc..3dac90b27 100644--- a/cli/src/harnessd/supervisor.ts+++ b/cli/src/harnessd/supervisor.ts@@ -207,7 +207,11 @@ export class Supervisor {this.coreSafeMode = nullthis.ending = nullthis.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.lastExitif (this.safeMode) env.HARNESSD_SAFE_MODE = this.safeModeconst core = this.deps.spawnCore(env)diff --git a/cli/src/startupOrder.spec.ts b/cli/src/startupOrder.spec.tsindex 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.tsnew file mode 100644index 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.mdindex 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.## Testingdiff --git a/docs/research/2026-10-04-whole-history-reads.md b/docs/research/2026-10-04-whole-history-reads.mdnew file mode 100644index 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 |