Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

31.7 KB
Raw Blame
import { maintenance } from '../lib/maintenanceAdmission.js';
/**
 * Agent TUI Spawning
 *
 * Runs CoS agents inside an interactive PTY-backed shell session. This is for
 * providers whose useful interface is a terminal UI rather than a headless CLI
 * or HTTP API.
 *
 * This module is the PUBLIC ADAPTER the rest of the agent cluster consumes
 * (`agentLifecycle.js`). It owns three things and delegates the rest:
 *
 *   - `resolveTuiLaunchShape` / `createAgentTuiSession` — which of the three PTY
 *     shapes a run gets, and the environment each one is opened with.
 *   - `spawnTuiAgent` — the orchestration: resolve the run's cwd, sentinel path,
 *     PR ownership and credentials; open the PTY; wire the live state machine to
 *     it; record the handoff and the agent registration.
 *   - The compatibility surface: `buildTuiSpawnConfig` is re-exported from
 *     `agentTuiSpawning/spawnConfig.js` so existing callers need no migration.
 *
 * The live session state machine — session phase, prompt delivery and its retry
 * ladder, the sentinel watcher, the provider-signal/idle gates, and the single
 * teardown path — lives in `agentTuiSpawning/sessionController.js` (#8021).
 * Output spooling (`outputSpooler.js`) and failure analysis
 * (`finalizeHelpers.js`) are the earlier extractions from #2833.
 */

import { join } from 'path';
import * as shellService from './shell.js';
import { emitLog } from './cosEvents.js';
import { updateAgent } from './cosAgentLifecycle.js';
import { createOutputSpooler } from './agentTuiSpawning/outputSpooler.js';
import { resolveErrorAnalysis } from './agentTuiSpawning/finalizeHelpers.js';
import { createTuiSessionController } from './agentTuiSpawning/sessionController.js';
import { buildTuiSpawnConfig } from './agentTuiSpawning/spawnConfig.js';
import { finalizeAgent } from './agentFinalization.js';
import { runSpawnerCompletionCleanup } from './agentCompletionCleanup.js';
import { activeAgents, registerSpawnedAgent, unregisterSpawnedAgent } from './agentState.js';
import { PATHS } from '../lib/fileUtils.js';
import { resolveAgentCliCwd } from '../lib/spawnCwd.js';
import { doneSentinelPath as resolveDoneSentinelPath } from '../lib/agentSentinel.js';
import { createAgentSentinelAccess } from './agentSentinelWatcher.js';
import { PTY_UNAVAILABLE_PREFIX } from '../lib/ptySpawnDiagnostics.js';
import { LIFECYCLE_LINES } from '../lib/agentOutputMarkers.js';
import { finalizeAgentRunCommon, shouldAbandonAgentRun } from './agentRunFinalize.js';
import { leavesPrForHuman } from '../lib/prDisposition.js';
import { resolvePrOwnership, PR_OPENED_BY } from '../lib/slashdoInvocation.js';
import { mergeGateOwed } from '../lib/mergeGateContract.js';
import { probePrForBranch } from './prProbe.js';
import * as git from './git.js';
import { spawnTuiSessionViaRunner, classifyRunnerSpawnFailure, RUNNER_SPAWN_REFUSED, RUNNER_SPAWN_AMBIGUOUS } from './cosRunnerClient.js';
import { providerSuppliesGithubToken } from '../lib/providerModels.js';
import { isPublicReviewRestrictedProfile } from '../lib/agentExecutionProfiles.js';
import { agentGuardEnv } from '../lib/agentGuard/index.js';
import { buildCliChildEnv, composeProviderEnv } from '../lib/cliChildEnv.js';
import { cliProviderAuthDescriptor } from '../lib/processEnv.js';
import { resolveAgentApiEnv } from './agentApiAuth.js';
import { ensureOllamaAgentContext } from './ollamaAgentContext.js';
import { isOllamaBackedProvider } from './providers.js';
import { shellHasLiveChild } from '../lib/shellLivenessProbe.js';
import { appendRunEvent } from './agentRunEventLog.js';

// The pure launch-shape builder. Re-exported rather than moved outright so
// `agentLifecycle.js` and the existing tests keep their entry point (#8021).
export { buildTuiSpawnConfig };

// Sentinel-file watching. TUI agents write `.agent-done` in their workspace
// when they've finished /simplify + /do:pr (or /do:push) — the session
// controller watches for it so the agent gets cleanly finalized as soon as the
// work is done, without waiting for a shell exit or repeatedly touching the
// filesystem.
// The filename is per agent instance — see doneSentinelName in ../lib/agentSentinel.js.

/**
 * What kind of PTY a TUI run gets. Resolved ONCE per run and threaded, rather
 * than re-derived wherever it matters: two consumers wire the prompt handshake
 * BEFORE the spawn happens, and a predicate that silently disagreed with the
 * branch actually taken fails by never delivering the prompt — no error, on a
 * live run.
 *
 *   'runner'      — the CoS Runner owns the PTY, in another process.
 *   'direct'      — this process pty.spawns the provider binary itself.
 *   'login-shell' — an interactive login shell with the CLI typed into it.
 *
 * A public-content stage is `direct` because a login shell would run the
 * operator's rc file inside its allowlisted environment (#6159). It is never
 * `runner`: the runner builds its own child env, which would drop that
 * allowlist, so `agentLifecycle.js` forces those stages direct-only and
 * `createAgentTuiSession` fails closed if one arrives anyway.
 *
 * This is a separate axis from `isPublicReviewRestrictedProfile` itself, which
 * answers a different question (is the env COMPLETE or a delta?) — the runner
 * case is the proof they are not the same axis.
 */
export function resolveTuiLaunchShape({ useDurableRunner = false, safetyProfile = null } = {}) {
  if (useDurableRunner) return 'runner';
  return isPublicReviewRestrictedProfile(safetyProfile) ? 'direct' : 'login-shell';
}

/**
 * Open the agent TUI's PTY and pair the returned session id with its underlying
 * pty process, so callers don't have to make a second `getSessionProcess` call
 * inline. Centralizes the agent-side defaults (kind, label, initialCommand).
 *
 * The launch shape is resolved by the caller and threaded through to avoid
 * the hand-shake mismatch documented in resolveTuiLaunchShape.
 *
 * Returns `{ sessionId, ptyProcess, pid }`. When the shell service fails
 * to create the session, `sessionId` is null and the caller is expected
 * to bail out via its `finish` path.
 */
export async function createAgentTuiSession({
  agentId,
  taskId,
  provider,
  model,
  tuiConfig,
  cwd,
  forgeTokenEnv = {},
  agentApiEnv = {},
  doneSentinelPath = null,
  securityScanGrant = null,
  launchShape,
  safetyProfile = null,
  onData,
  onExit,
  onInitialCommandSent,
}) {
  const restricted = isPublicReviewRestrictedProfile(safetyProfile);
  // A public-content stage's PTY starts from the SAME environment its headless
  // sibling gets — no forge credential, no SSH config, no cloud key, no
  // arbitrary provider var — so it calls the very builder the headless path
  // uses rather than re-deriving the profile→allowlist mapping here.
  //
  // The two branches produce DIFFERENT KINDS of value, which is why they route
  // to different spawn entry points below. `buildCliChildEnv` returns a COMPLETE
  // environment, so a restricted stage goes to `spawnCommandSession`, which
  // unions nothing underneath it — and which is also what removes the login
  // shell, so the operator's rc file can no longer run between this allowlist
  // and the provider and re-export whatever it likes (#6159). The ordinary
  // branch is a DELTA: `createShellSession` unions it onto `buildSafeEnv`.
  // The credential overlay both branches start from: the repo-owner GH_TOKEN and
  // the loopback PortOS API token (agentApiAuth.js). Both are resolved by the
  // caller and both are `{}` for a public-content stage, whose allowlist would
  // strip them regardless.
  const credentialEnv = { ...forgeTokenEnv, ...agentApiEnv };
  const env = restricted
    ? buildCliChildEnv({ before: credentialEnv, provider, model, cwd, guard: true, safetyProfile })
    : { ...composeProviderEnv({ before: credentialEnv, provider, model }), ...agentGuardEnv() };
  // How this session identifies itself in the Shell UI and the session registry.
  // Identical for all three spawn shapes below — an attached human sees the same
  // tab whichever one opened the PTY.
  const sessionOptions = {
    cwd,
    kind: 'agent-tui',
    agentId,
    label: `${provider.name} ${agentId}`,
    command: tuiConfig.commandLine,
  };
  let sessionId;
  if (launchShape === 'runner') {
    // The CoS runner is a shared long-lived process and builds its own child
    // env from ITS ambient environment (`/spawn-tui` → `buildCliChildEnv`
    // without a profile), so a public-content stage routed through it would
    // silently lose the allowlist resolved above. `agentLifecycle.js` forces
    // every such stage direct-only (`dispatchUseRunner`); fail closed here so
    // that stays true by construction rather than by remembering it.
    if (restricted) {
      throw new Error(`Public-content stage cannot spawn via the CoS runner (profile '${safetyProfile}')`);
    }
    // The runner launches the TUI command directly (there is no intermediate
    // login-shell readiness probe), so output can arrive before the spawn HTTP
    // response. Open the readiness gate before handing off to avoid discarding
    // the TUI's first bracketed-paste/input-ready signals.
    onInitialCommandSent?.();
    // An external session's exit wiring belongs to its owner (shell.js
    // adoptPtySession), so this branch unregisters it, as agentRunnerSync.js
    // does for a recovered run. Otherwise the record outlives the PTY and a
    // later paste "succeeds" into the runner proxy, whose writes always report
    // true (#11861). It runs BEFORE the controller sees the exit; `exited`
    // keeps a `tui:exit` that beats the spawn response from registering a
    // session that is already dead.
    let session = null;
    let exited = false;
    session = await spawnTuiSessionViaRunner({
      agentId,
      taskId,
      command: tuiConfig.spawnCommand,
      args: tuiConfig.spawnArgs,
      workspacePath: cwd,
      envVars: env,
      providerAuth: cliProviderAuthDescriptor(provider),
      doneSentinelPath,
      securityScanGrant,
      trackPromptSubmission: true,
      onData,
      onExit: (event) => {
        exited = true;
        if (session) shellService.unregisterExternalSession(session.sessionId, { exitCode: event?.exitCode });
        return onExit?.(event);
      },
    });
    if (!exited) shellService.registerExternalSession(session.sessionId, session.ptyProcess, sessionOptions);
    // The runner owns this PTY, so it already returns the pty/pid pair the tail
    // below would otherwise have to look up locally.
    return session;
  }

  if (launchShape === 'direct') {
    // Launch the vendor recipe AS the PTY — no hosting shell, so no rc file runs
    // between the allowlist above and the provider (#6159). `env` is already the
    // COMPLETE environment, which is what `spawnCommandSession` takes.
    //
    // `spawnCommandSession` resolves the executable before it spawns and throws
    // `Command executable unavailable: …` when it cannot — which the caller's
    // catch maps to `command-not-found`. That pre-flight has to live in the
    // launcher: a PTY has no shell to print "command not found", so handleData's
    // output-driven probe can never fire on this path.
    //
    // No shell readiness probe fires `onInitialCommandSent` here, so open the
    // paste gate before the spawn — exactly as the runner branch above does —
    // or the TUI's first bracketed-paste/input-ready bytes are discarded.
    onInitialCommandSent?.();
    sessionId = shellService.spawnCommandSession(tuiConfig.spawnCommand, tuiConfig.spawnArgs, {
      ...sessionOptions,
      env,
      onData,
      onExit,
    });
  } else {
    // This shell exists only to host the CoS TUI. `exitWithCommand` makes it
    // follow the TUI's lifetime and preserve the TUI exit status; otherwise the
    // login shell returns to its prompt when the provider exits and the spawner
    // cannot observe completion until the wall-clock backstop fires. The wrapper
    // is dialect-specific, so shell.js renders it once it knows which shell the
    // session got (see lib/shellExit.js).
    sessionId = shellService.createShellSession(null, {
      ...sessionOptions,
      initialCommand: tuiConfig.commandLine,
      exitWithCommand: true,
      // Wait until the shell can actually RUN commands before injecting the CLI
      // command — a fixed delay races a heavy interactive shell and the launched
      // TUI can fall straight back to a half-loaded prompt (see shell.js
      // waitForPromptReady, which proves readiness with a round-trip probe).
      waitForPromptReady: true,
      // Fires when the CLI command is actually injected. We start observing
      // claude's input-readiness only after this so the readiness probe's own
      // shell activity can't prematurely open the paste gate.
      onInitialCommandSent,
      // A DELTA, not a full env — buildSafeEnv inside createShellSession supplies
      // the base and shell.js does the PWD pin. composeProviderEnv owns the layer
      // order (forgeTokenEnv before provider.envVars so an explicit provider
      // GH_TOKEN still wins; the OpenCode declared-models map after it, overriding
      // the static config). forgeTokenEnv has to be threaded in explicitly because
      // buildSafeEnv strips GH_TOKEN from the inherited env (resolveForgeTokenEnv).
      //
      // agentGuardEnv() is spread last so the pm2 shim wins over any provider PATH.
      // It reads PATH from process.env rather than the composed env — correct here
      // and NOT what buildCliChildEnv's `guard` does, because this is an overlay
      // whose real base env is assembled downstream. Only AI agent sessions get
      // the shim; the user's own Shell page does not.
      env,
      onData,
      onExit,
    });
  }

  if (!sessionId) {
    return { sessionId: null, ptyProcess: null, pid: null };
  }

  const ptyProcess = shellService.getSessionProcess(sessionId);
  return { sessionId, ptyProcess, pid: ptyProcess?.pid || null };
}


export async function spawnTuiAgent({
  agentId,
  task,
  prompt,
  workspacePath,
  model,
  provider,
  runId,
  tuiConfig,
  agentDir,
  executionId,
  laneName,
  prOpenedBy,
  leanMode = false,
  useDurableRunner = false,
  securityScanGrant = null,
  // The public-content execution profile this run enforces (null for an
  // ordinary agent task). Threaded through to the session so the PTY child
  // gets the same allowlisted environment its headless sibling would.
  safetyProfile = null,
}) {
  // Resolved here once because the prompt handshake below is wired before the
  // spawn happens. Threaded through to createAgentTuiSession and the controller
  // so the shape is derived once per run and both consumers see the same answer.
  const launchShape = resolveTuiLaunchShape({ useDurableRunner, safetyProfile });
  const outputFile = join(agentDir, 'output.txt');
  // Raw PTY bytes spool to disk continuously rather than accumulate in-memory.
  // A chatty TUI (token-tick repaints, status lines) emits hundreds of chunks
  // /sec; a per-run in-memory buffer would grow without bound on long agents
  // and the join-into-single-string at finalize would double peak RAM. The
  // disk file is appended in 250ms-debounced batches (same pattern as
  // `flushPendingLines` for parsed output — see AGENTS.md "High-frequency
  // state writes must batch"), and `analyzeAgentFailure` reads the file on
  // failure so it gets the full PTY stream regardless of run length.
  const rawFile = join(agentDir, 'raw.txt');
  // CD no-worktree tasks get an isolated scratch cwd so native AGENTS.md
  // discovery cannot reach the PortOS repo tree (#4650). Everyone else keeps
  // workspacePath, falling back to the repo root when it was omitted.
  const cwd = resolveAgentCliCwd({ workspacePath, fallbackRoot: PATHS.root, task, agentId });
  // The agent writes `.agent-done` in its workspace to signal completion (see
  // the session controller's sentinel watcher) and then stops — it does NOT run
  // `/quit` (that is a UI command the agent can't invoke). The file watcher is
  // the primary finalize path; the controller's finish() also ingests the
  // sentinel directly so the summary is captured even if some other path (shell
  // exit) finalizes first. Resolved from the shared helper, so this is
  // byte-identical to the path the prompt told the agent to write.
  const doneSentinelPath = resolveDoneSentinelPath(cwd, agentId);
  const sentinelAccess = createAgentSentinelAccess({
    workspacePath: cwd,
    agentId,
    startedAt: Date.now(),
    getActiveAgentIds: () => activeAgents.keys(),
  });
  // Every TUI that is a real coding harness drives its own push → PR → review
  // → merge, whether or not it can type `/do:pr` (#3733) — a Claude TUI runs
  // the slashdo command (`prOpenedBy: 'agent-slashdo'`),
  // codex/antigravity/grok/OpenCode run the plain `git`/`gh` equivalent from
  // the same prompt (`'agent-inline'`). A lean `--bare` session, and any task
  // shape whose prompt says "do NOT open a PR", hands the lifecycle back to
  // PortOS (`'portos'`). Resolved once up front (rather than inside finish())
  // so the merge-gate contract check and the completion dispatch finish() hands
  // off to read the same answer.
  const prOwnership = resolvePrOwnership({
    task,
    persistedPrOpenedBy: prOpenedBy,
    providerId: provider?.id,
    providerCommand: provider?.command,
    leanMode,
  });
  // Does this run's own task shape say it owed a merge (#5876)? Only the inline
  // prompt carries a **Merge Gate** section to hold it to — a `/do:pr` run
  // merges inside that one command, and a run PortOS backstops or that hands
  // the PR to a human (JIRA, claim flow) never owed one. So the contract check
  // in the controller is inert for all three — see mergeGateContract.js.
  const mergeGateIsOwed = mergeGateOwed({
    taskOpenPR: prOwnership.taskOpenPR,
    rendersInlinePrLifecycle: prOwnership.prOpenedBy === PR_OPENED_BY.AGENT_INLINE,
    leaveOpen: leavesPrForHuman(task),
  });

  // Output buffering + raw PTY spooling (parsed-line → output.txt/state,
  // raw bytes → raw.txt, both debounced) live in the extracted spooler so
  // this function stays orchestration. `appendLine` records a status line,
  // `pushRaw` queues a raw chunk, `drainLines`/`drainRaw` flush at finalize,
  // and `getOutputBuffer` reads the capped buffer for failure-analysis fallback.
  const spooler = createOutputSpooler({ agentId, outputFile, rawFile });
  const { appendLine } = spooler;

  // The live state machine. Created BEFORE the PTY, because its `handleData` /
  // `handleExit` are what open it; `attachSession` arms prompt delivery and the
  // polling timers once a session id exists. Every collaborator it needs from
  // the SERVICE layer is threaded in here — that is what keeps
  // `sessionController.js` a leaf with no edge back into this cluster, and what
  // makes the state machine drivable without a live PTY in a test.
  let maintenanceExited = false;
  let maintenanceCleaned = false;
  const settleMaintenance = () => {
    if (maintenanceExited && maintenanceCleaned) maintenance.finishResource('agent', agentId);
  };
  const controller = createTuiSessionController({
    agentId,
    task,
    runId,
    model,
    provider,
    securityScanGrant,
    prompt,
    tuiConfig,
    cwd,
    rawFile,
    executionId,
    laneName,
    launchShape,
    prOwnership,
    mergeGateIsOwed,
    spooler,
    session: {
      write: (sessionId, keys, options) => options
        ? shellService.writeToSession(sessionId, keys, options)
        : shellService.writeToSession(sessionId, keys),
      paste: (sessionId, text, options) => shellService.pasteToSession(sessionId, text, options),
      isAlive: (sessionId) => !!shellService.getSession(sessionId),
      kill: (sessionId) => shellService.killSession(sessionId),
      hasLiveChild: (pid) => shellHasLiveChild(pid),
    },
    persistence: {
      markUnsettled: () => maintenance.markResourceUnsettled('agent', agentId),
      updateAgent,
      appendRunEvent,
      readRunRecord: () => activeAgents.get(agentId),
      releaseRunRecord: async (pid) => {
        if (pid) unregisterSpawnedAgent(pid);
        activeAgents.delete(agentId);
        await import('./agentRepoStateVerification.js').then(module => module.resumeAgentCompletionRetirement(agentId))
          .catch(error => emitLog('warn', `Completion retirement deferred for ${agentId}: ${error.message}`, { agentId }));
        maintenanceCleaned = true;
        settleMaintenance();
      },
    },
    sentinel: {
      path: doneSentinelPath,
      exists: sentinelAccess.exists,
      resolvedPath: sentinelAccess.resolvedPath,
      read: () => sentinelAccess.read(),
      remove: () => sentinelAccess.remove(),
      promote: (contents) => sentinelAccess.promote(contents),
      cleanup: () => sentinelAccess.cleanup(),
      watch: (onDetect) => sentinelAccess.watch(onDetect),
    },
    finalization: {
      finalizeAgent,
      finalizeRunCommon: finalizeAgentRunCommon,
      shouldAbandonRun: shouldAbandonAgentRun,
      resolveErrorAnalysis,
      runCompletionCleanup: runSpawnerCompletionCleanup,
    },
    // The forge lookup behind the Merge Gate contract check (#5876). Non-throwing:
    // a branch or PR probe that fails answers `null`, which the decision table
    // reads as "unreadable" and finalizes normally.
    probeMergeGatePr: async () => {
      const branchName = await git.getBranch(cwd).catch(() => null);
      if (!branchName) return null;
      return probePrForBranch(cwd, branchName).catch(() => null);
    },
  });

  // Repo-owner-pinned GH_TOKEN for the agent's own `gh pr create` (see
  // resolveForgeTokenEnv). Resolved here since createAgentTuiSession is sync.
  // Skip when the provider supplies its own GH_TOKEN/GITHUB_TOKEN so its explicit
  // credential wins — and skip for a public-content stage, which must never hold
  // a forge credential (the allowlist in createAgentTuiSession strips it anyway;
  // not resolving it means it is never read out of the keychain to begin with).
  const forgeTokenEnv = providerSuppliesGithubToken(provider) || isPublicReviewRestrictedProfile(safetyProfile)
    ? {}
    : await git.resolveForgeTokenEnv(cwd);

  // The loopback PortOS session token this agent's own `curl` snippets need when
  // the install has an instance password set (agentApiAuth.js). `buildSafeEnv`
  // allowlist-filters the inherited env for a login-shell PTY, so like GH_TOKEN
  // it only reaches the agent by riding the explicit delta below.
  const agentApiEnv = await resolveAgentApiEnv({ safetyProfile });

  // Ollama-backed harnesses talk to the daemon directly, so their context
  // window is whatever Ollama loaded the model at — no per-request `num_ctx`
  // reaches them. Hold the daemon at the provider's configured window (or warn
  // when it's below what an agent harness needs) BEFORE the TUI starts: the
  // failure mode otherwise is an hour of work lost to a 400 at 100% context.
  // Gated on the predicate here (not just inside the helper) so a cloud-provider
  // spawn — the overwhelmingly common case — takes no async hop at all.
  const ollamaContext = isOllamaBackedProvider(provider)
    ? await ensureOllamaAgentContext(provider, { model })
    : null;
  if (ollamaContext?.warning) appendLine(ollamaContext.warning);
  if (ollamaContext?.applied) appendLine(LIFECYCLE_LINES.ollamaContextApplied({ contextLength: ollamaContext.contextLength }));

  // A spawn failure here (a runner 400 for a command missing from its allowlist,
  // an unreachable runner, a PTY that won't open) used to propagate raw out of
  // spawnTuiAgent. The caller in subAgentSpawner only logs it, so the agent
  // record stayed `initializing` with the real error nowhere but the server log
  // until the zombie reaper finalized it ~a minute later as the generic "Agent
  // process terminated unexpectedly". Finalize it here instead, carrying the
  // spawn error into the record. Runs outside the Express request lifecycle, so
  // there is no middleware to bubble to.
  //
  // The REASON splits on which half failed. A durable-runner throw is a
  // runner-hop failure (a `fetch failed` mid-restart, or a runner refusal) —
  // no process ever existed, so it is `spawn-rejected` (non-actionable →
  // retry), mirroring the direct-CLI runner path's deliberate split in
  // agentLifecycle.js and the registration in COMPLETION_REASON_ANALYSES. A
  // LOCAL PTY that won't open keeps the actionable `spawn-error`: that is a
  // real host/config problem a retry cannot repair.
  let session;
  try {
    session = await createAgentTuiSession({
      agentId,
      taskId: task.id,
      provider,
      model,
      tuiConfig,
      cwd,
      forgeTokenEnv,
      agentApiEnv,
      doneSentinelPath,
      securityScanGrant,
      launchShape,
      safetyProfile,
      onData: (...args) => maintenance.withResource('agent', agentId, () => controller.handleData(...args)),
      onExit: (...args) => {
        if (args[0]?.killed !== true) maintenanceExited = true;
        const result = maintenance.withResource('agent', agentId, () => controller.handleExit(...args));
        settleMaintenance();
        return result;
      },
      onInitialCommandSent: controller.markCommandInjected,
    });
    // killSession removes the UI record and reports a synthetic exit. Readiness
    // additionally waits for node-pty/the runner to confirm physical exit.
    session.ptyProcess?.onExit?.(() => { maintenanceExited = true; settleMaintenance(); });
  } catch (err) {
    const message = err?.message || String(err);
    appendLine(LIFECYCLE_LINES.startFailed({ provider: provider.name || provider.id, message }));
    // The durable runner probes the configured executable before it opens a
    // PTY. Distinguish that deterministic configuration failure from a runner
    // outage/refusal so it is blocked with the existing actionable
    // command-not-found guidance rather than retried as a transient rejection.
    //
    // A LOCAL direct PTY raises the SAME failure with the same prefix — see the
    // pre-spawn resolve in createAgentTuiSession's restricted branch (#6159) —
    // so the test is no longer gated on the runner.
    //
    // An unusable PTY LAYER joins that actionable set for the same reason: it
    // reproduces on every attempt, so retrying it as a transient rejection burns
    // MAX_TASK_RETRIES on every task in the fleet and buries the one line naming
    // the repair (see lib/ptySpawnDiagnostics.js).
    //
    // The runner's OTHER named fault — a workspace that vanished — deliberately
    // does NOT join it. Each retry provisions a fresh worktree at a fresh path, so
    // a reaped one is exactly the transient case `spawn-rejected` exists for;
    // blocking on it would park work a retry fixes. A cwd that is missing because
    // it is misconfigured (a managed app whose directory is gone) still surfaces —
    // it fails identically every attempt and blocks on MAX_TASK_RETRIES carrying
    // the runner's message, which is that reason's documented behavior.
    const reason = /^Command executable unavailable:/i.test(message)
      ? 'command-not-found'
      : message.startsWith(PTY_UNAVAILABLE_PREFIX)
        ? 'runner-pty-unavailable'
        : useDurableRunner ? 'spawn-rejected' : 'spawn-error';
    if (useDurableRunner) {
      // A handoff that did not land (#4540), recorded like the CLI path's. A
      // LOCAL PTY that won't open is a host problem, not a handoff, so it is
      // deliberately not recorded here.
      //
      // `accepted: false` is reserved for an explicit refusal. An ambiguous
      // transport failure records the `null` sentinel instead — the spawn rpc
      // already asked the runner whether it has the PTY (and would have adopted
      // it), so what is unknown here is the CAUSE, not the outcome (#4615).
      const refused = classifyRunnerSpawnFailure(err) === RUNNER_SPAWN_REFUSED;
      await appendRunEvent({
        kind: 'run.handoff',
        runId,
        agentId,
        taskId: task.id,
        eventId: `handoff:${agentId}:${runId || 'no-run'}:${refused ? 'rejected' : 'unconfirmed'}`,
        data: {
          to: 'none',
          accepted: refused ? false : null,
          outcome: refused ? RUNNER_SPAWN_REFUSED : RUNNER_SPAWN_AMBIGUOUS,
          kind: 'tui',
          reason: message,
        },
      });
    }
    await controller.finish({
      success: false,
      exitCode: 1,
      error: `Failed to start TUI session: ${message}`,
      reason,
    });
    return null;
  }
  const sessionId = session.sessionId;
  if (useDurableRunner) {
    // A durable TUI's PTY lives in the CoS Runner, not this server — the same
    // ownership transfer `spawnViaRunner` records for CLI agents (#4540).
    // Without it, the longest-lived runs in the system are the only ones whose
    // ledger never says who owns their process.
    await appendRunEvent({
      kind: 'run.handoff',
      runId,
      agentId,
      taskId: task.id,
      eventId: `handoff:${agentId}:${runId || 'no-run'}:cos-runner`,
      data: {
        to: 'cos-runner',
        accepted: true,
        kind: 'tui',
        providerId: provider.id,
        sessionId: session.sessionId ?? null,
        // The handoff landed but its acknowledgement was lost; the relay was
        // re-attached to the PTY the runner already had (#4615).
        ...(session.adopted ? { outcome: RUNNER_SPAWN_AMBIGUOUS, adopted: true, reason: session.adoptedReason ?? null } : {}),
      },
    });
    if (session.adopted) {
      appendLine(LIFECYCLE_LINES.spawnAdopted({ reason: session.adoptedReason }));
      emitLog('warn', `TUI agent ${agentId} spawn acknowledgement was lost; adopted the live runner PTY`, { agentId, taskId: task.id });
    }
  }

  // A durable runner can emit tui:exit before its spawn POST response reaches
  // this process. The controller's handleExit then finalizes the run while
  // createAgentTuiSession is still awaiting that response. Do not revive the
  // finalized agent by registering its returned session, timers, or active-agent
  // record; release any external shell session the late response registered.
  if (controller.isTerminal()) {
    if (sessionId && shellService.getSession(sessionId)) shellService.killSession(sessionId);
    return null;
  }

  if (!sessionId) {
    await controller.finish({ success: false, exitCode: 1, error: 'Failed to create TUI shell session', reason: 'spawn-error' });
    return null;
  }

  const { ptyProcess, pid } = session;
  if (pid) {
    registerSpawnedAgent(pid, {
      fullCommand: tuiConfig.commandLine,
      agentId,
      taskId: task.id,
      model,
      workspacePath: cwd,
      prompt: (task.description || '').substring(0, 500)
    });
  }

  activeAgents.set(agentId, {
    process: ptyProcess || { kill: () => shellService.killSession(sessionId) },
    taskId: task.id,
    startedAt: Date.now(),
    runId,
    pid,
    providerId: provider.id,
    executionId,
    laneName,
    tuiSessionId: sessionId,
    refuseScanner: controller.refuseScanner,
  });

  // Arm prompt delivery, the provider-signal gates and the sentinel watcher.
  // AFTER the active-run entry exists: the controller's teardown reads that
  // record for the run's `startedAt`/`pid`, and a timer that fired between the
  // two would finalize against a record that wasn't there yet.
  controller.attachSession({ sessionId, pid });

  // Identify which TUI binary this session is running so consumers can gate
  // features that aren't universal — e.g. only Claude Code supports
  // bracketed-paste injection of post-spawn BTW messages; codex/gemini/lm-studio
  // TUIs don't.
  const tuiKind = tuiConfig.spawnCommand.split('/').pop().toLowerCase();
  await updateAgent(agentId, {
    pid,
    metadata: {
      phase: 'working',
      executionMode: useDurableRunner ? 'runner-tui' : 'tui',
      tuiSessionId: sessionId,
      tuiCommand: tuiConfig.commandLine,
      tuiKind,
    }
  });

  appendLine(LIFECYCLE_LINES.sessionStarted({ session: sessionId.slice(0, 8), commandLine: tuiConfig.commandLine }));
  appendLine(LIFECYCLE_LINES.shellTabHint());
  return agentId;
}