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
import { liveFor } from '../../engines/live.js'
import { appendFileSync, mkdirSync, mkdtempSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import type { RegisteredSession } from '../../lib/registry.js'
import { Watcher, type TailHold } from '../../watcher/watcher.js'
import { createIngest } from './ingest.js'
import { createCancel } from '../turns/cancel.js'
import { createAttach, type AttachDeps } from './attach.js'
import { loadEngine } from '../../engines/inProcess.js'
import { createSessionNormalizers } from './normalizers.js'
import { createRelaunchMarks, type RelaunchMark } from './relaunch.js'
import type { PreparedLive } from '../engines/liveSessions.js'
import type { LiveFrame } from '../../engines/worker/liveProtocol.js'
import { TranscriptDiscovery } from '../../engines/kit/transcriptDiscovery.js'
import { createBinding, type BindDeps } from '../agents/bind.js'
import { createDiscoveryHandlers, type DiscoveryDeps } from '../agents/discovery.js'
import type { DiscoveredTerminalAgent } from '../../lib/terminalAgentDiscovery.js'
vi.mock('../../lib/deletedSessions.js', () => ({ isRecentlyDeleted: () => false }))
/**
* The engines' own normalizers and readers are tested with each engine. Here each is a fake that
* reads JSON lines: `{"events":[…]}` is what a line yields, `{"open":true}` / `{"close":true}` move
* its turn. Transcript reading, folding and the attach tracker are the real ones.
*/
const fakes = vi.hoisted(() => {
const made: Array<{ kind: string; args: unknown[]; instance: Record<string, any> }> = []
const normalizer = (kind: string) => class {
turnOpen = false
turnRevision = 0
thinkingPrefix = ''
args: unknown[]
constructor(...args: unknown[]) { this.args = args; made.push({ kind, args, instance: this as Record<string, any> }) }
ingest(line: string) {
this.turnRevision++
const record = JSON.parse(line || '{}') as { events?: unknown[]; open?: boolean; close?: boolean }
if (record.open) this.turnOpen = true
if (record.close) this.turnOpen = false
return record.events ?? []
}
closeTurn() { this.turnRevision++; this.turnOpen = false; return [] }
}
const reader = (kind: string) => class {
turnOpen = false
opts: Record<string, any>
start = async () => {}
constructor(opts: Record<string, any>) { this.opts = opts; made.push({ kind, args: [opts], instance: this as Record<string, any> }) }
}
return { made, normalizer, reader, copilotOpen: { value: true } }
})
vi.mock('../../engines/codex/normalizer.js', async (real) => ({ ...await real<object>(), CodexNormalizer: fakes.normalizer('codex') }))
vi.mock('../../engines/cursor/normalizer.js', async (real) => ({ ...await real<object>(), CursorNormalizer: fakes.normalizer('cursor') }))
vi.mock('../../engines/muse/normalizer.js', async (real) => ({ ...await real<object>(), MuseNormalizer: fakes.normalizer('muse') }))
vi.mock('../../engines/amp/normalizer.js', async (real) => ({ ...await real<object>(), AmpNormalizer: fakes.normalizer('amp') }))
vi.mock('../../engines/grok/normalizer.js', async (real) => ({ ...await real<object>(), GrokNormalizer: fakes.normalizer('grok') }))
vi.mock('../../engines/agy/normalizer.js', async (real) => ({ ...await real<object>(), AgyNormalizer: fakes.normalizer('agy') }))
vi.mock('../../engines/pi/normalizer.js', async (real) => ({ ...await real<object>(), PiNormalizer: fakes.normalizer('pi') }))
vi.mock('../../engines/omp/normalizer.js', async (real) => ({ ...await real<object>(), OmpNormalizer: fakes.normalizer('omp') }))
vi.mock('../../engines/commandcode/normalizer.js', async (real) => ({ ...await real<object>(), CommandCodeNormalizer: fakes.normalizer('commandcode') }))
vi.mock('../../engines/copilot/normalizer.js', async (real) => ({
...await real<object>(),
CopilotNormalizer: fakes.normalizer('copilot'),
copilotHistoryTurnOpen: () => fakes.copilotOpen.value,
}))
vi.mock('../../engines/opencode/reader.js', async (real) => ({ ...await real<object>(), OpencodeReader: fakes.reader('opencode') }))
vi.mock('../../engines/kilo/reader.js', async (real) => ({ ...await real<object>(), KiloReader: fakes.reader('kilo') }))
vi.mock('../../engines/hermes/reader.js', async (real) => ({ ...await real<object>(), HermesReader: fakes.reader('hermes') }))
vi.mock('../../engines/devin/reader.js', async (real) => ({ ...await real<object>(), DevinReader: fakes.reader('devin') }))
const dirs: string[] = []
const bindings = new Map<string, RegisteredSession>()
const transcript = (lines: unknown[] = []): string => {
const dir = mkdtempSync(join(tmpdir(), 'core-attach-'))
dirs.push(dir)
const file = join(dir, 'session.jsonl')
writeFileSync(file, lines.map((line) => typeof line === 'string' ? line : JSON.stringify(line)).join('\n') + (lines.length ? '\n' : ''))
return file
}
const session = (engine: string, transcriptPath?: string, over: Partial<RegisteredSession> = {}): RegisteredSession => {
const value = { agentId: `${engine}-agent`, sessionId: `${engine}-s`, engine, transcriptPath, ...over } as RegisteredSession
bindings.set(value.agentId, value)
return value
}
// Each engine's code is loaded in this process before an attach folds; a test may say it could not be.
vi.mock('../../engines/inProcess.js', async (real) => {
const actual = await real<typeof import('../../engines/inProcess.js')>()
return { ...actual, loadEngine: vi.fn(actual.loadEngine) }
})
const IDLE_AGY = 'done\n\n ? for shortcuts'
const started = (userMessage = 'go') => ({ type: 'turn_started' as const, payload: { userMessage } })
const CLAUDE_PROMPT = { type: 'user', message: { role: 'user', content: 'hello' }, uuid: 'u1' }
function setup(over: Partial<AttachDeps> = {}) {
const normalizers = createSessionNormalizers()
const service = { needsTranscript: vi.fn(() => false), observeTranscript: vi.fn() }
const profile = { ingest: vi.fn(), commit: vi.fn() }
const deps: AttachDeps = {
liveFor,
announceSession: vi.fn(),
setInterpretationHold: (id, revision, reason, create) => {
const row = bindings.get(id)
if (!row || row.evidenceRevision !== revision || row.identityHold || (!row.interpretationHold && !(create && reason))) return false
if (!row.interpretationHold) row.evidenceRevision = (row.evidenceRevision ?? 0) + 1
if (reason) row.interpretationHold = reason
else delete row.interpretationHold
return true
},
resolve: id => bindings.get(id),
terminalGone: vi.fn(async () => false),
normalizers,
watcher: { addSession: vi.fn(async () => {}), removeSession: vi.fn(async () => {}), pollSession: vi.fn(async () => {}), hold: vi.fn(async () => null), tails: vi.fn(() => false) },
cursorDiscovery: { add: vi.fn(async () => {}) },
device: () => service,
runtimeProfiles: {
transcriptFields: vi.fn(() => []),
beginHydrate: vi.fn(() => profile),
hydrate: vi.fn(),
ingestConfig: vi.fn(async () => false),
ingestPane: vi.fn(() => false),
capturePane: vi.fn(async (session, capture, lines, silent) => {
const text = await capture(session.agentId, lines)
if (text) await deps.runtimeProfiles.ingestPane(session, text, silent)
return text
}),
} as AttachDeps['runtimeProfiles'],
captureTerminal: vi.fn(async () => 'pane'),
emit: vi.fn(),
announceTurnAborted: vi.fn(),
questionWatcher: { start: vi.fn() },
terminalLabel: () => 'tmux:%0',
dbs: { opencode: '/db/opencode.db', kilo: '/db/kilo.db', devin: '/db/devin.db' },
devinHome: '/devin',
hermesDb: async (s) => `/db/hermes-${s.agentId}.db`,
concurrency: 2,
...over,
}
return { deps, normalizers, service, profile, attach: createAttach(deps) }
}
const made = (kind: string) => fakes.made.filter((entry) => entry.kind === kind).map((entry) => entry.instance)
function remoteSetup(open = false, over: Partial<AttachDeps> = {}) {
const turn = { identity: 'worker:turn', turnOpen: open, continued: false }
const handle = { engine: 'claude', turnOpen: open, snapshot: () => ({ ...turn }), closeTurn: vi.fn() }
const candidate = { state: { handle }, page: { cursor: { offset: 20 }, lastStarted: open ? started() : null },
records: 1, content: true } as unknown as PreparedLive
const frames: LiveFrame[] = [
{ raw: 'metadata', profile: true, observe: false, events: [], replay: false, turn },
{ raw: 'record', profile: false, observe: true, events: [], replay: false, turn },
]
const remote: NonNullable<AttachDeps['remoteLive']> = {
handles: engine => engine === 'claude', current: vi.fn(() => true),
prepare: vi.fn(async (_session, _options, observe, observePage) => { await observePage?.(frames); frames.forEach(observe); return candidate }),
install: vi.fn(() => true), discard: vi.fn(), retry: vi.fn(),
}
const p = setup({ remoteLive: remote, liveFor: vi.fn(() => { throw new Error('isolated parser must stay in its worker') }), ...over })
return { ...p, remote, candidate, handle }
}
afterEach(() => {
vi.restoreAllMocks()
vi.mocked(loadEngine).mockReset()
vi.useRealTimers()
fakes.made.length = 0
fakes.copilotOpen.value = true
bindings.clear()
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
})
it.each(['same', 'repaired'] as const)('composes discovery, retry and inline attachment after %s binding recovery', async outcome => {
const run = setup({ settled: vi.fn() })
const savedPath = transcript([{ events: [started('unconfirmed')], open: true }])
const verifiedPath = outcome === 'same' ? savedPath : transcript([{ events: [started('verified')], open: true }, { close: true }])
const row = session('codex', savedPath, { active: false, registeredAt: 1, boundAt: 2, permissionMode: 'default' })
let previous: unknown
if (outcome === 'repaired') {
await run.attach.attachSession(row)
previous = run.normalizers.liveParsers.get(row.sessionId)
expect(run.normalizers.sessionTurnOpen(row.sessionId)).toBe(true)
}
row.identityHold = 'header incomplete'
let available = false
const registry = {
byAgent: (id: string) => bindings.get(id), byProcess: () => row,
updateRuntimes: vi.fn(), updateProcessIdentity: () => { row.active = true },
setBypassPermission: vi.fn(), setLaunch: vi.fn(),
revalidateBinding: () => {
if (!available) throw new Error('header incomplete')
row.transcriptPath = verifiedPath; delete row.identityHold; return row
},
setIdentityHold: (_id: string, reason: string) => { row.identityHold = reason; return false },
bySession: () => row,
}
const bind = createBinding({ registry, attachSession: run.attach.attachSession,
announceSession: vi.fn(), stoppedAgents: { save: vi.fn() }, syncRecapPool: vi.fn(),
} as unknown as BindDeps)
const discover = createDiscoveryHandlers({ registry, bindObservedAgent: bind.bindObservedAgent,
attachSession: run.attach.attachSession, announceSession: vi.fn(), syncRecapPool: vi.fn(),
} as unknown as DiscoveryDeps)
const seen = { engine: 'codex', processIdentity: { pid: 42, startMarker: 'fixture' }, args: 'codex', runtimes: [] } as unknown as DiscoveredTerminalAgent
vi.clearAllMocks()
await discover.onObserved(seen, row)
await new Promise(resolve => setTimeout(resolve, 20))
expect(run.deps.terminalGone).not.toHaveBeenCalled()
expect(run.deps.runtimeProfiles.beginHydrate).not.toHaveBeenCalled()
expect(run.profile.commit).not.toHaveBeenCalled()
expect(run.deps.emit).not.toHaveBeenCalled()
expect(run.deps.watcher.addSession).not.toHaveBeenCalled()
expect(row).toMatchObject({ active: true, identityHold: 'header incomplete', transcriptPath: savedPath })
if (outcome === 'same') writeFileSync(savedPath, JSON.stringify({ events: [started('verified')], open: true }) + '\n' + JSON.stringify({ close: true }) + '\n')
available = true
await discover.onObserved(seen, row)
await vi.waitFor(() => expect(run.deps.watcher.addSession).toHaveBeenCalledOnce())
expect(row).not.toHaveProperty('identityHold')
expect(run.normalizers.liveParsers.get(row.sessionId)).not.toBe(previous)
expect(run.normalizers.sessionTurnOpen(row.sessionId)).toBe(false)
expect(run.profile.commit).toHaveBeenCalledOnce()
expect(run.deps.emit).not.toHaveBeenCalled()
expect(run.deps.settled).toHaveBeenCalledWith(row.sessionId)
})
it('keeps an already held binding without starting a terminal probe or reader', async () => {
const run = setup()
expect(await run.attach.attachSession(session('codex', transcript([]), { identityHold: 'waiting' }))).toBe(true)
expect(run.deps.terminalGone).not.toHaveBeenCalled()
expect(run.deps.runtimeProfiles.beginHydrate).not.toHaveBeenCalled()
})
it.each(['terminal', 'config', 'watcher'] as const)('revokes inline attachment when identity becomes held during %s', async phase => {
const run = setup(), row = session('codex', transcript([{ events: [started()], open: true }]))
const hold = () => { row.identityHold = 'identity unavailable' }
if (phase === 'terminal') vi.mocked(run.deps.terminalGone).mockImplementationOnce(async () => { hold(); return false })
if (phase === 'config') vi.mocked(run.deps.runtimeProfiles.ingestConfig).mockImplementationOnce(async () => { hold(); return false })
if (phase === 'watcher') vi.mocked(run.deps.watcher.addSession).mockImplementationOnce(async () => { hold() })
expect(await run.attach.attachSession(row)).toBe(true)
expect(run.deps.emit).not.toHaveBeenCalled()
if (phase !== 'watcher') {
expect(run.profile.commit).not.toHaveBeenCalled()
expect(run.normalizers.hasState(row.sessionId)).toBe(false)
}
})
it.each(['prepare', 'config'] as const)('discards worker history when identity becomes held during %s', async phase => {
const run = remoteSetup(true), row = session('claude', '/fixture/transcript')
if (phase === 'prepare') vi.mocked(run.remote.prepare).mockImplementationOnce(async () => { row.identityHold = 'waiting'; return run.candidate })
else vi.mocked(run.deps.runtimeProfiles.ingestConfig).mockImplementationOnce(async () => { row.identityHold = 'waiting'; return false })
expect(await run.attach.attachSession(row)).toBe(true)
expect(run.remote.discard).toHaveBeenCalledWith(run.candidate)
expect(run.remote.install).not.toHaveBeenCalled()
expect(run.profile.commit).not.toHaveBeenCalled()
expect(run.deps.emit).not.toHaveBeenCalled()
})
it('discards an inline fold held during its file read, without observing it on a device', async () => {
const run = setup(), row = session('codex', transcript([{ events: [started()], open: true }]))
run.service.needsTranscript.mockReturnValue(true)
run.profile.ingest.mockImplementation(() => { row.identityHold = 'header changed' })
expect(await run.attach.attachSession(row)).toBe(true)
expect(run.service.observeTranscript).not.toHaveBeenCalled()
expect(run.profile.commit).not.toHaveBeenCalled()
expect(run.normalizers.hasState(row.sessionId)).toBe(false)
expect(run.deps.emit).not.toHaveBeenCalled()
})
it('discards a whole-file read when identity becomes held before hydration', async () => {
const row = session('terminal', transcript([{}]))
const run = setup({ liveFor: engine => {
queueMicrotask(() => { row.identityHold = 'path changed' })
return liveFor(engine)
} })
expect(await run.attach.attachSession(row)).toBe(true)
expect(run.deps.runtimeProfiles.hydrate).not.toHaveBeenCalled()
expect(run.normalizers.hasState(row.sessionId)).toBe(false)
})
it('defers history publication if identity becomes held during pane hydration', async () => {
const row = session('cursor', transcript([{ events: [started()], open: true }]))
const run = setup({ captureTerminal: async () => { row.identityHold = 'path changed'; return null } })
expect(await run.attach.attachSession(row)).toBe(true)
expect(run.deps.emit).not.toHaveBeenCalled()
expect(run.deps.watcher.addSession).not.toHaveBeenCalled()
})
describe('the order of an attach of another engine\'s session', () => {
it('loads the engine\'s code, then folds, then starts the tail: no line can come before its normalizer', async () => {
let loaded!: () => void
const real = await loadEngine('muse')
vi.mocked(loadEngine).mockImplementationOnce(() => new Promise((settle) => { loaded = () => settle(real as never) }) as never)
const run = setup()
const path = transcript([{ any: 'line' }])
const attaching = run.attach.attachSession(session('muse', path))
await new Promise((settle) => setTimeout(settle, 20))
expect(run.deps.watcher.addSession).not.toHaveBeenCalled()
expect(run.normalizers.hasState('muse-s')).toBe(false)
loaded()
expect(await attaching).toBe(true)
expect(run.normalizers.museNormalizers.has('muse-s')).toBe(true)
expect(run.deps.watcher.addSession).toHaveBeenCalledTimes(1)
// Claude Code and Codex never ask for it.
vi.mocked(loadEngine).mockClear()
await setup().attach.attachSession(session('codex', transcript([])))
expect(loadEngine).not.toHaveBeenCalled()
})
})
it('starts core transcript discovery before an optional Cursor module can stall attachment', async () => {
let release!: () => void
vi.mocked(loadEngine).mockImplementationOnce(() => new Promise(resolve => { release = () => resolve(null) }))
const run = setup()
const attaching = run.attach.attachSession(session('cursor'))
try {
await vi.waitFor(() => expect(run.deps.cursorDiscovery.add).toHaveBeenCalledWith('cursor-s'))
await vi.waitFor(() => expect(release).toBeTypeOf('function'))
expect(run.deps.watcher.addSession).not.toHaveBeenCalled()
} finally { release(); await attaching; vi.clearAllMocks() }
})
it('locates a fifth Cursor session while four optional readers occupy the entire attach pool', async () => {
const releases: Array<() => void> = []
vi.mocked(loadEngine).mockImplementationOnce(() => new Promise(resolve => { releases.push(() => resolve(null)) }))
const run = setup({ concurrency: 4 })
const pending = Array.from({ length: 4 }, (_, i) => run.attach.attachSession(session('copilot', undefined, { agentId: `a${i}`, sessionId: `s${i}` })))
await vi.waitFor(() => expect(releases).toHaveLength(1))
expect(run.attach.attaches.attaching()).toHaveLength(4)
const fifth = run.attach.attachSession(session('cursor'))
expect(run.attach.attaches.queued()).toBe(1)
expect(run.deps.cursorDiscovery.add).toHaveBeenCalledWith('cursor-s')
releases.forEach(release => release())
await Promise.all([...pending, fifth])
})
it.each(['terminal probe', 'optional module'] as const)('does not restore a forgotten Cursor while its %s completes', async phase => {
const run = setup()
let release!: () => void
if (phase === 'terminal probe') vi.mocked(run.deps.terminalGone).mockImplementationOnce(() => new Promise(resolve => { release = () => resolve(false) }))
else vi.mocked(loadEngine).mockImplementationOnce(() => new Promise(resolve => { release = () => resolve(null) }))
const s = session('cursor')
const pending = run.attach.attachSession(s)
await vi.waitFor(() => expect(release).toBeTypeOf('function'))
expect(run.deps.cursorDiscovery.add).toHaveBeenCalledOnce()
bindings.delete(s.agentId)
vi.mocked(run.deps.cursorDiscovery.add).mockClear()
release()
expect(await pending).toBe(false)
expect(run.deps.cursorDiscovery.add).not.toHaveBeenCalled()
expect(run.normalizers.hasState(s.sessionId)).toBe(false)
expect(run.deps.watcher.addSession).not.toHaveBeenCalled()
expect(run.deps.emit).not.toHaveBeenCalled()
})
it('rejects a stale attach before scheduling its locator or taking a slot', async () => {
const run = setup()
const stale = session('cursor')
bindings.delete(stale.agentId)
expect(await run.attach.attachSession(stale)).toBe(false)
expect(run.deps.cursorDiscovery.add).not.toHaveBeenCalled()
expect(run.deps.terminalGone).not.toHaveBeenCalled()
})
it('discards a queued attach whose binding was forgotten while every reader slot was occupied', async () => {
const run = setup({ concurrency: 1 })
let release!: () => void
vi.mocked(run.deps.terminalGone).mockImplementationOnce(() => new Promise(resolve => { release = () => resolve(true) }))
const first = run.attach.attachSession(session('pi'))
const stale = session('cursor')
const pending = run.attach.attachSession(stale)
bindings.delete(stale.agentId)
release()
await first
expect(await pending).toBe(false)
expect(run.deps.terminalGone).toHaveBeenCalledOnce()
})
it.each([new Error('unavailable'), 'unavailable'])('contains a failed core locator without rejecting the binding: %s', async error => {
const log = vi.spyOn(console, 'error').mockImplementation(() => {})
const run = setup({ cursorDiscovery: { add: vi.fn(async () => { throw error }) } })
expect(await run.attach.attachSession(session('cursor'))).toBe(true)
expect(log).toHaveBeenCalledWith('[cursor-discovery] lookup failed: unavailable')
})
it.each(['terminal probe', 'optional module'] as const)('attaches a newly located Cursor file after its pathless %s was superseded', async phase => {
const code = await loadEngine('cursor')
const home = mkdtempSync(join(tmpdir(), 'attach-locator-')); dirs.push(home)
const s = session('cursor')
let replacement: Promise<boolean> | undefined, release!: () => void
const discovery = new TranscriptDiscovery(home, { kind: 'direct', root: '', id: /^cursor-s$/, file: ['cursor.jsonl'] }, (_id, path) => {
s.transcriptPath = path
replacement = run.attach.attachSession(s, false, true)
}, () => true, 10)
const run = setup({ cursorDiscovery: discovery })
if (phase === 'terminal probe') vi.mocked(run.deps.terminalGone).mockImplementationOnce(() => new Promise(resolve => { release = () => resolve(false) }))
else vi.mocked(loadEngine).mockImplementationOnce(() => new Promise(resolve => { release = () => resolve(code) }))
await discovery.start()
try {
const first = run.attach.attachSession(s)
await vi.waitFor(() => expect(release).toBeTypeOf('function'))
mkdirSync(join(home, s.sessionId))
const path = join(home, s.sessionId, 'cursor.jsonl'); writeFileSync(path, '{}\n')
await vi.waitFor(() => expect(replacement).toBeDefined())
release()
expect(await first).toBe(false)
expect(await replacement).toBe(true)
expect(run.deps.watcher.addSession).toHaveBeenCalledOnce()
expect(run.deps.watcher.addSession).toHaveBeenCalledWith(expect.objectContaining({ transcriptPath: path }), {})
} finally { await discovery.stop() }
})
it.each(['current', 'forget', 'rebind'] as const)('holds a stalled import without writes and fences its late retry: %s', async change => {
const code = await loadEngine('cursor')
vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
let finish!: () => void
vi.mocked(loadEngine).mockImplementationOnce(() => new Promise(resolve => { finish = () => resolve(code) }))
const run = setup({ readerLoadWaitMs: 20 })
const s = session('cursor', transcript([{}]))
const first = run.attach.attachSession(s)
await vi.advanceTimersByTimeAsync(20)
expect(await first).toBe(true)
expect(run.normalizers.hasState(s.sessionId)).toBe(false)
expect(run.deps.watcher.addSession).not.toHaveBeenCalled()
if (change === 'forget') { bindings.delete(s.agentId); run.attach.forget(s.sessionId) }
if (change === 'rebind') s.sessionId = 'another'
finish()
if (change === 'current') await vi.waitFor(() => expect(run.deps.watcher.addSession).toHaveBeenCalledOnce())
else { await vi.advanceTimersByTimeAsync(0); expect(run.deps.watcher.addSession).not.toHaveBeenCalled() }
vi.useRealTimers()
})
it.each([new Error('reader failed'), 'reader failed'])('contains a late reader retry failure: %s', async error => {
const code = await loadEngine('cursor')
vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
const log = vi.spyOn(console, 'error').mockImplementation(() => {})
let finish!: () => void
vi.mocked(loadEngine).mockImplementationOnce(() => new Promise(resolve => { finish = () => resolve(code) }))
const run = setup({ readerLoadWaitMs: 20 })
vi.mocked(run.deps.watcher.addSession).mockRejectedValueOnce(error)
const pending = run.attach.attachSession(session('cursor', transcript([{}])))
await vi.advanceTimersByTimeAsync(20); await pending
finish()
await vi.waitFor(() => expect(log).toHaveBeenCalledWith('[agent] cursor-a reader retry failed: reader failed'))
vi.useRealTimers()
})
it.each(['terminal probe', 'import'] as const)('does not replay twice when a held loader resolves during a newer attach\'s %s', async phase => {
const code = await loadEngine('cursor')
vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
let loaded!: () => void, probed!: () => void
vi.mocked(loadEngine).mockImplementationOnce(() => new Promise(resolve => { loaded = () => resolve(code) }))
const run = setup({ readerLoadWaitMs: 20 })
const event = started('once')
const s = session('cursor', transcript([{ events: [event] }]))
const first = run.attach.attachSession(s, false, true)
await vi.advanceTimersByTimeAsync(20); expect(await first).toBe(true)
if (phase === 'terminal probe') vi.mocked(run.deps.terminalGone).mockImplementationOnce(() => new Promise(resolve => { probed = () => resolve(false) }))
const second = run.attach.attachSession(s, false, true)
await vi.advanceTimersByTimeAsync(0)
loaded()
await vi.advanceTimersByTimeAsync(0)
if (phase === 'terminal probe') probed()
expect(await second).toBe(true)
await vi.waitFor(() => expect(run.attach.attaches.attaching()).toEqual([]))
expect(run.deps.watcher.addSession).toHaveBeenCalledOnce()
expect(run.deps.emit).toHaveBeenCalledExactlyOnceWith(s.sessionId, [event])
expect(made('cursor')).toHaveLength(1)
})
describe('attaching a session whose engine\'s code could not be loaded', () => {
it('holds interpretation without a normalizer or tail, says why, and preserves the binding', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
vi.mocked(loadEngine).mockResolvedValueOnce(null as never).mockResolvedValueOnce(null as never)
const file = setup()
const path = transcript([{ any: 'line' }])
expect(await file.attach.attachSession(session('grok', path))).toBe(true)
expect(file.normalizers.hasState('grok-s')).toBe(false)
expect(file.deps.watcher.addSession).not.toHaveBeenCalled()
expect(file.deps.runtimeProfiles.hydrate).not.toHaveBeenCalled()
expect(file.deps.emit).not.toHaveBeenCalled()
const store = setup()
expect(await store.attach.attachSession(session('opencode'))).toBe(true)
expect(store.normalizers.hasState('opencode-s')).toBe(false)
expect(warn).toHaveBeenCalledWith('[agent] grok-age transcript held · engine=grok · its reader is unavailable or still loading')
expect(warn).toHaveBeenCalledWith('[agent] opencode transcript held · engine=opencode · its reader is unavailable or still loading')
warn.mockRestore()
})
})
describe('attaching a session', () => {
it('installs worker state after hydration, keeps device/profile observations and reuses only a current binding', async () => {
const p = remoteSetup(true), s = session('claude', '/private/transcript')
p.service.needsTranscript.mockReturnValue(true)
expect(await p.attach.attachSession(s)).toBe(true)
expect(p.deps.liveFor).not.toHaveBeenCalled()
expect(p.remote.prepare).toHaveBeenCalledWith(s, { live: false, end: undefined }, expect.any(Function), undefined)
expect(p.profile.ingest).toHaveBeenCalledExactlyOnceWith('metadata')
expect(p.service.observeTranscript).toHaveBeenCalledExactlyOnceWith(s.agentId, s.sessionId, s.engine, 'record')
expect(p.profile.commit).toHaveBeenCalledOnce()
expect(p.normalizers.liveParsers.get(s.sessionId)).toBe(p.handle)
expect(p.remote.install).toHaveBeenCalledWith(p.candidate)
await p.attach.attachSession(s)
expect(p.remote.prepare).toHaveBeenCalledOnce()
vi.mocked(p.remote.current).mockReturnValue(false)
await p.attach.attachSession(s)
expect(p.remote.prepare).toHaveBeenCalledTimes(2)
})
it('activates a first live worker stream without reading locally, including a session whose path is not announced yet', async () => {
const p = remoteSetup(), s = session('claude')
expect(await p.attach.attachSession(s, false, false, true)).toBe(true)
expect(p.remote.prepare).toHaveBeenCalledWith(s, { live: true, end: undefined }, expect.any(Function), undefined)
expect(p.deps.watcher.hold).not.toHaveBeenCalled()
expect(p.normalizers.liveParsers.get(s.sessionId)).toBe(p.handle)
})
it.each(['begin', 'prepare', 'config', 'commit', 'install'])('keeps the crash-resume boundary after a failed %s until an attach commits', async phase => {
let now = 0
vi.spyOn(Date, 'now').mockImplementation(() => now)
const marks = createRelaunchMarks()
const p = remoteSetup(true, { relaunchMarks: marks }), s = session('claude', '/fixture/transcript')
marks.note(s.sessionId, 20, true)
const unavailable = () => { throw new Error('ENGINE_STALE_REPLY') }
if (phase === 'begin') vi.mocked(p.deps.runtimeProfiles.beginHydrate).mockImplementationOnce(unavailable)
if (phase === 'prepare') vi.mocked(p.remote.prepare).mockImplementationOnce(unavailable)
if (phase === 'config') vi.mocked(p.deps.runtimeProfiles.beginHydrate).mockReturnValueOnce({ ...p.profile, config: async () => unavailable() })
if (phase === 'commit') vi.mocked(p.deps.runtimeProfiles.beginHydrate).mockReturnValueOnce({ ...p.profile, commitWith: () => false })
if (phase === 'install') vi.mocked(p.remote.install).mockReturnValueOnce(false)
await p.attach.attachSession(s).catch(() => {})
expect(p.deps.emit).not.toHaveBeenCalled()
expect(p.remote.retry).toHaveBeenCalledWith(s)
expect(marks.size).toBe(1)
// Worker availability cannot age a confirmed resume back into an interrupted live turn.
now = 60 * 60_000
await p.attach.attachSession(s, true)
expect(p.remote.prepare).toHaveBeenLastCalledWith(s, { live: false, end: 20 }, expect.any(Function), undefined)
expect(p.handle.closeTurn).toHaveBeenCalledExactlyOnceWith('abandoned')
expect(p.deps.emit).not.toHaveBeenCalled()
expect(marks.size).toBe(0)
})
it('closes the interrupted history before the resumed engine can deliver a new live turn', async () => {
const marks = createRelaunchMarks()
const p = remoteSetup(true, { relaunchMarks: marks }), s = session('claude', '/fixture/transcript')
marks.note(s.sessionId, 20, true)
vi.mocked(p.deps.watcher.addSession).mockImplementationOnce(async () => {
expect(p.handle.closeTurn).toHaveBeenCalledExactlyOnceWith('abandoned')
p.deps.emit(s.sessionId, [started('after the crash')])
p.handle.closeTurn.mockClear()
})
await p.attach.attachSession(s)
expect(p.deps.emit).toHaveBeenCalledExactlyOnceWith(s.sessionId, [started('after the crash')])
expect(p.handle.closeTurn).not.toHaveBeenCalled()
})
it.each([false, true])('uses a held tail from the old engine only when the engine survived: restarted %s', async restarted => {
const marks = createRelaunchMarks()
const p = remoteSetup(true, { relaunchMarks: marks }), s = session('claude', '/fixture/transcript')
const old = { ...p.handle }
p.normalizers.liveParsers.set(s.sessionId, old)
const hold: TailHold = { offset: 12, expired: false, release: vi.fn() }
vi.mocked(p.deps.watcher.hold).mockResolvedValue(hold)
vi.mocked(p.deps.watcher.tails).mockReturnValue(true)
marks.note(s.sessionId, 20, restarted)
await p.attach.attachSession(s)
expect(p.remote.prepare).toHaveBeenCalledWith(s, { live: false, end: restarted ? 20 : 12 }, expect.any(Function), undefined)
expect(p.handle.closeTurn).toHaveBeenCalledTimes(restarted ? 1 : 0)
expect(p.deps.emit).not.toHaveBeenCalled()
expect(hold.release).toHaveBeenCalled()
expect(marks.size).toBe(0)
})
it.each(['prepare', 'config'])('retries a resumed attach whose tail hold expires during %s', async stage => {
const marks = createRelaunchMarks()
const p = remoteSetup(true, { relaunchMarks: marks }), s = session('claude', '/fixture/transcript')
let expired = stage === 'prepare'
const hold: TailHold = { offset: 12, get expired() { return expired }, release: vi.fn() }
vi.mocked(p.deps.watcher.hold).mockResolvedValue(hold)
if (stage === 'config') vi.mocked(p.deps.runtimeProfiles.ingestConfig).mockImplementationOnce(async () => { expired = true; return false })
marks.note(s.sessionId, 20, true)
await p.attach.attachSession(s)
expect(p.remote.retry).toHaveBeenCalledWith(s)
expect(p.remote.install).not.toHaveBeenCalled()
expect(p.deps.emit).not.toHaveBeenCalled()
expect(marks.read(s.sessionId)).toEqual({ offset: 20, engineStarted: true })
})
it.each([false, true])('retains a binding and retries a failed worker prepare, with an existing tail: %s', async held => {
const p = remoteSetup(), s = session('claude', '/private/transcript')
const old = { ...p.handle }
p.normalizers.liveParsers.set(s.sessionId, old)
const hold: TailHold = { offset: 12, expired: false, release: vi.fn() }
if (held) vi.mocked(p.deps.watcher.hold).mockResolvedValue(hold)
vi.mocked(p.remote.prepare).mockRejectedValueOnce(new Error('ENGINE_UNAVAILABLE'))
expect(await p.attach.attachSession(s, true)).toBe(true)
expect(p.remote.retry).toHaveBeenCalledWith(s)
expect(p.normalizers.liveParsers.get(s.sessionId)).toBe(old)
expect(p.profile.commit).not.toHaveBeenCalled()
expect(p.remote.install).not.toHaveBeenCalled()
if (held) expect(hold.release).toHaveBeenCalled()
expect(await p.attach.attachSession(s, true)).toBe(true)
expect(p.normalizers.liveParsers.get(s.sessionId)).toBe(p.handle)
})
it.each(['prepare', 'config', 'install'])('discards a superseded candidate during %s and keeps the live state', async stage => {
const p = remoteSetup(), s = session('claude', '/private/transcript')
const old = { ...p.handle }
p.normalizers.liveParsers.set(s.sessionId, old)
let expired = stage === 'prepare'
const hold: TailHold = { offset: 12, get expired() { return expired }, release: vi.fn() }
vi.mocked(p.deps.watcher.hold).mockResolvedValue(hold)
if (stage === 'config') vi.mocked(p.deps.runtimeProfiles.ingestConfig).mockImplementation(async () => { expired = true; return false })
if (stage === 'install') vi.mocked(p.remote.install).mockReturnValue(false)
expect(await p.attach.attachSession(s, true)).toBe(true)
expect(p.remote.discard).toHaveBeenCalledWith(p.candidate)
expect(p.normalizers.liveParsers.get(s.sessionId)).toBe(old)
expect(hold.release).toHaveBeenCalled()
})
it('uses the worker only for engines it handles', async () => {
const p = remoteSetup()
const local = setup({ remoteLive: p.remote })
expect(await local.attach.attachSession(session('pi', transcript([])))).toBe(true)
expect(p.remote.prepare).not.toHaveBeenCalled()
})
it('commits staged worker profile state with parser installation and never parses its raw records', async () => {
const p = remoteSetup(), s = session('claude', '/private/transcript')
const order: string[] = []
const ingestFrames = vi.fn(async () => { order.push('evidence') })
const config = vi.fn(async () => { order.push('config') })
const commitWith = vi.fn((install: () => boolean) => { order.push('commit'); return install() })
vi.mocked(p.deps.runtimeProfiles.beginHydrate).mockReturnValue({ ...p.profile, ingestFrames, config, commitWith })
vi.mocked(p.remote.install).mockImplementation(() => { order.push('install'); return true })
expect(await p.attach.attachSession(s)).toBe(true)
expect(order).toEqual(['evidence', 'config', 'commit', 'install'])
expect(ingestFrames).toHaveBeenCalledOnce()
expect(p.profile.ingest).not.toHaveBeenCalled()
expect(p.profile.commit).not.toHaveBeenCalled()
expect(p.deps.runtimeProfiles.ingestConfig).not.toHaveBeenCalled()
expect(p.normalizers.liveParsers.get(s.sessionId)).toBe(p.handle)
})
it.each(['config', 'commit'])('discards and retries a worker profile %s failure without replacing live state', async phase => {
const p = remoteSetup(), s = session('claude', '/private/transcript'), old = { ...p.handle }
p.normalizers.liveParsers.set(s.sessionId, old)
vi.mocked(p.deps.runtimeProfiles.beginHydrate).mockReturnValue({ ...p.profile,
ingestFrames: async () => {}, config: async () => { if (phase === 'config') throw new Error('worker failed') },
commitWith: () => false })
expect(await p.attach.attachSession(s, true)).toBe(true)
expect(p.remote.install).not.toHaveBeenCalled()
expect(p.remote.discard).toHaveBeenCalledWith(p.candidate)
expect(p.remote.retry).toHaveBeenCalledWith(s)
expect(p.normalizers.liveParsers.get(s.sessionId)).toBe(old)
})
it('refuses a session whose pane is gone', async () => {
const { attach, deps } = setup({ terminalGone: vi.fn(async () => true) })
expect(await attach.attachSession(session('pi', transcript()))).toBe(false)
expect(deps.watcher.addSession).not.toHaveBeenCalled()
})
describe('a session it already follows', () => {
it('only makes sure the tail runs — from the start for one that never folded anything', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
const s = session('pi', '/t/pi.jsonl')
run.normalizers.piNormalizers.set(s.sessionId, {} as never)
expect(await run.attach.attachSession(s)).toBe(true)
run.attach.neverFoldedHistory.add(s.sessionId)
await run.attach.attachSession(s)
await run.attach.attachSession(s, false, false, true)
expect(vi.mocked(run.deps.watcher.addSession).mock.calls.map((call) => call[1])).toEqual([
{ fromStart: false }, { fromStart: true }, { fromStart: true },
])
expect(run.attach.neverFoldedHistory.has(s.sessionId)).toBe(false)
})
it('replays Cursor from the start when asked, and asks discovery when Cursor has no transcript yet', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
const withFile = session('cursor', '/t/cursor.jsonl')
run.normalizers.cursorNormalizers.set(withFile.sessionId, {} as never)
await run.attach.attachSession(withFile, false, true)
expect(vi.mocked(run.deps.watcher.addSession).mock.calls[0][1]).toEqual({ fromStart: true })
const noFile = session('cursor', undefined, { sessionId: 'cursor-2' })
run.normalizers.cursorNormalizers.set('cursor-2', {} as never)
await run.attach.attachSession(noFile)
expect(run.deps.cursorDiscovery.add).toHaveBeenCalledWith('cursor-2')
const opencode = session('opencode')
run.normalizers.opencodeReaders.set(opencode.sessionId, {} as never)
expect(await run.attach.attachSession(opencode)).toBe(true)
})
})
describe('a first attach', () => {
it('keeps an unknown engine registered without inventing a Claude parser for its file', async () => {
const run = setup()
const s = session('future-engine', transcript([CLAUDE_PROMPT]))
expect(await run.attach.attachSession(s)).toBe(true)
expect(run.normalizers.hasState(s.sessionId)).toBe(false)
expect(run.deps.emit).not.toHaveBeenCalled()
expect(run.deps.watcher.addSession).toHaveBeenCalledWith(s, {})
})
it('reads Claude Code from the end, hands the tail the byte it stopped at, and replays a turn left open', async () => {
const log = vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
const s = session('claude', transcript([CLAUDE_PROMPT]))
expect(await run.attach.attachSession(s)).toBe(true)
const [, from] = vi.mocked(run.deps.watcher.addSession).mock.calls[0]
expect(from).toEqual({ fromOffset: expect.any(Number) })
expect(run.normalizers.liveParsers.get(s.sessionId)?.turnOpen).toBe(true)
expect(run.profile.commit).toHaveBeenCalled()
expect(run.deps.emit).toHaveBeenCalledWith(s.sessionId, [expect.objectContaining({ type: 'turn_started' })], { resumed: true })
expect(run.attach.replayedFirstTurn.has(s.sessionId)).toBe(true)
expect(run.deps.questionWatcher.start).toHaveBeenCalledWith(s.sessionId)
expect(log.mock.calls.map(([line]) => String(line)).some((line) => line.includes('read the transcript from its end'))).toBe(true)
})
it('reads Codex from the end through its own normalizer, and lets each window name its thinking ids', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
const s = session('codex', transcript([{ type: 'event_msg', payload: { type: 'user_message', message: 'go' } }]))
await run.attach.attachSession(s)
const [codex] = made('codex')
expect(run.normalizers.liveParsers.get(s.sessionId)?.turnOpen).toBe(codex.turnOpen)
codex.turnOpen = true
expect(run.normalizers.liveParsers.get(s.sessionId)?.snapshot().turnOpen).toBe(true)
expect(codex.thinkingPrefix).toMatch(/^thinking-codex-/)
})
it('attaches a Codex session before its rollout exists, ready for its first line', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
expect(await run.attach.attachSession(session('codex'))).toBe(true)
expect(run.normalizers.liveParsers.get('codex-s')?.turnOpen).toBe(made('codex')[0].turnOpen)
expect(run.attach.neverFoldedHistory.has('codex-s')).toBe(true)
})
it('shows the device the raw lines it subscribed to, on either path', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
run.service.needsTranscript.mockReturnValue(true)
await run.attach.attachSession(session('claude', transcript([CLAUDE_PROMPT])))
await run.attach.attachSession(session('pi', transcript([{ events: [] }])))
expect(run.service.observeTranscript).toHaveBeenCalledWith('claude-agent', 'claude-s', 'claude', expect.any(String))
expect(run.service.observeTranscript).toHaveBeenCalledWith('pi-agent', 'pi-s', 'pi', '{"events":[]}')
const none = setup({ device: () => undefined })
expect(await none.attach.attachSession(session('pi', transcript([{}])))).toBe(true)
})
it('attaches a session whose device or runtime profile cannot take in its lines, on either path', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const error = vi.spyOn(console, 'error').mockImplementation(() => {})
// Asking the device whether it watches the session throws: the attach goes on without it.
const asking = setup()
asking.service.needsTranscript.mockImplementation(() => { throw new Error('device state unreadable') })
expect(await asking.attach.attachSession(session('pi', transcript([{ events: [] }])))).toBe(true)
expect(asking.normalizers.piNormalizers.has('pi-s')).toBe(true)
expect(asking.service.observeTranscript).not.toHaveBeenCalled()
// The device watches, but cannot take a line in; the profile cannot be hydrated either.
const run = setup()
run.service.needsTranscript.mockReturnValue(true)
run.service.observeTranscript.mockImplementation(() => { throw new Error('evidence unreadable') })
vi.mocked(run.deps.runtimeProfiles.hydrate).mockImplementation(() => { throw 'profile unreadable' })
expect(await run.attach.attachSession(session('pi', transcript([{ events: [] }, { events: [] }])))).toBe(true)
expect(await run.attach.attachSession(session('claude', transcript([CLAUDE_PROMPT])))).toBe(true)
expect(run.normalizers.piNormalizers.has('pi-s')).toBe(true)
expect(run.service.observeTranscript).toHaveBeenCalledWith('claude-agent', 'claude-s', 'claude', expect.any(String))
expect(run.profile.commit).toHaveBeenCalled()
expect(error.mock.calls).toEqual([
['[transcripts] the device could not take in a line of pi-s; the line goes on to its engine: device state unreadable'],
['[transcripts] the device could not take in a line of pi-s; the line goes on to its engine: evidence unreadable'],
['[transcripts] the runtime profile could not take in a line of pi-s; the line goes on to its engine: profile unreadable'],
['[transcripts] the device could not take in a line of claude-s; the line goes on to its engine: evidence unreadable'],
])
})
it('folds a resumed conversation only up to where its relaunched engine began, and tails the rest live', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const read = vi.fn((_sessionId: string): RelaunchMark | undefined => undefined)
const run = setup({ relaunchMarks: { read, complete: vi.fn() } })
const history = JSON.stringify({ ...CLAUDE_PROMPT, uuid: 'before' })
// The relaunched engine answered a message before this attach: a whole turn after the mark.
const s = session('claude', transcript([history, { ...CLAUDE_PROMPT, uuid: 'after' }, { type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: 'hi' }], stop_reason: 'end_turn' }, uuid: 'a1' }]))
const mark = Buffer.byteLength(history) + 1
read.mockReturnValueOnce({ offset: mark, engineStarted: true })
expect(await run.attach.attachSession(s)).toBe(true)
expect(read).toHaveBeenCalledWith(s.sessionId)
// The tail starts where the engine's own writing began, so its turn reaches every window live.
expect(vi.mocked(run.deps.watcher.addSession).mock.calls[0][1]).toEqual({ fromOffset: mark })
// A mark is for the next attach only: taken even by an attach that only makes sure the tail runs.
read.mockReturnValueOnce({ offset: mark, engineStarted: true })
expect(await run.attach.attachSession(s)).toBe(true)
expect(read).toHaveBeenCalledTimes(2)
})
it('takes over a tail it holds for a reset, resuming it where the read stopped', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
const s = session('claude', transcript([CLAUDE_PROMPT]))
const hold: TailHold = { offset: 1_000_000, expired: false, release: vi.fn() }
vi.mocked(run.deps.watcher.hold).mockResolvedValue(hold)
vi.mocked(run.deps.watcher.tails).mockReturnValue(true)
expect(await run.attach.attachSession(s, true)).toBe(true)
expect(run.deps.watcher.addSession).not.toHaveBeenCalled()
expect(hold.release).toHaveBeenCalledWith(expect.any(Number))
// A hold whose tail is gone by then: the tail is started from the read's end instead.
vi.mocked(run.deps.watcher.tails).mockReturnValue(false)
await run.attach.attachSession(s, true)
expect(run.deps.watcher.addSession).toHaveBeenCalledTimes(1)
// The prompt left a turn open, but the held tail had delivered its start already: never again.
expect(run.deps.emit).not.toHaveBeenCalledWith(s.sessionId, [expect.objectContaining({ type: 'turn_started' })], { resumed: true })
})
it('keeps the live normalizer when the re-read fails or outlasts its hold', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
const expired: TailHold = { offset: 10, expired: true, release: vi.fn() }
vi.mocked(run.deps.watcher.hold).mockResolvedValueOnce(expired)
expect(await run.attach.attachSession(session('claude', transcript([CLAUDE_PROMPT])), true)).toBe(true)
expect(expired.release).toHaveBeenCalledWith()
// The file is gone under the read: it cannot be read through.
const missing: TailHold = { offset: 10, expired: false, release: vi.fn() }
vi.mocked(run.deps.watcher.hold).mockResolvedValueOnce(missing)
await run.attach.attachSession(session('claude', '/nowhere/session.jsonl', { sessionId: 'gone' }), true)
// Expiring after the read, while the profile's config is read.
const late = { offset: 1_000_000, expired: false, release: vi.fn() }
vi.mocked(run.deps.watcher.hold).mockResolvedValueOnce(late as TailHold)
vi.mocked(run.deps.runtimeProfiles.ingestConfig).mockImplementationOnce(async () => { late.expired = true; return true })
await run.attach.attachSession(session('claude', transcript([CLAUDE_PROMPT]), { sessionId: 'late' }), true)
expect(warn.mock.calls.map(([line]) => String(line)).filter((line) => line.includes('kept its live normalizer'))).toEqual([
expect.stringContaining('the re-read outlasted its hold on the tail'),
expect.stringContaining('the re-read could not read the transcript'),
expect.stringContaining('the re-read outlasted its hold on the tail'),
])
expect(run.normalizers.liveParsers.has('late')).toBe(false)
})
it('replays a first turn already on disk when the transcript was born after its agent', async () => {
const log = vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
const s = session('pi', transcript([{ events: [started('first')] }, { events: [{ type: 'text_delta', payload: { content: 'hi' } }] }]))
await run.attach.attachSession(s, false, false, true)
expect(run.deps.emit).toHaveBeenCalledWith(s.sessionId, [expect.objectContaining({ type: 'turn_started' }), expect.objectContaining({ type: 'text_delta' })])
expect(log.mock.calls.map(([line]) => String(line)).some((line) => line.includes('replayed the first turn'))).toBe(true)
// Once replayed, never again.
run.normalizers.piNormalizers.delete(s.sessionId)
vi.mocked(run.deps.emit).mockClear()
await run.attach.attachSession(s, true, false, true)
expect(run.deps.emit).not.toHaveBeenCalled()
})
it('never replays a conversation its engine was relaunched on, however new its transcript', async () => {
const log = vi.spyOn(console, 'log').mockImplementation(() => {})
// A restore after a restart: the transcript is minutes old and was born after its agent, which is
// what the first-turn rule asks, but its engine was relaunched on it, so it is history.
const lines = [CLAUDE_PROMPT, { type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: 'hi' }], stop_reason: 'end_turn' }, uuid: 'a1' }]
const s = session('claude', transcript(lines))
const read = vi.fn((_sessionId: string): RelaunchMark | undefined => ({ offset: statSync(s.transcriptPath!).size, engineStarted: true }))
const run = setup({ relaunchMarks: { read, complete: vi.fn() } })
await run.attach.attachSession(s, false, false, true)
expect(run.deps.emit).not.toHaveBeenCalled()
expect(log.mock.calls.map(([line]) => String(line)).some((line) => line.includes('replayed the first turn'))).toBe(false)
// Cursor's own replay from the start is held to the same rule.
const cursor = session('cursor', undefined, { sessionId: 'cursor-relaunched' })
await run.attach.attachSession(cursor, false, true)
expect(run.deps.emit).not.toHaveBeenCalled()
})
it('announces a turn open at attach while its engine may still be running, never one a new engine left behind', async () => {
const log = vi.spyOn(console, 'log').mockImplementation(() => {})
// The engine was killed mid-turn (the tmux server died): the prompt is in, its answer never came.
const s = session('claude', transcript([CLAUDE_PROMPT]))
const size = statSync(s.transcriptPath!).size
// A daemon restart marks every conversation, and an engine that kept running is still in that turn.
const survived = setup({ relaunchMarks: { complete: vi.fn(), read: () => ({ offset: size, engineStarted: false }) } })
await survived.attach.attachSession(s)
expect(vi.mocked(survived.deps.emit).mock.calls.some((call) => call[2]?.resumed)).toBe(true)
// A resume, or a restore that rebuilt the pane, started a new engine: that turn died with the old one.
const restarted = setup({ relaunchMarks: { complete: vi.fn(), read: () => ({ offset: size, engineStarted: true }) } })
await restarted.attach.attachSession(s)
expect(restarted.deps.emit).not.toHaveBeenCalled()
expect(log.mock.calls.some(([line]) => String(line).includes('left the turn open at attach as history'))).toBe(true)
// Closed where the next message is read, too: its start must not first end a turn nobody saw start.
expect(restarted.normalizers.liveParsers.get(s.sessionId)?.turnOpen).toBe(false)
expect(survived.normalizers.liveParsers.get(s.sessionId)?.turnOpen).toBe(true)
// Codex's own normalizer, likewise.
const codex = session('codex', transcript([{ open: true }]))
const resumed = setup({ relaunchMarks: { complete: vi.fn(), read: () => ({ offset: statSync(codex.transcriptPath!).size, engineStarted: true }) } })
await resumed.attach.attachSession(codex)
expect(resumed.normalizers.liveParsers.get(codex.sessionId)?.turnOpen).toBe(false)
})
it('replays a Claude Code first turn live when born after its agent, unless a held tail already delivered it', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
await run.attach.attachSession(session('claude', transcript([CLAUDE_PROMPT])), false, false, true)
expect(vi.mocked(run.deps.emit).mock.calls[0][2]).toBeUndefined()
const held = setup()
vi.mocked(held.deps.watcher.hold).mockResolvedValue({ offset: 1_000_000, expired: false, release: vi.fn() })
await held.attach.attachSession(session('claude', transcript([CLAUDE_PROMPT])), true, false, true)
expect(vi.mocked(held.deps.emit).mock.calls.every((call) => call[2]?.resumed)).toBe(true)
})
it('marks a session with no transcript yet, so its first content is read whole', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
await run.attach.attachSession(session('pi'))
expect(run.attach.neverFoldedHistory.has('pi-s')).toBe(true)
await run.attach.attachSession(session('cursor'))
expect(run.deps.cursorDiscovery.add).toHaveBeenCalledWith('cursor-s')
expect(run.attach.neverFoldedHistory.has('cursor-s')).toBe(false)
})
it('folds each file engine into its own normalizer, reading the pane where the chips live there', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
const maps: Record<string, Map<string, unknown>> = {
cursor: run.normalizers.cursorNormalizers, muse: run.normalizers.museNormalizers, amp: run.normalizers.ampNormalizers,
grok: run.normalizers.grokNormalizers, agy: run.normalizers.agyNormalizers, copilot: run.normalizers.copilotNormalizers,
pi: run.normalizers.piNormalizers, omp: run.normalizers.ompNormalizers, commandcode: run.normalizers.commandcodeNormalizers,
}
for (const engine of Object.keys(maps)) {
await run.attach.attachSession(session(engine, transcript([{}])))
expect(maps[engine].get(`${engine}-s`), engine).toBe(made(engine)[0])
}
expect(vi.mocked(run.deps.captureTerminal).mock.calls).toEqual([['cursor-agent', 100], ['grok-agent', 60], ['agy-agent', 60]])
expect(run.deps.runtimeProfiles.ingestPane).toHaveBeenCalledTimes(3)
// A pane that cannot be read leaves the chips to the next look.
vi.mocked(run.deps.captureTerminal).mockResolvedValue(null)
for (const engine of ['cursor', 'grok', 'agy']) await run.attach.attachSession(session(engine, transcript([{}]), { sessionId: `${engine}-2` }))
expect(run.deps.runtimeProfiles.ingestPane).toHaveBeenCalledTimes(3)
})
it('closes an agy turn its pane shows finished, and a Copilot turn its records show over', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
vi.mocked(run.deps.captureTerminal).mockResolvedValue(IDLE_AGY)
await run.attach.attachSession(session('agy', transcript([{ events: [started()], open: true }])))
expect(made('agy')[0].turnOpen).toBe(false)
fakes.copilotOpen.value = false
await run.attach.attachSession(session('copilot', transcript([{ events: [started()], open: true }])))
expect(made('copilot')[0].turnOpen).toBe(false)
// Still running by the pane, and by the records: left open, and replayed as a resumed turn.
vi.mocked(run.deps.captureTerminal).mockResolvedValue('working\n esc to cancel')
await run.attach.attachSession(session('agy', transcript([{ events: [started()], open: true }]), { sessionId: 'agy-2' }))
fakes.copilotOpen.value = true
await run.attach.attachSession(session('copilot', transcript([{ events: [started()], open: true }]), { sessionId: 'copilot-2' }))
expect(made('agy')[1].turnOpen).toBe(true)
expect(made('copilot')[1].turnOpen).toBe(true)
expect(vi.mocked(run.deps.emit).mock.calls.filter((call) => call[2]?.resumed).map((call) => call[0])).toEqual(['agy-2', 'copilot-2'])
})
it('closes an idle agy history turn even when newer profile evidence discards the chip update', async () => {
const run = setup({ settled: vi.fn() })
vi.mocked(run.deps.captureTerminal).mockResolvedValue(IDLE_AGY)
vi.mocked(run.deps.runtimeProfiles.capturePane).mockImplementationOnce(async (_session, capture, lines) => {
await capture('agy-agent', lines)
return null
})
await run.attach.attachSession(session('agy', transcript([{ events: [started()], open: true }])))
expect(made('agy')[0].turnOpen).toBe(false)
expect(run.deps.emit).not.toHaveBeenCalled()
expect(run.deps.settled).toHaveBeenCalledExactlyOnceWith('agy-s')
})
it.each(['binding', 'forgotten', 'new turn', 'later binding', 'later normalizer', 'later turn'] as const)(
'does not close or replay agy history after %s supersedes its capture', async change => {
const run = setup({ settled: vi.fn() }), s = session('agy', transcript([{ events: [started()], open: true }]))
let finish!: (value: string) => void
vi.mocked(run.deps.captureTerminal).mockReturnValueOnce(new Promise<string>(resolve => { finish = resolve }))
const mutate = () => {
if (change.includes('binding')) bindings.set(s.agentId, { ...s, boundAt: 2 })
if (change === 'forgotten' || change === 'later normalizer') run.normalizers.agyNormalizers.delete(s.sessionId)
if (change.includes('turn')) made('agy')[0].ingest(JSON.stringify({ open: true }))
}
if (change.startsWith('later')) vi.mocked(run.deps.runtimeProfiles.capturePane).mockImplementationOnce(async (_s, capture) => {
await capture(s.agentId)
queueMicrotask(mutate)
return null
})
const pending = run.attach.attachSession(s)
await vi.waitFor(() => expect(run.deps.captureTerminal).toHaveBeenCalled())
const normalizer = made('agy')[0], close = vi.spyOn(normalizer, 'closeTurn')
if (!change.startsWith('later')) mutate()
finish(change.startsWith('later') ? 'working\n esc to cancel' : IDLE_AGY)
await pending
expect(close).not.toHaveBeenCalled()
expect(run.deps.emit).not.toHaveBeenCalled()
expect(run.deps.settled).not.toHaveBeenCalled()
},
)
it.each(['new turn', 'binding', 'forgotten'] as const)(
'keeps captured agy history fenced through watcher installation: %s', async change => {
for (const pane of [IDLE_AGY, 'working\n esc to cancel']) {
const run = setup({ settled: vi.fn() }), s = session('agy', transcript([{ events: [started()], open: true }]))
vi.mocked(run.deps.captureTerminal).mockResolvedValue(pane)
let finish!: () => void
vi.mocked(run.deps.watcher.addSession).mockReturnValueOnce(new Promise<void>(resolve => { finish = resolve }))
const pending = run.attach.attachSession(s)
await vi.waitFor(() => expect(run.deps.watcher.addSession).toHaveBeenCalled())
const normalizer = run.normalizers.agyNormalizers.get(s.sessionId)!
if (change === 'new turn') normalizer.ingest(JSON.stringify({ open: true }))
if (change === 'binding') bindings.set(s.agentId, { ...s, boundAt: 2 })
if (change === 'forgotten') run.normalizers.agyNormalizers.delete(s.sessionId)
finish()
await pending
expect(run.deps.emit, pane).not.toHaveBeenCalled()
expect(run.deps.settled, pane).not.toHaveBeenCalled()
}
},
)
it('tells the recaps when the last turn was already over at attach, never for one open or killed', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const settled = vi.fn()
const run = setup({ settled })
const ended = (payload = {}) => ({ type: 'turn_ended', payload })
// It ended while the daemon was stopped: its end is history, and only the recaps can still recap it.
await run.attach.attachSession(session('pi', transcript([{ events: [started()], open: true }, { events: [ended()], close: true }])))
await run.attach.attachSession(session('pi', transcript([{ events: [started()], open: true }]), { sessionId: 'open' }))
await run.attach.attachSession(session('pi', transcript([{ events: [started()], open: true }, { events: [ended({ aborted: true })], close: true }]), { sessionId: 'killed' }))
await run.attach.attachSession(session('pi', transcript([{}]), { sessionId: 'none' }))
// Read from the end (Claude Code, Codex), only the last turn's start is history: closed, it ended.
await run.attach.attachSession(session('pi', transcript([{ events: [started()], open: true }, { close: true }]), { sessionId: 'from-end' }))
await run.attach.attachSession(session('codex', transcript([{ events: [started()], open: true }, { close: true }])))
await run.attach.attachSession(session('codex', transcript([{ events: [started()], open: true }]), { sessionId: 'codex-open' }))
expect(settled.mock.calls).toEqual([['pi-s'], ['from-end'], ['codex-s']])
})
it('does not resume a turn left open when its history holds no turn start', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
await run.attach.attachSession(session('pi', transcript([{ open: true }])))
expect(run.deps.emit).not.toHaveBeenCalled()
})
it('polls each database engine through its reader, wired to the funnel', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
for (const engine of ['opencode', 'kilo', 'hermes', 'devin']) await run.attach.attachSession(session(engine))
const [opencode] = made('opencode')
const [kilo] = made('kilo')
const [hermes] = made('hermes')
const [devin] = made('devin')
expect(opencode.opts).toMatchObject({ dbPath: '/db/opencode.db', sessionId: 'opencode-s' })
expect(kilo.opts).toMatchObject({ dbPath: '/db/kilo.db', sessionId: 'kilo-s' })
expect(hermes.opts).toMatchObject({ dbPath: '/db/hermes-hermes-agent.db', sessionId: 'hermes-s' })
expect(devin.opts).toMatchObject({ dbPath: '/db/devin.db', devinHome: '/devin', sessionId: 'devin-s' })
expect(run.normalizers.opencodeReaders.get('opencode-s')).toBe(opencode)
expect(run.normalizers.kiloReaders.get('kilo-s')).toBe(kilo)
expect(run.normalizers.hermesReaders.get('hermes-s')).toBe(hermes)
expect(run.normalizers.devinReaders.get('devin-s')).toBe(devin)
for (const reader of [opencode, kilo, hermes, devin]) {
reader.opts.onEvents([started()])
reader.opts.onFatal(new Error('store missing'))
}
expect(vi.mocked(run.deps.emit).mock.calls.map((call) => call[0])).toEqual(['opencode-s', 'kilo-s', 'hermes-s', 'devin-s'])
expect(warn).toHaveBeenCalledTimes(4)
devin.opts.onTurnAborted('provider error')
expect(run.deps.announceTurnAborted).toHaveBeenCalledWith('devin-s', 'devin', 'provider error')
expect(run.deps.emit).toHaveBeenLastCalledWith('devin-s', [{ type: 'turn_ended', payload: {} }])
// OpenCode and Devin name their model only in the pane.
expect(vi.mocked(run.deps.captureTerminal).mock.calls).toEqual([['opencode-agent', 100], ['devin-agent', 60]])
vi.mocked(run.deps.captureTerminal).mockResolvedValue(null)
await run.attach.attachSession(session('opencode', undefined, { sessionId: 'opencode-2' }))
await run.attach.attachSession(session('devin', undefined, { sessionId: 'devin-2' }))
expect(run.deps.runtimeProfiles.ingestPane).toHaveBeenCalledTimes(2)
})
it('folds any other engine with a plain turn state', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const run = setup()
await run.attach.attachSession(session('terminal', transcript(['{}'])))
expect(run.normalizers.liveParsers.has('terminal-s')).toBe(true)
expect(run.deps.questionWatcher.start).not.toHaveBeenCalled()
})
it('folds only the newest part of a transcript over the cap, and says so', async () => {
vi.spyOn(console, 'log').mockImplementation(() => {})
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
const records = Array.from({ length: 20 }, (_, i) => JSON.stringify({ n: i, pad: 'x'.repeat(40) }))
const capBytes = records.slice(-5).reduce((sum, record) => sum + Buffer.byteLength(record), 0)
const run = setup({ wholeReadCapBytes: capBytes })
await run.attach.attachSession(session('terminal', transcript(records)))
expect(warn).toHaveBeenCalledWith('[agent] terminal transcript over 0 MB · folded from its newest 0 MB')
// The profile was hydrated from what was read: the newest records that fit, in order.
expect(run.deps.runtimeProfiles.hydrate).toHaveBeenCalledWith(expect.objectContaining({ agentId: 'terminal-agent' }), records.slice(-5))
warn.mockClear()
await run.attach.attachSession(session('terminal', transcript(records.slice(0, 3)), { agentId: 'small', sessionId: 'small-s' }))
expect(warn).not.toHaveBeenCalled()
})
})
it('says when an attach is slow', async () => {
vi.useFakeTimers()
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
const run = setup({ terminalGone: () => new Promise<boolean>(() => {}) })
void run.attach.attachSession(session('pi', '/t/pi.jsonl'))
await vi.advanceTimersByTimeAsync(15_000)
expect(String(warn.mock.calls[0][0])).toMatch(/attach still running · engine=pi · session=.* · 15s/)
expect(run.attach.attaches.attaching()).toHaveLength(1)
})
})
it.each(['terminal', 'config', 'worker'] as const)('discards a deferred %s result across a full same-path native hold/recovery', async phase => {
const run = phase === 'worker' ? remoteSetup(true) : setup()
const row = session('claude', transcript([CLAUDE_PROMPT]))
let finish!: () => void
const wait = new Promise<void>(resolve => { finish = resolve })
const entered = vi.fn()
if (phase === 'terminal') vi.mocked(run.deps.terminalGone).mockImplementationOnce(async () => { entered(); await wait; return false })
else if (phase === 'config') vi.mocked(run.deps.runtimeProfiles.ingestConfig).mockImplementationOnce(async () => { entered(); await wait; return false })
else {
const remote = (run as ReturnType<typeof remoteSetup>).remote
const prepare = vi.mocked(remote.prepare).getMockImplementation()!
vi.mocked(remote.prepare).mockImplementationOnce(async (...args) => { const value = await prepare(...args); entered(); await wait; return value })
}
const pending = run.attach.attachSession(row)
await vi.waitFor(() => expect(entered).toHaveBeenCalled())
row.identityHold = 'incomplete'; row.evidenceRevision = 1
delete row.identityHold; row.evidenceRevision = 2; row.interpretationHold = 'replacement pending'
finish(); expect(await pending).toBe(true)
expect(run.deps.emit).not.toHaveBeenCalled()
expect(run.profile.commit).not.toHaveBeenCalled()
expect(run.normalizers.hasState(row.sessionId)).toBe(false)
run.attach.forget(row.sessionId)
})
it.each(['config', 'watcher'] as const)('holds real watcher ingestion through deferred and failed replacement %s, then retries without another event', async phase => {
const watcher = new Watcher()
const run = setup({ watcher })
const file = transcript([]), row = session('claude', file)
const emit = vi.fn(), ingestProfile = vi.fn(), token = vi.fn()
const ingest = createIngest({ liveFor, has: () => true, bySession: () => row, device: () => undefined,
runtimeProfiles: { ingest: ingestProfile }, tokenUsage: { changed: token }, normalizers: run.normalizers,
announceTurnAborted: vi.fn(), emit, attachSession: run.attach.attachSession })
ingest.wireWatcher(watcher)
try {
await run.attach.attachSession(row)
const old = run.normalizers.liveParsers.get(row.sessionId)
row.identityHold = 'header incomplete'; row.evidenceRevision = 1
appendFileSync(file, JSON.stringify(CLAUDE_PROMPT) + '\n')
await watcher.pollSession(row.sessionId)
expect(emit).not.toHaveBeenCalled(); expect(ingestProfile).not.toHaveBeenCalled()
delete row.identityHold; row.evidenceRevision = 2; row.interpretationHold = 'replacement pending'
const entered = vi.fn()
let fail!: (error: Error) => void
const pending = new Promise<void>((_resolve, reject) => { fail = reject })
run.profile.commit.mockClear()
if (phase === 'config') {
vi.mocked(run.deps.runtimeProfiles.beginHydrate).mockReturnValue({ ...run.profile, config: async () => { entered(); await pending } })
} else {
const add = watcher.addSession.bind(watcher)
vi.spyOn(watcher, 'addSession').mockImplementationOnce(async (...args) => { await add(...args); entered(); await pending })
}
const attached = run.attach.attachSession(row) // ordinary caller must see the recovery obligation
await vi.waitFor(() => expect(entered).toHaveBeenCalled())
appendFileSync(file, JSON.stringify({ ...CLAUDE_PROMPT, uuid: 'u2', message: { role: 'user', content: 'while installation waits' } }) + '\n')
await watcher.pollSession(row.sessionId)
expect(emit).not.toHaveBeenCalled(); expect(ingestProfile).not.toHaveBeenCalled(); expect(token).not.toHaveBeenCalled()
expect(run.profile.commit).not.toHaveBeenCalled()
expect(run.normalizers.liveParsers.get(row.sessionId)).not.toBe(old)
fail(new Error('replacement unavailable')); expect(await attached).toBe(true)
expect(row.interpretationHold).toContain(phase === 'config' ? 'runtime profile' : 'replacement unavailable')
expect(run.profile.commit).not.toHaveBeenCalled()
// On the next timer attempt the actual file is read again; stale held lines are history.
vi.mocked(run.deps.runtimeProfiles.beginHydrate).mockReturnValue(run.profile)
await vi.waitFor(() => expect(row.interpretationHold).toBeUndefined(), { timeout: 3_000 })
expect(run.normalizers.liveParsers.get(row.sessionId)).not.toBe(old)
expect(emit).not.toHaveBeenCalled()
appendFileSync(file, JSON.stringify({ type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: 'done' }], stop_reason: 'end_turn' } }) + '\n')
await watcher.pollSession(row.sessionId)
expect(ingestProfile).toHaveBeenCalledTimes(1)
expect(emit).toHaveBeenCalledTimes(1)
// A completed installation gate is temporary. A later legitimate same-path restart must
// hand the existing tail to its next parser without retaining the recovery's pane identity.
row.tmuxPane = '%new'; row.boundAt = 99
await run.attach.attachSession(row, true)
appendFileSync(file, JSON.stringify({ ...CLAUDE_PROMPT, uuid: 'after-reset' }) + '\n')
await watcher.pollSession(row.sessionId)
expect(ingestProfile).toHaveBeenCalledTimes(2)
expect(emit).toHaveBeenCalledTimes(2)
} finally { run.attach.forget(row.sessionId); await watcher.stop() }
})
it.each(['inline', 'worker'] as const)('retains the crash boundary across failed recovery installation and closes the staged %s turn', async mode => {
const marks = createRelaunchMarks()
const run = mode === 'worker' ? remoteSetup(true, { relaunchMarks: marks }) : setup({ relaunchMarks: marks })
const file = transcript([CLAUDE_PROMPT]), row = session('claude', file, { evidenceRevision: 2, interpretationHold: 'replacement pending' })
marks.note(row.sessionId, statSync(file).size, true)
const mark = marks.read(row.sessionId)
const commitWith = vi.fn((install: () => boolean) => install())
vi.mocked(run.deps.runtimeProfiles.beginHydrate).mockReturnValue({ ...run.profile, commitWith })
vi.mocked(run.deps.watcher.addSession).mockRejectedValueOnce(new Error('tail unavailable'))
await run.attach.attachSession(row)
expect(marks.read(row.sessionId)).toBe(mark)
expect(row.interpretationHold).toContain('tail unavailable')
expect(commitWith).not.toHaveBeenCalled()
expect(run.normalizers.liveParsers.get(row.sessionId)?.snapshot().identity).toMatch(/^held:/)
await run.attach.attachSession(row)
expect(row.interpretationHold).toBeUndefined()
expect(marks.read(row.sessionId)).toBeUndefined()
if (mode === 'inline') expect(run.normalizers.sessionTurnOpen(row.sessionId)).toBe(false)
else expect((run as ReturnType<typeof remoteSetup>).handle.closeTurn).toHaveBeenCalledWith('abandoned')
expect(run.deps.emit).not.toHaveBeenCalled()
run.attach.forget(row.sessionId)
})
it('keeps a replacement obligation when the profile commit loses authority during watcher installation', async () => {
const run = setup(), row = session('claude', transcript([CLAUDE_PROMPT]), { evidenceRevision: 2, interpretationHold: 'pending' })
const commitWith = vi.fn(() => false)
vi.mocked(run.deps.runtimeProfiles.beginHydrate).mockReturnValue({ ...run.profile, commitWith })
expect(await run.attach.attachSession(row)).toBe(true)
expect(row.interpretationHold).toContain('superseded during watcher installation')
expect(run.normalizers.liveParsers.get(row.sessionId)?.snapshot().identity).toMatch(/^held:/)
expect(run.deps.emit).not.toHaveBeenCalled()
run.attach.forget(row.sessionId)
})
it.each([new Error('tail read failed'), 'tail read failed'])('contains a failed post-recovery drain: %s', async error => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
const run = setup(), row = session('claude', transcript([]), { evidenceRevision: 2, interpretationHold: 'pending' })
vi.mocked(run.deps.watcher.pollSession).mockRejectedValueOnce(error)
await run.attach.attachSession(row)
expect(row.interpretationHold).toBeUndefined()
expect(warn).toHaveBeenCalledWith(expect.stringContaining('recovered tail read failed'))
run.attach.forget(row.sessionId)
})
it.each(['queued', 'detaching', 'rejected', 'non-error', 'retry-stale'] as const)('fences recovery while %s and does not retire its binding', async phase => {
const run = setup(), row = session('claude', transcript([]), { evidenceRevision: 2, interpretationHold: 'pending' })
let finish!: () => void
const waiting = new Promise<void>(resolve => { finish = resolve })
let first: Promise<boolean> | undefined
if (phase === 'queued') {
const other = session('claude', row.transcriptPath!, { agentId: row.agentId, sessionId: row.sessionId, evidenceRevision: 2 })
bindings.set(row.agentId, row)
delete row.interpretationHold
vi.mocked(run.deps.terminalGone).mockImplementationOnce(async () => { await waiting; return false })
first = run.attach.attachSession(other)
row.interpretationHold = 'pending'
} else if (phase === 'detaching') vi.mocked(run.deps.watcher.removeSession).mockImplementationOnce(async () => { await waiting })
else vi.mocked(run.deps.watcher.removeSession).mockImplementationOnce(async () => {
if (phase === 'rejected') row.evidenceRevision = row.evidenceRevision! + 1
throw phase === 'non-error' ? 'detachment failed' : new Error('detachment failed')
})
const pending = run.attach.attachSession(row)
if (phase === 'queued' || phase === 'detaching') { row.evidenceRevision = row.evidenceRevision! + 1; finish() }
await first; await pending
expect(run.profile.commit).not.toHaveBeenCalled()
expect(run.deps.emit).not.toHaveBeenCalled()
if (phase === 'retry-stale') {
row.evidenceRevision = row.evidenceRevision! + 1
await new Promise(resolve => setTimeout(resolve, 1_100))
expect(run.deps.watcher.removeSession).toHaveBeenCalledOnce()
}
run.attach.forget(row.sessionId)
})
it.each(['inline', 'worker'] as const)('preserves eager cancel while the %s recovery parser is staged', async mode => {
const run = mode === 'worker' ? remoteSetup(true) : setup()
const row = session('claude', transcript([CLAUDE_PROMPT]), { evidenceRevision: 2, interpretationHold: 'pending' })
if (mode === 'worker') (run as ReturnType<typeof remoteSetup>).candidate.page.cursor.offset = statSync(row.transcriptPath!).size
let finish!: () => void
const waiting = new Promise<void>(resolve => { finish = resolve })
vi.mocked(run.deps.watcher.addSession).mockImplementationOnce(async () => { await waiting })
const pending = run.attach.attachSession(row)
await vi.waitFor(() => expect(run.deps.watcher.addSession).toHaveBeenCalledOnce())
const cancel = createCancel({ resolve: () => row, normalizers: run.normalizers,
cursorSubagents: { forget: vi.fn() }, input: { cancel: vi.fn(), cancelConfirmed: vi.fn(async () => true) },
device: () => undefined, stopHeartbeat: vi.fn(), questionWatcher: { stop: vi.fn() }, mirror: { cancel: vi.fn() },
turnActivity: { observe: vi.fn(), snapshot: vi.fn() }, turnStartedAt: new Map(), agentIdFor: () => row.agentId, clients: { send: vi.fn() },
})
await cancel(row.agentId)
finish(); await pending
expect(row.interpretationHold).toContain('turn control changed')
await run.attach.attachSession(row)
expect(row.interpretationHold).toBeUndefined()
if (mode === 'inline') expect(run.normalizers.sessionTurnOpen(row.sessionId)).toBe(false)
else expect((run as ReturnType<typeof remoteSetup>).remote.prepare).toHaveBeenLastCalledWith(
expect.anything(), expect.objectContaining({ closes: [expect.objectContaining({ reason: 'cancel' })] }), expect.anything(), undefined)
expect(run.deps.emit).not.toHaveBeenCalled()
run.attach.forget(row.sessionId)
})
it('coalesces a queued recovery after the first replacement completes', async () => {
const run = setup(), row = session('claude', transcript([]), { evidenceRevision: 2, interpretationHold: 'pending' })
let finish!: () => void
const waiting = new Promise<void>(resolve => { finish = resolve })
vi.mocked(run.deps.terminalGone).mockImplementationOnce(async () => { await waiting; return false }).mockRejectedValueOnce(new Error('must not run a second read'))
const first = run.attach.attachSession(row), second = run.attach.attachSession(row)
finish(); expect(await first).toBe(true); expect(await second).toBe(true)
expect(run.deps.terminalGone).toHaveBeenCalledOnce()
expect(run.deps.watcher.removeSession).toHaveBeenCalledOnce()
expect(row.interpretationHold).toBeUndefined()
expect(run.normalizers.hasState(row.sessionId)).toBe(true)
run.attach.forget(row.sessionId)
})
it('retries a still-current recovery after its pane route moves without another hook', async () => {
const run = setup(), row = session('claude', transcript([]), { evidenceRevision: 2, interpretationHold: 'pending' })
vi.mocked(run.deps.watcher.addSession).mockImplementationOnce(async () => { row.tmuxPane = '%moved' })
await run.attach.attachSession(row)
expect(row.interpretationHold).toBeTruthy()
await vi.waitFor(() => expect(row.interpretationHold).toBeUndefined(), { timeout: 3_000 })
expect(run.deps.watcher.addSession).toHaveBeenCalledTimes(2)
run.attach.forget(row.sessionId)
})
it('revokes a recovery still detaching when its session is forgotten', async () => {
const run = setup(), row = session('claude', transcript([]), { evidenceRevision: 2, interpretationHold: 'pending' })
let finish!: () => void
vi.mocked(run.deps.watcher.removeSession).mockImplementationOnce(() => new Promise<void>(resolve => { finish = resolve }))
const pending = run.attach.attachSession(row)
run.attach.forget(row.sessionId); finish(); await pending
expect(run.deps.terminalGone).not.toHaveBeenCalled()
expect(run.profile.commit).not.toHaveBeenCalled()
expect(run.deps.watcher.addSession).not.toHaveBeenCalled()
})
it('keeps a recovered tail paused if clearing its obligation loses registry authority', async () => {
const setInterpretationHold = vi.fn(() => false), run = setup({ setInterpretationHold })
const row = session('claude', transcript([CLAUDE_PROMPT]), { evidenceRevision: 2, interpretationHold: 'pending' })
await run.attach.attachSession(row)
expect(row.interpretationHold).toBe('pending')
expect(vi.mocked(run.deps.watcher.addSession).mock.calls[0][1]?.deliveryAllowed?.()).toBe(false)
expect(run.deps.watcher.pollSession).not.toHaveBeenCalled()
expect(run.deps.announceSession).not.toHaveBeenCalled()
run.attach.forget(row.sessionId)
})
it('does not reconstruct a retained cancellation when the new recovery obligation cannot be claimed', async () => {
let claim = true
const run = setup({ setInterpretationHold: (_id, _revision, reason) => {
if (!claim) return false
row.interpretationHold = reason
return true
} })
const row = session('claude', transcript([CLAUDE_PROMPT]), { evidenceRevision: 2, interpretationHold: 'pending' })
run.attach.beforeCancel(row); run.normalizers.closeTurns(row.sessionId)
await run.attach.attachSession(row)
expect(row.interpretationHold).toBeUndefined()
claim = false
vi.mocked(run.deps.watcher.addSession).mockClear()
await run.attach.attachSession(row, true)
expect(run.deps.watcher.addSession).not.toHaveBeenCalled()
expect(run.normalizers.sessionTurnOpen(row.sessionId)).toBe(false)
run.attach.forget(row.sessionId)
})
it('keeps normal Stop on its existing path and contains a rejected recovery scheduler', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
const run = setup(), row = session('claude', transcript([]))
run.attach.beforeCancel(row)
expect(run.attach.holdStop(row)).toBe(false)
vi.spyOn(run.attach.attaches, 'attach').mockRejectedValueOnce(new Error('scheduler unavailable'))
run.attach.holdInterpretation(row, 'waiting for evidence')
await vi.waitFor(() => expect(warn).toHaveBeenCalledWith(expect.stringContaining('scheduler unavailable')))
expect(row.interpretationHold).toBe('waiting for evidence')
run.attach.forget(row.sessionId)
})
it.each(['cursor', 'commandcode'] as const)('holds a %s catch-hook completion before a missing parser can hydrate a newer turn', async engine => {
const run = setup(), row = session(engine, transcript([{ open: true, events: [started('newer turn')] }]))
expect(run.attach.holdAdmissionStop(row, false)).toBe(true)
expect(row.interpretationHold).toContain('Stop could not be matched')
await run.attach.attachSession(row, true)
expect(row.interpretationHold).toContain('Stop could not be matched')
expect(run.deps.emit).not.toHaveBeenCalled()
run.attach.forget(row.sessionId)
})
it('holds rebuilt admission interpretation even when a parser still exists, preserving normal immediate Stop', async () => {
const run = setup(), row = session('commandcode', transcript([]))
await run.attach.attachSession(row)
expect(run.attach.holdAdmissionStop(row, false)).toBe(false)
row.identityHold = 'native source unavailable'
expect(run.attach.holdAdmissionStop(row, false)).toBe(true)
delete row.identityHold
row.interpretationHold = 'rebuilding interpretation'
expect(run.attach.holdAdmissionStop(row, false)).toBe(true)
delete row.interpretationHold
expect(run.attach.holdAdmissionStop(row, true)).toBe(true)
run.attach.forget(row.sessionId)
})
it.each(['queued', 'running', 'relaunch'] as const)('retains a Stop while existing interpretation has a %s replacement', async phase => {
const marks = createRelaunchMarks(), run = setup({ relaunchMarks: marks, concurrency: 1 })
const row = session('commandcode', transcript([{ open: true, events: [started('later turn')] }]))
await run.attach.attachSession(row)
vi.mocked(run.deps.emit).mockClear()
let finish!: () => void
let blocker: Promise<boolean> | undefined, reset: Promise<boolean> | undefined
if (phase === 'relaunch') marks.note(row.sessionId, 0, true)
else {
vi.mocked(run.deps.terminalGone).mockImplementationOnce(() => new Promise(resolve => { finish = () => resolve(false) }))
if (phase === 'queued') blocker = run.attach.attachSession(session('claude', transcript([])))
reset = run.attach.attachSession(row, true)
}
expect(run.attach.holdAdmissionStop(row, false)).toBe(true)
expect(row.interpretationHold).toContain('Stop could not be matched')
if (finish) finish()
await blocker; await reset
await run.attach.attachSession(row, true)
expect(row.interpretationHold).toBeTruthy()
expect(run.deps.emit).not.toHaveBeenCalled()
run.attach.forget(row.sessionId)
})
it('acknowledges retained Stop despite an announcement failure so later Cancel remains authoritative', async () => {
const announceSession = vi.fn((): void => { throw new Error('fixture announcement failed') })
const run = setup({ announceSession }), row = session('claude', transcript([CLAUDE_PROMPT]))
expect(run.attach.holdAdmissionStop(row, true)).toBe(true)
expect(row.interpretationHold).toContain('Stop could not be matched')
announceSession.mockImplementation(() => {})
run.attach.beforeCancel(row)
run.normalizers.closeTurns(row.sessionId)
await run.attach.attachSession(row, true)
expect(row.interpretationHold).toBeUndefined()
expect(run.normalizers.sessionTurnOpen(row.sessionId)).toBe(false)
run.attach.forget(row.sessionId)
})
it('revokes captured Stop admission on Cancel, a new conversation and forget without revoking a sibling', () => {
const run = setup(), row = session('cursor'), sibling = session('commandcode')
const first = run.attach.captureAdmissionStop(row), same = run.attach.captureAdmissionStop(row)
const other = run.attach.captureAdmissionStop(sibling)
expect(first()).toBe(true); expect(same()).toBe(true)
run.attach.beforeCancel(row)
expect(first()).toBe(false); expect(same()).toBe(false); expect(other()).toBe(true)
const next = run.attach.captureAdmissionStop(row)
expect(next()).toBe(true)
const rebound = run.attach.captureAdmissionStop({ ...row, sessionId: 'new-conversation' })
expect(next()).toBe(false); expect(rebound()).toBe(true)
run.attach.forget(row.sessionId)
expect(rebound()).toBe(true)
run.attach.forget('new-conversation')
expect(rebound()).toBe(false); expect(other()).toBe(true)
run.attach.forget(sibling.sessionId)
expect(other()).toBe(false)
})
it('recovers a legacy reader without control cuts and holds one that cannot replay them', async () => {
const run = setup(), row = session('muse', transcript([]), { evidenceRevision: 2, interpretationHold: 'pending' })
await run.attach.attachSession(row)
expect(row.interpretationHold).toBeUndefined()
expect(run.normalizers.museNormalizers.has(row.sessionId)).toBe(true)
row.interpretationHold = 'pending'
run.attach.beforeCancel(row); run.normalizers.closeTurns(row.sessionId)
await run.attach.attachSession(row)
expect(row.interpretationHold).toContain('cannot yet replay ordered cancellation')
expect(run.deps.emit).not.toHaveBeenCalled()
run.attach.forget(row.sessionId)
})
it('abandons a legacy open turn at the relaunch boundary', async () => {
const marks = createRelaunchMarks(), run = setup({ relaunchMarks: marks })
const file = transcript([{ open: true, events: [started()] }]), row = session('muse', file)
marks.note(row.sessionId, statSync(file).size, true)
await run.attach.attachSession(row)
expect(run.normalizers.museNormalizers.get(row.sessionId)?.turnOpen).toBe(false)
expect(run.deps.emit).not.toHaveBeenCalled()
expect(marks.read(row.sessionId)).toBeUndefined()
})
it('holds a worker candidate that stops before its cancellation cutoff', async () => {
const run = remoteSetup(), row = session('claude', transcript([CLAUDE_PROMPT]), { evidenceRevision: 2, interpretationHold: 'pending' })
run.attach.beforeCancel(row); run.normalizers.closeTurns(row.sessionId)
await run.attach.attachSession(row)
expect(row.interpretationHold).toContain('did not reach its cancellation boundary')
expect(run.deps.watcher.pollSession).not.toHaveBeenCalled()
run.attach.forget(row.sessionId)
})
it('holds a recovery whose control proxy was replaced during watcher installation', async () => {
const run = setup(), row = session('claude', transcript([CLAUDE_PROMPT]), { evidenceRevision: 2, interpretationHold: 'pending' })
vi.mocked(run.deps.watcher.addSession).mockImplementationOnce(async () => { run.normalizers.liveParsers.delete(row.sessionId) })
await run.attach.attachSession(row)
expect(row.interpretationHold).toContain('superseded during watcher installation')
expect(run.profile.commit).not.toHaveBeenCalled()
expect(run.deps.watcher.pollSession).not.toHaveBeenCalled()
run.attach.forget(row.sessionId)
})
it('replays a crash boundary in order with a retained cancellation', async () => {
const marks = createRelaunchMarks(), run = setup({ relaunchMarks: marks })
const file = transcript([CLAUDE_PROMPT]), row = session('claude', file, { evidenceRevision: 2, interpretationHold: 'pending' })
run.attach.beforeCancel(row); run.normalizers.closeTurns(row.sessionId)
appendFileSync(file, JSON.stringify({ ...CLAUDE_PROMPT, uuid: 'second' }) + '\n')
marks.note(row.sessionId, statSync(file).size, true)
appendFileSync(file, JSON.stringify({ ...CLAUDE_PROMPT, uuid: 'third' }) + '\n')
await run.attach.attachSession(row)
expect(row.interpretationHold).toBeUndefined()
expect(run.normalizers.sessionTurnOpen(row.sessionId)).toBe(true)
expect(marks.read(row.sessionId)).toBeUndefined()
expect(run.deps.emit).not.toHaveBeenCalled()
run.attach.forget(row.sessionId)
})
it('leaves an ordinary database cancellation on its eager native control path', () => {
const run = setup(), row = session('opencode')
run.attach.beforeCancel(row)
expect(row.interpretationHold).toBeUndefined()
expect(run.normalizers.liveParsers.has(row.sessionId)).toBe(false)
expect(run.deps.terminalGone).not.toHaveBeenCalled()
expect(run.deps.watcher.addSession).not.toHaveBeenCalled()
})
it.each(['opencode', 'kilo', 'hermes', 'devin'])('keeps %s Cancel eager after retaining a previous Stop without a file boundary', async engine => {
const run = setup(), row = session(engine)
const reader = { turnOpen: false, closeTurn() { this.turnOpen = false } }
const maps = { opencode: run.normalizers.opencodeReaders, kilo: run.normalizers.kiloReaders,
hermes: run.normalizers.hermesReaders, devin: run.normalizers.devinReaders }
;(maps[engine as keyof typeof maps] as Map<string, unknown>).set(row.sessionId, reader)
run.attach.afterStop(row)
reader.turnOpen = true
run.attach.beforeCancel(row)
run.normalizers.closeTurns(row.sessionId)
expect(reader.turnOpen).toBe(false)
expect(row.interpretationHold).toBeUndefined()
expect(run.normalizers.liveParsers.has(row.sessionId)).toBe(false)
expect(run.deps.watcher.removeSession).not.toHaveBeenCalled()
row.evidenceRevision = 1; row.interpretationHold = 'pending'
await run.attach.attachSession(row)
expect(row.interpretationHold).toContain('no file cancellation boundary')
expect(run.deps.emit).not.toHaveBeenCalled()
run.attach.forget(row.sessionId)
})