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
/**
* Binding: a session to its agent (`handleRegistered`, after the registry took a hook's or a discovery's
* registration) and a running engine process to the session it is in (`bindObservedAgent`, from the
* reconciler's scans: a resume named on the command line, a session the process changed to without a
* hook, or one repaired by looking for it).
*
* Moved verbatim out of `runForeground` (the core boundary, step 10: docs/design/2026-10-03-harnessd.md).
*/
import { stat } from 'node:fs/promises'
import { transcriptOf, processSessionOf } from '../../engines/identities.js'
import { IdentityReadUnavailable } from '../../engines/kit/identityScan.js'
import { cursorDataDir } from '../../engines/cursor/contract.js'
import { continuationOf } from '../../engines/sessionFiles.js'
import { sessionStoreOf } from '../../engines/sessionStoreContracts.js'
import type { TurnRecaps } from '../turns/recaps.js'
import { paneReadIdentity } from '../transcripts/readIdentity.js'
import type { AutonomousDeviceInput } from '../deviceInput.js'
import { isRecentlyDeleted } from '../../lib/deletedSessions.js'
import { transcriptIsFirstTurn } from '../../lib/firstTurnReplay.js'
import { sid } from '../../lib/log.js'
import { projectDisplayName, type registry, type RegisteredSession } from '../../lib/registry.js'
import type { SessionInputController } from '../../lib/sessionInput.js'
import { findLiveSession, findResumedTranscript } from '../../lib/sessionRepair.js'
import type { StoppedAgentStore } from '../../lib/stoppedAgents.js'
import { conversationKey, type ConversationOwners } from './conversationOwners.js'
import type { DiscoveredTerminalAgent } from '../../lib/terminalAgentDiscovery.js'
/** Between session-binding attempts for a process whose engine store is not resolvable yet. */
const REPAIR_RETRY_MS = 60_000
/** A NEW process is waiting for a session that is about to appear. Muse makes
* this concrete — its session is only claimable once the user has typed, because a file with no turn in
* it cannot be told apart from the ones muse opens for itself. Backing off a full minute there costs the
* FIRST message: the pane answers while web and device show nothing. So keep sweeping for a while first,
* then settle into the slow rhythm for processes that will never resolve. */
const REPAIR_EAGER_ATTEMPTS = 24 // ≈2 min at the 5s sweep
/** Birth time of a transcript in ms, or 0 when it cannot be read (treated as "not newer than the agent").
* A filesystem that keeps no birth time reports 0 for it: the change time, then the write time, stand in. */
export async function statBirthMs(path: string, statFile: (path: string) => Promise<{ birthtimeMs: number; ctimeMs: number; mtimeMs: number }> = stat): Promise<number> {
const st = await statFile(path).catch(() => null)
if (!st) return 0
const birth = st.birthtimeMs || st.ctimeMs || st.mtimeMs
return Number.isFinite(birth) ? birth : 0
}
/** What the registry says about a registration it just took. */
export type RegisteredMeta = {
isNew: boolean
evicted: string | null
rebound: string | null
orphaned?: { agentId: string; sessionId: string } | null
hookEvent?: string
/** A saved binding's evidence recovered; rebuild even an inline parser of the old file. */
recovered?: boolean
}
export interface BindDeps {
registry: Pick<typeof registry, 'inheritName' | 'unbindSession' | 'byAgent' | 'byProcess' | 'register' | 'has' | 'bySession' | 'setIdentityHold' | 'revalidateBinding'>
mirror: Pick<TurnRecaps, 'inheritSummary'>
forgetSession: (id: string, opts?: { force?: boolean; keepAgent?: boolean; agentId?: string }) => void
/** The app. */
clients: { send(frame: { type: string; payload: Record<string, unknown> }): void }
attachSession: (session: RegisteredSession, reset?: boolean, replayCursorFromStart?: boolean, replayFromStart?: boolean) => Promise<boolean>
announceSession: (session: RegisteredSession) => void
stoppedAgents: Pick<StoppedAgentStore, 'save' | 'finishResume' | 'get'>
syncRecapPool: () => void
input: Pick<SessionInputController, 'forget'>
deviceInput: Pick<AutonomousDeviceInput, 'forget'>
/** Where Copilot, Grok and agy keep their sessions. */
homes: { copilot: string; grok: string; agy: string }
/** One owner per conversation, stopped harnesses included (conversationOwners.ts). */
owners?: Pick<ConversationOwners, 'settle'>
}
export function createBinding({
registry, mirror, forgetSession, clients, attachSession, announceSession, stoppedAgents, syncRecapPool,
input, deviceInput, homes, owners,
}: BindDeps) {
/**
* Forks whose engine session has not reported in yet, agentId → the SOURCE's sessionId. A fork's tile
* should open with the source's last recap on it, the way its pane opens with the source's transcript
* — but the mirror keys by session, and the fork's session id is the engine's to name, minutes later
* over a hook. Settled the moment it binds, below.
*/
const pendingForkInherit = new Map<string, string>()
/** Whether a stop, restart, retarget or resume owns the agent right now (`whileChanging`). */
let changing: (agentId: string) => boolean = () => false
const handleRegistered = async (entry: RegisteredSession, meta: RegisteredMeta): Promise<void> => {
const authority = paneReadIdentity(entry)
const current = () => paneReadIdentity(registry.byAgent(entry.agentId)) === authority
if (!current() || entry.identityHold) return
const forkSource = pendingForkInherit.get(entry.agentId)
if (forkSource && entry.sessionId) {
pendingForkInherit.delete(entry.agentId)
mirror.inheritSummary(forkSource, entry.sessionId)
}
if (meta.rebound) {
registry.inheritName(meta.rebound, entry.sessionId)
mirror.inheritSummary(meta.rebound, entry.sessionId)
forgetSession(meta.rebound, { force: true, keepAgent: true })
clients.send({ type: 'session_reset', payload: { staleSessionId: meta.rebound } })
console.log(`[agent] ${sid(entry.agentId)} rebound ${sid(meta.rebound)} → ${sid(entry.sessionId)}`)
} else if (meta.evicted) {
forgetSession(meta.evicted, { force: true })
}
// The agent this bind emptied out — `claude --resume` in a second pane, with
// the first one's engine already gone. The registry dropped it; without this
// the app kept showing it until someone hit Reload machines by hand, and
// opening it landed on TERMINAL FROZEN because it has nothing left to open.
//
// Not part of the chain above: a rebound bind can orphan an agent too, so
// this has to be asked independently of which branch ran.
if (meta.orphaned) {
forgetSession(meta.orphaned.agentId, {
force: true,
agentId: meta.orphaned.agentId,
})
}
// Registration is complete before any optional history reader runs. In particular a stalled
// module cannot withhold a resumed agent's record, name or announcement. Capture this fact before
// finishResume changes the stopped record used to decide whether history may be replayed below.
const resumedConversation = !!entry.resumeOnly && stoppedAgents.get(entry.agentId)?.sessionId === entry.sessionId
try {
stoppedAgents.save(entry)
} catch (error) {
console.error(`[agent] ${sid(entry.agentId)} could not save the record it resumes from: ${error instanceof Error ? error.message : error}`)
}
if (entry.resumeOnly) stoppedAgents.finishResume(entry.agentId)
// A conversation new to this harness has one owner from now on: a stopped harness it came from (a
// `/resume`, `claude --resume` in a terminal, a compaction) lets it go, as a running one already has.
if (meta.isNew) {
try { owners?.settle([conversationKey(entry)]) }
catch (error) { console.warn(`[agent] ${sid(entry.agentId)} could not settle who owns ${sid(entry.sessionId)}: ${error instanceof Error ? error.message : error}`) }
}
syncRecapPool()
if (meta.isNew) {
registry.inheritName(entry.agentId, entry.sessionId)
announceSession(entry)
clients.send({
type: 'session_synced',
payload: {
sessionId: entry.sessionId,
agentId: entry.agentId,
title: projectDisplayName(entry),
createdAt: new Date(entry.boundAt ?? Date.now()).toISOString(),
},
})
}
// agy is excluded for the same reason as cursor, arriving by a different road: it has no
// session-start event at all. The closest thing is `PreInvocation`, which fires before EVERY model
// round-trip — four to seven times in one measured turn — and each one re-folded the transcript and
// re-emitted `turn_started` for a turn already open (measured: two turn_started, one turn_ended).
// Its first bind is covered by `meta.isNew`, and registry derives the transcript path from the
// conversation id, so nothing here depends on a later announcement carrying it.
// Copilot joins cursor and agy for a third reason: it announces the SAME turn twice. Its
// `userPromptSubmitted` and `sessionStart` hooks both register (measured 2.5s apart, and in that
// order — sessionStart fires AFTER the first prompt), so treating the second as a reset re-folded
// the transcript and emitted a second `turn_started` for one exchange.
const reset = meta.isNew || !!meta.recovered
|| (entry.engine !== 'cursor' && entry.engine !== 'agy' && entry.engine !== 'copilot'
&& meta.hookEvent === 'SessionStart')
// Deliberately NOT gated on `meta.isNew`. `isNew` is false in exactly the case this is meant to catch:
// a session announced once BEFORE its transcript exists and registered again when the file appears —
// the second announcement is the only one that can carry the path, and it reports `isNew=false`
// (measured: `[hooks] 019fff7f SessionStart · engine=codex · isNew=false`, whose whole first turn was
// then folded away as history and never reached web or device).
//
// `statBirthMs >= registeredAt` is what actually separates the two cases. Measured on one machine,
// same claude session, transcript birth relative to each timestamp:
//
// first turn resumed (`claude --continue`)
// registeredAt +18.1s -81.5s ← separates cleanly
// boundAt -0.5s -81.6s ← negative for BOTH; useless as a test
//
// so the birth-vs-`registeredAt` comparison stays, and comparing against `boundAt` instead — the
// obvious-looking alternative, since `boundAt` is when this session was bound — does not work: the
// transcript is created a moment BEFORE the hook binds it.
//
// And only while the file is new (`transcriptIsFirstTurn`): a long session's transcript was born after
// its agent too, and after a daemon restart its next SessionStart replayed the whole history live.
//
// And never for the conversation a resume put back: its transcript existed before the row did,
// whatever its birth says against the row's ORIGINAL `registeredAt`, which a resume keeps. Replaying
// it sent the whole first turn out again as live, and a turn the stopped process had left open was
// announced as running with nothing left to end it (found end to end: stop in the middle of a first
// turn, resume, and the agent read as working for good). A new session started in the agent after
// the resume is not this conversation, and is judged like any other.
const bornAfterAgent = !meta.recovered && !resumedConversation && transcriptIsFirstTurn(
entry,
entry.transcriptPath ? await statBirthMs(entry.transcriptPath) : 0,
{ rebound: !!meta.rebound, now: Date.now() },
)
if (!current() || entry.identityHold) return
const attached = await attachSession(entry, reset, entry.engine === 'cursor', bornAfterAgent)
// The registry mutates rows in place. This completion cannot unbind or re-announce a later
// conversation, nor an agent that Stop has already retired.
if (!current() || entry.identityHold) return
if (!attached) {
// A terminal reads as gone while a stop or a restart ends its engine. A registration that comes in
// then, such as the old engine's own SessionStart arriving late on a loaded machine, is still the
// agent's conversation, and the operation owns what happens to it. Unbound, a stop that had just
// signalled the engine found the conversation changed and gave up, leaving an active agent with no
// engine; and a second restart queued behind a first found no conversation to resume and started a
// fresh one (e2e/races.e2e.ts). The binding stands while one of them runs: a stop retires it, and a
// restart's new engine registers it again.
// The October 6 TUI picker exit/resume incident: a verified engine exited while its startup
// attach was pending. Unbinding here erased the conversation before discovery retired it, so
// Open started a fresh one under the saved title. Keep that verified id for the existing lifecycle.
if (!changing(entry.agentId) && !entry.processIdentity) registry.unbindSession(entry.sessionId)
announceSession(entry)
return
}
}
const lastRepairAttempt = new Map<string, number>()
const repairAttempts = new Map<string, number>()
// Binding is committed before optional interpretation starts. A missing reader must not hold the
// discovery pass (and therefore readiness) or prevent another process from being bound.
const followRegistered = (entry: RegisteredSession, meta: RegisteredMeta): void => {
void handleRegistered(entry, meta).catch(error => console.error(
`[agent] ${sid(entry.agentId)} transcript attachment is unavailable: ${error instanceof Error ? error.message : error}`))
}
const ownTranscript = (engine: 'cursor' | 'grok' | 'agy' | 'copilot', sessionId: string, cwd: string): Promise<string | null> =>
transcriptOf(engine, engine === 'cursor' ? cursorDataDir() : homes[engine], sessionId, cwd)
const bindObservedAgent = async (observed: DiscoveredTerminalAgent): Promise<void> => {
const found = registry.byProcess(observed.engine, observed.processIdentity)
if (!found || changing(found.agentId) || isRecentlyDeleted(found.agentId)) return
let agent: RegisteredSession = found
if (agent.identityHold && agent.sessionId && agent.transcriptPath) {
try {
const previous = agent.sessionId
const retried = registry.revalidateBinding(agent.agentId)
if (!retried) return
agent = retried
if (!agent.sessionId) forgetSession(previous, { force: true, keepAgent: true, agentId: agent.agentId })
else followRegistered(agent, { isNew: false, evicted: null, rebound: null, recovered: true })
announceSession(agent)
} catch (error) {
const reason = error instanceof Error ? error.message : String(error)
if (registry.setIdentityHold(agent.agentId, reason)) announceSession(agent)
return
}
}
const authority = paneReadIdentity(agent)
const current = () => !changing(agent.agentId) && !isRecentlyDeleted(agent.agentId)
&& paneReadIdentity(registry.byProcess(observed.engine, observed.processIdentity)) === authority
const hold = (error: unknown) => {
if (!current()) return
const reason = error instanceof Error ? error.message : String(error)
if (registry.setIdentityHold(agent.agentId, reason)) announceSession(agent)
console.log(`[discovery] ${sid(agent.agentId)} binding held · ${reason}`)
}
const commit = (input: Parameters<typeof registry.register>[0]) => {
try { return registry.register(input) }
catch (error) { hold(error); return null }
}
// Only native reads are contained here. A rejected lookup cannot end the serial
// discovery/readiness pass or bind an unwritten session as if evidence were absent.
const read = async <T>(work: () => Promise<T>): Promise<{ value: T } | null> => {
try { return { value: await work() } }
catch (error) {
hold(error)
return null
}
}
const mayClaim = (id: string): boolean => {
if (isRecentlyDeleted(id)) return false
const owner = registry.bySession(id)
if (!owner || owner.agentId === agent.agentId) return true
const observedStarted = Date.parse(observed.processIdentity.startMarker)
const ownerStarted = Date.parse(owner.processIdentity?.startMarker ?? '')
return !Number.isFinite(ownerStarted) || (Number.isFinite(observedStarted) && observedStarted > ownerStarted)
}
// Copilot can change session WITHOUT changing process: `/resume` inside the CLI opens another one,
// and the pane then shows a conversation the daemon is not streaming. Every other engine here
// starts a new process for that, which is why this path used to stop at `agent.sessionId`.
//
// The switch leaves exactly one trace — the `inuse.<pid>.lock` Copilot takes on the new session
// directory. It writes nothing to the transcript and fires no hook until the next prompt.
if (agent.resumeOnly && agent.launch && agent.launch.state !== 'ready') return
if (agent.sessionId) {
if (observed.engine === 'copilot') {
const process = await read(() => processSessionOf('copilot', homes.copilot, observed.processIdentity.pid))
if (!process) return
const next = process.value
if (!next || next === agent.sessionId || isRecentlyDeleted(next)) return
const located = await read(async () => {
const path = await transcriptOf('copilot', homes.copilot, next)
if (await processSessionOf('copilot', homes.copilot, observed.processIdentity.pid) !== next) {
throw new IdentityReadUnavailable('the process conversation changed during transcript lookup')
}
return path
})
if (!located) return
const transcript = located.value
if (!current() || !mayClaim(next)) return
console.log(`[discovery] ${sid(agent.agentId)} switched copilot session ${sid(agent.sessionId)} → ${sid(next)} (/resume)`)
const rotated = commit({
engine: 'copilot',
sessionId: next,
transcriptPath: transcript ?? undefined,
cwd: observed.cwd,
source: 'copilot-resume',
runtimes: observed.runtimes,
primaryRuntimeKey: observed.primaryRuntimeKey,
processIdentity: observed.processIdentity,
hookEvent: 'CopilotResume',
})
if (rotated?.isNew) followRegistered(rotated.entry, rotated)
return
}
// Claude can also change session WITHOUT any hook firing: a long conversation's transcript
// rolls over to a new file on its own (compaction/a resume chain), and if the turn that follows
// lands on a pooled/"spare" worker process rather than one spawned fresh in the pane, no
// SessionStart/UserPromptSubmit ever reaches us for it — the agent is left bound to a transcript
// that has gone quiet forever while the real conversation continues one file over. Checked on
// the same cadence this reconciler already re-observes every live process, so it costs nothing
// extra to ask. Its session store declares the marker (`continuation`), read in core with the kit.
const store = sessionStoreOf(observed.engine)
if (store?.continuation && agent.transcriptPath) {
const located = await read(() => continuationOf(observed.engine, agent.transcriptPath!))
if (!located) return
const continuation = located.value
if (!continuation || continuation.sessionId === agent.sessionId
|| registry.has(continuation.sessionId) || isRecentlyDeleted(continuation.sessionId)) return
if (!current()) return
console.log(`[discovery] ${sid(agent.agentId)} ${observed.engine} session continued ${sid(agent.sessionId)} → ${sid(continuation.sessionId)}`)
const rotated = commit({
engine: observed.engine,
sessionId: continuation.sessionId,
transcriptPath: continuation.transcriptPath,
cwd: observed.cwd,
source: `${observed.engine}-continuation`,
runtimes: observed.runtimes,
primaryRuntimeKey: observed.primaryRuntimeKey,
processIdentity: observed.processIdentity,
hookEvent: `${store.label}Continuation`,
})
if (rotated?.isNew) followRegistered(rotated.entry, rotated)
return
}
return
}
let sessionId = observed.resumeSessionId
let transcriptPath: string | undefined
let hermesHome: string | undefined
let source = 'terminal-resume'
if (sessionId) {
if (!mayClaim(sessionId)) return
const located = await read(async () => observed.engine === 'cursor' || observed.engine === 'grok' || observed.engine === 'agy' || observed.engine === 'copilot'
? await ownTranscript(observed.engine, sessionId!, observed.cwd) ?? undefined
: observed.engine === 'claude' || observed.engine === 'codex'
? await findResumedTranscript(observed.engine, sessionId!, { codexHome: agent.codexHome ?? undefined }) ?? undefined
: undefined)
if (!located) return
transcriptPath = located.value
// The registry refuses a claude/codex session without its file, so a resume of a transcript this
// machine does not have is not a session — the hook that follows the user's next prompt will say.
if ((observed.engine === 'cursor' || observed.engine === 'grok' || observed.engine === 'claude' || observed.engine === 'codex')
&& !transcriptPath) return
} else {
const attempts = repairAttempts.get(agent.agentId) ?? 0
const lastAttempt = lastRepairAttempt.get(agent.agentId) ?? 0
if (attempts >= REPAIR_EAGER_ATTEMPTS && Date.now() - lastAttempt < REPAIR_RETRY_MS) return
lastRepairAttempt.set(agent.agentId, Date.now())
repairAttempts.set(agent.agentId, attempts + 1)
const startedAtMs = Date.parse(observed.processIdentity.startMarker)
if (!Number.isFinite(startedAtMs)) return
// agy cannot be found by directory — its repair reads the presence lock the process holds open.
//
const located = await read(() => findLiveSession(observed.engine, observed.cwd, startedAtMs, {
bornOnly: true,
...(agent.forkedFrom?.sessionId ? { excludedSessionId: agent.forkedFrom.sessionId } : {}),
pid: observed.processIdentity.pid,
expectedProcess: observed.processIdentity,
codexHome: agent.codexHome ?? undefined,
hermesHome: agent.hermesHome ?? undefined,
}))
if (!located) return
const found = located.value
if (!found || registry.has(found.sessionId) || isRecentlyDeleted(found.sessionId)) return
sessionId = found.sessionId
transcriptPath = found.transcriptPath
// Which Hermes home the repair found it in, so the row starts life reading the right store
// rather than looking it up again on its first poll.
hermesHome = found.hermesHome
source = 'process-repair'
}
if (!current() || !mayClaim(sessionId)) return
const previousOwner = registry.bySession(sessionId)
const result = commit({
engine: observed.engine,
sessionId,
transcriptPath,
...(hermesHome ? { hermesHome } : {}),
cwd: observed.cwd,
source,
runtimes: observed.runtimes,
primaryRuntimeKey: observed.primaryRuntimeKey,
processIdentity: observed.processIdentity,
hookEvent: source === 'terminal-resume' ? 'TerminalResumeDiscovery' : 'ProcessRepair',
})
if (!result || !result.isNew) return
if (previousOwner && previousOwner.agentId !== result.entry.agentId) {
input.forget(previousOwner.agentId)
deviceInput.forget(previousOwner.agentId)
announceSession(previousOwner)
}
lastRepairAttempt.delete(agent.agentId)
repairAttempts.delete(agent.agentId)
followRegistered(result.entry, result)
console.log(`[discovery] bound ${observed.engine} session ${sid(result.entry.sessionId)} via ${observed.primaryRuntimeKey}`)
}
return {
pendingForkInherit, handleRegistered, bindObservedAgent,
/** Set by cli.ts once the lifecycle operations exist: they are made long after the binding. */
whileChanging: (test: (agentId: string) => boolean): void => { changing = test },
}
}