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
/**
* An engine that is no longer running, retained rather than lost.
*
* Reached from every place the daemon learns an engine process ended without anybody asking it to —
* the reconciler finding its pane empty, a restore or a create watcher meeting a pane whose engine
* exited, a resume that never came up — and it always does the same three things: save the
* conversation so it can be opened again, END THE IDENTITY THAT WAS RUNNING IT, and, when the tmux
* pane outlived the engine, keep that shell alive under an identity of its own.
*
* Extracted from cli.ts for the same reason as stopAgentService and restoreAgents: the ORDER of those
* steps is the part worth testing — the archive must exist before a client is told to look for it,
* and the ending must reach the client before the frame that is behind a filesystem await.
*/
import type { RegisteredSession } from './registry.js'
export interface RetainExitedSessionDeps {
stoppedAgents: {
save(session: RegisteredSession): void
get(agentId: string): RegisteredSession | null
}
registry: {
releaseEngine(agentId: string, separateShell?: boolean): RegisteredSession | null
removeAgent(agentId: string): boolean
}
/** Web and desktop: `agent_deleted` closes this identity's views, `agent_synced` carries frames. */
send(frame: { type: string; payload: Record<string, unknown> }): void
/** The archive, announced to every client that lists saved harnesses (and removed from the dial). */
publishStoppedAgent(saved: RegisteredSession): Promise<void>
announceSession(session: RegisteredSession): void
invalidateTerminalControl(agentId: string): void
forgetInput(agentId: string): void
forgetRelaunch?(sessionId: string): void
detachDsh(agentId: string): void
syncRecapPool(): void
warn(message: string, error: unknown): void
}
export function createRetainExitedSession(deps: RetainExitedSessionDeps) {
/** Retain the conversation's identity; a surviving shell gets its own live identity. */
return (entry: RegisteredSession, paneAlive: boolean): void => {
deps.stoppedAgents.save(entry)
const saved = deps.stoppedAgents.get(entry.agentId)!
deps.invalidateTerminalControl(entry.agentId)
deps.forgetInput(entry.agentId)
deps.forgetRelaunch?.(entry.sessionId)
deps.detachDsh(entry.agentId)
// END THE VIEWS OF THE AGENT THAT JUST ENDED: moved to the shell that keeps its pane, or closed,
// the way a stop closes them, when there is none.
//
// This identity has no runtime left: a surviving shell continues under a new one, and the
// conversation is now an archive to be opened. The `agent_synced` below says so, but a client
// treats that as a snapshot rather than a deletion — it cannot tell a real ending from the brief
// gap a process replacement leaves — so a tile left on this id sat on "terminal unavailable" with
// nothing to press, the shell it had been watching alive and typeable one identity away (#262).
// `retained` means here what it means in `forgetSession`: the row is archived, not gone, so the
// client re-reads its inventory and finds it among the saved harnesses. Sent BEFORE the archive
// frame, which is behind an await, so the view closes at once rather than a filesystem turn later.
//
// An engine whose pane outlived it names the shell that keeps that pane as `successor`, so a
// window moves its tiles there instead of closing them. The pane says so ("This pane is a shell
// now — run codex again, or stop the pane"), and the person decides: run the engine again, run
// anything else, or close it. Closing the views of a later exit took the pane away 10–15 s
// after a Ctrl-C that only meant to stop Codex, the shell still running out of sight (#600).
// A failed start keeps its last screen, the only place that says why it stopped, the same way
// (fresh macOS VM, 2026-10-08). A pane that died with its engine has no successor, and its
// views close as above. The shell is released first (synchronous), so the frame still goes out
// before anything awaited.
const terminal = paneAlive ? deps.registry.releaseEngine(entry.agentId, true) : null
deps.send({ type: 'agent_deleted', payload: { agentId: entry.agentId, retained: true, ...(terminal ? { successor: terminal.agentId } : {}) } })
if (!paneAlive) deps.registry.removeAgent(entry.agentId)
deps.syncRecapPool()
void deps.publishStoppedAgent(saved).catch(error => deps.warn('[resume] could not announce saved harness', error))
if (terminal) deps.announceSession(terminal)
}
}