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
/**
* Stop an agent's live engine process and relaunch it in the SAME tmux pane, preserving the pane/agent
* identity and (best-effort) resuming the same engine conversation.
*
* Factored out of cli.ts's `onRestartAgent` the same way deleteAgentFallback.ts factors out delete's
* kill sequence: a small, dependency-injected core so the kill → respawn → verify → fallback ordering
* can be exercised without the daemon's registry, tmux, and reconciler wiring. cli.ts owns everything
* registry-shaped around a call to this function — resolving the session, `agentReconciler.holdRoute` /
* `releaseRoute`, `registry.updateProcessIdentity`, `clearPaneRemainOnExit`, and `announceSession`.
*/
import type { AgentEngine } from '../engines/types.js'
import type { RegisteredSession, ProcessIdentity } from './registry.js'
import type { TerminateOutcome } from './deleteAgentFallback.js'
import { permissionModeApproves } from './engineLaunch.js'
/**
* Whether the relaunch approves on its own — from the ROW first, and the live process only for a row
* that never learned.
*
* The row is what create wrote and what discovery keeps in step with the live argv, so it is the
* answer even once the process is dead or `ps` has failed. Reading the live argv instead was the
* original design (there was nothing else to read then), and it is what lost the flag: a `ps` that
* timed out read as "no", and an agent typed into a terminal with the skip-everything flag came back
* in the auto mode. The mode outranks the boolean — Plan is not a yes — and `buildArgv` reapplies the
* mode itself; this only settles the yes/no the engines without a mode table launch with.
*/
export async function bypassPermissionFor(
session: Pick<RegisteredSession, 'permissionMode' | 'bypassPermission' | 'swarmSkill'>,
probeLive: () => Promise<boolean>,
): Promise<boolean> {
if (session.permissionMode) return permissionModeApproves(session.permissionMode)
if (session.bypassPermission !== undefined) return session.bypassPermission
// A Swarm agent's mode is its person's choice, or none (task #4215). One Harness started in full mode, cleared since,
// still runs with that flag until it relaunches: read back, it would come back in Auto, which nobody chose.
if (session.swarmSkill) return false
return probeLive()
}
export type RestartOutcome =
| { ok: true; processIdentity: ProcessIdentity; resumed: boolean }
| { ok: false; detail: string; error?: 'ENGINE_LAUNCH_REFUSED' }
export type RestartAgentReply =
| { ok: true; session: RegisteredSession; resumed: boolean }
| { ok: false; error: string; detail?: string }
/** One process replacement per agent, even across clients and different receipt
* IDs. Stop cancels the work before its next process-changing step. */
export class AgentRestartCoordinator {
private readonly revisions = new Map<string, number>()
private sequence = 0
revision(agentId: string): number {
let revision = this.revisions.get(agentId)
if (revision === undefined) { revision = ++this.sequence; this.revisions.set(agentId, revision) }
return revision
}
forget(agentId: string): void { this.revisions.delete(agentId) }
operation(agentId: string): string | undefined { return this.jobs.get(agentId)?.operation }
private readonly jobs = new Map<string, { operation: string; variant: string; cancelled: boolean; result: Promise<RestartAgentReply> }>()
/** [variant] tells apart two asks of the same operation that must not share one launch: the launch words a restart
* was given. Only the same variant joins a running one; any other is refused, never answered by a launch that did
* not carry its words. */
run(agentId: string, restart: (current: () => boolean) => Promise<RestartAgentReply>, operation = 'restart', variant = ''): Promise<RestartAgentReply> {
const existing = this.jobs.get(agentId)
if (existing) return existing.operation === operation && existing.variant === variant ? existing.result
: Promise.resolve({ ok: false, error: 'AGENT_BUSY', detail: 'Another lifecycle operation is changing this harness.' })
if (this.revisions.has(agentId)) this.revisions.set(agentId, ++this.sequence)
const job = { operation, variant, cancelled: false, result: null! as Promise<RestartAgentReply> }
const current = () => !job.cancelled && this.jobs.get(agentId) === job
job.result = Promise.resolve().then(async () => {
if (!current()) return { ok: false, error: 'AGENT_CHANGED' } as const
const result = await restart(current)
return current() ? result : { ok: false, error: 'AGENT_CHANGED' } as const
}).finally(() => {
if (this.jobs.get(agentId) === job) this.jobs.delete(agentId)
})
this.jobs.set(agentId, job)
return job.result
}
busy(agentId: string): boolean { return this.jobs.has(agentId) }
cancel(agentId: string): void {
if (this.revisions.has(agentId)) this.revisions.set(agentId, ++this.sequence)
const job = this.jobs.get(agentId)
if (job) job.cancelled = true
}
}
/** How the relaunch reopens the conversation: resumed, continued in a fork of it, or neither (a fresh one). */
export interface RelaunchArgvOptions { bypassPermission: boolean; resumeSessionId?: string; forkSessionId?: string }
export interface RestartAgentDeps {
/** False after Stop, replacement, or removal. Checked across every await. */
isCurrent?: () => boolean
/** Re-arm `remain-on-exit` before anything is killed — see `tmuxBackend.ts`'s `holdOpen` (the pty host's
* `holdOpen` is the same keep). Without this, tmux tears the pane (and, being its only pane, the whole
* session) down the instant the old process exits. */
holdOpen: () => Promise<{ ok: boolean; reason?: string }>
/** Validate + SIGTERM/SIGKILL the saved process. Same contract as `terminateDeletedAgent`. */
terminate: (checkAfterMs?: number) => Promise<TerminateOutcome>
/** `tmux respawn-pane -k` (or the pty host's `respawn`, the same in place) with a fully-built argv. */
respawn: (argv: string[]) => Promise<{ ok: boolean; reason?: string }>
/** Why `respawn` would be refused here (a tmux too old for what the relaunch needs), asked before
* anything is stopped; null when it would try. Left out, never refused. */
respawnRefusal?: () => Promise<string | null>
/** Poll the pane for a recognizable engine process, up to an internal budget. Null on timeout. */
waitForProcess: () => Promise<ProcessIdentity | null>
/** Prepare persisted history only once the old writer is confirmed stopped. A failure must
* preserve the conversation, not enter the fresh-session fallback. */
prepareResume?: () => void | Promise<void>
/**
* Claude only: stop a `claude --bg` job still holding the session this is about to `--resume`
* (`lib/claudeBackgroundJob.ts`). Run once, after history preparation and before the resume
* argv is built, so a job that held the jobs store's lock is gone before Claude Code is asked to
* reopen it. A failure here must not block the restart it exists to unblock, so it is awaited for
* ordering only, never allowed to fail the restart; implementations swallow their own errors.
*/
stopConflictingJob?: () => Promise<void>
/** A [continueInFork] move, once the old writer is stopped: makes the fork ready for its destination and returns its
* id, which the relaunch then resumes. A failure falls back to the plain fork: the conversation still continues. */
prepareFork?: () => Promise<string>
buildArgv: (opts: RelaunchArgvOptions) => string[]
/** Why the relaunch [buildArgv] would build is refused on this platform (a Windows batch-file engine whose arguments
* cmd.exe would read, lib/windows/launch.ts), asked before anything is stopped; null when it is not. */
launchRefusal?: (opts: RelaunchArgvOptions) => string | null
log: (message: string) => void
/** Keeps the conversation the fresh fallback left as a stopped harness (keepAbandonedConversation.ts). */
keepAbandoned?: () => void
}
/** Outcomes that mean the old process is confirmed gone — safe to respawn over the pane (or, for a move, to start
* the engine in another one: hostMove/moveAgent.ts). `not-ours` and `failed` are NOT here on purpose: never
* respawn over a target the kill sequence could not confirm. */
export const KILL_CONFIRMED: ReadonlySet<TerminateOutcome> = new Set(['gone', 'terminated', 'killed'])
/**
* [session.continueInFork]: the conversation goes on in a fork of it (`codex fork <id>`) instead of being resumed — the
* relaunch moves it to a provider it cannot be resumed on (`EngineLaunch.providerBoundConversations`). The fork is the
* whole conversation, so nothing is kept for the one it came from; the agent follows the fork's id when it binds
* (bind.ts, as a rebound).
*/
export async function restartAgent(
session: { engine: AgentEngine; sessionId: string; resumeOnly?: true; continueInFork?: true },
bypassPermission: boolean,
deps: RestartAgentDeps,
): Promise<RestartOutcome> {
const changed = { ok: false, detail: 'the harness changed or stopped during restart' } as const
const current = () => deps.isCurrent?.() !== false
if (!current()) return changed
// Before anything is stopped: refused after the kill, the agent was left with no engine at all.
const refused = await deps.respawnRefusal?.()
if (refused) return { ok: false, detail: `${refused} Nothing was stopped.` }
const reopen = (id: string | undefined) => !id ? {} : session.continueInFork ? { forkSessionId: id } : { resumeSessionId: id }
// The resume relaunch has every argument the fresh fallback has, and more: refused, neither would start.
const launchRefused = deps.launchRefusal?.({ bypassPermission, ...reopen(session.sessionId) })
if (launchRefused) return { ok: false, error: 'ENGINE_LAUNCH_REFUSED', detail: `${launchRefused} Nothing was stopped.` }
if (!current()) return changed
const armed = await deps.holdOpen()
if (!current()) return changed
if (!armed.ok) {
return { ok: false, detail: armed.reason ?? 'could not re-arm the pane before restart' }
}
let outcome: TerminateOutcome
try { outcome = await deps.terminate() }
catch (error) {
return { ok: false, detail: `could not stop the running ${session.engine} session: ${error instanceof Error ? error.message : error}` }
}
if (!current()) return changed
if (!KILL_CONFIRMED.has(outcome)) {
return { ok: false, detail: `could not confirm the running ${session.engine} process was stopped (${outcome})` }
}
const resumeSessionId = session.sessionId || undefined
if (resumeSessionId && deps.prepareResume) {
try { await deps.prepareResume() } catch (error) {
return { ok: false, detail: `could not prepare ${session.engine} session for resume: ${error instanceof Error ? error.message : error}` }
}
}
if (!current()) return changed
if (resumeSessionId && deps.stopConflictingJob) await deps.stopConflictingJob()
if (!current()) return changed
let preparedFork: string | null = null
if (resumeSessionId && session.continueInFork && deps.prepareFork) {
try { preparedFork = await deps.prepareFork() } catch (error) {
deps.log(`[restart] ${session.engine} could not prepare the move, continuing in a plain fork: ${error instanceof Error ? error.message : error}`)
}
if (!current()) return changed
}
const spawnAndWait = async (withResume: boolean): Promise<ProcessIdentity | null> => {
if (!current()) return null
const argv = deps.buildArgv({ bypassPermission, ...(!withResume ? {} : preparedFork ? { resumeSessionId: preparedFork } : reopen(resumeSessionId)) })
const spawned = await deps.respawn(argv)
if (!current()) return null
if (!spawned.ok) {
deps.log(`[restart] ${session.engine} respawn-pane failed: ${spawned.reason ?? 'unknown reason'}`)
return null
}
return deps.waitForProcess()
}
// Attempt a resume relaunch whenever we have a session id to resume, for every engine — an
// unconfirmed/wrong flag is not fatal because of the fallback below. Engines with no known launch
// resume flag never spawn a resume argv in the first place (buildArgv's `resumeSessionId` is a no-op
// when LAUNCH_RESUME_FLAG has no entry for the engine), so `resumed` still degrades correctly.
let resumed = !!resumeSessionId
let identity = await spawnAndWait(resumed)
if (!current()) return changed
if (!identity && resumed && !session.resumeOnly) {
// Safe degradation: a working agent with a FRESH session under the same agentId/pane beats a dead
// pane. Retry once with no resume attempt before giving up entirely.
deps.log(`[restart] ${session.engine} did not come back up resuming its session — retrying fresh`)
resumed = false
identity = await spawnAndWait(false)
}
if (!current()) return changed
if (!identity) {
return { ok: false, detail: `${session.engine} did not come back up after restart` }
}
// The agent works on in a new conversation; the one it was in, which the engine could not reopen, is
// kept as a stopped harness to read and to resume once it can (round 24). A /clear keeps nothing.
if (resumeSessionId && !resumed) deps.keepAbandoned?.()
return { ok: true, processIdentity: identity, resumed }
}