Skip to content

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.

12.6 KB
Raw Blame
/**
 * The pane-process swap: kill an agent's engine, respawn it in the pane it was already in, and wait for
 * the new process — what restart and retarget both do, with the restart coordinator that keeps one swap
 * per agent at a time, and the bypass flag the live process was launched with.
 *
 * Moved verbatim out of `runForeground` (the core boundary, step 11: docs/design/2026-10-03-harnessd.md).
 */
import { homedir } from 'node:os'
import { checkPidRuntime, terminateDeletedAgent } from '../../lib/deleteAgentFallback.js'
import { buildEngineCommandArgv, buildEngineLaunchArgv, engineLaunchEnv } from '../../lib/engineLaunch.js'
import { engineBin } from '../../lib/engineBin.js'
import { stopConflictingBackgroundJob } from '../../lib/claudeBackgroundJob.js'
import { windowsLaunchRefusal } from '../../lib/windows/launch.js'
import { isWindowsHeldPane, windowsPaneLaunch } from '../../lib/windows/engineStart.js'
import { mergedLaunchEnv } from './launchEnv.js'
import type { RegisteredSession } from '../../lib/registry.js'
import { AgentRestartCoordinator, type RelaunchArgvOptions, type RestartAgentDeps } from '../../lib/restartAgent.js'
import { processRows } from '../../lib/terminalAgentDiscovery.js'
import type { RestartTarget } from '../../lib/terminalBackend.js'
import { resolvePaneEngineProcess } from '../../lib/paneEngineProcess.js'
import { bypassPermissionActive } from '../../lib/processTable.js'
import { sameProcessIdentity } from '../../lib/terminalRuntime.js'
import { signalAgentProcess } from '../../lib/processSignals.js'
import type { StopAgentServiceDeps } from '../../lib/stopAgentService.js'
import { paneReadIdentity } from '../transcripts/readIdentity.js'

export interface PaneSwapDeps {
  restartJobs?: AgentRestartCoordinator
  byAgent: (agentId: string) => RegisteredSession | undefined
  prepareSessionResume: (session: RegisteredSession) => void
  /** Keeps a conversation a swap had to leave for a new one as a stopped harness (lib/keepAbandonedConversation.ts). */
  keepAbandonedConversation: (left: RegisteredSession) => void
  /** Release the conversation on its engine's server before replacing the terminal client. */
  stopNative: StopAgentServiceDeps['stopNative']
}

/** How long a relaunched engine must stay running before a restart counts it as come up (`waitForProcess`). */
export const SWAP_SETTLE_MS = 500

export function createPaneSwap({ byAgent, prepareSessionResume, keepAbandonedConversation, stopNative, restartJobs = new AgentRestartCoordinator() }: PaneSwapDeps) {
  /**
   * The dependencies a pane-process swap needs, for both callers that do one.
   *
   * Restart and retarget are the same mechanism pointed at different ends: kill the engine, respawn it
   * in the pane it was already in, wait for the new process. They differ only in what the replacement
   * is launched WITH — retarget adds the grid's environment and the argv that configures it — so that
   * is the only thing this takes. Written once because two copies of a kill sequence drift, and the
   * half that drifts is the half nobody ran today.
   */
  const sameRestartTarget = (session: RegisteredSession): boolean => {
    const current = byAgent(session.agentId)
    return !!current && current.registeredAt === session.registeredAt
      && current.tmuxPane === session.tmuxPane && current.engine === session.engine
  }

  const paneSwapDeps = (
    session: RegisteredSession,
    /** The row's own pane and the backend it is on (`restartTargetOf`): a swap runs where the row is. */
    { backend, runtime }: RestartTarget,
    launch: { native?: import('../../engines/nativeLaunch.js').NativeLaunch; env?: Record<string, string>; extraArgs?: readonly string[]; ownerArgs?: readonly string[]; clearEnv?: readonly string[]
      /** Names the respawn takes out of what the pane was created with, on a backend with no `clearEnv()` of its own
       *  (the pty host): a retarget home's grid variables. */
      clearPaneEnv?: readonly string[] } = {},
    /** The mode this swap may actually ask for — the row's own, unless the engine on disk has since
     *  stopped taking its flag and the caller dropped it (`dropPermissionFlagIfUnsupported`). */
    permissionMode: string | null = session.permissionMode ?? null,
    current?: () => boolean,
    /** The conversation the relaunch reopens when it is not the row's own: a retarget home reopening the one a
     *  fresh move left (retarget.ts). The process stopped is still the row's. */
    reopens?: string,
  ): RestartAgentDeps => {
    const target = { ...session, processIdentity: session.processIdentity && { ...session.processIdentity } }
    // Found by its id when it is another conversation: the row's transcript is the one it is leaving.
    const conversation = reopens && reopens !== session.sessionId ? { ...session, sessionId: reopens, transcriptPath: null } : session
    const identity = paneReadIdentity(target)
    const ownsOriginal = () => current?.() !== false && sameRestartTarget(target)
      && paneReadIdentity(byAgent(target.agentId)) === identity
    const relaunchOptions = (opts: RelaunchArgvOptions) => ({
      ...opts,
      ...(launch.native ? { native: launch.native } : {}),
      // The mode picked at create outranks what the live argv said: `bypassPermission` is a yes/no, and
      // Plan or Accept edits would come back as Ask without it.
      ...(permissionMode ? { permissionMode } : {}),
      ...(session.cwd ? { cwd: session.cwd } : {}),
      ...(launch.extraArgs?.length ? { extraArgs: launch.extraArgs } : {}),
      // The owner's own words, which the argv builder puts last (engineLaunch.ts `ownerArgs`).
      ...(launch.ownerArgs?.length ? { ownerArgs: launch.ownerArgs } : {}),
      // A pane swap onto a grid has to clear the same vendor credentials a fresh create does, for the
      // same reason and against the same failure: an engine re-exec'd with the grid's variables still
      // sees whatever else the pane inherited, and picks its provider from all of it. This was the
      // gap — a create cleared them, then moving that agent onto a grid from the pane header put them
      // straight back, so the engine came up on Anthropic with a grid selected above it.
      //
      // Named by the caller (`buildLaunchOverrides` derives it from what the grid launch provides), so
      // a swap that sets no grid — back to the engine's own login, or a Codex profile's CODEX_HOME —
      // clears nothing. There the user's own variables are the point.
      ...(launch.clearEnv?.length ? { clearEnv: launch.clearEnv } : {}),
      ...(launch.env?.HARNESS_DSH ? { harnessNode: true } : {}),
    })
    return {
      ...(current ? { isCurrent: current } : {}),
      prepareResume: () => prepareSessionResume(conversation),
      // The conversation the swap meant to reopen: the one a fallback to a fresh start leaves behind.
      keepAbandoned: () => keepAbandonedConversation(conversation),
      // Only a backend that can refuse is asked (tmux, too old for `-e`); the pty host takes any environment.
      ...(backend.respawnRefusal ? { respawnRefusal: () => backend.respawnRefusal!(launch.env ? { env: launch.env } : {}) } : {}),
      holdOpen: async () => {
        const result = await backend.holdOpen(runtime, current)
        return result.state === 'succeeded'
          ? { ok: true }
          : { ok: false, reason: 'reason' in result ? result.reason : 'could not re-arm remain-on-exit' }
      },
      terminate: async (checkAfterMs) => {
        if (!ownsOriginal()) return 'not-ours'
        // A failed native turn can leave the shared app-server holding its writer lock.
        // Release that conversation before stopping its terminal client.
        await stopNative(target, ownsOriginal)
        if (!ownsOriginal()) return 'not-ours'
        return terminateDeletedAgent(target, {
          checkRuntime: checkPidRuntime,
          kill: signalAgentProcess,
          sleep: (ms) => new Promise((resolve) => { const t = setTimeout(resolve, ms); t.unref?.() }),
          log: (message) => console.log(message),
          current: ownsOriginal,
        }, checkAfterMs)
      },
      respawn: async (argv) => {
        // Windows: the variables the argv's `/usr/bin/env` prefix carries elsewhere, last (engineLaunchEnv).
        const env = mergedLaunchEnv(launch.env, engineLaunchEnv(session.engine, launch.native))
        const result = await backend.respawn(runtime, {
          command: argv,
          ...(current ? { current } : {}),
          cwd: homedir(),
          // Windows: the workspace to start in, what this launch alone must not inherit from the host (its own
          // `clearEnv`, a grid's keys: none for a swap that sets no grid), and the shell the pane becomes after the
          // engine (lib/windows/engineStart.ts). Never merged with `clearPaneEnv`, which only takes names out of
          // what the pane was created with, as tmux's `set-environment -u` does.
          ...windowsPaneLaunch(session.engine, { ...relaunchOptions({ bypassPermission: false }), held: isWindowsHeldPane(argv) }),
          ...(env ? { env } : {}),
          ...(launch.clearPaneEnv?.length ? { clearEnv: launch.clearPaneEnv } : {}),
        })
        return result.state === 'succeeded'
          ? { ok: true }
          : { ok: false, reason: 'reason' in result ? result.reason : 'tmux respawn-pane did not complete' }
      },
      waitForProcess: async () => {
        // Mirrors onCreateAgent's own discovery budget/backoff shape for the same reason: the engine's
        // interactive-login-shell startup, not the tmux call, is the slow half.
        const SWAP_DISCOVERY_BUDGET_MS = 8_000
        let delayMs = 150
        let waited = 0
        while (waited < SWAP_DISCOVERY_BUDGET_MS) {
          await new Promise((resolve) => setTimeout(resolve, delayMs))
          waited += delayMs
          const found = await resolvePaneEngineProcess(backend, runtime, session.engine)
          if (found) {
            // Up means still up a moment later: a launch the engine refuses (`codex resume` after an update
            // dropped it) runs for an instant, and seen then, the restart said "resumed" and never fell back
            // to a fresh start (e2e/updates.e2e.ts on Linux, whose faster start put it in the first look).
            await new Promise((resolve) => setTimeout(resolve, SWAP_SETTLE_MS))
            waited += SWAP_SETTLE_MS
            const still = await resolvePaneEngineProcess(backend, runtime, session.engine)
            if (sameProcessIdentity(still, found)) return found
          }
          delayMs = Math.min(delayMs * 2, 750)
        }
        return null
      },
      buildArgv: (opts) => buildEngineLaunchArgv(session.engine, relaunchOptions(opts)),
      // The same command, built without its launch script (no file is written), before anything is stopped.
      launchRefusal: (opts) => {
        try { buildEngineCommandArgv(session.engine, relaunchOptions(opts)); return null } catch (error) { return windowsLaunchRefusal(error).detail }
      },
      // Claude only. `launch.native` is the captured launch for every ordinary LOCAL Claude run
      // (launchOverrides.ts), not a signal the pane is elsewhere, so it must not gate this off. A DSH
      // agent's pane is the one case that may run on a different host entirely, whose `claude --bg`
      // jobs this process cannot see.
      ...(session.engine === 'claude' && !session.dsh ? { stopConflictingJob: () =>
        // The exact environment the pane is about to get, the same way `respawn` above builds it: `launch.env`
        // already carries a native launch's own CLAUDE_CONFIG_DIR (launchOverrides.ts merges `native.environment`
        // into it), and `engineLaunchEnv` adds Windows's own-process variables.
        stopConflictingBackgroundJob({ bin: engineBin(session.engine), sessionId: conversation.sessionId,
          env: { ...process.env, ...launch.env, ...engineLaunchEnv(session.engine, launch.native) } }) } : {}),
      log: (message) => console.log(message),
    }
  }

  /** The bypass-permission flag the LIVE process was launched with. The fallback behind
   *  `bypassPermissionFor` for a row that recorded neither a mode nor the flag (written before either
   *  was persisted, and not yet seen by a discovery scan); read before anything is signalled. */
  const liveBypassPermission = async (session: RegisteredSession): Promise<boolean> => {
    const identity = session.processIdentity
    if (!identity) return false
    const rows = await processRows()
    const row = rows?.find((candidate) => sameProcessIdentity(candidate, identity))
    return row ? bypassPermissionActive(session.engine, row.args) : false
  }
  return { restartJobs, sameRestartTarget, paneSwapDeps, liveBypassPermission }
}

export type PaneSwap = ReturnType<typeof createPaneSwap>