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 { terminalRouteKey } from './terminalRuntime.js'
import { isTerminalEngine } from '../engines/types.js'
import type { RegisteredSession, ProcessIdentity } from './registry.js'
import { resumesConversation } from './resumeCapability.js'
import type { RestartAgentReply } from './restartAgent.js'
import type { RuntimeCheck } from './paneEngineProcess.js'
export interface ResumeStoppedDeps {
live: () => RegisteredSession | undefined
saved: () => RegisteredSession | null
current: () => boolean
checkLive: (session: RegisteredSession) => Promise<RuntimeCheck>
canLaunch: (saved: RegisteredSession) => Promise<boolean>
/** Only called after the engine is confirmed gone; never destroys the surviving shell. */
retain: (session: RegisteredSession) => Promise<void>
waitForReady: (session: RegisteredSession) => Promise<RestartAgentReply>
launch: (saved: RegisteredSession, resumeSessionId: string | undefined) => Promise<RestartAgentReply>
}
/** The longest a resume waits for its replacement process before giving up — and so the longest one
* can legitimately hold the reservation `stoppedAgents.beginResume` takes for it. */
export const RESUME_READINESS_BUDGET_MS = 10 * 60_000
export const resumeChanged = { ok: false, error: 'AGENT_CHANGED', detail: 'The harness changed while opening. Select it again.' } as const
export const resumeUnconfirmed = { ok: false, error: 'RESUME_UNCONFIRMED', detail: 'The saved conversation has not been confirmed yet. Check the terminal, then select the harness again to check its status.' } as const
/** Enter means attach or exact resume. A route, shell or allocated pane alone is not success. */
const liveIdentity = (row: RegisteredSession | undefined) => row ? JSON.stringify([
row.agentId, row.engine, row.sessionId, row.registeredAt, row.codexHome,
row.processIdentity?.pid, row.processIdentity?.startMarker, row.processIdentity?.executable,
row.runtimes?.map(terminalRouteKey).sort(), row.tmuxPane,
]) : null
export async function resumeStoppedAgent(deps: ResumeStoppedDeps): Promise<RestartAgentReply> {
if (!deps.current()) return resumeChanged
const existing = deps.live()
let saved = deps.saved()
if (existing) {
// Compatibility with an archive written before surviving shells got a new identity.
if (isTerminalEngine(existing.engine) && saved && !isTerminalEngine(saved.engine)) {
await deps.retain(existing)
} else if (existing.resumeOnly && existing.launch?.state === 'starting') {
return deps.waitForReady(existing)
} else {
// Hooks replace registry objects while retaining the exact same process.
// Capture values before awaiting; object identity both rejects harmless
// hooks and misses an in-place PID/session replacement.
const identity = liveIdentity(existing)
const runtime = await deps.checkLive(existing)
const latest = deps.live()
if (!deps.current() || liveIdentity(latest) !== identity) return resumeChanged
if (runtime.state === 'unknown') return resumeUnconfirmed
if (runtime.state === 'alive') {
if (latest!.resumeOnly && latest!.launch?.state === 'failed') {
// Never confirmed is not the same as disproved: the engine is running, so ask for
// confirmation again rather than repeating the old verdict.
if (latest!.launch.error === 'RESUME_UNCONFIRMED') return deps.waitForReady(latest!)
// Any other verdict is reported as ITSELF. Relabelling them all "not confirmed yet" told
// somebody whose resume had reopened the wrong conversation to go and check the terminal,
// and hid the one fact that would have explained what they were looking at.
return { ok: false, error: latest!.launch.error, detail: latest!.launch.detail }
}
return { ok: true, session: latest!, resumed: true }
}
saved = { ...latest! }
await deps.retain(latest!)
}
}
if (!deps.current()) return resumeChanged
// An app's list can still show a deleted harness, or one whose conversation another harness took over (4 on Oct 26);
// search finds the conversation wherever it is now.
if (!saved) {
return { ok: false, error: 'AGENT_NOT_FOUND', detail: 'This harness is no longer on this machine: it was deleted, or another '
+ 'harness now has its conversation. Search for the conversation to open it where it is now.' }
}
// No engine is refused here any more. An engine with a resume argv and a recorded id comes back
// where it left off; one with neither still comes back — same pane, same folder, same name — as a
// new conversation, which `resumed: false` and the client's wording say out loud. Refusing the
// pause instead was the stricter rule: `agent_restart` has relaunched every engine this way for as
// long as it has existed (`restartAgent.ts`).
if (!await deps.canLaunch(saved)) {
return { ok: false, error: 'AGENT_BUSY', detail: 'The previous process is still running or could not be checked. Wait for it to stop, then retry.' }
}
if (!deps.current()) return resumeChanged
// Discovery won the race. Recheck it through the same verified attach path.
if (deps.live()) return resumeStoppedAgent(deps)
return deps.launch(saved, resumesConversation(saved.engine, saved.sessionId) ? saved.sessionId : undefined)
}
export interface ResumeReadinessDeps {
current: () => boolean
session: () => RegisteredSession | undefined
process: () => Promise<ProcessIdentity | null>
/** `'gone'`: tmux has no such pane; `'unknown'`: it could not be asked (`tmuxPaneState`). */
pane: () => Promise<{ dead: boolean; engineExit?: number | null } | 'gone' | 'unknown'>
sleep: (ms: number) => Promise<void>
now?: () => number
budgetMs?: number
}
/**
* Wait for the replacement process to prove it came back.
*
* The proof is the engine process alive in this row's own pane — the bar `agent_restart` has cleared
* for every engine for as long as it has existed. Claude and Codex were held to their `SessionStart`
* hook instead; see the note at the check itself for why that is no longer a precondition.
*
* The budget is only reached when NO engine process was ever seen: the pane is up, and nothing this
* row would recognise is running in it. That is the one state worth reporting as unconfirmed.
*/
export async function waitForResumedAgent(saved: RegisteredSession, deps: ResumeReadinessDeps): Promise<RestartAgentReply> {
const now = deps.now ?? Date.now
const until = now() + (deps.budgetMs ?? RESUME_READINESS_BUDGET_MS)
while (now() < until) {
if (!deps.current()) return resumeChanged
const process = await deps.process()
const pane = await deps.pane()
if (!deps.current()) return resumeChanged
const row = deps.session()
if (!row) return { ok: false, error: 'RESUME_FAILED', detail: 'The resume runtime disappeared. The saved conversation is still retained.' }
if (row.sessionId !== saved.sessionId || row.engine !== saved.engine) return resumeChanged
if (row.launch?.state === 'failed') return { ok: false, error: row.launch.error, detail: row.launch.detail }
// A pane tmux could not read is asked again: a call that timed out while the daemon's event loop
// was held said the harness had exited, and a resume that was coming up was failed for it.
if (pane === 'unknown') {
await deps.sleep(250)
continue
}
if (pane === 'gone' || pane.dead || pane.engineExit != null) {
return { ok: false, error: 'RESUME_FAILED', detail: 'The harness exited before confirming the saved conversation. Its terminal output and conversation have been retained.' }
}
// ONE proof, for every engine: this row's own engine process, running in this row's own pane,
// which the checks above have just confirmed is alive. `deps.process()` resolves the engine
// binary beneath THAT pane, so it cannot be answered by somebody else's shell.
//
// Claude and Codex used to be held to a stricter one — their `SessionStart` hook, carrying the
// new pid, proving they had reopened this very conversation. It is better evidence, and it is
// evidence that does not reliably come to a RESUME, which is a narrower thing than "has a
// startup hook": opencode's plugin posts on `session.created`, which `--session <id>` never
// emits; a claude hook can announce a transcript path that never appears and be dropped
// (openharness#189); and measured on machine-remote-1, both resume-only codex rows carried
// `lastHookAt: 0` while every fresh launch beside them had hooked. Waiting for it turned a
// working harness into ten minutes of "Starting" and then a permanent "Start failed" over a pane
// the person could type in — with `active` cleared and the desk refusing to open it, the cost of
// the strict rule was never the resume, it was the harness. A resume that reopened the WRONG
// conversation is still caught, by `registry.register`'s mismatch guard, when the hook arrives.
if (process) return { ok: true, session: { ...row, processIdentity: process }, resumed: resumesConversation(saved.engine, saved.sessionId) }
await deps.sleep(250)
}
return resumeUnconfirmed
}