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
/**
* Attach: start following a session. The first attach of a session reads its history into its engine's
* normalizer — Claude Code and Codex from the end of the transcript (lib/attachTranscript.ts), the other
* file engines whole, the database engines through a reader that then polls — replays only a turn still
* open, and hands the tail the byte the read stopped at. A later attach of a session it already follows
* only makes sure the tail is running. One attach per session at a time, a few sessions at a time.
*
* Moved verbatim out of `runForeground` (the core boundary, step 9: docs/design/2026-10-03-harnessd.md).
*/
import type { LiveFor } from '../../engines/facets/live.js'
import type { CursorTranscriptDiscovery } from '../../engines/cursor/discovery.js'
import { isOtherEngine, type InProcessModules } from '../../engines/inProcess.js'
import type { AgentEngine } from '../../engines/types.js'
import { pollsQuestions, type QuestionWatcher } from '../../lib/questionController.js'
import { attachTranscript, type AttachRead } from '../../lib/attachTranscript.js'
import { AttachTracker } from '../../lib/attachTracker.js'
import type { WifiFeed } from '../wifi.js'
import { sid } from '../../lib/log.js'
import { foldTranscript, TranscriptFold } from '../../engines/kit/transcriptFold.js'
import type { LiveEvent } from '../../engines/kit/events.js'
import type { RegisteredSession } from '../../lib/registry.js'
import type { RuntimeField, RuntimeProfileManager } from '../../lib/runtimeProfile.js'
import type { ProfileHydration } from '../engines/runtimeProfiles.js'
import { tailFileCapped, WHOLE_READ_CAP_BYTES } from '../../lib/transcriptTail.js'
import type { TailHold, Watcher } from '../../watcher/watcher.js'
import type { SessionNormalizers } from './normalizers.js'
import type { RelaunchMarks } from './relaunch.js'
import { createSideReads } from './sideReads.js'
import { paneReadIdentity } from './readIdentity.js'
import type { LiveSessions, PreparedLive } from '../engines/liveSessions.js'
import { createReaderLoads } from './readerLoads.js'
import { createTurnReplacements } from './turnReplacement.js'
export interface AttachDeps {
liveFor: LiveFor
resolve: (agentId: string) => RegisteredSession | undefined
remoteLive?: Pick<LiveSessions, 'handles' | 'current' | 'prepare' | 'install' | 'discard' | 'retry'>
/** Whether the session's terminal is known to be gone (core/terminals/control.ts `terminalGone`). */
terminalGone: (session: RegisteredSession) => Promise<boolean>
normalizers: SessionNormalizers
watcher: Pick<Watcher, 'addSession' | 'removeSession' | 'pollSession' | 'hold' | 'tails'>
setInterpretationHold: (agentId: string, revision: number | undefined, reason?: string, create?: boolean) => boolean
announceSession: (session: RegisteredSession) => void
cursorDiscovery: Pick<CursorTranscriptDiscovery, 'add'>
/** The Wi-Fi device's service, wherever it runs (core/wifi.ts): it proves its turns by the raw transcript. */
device: () => Pick<WifiFeed, 'needsTranscript' | 'observeTranscript'> | undefined
runtimeProfiles: Pick<RuntimeProfileManager, 'transcriptFields' | 'hydrate' | 'ingestConfig' | 'capturePane'> & {
beginHydrate(session: RegisteredSession): ProfileHydration
ingestPane(session: RegisteredSession, text: string, silent?: boolean): boolean | Promise<boolean>
}
captureTerminal: (target: string, historyLines?: number) => Promise<string | null>
emit: (sessionId: string, events: LiveEvent[], opts?: { resumed?: boolean }) => void
announceTurnAborted: (sessionId: string, engine: string, message: string) => void
questionWatcher: Pick<QuestionWatcher, 'start'>
/** How a session's terminal is named in the log. */
terminalLabel: (session: RegisteredSession) => string
/** The database engines' stores. */
dbs: { opencode: string; kilo: string; devin: string }
devinHome: string
/** Hermes keeps a store per profile: the one this session's lives in. */
hermesDb: (session: RegisteredSession) => Promise<string>
/** How many sessions attach at once. */
concurrency: number
/** The wait for optional code, before any reader has started writing. */
readerLoadWaitMs?: number
/** Where an engine's writing became live again after a relaunch (core/transcripts/relaunch.ts): the fold stops there. */
relaunchMarks?: Pick<RelaunchMarks, 'read' | 'complete'>
/** The most of a transcript an engine without its own reader from the end folds, from its end. */
wholeReadCapBytes?: number
/** The session attached with its last turn already over (core/turns/recaps.ts `settled`). */
settled?: (sessionId: string) => void
}
export function createAttach({
liveFor, resolve, remoteLive, terminalGone, normalizers, watcher, cursorDiscovery, device, runtimeProfiles, captureTerminal, emit,
announceTurnAborted, questionWatcher, terminalLabel, dbs, devinHome, hermesDb, concurrency, relaunchMarks,
wholeReadCapBytes = WHOLE_READ_CAP_BYTES, settled, readerLoadWaitMs, setInterpretationHold, announceSession,
}: AttachDeps) {
const {
liveParsers, cursorNormalizers, opencodeReaders, kiloReaders, museNormalizers, ampNormalizers,
grokNormalizers, agyNormalizers, copilotNormalizers, piNormalizers, ompNormalizers, hermesReaders, devinReaders, commandcodeNormalizers,
} = normalizers
const sideRead = createSideReads()
const readerLoads = createReaderLoads(readerLoadWaitMs)
const turnReplacements = createTurnReplacements(normalizers)
const recoveryRetries = new Map<string, ReturnType<typeof setTimeout>>()
const pendingAttaches = new Map<string, number>()
const admissionStops = new Map<string, { sessionId: string }>()
const captureAdmissionStop = (session: RegisteredSession): (() => boolean) => {
const agentId = session.agentId
let token = admissionStops.get(agentId)
if (token?.sessionId !== session.sessionId) {
token = { sessionId: session.sessionId }
admissionStops.set(agentId, token)
}
const captured = token
return () => admissionStops.get(agentId) === captured
}
const lifetimes = new Map<string, object>()
const forget = (sessionId: string): void => {
readerLoads.forget(sessionId)
lifetimes.delete(sessionId)
turnReplacements.forget(sessionId)
for (const [agentId, token] of admissionStops) if (token.sessionId === sessionId) admissionStops.delete(agentId)
clearTimeout(recoveryRetries.get(sessionId))
recoveryRetries.delete(sessionId)
}
const explainRecovery = (session: RegisteredSession, reason?: string): boolean => {
if (!setInterpretationHold(session.agentId, session.evidenceRevision, reason)) return false
announceSession(resolve(session.agentId)!)
return true
}
const beforeCancel = (session: RegisteredSession): void => {
admissionStops.delete(session.agentId)
if (session.identityHold || session.interpretationHold) turnReplacements.stage(session)
else if (session.transcriptPath || turnReplacements.retains(session)) {
const reason = turnReplacements.cancel(session)
if (reason && session.transcriptPath) holdInterpretation(session, `Waiting for transcript interpretation: ${reason}.`)
}
}
const holdInterpretation = (session: RegisteredSession, reason: string): void => {
turnReplacements.stage(session)
if (setInterpretationHold(session.agentId, session.evidenceRevision, reason, true)) {
const latest = resolve(session.agentId)!
// The control obligation already exists. A failed status notification must
// never make its caller replay that Stop after a later explicit Cancel.
try { announceSession(latest) }
catch (error) { console.warn('[agent] interpretation hold notification failed', error) }
void attachSession(latest, true).catch(error => console.warn(`[agent] recovery held: ${String(error)}`))
}
}
const holdStop = (session: RegisteredSession, force = false): boolean => {
if (!session.identityHold && !session.interpretationHold && !force) return false
turnReplacements.stage(session).stop()
holdInterpretation(session, 'Stop could not be matched to its turn; Cancel can resolve this hold.')
return true
}
const afterStop = (session: RegisteredSession): void => { turnReplacements.stop(session) }
const holdAdmissionStop = (session: RegisteredSession, unmatched: boolean): boolean => {
// A catch hook can supply the first transcript path, or arrive before a
// parser exists. Retain that completion before any recovered fold starts.
if (!unmatched && normalizers.sessionTurnState(session.sessionId) !== undefined
&& !session.identityHold && !session.interpretationHold && !pendingAttaches.has(session.sessionId)
&& !relaunchMarks?.read(session.sessionId)) return false
return holdStop(session, true)
}
/**
* Sessions that attached before their transcript existed, so nothing was folded and nothing has ever
* been streamed for them.
*
* `bornAfterAgent` was supposed to cover this and does not always fire — measured on pi, whose agent is
* discovered the instant the engine starts but whose session file only materialises once the first
* answer is written: the re-attach that finally brought the path tailed from the file's END, so the
* entire first turn — prompt, tools and answer — was read as history and never reached web or device.
* A session that folded NOTHING can replay its whole file live without double-showing anything, which
* is the one case where starting at byte 0 is unambiguously right.
*/
const neverFoldedHistory = new Set<string>()
/**
* Sessions whose first turn has already been replayed live by an attach, or whose transcript an attach
* has already folded.
*
* NOT the same question as `neverFoldedHistory` above, which is why they stay two sets: that one asks
* "where should the watcher start reading?", this one asks "has this session's file already been
* emitted?". A `reset` attach (`meta.isNew` or a repeat `SessionStart`) re-enters the folding branch for
* a session that may already have streamed, and without this the whole transcript would go out a second
* time.
*/
const replayedFirstTurn = new Set<string>()
const attachSessionNow = async (
session: RegisteredSession,
current: () => boolean,
reset = false,
replayCursorFromStart = false,
/**
* Tail the transcript from byte 0 instead of from its current end.
*
* The watcher normally starts at the end, because a session is registered the moment the engine
* starts and the file is empty — end and start are the same place. That stops being true when an
* agent exists BEFORE its session: the user types their first message in the terminal, THAT is what
* makes the engine open a session, and by the time the hook binds it the prompt (and the first of the
* answer) is already on disk. Starting at the end skipped it, so the web showed neither the message
* nor the response. Only ever set for a session that was born after its agent — a resumed one keeps
* tailing from the end, since its history belongs to `session_get`, not to the live stream.
*/
replayFromStart = false,
/** A tail being taken over (see `attachSession`): the hold on it, and where the read that replaces
* its normalizer stopped — the byte the tail resumes from. */
handover: { hold: TailHold | null; next: number | null } = { hold: null, next: null },
): Promise<boolean> => {
// Only a terminal known to be gone refuses an attach, never a probe that could not answer. A failed
// attach costs the agent its binding (agents/bind.ts) or its place among the active (discovery.ts),
// and a probe in flight when the machine slept times out at the wake before its answer is read: the
// session of an agent still at work was unbound that way two seconds after a laptop woke (round 29,
// e2e/clockjump.e2e.ts). A terminal that really is gone is retired by the reconciler's confirmed scans.
if (!current() || await terminalGone(session) || !current()) return false
// Bound only the wait for optional code, before any interpretation writes. A late import gets one
// fenced retry; a missing import holds the transcript intact until an update or restart fixes it.
const other = isOtherEngine(session.engine) ? await readerLoads.read(
session.engine, session.sessionId, paneReadIdentity(session), current, async stillHeld => {
if (current()) await attachSession(session, true, replayCursorFromStart, replayFromStart, stillHeld).catch(error => console.error(
`[agent] ${sid(session.agentId)} reader retry failed: ${error instanceof Error ? error.message : error}`))
}) : null
if (!current()) return false
if (isOtherEngine(session.engine) && !other) {
console.warn(`[agent] ${sid(session.agentId)} transcript held · engine=${session.engine} · its reader is unavailable or still loading`)
return true
}
const engine = <Name extends keyof InProcessModules>(name: Name): InProcessModules[Name] | null =>
session.engine === name ? other as InProcessModules[Name] | null : null
// Reading does not consume the boundary. A stale profile or unavailable worker can abandon this
// attach before installing anything; the next attach must still know the old engine's turn died.
const relaunch = relaunchMarks?.read(session.sessionId)
const relaunchedAt = relaunch?.offset
const remote = remoteLive?.handles(session.engine) ? remoteLive : undefined
if (!relaunch && !reset && normalizers.hasState(session.sessionId) && (!remote || remote.current(session))) {
if (session.transcriptPath) {
const unseen = neverFoldedHistory.delete(session.sessionId)
await watcher.addSession(
{ ...session, transcriptPath: session.transcriptPath },
{ fromStart: replayFromStart || unseen || (session.engine === 'cursor' && replayCursorFromStart) },
)
}
console.log(`[agent] ${sid(session.agentId)} re-attached · engine=${session.engine} · terminal=${terminalLabel(session)} · session=${sid(session.sessionId)}`)
return true
}
const initialEvents: LiveEvent[] = []
// Folding the transcript in below is deliberately silent — old turns must never replay live. But
// when the history ENDS mid-turn the turn is still running, and dropping its `turn_started` costs
// the whole turn: the recaps' mirror (lib/commander.ts onTurnEnded) returns early while turnOpen is false, so the close
// that follows produces no recap and no `done`. Keep the last start and replay exactly that one.
//
// The exception is a transcript BORN AFTER its agent — the file is then the live first turn rather
// than history, and swallowing it loses the whole thing without a trace. `replayLive` routes the same
// fold to `initialEvents`, which is emitted below. Cursor has always done this for its own discovery
// path; the flag simply makes it available to every engine.
//
// Never for a conversation its engine was just relaunched on (a resume, a restart, a restore after
// the machine came back): everything before its relaunch mark existed before this launch, and is
// history. A restore is not a resume to `bind.ts`, so a transcript under ten minutes old
// (lib/firstTurnReplay.ts) went out live again after a daemon restart: its turns, and their recaps
// and notifications, a second time (found end to end, e2e/machine.e2e.ts).
const replayLive = !session.interpretationHold && relaunchedAt === undefined && (
(replayFromStart && !replayedFirstTurn.has(session.sessionId))
|| (session.engine === 'cursor' && replayCursorFromStart))
const historyEvents: LiveEvent[] = []
let historyTurnOpen = false
let historyExplicitlyClosed = false
let historySuperseded = false
let historyCurrent: (() => boolean) | undefined
let observed = false
sideRead('device', session.sessionId, () => { observed = !!device()?.needsTranscript(session.agentId, session.sessionId, session.engine) })
const observe = observed && !session.interpretationHold
? (line: string): void => { if (current()) sideRead('device', session.sessionId, () => device()?.observeTranscript(session.agentId, session.sessionId, session.engine, line)) }
: undefined
// Returns `turnOpen` rather than assigning it: every engine folds exactly once, and a second call
// quietly overwriting the first is the kind of mistake a returned value makes impossible to write.
const take = (out: { history: LiveEvent[]; live: LiveEvent[]; turnOpen: boolean }): boolean => {
// One at a time, not `push(...arr)`: spreading passes every element as a separate argument and Node
// throws RangeError somewhere past 100k of them. Real transcripts are nowhere near that (measured:
// 1194 events out of a 25.6 MB rollout) — but the per-line spread this replaced had no ceiling at
// all, and re-introducing one for no gain would be a poor trade.
for (const event of out.history) historyEvents.push(event)
for (const event of out.live) initialEvents.push(event)
return out.turnOpen
}
// Claude Code and Codex read their transcript from the END: the last turn, plus the few older records
// the chips and a continuing /goal still need — never the whole conversation, which on a long session
// cost the daemon more memory than it has (lib/attachTranscript.ts). Their normalizers exist before
// the read because they fold as the records stream in. The other engines still fold everything.
const adapter = remote ? undefined : liveFor(session.engine)
const parser = adapter?.create(session)
const fields = (line: string): readonly RuntimeField[] => runtimeProfiles.transcriptFields(session, line)
const rules = adapter?.attachRules?.(fields)
const fromEndFold = parser && rules
? { rules, ingest: (line: string) => {
const events = parser.ingest(line).events
if (events.some(event => event.type === 'turn_started' || event.type === 'turn_ended')) historyExplicitlyClosed = false
return events
}, turnOpen: () => parser.turnOpen }
: null
let fromEnd: AttachRead | null = null
let prepared: PreparedLive | null = null
let profileHydration: ProfileHydration | null = null
const replacement = session.interpretationHold ? turnReplacements.stage(session) : undefined
const recoveryPlan = replacement?.plan()
const closes = recoveryPlan?.closes.length ? [
...(relaunch?.engineStarted ? [{ offset: relaunch.offset, reason: 'abandoned' as const }] : []),
...recoveryPlan.closes,
].sort((a, b) => a.offset - b.offset) : undefined
let recoveryInstall = () => replacement!.commit(recoveryPlan!)
let recoveryReady = false
// A reset keeps the normalizer it meant to replace when its read failed, or outlasted the hold on the
// tail — which then let go, and delivery went back to that normalizer: it has seen every record since,
// this one has not.
const keepLiveNormalizer = (why: string): boolean => {
console.warn(`[agent] ${sid(session.agentId)} ${session.interpretationHold ? 'transcript held' : 'kept its live normalizer'} · the re-read ${why}`)
if (session.interpretationHold && current()) explainRecovery(session, `Waiting for transcript interpretation: the re-read ${why}.`)
handover.hold?.release()
handover.next = null
if (relaunch) remote?.retry(session)
return true
}
// A surviving shell can leave its old tail installed. Its cursor is the old engine's delivery
// position; a newly started engine's history ends at the launch boundary instead.
const historyEnd = () => closes ? undefined : relaunch?.engineStarted ? relaunch.offset : handover.hold?.offset ?? relaunchedAt
if (remote) {
if (session.transcriptPath) handover.hold = await watcher.hold(session.sessionId, session.transcriptPath)
const live = replayLive && handover.hold === null
try {
const profile = runtimeProfiles.beginHydrate(session)
profileHydration = profile
prepared = await remote.prepare(session, { live, end: historyEnd(), ...(closes ? { closes } : {}) }, frame => {
if (frame.profile && !profile.ingestFrames) sideRead('runtime profile', session.sessionId, () => profile.ingest(frame.raw))
if (frame.observe && observe) observe(frame.raw)
}, profile.ingestFrames)
if (current() && profile.config) await profile.config()
} catch {
if (prepared) remote.discard(prepared)
remote.retry(session)
return handover.hold ? keepLiveNormalizer('could not reach its engine worker') : true
}
if (handover.hold?.expired) { remote.discard(prepared); return keepLiveNormalizer('outlasted its hold on the tail') }
fromEnd = { next: prepared.page.cursor.offset, records: prepared.records, content: prepared.content }
handover.next = fromEnd.next
historyTurnOpen = !live && prepared.state.handle.turnOpen
historyExplicitlyClosed = !!prepared.page.cursor.closed
if (prepared.page.lastStarted) historyEvents.push(prepared.page.lastStarted)
} else if (session.transcriptPath && fromEndFold) {
// A session already being tailed — a reset — is re-read while its old normalizer is still the one
// being fed: hold its tail, so the read stops exactly where delivery stopped and delivery resumes,
// into the new normalizer, from where the read stopped (released by `attachSession`).
handover.hold = await watcher.hold(session.sessionId, session.transcriptPath)
// Lines a held tail already delivered were seen live; replaying them live again would repeat them.
const live = replayLive && handover.hold === null
const stream = new TranscriptFold(fromEndFold.ingest, fromEndFold.turnOpen, live)
const profile = runtimeProfiles.beginHydrate(session)
profileHydration = profile
const read = await attachTranscript(session.transcriptPath, fromEndFold.rules, {
// Ids named for this window cannot repeat ones another fold of the session sent.
start: (span) => parser!.windowStart(span.turnFrom),
profile: (line) => profile.ingest(line),
fold: (line) => stream.push(line),
close: reason => { parser!.closeTurn(reason); historyExplicitlyClosed = true },
observe,
}, { fromStart: live, end: historyEnd(), closes })
if ((session.interpretationHold && read.failed) || (handover.hold && (read.failed || handover.hold.expired))) {
return keepLiveNormalizer(read.failed ? 'could not read the transcript' : 'outlasted its hold on the tail')
}
if (!current()) return false
try { await profile.config?.() }
catch { return keepLiveNormalizer('could not read its runtime profile') }
fromEnd = read
handover.next = read.next
historyTurnOpen = take(stream.finish())
console.log(`[agent] ${sid(session.agentId)} read the transcript from its end · turn @${read.turnFrom} · profile @${read.profileFrom} · ${read.end} bytes${handover.hold ? ' · took over its tail' : ''}`)
}
// An engine without a reader from the end folds its transcript from the start, bounded: one huge
// transcript read whole would take every agent's daemon down (the October 3 crash, on Codex). Its
// oldest history past the cap is not folded; its last turns, which say whether it is working, are.
let lines: string[] = []
if (session.transcriptPath && !fromEnd) {
const read = await tailFileCapped(session.transcriptPath, wholeReadCapBytes)
if (read.truncated) console.warn(`[agent] ${sid(session.agentId)} transcript over ${Math.round(wholeReadCapBytes / 1024 / 1024)} MB · folded from its newest ${Math.round(wholeReadCapBytes / 1024 / 1024)} MB`)
lines = read.lines
}
if (!current()) {
if (prepared) remote!.discard(prepared)
return false
}
if (!fromEnd) {
if (closes) throw new Error('the native reader cannot yet replay ordered cancellation boundaries')
if (observe) for (const line of lines) observe(line)
sideRead('runtime profile', session.sessionId, () => runtimeProfiles.hydrate(session, lines))
}
if (!profileHydration?.config) await runtimeProfiles.ingestConfig(session, true)
if (!current()) {
if (prepared) remote!.discard(prepared)
return false
}
// From here to the release in `attachSession` nothing is awaited for a held tail, so the hold cannot
// expire between installing the new normalizer and handing it the tail.
if (handover.hold?.expired) {
if (prepared) remote!.discard(prepared)
return keepLiveNormalizer('outlasted its hold on the tail')
}
const fold = (ingest: (line: string) => LiveEvent[], turnOpenAfter: () => boolean): boolean =>
take(foldTranscript(ingest, lines, turnOpenAfter, { live: replayLive }))
if (prepared) {
const install = () => remote!.install(prepared!)
if (!(session.interpretationHold ? install() : profileHydration?.commitWith ? profileHydration.commitWith(install) : install())) {
remote!.discard(prepared); remote!.retry(session)
return keepLiveNormalizer('was superseded while reading')
}
if (!session.interpretationHold && !profileHydration?.commitWith) profileHydration?.commit()
const publish = () => { liveParsers.set(session.sessionId, prepared!.state.handle); return true }
if (replacement) recoveryInstall = () => replacement.commit(recoveryPlan!, prepared!.state.handle)
else publish()
} else if (parser) {
if (!fromEnd) historyTurnOpen = fold((line) => parser.ingest(line).events, () => parser.turnOpen)
const install = () => { liveParsers.set(session.sessionId, parser); return true }
if (replacement) recoveryInstall = () => replacement.commit(recoveryPlan!, parser)
else if (profileHydration?.commitWith) {
if (!profileHydration.commitWith(install)) return keepLiveNormalizer('was superseded while reading')
} else { install(); profileHydration?.commit() }
} else if (engine('cursor')) {
const normalizer = new (engine('cursor')!).CursorNormalizer('live', session.sessionId)
historyTurnOpen = fold((line) => normalizer.ingest(line), () => normalizer.turnOpen)
cursorNormalizers.set(session.sessionId, normalizer)
await runtimeProfiles.capturePane(session, captureTerminal, 100, true)
} else if (engine('opencode')) {
// OpenCode has no transcript file — poll its SQLite DB. The reader hydrates silently, then
// streams new activity into the funnel (the same one the file engines use).
const reader = new (engine('opencode')!).OpencodeReader({
dbPath: dbs.opencode,
sessionId: session.sessionId,
onEvents: (events) => emit(session.sessionId, events),
onFatal: (err) => console.warn(`[opencode] ${sid(session.sessionId)} ${err.message}`),
})
opencodeReaders.set(session.sessionId, reader)
await reader.start()
// The composer footer is the ONLY place OpenCode names its model and reasoning level, so
// without this a freshly opened agent showed empty chips until the five-minute reconcile came
// round — which is exactly how long it looked broken for.
await runtimeProfiles.capturePane(session, captureTerminal, 100, true)
} else if (engine('kilo')) {
// Kilo is opencode's fork and keeps the same store shape, so it is polled the same way — but from
// its OWN db and through its own reader, so the two can diverge without one breaking the other.
const reader = new (engine('kilo')!).KiloReader({
dbPath: dbs.kilo,
sessionId: session.sessionId,
onEvents: (events) => emit(session.sessionId, events),
onFatal: (err) => console.warn(`[kilo] ${sid(session.sessionId)} ${err.message}`),
})
kiloReaders.set(session.sessionId, reader)
await reader.start()
} else if (engine('muse')) {
// Same JSONL tail as claude/pi; only the record shape differs.
const normalizer = new (engine('muse')!).MuseNormalizer()
historyTurnOpen = fold((line) => normalizer.ingest(line), () => normalizer.turnOpen)
museNormalizers.set(session.sessionId, normalizer)
} else if (engine('amp')) {
// A JSONL tail like claude/muse — except the file is written by the adapter's own Amp plugin,
// because Amp is the one engine that keeps no conversation on disk.
const normalizer = new (engine('amp')!).AmpNormalizer()
historyTurnOpen = fold((line) => normalizer.ingest(line), () => normalizer.turnOpen)
ampNormalizers.set(session.sessionId, normalizer)
} else if (engine('grok')) {
const normalizer = new (engine('grok')!).GrokNormalizer()
historyTurnOpen = fold((line) => normalizer.ingest(line), () => normalizer.turnOpen)
grokNormalizers.set(session.sessionId, normalizer)
await runtimeProfiles.capturePane(session, captureTerminal, 60, true)
} else if (engine('agy')) {
const agy = engine('agy')!
// A JSONL tail like claude/grok. agy announces its model only in the hook payload and its pane
// footer, so the pane is read once on attach to fill the chip before the first turn.
const normalizer = new agy.AgyNormalizer()
historyTurnOpen = fold((line) => normalizer.ingest(line), () => normalizer.turnOpen)
agyNormalizers.set(session.sessionId, normalizer)
// agy's transcript has no end-of-turn record - only its Stop hook does - so a fold of a FINISHED
// conversation still reports the last turn as open, and after a daemon restart nothing is ever
// coming to close it. The pane is the one place the answer exists; ask it.
const agentId = session.agentId, sessionId = session.sessionId, identity = paneReadIdentity(session)
const revision = normalizer.turnRevision
let observedRevision = revision
let current = true
historyCurrent = () => paneReadIdentity(resolve(agentId)) === identity
&& agyNormalizers.get(sessionId) === normalizer && normalizer.turnRevision === observedRevision
const capturing = captureTerminal(agentId, 60)
await Promise.all([
runtimeProfiles.capturePane(session, () => capturing, 60, true),
capturing.then(capture => {
// Turn closing owns its own authority: accepting a chip update is not a prerequisite.
current = paneReadIdentity(resolve(agentId)) === identity && agyNormalizers.get(sessionId) === normalizer
if (!current) return
if (normalizer.turnRevision !== revision) { historySuperseded = true; return }
if (historyTurnOpen && capture && agy.agyPaneIdle(capture)) {
normalizer.closeTurn()
historyTurnOpen = false
}
observedRevision = normalizer.turnRevision
}),
])
if (!current || paneReadIdentity(resolve(agentId)) !== identity || agyNormalizers.get(sessionId) !== normalizer) {
if (agyNormalizers.get(sessionId) === normalizer) agyNormalizers.delete(sessionId)
return keepLiveNormalizer('changed binding while its pane was read')
}
if (normalizer.turnRevision !== observedRevision) historySuperseded = true
} else if (engine('copilot')) {
const copilot = engine('copilot')!
// A JSONL tail like claude/agy. Its turn lifecycle comes from the agentStop hook, not the file —
// which is exactly why a fold cannot be trusted on its own: `copilot --resume` replays a finished
// conversation, the fold opens a turn on its last `user.message`, and no hook is coming to close
// it. Ask the records where the last activity actually ended.
const normalizer = new copilot.CopilotNormalizer()
historyTurnOpen = fold((line) => normalizer.ingest(line), () => normalizer.turnOpen)
copilotNormalizers.set(session.sessionId, normalizer)
if (historyTurnOpen && !copilot.copilotHistoryTurnOpen(lines)) {
normalizer.closeTurn()
historyTurnOpen = false
}
} else if (engine('pi')) {
const normalizer = new (engine('pi')!).PiNormalizer('live')
// Hydrate state silently; never replay history live — except a turn left open, below.
historyTurnOpen = fold((line) => normalizer.ingest(line), () => normalizer.turnOpen)
piNormalizers.set(session.sessionId, normalizer)
} else if (engine('omp')) {
const normalizer = new (engine('omp')!).OmpNormalizer('live')
// Hydrate state silently; never replay history live — except a turn left open, below.
historyTurnOpen = fold((line) => normalizer.ingest(line), () => normalizer.turnOpen)
ompNormalizers.set(session.sessionId, normalizer)
} else if (engine('hermes')) {
// Hermes has no transcript file — poll its SQLite store, like opencode.
const reader = new (engine('hermes')!).HermesReader({
dbPath: await hermesDb(session),
sessionId: session.sessionId,
onEvents: (events) => emit(session.sessionId, events),
onFatal: (err) => console.warn(`[hermes] ${sid(session.sessionId)} ${err.message}`),
})
hermesReaders.set(session.sessionId, reader)
await reader.start()
} else if (engine('devin')) {
// Devin has no transcript file either — poll its SQLite store, like hermes/opencode.
const reader = new (engine('devin')!).DevinReader({
dbPath: dbs.devin,
devinHome,
sessionId: session.sessionId,
onEvents: (events) => emit(session.sessionId, events),
// Devin has no StopFailure: a turn that dies on a provider error writes no assistant row and
// fires no Stop hook, so surface the failure and close the turn ourselves — otherwise the web
// sits on the typing indicator forever.
onTurnAborted: (message) => {
announceTurnAborted(session.sessionId, 'devin', message)
emit(session.sessionId, [{ type: 'turn_ended', payload: {} }])
},
onFatal: (err) => console.warn(`[devin] ${sid(session.sessionId)} ${err.message}`),
})
devinReaders.set(session.sessionId, reader)
await reader.start()
// Devin's model/effort exist ONLY in its pane footer, so read it now. Without this the chip stayed
// on Auto until the 5-minute reconcile happened to run — the attach itself said nothing about it.
await runtimeProfiles.capturePane(session, captureTerminal, 60, true)
} else if (engine('commandcode')) {
const normalizer = new (engine('commandcode')!).CommandCodeNormalizer('live')
// Hydrate state silently; never replay history live — except a turn left open, below.
historyTurnOpen = fold((line) => normalizer.ingest(line), () => normalizer.turnOpen)
commandcodeNormalizers.set(session.sessionId, normalizer)
}
if (!current()) return false
// Close the old engine's turn before starting the tail: addSession may synchronously deliver a
// new turn written after resume. Closing afterward would abandon that new turn instead.
const abandonedHistory = !closes && !historySuperseded && historyTurnOpen && relaunch?.engineStarted
if (abandonedHistory) {
console.log(`[agent] ${sid(session.agentId)} left the turn open at attach as history · it began before its engine was started again`)
const folds: Array<Map<string, { closeTurn(): unknown }>> = [cursorNormalizers, museNormalizers, ampNormalizers,
grokNormalizers, agyNormalizers, copilotNormalizers, piNormalizers, ompNormalizers, commandcodeNormalizers]
for (const fold of folds) fold.get(session.sessionId)?.closeTurn()
const closing = prepared?.state.handle ?? parser ?? liveParsers.get(session.sessionId)
closing?.closeTurn('abandoned')
}
if (session.transcriptPath) {
neverFoldedHistory.delete(session.sessionId)
// Deliberately NOT `fromStart`, even when the caller asked for it: this branch has just folded the
// file into the normalizer above, so replaying it from byte 0 emits every line a second time.
// Measured: a claude turn opened, closed after 44ms and opened again, because the fold replayed the
// open turn and the watcher then re-read the same bytes. `fromStart` belongs to the re-attach path,
// which folds nothing. A transcript read from its end hands the tail the exact byte it stopped at.
// A held tail is already this session's, and resumes from there when the hold is released.
if (!handover.hold || !watcher.tails(session.sessionId, session.transcriptPath)) {
await watcher.addSession({ ...session, transcriptPath: session.transcriptPath }, {
...(fromEnd ? { fromOffset: fromEnd.next } : {}),
...(session.interpretationHold ? { deliveryAllowed: () => recoveryReady } : {}),
})
}
} else if (session.engine !== 'cursor') {
// No transcript to fold: whatever this session writes later is its FIRST content, so the re-attach
// that brings the path must read the file whole rather than from its end.
neverFoldedHistory.add(session.sessionId)
}
if (!current()) return false
if (session.interpretationHold) {
if (closes && fromEnd!.next < closes.at(-1)!.offset) return keepLiveNormalizer('did not reach its cancellation boundary')
replacement!.check(recoveryPlan!)
// Both parser and tail are installed. Reads held during watcher installation kept their cursors;
// resume them only now, after clearing the obligation under the same evidence revision.
if (profileHydration?.commitWith) {
if (!profileHydration.commitWith(recoveryInstall)) return keepLiveNormalizer('was superseded during watcher installation')
} else {
if (!recoveryInstall()) return keepLiveNormalizer('was superseded during watcher installation')
profileHydration?.commit()
}
if (!explainRecovery(session)) return keepLiveNormalizer('lost its binding while clearing the hold')
if (relaunch) relaunchMarks!.complete(session.sessionId, relaunch)
recoveryReady = true
void watcher.pollSession(session.sessionId).catch(error => console.warn(
`[agent] ${sid(session.agentId)} recovered tail read failed: ${error instanceof Error ? error.message : error}`))
}
if (!session.interpretationHold && relaunch) relaunchMarks!.complete(session.sessionId, relaunch)
// Marked on the FOLD, not on the emission. A live fold that happened to produce nothing — the file
// was still empty when this attach ran — would otherwise leave the session unmarked, and the next
// `reset` attach (claude fires `SessionStart` on compact, which resets) would fold the by-then
// complete transcript and emit it live on top of everything the watcher had already streamed. That
// is the same duplicate-turn class this whole change exists to remove.
// Any fold of a transcript with content counts too: the watcher now tails it from the end, so a later
// replay could only send history out again as if it were live.
if (replayLive || lines.length || fromEnd?.content) replayedFirstTurn.add(session.sessionId)
// Installing the file watcher also yields. The final history consumer must still own the capture.
if (historyCurrent && !historyCurrent()) historySuperseded = true
if (!historySuperseded && initialEvents.length) {
emit(session.sessionId, initialEvents)
console.log(`[agent] ${sid(session.agentId)} replayed the first turn its transcript already held · ${initialEvents.length} events`)
}
console.log(`[agent] ${sid(session.agentId)} attached · engine=${session.engine} · terminal=${terminalLabel(session)} · session=${sid(session.sessionId)} · lines=${fromEnd ? fromEnd.records : lines.length}`)
// A first prompt that lands while this attach is running is already in the transcript we just
// folded, so its turn_started was consumed as history and the live turn would end up untracked.
// Replay that one event, after the attach log, so the recovery is visible in order.
// Not for a tail this attach took over: everything before the hold was delivered live, the turn's
// start included. Claude Code announces its session again when it compacts, often in the middle of
// a long turn, and replaying the start showed every window that turn starting twice
// (e2e/compaction.e2e.ts).
// Nor for a turn left open before a new engine was started on the conversation (a resume, or a restore
// that rebuilt the pane): that turn died with the engine before, and announcing it showed the
// interrupted message starting anew (core/transcripts/relaunch.ts).
if (!session.interpretationHold && !historySuperseded && historyTurnOpen && !handover.hold && !abandonedHistory) {
const opened = historyEvents.findLast((event) => event.type === 'turn_started')
if (opened) {
console.log(`[agent] ${sid(session.agentId)} resumed the turn already open at attach`)
emit(session.sessionId, [opened], { resumed: true })
}
}
// Watch this pane for a question from ATTACH, not only from the next turn_started.
//
// A turn-scoped start assumes the agent exists before its turn does, and for some engines it does not:
// OpenCode registers itself when its FIRST message creates the session, i.e. the turn is already
// running by the time the daemon knows the agent — so its question opened and nothing announced it
// (measured: the dialog sat on the pane, the device saw nothing). Command Code has the mirror problem,
// asking AFTER the turn ends. The watcher is idempotent, no-ops without a device, and dies with the
// session, so starting it early costs nothing.
if (pollsQuestions(session.engine)) questionWatcher.start(session.sessionId)
// The last turn was over before this attach read it (it ended while the daemon was stopped: an update, a
// restart, a dial being flashed): its end went into history, and nothing recapped it. On 2026-10-07 a
// Codex answer landed nine seconds into a restart and the dial showed the agent blank. The recaps recap
// such a turn as history, once; one they already hold is left alone.
// A fold from the end keeps only the last turn's start as history (lib/normalize.ts TranscriptFold), so a turn
// that is no longer open is one that ended; a fold from the start keeps its end too, and says if it was killed.
const last = historyEvents.findLast((event) => event.type === 'turn_started' || event.type === 'turn_ended')
if (!historyExplicitlyClosed && !historySuperseded && !historyTurnOpen && last && !(last.type === 'turn_ended' && last.payload.aborted)) settled?.(session.sessionId)
return true
}
/** One attach per session, a few sessions at a time, and a record of what is being read — see lib/attachTracker. */
const attaches = new AttachTracker<AgentEngine>({
concurrency,
onSlow: (session, elapsedMs) => console.warn(
`[agent] ${sid(session.agentId)} attach still running · engine=${session.engine} · session=${sid(session.sessionId)} · ${Math.round(elapsedMs / 1000)}s`,
),
})
const attachSession = (
session: RegisteredSession,
reset = false,
replayCursorFromStart = false,
replayFromStart = false,
retryCurrent?: () => boolean,
): Promise<boolean> => {
// Compaction and ordinary SessionStart also reconstruct parsers. A prior explicit closure still
// belongs to this conversation and must survive those resets, not only native-evidence recovery.
if (reset && turnReplacements.retains(session) && !session.identityHold && !session.interpretationHold
&& paneReadIdentity(resolve(session.agentId)) === paneReadIdentity(session)) {
if (setInterpretationHold(session.agentId, session.evidenceRevision, 'Reapplying retained turn control.', true)) {
session = { ...resolve(session.agentId)! }
announceSession(session)
} else return Promise.resolve(true)
}
// An unavailable identity is still the agent's binding, but grants no interpretation authority.
// Snapshot the mutable row before yielding so a later bind cannot redirect this read's writes.
session = { ...session, interpretationHold: resolve(session.agentId)?.interpretationHold }
const authority = paneReadIdentity(session)
const lifetime = lifetimes.get(session.sessionId) ?? {}
lifetimes.set(session.sessionId, lifetime)
const current = () => lifetimes.get(session.sessionId) === lifetime && paneReadIdentity(resolve(session.agentId)) === authority
if (!current()) return Promise.resolve(false)
if (session.identityHold) return Promise.resolve(true)
// Every caller observes this obligation, including an ordinary hook racing discovery's reset.
if (session.interpretationHold) { reset = true; replayFromStart = false; replayCursorFromStart = false }
readerLoads.supersede(session.sessionId, authority)
// Location is core control, outside the optional reader pool. Four stalled readers must not
// prevent a fifth Cursor session finding its file. add records its candidate synchronously, so
// forget's remove revokes it even while the first filesystem lookup is pending.
if (session.engine === 'cursor' && !session.transcriptPath) {
void cursorDiscovery.add(session.sessionId).catch(error => console.error(
`[cursor-discovery] lookup failed: ${error instanceof Error ? error.message : error}`))
}
const key = session.sessionId
pendingAttaches.set(key, (pendingAttaches.get(key) ?? 0) + 1)
return attaches.attach(session, reset, async () => {
// A normal attach may have taken the import's result while this retry waited for its slot.
if (retryCurrent && !retryCurrent()) return false
// A tail an attach holds (a Claude Code or Codex reset, see attachSessionNow) is released only
// here, after the whole attach — the new normalizer installed and any open turn said to be open —
// so delivery resumes into it, in order. Released on every exit, however the attach ends.
const handover = { hold: null as TailHold | null, next: null as number | null }
try {
if (session.interpretationHold) {
if (!current()) return false
// Another queued recovery may already have fulfilled this same obligation.
if (!resolve(session.agentId)?.interpretationHold) return true
turnReplacements.stage(session)
await watcher.removeSession(session.sessionId)
if (!current()) return false
}
const attached = await attachSessionNow(session, current, reset, replayCursorFromStart, replayFromStart, handover)
// A hold that arrived during the read is not evidence that the terminal disappeared.
return attached || !!resolve(session.agentId)?.identityHold || !!resolve(session.agentId)?.interpretationHold
} catch (error) {
if (!session.interpretationHold) throw error
if (current()) explainRecovery(session, `Waiting for transcript interpretation: ${error instanceof Error ? error.message : error}`)
return true
} finally {
handover.hold?.release(handover.next)
const obligation = () => {
const latest = resolve(session.agentId)
return lifetimes.get(session.sessionId) === lifetime && latest?.sessionId === session.sessionId && latest.evidenceRevision === session.evidenceRevision
&& !latest.identityHold && latest.interpretationHold ? latest : undefined
}
if (obligation() && !recoveryRetries.has(session.sessionId)) {
// One bounded, revision-fenced retry per conversation. An unavailable reader is still work
// to do even when its attach returned true to preserve the live binding.
recoveryRetries.set(session.sessionId, setTimeout(() => {
recoveryRetries.delete(session.sessionId)
const latest = obligation()
if (latest) void attachSession(latest, true)
}, 1_000))
recoveryRetries.get(session.sessionId)!.unref()
}
}
}, authority).finally(() => {
const pending = pendingAttaches.get(key)! - 1
if (pending) pendingAttaches.set(key, pending)
else pendingAttaches.delete(key)
})
}
return { attachSession, attaches, neverFoldedHistory, replayedFirstTurn, forget, beforeCancel, afterStop, holdStop, holdAdmissionStop, holdInterpretation, captureAdmissionStop }
}
export type Attach = ReturnType<typeof createAttach>