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

66.8 KB
Raw Blame
import { maintenance } from '../lib/maintenanceAdmission.js';
/**
 * One-shot TUI prompt runner.
 *
 * Spawns a TUI binary (Claude Code, Codex, Antigravity, etc.) in a PTY, waits for
 * the prompt cursor to become input-ready, bracketed-pastes the prompt + Enter,
 * watches for the model response to complete via sustained output-idle, then
 * strips ANSI and returns the captured text. Persists a run record under
 * `data/runs/<runId>/` so /runs can replay TUI invocations alongside CLI/API.
 *
 * Distinct from `server/services/agentTuiSpawning.js` — that path wraps
 * long-running CoS agents (worktree, /simplify, /do:pr, .agent-done sentinel).
 * This is the synchronous "send prompt, get text back" variant the central
 * promptRunner needs when `provider.type === 'tui'`.
 *
 * Spawning bypasses `services/shell.js` deliberately:
 *   - shellService caps interactive sessions, which the central handler can
 *     exceed easily (arc planner fans out parallel calls). We still *register*
 *     the spawned PTY as an external view afterward (see below) — that path is
 *     exempt from the cap, so surfacing the run doesn't re-introduce the limit.
 *   - shellService wraps a login shell around the TUI; pasting `${cmd}\n`
 *     into a zsh prompt is slower and noisier than spawning the TUI directly.
 *
 * Completion detection, in priority order: the model's response-file write
 * is the authoritative "done" signal (the wrapped prompt directs it to write
 * its full answer to `tui-response.txt` and then finish) — checked
 * unconditionally, even while a human watches. Output-idle is the fallback for
 * TUIs that print inline instead of writing the file (paused while watched, so
 * a viewer isn't snapped shut mid-read). Codex is excluded from that fallback:
 * its status chrome can go silent for long stretches during real reasoning,
 * and the required response file is the only safe completion signal. The hard
 * timeout is the backstop, and salvages an already-written file before failing.
 * Per-binary input-prompt
 * regexes were considered for idle but are fragile across versions and screen
 * sizes; for non-Codex TUIs, the idle threshold (~8s) remains the pragmatic
 * inline-output fallback.
 */

import { spawn as ptySpawn } from 'node-pty';

import { basename, isAbsolute, join, resolve } from 'path';
import { access } from 'node:fs/promises';
import { ensureDir, PATHS, tryReadFile } from '../lib/fileUtils.js';
import { createStreamingAnsiStripper, stripAnsi } from '../lib/ansiStrip.js';
import {
  createClaudeSessionLimitBannerDetector,
  createContentRefusalDetector,
  createImmediateFallbackSignalDetector,
  createTerminalModelErrorDetector,
  createTerminalRequestTimeoutDetector,
} from '../lib/aiToolkit/errorDetection.js';
import { getRunsPath, finalizeRunRecord, failRunRecord, emitRunStarted, registerActiveRun, unregisterActiveRun, consumeRunStopRequested, resolveRunCwd } from './runner.js';
import { registerExternalSession, unregisterExternalSession, isExternalSessionAttached, pasteToSession } from './shell.js';
import { isHostShuttingDown } from '../lib/hostShutdown.js';
import { findCommandOnPath } from '../lib/processEnv.js';
import {
  DEFAULT_TUI_PROMPT_DELAY_MS,
  PASTE_MARKER_POLL_MS,
  countPasteMarkers,
  isPasteCommitted,
  PASTE_TO_ENTER_MIN_DELAY_MS,
  PASTE_TO_ENTER_FALLBACK_MS,
  scheduleSubmitEnters,
  SELF_CLEARING_RESUBMIT_POLL_MS,
  PASTE_DEADLINE_MS,
  TUI_INPUT_READY_DEADLINE_MS,
  READY_POLL_INTERVAL_MS,
  READY_IDLE_THRESHOLD_MS,
  OUTPUT_BUFFER_CAP,
  OUTPUT_BUFFER_HEADROOM,
  RAW_BUFFER_CAP,
  RAW_BUFFER_HEADROOM,
  CLAUDE_LOW_PRIORITY_RESUBMIT_DELAY_MS,
  buildTuiInvocation,
  createInputReadyTracker,
  OPENCODE_INPUT_READY_PATTERN,
  detectMissingTuiBinary,
  createSelfClearingSignalGate,
  createPromptSubmissionGate,
  screenShowsInFlightChrome,
  SUBMIT_KEY,
  UNSUBMITTED_PROMPT_ENTER_MAX_ATTEMPTS,
} from '../lib/tuiHandshake.js';
import { buildCliChildEnv } from '../lib/cliChildEnv.js';
import { isCodexCommand } from '../lib/codex.js';
import { isClaudeCommand, isOpencodeCommand } from '../lib/providerModels.js';
import { applyCredentialBootstrap, needsProcessGroup, processGroupKillable } from '../lib/credentialBootstrap.js';
import { killProcessTree } from '../lib/bufferedSpawn.js';

// One-shot defaults that don't apply to the long-running agent path:
//   - hard run cap (5 min vs unbounded for agents)
//   - response-complete idle threshold (8s vs 180s for agents — agents wait
//     out tool calls + /simplify + /do:pr, we're just waiting for the model
//     to stop talking)
const DEFAULT_TIMEOUT_MS = 300000;
const DEFAULT_ONE_SHOT_IDLE_MS = 8000;
const UNSUBMITTED_PROMPT_POLL_MS = 1000;
// A one-shot answer can be short, quick and free of in-flight chrome (OpenCode).
// The agent path's 30s echo window would read it as an ignored submit and hold
// idle completion for the whole Enter budget. An ignored Enter repaints nothing,
// so output this long after PortOS's last keystroke means the turn ran.
const ONE_SHOT_PROMPT_WORK_EVIDENCE_MS = 2500;
// Enough stripped screen to hold a status line plus the composer and footer
// painted beneath it; see screenShowsInFlightChrome.
const IN_FLIGHT_SCREEN_TAIL_CHARS = 4096;

// A one-shot prompt must return one machine-consumed answer. Codex's general
// interactive TUI inherits the user's multi-agent feature flag, which can turn
// that bounded request into agent fan-out + wait loops that consume the entire
// timeout before the fallback provider repeats the work. Long-running CoS
// agents use agentTuiSpawning.js and keep their configured collaboration
// posture; only this synchronous prompt runner pins the feature off.
function buildOneShotTuiArgs(command, args) {
  if (!isCodexCommand(command)) return args;
  const alreadyDisabled = args.some((arg, index) => (
    arg === '--disable=multi_agent'
    || (arg === '--disable' && args[index + 1] === 'multi_agent')
    || (arg === '-c' && args[index + 1] === 'features.multi_agent=false')
  ));
  return alreadyDisabled ? args : [...args, '--disable', 'multi_agent'];
}

// Wide PTY so TUI doesn't wrap responses at narrow widths, which makes
// downstream parsing harder.
const PTY_COLS = 200;
const PTY_ROWS = 50;

/**
 * Run a single prompt through a TUI provider. Mirrors the signature of
 * `executeCliRun` / `executeApiRun` so the central handler treats all three
 * branches uniformly (a single options object).
 *
 * Caller (typically `runPromptThroughProvider`) owns the run record:
 *   - `createRun` (toolkit) writes the initial metadata.json + prompt.txt
 *   - this function writes output.txt and finalizes metadata.json on exit
 *     via `runner.js#finalizeRunRecord`, so /runs shows TUI runs with the
 *     same success/exitCode/duration shape as CLI runs.
 *
 * @param {object} options
 * @param {string} options.runId — pre-created run id (from createRun).
 * @param {object} options.provider — { id, type: 'tui', command, args, envVars,
 *   tuiPromptDelayMs?, tuiOneShotIdleMs?, timeout?, defaultModel? }. The
 *   model passed to `--model` is taken from `provider.defaultModel`; per-
 *   call overrides are applied by the central handler via a provider clone
 *   before this function is reached.
 * @param {string} options.prompt — full text to paste into the TUI.
 * @param {string} options.workspacePath — working directory for the spawned TUI.
 * @param {(chunk: string) => void} [options.onData] — incremental ANSI-stripped
 *   output stream.
 * @param {(meta: object) => void} [options.onComplete] — fired after exit with
 *   `{ exitCode, duration, success, error?, model? }`. Promise resolves
 *   AFTER this fires.
 * @param {number} [options.timeout] — hard cap on a single run (ms). Falls back to
 *   `provider.timeout`, then `DEFAULT_TIMEOUT_MS`.
 * @param {number} [options.idleMs] — response-complete idle threshold (ms) for
 *   THIS call, overriding `provider.tuiOneShotIdleMs` and the 8s default. The
 *   default suits a chatty text reply that goes quiet within seconds; a task
 *   that streams sparse output during a long operation (e.g. a multi-minute
 *   grok `image_to_video` render) needs a larger value so a mid-work lull isn't
 *   mistaken for completion. Pair with a larger `timeout`.
 * @param {string} [options.label] — human label for the live Shell view (the
 *   run `source`, e.g. `'pipeline-manuscript-completeness'`). Surfaced in the
 *   Shell page's session tab; falls back to `command · model` when absent.
 * @param {boolean} [options.guard=false] — prepend the PM2 guard shim for an
 *   autonomous task that must not be able to kill the shared PortOS daemon.
 * @param {boolean} [options.reportFailure=true] — fire the host's `onRunFailed`
 *   hook when the run fails. Pass `false` for a deliberate PROBE of a provider
 *   (the local-model benchmark): its failure is the caller's measurement, which
 *   it reports itself, not a provider incident for the autofixer to escalate.
 * @returns {Promise<void>}
 */
export async function executeTuiRun(options) {
  const permit = maintenance.admit('tui-run', options.runId, { continuation: true });
  const lifecycle = { spawned: false, exited: false, cleaned: false,
    settle() { if (this.cleaned && (!this.spawned || this.exited)) return permit.finish(); } };
  try { return await permit.run(() => executeAdmittedTuiRun(options, lifecycle)); }
  catch (err) { if (lifecycle.spawned) permit.markUnsettled(); throw err; }
  finally { lifecycle.cleaned = true; await lifecycle.settle(); }
}

async function executeAdmittedTuiRun({ runId, provider, prompt, screenshots = [], workspacePath, onData, onComplete, onReady, timeout, idleMs, label, guard = false, reportFailure = true, beforeExecute }, maintenanceLifecycle) {
  if (!provider || typeof provider !== 'object') {
    throw new Error('executeTuiRun: provider is required');
  }
  if (typeof prompt !== 'string' || !prompt) {
    throw new Error('executeTuiRun: prompt must be a non-empty string');
  }

  const invocation = buildTuiInvocation(provider, provider.defaultModel);
  const { command } = invocation;
  const args = buildOneShotTuiArgs(command, invocation.args);
  if (screenshots.length > 0) {
    if (!isCodexCommand(command)) throw new Error('This TUI provider cannot receive image attachments');
    for (const screenshot of screenshots) {
      if (typeof screenshot !== 'string' || !screenshot) throw new Error('Invalid screenshot path');
      const imagePath = isAbsolute(screenshot) ? screenshot : resolve(PATHS.screenshots, basename(screenshot));
      await access(imagePath);
      args.push('--image', imagePath);
    }
  }
  // `command`/`args` keep naming the harness itself — every heuristic below
  // (isCodexCommand, isClaudeCommand, ready-text detection) keys off them by
  // identity. `spawnCommand`/`spawnArgs` are what actually gets launched: the
  // bootstrap CLI in front of the harness invocation for a credential-
  // bootstrap-configured provider (see credentialBootstrap.js), or an
  // identical copy otherwise.
  const { command: spawnCommand, args: spawnArgs, wrapped } = applyCredentialBootstrap(provider, command, args);
  // When the wrap applied, the PTY's direct child is the bootstrap WRAPPER and
  // node-pty's `kill()` signals that pid alone, so a cancel/timeout would leave
  // the harness running (#7496). forkpty already makes the PTY child a session
  // leader whose descendants share its process group, so signalling the group is
  // exact. False — and byte-identical to today — for every unwrapped provider.
  const processGroup = needsProcessGroup(wrapped);
  // 'SIGHUP' is node-pty's own POSIX default for `kill()`; naming it explicitly
  // keeps the signal identical while letting killProcessTree take the group path.
  const killPty = (target) => killProcessTree(target, 'SIGHUP', { processGroup });
  // Deliberately NOT `trackDetachedGroup`ed, unlike the headless spawn sites.
  // That registry exists because `detached: true` moves a child OUT of the
  // server's process group; forkpty already put this PTY in its own session for
  // every provider, wrapped or not, so nothing was lost here to restore. Adding
  // it would instead start killing TUI runs on a host restart that pm2 already
  // tree-kills — and that `hostShutdown.js` deliberately preserves as
  // INTERRUPTED for the next boot's recovery rather than terminating (#3202).
  const promptDelayMs = provider.tuiPromptDelayMs ?? DEFAULT_TUI_PROMPT_DELAY_MS;
  const idleThresholdMs = idleMs ?? provider.tuiOneShotIdleMs ?? DEFAULT_ONE_SHOT_IDLE_MS;
  const totalTimeoutMs = timeout ?? provider.timeout ?? DEFAULT_TIMEOUT_MS;
  // Codex is explicitly instructed to write the machine-consumed answer to a
  // response file. Its PTY may stop repainting for many seconds or minutes
  // while the model is still reasoning; treating that quiet screen as a final
  // inline answer kills the live request and returns terminal chrome such as
  // "[Pasted Content …]" to JSON parsers. Wait for the authoritative file,
  // natural process exit, explicit cancellation, or the configured hard cap.
  // Unbounded calls likewise cannot infer completion from a quiet screen.
  const requiresResponseFileForIdleCompletion = totalTimeoutMs === 0 || isCodexCommand(command);
  // Mirror runner.js#executeCliRun's runs-path resolution so TUI runs land
  // under the runner-config dataDir (not always PATHS.runs) — otherwise a
  // non-default dataDir would split metadata + output across two trees.
  const runDir = join(getRunsPath(), runId);
  await ensureDir(runDir);

  // Who this run is, for a finalize that finds no `createRun` metadata on disk
  // to merge into. Mirrors `emitRunStarted`'s naming so the started and failed
  // events describe the same run — they used to disagree, and the failure event
  // was the anonymous one.
  const runIdentity = {
    providerId: provider.id,
    providerName: provider.name || provider.id,
    model: provider.defaultModel,
  };

  // Logs the effective cwd, and rejects a workspace that was requested but is
  // missing on disk instead of silently spawning in the PortOS root (#3180).
  // Sequenced after ensureDir so finalizeRunRecord has a run dir to write into.
  const { cwd: workingDir, failure } = await resolveRunCwd({
    runId, workspacePath, label: `TUI run ${runId}`, onData, onComplete, identity: runIdentity, reportFailure,
  });
  if (failure) return failure;

  // TUI screens redraw their banner, input chrome, and status bar on every
  // keystroke — scraping the PTY stream for the model's reply is
  // fundamentally lossy (box-drawing chars, "5%" cost meters, "bypass
  // permissions on" hints, etc. all bleed into the captured text). Ask the
  // model to write its final response to a file we'll read back instead.
  //
  // `resolve()` is load-bearing: `runnerConfig.dataDir` defaults to the
  // relative `'./data'`, and the TUI's cwd (`workingDir`) is frequently a
  // different directory (universe/loop workspaces, target-app paths). A
  // relative path embedded in the prompt would tell the LLM to write into
  // its own cwd while the server reads from process.cwd() — different
  // files, fallback every time.
  const responseFilePath = resolve(runDir, 'tui-response.txt');
  const wrappedPrompt = `IMPORTANT — Output to file:
When you have completed the task below, write your COMPLETE final response (and nothing else — no commentary, preamble, or wrapper text) to this exact absolute path using your file-writing tool:

    ${responseFilePath}

Only the contents of that file will be used as your response, so do not print the response inline. Once the file is written, you can finish.

----- TASK -----

${prompt}`;

  console.log(`📟 Executing TUI: ${command} ${args.join(' ')} (${wrappedPrompt.length} chars via paste, response→${responseFilePath})`);

  // Markers already present in the (wrapped) prompt itself — a transcript-analysis
  // task can echo `[Pasted text #N]` back into the post-paste stream. The fast
  // path must wait for the TUI's OWN marker (the count to EXCEED this), so an
  // echoed marker doesn't fire the submit-Enter mid-reflow (issue #1229 review).
  // STRIP first so a pasted RAW transcript's cursor-positioned marker (counts as 0
  // unstripped) is counted the same way the stripped post-paste buffer is.
  const promptMarkerCount = countPasteMarkers(stripAnsi(wrappedPrompt));
  // The paste chip can render and every submit Enter still be ignored, leaving
  // the prompt sitting in the composer (#12769). Shared with the agent path.
  const promptGate = createPromptSubmissionGate({ promptMarkerCount, workEvidenceMs: ONE_SHOT_PROMPT_WORK_EVIDENCE_MS });

  // Shared composition (provider.envVars + OpenCode models map + PWD pin +
  // CLAUDECODE strip) — see buildCliChildEnv. The PWD pin matters here because
  // this PTY runs the CLI directly, so there is no login shell to rewrite PWD
  // for us. TERM/COLORTERM go in `extra` so they override any provider setting —
  // the PTY is always a truecolor xterm regardless of provider config. No
  // `guard`: this is a Run Prompt TUI, not an autonomous agent.
  const childEnv = buildCliChildEnv({
    provider,
    cwd: workingDir,
    guard,
    extra: { TERM: 'xterm-256color', COLORTERM: 'truecolor' },
  });

  // A PTY has no shell to print "command not found": node-pty forks, `execvp`
  // fails in the child, and the child exits 1 with an EMPTY screen. So the
  // output-driven `detectMissingTuiBinary` probe further down can never fire on
  // this path, and the run finalized as a bare `TUI exited with code 1` — no
  // provider, no cause, nothing to act on. Resolve against the CHILD's PATH
  // (`childEnv`, since a provider may override PATH with only its own bin dir)
  // and report the real reason with the 127 that probe already uses.
  if (!findCommandOnPath(spawnCommand, { env: childEnv, cwd: workingDir })) {
    return failRunRecord({
      runId,
      error: `TUI command not found: ${spawnCommand}`,
      exitCode: 127,
      startTime: Date.now(),
      onData,
      onComplete,
      identity: runIdentity,
      reportFailure,
    });
  }

  let ptyProcess;
  if (beforeExecute) {
    try { await beforeExecute(); }
    catch (error) {
      await finalizeRunRecord({ runId, output: '', exitCode: 1, success: false, error: error.message, startTime: Date.now(),
        extras: { canceled: true, completionReason: 'canceled' }, identity: runIdentity });
      throw error;
    }
  }
  try {
    ptyProcess = ptySpawn(spawnCommand, spawnArgs, {
      name: 'xterm-256color',
      cols: PTY_COLS,
      rows: PTY_ROWS,
      cwd: workingDir,
      env: childEnv,
    });
  } catch (err) {
    throw new Error(`Failed to spawn TUI '${spawnCommand}': ${err.message}`);
  }

  // Subscribe to exit IMMEDIATELY after spawn. A CLI can fail before its first
  // paint (bad local config, an early runtime crash, etc.); the rest of this
  // function registers the run, Shell view, and completion machinery before it
  // used to attach onExit. node-pty does not replay an already-delivered exit,
  // so that small window stranded the run until its hard timeout. Queue the
  // one exit event until finish() and the timers below are ready, then replay it
  // through the ordinary exit path. This is a startup/lifecycle guard, not an
  // output-idle timeout: a live but quiet model remains untouched.
  maintenanceLifecycle.spawned = true;
  let dispatchPtyExit = null;
  let pendingPtyExit = null;
  ptyProcess.onExit((event) => {
    maintenanceLifecycle.exited = true;
    maintenanceLifecycle.settle();
    if (dispatchPtyExit) {
      dispatchPtyExit(event);
      return;
    }
    pendingPtyExit = pendingPtyExit || event;
  });

  // Register in the same active-runs map the patched stopRun/isRunActive
  // consult, so /runs UI can stop a hung TUI run. Without this, stopRun is a
  // no-op for TUI and isRunActive returns false — the PTY keeps spending
  // tokens with no way to cancel from the UI. Mirrors executeCliRun's
  // registration of its ChildProcess; node-pty's IPty exposes the same
  // .kill(signal?) interface so the patched stopRun works unchanged.
  // A group-aware killable for a wrapped PTY: the toolkit's own self-contained
  // killProcessTree has no processGroup option, so /runs Stop would otherwise
  // signal the wrapper alone. Unwrapped runs register the raw IPty as before.
  registerActiveRun(runId, processGroupKillable(ptyProcess, processGroup));

  // Fire the toolkit's `onRunStarted` hook now that the PTY is alive — the
  // CLI/API paths fire it inside the toolkit's executeCliRun/executeApiRun,
  // but the TUI path doesn't go through those. Without this hook, /runs and
  // any SSE-based "active run" UI never see TUI runs as in-flight.
  emitRunStarted({ runId, provider, model: provider.defaultModel });

  // Surface this one-shot run as an interactive session in the Shell UI so the
  // user can watch its live output and step in — answer a question, correct it,
  // or interrupt it (it bypasses services/shell.js for *spawning*, but
  // registering the already-live PTY for *viewing/driving* doesn't re-introduce
  // the cap/login-shell concerns the spawn bypass avoids).
  const viewLabel = (typeof label === 'string' && label)
    ? label
    : `${command} · ${provider.defaultModel || 'tui'}`;
  registerExternalSession(runId, ptyProcess, {
    label: viewLabel,
    command: `${command} ${args.join(' ')}`.trim(),
    cwd: workingDir,
    kind: 'tui-run',
  });
  try {
    onReady?.({
      runId,
      providerId: provider.id,
      providerName: provider.name || provider.id,
      model: provider.defaultModel,
      providerType: provider.type,
      shellReady: true,
    });
  } catch (err) {
    console.error(`❌ TUI ready hook failed: ${err.message}`);
  }

  const startTime = Date.now();
  let outputBuffer = '';
  let rawBuffer = '';
  let promptSentAt = null;
  let promptSubmittedAt = null;
  // ANSI-stripped post-paste accumulator for paste-marker detection. The marker
  // renders with absolute-column cursor moves between glyphs, so it only matches
  // after stripping — testing the raw stream never matched and left the fast
  // path dead (issue #1229). Lives only during the paste→Enter window; nulled
  // when detection resolves or the run finalizes.
  let postPasteStripped = null;
  let firstOutputAt = null;
  let lastOutputAt = startTime;
  let firstResponseAt = null;
  let finalized = false;
  const detectImmediateFallbackSignal = createImmediateFallbackSignalDetector();
  const detectContentRefusal = createContentRefusalDetector();
  const detectClaudeSessionLimitBanner = createClaudeSessionLimitBannerDetector();
  const mayUseClaudeLowPriority = provider.type === 'tui'
    && provider.lowPriorityOnUsageLimit === true
    && isClaudeCommand(command);
  let lowPriorityCommandAttempted = false;
  let lowPriorityPromptResubmitted = false;
  // One-shot-only: a terminal model-id rejection (Bedrock 400 / Anthropic 404)
  // leaves the TUI idle at an unanswered prompt, so without this the run idles to
  // a false success and the error screen is scraped as the "response". Scoped here
  // (not in the shared fallback detector) so it can't kill a long-running agent
  // that merely echoes the error line — see errorDetection.js for the rationale.
  const detectTerminalModelError = createTerminalModelErrorDetector();
  // Claude Code can exhaust all of its own request retries and then exit 0 with
  // only `⎿ Request timed out` on screen. This one-shot-only detector lets the
  // central runner fall back instead of parsing that terminal as creative output.
  const detectTerminalRequestTimeout = createTerminalRequestTimeoutDetector();
  // True once outputBuffer overflowed OUTPUT_BUFFER_HEADROOM and the head was
  // dropped. We warn once and surface it in the run record so /runs can flag
  // responses where the fallback path may have lost the start.
  let outputBufferTruncated = false;

  const streamingStrip = createStreamingAnsiStripper();
  // This PTY spawns the TUI directly, so the TUI's first paste-mode ON is the
  // positive ready signal for Claude. OpenCode also requires its composer
  // placeholder and a settled repaint; terminal queries alone are not ready.
  const isOpencodeSession = isOpencodeCommand(command);
  const inputReady = createInputReadyTracker({
    launchShape: 'direct',
    ...(isOpencodeSession ? { readyTextPattern: OPENCODE_INPUT_READY_PATTERN } : {}),
  });
  const requiresInputReady = isClaudeCommand(command) || isOpencodeSession;
  // Keep local one-shot flags alongside the tracker's terminal acknowledgements
  // so a failed/delayed PTY write cannot cause repeated selector navigation.
  let trustAccepted = false;
  let hookReviewDeclined = false;

  // The wrapped prompt directs the model to write its COMPLETE response to
  // `responseFilePath` and then finish. That file appearing is the model's
  // explicit "done" signal — more reliable than output-idle and, unlike idle,
  // authoritative even while a human watches (the task is finished; there's
  // nothing left to intervene in). Returns true once the file has non-empty
  // content whose length held steady across two consecutive polls (~1s apart),
  // so a half-flushed write isn't read as complete. `lastResponseLen = -1`
  // means "not yet seen / reset"; a real reading seeds it and the next equal
  // reading confirms stability.
  let lastResponseLen = -1;
  const responseFileSettled = async () => {
    const txt = await tryReadFile(responseFilePath);
    if (typeof txt !== 'string' || !txt.trim()) { lastResponseLen = -1; return false; }
    if (txt.length === lastResponseLen) return true;
    lastResponseLen = txt.length;
    return false;
  };
  // Stability doesn't apply once nothing can still be writing (hard timeout with
  // the TUI wedged, or the PTY already gone): non-empty content is the whole
  // answer by then.
  const responseFileHasContent = async () => {
    const txt = await tryReadFile(responseFilePath);
    return typeof txt === 'string' && !!txt.trim();
  };

  let readyTimer = null;
  let pasteEnterTimer = null;
  let submitEnterTimer = null;
  let unsubmittedPromptTimer = null;
  let idleWatchTimer = null;
  let responseFileWatchTimer = null;
  let hardTimeoutTimer = null;
  let claudeLowPriorityResubmitTimer = null;
  // Holds the wait-it-out window for a provider signal carrying a `graceMs`
  // (agy's account-eligibility banner). Unlike the long-running agent path this
  // needs its OWN timer: `idleWatchTimer` is created lazily on the first
  // post-prompt chunk and may not exist yet when the banner paints.
  let selfClearingTimer = null;
  // Re-sends the prompt on a cadence while that window is open (the banner is a
  // REJECTION, not a spinner — see resubmitAfterSignal).
  let selfClearingResubmitTimer = null;
  const selfClearingGate = createSelfClearingSignalGate();
  // The deadline and its retry poll are armed together and always die together —
  // on recovery, at expiry, and on any finish.
  const stopSelfClearingTimers = () => {
    if (selfClearingTimer) { clearTimeout(selfClearingTimer); selfClearingTimer = null; }
    if (selfClearingResubmitTimer) { clearInterval(selfClearingResubmitTimer); selfClearingResubmitTimer = null; }
  };

  const cleanupTimers = () => {
    // Stop the post-paste accumulator from growing on any chunk that lands
    // between finalize and the PTY kill (onData here has no finalized guard).
    postPasteStripped = null;
    if (readyTimer) { clearInterval(readyTimer); readyTimer = null; }
    if (pasteEnterTimer) { clearInterval(pasteEnterTimer); pasteEnterTimer = null; }
    if (submitEnterTimer) { clearInterval(submitEnterTimer); submitEnterTimer = null; }
    if (unsubmittedPromptTimer) { clearInterval(unsubmittedPromptTimer); unsubmittedPromptTimer = null; }
    if (idleWatchTimer) { clearInterval(idleWatchTimer); idleWatchTimer = null; }
    if (responseFileWatchTimer) { clearInterval(responseFileWatchTimer); responseFileWatchTimer = null; }
    if (hardTimeoutTimer) { clearTimeout(hardTimeoutTimer); hardTimeoutTimer = null; }
    if (claudeLowPriorityResubmitTimer) { clearTimeout(claudeLowPriorityResubmitTimer); claudeLowPriorityResubmitTimer = null; }
    stopSelfClearingTimers();
  };

  return new Promise((resolve) => {
    const finish = async ({ success, exitCode = 0, error = null, reason = 'completed', canceled = false, errorAnalysis = null }) => {
      if (finalized) return;
      finalized = true;
      // Tracks whether the normal-path onComplete was reached, so the catch
      // below re-surfaces failure ONLY when a step BEFORE onComplete threw —
      // never re-invoking onComplete when onComplete itself was the throw
      // source (that would violate the once-only completion contract).
      let onCompleteInvoked = false;
      // finish() is invoked fire-and-forget from PTY/timer callbacks outside the
      // request lifecycle (onData, onExit, sendPrompt's write-catch,
      // responseFileWatchTimer, hardTimeoutTimer) — none of them await or
      // .catch() this call. try/finally guarantees `resolve` below always fires
      // exactly once even if a step throws (including the caller-supplied
      // `onComplete` callback), so executeTuiRun's Promise can never hang forever.
      try {
        cleanupTimers();
        unregisterActiveRun(runId);
        // Drop the live Shell view the moment the run ends (notifies any attached
        // viewer via shell:exit). Idempotent — safe even if no viewer ever
        // attached. Runs before the kill below so the session disappears from the
        // list immediately rather than waiting on PTY teardown.
        unregisterExternalSession(runId, { exitCode });

        // Kill the PTY if still alive — one-shot runs don't leave a session
        // behind for the user to interact with.
        try { if (ptyProcess && !ptyProcess.killed) killPty(ptyProcess); } catch { /* already gone */ }

        // Prefer the response file the TUI was directed to write; fall back
        // to the ANSI-stripped screen scrape when the file is missing/empty
        // or the run didn't succeed. Logic lives in `resolveTuiResponseText`
        // so it can be unit-tested without a live PTY.
        const { text: responseText, usedResponseFile } = await resolveTuiResponseText({
          success, responseFilePath, outputBuffer, wrappedPrompt,
        });

        // Delegate run-record finalization (output.txt + metadata.json merge
        // + onRunCompleted/onRunFailed hooks + toolkit error analysis) to the
        // shared runner helper. `completionReason` lands in `extras` so it
        // gets persisted to metadata.json BEFORE the write (was previously
        // set post-write and never made it to disk → /runs replay missed it).
        const metadata = await finalizeRunRecord({
          runId, output: responseText, exitCode, success, error, startTime,
          identity: runIdentity,
          reportFailure,
          extras: {
            completionReason: reason,
            ...(errorAnalysis ? { errorAnalysis, executionInterruption: { category: errorAnalysis.category, source: 'provider' } } : {}),
            usedResponseFile,
            outputTruncated: outputBufferTruncated,
            ...(canceled ? { canceled: true } : {}),
          },
        }).catch((err) => {
          maintenance.markCurrentUnsettled();
          console.error(`❌ TUI run ${runId} finalize failed: ${err.message}`);
          return {
            exitCode, success, error: error || err.message,
            duration: Date.now() - startTime, completionReason: reason,
            ...(errorAnalysis ? { errorAnalysis } : {}),
            ...(canceled ? { canceled: true } : {}),
          };
        });
        onCompleteInvoked = true;
        onComplete?.({ ...metadata, text: responseText, usedResponseFile, outputTruncated: outputBufferTruncated });
      } catch (err) {
        maintenance.markCurrentUnsettled();
        console.error(`❌ TUI run ${runId} finish() failed: ${err?.message || err}`);
        // Ensure the original PTY is torn down even when a cleanup step BEFORE
        // the kill above threw (e.g. unregisterExternalSession). Otherwise the
        // failure we report below rejects executeProviderRunOnce and spins up a
        // fallback provider while the original PTY keeps running — two live runs
        // for one request. Idempotent: no-op if the kill above already fired.
        try { if (ptyProcess && !ptyProcess.killed) killPty(ptyProcess); } catch { /* already gone */ }
        // A step BEFORE onComplete threw, so the caller's onComplete-driven
        // settle never fired. executeProviderRunOnce (promptRunner.js) settles
        // its OUTER Promise only via onComplete (→ safeReject) or the returned
        // promise rejecting — and our try/finally always resolves (never
        // rejects), so `.catch(safeReject)` won't fire either. Without this,
        // resolving the inner promise leaves the central-prompt/pipeline caller
        // pending forever — the exact hang this patch exists to prevent. Deliver
        // failure metadata so onComplete → safeReject settles the caller. Skip
        // this when onComplete itself was the throw source (onCompleteInvoked) —
        // re-invoking it would break the once-only completion contract and could
        // emit a contradictory success-then-failure. Guard the callback so a
        // throw here doesn't escape finish() (un-awaited → unhandled rejection)
        // and still fall through to resolve().
        if (!onCompleteInvoked) {
          try {
            onComplete?.({
              runId, success: false, exitCode, error: `finish() failed: ${err?.message || err}`,
              duration: Date.now() - startTime, completionReason: reason,
              ...(errorAnalysis ? { errorAnalysis } : {}),
              ...(canceled ? { canceled: true } : {}),
            });
          } catch (cbErr) {
            console.error(`❌ TUI run ${runId} onComplete threw during finish() error handling: ${cbErr?.message || cbErr}`);
          }
        }
      } finally {
        resolve();
      }
    };

    // A fallback signal means "this provider can't finish the job" — but the
    // model may have ALREADY finished it. responseFileWatchTimer only finalizes
    // after two 1s polls agree on the file size, so there is a ≥1s window where
    // the response file is complete on disk and the run hasn't finalized. A
    // signal painting inside that window used to finish({ success: false }),
    // and since resolveTuiResponseText only reads the file when `success` is
    // true, the finished response was discarded, the ANSI-stripped error screen
    // was returned in its place, and a fallback tier re-ran an expensive stage
    // (#3715). Check for a usable response file first — the same salvage net the
    // hard-timeout path already has. While the PTY is alive the file must be
    // size-stable (it could still be mid-write); once the process has exited
    // nothing can still be writing, so non-empty is enough.
    const finishWithFallbackSignal = async (signal, { processExited = false } = {}) => {
      const salvaged = processExited
        ? await responseFileHasContent()
        : await responseFileSettled();
      if (finalized) return;
      if (salvaged) {
        console.log(`📄 TUI run ${runId} salvaged its completed response file despite a fallback signal: ${signal.message}`);
        await finish({ success: true, exitCode: 0, reason: 'fallback-signal-response-file' });
        return;
      }
      await finish({
        success: false,
        exitCode: signal.exitCode ?? 1,
        error: signal.message || 'Provider requires fallback',
        reason: 'fallback-signal',
      });
    };

    ptyProcess.onData((data) => {
      // One clock reading for the whole chunk — the grace-window bookkeeping
      // below and the idle/response timestamps at the end all want the same
      // instant, and this runs on every PTY chunk of every run.
      const now = Date.now();
      const text = data.toString();
      rawBuffer += text;
      if (rawBuffer.length > RAW_BUFFER_HEADROOM) rawBuffer = rawBuffer.slice(-RAW_BUFFER_CAP);

      const stripped = streamingStrip(text);
      const refusal = isCodexCommand(command) && promptSubmittedAt ? detectContentRefusal(text) : null;
      if (refusal) {
        void finish({ success: false, exitCode: 1, error: refusal.message,
          reason: 'content-refusal', errorAnalysis: refusal });
        return;
      }

      // The readiness tracker needs both streams: bracketed-paste transitions
      // survive only in raw output, while startup dialog text is ANSI-stripped.
      inputReady.observe(text, stripped);
      if (stripped) {
        promptGate.observe(stripped, now);
        if (postPasteStripped !== null) postPasteStripped += stripped;
        outputBuffer += stripped;
        if (outputBuffer.length > OUTPUT_BUFFER_HEADROOM) {
          outputBuffer = outputBuffer.slice(-OUTPUT_BUFFER_CAP);
          if (!outputBufferTruncated) {
            outputBufferTruncated = true;
            console.warn(`⚠️ TUI run ${runId} output buffer exceeded ${Math.round(OUTPUT_BUFFER_HEADROOM / 1024 / 1024)}MB — head dropped (response file is the authoritative path; fallback may be incomplete)`);
          }
        }
        onData?.(stripped);

        // While a grace window is open, every chunk is evidence about whether the
        // provider came back; the gate closes itself the moment it is, which also
        // lifts the idle suppression below instead of holding it to the deadline.
        // The clock is load-bearing — it lets the gate discount the echo of a
        // prompt IT just re-pasted (see SELF_CLEARING_RESUBMIT_ECHO_MS).
        if (selfClearingGate.observe(stripped, now)) {
          stopSelfClearingTimers();
          console.log(`✅ TUI run ${runId} provider signal cleared — generating again`);
        }

        const sessionLimit = isClaudeCommand(command) && promptSubmittedAt
          ? detectClaudeSessionLimitBanner(stripped)
          : null;
        let waitingForLowPriorityResubmit = false;
        if (sessionLimit && mayUseClaudeLowPriority) {
          if (lowPriorityCommandAttempted && !lowPriorityPromptResubmitted) {
            // Repaints of the initial rejection can arrive while Claude
            // processes the mode command. Re-submit below, then treat a fresh
            // limit banner as a failed continuation.
            waitingForLowPriorityResubmit = true;
          } else if (!lowPriorityCommandAttempted) {
            lowPriorityCommandAttempted = true;
            try {
              ptyProcess.write(`/low-priority${SUBMIT_KEY}`);
              waitingForLowPriorityResubmit = true;
              console.log(`⏳ TUI run ${runId} reached Claude's session limit; sent /low-priority from the provider opt-in`);
              claudeLowPriorityResubmitTimer = setTimeout(() => {
                claudeLowPriorityResubmitTimer = null;
                if (finalized) return;
                promptSubmittedAt = Date.now();
                let resubmitted = false;
                try {
                  if (submitEnterTimer) clearInterval(submitEnterTimer);
                  submitEnterTimer = null;
                  submitEnterTimer = pasteToSession(runId, wrappedPrompt, {
                    label: `[tuiRun ${runId}] Claude low-priority continuation`,
                  }) || null;
                  resubmitted = !!submitEnterTimer;
                } catch (err) {
                  sessionLimit.message = `Claude Code low-priority mode was enabled, but the task could not be re-submitted: ${err?.message || err}`;
                }
                if (resubmitted) {
                  lowPriorityPromptResubmitted = true;
                  console.log(`🔁 TUI run ${runId} re-submitted its task after enabling Claude low-priority mode`);
                  return;
                }
                finishWithFallbackSignal({
                  ...sessionLimit,
                  message: sessionLimit.message
                    || 'Claude Code low-priority mode was enabled, but the task could not be re-submitted',
                }).catch((err) => {
                  console.error(`❌ TUI run ${runId} low-priority re-submit fallback failed: ${err?.message || err}`);
                });
              }, CLAUDE_LOW_PRIORITY_RESUBMIT_DELAY_MS);
            } catch (err) {
              sessionLimit.message = `Claude Code session limit reached and /low-priority could not be sent: ${err?.message || err}`;
            }
          }
        }
        const fallbackSignal = waitingForLowPriorityResubmit ? null : (sessionLimit || detectImmediateFallbackSignal(stripped))
          || detectTerminalModelError(stripped)
          || detectTerminalRequestTimeout(stripped);
        // Branch on the SIGNAL's own grace window, never on gate state: the
        // detector buffers ~512 chars, so a banner keeps matching for many chunks
        // after it has scrolled off. Reading gate state here would let one of
        // those stale matches fall through to an immediate kill the moment the
        // gate closed. A graceful signal can only ever arm a window (or be
        // ignored, when one is already open or the provider already recovered).
        if (fallbackSignal?.graceMs > 0) {
          if (selfClearingGate.arm(fallbackSignal, now)) {
            console.log(`⏳ TUI run ${runId} holding for a self-clearing provider signal (${Math.round(fallbackSignal.graceMs / 1000)}s): ${fallbackSignal.message}`);
            // The wait is ACTIVE — see resubmitAfterSignal. This only ASKS on a
            // sub-multiple of the cadence; the gate decides when an attempt is
            // actually due (SELF_CLEARING_RESUBMIT_POLL_MS). Stopped on recovery
            // above, at expiry below, and by cleanupTimers on any finish.
            selfClearingResubmitTimer = setInterval(resubmitAfterSignal, SELF_CLEARING_RESUBMIT_POLL_MS);
            selfClearingTimer = setTimeout(() => {
              selfClearingTimer = null;
              stopSelfClearingTimers();
              // No clock argument: this timer IS this window's deadline, and it
              // is one-shot — a deadline re-check that came up a millisecond
              // short would strand the gate armed with nothing left to retry it.
              const expired = selfClearingGate.takeExpired();
              if (finalized || !expired) return;
              finishWithFallbackSignal(expired).catch((err) => {
                console.error(`❌ TUI run ${runId} deferred fallback-signal handling failed: ${err?.message || err}`);
              });
            }, fallbackSignal.graceMs);
          }
        } else if (fallbackSignal) {
          // Fire-and-forget like every other finish() call from this PTY
          // callback; finish() itself never rejects and the salvage read can't
          // throw, so the catch is belt-and-braces for a callback boundary.
          finishWithFallbackSignal(fallbackSignal).catch((err) => {
            console.error(`❌ TUI run ${runId} fallback-signal handling failed: ${err?.message || err}`);
          });
          return;
        }
      }

      lastOutputAt = now;
      if (firstOutputAt === null) firstOutputAt = now;
      if (promptSentAt && firstResponseAt === null && now > promptSentAt) {
        firstResponseAt = now;
        // Defer the idle-watch timer until the first response chunk so we
        // don't run a 1Hz no-op throughout the 5-30s spawn + paste window.
        // Significant on parallel fan-out paths (arc planner).
        idleWatchTimer = setInterval(() => {
          if (finalized) return;
          // Idle-completion is the FALLBACK for runs that print their answer
          // inline instead of writing the response file (the authoritative
          // done-signal, handled by responseFileWatchTimer from paste onward).
          // Don't auto-complete a run a human is actively watching in the Shell
          // page — they may be reading the output or about to type a correction
          // or an answer the model is waiting on. The run then ends only on
          // natural process exit or an explicit Stop. Unattended pipeline runs
          // keep the snappy idle threshold for throughput.
          if (isExternalSessionAttached(runId)) return;
          // A run waiting out a provider handshake is silent by design, and the
          // only thing on screen is the banner. Idle-completing here would
          // finalize SUCCESS and scrape that error screen as the answer — the
          // bogus-response failure this file guards against elsewhere. Bounded
          // twice over: the gate closes on the first sign of generation, and its
          // own timer resolves the deadline regardless.
          if (selfClearingGate.armed) return;
          // A low-priority continuation still owes a complete response file or
          // process exit. Do not scrape an idle limit/command screen as success,
          // either while the mode command is being processed or after the task
          // has been re-submitted.
          if (lowPriorityCommandAttempted) return;
          // Quiet with the paste chip still in the composer is a prompt that was
          // never submitted, not an answer; unsubmittedPromptTimer owes it an Enter.
          if (promptGate.awaitingSubmit) return;
          const idle = Date.now() - lastOutputAt;
          if (idle >= idleThresholdMs) {
            if (requiresResponseFileForIdleCompletion) return;
            // A quiet screen whose last paint is still in-flight chrome (a
            // working counter, `thinking with medium effort`) is a model
            // thinking without repainting, not an answer — Fable sat silent
            // on that spinner past the idle threshold and the run scraped it
            // as the response. Hold for the response file, process exit, or
            // the hard timeout instead.
            if (screenShowsInFlightChrome(outputBuffer.slice(-IN_FLIGHT_SCREEN_TAIL_CHARS))) return;
            // NOTE: non-Codex providers are NOT required to show a work-activity
            // signal. Idle-complete is their inline-output fallback when a model
            // prints its answer instead of writing the response file; that
            // output may legitimately carry no `(Ns ·` working counter. Codex is
            // held to the response-file contract above because its quiet
            // reasoning stretches are otherwise indistinguishable from completion.
            finish({ success: true, exitCode: 0, reason: 'idle-complete' });
          }
        }, 1000);
      }

      // Early-fail probe — without this guard a typo'd provider.command
      // would idle until the hard timeout (5 min default).
      if (!promptSentAt && detectMissingTuiBinary(stripped, command)) {
        finish({
          success: false,
          exitCode: 127,
          error: `TUI command not found: ${command}`,
          reason: 'command-not-found'
        });
      }
    });

    const handlePtyExit = ({ exitCode, signal }) => {
      const killed = !!signal;
      // pm2 tree-kills descendants during a PortOS restart, while /runs Stop
      // kills this registered PTY through runner.stopRun. Both are intentional
      // interruptions, not provider failures: never scan the story transcript
      // for a bogus quota marker, bench the provider, or launch a fallback.
      const stopRequested = consumeRunStopRequested(runId);
      const hostInterrupted = killed && isHostShuttingDown();
      // A CLI can handle SIGTERM and exit through its shell with code 143
      // (or cleanly), leaving node-pty's signal at 0. The explicit stop marker
      // is authoritative regardless of how that process reports its exit.
      const canceled = stopRequested || hostInterrupted;
      const finalExitCode = typeof exitCode === 'number' ? exitCode : (killed ? 130 : 0);
      const success = !canceled && !killed && finalExitCode === 0;
      // The terminal-timeout detector holds a candidate banner until a real line
      // terminator proves the line is finished (#3715). Process exit IS that
      // proof — no further byte can turn `⎿ Request timed out` into a
      // `· Retrying …` banner — so flush the held candidate here rather than
      // letting a clean exit 0 scrape the error screen as model output (the
      // exact failure the detector was added for).
      const heldTimeout = success ? detectTerminalRequestTimeout(null, { endOfStream: true }) : null;
      if (heldTimeout) {
        finishWithFallbackSignal(heldTimeout, { processExited: true }).catch((err) => {
          console.error(`❌ TUI run ${runId} exit-time timeout handling failed: ${err?.message || err}`);
        });
        return;
      }
      // Always set an explicit error string when finishing as failure. The
      // toolkit's errorDetection (if enabled) will fill in `error` inside
      // finalizeRunRecord, but if it's absent we'd persist `success: false`
      // with no error and the central handler would reject with a generic
      // "TUI execution failed". Include the exit code + a tail of the
      // captured output so failures are actionable from /runs without
      // re-running.
      let error = null;
      if (hostInterrupted) {
        error = `TUI interrupted by PortOS shutdown (signal ${signal})`;
      } else if (stopRequested) {
        error = killed ? `TUI canceled (signal ${signal})` : `TUI canceled (exit code ${finalExitCode})`;
      } else if (killed) {
        error = `TUI killed (signal ${signal})`;
      } else if (!success) {
        const tail = outputBuffer.slice(-200).trim();
        error = tail
          ? `TUI exited with code ${finalExitCode}: ${tail}`
          : `TUI exited with code ${finalExitCode}`;
      }
      finish({
        success,
        exitCode: finalExitCode,
        error,
        reason: hostInterrupted ? 'host-shutdown' : (stopRequested ? 'canceled' : (killed ? 'killed' : 'exit')),
        canceled,
      });
    };

    const sendPrompt = (reason) => {
      if (finalized || promptSentAt) return;
      promptSentAt = Date.now();
      // Start capturing stripped post-paste output BEFORE the paste write so the
      // marker watcher sees every response chunk.
      postPasteStripped = '';
      try {
        ptyProcess.write(`\x1b[200~${wrappedPrompt}\x1b[201~`);
      } catch (err) {
        finish({ success: false, exitCode: 1, error: `Failed to write prompt: ${err.message}`, reason: 'write-failed' });
        return;
      }
      console.log(`📟 Pasted prompt into TUI ${command} (${reason})`);

      // Watch for the response file from paste onward — it's the model's
      // authoritative "done" signal and must complete the run INDEPENDENTLY of
      // whether any post-paste PTY output ever arrives. A model that writes the
      // file silently (no streamed output to arm idleWatchTimer) would otherwise
      // hang until the hard-timeout salvage. Runs unconditionally, even while a
      // human watches: once the file exists the task is finished, so there's
      // nothing left to intervene in. (Idle/attach gating lives only on
      // idleWatchTimer, the inline-output fallback.)
      responseFileWatchTimer = setInterval(async () => {
        if (finalized) return;
        // try/catch is mandatory in an async timer callback: a rejected await
        // has no owner and escapes as an unhandled rejection (process-killing
        // on Node >= 15). The poll is a best-effort completion signal — drop a
        // failed tick and let the next one (or the hard timeout) settle the run.
        try {
          if (await responseFileSettled()) {
            finish({ success: true, exitCode: 0, reason: 'response-file' });
          }
        } catch (err) {
          console.error(`❌ TUI run ${runId} response-file poll failed: ${err?.message || err}`);
        }
      }, 1000);

      const pasteSentAt = Date.now();
      pasteEnterTimer = setInterval(() => {
        if (finalized) { clearInterval(pasteEnterTimer); pasteEnterTimer = null; postPasteStripped = null; return; }
        const elapsed = Date.now() - pasteSentAt;
        // Shared with the agent spawner's poll so the two can't drift on what
        // counts as a commit — without a verifiable prefix this is the marker
        // count plus Claude's/OpenCode's collapsed-chip shape.
        const markerSeen = isPasteCommitted(postPasteStripped || '', { promptMarkerCount });
        if ((markerSeen && elapsed >= PASTE_TO_ENTER_MIN_DELAY_MS)
          || elapsed >= PASTE_TO_ENTER_FALLBACK_MS) {
          clearInterval(pasteEnterTimer);
          pasteEnterTimer = null;
          // The commit buffer holds the chip: a TUI that ignores the Enter may
          // never repaint it.
          promptGate.noteInput(Date.now(), postPasteStripped || '');
          postPasteStripped = null;
          // Submit with repeated Enters — a single `\r` can be swallowed while
          // the TUI is still reflowing a large paste, stranding the prompt
          // unsent. Tracked in submitEnterTimer so finish()'s cleanupTimers()
          // cancels pending retries if the run ends first.
          submitEnterTimer = scheduleSubmitEnters(
            () => {
              promptGate.noteInput(Date.now());
              try { ptyProcess.write(SUBMIT_KEY); } catch { /* PTY may have already exited */ }
            },
            () => finalized
          );
          promptSubmittedAt = Date.now();
          unsubmittedPromptTimer = setInterval(() => {
            if (finalized || promptGate.worked) {
              clearInterval(unsubmittedPromptTimer);
              unsubmittedPromptTimer = null;
              return;
            }
            const now = Date.now();
            const enter = promptGate.takeEnter(now, lastOutputAt);
            if (!enter) return;
            try {
              ptyProcess.write(SUBMIT_KEY);
              console.log(`🔁 TUI run ${runId} prompt still unsubmitted in the composer — pressed Enter (attempt ${enter}/${UNSUBMITTED_PROMPT_ENTER_MAX_ATTEMPTS})`);
            } catch { /* PTY may have already exited */ }
          }, UNSUBMITTED_PROMPT_POLL_MS);
        }
      }, PASTE_MARKER_POLL_MS);
    };

    const dismissStartupDialog = (keys, dialog) => {
      try {
        ptyProcess.write(keys);
        return true;
      } catch (err) {
        finish({
          success: false,
          exitCode: 1,
          error: `Failed to dismiss ${dialog}: ${err.message}`,
          reason: 'startup-dialog-write-failed',
        }).catch((finishErr) => {
          console.error(`❌ TUI run ${runId} ${dialog} dismissal failed: ${finishErr?.message || finishErr}`);
        });
        return false;
      }
    };

    /**
     * Re-deliver the prompt while a self-clearing provider signal's window is
     * open. Mirrors `resubmitAfterSignal` on the long-running agent path — see
     * that copy (and SELF_CLEARING_RESUBMIT_INTERVAL_MS) for why a passive wait
     * cannot clear agy's eligibility banner: it is the REJECTION of the
     * submission, so the prompt is gone, the composer is empty, and nothing will
     * generate until something re-asks.
     */
    const resubmitAfterSignal = () => {
      // A banner during startup has nothing to re-send — the ready watch below
      // still owns first delivery.
      if (finalized || !promptSentAt) return;
      const attempt = selfClearingGate.takeResubmit(Date.now());
      if (!attempt) return;
      // Overwriting a live handle would leak the previous attempt's Enter
      // interval past cleanupTimers. `pasteToSession` returns false once the PTY
      // has been unregistered, which is also the "don't bother" answer here —
      // the deadline timer still owns the fail-over.
      if (submitEnterTimer) clearInterval(submitEnterTimer);
      const submitted = pasteToSession(runId, wrappedPrompt, {
        label: `[tuiRun ${runId}] provider-handshake resubmit`,
      });
      submitEnterTimer = submitted || null;
      // Only claim the re-submission that actually went out — `false` here means
      // the PTY is already gone, and a log line saying otherwise would send a
      // post-mortem looking for a paste the provider never received.
      if (submitted) {
        console.log(`🔁 TUI run ${runId} re-submitted its prompt while the provider handshake is open (attempt ${attempt})`);
      }
    };

    // Ready watch — known startup dialogs (folder trust, external imports,
    // Codex's hook review) are dismissed for EVERY provider before anything is
    // sent, since each of them swallows a paste. Claude then waits for its
    // positive input-ready signal; other providers retain the idle/deadline
    // fallback for delivery.
    readyTimer = setInterval(() => {
      if (finalized || promptSentAt) {
        clearInterval(readyTimer);
        readyTimer = null;
        return;
      }
      const now = Date.now();
      const elapsed = now - startTime;
      // OpenCode answers an unresolvable model with a toast and then paints its
      // composer for a replacement model; fail the run rather than let readiness
      // deliver the prompt to (and scrape output from) that other model.
      const opencodeRejection = isOpencodeSession ? inputReady.opencodeModelRejection : null;
      if (opencodeRejection) {
        clearInterval(readyTimer);
        readyTimer = null;
        finish({
          success: false,
          exitCode: 1,
          error: opencodeRejection.message,
          reason: 'opencode-model-rejected',
          errorAnalysis: { ...opencodeRejection, configuredModel: provider.defaultModel },
        }).catch((err) => {
          console.error(`❌ TUI run ${runId} OpenCode model-rejection failure could not finalize: ${err?.message || err}`);
        });
        return;
      }
      // Both dismissals below rewind the idle clock and clear `firstOutputAt`:
      // the idle path further down reads silence as readiness, and a dialog is
      // quietest right after it paints, so otherwise the keystroke and an idle
      // paste go out inside the same window and the prompt lands in a menu that
      // has not repainted. Requiring fresh output-then-silence after the
      // keystroke makes delivery wait for what the dismissal reveals;
      // PASTE_DEADLINE_MS still backstops a dismissal the TUI ignores entirely.

      if (isOpencodeSession && inputReady.needsOpencodeUpdate) {
        if (dismissStartupDialog('\x1b', 'OpenCode update offer')) inputReady.ackOpencodeUpdate();
        lastOutputAt = now;
        firstOutputAt = null;
        return;
      }

      // A managed-app worktree nested below PortOS can make Claude discover the
      // parent PortOS CLAUDE.md and offer to import its external AGENTS.md.
      // Decline option 1 rather than crossing that repository boundary. The
      // target checkout's own instructions remain available after option 2.
      if (inputReady.needsExternalImportsChoice) {
        if (dismissStartupDialog('\x1b[B\r', 'external-imports prompt')) {
          inputReady.ackExternalImportsChoice();
        }
        lastOutputAt = now;
        firstOutputAt = null;
        return;
      }

      // Codex's hook-review selector precedes its composer. An unattended run
      // must not grant hooks permission to execute outside the sandbox, so take
      // the explicit "Continue without trusting" option before ordinary
      // readiness/fallback delivery can paste into the selector.
      if (inputReady.needsHookReview && !hookReviewDeclined) {
        hookReviewDeclined = true;
        if (dismissStartupDialog('\x1b[B\x1b[B\r', 'hook-review prompt')) {
          inputReady.ackHookReview();
        }
        lastOutputAt = now;
        firstOutputAt = null;
        return;
      }
      // The first-run folder-trust gate, like the hook-review selector above,
      // must be answered for EVERY provider rather than only the input-ready
      // ones: codex takes the idle/deadline path below, and its trust dialog
      // paints and then goes silent — which that path reads as "ready" and
      // pastes into, losing the prompt and every retry with it (agent-671af38f).
      // Wait for the options to paint before acting. Claude Code versions do
      // not agree on their order: when "No, exit" is highlighted, select the
      // next option before submitting. `trustAccepted` keeps this to one input.
      if (inputReady.needsTrust && inputReady.trustChoiceReady && !trustAccepted) {
        trustAccepted = true;
        const trustInput = `${inputReady.trustSelectionKey}${SUBMIT_KEY}`;
        if (dismissStartupDialog(trustInput, 'folder-trust prompt')) inputReady.ackTrustChoice();
        lastOutputAt = now;
        firstOutputAt = null;
        return;
      }
      if (inputReady.needsTrust && !inputReady.trustChoiceReady) {
        const trustDeadlineMs = requiresInputReady ? TUI_INPUT_READY_DEADLINE_MS : PASTE_DEADLINE_MS;
        if (elapsed >= trustDeadlineMs) {
          clearInterval(readyTimer);
          readyTimer = null;
          finish({
            success: false,
            exitCode: 1,
            error: `${command} presented a folder-trust prompt whose affirmative choice PortOS could not identify, so no prompt was sent.`,
            reason: 'tui-trust-choice-unrecognized',
          });
        }
        return;
      }
      if (requiresInputReady) {
        if (inputReady.needsAutoModeChoice) {
          // Select "No, keep don't ask" so a one-shot run never rewrites the
          // user's global Claude permission default as a startup side effect.
          if (dismissStartupDialog('\x1b[B\r', 'auto-mode prompt')) {
            // The offer paints over an already-live composer, so this re-arms
            // that verified paste-mode signal. Returning still leaves a full
            // ready-poll interval for Ink to redraw before any paste can start.
            inputReady.ackAutoModeChoice();
          }
          return;
        }
        if (inputReady.ready && elapsed >= promptDelayMs
          && (!isOpencodeSession || (firstOutputAt !== null && now - lastOutputAt >= READY_IDLE_THRESHOLD_MS))) {
          sendPrompt('input-ready');
          return;
        }
        if (elapsed >= TUI_INPUT_READY_DEADLINE_MS) {
          clearInterval(readyTimer);
          readyTimer = null;
          finish({
            success: false,
            exitCode: 1,
            error: `${command} did not present an input prompt within ${Math.round(TUI_INPUT_READY_DEADLINE_MS / 1000)}s, so no prompt was sent.`,
            reason: 'tui-not-ready',
          }).catch((err) => {
            console.error(`❌ TUI run ${runId} input-readiness failure could not finalize: ${err?.message || err}`);
          });
        }
        return;
      }
      if (elapsed >= PASTE_DEADLINE_MS) {
        sendPrompt('fallback');
        return;
      }
      if (elapsed < promptDelayMs) return;
      if (firstOutputAt === null) return;
      if (now - lastOutputAt < READY_IDLE_THRESHOLD_MS) return;
      sendPrompt('ready');
    }, READY_POLL_INTERVAL_MS);

    // (idleWatchTimer is created inside onData once firstResponseAt is set.)

    // Hard timeout — covers stuck-banner, no-response, and runaway-response
    // cases, and is the honest backstop that bounds a run a viewer left open on
    // a backgrounded tab (idle-completion is paused while watched, but this is
    // not — a run can't exceed its configured max time). Provider-configurable
    // via `timeout`; defaults to 5 min.
    if (totalTimeoutMs > 0) hardTimeoutTimer = setTimeout(async () => {
      if (finalized) return;
      // try/catch is mandatory in an async timer callback — see the response-file
      // watcher above. Only the salvage read is wrapped: a read that rejects
      // falls through to the timeout verdict below (the run really did exceed
      // its budget) instead of escaping as an unhandled rejection.
      try {
        // Salvage net: if the model already wrote its response file, the run truly
        // finished — the TUI just never exited — so the timeout is a false failure.
        // Complete as success with the written result instead of discarding it and
        // triggering a pointless fallback retry. (The response-file watcher above
        // normally catches this within ~2s; this covers the boundary case where the
        // file lands right at the deadline or the watcher hadn't confirmed yet.)
        if (await responseFileHasContent()) {
          finish({ success: true, exitCode: 0, reason: 'timeout-response-file' });
          return;
        }
      } catch (err) {
        console.error(`❌ TUI run ${runId} timeout salvage read failed: ${err?.message || err}`);
      }
      finish({
        success: false,
        exitCode: 124,
        error: `TUI run timed out after ${totalTimeoutMs}ms`,
        reason: 'timeout'
      });
    }, totalTimeoutMs);

    // The exit bridge was attached immediately after spawn. Hand it the fully
    // initialized lifecycle only after every cleanup-owned timer exists, then
    // replay an exit that arrived during setup. Assign before reading the
    // pending slot so an exit racing this handoff is delivered exactly once.
    dispatchPtyExit = handlePtyExit;
    if (pendingPtyExit) {
      const earlyExit = pendingPtyExit;
      pendingPtyExit = null;
      handlePtyExit(earlyExit);
    }
  });
}

/**
 * Pick the TUI response text — preferring the file the model was directed
 * to write, falling back to the cleaned screen scrape.
 *
 * Returns `{ text, usedResponseFile }`. `usedResponseFile` is true when the
 * file existed and had non-empty trimmed content; false in every other
 * case (file missing, empty, whitespace-only, or run did not succeed).
 *
 * Extracted out of `executeTuiRun.finish` so the file-read + fallback
 * decision is testable without spawning a PTY.
 */
export async function resolveTuiResponseText({ success, responseFilePath, outputBuffer, wrappedPrompt }) {
  if (success) {
    const fileText = await tryReadFile(responseFilePath);
    if (typeof fileText === 'string' && fileText.trim()) {
      return { text: fileText.trim(), usedResponseFile: true };
    }
  }
  return { text: cleanTuiResponse(outputBuffer, wrappedPrompt), usedResponseFile: false };
}

/**
 * Best-effort response cleanup for an already-ANSI-stripped TUI buffer.
 *
 * The TUI buffer is a screen, not a log — it contains banner art, the
 * pasted prompt echoed back, status lines ("thinking...", token counters),
 * box-drawing characters around the input prompt, and the model's response
 * interleaved with all of it. Reliable carve-out would need per-binary
 * scrapers; this helper just drops the obvious bits (paste marker + echoed
 * prompt) and leaves downstream consumers (`extractJson`,
 * `extractCodexAssistant`) to find structured content in the rest.
 *
 * Input is assumed pre-stripped of ANSI codes (the central handler streams
 * each chunk through `createStreamingAnsiStripper` during accumulation, so
 * `outputBuffer` is already clean). Don't strip again — it's a wasted scan
 * over up to `OUTPUT_BUFFER_CAP` bytes of text.
 */
export function cleanTuiResponse(strippedText, prompt) {
  if (typeof strippedText !== 'string' || !strippedText) return '';
  let text = strippedText.replace(/\[Pasted text #\d+[^\]]*\]/g, '');
  // split-join over the prompt is safe because the prompt is fixed text —
  // no regex escaping needed. Guard on length>16 so a degenerate empty/
  // tiny prompt doesn't accidentally erase model output.
  if (typeof prompt === 'string' && prompt.length > 16) {
    text = text.split(prompt).join('');
  }
  return text.trim();
}