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
/**
* Moving a RUNNING agent onto a grid, or back to its engine's own login (`agent_retarget`).
*
* A process's environment is fixed at `execve`, so there is no way to re-point a live engine short of
* replacing the process. `respawn-pane -k` does exactly that and keeps the pane, which keeps the pane
* id, which keeps the agent's identity, its tile and its scrollback — the user sees their agent
* restart, not a new agent appear. `--resume` brings the conversation back.
*
* Every check refuses instead of doing something partial, because a half-applied move is
* indistinguishable from a working one until the bill arrives.
*
* Moved verbatim out of `runForeground` (the core boundary, step 11: docs/design/2026-10-03-harnessd.md).
*/
import type { BackendSocket } from '../../backendSocket.js'
import * as opencodeLaunch from '../../engines/launchControl.js'
import { binaryOnPath } from '../../lib/binaryOnPath.js'
import { builtinSqlite } from '../../lib/sqliteBuiltin.js'
import { probeGatewayRuntime } from '../../lib/gatewayRuntime.js'
import { describeGridLaunch, gridEnvVarNames } from '../../lib/gridLaunchWire.js'
import { validateLaunchOverrides, type LaunchOverridesDeps, type LaunchSource } from '../../lib/launchOverrides.js'
import { sid } from '../../lib/log.js'
import type { registry, RegisteredSession } from '../../lib/registry.js'
import { bypassPermissionFor, restartAgent } from '../../lib/restartAgent.js'
import type { RuntimeProfileManager } from '../../lib/runtimeProfile.js'
import { parseRuntimeProfile } from '../../lib/runtimeProfileWire.js'
import type { TerminalAgentReconciler } from '../../lib/terminalAgentReconciler.js'
import { canRestart, restartTargetOf } from '../../lib/terminalBackend.js'
import { launchContract } from '../../engines/launches.js'
import { moveCodexConversation } from '../../engines/codex/providerMove.js'
import { engineBin } from '../../lib/engineBin.js'
import { sessionCodexHome } from '../../lib/engineHomes.js'
import { windowsEngineArgv } from '../../lib/windows/launch.js'
import type { TerminalBackendCoordinator } from '../../lib/terminalBackendCoordinator.js'
import { terminalRouteKey } from '../../lib/terminalRuntime.js'
import { workspaceMissing } from '../../lib/workspaceCheck.js'
import type { createLaunchHelpers } from './launch.js'
import type { PaneSwap } from './swap.js'
import { createLaunchAuthority } from './launchAuthority.js'
import type { AdoptSwarmSkill } from '../api.js'
import { nativeOpencodeStore } from '../../engines/kit/nativeLocations.js'
import { GUEST_HARNESS_REFUSAL } from '../guestPolicy.js'
type LaunchHelpers = ReturnType<typeof createLaunchHelpers>
type RetargetAgent = NonNullable<BackendSocket['onRetargetAgent']>
export interface RetargetDeps {
/** What it answers when no backend here can respawn a pane: the configured backend's own code (terminalBackend.ts
* `noBackendCode`); `TMUX_UNAVAILABLE`, as before, by default. */
noBackendCode?: string
/** Whether the engine's turn state says this session is mid-turn (normalizers.sessionTurnOpen). */
sessionTurnOpen: (sessionId: string) => boolean
/** Whether a purge holds this agent (PurgeAgentService.busy). */
purgeBusy: (agentId: string) => boolean | undefined
/** The backends, and each runtime's own: a row is retargeted in the pane it is in (`restartTargetOf`). */
terminals: Pick<TerminalBackendCoordinator, 'backendFor' | 'instances'>
registry: typeof registry
runtimeProfiles: Pick<RuntimeProfileManager, 'selectedModel'>
launchOverridesDeps: LaunchOverridesDeps
acquireTerminalControl: (id: string, opts?: { forAnswer?: boolean }) => (() => void) | null
relaunchOverrides: LaunchHelpers['relaunchOverrides']
downgradedPermission: LaunchHelpers['downgradedPermission']
agentReconciler: Pick<TerminalAgentReconciler, 'holdRoute'>
restartJobs: PaneSwap['restartJobs']
paneSwapDeps: PaneSwap['paneSwapDeps']
liveBypassPermission: PaneSwap['liveBypassPermission']
announceSession: (session: RegisteredSession) => void
refreshGridAssignment: (session: RegisteredSession) => void
/** OpenCode's store, whose rows a resumed session takes its model from. */
opencodeDb: string
/** An older Swarm session's role, read before it is relaunched (superTabs/inCore/adoption.ts). Absent while the Swarm is off. */
adoptSwarmSkill?: AdoptSwarmSkill
}
export function createAgentRetargeter({
sessionTurnOpen, purgeBusy, terminals, registry, runtimeProfiles, launchOverridesDeps, acquireTerminalControl,
relaunchOverrides, downgradedPermission, agentReconciler, restartJobs, paneSwapDeps, liveBypassPermission,
announceSession, refreshGridAssignment, opencodeDb, noBackendCode = 'TMUX_UNAVAILABLE', adoptSwarmSkill,
}: RetargetDeps) {
const authority = createLaunchAuthority({ byAgent: id => registry.byAgent(id),
revision: id => restartJobs.revision(id), cancelled: () => false })
const retargetAgent: RetargetAgent = async ({ agentId, grid, fresh }) => {
if (purgeBusy(agentId)) return { ok: false, error: 'AGENT_BUSY' }
// No backend here can respawn a pane (tmux missing, the pty host down): the configured backend's code.
if (!terminals.instances().some(canRestart)) return { ok: false, error: noBackendCode }
const live = registry.resolve(agentId)
if (!live) return { ok: false, error: 'AGENT_NOT_FOUND' }
if (live.guest) return GUEST_HARNESS_REFUSAL
// Registry observations can update a row in place while a service or pane
// read waits. The request keeps its original conversation and exact process.
const session = structuredClone(live)
grid = grid && structuredClone(grid)
const captureAuthority = () => {
const owns = authority(session.agentId)
return () => !!registry.byAgent(session.agentId) && owns()
}
let current = captureAuthority()
let nativeEffect: 'none' | 'uncertain' | 'applied' = 'none'
let replacementStarted = false
const failed = (error: string, detail: string) => ({ ok: false as const, error, detail: [
nativeEffect === 'applied' ? 'The native model change was applied.'
: nativeEffect === 'uncertain' ? 'The native model change may already have applied.' : '',
replacementStarted ? 'The replacement process started, but retarget did not complete.' : '',
detail,
].filter(Boolean).join(' ') })
const changed = () => failed('AGENT_CHANGED', 'The harness changed or stopped during retarget.')
// Only a pane on a backend that respawns in place can be retargeted: its tmux pane first, as before. Saying
// so is better than a generic failure the user cannot act on.
const place = restartTargetOf(session, (runtime) => terminals.backendFor(runtime))
if (!place) return { ok: false, error: 'RETARGET_UNSUPPORTED_BACKEND', detail: `${session.engine} is not running in a tmux pane` }
const { backend, runtime: pane } = place
// The swap kills a process it has validated by pid + start marker. Without one there is nothing to
// validate, and respawning over a pane whose occupant we cannot identify is how you replace
// something that was not ours.
if (!session.processIdentity) return { ok: false, error: 'NO_ACTIVE_PROCESS' }
// An older Swarm session switches with its role, or not at all while the role cannot be read: a switch relaunched an old
// Buddy with no saved role as an ordinary session, without its guard (security review 1 of #2255). Nothing has touched
// the pane yet, so a refusal leaves the running engine as it is.
const looked = await adoptSwarmSkill?.lookup?.(session, current)
if (looked !== undefined) {
// The lookup answers null once this switch no longer owns the row.
if (looked === null) return changed()
if (looked === 'unavailable') return { ok: false, error: 'SWARM_ROLE_UNAVAILABLE',
detail: 'This agent\'s Swarm role could not be confirmed, so its model was not switched. Try again once the Swarm can be reached.' }
// Recording the role changes the row this switch owns: it owns the recorded one, taken in the same step.
looked.commit()
if (looked.row.swarmSkill) session.swarmSkill = looked.row.swarmSkill
current = captureAuthority()
}
// Leaving for a grid is the LAST moment this agent's own model is observable: once the pane is on
// the grid, the engine reports the grid's model and the previous choice exists nowhere. So it is
// read now and kept, and a later move back returns the person to it rather than to whatever
// default the engine would otherwise fall to. Read from the live engine, not from the row.
//
// Coming back reads what was kept. Not cleared on the way home: an agent bounced between a grid
// and its own login should land on the same model every time, not only the first.
// ⚠️ `selectedModel` answers an ENCODED runtime-profile id (`runtime-v1:…`), not a model name —
// handing that to an engine would point it at a model that does not exist. Decode it and take
// the model. For claude the decoded value is already the vendor's alias (`opus`), which is what
// ANTHROPIC_MODEL wants. Null when the daemon has not observed this pane's model yet, which is a
// real answer: there is then nothing to come back to and the engine decides, as it did before.
// ⚠️ The profile's OWN engine has to match, not just the session it was read under. A model is
// only meaningful to the engine that named it — `opencode/big-pickle` handed back as
// ANTHROPIC_MODEL is not a Claude model, and Claude Code says so ("It may not exist or you may
// not have access to it") on a pane the user never chose it for. The keying bug that let one
// agent read another's model is fixed at its source in RuntimeProfileManager; this is the second
// lock, because the cost of being wrong here is a pane that answers on nothing.
const profile = parseRuntimeProfile(runtimeProfiles.selectedModel(session))
const observed = profile && profile.engine === session.engine ? profile.model : null
const remembered = grid
// Two guards, and both come from watching this go wrong:
//
// * Capture only when the agent is on its OWN LOGIN. Moving grid→grid must not overwrite the
// memory with the first grid's model — the subscription choice has not changed, and the
// whole point is to still have it on the way home.
//
// * Never remember the model being moved TO. An engine can keep REPORTING a grid model after
// it has come back (Claude Code restores it from its own session file and says so), so a
// later move to that same grid would otherwise capture the grid's model as the
// "subscription" one and hand it straight back — teaching the bug to itself.
? (!session.grid && observed !== grid.model ? observed : (session.subscriptionModel ?? null))
: (session.subscriptionModel ?? null)
// Which conversation the relaunch reopens. `fresh` (a grid's or an API's: the conversation is too long for the
// model's window) starts a new one, and the one left on the own login is remembered, as the model is above. The
// way home reopens that one rather than the grid's, so the person is back where they left off. Grid to grid,
// the remembered one stays: it is still the own login's. '' starts a new conversation (restartAgent).
const onGrid = !!(session.grid || session.gridLaunch)
const startsFresh = !!grid && fresh === true
const homeConversation = !grid && onGrid ? session.subscriptionSessionId ?? null : null
const reopens = startsFresh ? '' : homeConversation ?? session.sessionId
// What this machine cannot do at all is said first, before the pane is even looked at.
const target: LaunchSource = {
gridLaunch: grid,
codexHome: session.codexHome,
// Home, the model it was launched with too: it outranks the remembered one (lib/launchOverrides.ts, task #3449).
...(grid ? {} : { subscriptionModel: remembered, ...(session.launchModel ? { launchModel: session.launchModel } : {}) }),
}
const inspected = await launchOverridesDeps.native?.(session.engine, session, { id: session.agentId, current })
if (!current()) return changed()
if (inspected && !inspected.ok) return inspected
const native = inspected?.ok ? inspected.launch : undefined
const valid = await validateLaunchOverrides(launchOverridesDeps, session.engine, target, native)
if (!current()) return changed()
if (!valid.ok) return { ok: false, error: valid.error, detail: valid.detail }
// A resumed opencode session takes its model from its own rows in opencode.db, not from `-m`
// (see below), and those rows are written through the `sqlite3` CLI, or through `node:sqlite` where no CLI
// is installed (Windows; `kit/nativeSessionModel.ts`). Without either the respawn
// would land the right provider, key and argv on a pane that then answers on the OLD model —
// the failure this handler exists to refuse — so it is refused here, before the pane is touched.
// Only when the launch will name a model: a grid launch always does; a move home does only when
// the remembered model carries its provider (`subscriptionModel.ts`), and otherwise the engine
// decides, as it always did. v2 switches the model through OpenCode's own API instead and needs no
// sqlite3 (`applyOpencodeSessionModel`).
const rewritesOpencodeSession = session.engine === 'opencode' && !!reopens
&& (!!grid || !!remembered?.includes('/'))
const opencode = session.engine === 'opencode' ? opencodeLaunch : null
const opencodeMajor = native ? native.opencodeMajor : opencode ? await opencode.opencodeMajorVersion() : null
if (!current()) return changed()
if (rewritesOpencodeSession && opencode && !opencode.isOpencodeV2(opencodeMajor) && !builtinSqlite() && !binaryOnPath('sqlite3')) {
return {
ok: false,
error: 'OPENCODE_SQLITE_MISSING',
detail: 'this Node has no node:sqlite and the sqlite3 CLI is not on PATH, and a resumed opencode session keeps its model unless its store is rewritten — install sqlite3 and retry',
}
}
// The replacement enters the row's folder before it execs: a folder that is gone is refused here,
// with the other refusals, before the pane is touched or its control taken.
const missing = workspaceMissing(session.cwd)
if (missing) return missing
// Mid-turn is the one state where restarting costs real work: the conversation comes back but
// whatever the engine was doing does not. The engine's own turn state (hooks, transcript) says
// so, for every engine; the screen is not read. It used to be, to keep an unsent draft, and an
// engine whose placeholder colour moved (OpenCode 2) then read as holding one and refused every
// switch until its first chat. A draft is lost to the respawn; that is the person's call.
const inTurn = { ok: false as const, error: 'AGENT_BUSY', detail: 'This harness is in a turn. Stop it, then switch the model.' }
if (session.sessionId && sessionTurnOpen(session.sessionId)) return inTurn
// OpenCode 2 keeps its turns where that state does not read (`opencodeV2TurnOpen`), so its own
// record is asked. A store it cannot read is no evidence of a turn, as for an engine with none.
if (session.sessionId && opencode?.isOpencodeV2(opencodeMajor)) {
const open = await opencode.opencodeV2TurnOpen(native ? nativeOpencodeStore(native.environment) : opencodeDb, session.sessionId)
if (!current()) return changed()
if (open) return inTurn
}
// Nothing may type into the pane while it is being replaced.
if (purgeBusy(session.agentId) || restartJobs.busy(session.agentId)) return { ok: false, error: 'AGENT_BUSY' }
const release = acquireTerminalControl(session.agentId)
if (!release) return { ok: false, error: 'AGENT_BUSY' }
// The old restore watcher stays cancelled after this control pin is released.
restartJobs.cancel(session.agentId)
current = captureAuthority()
const routeKey = terminalRouteKey(pane)
let releaseRoute: (() => void) | undefined
try {
// The grid's env and argv, config directory written (keyed on the agent, so moving it between
// grids rewrites one directory) — or nothing at all for a move back to the engine's own login
// (clearing uses set-environment, which every supported tmux has). Built from the override the
// desktop just sent, never from the row: the row is what this call REPLACES. After the refusal
// guards, so a refused move leaves the live process's own configuration untouched.
const built = await relaunchOverrides(session, target, current, native)
if (!current()) return changed()
if (!built.ok) return { ok: false, error: built.error, detail: built.detail }
const dispatchCurrent = () => current() && native?.current() !== false && built.overrides.native?.current() !== false
const preparationChanged = () => current()
? failed('NATIVE_LAUNCH_HELD', 'Waiting for fresh executable and hook evidence.') : changed()
if (!dispatchCurrent()) return preparationChanged()
// ⚠️ THE AGENT MUST ADOPT THE NEW PROCESS, OR IT STOPS BEING THE SAME AGENT.
//
// Identity in this daemon is keyed on the PROCESS, not the pane: the reconciler matches an existing
// record to an observation by pid + start marker (`currentProcessKey`), and its same-pane fallback
// only applies to an agent with no bound engine session. A respawn changes the pid, so left to
// discovery the new process is an unmatched observation — `onDiscovered` mints a NEW agent id, and
// the record the user was looking at becomes a ghost that the app still lists, still counts as "on
// an older target", and still offers to move. Moving it respawns the same pane again. Holding the
// route shuts the reconciler out for the duration; rebinding below is what ends the swap.
releaseRoute = agentReconciler.holdRoute(routeKey, null)
// Back to the engine's own login. Nothing is built, because there is no launch to build. If this
// agent was launched onto a grid at creation, `new-session -e` wrote the grid's variables into
// the pane's SESSION environment, which a bare respawn-pane would inherit — clearing them first
// is what makes the env-less respawn below actually land on the engine's own login instead of
// silently keeping the old grid. If instead the agent was moved here by an earlier retarget,
// `respawn-pane -e` set those variables on that one process, not the session, so this clear is
// a harmless no-op and it is the env-less respawn itself that drops them. Either way the pane
// ends up clean. Run only after every refusal guard above: an early return with the pane
// already cleared but its live process untouched would leave that process still talking to the
// grid while the retarget reports failed — the exact half-applied state this handler exists to
// refuse.
//
// OpenCode's TUI drops `-m` when it RESUMES a session: it restores the model from the session's
// LAST USER MESSAGE (`data.model`), and its server falls back to the `session.model` column
// (measured on 1.18.31; upstream anomalyco/opencode #26901). Nothing else — config, model.json,
// `--fork` — changes a resumed session's model; the picker is the only writer opencode ships,
// and those two rows are what it writes. So they are written here, through SQL, before the
// respawn, with the exact `provider/model` the respawn's own `-m` names — and the TUI opens
// already on it, with nothing typed into the pane. Before the live process is touched, so a
// write that fails refuses the move with that process still on its old target. A session with
// no user message yet has nothing to restore from and takes `-m` on launch, so it is skipped.
//
// OpenCode 2.0 has no `-m` on its TUI, keeps sessions in tables the SQL above never reads (it
// used to answer SESSION_NOT_FOUND there, read as success, and then respawn with `-m` into
// `Unrecognized flag: -m` and a dead pane), and ships its own writer: the service's
// `session.switchModel`. `applyOpencodeSessionModel` picks per version, and on v2 every
// failure refuses the move — with the live process still untouched.
if (rewritesOpencodeSession && opencode) {
const model = built.overrides.sessionModel ? opencode.parseOpencodeModelId(built.overrides.sessionModel) : null
if (model) {
nativeEffect = 'uncertain'
const written = await opencode.applyOpencodeSessionModel({
opencodeMajor, dbPath: native ? nativeOpencodeStore(native.environment) : opencodeDb, sessionId: reopens, model, cwd: session.cwd ?? undefined,
// (A model of opencode's own is looked for in its catalogue; a grid's provider lives in
// the pane's own config, which the service never reads.)
checkCatalog: !grid,
}, { current: dispatchCurrent, ...(native?.executable ? { executable: native.executable, environment: { ...built.overrides.env, ...native.environment } } : {}) })
nativeEffect = written.ok ? 'applied' : (written.effect ?? 'none')
if (!dispatchCurrent()) return preparationChanged()
if (!written.ok) {
console.warn(`[grid] retarget ${sid(session.agentId)} refused · ${written.code} · ${written.detail}`)
return { ok: false, error: written.code, detail: written.detail }
}
}
}
// A backend with no `clearEnv()` (the pty host keeps the pane's create env as tmux keeps its session's) clears
// the same names in the respawn itself: `clearPaneEnv` below.
if (!grid && backend.clearEnv) {
const cleared = await backend.clearEnv(pane, gridEnvVarNames(session.engine), dispatchCurrent)
if (!dispatchCurrent()) return preparationChanged()
if (cleared.state !== 'succeeded') {
return failed('GRID_CLEAR_FAILED', 'reason' in cleared ? cleared.reason : 'tmux would not clear the pane environment')
}
}
const bypassPermission = await bypassPermissionFor(session, () => liveBypassPermission(session))
if (!current()) return changed()
const retargetPermission = await downgradedPermission(session, bypassPermission, 'retarget', native)
if (retargetPermission.nativeHold || native?.current() === false) return failed('NATIVE_LAUNCH_HELD', retargetPermission.nativeHold ?? 'Waiting for fresh executable and hook evidence.')
if (!current()) return changed()
// A Codex conversation is bound to its provider (`providerBoundConversations`): moved between a grid and the
// own login it goes on in a fork, its whole history with it; grid to grid is one provider and resumes. The
// conversation a fresh move left was the own login's, so going home it resumes.
const movesProvider = !!launchContract(session.engine)?.providerBoundConversations
&& !!reopens && (homeConversation ? false : onGrid) !== !!grid
const outcome = await restartAgent(
{ engine: session.engine, sessionId: reopens, ...(session.resumeOnly ? { resumeOnly: true as const } : {}),
...(movesProvider ? { continueInFork: true as const } : {}) },
retargetPermission.bypassPermission === true,
{ ...paneSwapDeps(session, place, !grid && !backend.clearEnv ? { ...built.overrides, clearPaneEnv: gridEnvVarNames(session.engine) } : built.overrides,
retargetPermission.permissionMode ?? null, dispatchCurrent, ...(homeConversation ? [homeConversation] as const : [] as const)), isCurrent: dispatchCurrent,
...(movesProvider ? { prepareFork: () => {
const env: NodeJS.ProcessEnv = { ...process.env, CODEX_HOME: sessionCodexHome(session), ...built.overrides.env, ...built.overrides.native?.environment }
if (!grid) for (const name of gridEnvVarNames(session.engine)) delete env[name]
return moveCodexConversation({
sessionId: reopens, toGrid: !!grid, args: built.overrides.extraArgs ?? [], env,
argv: (codexArgs) => windowsEngineArgv(session.engine, [built.overrides.native?.executable?.command ?? engineBin(session.engine), ...codexArgs]),
...(session.cwd ? { cwd: session.cwd } : {}),
})
} } : {}) },
)
replacementStarted = outcome.ok
if (!current()) return changed()
if (!outcome.ok) {
console.warn(`[grid] retarget ${sid(session.agentId)} failed · ${outcome.detail}`)
return failed('RESPAWN_FAILED', outcome.detail)
}
// Commit the new process now. Optional grid metadata follows outside the route hold.
const gateway = await probeGatewayRuntime(outcome.processIdentity)
if (!current()) return changed()
await backend.releaseHold(pane, current)
if (!current()) return changed()
registry.updateProcessIdentity(session.agentId, outcome.processIdentity, gateway.kind)
// The launch that just worked is the one a restart or a post-reboot restore must repeat — and
// what it decided about web search is what the app shows for this agent from now on. Null for
// a move home: the block, and the status with it, leave the frame together.
registry.setGridLaunch(session.agentId, built.overrides.gridLaunchRecord ?? null)
// Persisted only on the way OUT, and only once the move actually succeeded — a refused move
// must not overwrite the model the agent is still sitting on. Survives a daemon restart, so an
// agent left on a grid for a week still knows where it came from.
if (grid && remembered) registry.setSubscriptionModel(session.agentId, remembered)
// The conversation: kept on a fresh move from the own login, forgotten on any other move from it (it goes on
// on the grid) and once home. Grid to grid it stays, like the model.
const keptConversation = !grid ? null : onGrid ? session.subscriptionSessionId ?? null
: startsFresh && session.sessionId ? session.sessionId : null
if ((session.subscriptionSessionId ?? null) !== keptConversation) registry.setSubscriptionSession(session.agentId, keptConversation)
registry.setActive(session.agentId, true)
const refreshed = registry.byAgent(session.agentId)
// The app decides whether to still offer a move from what it is told here, so a silent success
// would leave the banner up over an agent that had already been moved.
if (refreshed) { announceSession(refreshed); refreshGridAssignment(refreshed) }
const how = outcome.resumed ? (movesProvider ? 'continued in a fork' : 'resumed') : 'fresh session'
const record = built.overrides.gridLaunchRecord
const where = record
? describeGridLaunch(session.engine, record.override, record.webSearch)
: `${session.engine} on its own login`
console.log(`${where} · retargeted ${sid(session.agentId)} · ${how}`)
// Nothing is typed into the pane after the respawn. A resumed opencode session used to be put
// on its model through the `/models` picker here (MODEL_SELECT_FAILED); its store is rewritten
// before the respawn instead, see above.
return { ok: true }
} catch (error) {
if (nativeEffect !== 'none' || replacementStarted) return failed('RETARGET_FAILED', error instanceof Error ? error.message : String(error))
throw error
} finally {
release()
releaseRoute?.()
}
}
return retargetAgent
}