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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
/**
* Agent TUI session controller
*
* The live state machine behind one TUI agent run: session phase, prompt
* delivery and its retry ladder, the completion-sentinel watcher, the
* provider-signal / idle / nudge gates, and the ONE teardown path every ending
* shares.
*
* Extracted from `agentTuiSpawning.js` (#8021) so a change to one provider's
* readiness behaviour no longer means reasoning through sentinel completion,
* PTY teardown, merge-gate handling and the idle/retry timers in the same
* closure. `agentTuiSpawning.js` stays the public adapter: it builds the launch
* shape, opens the PTY, and hands this controller the seams below.
*
* Everything that touches another SERVICE is injected, never imported — that is
* what keeps this module a leaf (no edge back into `agentLifecycle.js` or the
* rest of the spawn cluster) and what makes the state machine drivable in a
* test without a live PTY:
*
* `spooler` output spooling (parsed lines + raw PTY bytes)
* `session` PTY/session I/O, keyed by the sessionId this controller owns
* `persistence` agent-record writes, the run ledger, the active-run entry
* `sentinel` `.agent-done` presence / read / removal / watch
* `finalization` the shared finalize sequence, failure analysis, cleanup
* `probeMergeGatePr` the forge lookup behind the Merge Gate contract check
*
* The pure predicates it keeps as direct imports (handshake gates, ANSI
* stripping, error detectors, the merge-gate decision table) are leaves with no
* path back into this cluster.
*/
import { readFile } from 'fs/promises';
import { emitLog } from '../cosEvents.js';
import { HOST_SHUTDOWN_REASON } from '../../lib/hostShutdown.js';
import { missingSentinelLogMessage, parseSentinelPayload } from '../../lib/agentSentinel.js';
import { LIFECYCLE_LINES, SENTINEL_COMPLETION_MARKER } from '../../lib/agentOutputMarkers.js';
import { resolveMergeGateVerdict, buildMergeGateReprompt } from '../../lib/mergeGateContract.js';
import { createStreamingAnsiStripper, stripAnsi } from '../../lib/ansiStrip.js';
import { createContentRefusalDetector, createClaudeSessionLimitBannerDetector, createImmediateFallbackSignalDetector, createLocalRuntimeOomDetector, createTruncatedResponseDetector, createModelAtCapacityDetector } from '../../lib/aiToolkit/errorDetection.js';
import { isAntigravityCommand } from '../../lib/antigravity.js';
import { isCodexCommand } from '../../lib/codex.js';
import { isClaudeCommand, isOpencodeCommand } from '../../lib/providerModels.js';
import { isFalsyMeta } from '../../lib/metadataFlags.js';
import { createCodexModelRejectionGate } from './codexModelRejection.js';
import {
READY_POLL_INTERVAL_MS,
READY_IDLE_THRESHOLD_MS,
PASTE_MARKER_POLL_MS,
countPasteMarkers,
createSelfClearingSignalGate,
createOomNudgeGate,
createRetryStallGate,
createToolPermissionGate,
TOOL_PERMISSION_DECLINE_MAX,
TOOL_PERMISSION_NUDGE_TEXT,
OOM_NUDGE_MAX_ATTEMPTS,
OOM_NUDGE_TEXT,
createTruncationNudgeGate,
createModelCapacityNudgeGate,
CAPACITY_NUDGE_MAX_ATTEMPTS,
CAPACITY_NUDGE_TEXT,
TRUNCATION_NUDGE_MAX_ATTEMPTS,
TRUNCATION_NUDGE_TEXT,
createStallNudgeGate,
createPromptSubmissionGate,
UNSUBMITTED_PROMPT_ENTER_MAX_ATTEMPTS,
createAgyResumeGate,
AGY_RESUME_MAX_ATTEMPTS,
STALL_NUDGE_MAX_ATTEMPTS,
STALL_NUDGE_TEXT,
STALL_NUDGE_MAX_TOTAL,
createMcpBootTracker,
MCP_BOOT_PASTE_DEADLINE_MS,
MCP_BOOT_PASTE_RETRY_DELAY_MS,
createInputReadyTracker,
shapeHasLoginShell,
createStartupDialogAnswers,
answerStartupDialogs,
AGY_INPUT_READY_PATTERN,
OPENCODE_INPUT_READY_PATTERN,
PASTE_TO_ENTER_MIN_DELAY_MS,
PASTE_TO_ENTER_FALLBACK_MS,
PASTE_COMMIT_PATIENCE_MS,
CODEX_COMPOSER_READY_PATTERN,
POST_PASTE_BUFFER_CAP,
scheduleSubmitEnters,
PASTE_DEADLINE_MS,
TUI_INPUT_READY_DEADLINE_MS,
PASTE_VERIFY_POLL_MS,
PASTE_VERIFY_WINDOW_MS,
PASTE_RETRY_MAX_ATTEMPTS,
PASTE_RETRY_BASE_DELAY_MS,
extractVerifiablePromptPrefix,
isPasteConfirmed,
isPasteCommitted,
CLAUDE_LOW_PRIORITY_RESUBMIT_DELAY_MS,
SUBMIT_KEY,
detectMissingTuiBinary,
} from '../../lib/tuiHandshake.js';
// Agent-specific timing/lifecycle constants (not shared with the one-shot
// runner — agents stay alive much longer and write a sentinel file when done).
const PROVIDER_SIGNAL_POLL_MS = 5000;
const SENTINEL_RECOVERY_RETRY_MS = 250;
// Paste + submit-Enter retry machinery for the controller's prompt delivery.
// Separated so retries don't re-run the liveness guard or re-set the outer
// promptSentAt (see `sendPrompt` below) — the cluster the spawner's own
// comments already described as one cohesive concern. Owns the paste-attempt
// counter, the post-paste accumulator, the paste-marker/verify timers, and the
// submit-Enter backstop timer.
//
// `isFinalized`/`markPromptSent`/`markPromptSubmitted` are accessors into the
// controller's own `sessionPhase`/`promptSentAt`/`promptSubmittedAt` — those are
// read by handleData and the provider-signal timer well outside this cluster, so
// they stay owned by the controller and are threaded through rather than
// duplicated here. `finishStartupFailure`/`appendLine` are likewise the
// controller's own closures, passed in rather than re-implemented, and
// `noteInput` reports each submit and re-delivery to the controller's
// prompt-submission gate.
function createPasteRetryController({
agentId,
sessionLabel,
write,
paste,
hasLiveChild,
launchShape,
prompt,
tuiConfig,
mcpBoot,
isCodexSession,
appendLine,
isFinalized,
markPromptSent,
markPromptSubmitted,
noteInput,
finishStartupFailure,
}) {
// Markers already present in the prompt text itself (a transcript-analysis task
// can echo `[Pasted text #N]` back). The paste-commit fast path must wait for
// the TUI's OWN marker — i.e. the count to EXCEED this — so an echoed marker
// doesn't fire the submit-Enters mid-reflow (issue #1229 review). STRIP the
// prompt first: a pasted RAW transcript may carry the cursor-positioned marker
// form (`[Pasted\x1b[11Gtext…`), which counts as 0 unstripped but echoes back as
// the stripped `[Pastedtext#…]` (count 1) — so we must count the prompt the same
// way the post-paste buffer is counted, or the gate undercounts and fires early.
const promptMarkerCount = countPasteMarkers(stripAnsi(prompt));
// Extract a verifiable prefix from the prompt for paste verification (issue #2192).
// Computed once up front so retry attempts use the same verification target.
const verifiablePrefix = extractVerifiablePromptPrefix(prompt);
const pasteConfirmed = (buffer) =>
isPasteConfirmed(buffer, { verifiablePrefix, promptMarkerCount });
// Same evidence, minus isPasteConfirmed's "nothing to verify against" pass —
// the commit-wait below must keep WAITING while a prompt too short to carry a
// verifiable prefix has not visibly landed, not treat it as already committed.
//
// Memoized on buffer identity because the marker poll re-asks every
// PASTE_MARKER_POLL_MS for up to PASTE_COMMIT_PATIENCE_MS — ~300 ticks — while
// a booting codex is silent, and the predicate is three full-buffer regex
// scans plus two whitespace-stripped copies of it. `pasteState.buffer` is only
// ever rebound when output actually arrives, so an idle tick is a pointer
// compare.
let lastCommitBuffer = null;
let lastCommitVerdict = false;
const pasteCommitted = (buffer) => {
if (buffer !== lastCommitBuffer) {
lastCommitBuffer = buffer;
lastCommitVerdict = isPasteCommitted(buffer, { verifiablePrefix, promptMarkerCount });
}
return lastCommitVerdict;
};
// Paste-confirmation state: which protocol window an attempt is in, plus the
// bounded post-paste output accumulated across it.
// idle no attempt in flight; incoming output is ignored
// awaiting-marker attempt fired; waiting for the TUI's commit evidence
// awaiting-verify commit wait elapsed with no evidence; short window for a
// late marker / prompt echo before declaring it swallowed
// backoff verification failed; waiting out the retry delay
// The buffer deliberately survives every phase change except `idle`, so
// delayed TUI output can still confirm a paste that looked failed. The
// transition helpers below are the ONLY writers of this object.
const pasteState = { phase: 'idle', buffer: '' };
const armAttempt = () => { pasteState.phase = 'awaiting-marker'; pasteState.buffer = ''; };
const beginVerify = () => { pasteState.phase = 'awaiting-verify'; };
// Retains the buffer: a marker painted after the verify window closes must
// still confirm this paste instead of letting the retry duplicate it.
const enterBackoff = () => { pasteState.phase = 'backoff'; };
const clearPaste = () => { pasteState.phase = 'idle'; pasteState.buffer = ''; };
let pasteEnterTimer = null;
let pasteVerifyTimer = null;
let pasteRetryTimer = null;
let submitEnterTimer = null;
let pasteAttempt = 0;
// Wall-clock of the FIRST paste attempt — the anchor for the MCP-boot-aware
// retry deadline (retries are time-bounded, not attempt-count-bounded, while
// codex is still booting its MCP servers).
let firstPasteStartedAt = null;
// Guards re-entry the way the outer promptSentAt used to before this state
// moved here — sendPrompt is this controller's only setter for it now.
let sent = false;
/**
* Re-deliver text into the live session: the whole prompt while a
* self-clearing provider signal's grace window is open (agy's
* account-eligibility banner), or the short `continue` nudge that recovers a
* turn a local-GPU OOM killed (see createOomNudgeGate).
*
* The banner is the REJECTION of the submission, not a spinner over an
* in-flight one: agy discards the prompt, empties its composer and returns to
* its idle footer, so nothing will generate until something re-asks — which is
* also what the banner instructs ("try again shortly"). Re-pasting the WHOLE
* prompt is correct precisely because the composer is empty.
*
* Lives here rather than in the controller because this cluster owns
* `submitEnterTimer`; leaving the handle in one scope and the re-delivery in
* another is how you leak an Enter interval past finish(). Nothing here
* re-runs paste VERIFICATION: the prompt already rendered once (its rejection
* is why we're here), and routing back through `attemptPaste` would spend the
* startup paste-retry budget and let a verification hiccup mid-handshake
* finalize the run as `paste-not-rendered`.
*
* @returns {boolean} whether the paste actually went out (false once the
* session is gone — the caller must not claim a re-submission that didn't
* happen).
*/
const resubmit = ({ text = prompt, label = 'provider-handshake resubmit' } = {}) => {
if (isFinalized()) return false;
// Overwriting a live handle would leak the previous attempt's Enter interval
// past cancel(); paste returns a fresh one, or false once the session is
// gone — which is also the "don't bother" answer, since the grace window's
// deadline still owns the fail-over.
if (submitEnterTimer) clearInterval(submitEnterTimer);
const handle = paste(text, { label: `[cosAgents] ${label}` });
submitEnterTimer = handle || null;
if (handle) noteInput();
return !!handle;
};
const sendPrompt = async (reason) => {
if (isFinalized() || sent) return;
sent = true;
markPromptSent();
// Liveness guard: the TUI command runs as a child of the persistent PTY
// shell, so if it exited at startup (e.g. claude failing to enter
// interactive mode) the PTY stays open and onExit never fires. Pasting now
// would dump the bracketed-paste prompt into the bare shell — the wedged
// `^[[200~ …` session. If the shell has no live child, the command is gone:
// fail loudly with whatever it printed instead of pasting into the shell.
//
// A launch shape with a login shell has an intermediate shell; without one
// (runner or direct), the TUI IS the PTY process and "does this pid have a
// live child?" is the wrong question (the TUI may have zero children at
// paste time). A TUI exit kills the PTY in those shapes, firing onExit.
// Skip the probe when there is no shell to host the TUI.
if (shapeHasLoginShell(launchShape) && !(await hasLiveChild())) {
if (isFinalized()) return; // a real onExit may have finalized during the probe await
await finishStartupFailure(
'tui-exited-early',
`${tuiConfig.command} exited at startup before the TUI was ready, so no prompt was sent.`,
);
return;
}
// Start the paste attempt — may be retried if verification fails (issue #2192).
attemptPaste(reason);
};
// The commit buffer goes to noteInput because it holds the paste chip: a TUI
// that ignores the submit Enter may never repaint it (createPromptSubmissionGate).
const submitConfirmedPaste = () => {
const evidence = pasteState.buffer;
clearPaste();
if (pasteRetryTimer) {
clearTimeout(pasteRetryTimer);
pasteRetryTimer = null;
}
markPromptSubmitted();
noteInput(evidence);
submitEnterTimer = scheduleSubmitEnters(
() => write(SUBMIT_KEY, { promptSubmission: true }),
() => isFinalized()
);
};
// Actually perform a paste attempt. Separated from sendPrompt so retries don't
// re-run the liveness guard or re-set promptSentAt. Increments pasteAttempt on
// each call; clears any pending timers from the previous attempt first.
const attemptPaste = (reason) => {
pasteAttempt += 1;
const attemptNum = pasteAttempt;
if (firstPasteStartedAt === null) firstPasteStartedAt = Date.now();
if (pasteEnterTimer) { clearInterval(pasteEnterTimer); pasteEnterTimer = null; }
if (pasteVerifyTimer) { clearInterval(pasteVerifyTimer); pasteVerifyTimer = null; }
if (pasteRetryTimer) { clearTimeout(pasteRetryTimer); pasteRetryTimer = null; }
// Start capturing post-paste output. Armed BEFORE writing the paste so
// every chunk that arrives in response gets appended.
armAttempt();
write(`\x1b[200~${prompt}\x1b[201~`);
const attemptSuffix = attemptNum > 1 ? ` [attempt ${attemptNum}/${PASTE_RETRY_MAX_ATTEMPTS}]` : '';
appendLine(LIFECYCLE_LINES.promptPasted({ session: sessionLabel, reason, attemptSuffix }));
// Confirms the TUI actually received the paste before we submit. The
// paste-commit marker is authoritative — Claude Code and OpenCode can
// collapse a multi-line paste into a chip and HIDE the body text, so a
// literal text check false-negatives on multi-line prompts (real incident
// 2026-07-05: agent-656efa6e et al. failed `paste-not-rendered` despite
// Claude's marker being present). Literal-text verification is only the
// fallback for the markerless path — see isPasteConfirmed.
// Markerless AND the prompt text never rendered → the paste was swallowed by
// a still-initializing TUI (issue #2192). Retry, then fail.
//
// Budget is boot-aware: once codex's MCP-boot banner has been seen (mcpBoot
// active), the boot can legitimately run for tens of seconds — up to ~2min
// for a node_repl/npx server — during which EVERY paste is swallowed. Switch
// from the fixed 3-attempt/exponential-backoff budget to a TIME budget
// (MCP_BOOT_PASTE_DEADLINE_MS from the first paste) with a fixed cadence, so
// retries outlast the boot and the paste finally lands once the input box is
// live (incident 2026-07-10, agent-c5a26b40). No MCP boot → unchanged.
const retryOrFailPaste = () => {
if (isFinalized()) return;
const bootActive = mcpBoot.active;
const withinBudget = bootActive
? (Date.now() - firstPasteStartedAt) < MCP_BOOT_PASTE_DEADLINE_MS
: attemptNum < PASTE_RETRY_MAX_ATTEMPTS;
if (withinBudget) {
const retryDelayMs = bootActive
? MCP_BOOT_PASTE_RETRY_DELAY_MS
: PASTE_RETRY_BASE_DELAY_MS * Math.pow(2, attemptNum - 1);
const bootNote = bootActive
? ` (waiting for ${tuiConfig.command} MCP servers to finish booting)`
: '';
appendLine(LIFECYCLE_LINES.pasteRetrying({ delayMs: retryDelayMs, bootNote }));
// The failed attempt's buffer stays live during the backoff (see
// enterBackoff). A busy TUI can paint its authoritative paste marker
// only after the verification window closes; dropping output in this
// gap made Codex stack duplicate prompt chips, then falsely report that
// none had rendered.
pasteRetryTimer = setTimeout(() => {
pasteRetryTimer = null;
if (isFinalized()) return;
if (pasteConfirmed(pasteState.buffer)) {
submitConfirmedPaste();
return;
}
attemptPaste(reason);
}, retryDelayMs);
return;
}
// Budget exhausted — fail the agent, naming the MCP-boot cause when that's
// what kept the paste from landing so the operator knows to check their
// codex config rather than chasing a phantom paste-timing bug.
const bootSecs = Math.round(MCP_BOOT_PASTE_DEADLINE_MS / 1000);
const summary = bootActive
? `${tuiConfig.command} did not finish booting its MCP servers within ${bootSecs}s, so the prompt was never delivered. A slow or hung MCP server in your ~/.codex config (e.g. playwright via npx, or a node_repl) blocks codex from accepting input — disable or fix it, or remove it for headless runs.`
: `${tuiConfig.command} was still initializing and the paste was silently swallowed. The prompt never appeared in the TUI buffer after ${PASTE_RETRY_MAX_ATTEMPTS} attempts.`;
appendLine(bootActive
? LIFECYCLE_LINES.pasteNeverLandedMcpBoot({ seconds: bootSecs })
: LIFECYCLE_LINES.pasteNeverRendered({ attempts: PASTE_RETRY_MAX_ATTEMPTS }));
finishStartupFailure('paste-not-rendered', summary)
.catch(err => emitLog('error', `TUI agent ${agentId} finishStartupFailure(paste-not-rendered) failed: ${err?.message || err}`, { agentId }));
};
const pasteSentAt = Date.now();
// How long THIS attempt waits for the TUI to commit the paste before
// handing over to the verify/retry budget. Read live rather than captured:
// codex's MCP-boot banner can latch after the paste went out, and a
// swallowing codex must not spend the patient window — see
// PASTE_COMMIT_PATIENCE_MS.
const commitWaitMs = () => (isCodexSession && attemptNum <= 1 && !mcpBoot.active
? PASTE_COMMIT_PATIENCE_MS
: PASTE_TO_ENTER_FALLBACK_MS);
pasteEnterTimer = setInterval(() => {
if (isFinalized()) {
clearInterval(pasteEnterTimer);
pasteEnterTimer = null;
clearPaste();
return;
}
const elapsed = Date.now() - pasteSentAt;
// Submit when EITHER the TUI's paste commit shows up (preferred) or the
// commit-wait window elapses (covers small prompts that don't render the
// marker). Waiting on the full commit evidence rather than the marker
// alone is what lets codex's patient first attempt (PASTE_COMMIT_PATIENCE_MS)
// exit in ~200ms when the composer was live all along.
if ((pasteCommitted(pasteState.buffer) && elapsed >= PASTE_TO_ENTER_MIN_DELAY_MS)
|| elapsed >= commitWaitMs()) {
clearInterval(pasteEnterTimer);
pasteEnterTimer = null;
// Confirm the paste (issue #2192).
const commitBuffer = pasteState.buffer;
// Marker present (or text already visible, or nothing to verify) → the
// paste landed; submit now. Trusting the marker here is what fixes the
// multi-line-collapse false negative — Claude hides the pasted body text.
// pasteConfirmed is a superset of the pasteCommitted exit above, so only
// the commitWaitMs timeout can fall through to the verification window.
if (pasteConfirmed(commitBuffer)) {
submitConfirmedPaste();
return;
}
// Markerless AND text not visible yet: give the prompt a short window to
// render (a late marker also counts as confirmed) before declaring it
// swallowed. Keep accumulating through the verification window.
const verifyStartedAt = Date.now();
beginVerify();
pasteVerifyTimer = setInterval(() => {
if (isFinalized()) {
clearInterval(pasteVerifyTimer);
pasteVerifyTimer = null;
clearPaste();
return;
}
const verifyElapsed = Date.now() - verifyStartedAt;
const confirmed = pasteConfirmed(pasteState.buffer);
// Submit once confirmed, or give up and retry/fail when the window expires.
if (confirmed || verifyElapsed >= PASTE_VERIFY_WINDOW_MS) {
clearInterval(pasteVerifyTimer);
pasteVerifyTimer = null;
if (confirmed) {
submitConfirmedPaste();
} else {
enterBackoff();
retryOrFailPaste();
}
}
}, PASTE_VERIFY_POLL_MS);
}
}, PASTE_MARKER_POLL_MS);
};
// handleData's own hook: accumulates PTY output while a paste attempt is
// awaiting its marker, verification, or retry backoff (see pasteState
// above). A no-op while idle.
const ingestChunk = (stripped) => {
if (pasteState.phase === 'idle' || !stripped) return;
// Tail-bounded: see POST_PASTE_BUFFER_CAP for why a few screens is all the
// commit predicates can use.
pasteState.buffer = (pasteState.buffer + stripped).slice(-POST_PASTE_BUFFER_CAP);
// The retry backoff used to be a blind spot: output was discarded after
// verification failed and before the next attempt began. A late marker or
// prompt echo still proves the existing paste landed, so submit it now and
// cancel the duplicate retry.
if (pasteState.phase === 'backoff' && pasteRetryTimer && pasteConfirmed(pasteState.buffer)) {
clearTimeout(pasteRetryTimer);
pasteRetryTimer = null;
submitConfirmedPaste();
}
};
// Stop everything this controller armed. Safe to call unconditionally (a run
// that ends before any paste was attempted just clears nulls) — see
// stopRunMachinery's own comment for why every teardown site must go through
// one chokepoint.
const cancel = () => {
if (pasteEnterTimer) { clearInterval(pasteEnterTimer); pasteEnterTimer = null; }
if (pasteVerifyTimer) { clearInterval(pasteVerifyTimer); pasteVerifyTimer = null; }
if (pasteRetryTimer) { clearTimeout(pasteRetryTimer); pasteRetryTimer = null; }
if (submitEnterTimer) { clearInterval(submitEnterTimer); submitEnterTimer = null; }
clearPaste();
};
return { sendPrompt, resubmit, ingestChunk, cancel };
}
/**
* Create the live session controller for one TUI agent run.
*
* Created BEFORE the PTY exists, because `handleData`/`handleExit` are what the
* launcher needs to open it. `attachSession()` is the second half: once a
* session id is known it arms prompt delivery, the provider-signal gates and
* the sentinel watcher. A run that never gets that far (a spawn throw) still
* finalizes correctly through `finish()`.
*
* @returns {{
* handleData: (data: unknown) => Promise<void>,
* handleExit: (event: object) => Promise<void>,
* markCommandInjected: () => void,
* isTerminal: () => boolean,
* finish: (outcome: object) => Promise<void>,
* attachSession: (session: { sessionId: string, pid: number|null }) => void,
* }}
*/
export function createTuiSessionController({
agentId,
task,
runId,
model,
provider,
securityScanGrant,
prompt,
tuiConfig,
cwd,
rawFile,
executionId,
laneName,
launchShape,
prOwnership,
mergeGateIsOwed,
spooler,
session,
persistence,
sentinel,
finalization,
probeMergeGatePr,
}) {
const { appendLine, pushRaw, flushRaw, drainLines, drainRaw, getOutputBuffer } = spooler;
// The login shell prints "command not found" for the binary it was asked to
// run — the SPAWNED one, which for a credential-bootstrap provider is the
// bootstrap CLI, not the harness `tuiConfig.command` names.
const commandName = tuiConfig.spawnCommand.split('/').pop();
/**
* Where this session is in its lifecycle — the one value every path that
* ends a run reads and writes.
*
* 'running' — live; finish() accepts a trigger.
* 'finishing' — a finish() call is mid-decision. The merge-gate contract
* check (#5876) adds awaits before that call can say whether
* it finalizes at all, so this is set SYNCHRONOUSLY to park a
* second trigger arriving in that window. Goes back to
* 'running' if the call decides not to finalize after all.
* 'finalized' — an outcome was recorded.
* 'abandoned' — PortOS went down mid-run (#3202): no outcome recorded, the
* worktree preserved for the resume.
*
* Named `sessionPhase`, not `phase`, because `abandonForHostShutdown` also
* writes a `phase: 'interrupted'` breadcrumb into the agent RECORD's
* metadata a few lines from where it sets this — two different phases with
* two different vocabularies, and collapsing their names is the mistake this
* value exists to undo.
*/
let sessionPhase = 'running';
/**
* Both end states are terminal: the run is over, and the sentinel watcher,
* the PTY data handler, the prompt and provider-signal timers and the paste
* controller must all become no-ops for the rest of this process's life. An
* abandoned run is no less over than a finalized one — it just has no
* outcome — so both stop everything.
*/
const isTerminal = () => sessionPhase === 'finalized' || sessionPhase === 'abandoned';
// A finish() call's args, parked because the session was already 'finishing'
// when it arrived — replayed if the call that was deciding ends up NOT
// finalizing (see finish()'s own comments on both).
let pendingFinish = null;
// Caps the merge-gate re-prompt (#5876) at once per run — a local closure
// counter is enough: the check only ever runs from this same live process,
// and a fresh spawn (a real retry) starts a fresh closure with its own flag.
let mergeGateReprompted = false;
let immediateFallbackAnalysis = null;
let terminalRefusal = null;
let executionInterruption = null;
const detectImmediateFallbackSignal = createImmediateFallbackSignalDetector();
const detectContentRefusal = createContentRefusalDetector();
const detectClaudeSessionLimitBanner = createClaudeSessionLimitBannerDetector();
let claudeLowPriorityPromptResubmitted = false;
const mayUseClaudeLowPriority = provider?.type === 'tui'
&& provider?.lowPriorityOnUsageLimit === true
&& isClaudeCommand(tuiConfig.command);
let lowPriorityCommandAttempted = false;
// Holds the wait-it-out window for a provider signal carrying a `graceMs`
// (agy's account-eligibility banner). The provider-signal timer below resolves
// its deadline and drives the re-submission cadence.
const selfClearingGate = createSelfClearingSignalGate();
// A local-GPU OOM kills the turn but leaves the TUI session holding the whole
// conversation, so it is nudged to carry on rather than re-prompted — see
// createOomNudgeGate for why this is a separate mechanism from the gate above.
// A dead turn in an intact session is nudged (not re-prompted) once the
// session goes quiet; a signal that outlasts its nudge budget fails over.
// One entry per signal, in detection order: handleData arms them, the
// provider-signal timer sends the due nudge. A new signal is one entry here.
// OOM: a local-GPU OOM — see createOomNudgeGate for why this is separate from
// the self-clearing gate above.
// truncation: a harness that cut the response off mid-generation (pi's TUI).
// capacity: a provider-side `model is at capacity` rejection (Codex); nudged
// only after a much longer quiet spell.
const silenceNudgeSignals = [
{
detect: createLocalRuntimeOomDetector(),
gate: createOomNudgeGate(),
pendingLine: () => LIFECYCLE_LINES.localOomPending(),
nudgeText: OOM_NUDGE_TEXT,
nudgeLabel: 'local-runtime OOM nudge',
nudgedLine: (attempt) => LIFECYCLE_LINES.localOomNudged({ attempt, max: OOM_NUDGE_MAX_ATTEMPTS }),
},
{
detect: createTruncatedResponseDetector(),
gate: createTruncationNudgeGate(),
pendingLine: () => LIFECYCLE_LINES.truncationPending(),
nudgeText: TRUNCATION_NUDGE_TEXT,
nudgeLabel: 'truncated-response nudge',
nudgedLine: (attempt) => LIFECYCLE_LINES.truncationNudged({ attempt, max: TRUNCATION_NUDGE_MAX_ATTEMPTS }),
},
{
detect: createModelAtCapacityDetector(),
gate: createModelCapacityNudgeGate(),
pendingLine: () => LIFECYCLE_LINES.capacityPending(),
nudgeText: CAPACITY_NUDGE_TEXT,
nudgeLabel: 'model-capacity nudge',
nudgedLine: (attempt) => LIFECYCLE_LINES.capacityNudged({ attempt, max: CAPACITY_NUDGE_MAX_ATTEMPTS }),
},
];
// agy quitting back to its launch shell (see createAgyResumeGate). Only a
// login-shell launch has a shell to fall back to; runner/direct PTYs die with
// agy and finish through handleExit instead.
const agyResumeGate = shapeHasLoginShell(launchShape) && isAntigravityCommand(tuiConfig.command) ? createAgyResumeGate() : null;
let agyResumeAwaitingComposer = false;
// A request the TUI keeps retrying and the provider never answers. Every
// reaper reads such a session as busy (the retry ladder repaints the screen),
// so without this the run holds its lane until the max-runtime ceiling — see
// createRetryStallGate.
const retryStallGate = createRetryStallGate();
// A tool-permission dialog nobody is present to answer. Declined on sight —
// the launch posture already decided the run's scope — then nudged along
// once the session goes quiet. See createToolPermissionGate.
const toolPermissionGate = createToolPermissionGate();
// The stall no detector can see, because nothing is on screen: a turn that
// ended with the task unfinished. Reads pure silence. See createStallNudgeGate.
const stallNudgeGate = createStallNudgeGate();
// A prompt whose paste landed but whose submit Enter was ignored: pressed
// again where it sits, and a run that never started is failed rather than
// parked. See createPromptSubmissionGate.
const promptGate = createPromptSubmissionGate({ promptMarkerCount: countPasteMarkers(stripAnsi(prompt)) });
// Guards ingestDoneSentinel to a single read. finish() is its only caller and
// is itself guarded by `sessionPhase`, so this is defensive — it pins the
// read-at-most-once invariant at the helper.
let sentinelIngested = false;
// A recovered sentinel is not completion until its contents have been read
// and promoted to the canonical path. If either step races the filesystem,
// keep the run alive and let the watcher retry instead of finalizing from a
// partial/ambiguous signal.
let sentinelRecoveryPending = false;
let hasStartedWorking = false;
// Guards the once-per-run `run.output` boundary (#4540). Kept separate from
// `firstOutputAt` / `hasStartedWorking`: both of those are also set by paths
// with no real output behind them, and a run that never spoke is exactly the
// run this boundary must not vouch for.
let firstOutputRecorded = false;
/**
* Record the run's first observed output, once. Called from the live PTY
* stream and from the exit-tail fallback — a durable runner can deliver a
* short-lived agent's entire output as `outputTail` on `tui:exit`, and that
* output is no less real for having lost the race with process exit.
*
* Not awaited: the live caller is on the hot output path, and
* `appendRunEvent` is a serialized queue that never rejects — blocking a
* terminal repaint on a telemetry write would be the wrong trade. The
* explicit key makes the append idempotent however the two callers race.
*/
const recordFirstOutput = (source) => {
if (firstOutputRecorded) return;
firstOutputRecorded = true;
persistence.appendRunEvent({
kind: 'run.output',
runId,
agentId,
taskId: task.id,
eventId: `output:${agentId}:${runId || 'no-run'}:first`,
data: { source },
});
};
let promptSentAt = null;
// When the submit-Enter is first written (NOT when the paste starts). Provider
// signal handling keys on this so a startup banner is not treated as a signal
// from a submitted prompt.
let promptSubmittedAt = null;
// Latches once codex prints its MCP-server boot banner during startup. A user
// with heavyweight interactive MCP servers in ~/.codex/config.toml (playwright
// via npx, a node_repl with startup_timeout_sec=120) makes codex spend tens of
// seconds — up to ~2min — booting them before its input box accepts a paste,
// far longer than the default 3-attempt paste-retry window. While latched, the
// paste-retry loop below extends its budget to MCP_BOOT_PASTE_DEADLINE_MS so a
// slow boot completes and the paste finally lands, instead of being killed
// `paste-not-rendered` mid-boot (incident 2026-07-10, agent-c5a26b40).
//
// Gated to codex ONLY (isCodexSession below). The extended budget and the
// failure message ("check your ~/.codex config") are codex-specific, and the
// claude path never blind-pastes during its own MCP boot — it waits for
// claude's positive input-ready signal first (createInputReadyTracker) — so it
// can't hit this failure mode. Observing every provider would let an unrelated
// TUI whose startup text happened to contain "starting mcp servers" inherit
// codex's 150s budget and its misleading codex-config guidance, breaking the
// "non-codex TUIs are unchanged" contract (codex review [P2]).
//
// One verdict for the session, through the shared predicate: it also gates the
// patient first paste (PASTE_COMMIT_PATIENCE_MS), and the two codex-only paste
// mechanisms must agree on what codex is. It keys on `command` (the harness),
// not `spawnCommand` — a credential-bootstrap wrap makes the latter the
// bootstrap CLI.
const isCodexSession = isCodexCommand(tuiConfig.command);
const isOpencodeSession = isOpencodeCommand(tuiConfig.command);
const codexModelRejectionGate = isCodexSession ? createCodexModelRejectionGate() : null;
// Latches once codex's composer placeholder paints — the positive "the input
// box exists" signal the idle heuristic lacks. See
// CODEX_COMPOSER_READY_PATTERN; consumed by the idle paste branch below.
let codexComposerReady = false;
const mcpBoot = createMcpBootTracker();
// Tracks claude's interactive input-readiness (footer chrome) and its first-run
// folder-trust gate. Gates the prompt paste for the claude TUI so we never
// paste into a startup banner, a trust menu, or a returned shell prompt.
// agy enables bracketed paste on alt-screen entry, before its composer (and
// before its trust gate) exists, so it needs the extra composer-footer gate.
// OpenCode also enables paste mode before the composer. Require its
// placeholder and a settled repaint so terminal queries cannot trigger paste.
// Runner/direct shapes pty.spawn the TUI itself (no launch shell), so the
// tracker must not wait for a shell paste-mode OFF that will never come.
const inputReady = createInputReadyTracker({
...(isOpencodeSession ? { readyTextPattern: OPENCODE_INPUT_READY_PATTERN } : {}),
...(isAntigravityCommand(tuiConfig.command) ? { readyTextPattern: AGY_INPUT_READY_PATTERN } : {}),
launchShape,
});
// Which of the TUI's startup dialogs this session has already answered. One
// record instead of four sibling booleans; the arms themselves live in
// answerStartupDialogs, so a provider's next dialog is a row there rather than
// a fifth flag here.
const dialogAnswers = createStartupDialogAnswers();
// True once shell.js actually injects the `claude` command (after its
// round-trip readiness probe). The probe runs its OWN shell command first,
// which toggles bracketed-paste mode and would otherwise advance the
// input-ready tracker (sawCommandRun + pasteModeOn) while still at the bare
// shell prompt — pasting the prompt into claude's startup banner. Gating
// observation on this discards every pre-command toggle.
let commandInjected = false;
let firstOutputAt = null;
let lastOutputAt = Date.now();
let sessionId = null;
// The runner's `tui:output` socket messages are live telemetry. An OpenCode
// CLI that prints one startup error and exits can race that delivery, while
// its `tui:exit` arrives reliably enough to finish the session. Track whether
// we received any ordinary chunk so the runner-provided exit tail is spooled
// only as a recovery path, never duplicated into raw.txt.
let receivedTuiOutput = false;
// The paste-attempt / submit-Enter machinery (pasteState, pasteEnterTimer,
// pasteVerifyTimer, submitEnterTimer) lives in createPasteRetryController
// rather than this closure — see its own comment for why that cluster is
// separated out. Created by attachSession() once sessionId/pid are known, and
// torn down from stopRunMachinery via `pasteController?.cancel()`.
let pasteController = null;
// The two intervals and the sentinel watcher this run arms, owned HERE rather
// than parked on the active-run record: `stopRunMachinery` is the only place
// that clears them, and reading them back off a map entry made a missing entry
// silently equivalent to "nothing to stop".
let promptTimer = null;
let providerSignalTimer = null;
let claudeLowPriorityResubmitTimer = null;
let doneSentinelWatcher = null;
let sentinelRecoveryRetryTimer = null;
const streamingStrip = createStreamingAnsiStripper();
// Has the agent written its completion sentinel? One predicate for the 2s
// watcher and ingestDoneSentinel so "the run finished" can't mean subtly
// different things in two places.
const sentinelPresent = () => sentinel.exists();
// Read the `.agent-done` sentinel (if present) and append its markdown task
// summary line-by-line into the agent's output so downstream consumers
// (extractFinalSummary, persistCompletionSummary, completion hooks, the agent
// card, output.txt) get the resolution. Called only from finish() (the single
// finalize chokepoint); idempotent via `sentinelIngested` so it reads at most
// once. Capped at 4 KB so an agent that pasted the whole diff into the
// sentinel can't blow up the record.
//
// Returns the sentinel's `summary` text (or null on a second call / no
// sentinel / an empty summary) — the merge-gate contract check below reads
// this same return value rather than re-reading the file a second time.
const ingestDoneSentinel = async () => {
if (sentinelIngested) return null;
if (!sentinelPresent()) return null;
sentinelIngested = true;
const sentinelSourcePath = sentinel.resolvedPath?.();
let sentinelReadSucceeded = true;
let contents = await sentinel.read().catch(err => {
sentinelReadSucceeded = false;
console.error(`❌ ingestDoneSentinel readFile failed: ${err.message}`);
return '';
});
// A terminal-copy recovery name is accepted only by the run-scoped
// sentinel access. Promote its contents to the canonical name before the
// shared finalization/output-hook path reads the sentinel again, so a
// structured completion has the same behavior as an exact write.
let sentinelValidated = sentinelReadSucceeded;
if (sentinelReadSucceeded && sentinelSourcePath && sentinelSourcePath !== sentinel.path) {
if (typeof sentinel.promote !== 'function') {
sentinelValidated = false;
} else {
sentinelValidated = await sentinel.promote(contents).catch(err => {
console.error(`❌ ingestDoneSentinel canonical promotion failed: ${err.message}`);
return false;
});
if (sentinelValidated) {
let canonicalReadSucceeded = true;
const canonicalContents = await sentinel.read().catch(err => {
canonicalReadSucceeded = false;
console.error(`❌ ingestDoneSentinel canonical read failed: ${err.message}`);
return '';
});
sentinelValidated = canonicalReadSucceeded;
if (sentinelValidated) contents = canonicalContents;
}
}
}
if (!sentinelValidated) {
sentinelIngested = false;
sentinelRecoveryPending = true;
return null;
}
// A programmatic-I/O task type writes a JSON `{ summary, payload }` sentinel;
// append only the human `summary` to the agent output (the structured
// `payload` is consumed separately by the task type's processTaskOutput hook,
// read mode-agnostically in finalizeAgent). A legacy plain-markdown sentinel
// parses back as its own text, so this is a no-op change for existing types.
const { summary } = parseSentinelPayload(contents);
if (!summary) return null;
// Shared constant, not a literal: `extractAgentSummary` anchors the PR-body
// extraction on this exact line to tell the agent's summary apart from the
// lifecycle telemetry above it. Reword it here only, and the noise returns.
appendLine(SENTINEL_COMPLETION_MARKER);
const truncated = summary.length > 4096 ? `${summary.slice(0, 4096)}\n…[truncated]` : summary;
for (const line of truncated.split('\n')) appendLine(line);
return summary;
};
// Sentinel-file watcher. The agent's prompt instructs it to write
// .agent-done in the workspace after running /simplify + /do:pr and then
// stop (it does NOT `/quit` — that is a UI command it can't invoke). This
// watcher is the PRIMARY finalize path: it fires finish() shortly after the
// sentinel appears, and finish()'s own cleanup kills the still-running TUI
// session. The actual sentinel READ happens in finish() (via
// ingestDoneSentinel) so the resolution is captured no matter which path
// finalizes. A normal shell exit or explicit provider failure handles
// agents that do not write the sentinel.
//
// `sentinel.watch` is one-shot (it detects, closes itself, then calls back) —
// so a run whose merge-gate check re-prompts and deletes the sentinel to
// await a SECOND completion needs a brand-new watcher, not a re-trigger of
// this one. Factored out so both call sites build the exact same watcher.
const armSentinelWatcher = () => sentinel.watch(async () => {
if (isTerminal()) return;
await finish({ success: true, exitCode: 0, reason: 'agent-signaled-done' });
});
const scheduleSentinelRecoveryRetry = () => {
if (sentinelRecoveryRetryTimer || isTerminal()) return;
sentinelRecoveryRetryTimer = setTimeout(() => {
sentinelRecoveryRetryTimer = null;
if (isTerminal() || terminalRefusal) return;
doneSentinelWatcher?.();
doneSentinelWatcher = armSentinelWatcher();
}, SENTINEL_RECOVERY_RETRY_MS);
};
/**
* Merge Gate contract check (#5876) — runs on a successful sentinel, before
* ANY teardown, for a run whose own task shape said it owed a merge. Asks
* the forge whether the PR this run opened actually landed and, if it is
* still open with no blocker stated in the agent's own summary, re-pastes
* one corrective nudge into the still-attached session instead of paying
* for a cold recovery agent (`agentRepoStateVerification.js`) to do the
* same merge later. See mergeGateContract.js for the decision table.
*
* The caller (runFinishDecision) checks `mergeGateIsOwed` and the
* once-per-run `mergeGateReprompted` cap synchronously before calling, so a
* run that owes no merge finalizes without an extra await in its path.
*
* @returns {Promise<boolean>} true when a re-prompt went out — the caller
* must NOT finalize this call; false means finalize normally.
*/
const checkMergeGateCompliance = async (summary) => {
const prProbe = await probeMergeGatePr();
const verdict = resolveMergeGateVerdict({ prProbe, summary });
if (verdict !== 'needs-reprompt') return false;
if (terminalRefusal) return false;
if (!pasteController?.resubmit({ text: buildMergeGateReprompt(prProbe.prUrl || '<PR_URL>'), label: 'merge-gate contract nudge' })) {
// Session is already gone — nothing to nudge; fall through to finalize.
return false;
}
mergeGateReprompted = true;
// Reopen the completion window: a fresh `.agent-done` write after the
// nudge must be re-ingested (not silently skipped by the once-only guard)
// and needs a brand-new watcher — the original already closed itself on
// its first (this) detection.
sentinelIngested = false;
await sentinel.remove();
doneSentinelWatcher = armSentinelWatcher();
appendLine(LIFECYCLE_LINES.mergeGateReprompted());
emitLog('warn', `🔁 Merge-gate contract nudge sent for ${agentId} — PR still OPEN with no stated blocker`, { agentId });
return true;
};
/**
* Stop everything this run armed, and hand back the agent record so the
* caller doesn't need a second map lookup.
*
* Shared by the two paths that end a run — `finish()` (records an outcome) and
* `abandonForHostShutdown()` (records none). Every timer here is created inside
* this closure, so a teardown site that falls behind leaks an interval holding
* the closure and the PTY handle alive, which is exactly the drift a single
* teardown prevents.
*/
const stopRunMachinery = () => {
if (providerSignalTimer) { clearInterval(providerSignalTimer); providerSignalTimer = null; }
if (promptTimer) { clearInterval(promptTimer); promptTimer = null; }
if (claudeLowPriorityResubmitTimer) { clearTimeout(claudeLowPriorityResubmitTimer); claudeLowPriorityResubmitTimer = null; }
if (sentinelRecoveryRetryTimer) { clearTimeout(sentinelRecoveryRetryTimer); sentinelRecoveryRetryTimer = null; }
doneSentinelWatcher?.();
doneSentinelWatcher = null;
// Cancels the paste-attempt timers and releases the post-paste accumulator
// even when the run ends mid-paste-window — see
// createPasteRetryController's own cancel() for why each is safe to clear
// unconditionally (a run that ends from elsewhere — shell-exit,
// command-not-found, user termination, a host restart — never gets a
// chance to let its own cleanup path run).
pasteController?.cancel();
return persistence.readRunRecord();
};
/**
* Everything this run held, released in one place: its own `.agent-done`
* sentinel, the shared completion dispatch, the pid registration, the
* active-run entry, and the PTY session.
*
* Called from `finish()`'s `finally`, so it must run even when `finalizeAgent`
* threw — a memory-extraction crash would otherwise strand the worktree and
* the shell session on disk.
*/
const releaseRunResources = async ({ agentData, cleanupSuccess, prClaimVerified, branchProvenEmpty }) => {
// Pipeline progression → worktree cleanup with the PR disposition →
// sentinel removal → retry-hold release, in the one owner every completion
// path shares. Caught so a throw there cannot skip the in-memory teardown
// below — this runs off a PTY exit, outside any request lifecycle.
await finalization.runCompletionCleanup({
agentId,
task,
success: cleanupSuccess,
prOwnership,
prClaimVerified,
branchProvenEmpty,
outputBuffer: getOutputBuffer(),
}).catch(err => {
persistence.markUnsettled?.();
emitLog('warn', `TUI completion cleanup failed for ${agentId}: ${err.message}`, { agentId });
});
if (sentinel.cleanup) {
await sentinel.cleanup().catch(err => {
persistence.markUnsettled?.();
emitLog('warn', `TUI recovery sentinel cleanup failed for ${agentId}: ${err.message}`, { agentId });
});
}
// Stop this finished writer before releasing its execution binding. The
// adapter then awaits deterministic retirement; no scheduled wake is owed.
if (sessionId && session.isAlive(sessionId)) await session.kill(sessionId);
await persistence.releaseRunRecord(agentData?.pid ?? null);
};
/**
* Decide what one finish() call does, as a single explicit verdict. Runs
* while `sessionPhase` is 'finishing'; finish() interprets the result and
* owns every phase transition and the parked-trigger replay, so a new exit
* here cannot strand the run in 'finishing' with its timers already cleared.
*
* { type: 'abandon' } — PortOS is going down; record no outcome.
* { type: 'finalize' } — record the outcome.
* { type: 'retry-later' | 'reprompt', replayParked } — NOT finalizing:
* the session goes back to 'running', and a trigger parked during this
* decision is replayed per `replayParked`:
* 'always' — replay it; it may be the only news the session died.
* 'if-no-sentinel' — replay it only while no sentinel is present. A
* present sentinel means the agent finished, so a
* late exit carries no news; the recovery retry
* re-reads that sentinel instead.
*
* Order matters: `ingestDoneSentinel` runs before `checkMergeGateCompliance`,
* which mutates the sentinel state (clears `sentinelIngested`, deletes the
* file, re-arms the watcher) — so finish() reopens the phase only after this
* whole function settles.
*/
const runFinishDecision = async ({ success, reason }) => {
if (terminalRefusal) return { type: 'finalize' };
// PortOS is going down. Whatever path got here — the PTY exiting under
// TreeKill, a provider-signal failure, a paste that failed because the shell died —
// the cause is the host restart, not the agent, so there is no outcome to
// record. Abandoning instead of finalizing is what keeps an interrupted run
// from being written down as completed AND keeps its worktree (which
// finalize's cleanup would delete) intact for the resume (#3202).
//
// Three exceptions keep their normal path. An agent that already wrote its
// `.agent-done` sentinel has given a valid completion signal. A run the user
// terminated must reach finalizeAgent to be recorded `user-terminated` —
// abandoning it would leave the record `running` with no such mark, and boot
// recovery's user-terminated skip would miss it and resurrect the run. And a
// run the user paused already has its own don't-finalize branch in finish(),
// which owns the paused bookkeeping (pid unregister, active-run delete).
if (finalization.shouldAbandonRun({ agentId, sentinelPresent: sentinelPresent() })) {
return { type: 'abandon' };
}
// Ingest the .agent-done sentinel BEFORE any teardown decision, so its
// markdown summary lands in outputBuffer/output.txt regardless of WHICH
// path finalized the agent, AND so the merge-gate contract check right
// below reads the same text without a second file read. The completion
// workflow writes the sentinel and stops; the 2s doneSentinelWatcher is
// what normally calls finish(). Idempotent via `sentinelIngested`.
const sentinelSummary = await ingestDoneSentinel();
if (terminalRefusal) return { type: 'finalize' };
if (sentinelRecoveryPending) {
sentinelRecoveryPending = false;
scheduleSentinelRecoveryRetry();
return { type: 'retry-later', replayParked: 'if-no-sentinel' };
}
// Merge Gate contract check (#5876): only for a run that actually
// succeeded AND signaled that success via a real `.agent-done` summary —
// an ordinary clean exit with no sentinel (or one with an empty summary)
// is not the "the agent believes its Merge Gate is done" signal this
// reads; re-prompting THAT would paste into a shell whose TUI child may
// already be gone, parking the run on a nudge that can never land.
// True (and this call does NOT finalize) exactly once, when the run owed
// a merge, the PR is open, and the summary names no blocker — see
// mergeGateContract.js for the full decision table. The re-prompt expects
// a fresh completion signal; a trigger that arrived while this was
// deciding is the only thing that could say the session died meanwhile.
//
// Never when a PTY exit (`shell-*`) is the deciding trigger: a dead
// session cannot answer the nudge, and `tui:exit` is already consumed, so
// nothing would ever finish the run. `resubmit()` cannot be the liveness
// test — a runner proxy accepts writes after its PTY died (#11861). The
// still-open PR takes the post-finalize merge path instead.
const sessionExited = reason?.startsWith('shell-');
if (success && sentinelSummary !== null && mergeGateIsOwed && !mergeGateReprompted && !sessionExited
&& await checkMergeGateCompliance(sentinelSummary)) {
return { type: 'reprompt', replayParked: 'always' };
}
return { type: 'finalize' };
};
const finish = async ({ success, exitCode = 0, error = null, reason = 'completed' }) => {
// A terminal check alone used to be the whole re-entrancy guard, safe
// because it was set SYNCHRONOUSLY as this function's first act. The
// merge-gate check needs `ingestDoneSentinel`'s summary before it can
// decide whether to finalize at all, which pushes the terminal transition
// past several awaits — wide enough for a second trigger (the shell exiting
// right after the sentinel appears) to also pass the gate before the first
// call sets it, double-firing `finalizeAgent`. 'finishing' closes that
// window synchronously while staying NON-terminal, which is what
// `pasteController.resubmit()` depends on: a re-prompt must still be
// possible while this call is deciding.
//
// A trigger parked here while the first call is mid-decision is not
// discarded outright: the decision's `replayParked` policy says whether
// it is replayed once that call settles on "not finalizing after all".
if (isTerminal()) return;
if (sessionPhase === 'finishing') {
pendingFinish = { success, exitCode, error, reason };
return;
}
sessionPhase = 'finishing';
let decision = await runFinishDecision({ success, reason });
// A refusal observed while a sentinel/probe was awaited outranks its result.
if (terminalRefusal) {
decision = { type: 'finalize' };
success = false;
exitCode = 1;
error = terminalRefusal.message;
reason = 'content-refusal';
}
if (decision.type === 'abandon') {
await abandonForHostShutdown();
return;
}
// Every other non-finalizing verdict shares this ONE epilogue: reopen the
// re-entrancy gate for the next completion signal, then replay or drop the
// parked trigger per the verdict's policy. A verdict without a policy
// replays — the safe default, since a dropped trigger can park the run.
if (decision.type !== 'finalize') {
sessionPhase = 'running';
const parked = pendingFinish;
pendingFinish = null;
const replay = parked && (decision.replayParked !== 'if-no-sentinel' || !sentinelPresent());
if (replay) return finish(parked);
return;
}
sessionPhase = 'finalized';
const agentData = stopRunMachinery();
// Drain pending parsed lines AND raw chunks before the final state
// writes so completion events don't beat the last output batch to disk.
// Non-fatal: the phase is already 'finalized', so a rejected drain (e.g.
// BACKUP_SNAPSHOT_BUSY while a long backup holds the snapshot cut) must not
// skip the teardown below — a later exit/Kill would find the run terminal
// and no-op, stranding the lane, the PTY and the worktree until restart.
for (const [drain, label] of [[drainLines, 'parsed output'], [drainRaw, 'raw PTY spool']]) {
await drain().catch(err => {
persistence.markUnsettled?.();
emitLog('warn', `TUI ${label} drain failed for ${agentId}: ${err.message}`, { agentId });
});
}
// The teardown both in-process spawners share: paused early return, then
// the host-shutdown abandon gate, the user-termination consume, the final
// success/error derivation, and the lane release — done before the
// potentially-slow error-analysis / completeAgent / processAgentCompletion
// chain, since lanes serialize related work. See agentRunFinalize.js.
//
// The abandon gate is consulted a second time here on purpose: the gate at
// the top of runFinishDecision() ran before ingestDoneSentinel and the merge-gate probe,
// which can take seconds, and a host restart that begins in that window is
// still an interruption rather than an outcome (#3202).
const duration = Date.now() - (agentData?.startedAt || Date.now());
// Read ONCE: the shared finalize decides the run's outcome from it and the
// diagnostic below reports on it, and two reads could disagree about the
// same run.
const wroteSentinel = sentinelPresent();
const finalizeOutcome = finalization.finalizeRunCommon({
agentId,
agentData,
success,
error,
exitCode,
duration,
executionId,
laneName,
sentinelPresent: wroteSentinel,
errorExecutionFallback: `TUI agent ended: ${reason}`,
});
if (finalizeOutcome.outcome === 'paused') { await persistence.releaseRunRecord(agentData?.pid ?? null); return; }
if (finalizeOutcome.outcome === 'abandoned') {
await abandonForHostShutdown();
return;
}
const { finalSuccess, finalError, terminatedByUser } = finalizeOutcome;
// Name the path the run was supposed to write when it ends without one.
// The sentinel is the PRIMARY finalize path for a TUI, so reaching here
// without it means the run either died or talked itself out of the write —
// and the second shape is otherwise silent, leaving an ordinary "TUI agent
// ended" line and nothing an operator can grep for (#7405; the prompt-side
// contract is SENTINEL_WRITE_PERMISSION_NOTE). Deliberately NOT gated on
// `finalSuccess`: a run that stalls on a question is reaped as a failure,
// which is exactly the case this exists to name. Placed after the shared
// finalize, so the paused and host-abandoned paths have already returned
// and only a user kill — a legitimate no-sentinel exit — needs excluding.
// A CLI run is out of scope: it signals completion by exiting, so the same
// warn in `agentRunFinalize` would fire on every headless run.
// A merge-gate nudge DELETES the sentinel this run already wrote, so
// "never wrote one" would be a false reading of that path — and the
// remedy it points at is the opposite one (the nudge never landed).
if (sentinel.path && !terminatedByUser && !wroteSentinel) {
emitLog('warn', missingSentinelLogMessage({
agentId,
reason,
sentinelPath: sentinel.path,
mergeGateReprompted,
command: tuiConfig.command,
providerId: provider?.id,
}), { agentId });
}
// output.txt has already been incrementally appended via the spooler;
// do NOT writeFile() it from the output buffer at finalize — the buffer is
// capped at OUTPUT_BUFFER_CAP and would silently truncate the on-disk
// record for long runs. The append-only stream is the authoritative copy.
//
// For failure analysis: resolveErrorAnalysis reads only the tail of the raw
// PTY spool (the analyzer strips ANSI and windows it to the last ~200 lines /
// 16K chars) and falls back to the capped output buffer if the spool is
// missing/unreadable. Successful runs skip the read entirely. raw.txt stays
// in agentDir alongside output.txt as the persistent record of the agent's
// full PTY transcript.
const errorAnalysis = await finalization.resolveErrorAnalysis({
finalSuccess,
rawFile,
fallbackText: getOutputBuffer(),
task,
model,
immediateFallbackAnalysis,
// The finalize path's own verdict outranks a keyword sweep of the
// transcript when the analyzer recognizes it (COMPLETION_REASON_ANALYSES).
completionReason: reason,
completionError: finalError,
});
// `prOwnership` was resolved once, up front, by the adapter, so the
// merge-gate contract check above and the completion dispatch below read the
// same answer (#3733); see `resolvePrOwnership` for why finalize's
// `prClaimExpected` and cleanup's `agentOpensOwnPr` are two predicates (#3358).
//
// Whether finalize's check ACTUALLY produced a forge answer, filled in from
// its return below. Deliberately not `prClaimExpected`: finalize substitutes
// `{ok:true}` for a user-terminated run and for a check that threw, and a
// throw from finalize itself skips the assignment entirely — in all three
// cases nothing was verified, so cleanup must ask rather than stand down.
let prClaimVerified = false;
let branchProvenEmpty = false;
// try/finally so a throw from finalizeAgent (e.g. processAgentCompletion
// hook crash) still runs the local cleanup — sentinel removal, the shared
// completion dispatch (pipeline, worktree, retry hold), pid unregister,
// active-run delete, session kill. Without this, a memory-extraction
// crash would strand the worktree and the shell session on disk.
// The verdict finalizeAgent actually persisted. A PR-claim downgrade (#3358)
// must reach cleanup too — cleaning up as a success removes the worktree and
// deletes the local branch, destroying the state the retry needs. Left at
// `finalSuccess` if finalize threw before returning (the pre-existing
// best-effort posture).
let cleanupSuccess = finalSuccess;
try {
const finalizeVerdict = await finalization.finalizeAgent({
agentId,
task,
runId,
providerId: provider?.id,
success: finalSuccess,
exitCode,
duration,
outputBuffer: getOutputBuffer(),
errorAnalysis,
terminatedByUser,
error: finalError || undefined,
completionReason: reason,
...(executionInterruption ? { executionInterruption } : {}),
workspacePath: cwd,
prExpected: prOwnership.prClaimExpected,
// The run window the commit criterion is evaluated against (#3637).
startedAt: agentData?.startedAt ?? null,
});
if (finalizeVerdict && typeof finalizeVerdict.success === 'boolean') cleanupSuccess = finalizeVerdict.success;
if (finalizeVerdict?.prClaimVerified === true) prClaimVerified = true;
if (finalizeVerdict?.branchProvenEmpty === true) branchProvenEmpty = true;
} catch (err) {
persistence.markUnsettled?.();
throw err;
} finally {
await releaseRunResources({ agentData, cleanupSuccess, prClaimVerified, branchProvenEmpty });
}
};
/**
* Abandon the run because PortOS itself is going down (#3202).
*
* Deliberately NOT `finish()`: finalizing here would record an outcome for a
* run that never reached one, and its cleanup path removes the `.agent-done`
* sentinel and hands the worktree to `cleanupAgentWorktree` — destroying exactly
* the state a resume needs. So this only stops the machinery and flushes what
* was captured; the agent record stays `running` and the worktree stays on
* disk. The next boot's orphan sweep reads the host-shutdown marker, sees this
* agent named in it, and requeues the task as *interrupted* — resumable, and
* without charging it orphan-retry budget.
*
* Moves the session to the terminal 'abandoned' phase so every other path
* (provider-signal timer, sentinel watcher, paste retry) becomes a no-op for
* the rest of this process's life — a full stop, under the name that says no
* outcome was recorded.
*/
const abandonForHostShutdown = async () => {
// No terminal guard: finish() — the only caller — already returned if the
// session had reached one, and this sets it below.
sessionPhase = 'abandoned';
stopRunMachinery();
appendLine(LIFECYCLE_LINES.hostRestarted());
emitLog('info', `TUI agent ${agentId} interrupted by a PortOS host restart — preserved for resume`, { agentId, phase: 'interrupted' });
// Concurrent, not sequential: nothing awaits this function (it runs off the
// PTY-exit handler, racing the shutdown handler's own process.exit), so the
// shorter the critical path the more of the transcript actually lands. The
// three targets are independent — output.txt + the state record, raw.txt, and
// the metadata patch — and the two that share the state lock still serialize
// on it. `phase` is a breadcrumb only: the record stays `running` on purpose,
// because boot recovery owns the transition.
await withBackupAssetPublication(() => Promise.all([
drainLines().catch(() => {}),
drainRaw().catch(() => {}),
persistence.updateAgent(agentId, { metadata: { phase: 'interrupted', interruptedBy: HOST_SHUTDOWN_REASON } })
.catch(err => emitLog('warn', `Could not mark TUI agent ${agentId} interrupted: ${err.message}`, { agentId })),
]));
// NOTE: the active-run entry is intentionally left in place — the shutdown
// handler reads that map to name the agents in the host-shutdown marker, and
// there is no reason to shrink it on the way out.
};
// The single fail-over verdict, reached from two places: a signal with no grace
// window (immediate) and a grace window that expired without recovery. Sharing
// it keeps the deferred path provably identical to the immediate one.
//
// `immediateFallbackAnalysis` is set HERE and not at arm time on purpose — it is
// read at finalize by resolveErrorAnalysis, so stamping it when the window opens
// would tag a run that went on to RECOVER with the banner as its error.
const failOverToFallback = (analysis) => {
immediateFallbackAnalysis = analysis;
appendLine(LIFECYCLE_LINES.providerFallbackSignal({ message: analysis.message }));
return finish({
success: false,
exitCode: 1,
error: analysis.message || 'Provider requires fallback',
reason: 'fallback-signal'
});
};
/**
* Re-deliver the prompt while a self-clearing provider signal's window is open.
*
* agy's eligibility banner is the REJECTION of a submission, not a spinner over
* an in-flight one: the prompt is discarded, the composer goes back to empty
* and the session sits at its idle footer indefinitely. So the window can only
* clear if something re-asks — hence a plain re-paste + submit, which is also
* literally what the banner instructs ("Please try again shortly").
*
* Re-pasting the WHOLE prompt is correct precisely because the composer is
* empty; the gate's 20s cadence keeps this well clear of the reflow that
* follows the rejected paste. Nothing here re-runs paste VERIFICATION: this
* prompt already rendered once (its rejection is why we're here), and routing
* back through `attemptPaste` would spend the startup paste-retry budget and
* let a verification hiccup mid-handshake finalize the run as
* `paste-not-rendered`.
*/
const resubmitAfterSignal = () => {
// A banner that paints during startup (before the prompt was ever submitted)
// has nothing to re-send — the ordinary paste path still owns first delivery.
if (isTerminal() || terminalRefusal || !promptSubmittedAt) return;
const attempt = selfClearingGate.takeResubmit(Date.now());
if (!attempt) return;
// Only claim the re-submission that actually went out — a false return means
// the session is already gone, and a transcript line saying otherwise would
// send a post-mortem looking for a paste the provider never received.
if (pasteController?.resubmit()) {
appendLine(LIFECYCLE_LINES.handshakeResubmitted({ attempt }));
}
};
// `/low-priority` is a hidden Claude Code TUI command, not a CLI startup
// argument or a supported --print/SDK prompt. On an opted-in session
// limit, enable the mode and then re-submit the rejected task. A later
// limit after that re-submit means the mode was unavailable or exhausted.
// A session limit always consumes the chunk: the caller returns afterwards.
const handleClaudeSessionLimit = async (sessionLimit) => {
if (lowPriorityCommandAttempted) {
if (claudeLowPriorityPromptResubmitted) await failOverToFallback(sessionLimit);
return;
}
if (!mayUseClaudeLowPriority) {
await failOverToFallback(sessionLimit);
return;
}
lowPriorityCommandAttempted = true;
let submitted = false;
try {
submitted = session.write(sessionId, `/low-priority${SUBMIT_KEY}`) !== false;
} catch (err) {
emitLog('warn', `TUI agent ${agentId} could not send Claude low-priority command: ${err?.message || err}`, { agentId });
}
if (submitted) {
appendLine(LIFECYCLE_LINES.claudeSessionLimit());
claudeLowPriorityResubmitTimer = setTimeout(() => {
claudeLowPriorityResubmitTimer = null;
if (sessionPhase !== 'running') return;
let promptResubmitted = false;
try {
promptResubmitted = !!pasteController?.resubmit({ label: 'Claude low-priority continuation' });
} catch (err) {
emitLog('warn', `TUI agent ${agentId} could not re-submit after Claude low-priority: ${err?.message || err}`, { agentId });
}
if (promptResubmitted) {
claudeLowPriorityPromptResubmitted = true;
appendLine(LIFECYCLE_LINES.claudeLowPriorityResubmitted());
return;
}
failOverToFallback({
...sessionLimit,
message: 'Claude Code low-priority mode was enabled, but the task could not be re-submitted',
}).catch((err) => emitLog('error', `TUI agent ${agentId} low-priority re-submit fallback failed: ${err?.message || err}`, { agentId }));
}, CLAUDE_LOW_PRIORITY_RESUBMIT_DELAY_MS);
} else {
await failOverToFallback({
...sessionLimit,
message: 'Claude Code session limit reached and /low-priority could not be sent',
});
}
};
const handleData = async (data) => {
// EventEmitter listeners run outside the request lifecycle — a rejection
// here on Node ≥15 will kill the process unless we catch locally. The
// outer try/catch routes failures through emitLog (best-effort log, no
// re-throw) and leaves the agent run intact.
// See skill: nodejs-async-event-listener-unhandled-rejection.
try {
// node-pty can deliver chunks between finalize starting and the shell
// session being killed in finalize's finally block. Once the run has
// reached a terminal phase, drop them — appending to the spool, growing
// the post-paste accumulator, or mutating timing state is all pointless
// after finish has settled.
if (isTerminal() || terminalRefusal) return;
// node-pty surfaces output as already-decoded UTF-8 strings via
// shellService's onData hook (StringDecoder handles multi-byte
// boundaries internally), so `data` is a string here in normal use.
// The String(...) coerces defensively in case a future caller wires
// a Buffer-emitting encoding.
const text = typeof data === 'string' ? data : String(data);
if (text) receivedTuiOutput = true;
const stripped = streamingStrip(text);
pushRaw(text);
// Accumulate the ANSI-STRIPPED chunk (not the raw text): the paste marker
// is rendered with absolute-column cursor moves between glyphs, so it only
// matches after stripping (see countPasteMarkers). Appending raw text here
// — as this did before #1229 — left the marker unmatchable and the fast
// path dead.
pasteController?.ingestChunk(stripped);
// Observe claude's input-readiness / folder-trust chrome (before the
// paste). Raw `text` carries the bracketed-paste-mode toggles; `stripped`
// carries the visible footer/trust text. Only AFTER the CLI command is
// injected — earlier toggles belong to shell startup and the readiness
// probe, not to claude.
if (!promptSentAt && commandInjected) inputReady.observe(text, stripped);
// Latch codex's MCP-server boot banner during startup (codex sessions only;
// before the prompt is submitted, so codex's own boot chrome — not the
// echoed prompt — is what trips it). Gates the extended, boot-aware
// paste-retry budget below. Observing until promptSubmittedAt (set only on a
// CONFIRMED paste) means a banner that arrives AFTER an early swallowed paste
// still latches — the swallowed paste never sets promptSubmittedAt.
if (isCodexSession && !promptSubmittedAt && stripped && !mcpBoot.active) mcpBoot.observe(stripped);
// Same window as the MCP-boot latch, and for the same reason: only codex's
// own startup chrome (never the echoed prompt) may trip it.
if (isCodexSession && !codexComposerReady && !promptSentAt && commandInjected && stripped
&& CODEX_COMPOSER_READY_PATTERN.test(stripped)) codexComposerReady = true;
const now = Date.now();
// A policy refusal ends this request before any recovery/nudge machinery.
const refusal = isCodexSession && promptSubmittedAt ? detectContentRefusal(text) : null;
if (refusal) {
terminalRefusal = refusal;
executionInterruption = { category: refusal.category, source: 'provider', at: new Date(now).toISOString() };
immediateFallbackAnalysis = refusal;
await persistence.updateAgent(agentId, { metadata: {
executionInterruption,
} }).catch(err => emitLog('warn', `Could not persist refusal for ${agentId}: ${err.message}`, { agentId }));
appendLine(LIFECYCLE_LINES.contentRefused());
await finish({ success: false, exitCode: 1, error: refusal.message, reason: 'content-refusal' });
return;
}
if (promptSubmittedAt) codexModelRejectionGate?.observe(stripped);
promptGate.observe(stripped, now);
// Startup-idle detection (the promptTimer's non-inputReady branch below)
// reads lastOutputAt/firstOutputAt to decide the TUI has gone quiet and is
// ready for the prompt paste. Gate them on commandInjected for the same
// reason inputReady.observe is gated above: the shell-level readiness
// probe (posix printf / PowerShell Write-Output) round-trips its own
// marker through this same onData hook BEFORE the real CLI command is
// injected, so counting it would seed the idle clock from probe echo
// instead of the CLI's own output — falsely satisfying "quiet" while a
// still-loading CLI (e.g. PowerShell's heavier startup) hasn't painted
// anything yet, and pasting the prompt into it.
if (commandInjected) {
lastOutputAt = now;
if (firstOutputAt === null) firstOutputAt = lastOutputAt;
}
recordFirstOutput('tui-pty');
if (isClaudeCommand(tuiConfig.command) && promptSubmittedAt) {
const sessionLimit = detectClaudeSessionLimitBanner(stripped);
if (sessionLimit) {
await handleClaudeSessionLimit(sessionLimit);
return;
}
}
if (!hasStartedWorking) {
hasStartedWorking = true;
await persistence.updateAgent(agentId, { metadata: { phase: 'working' } });
emitLog('info', `TUI agent ${agentId} working...`, { agentId, phase: 'working' });
}
// The TUI is a *screen*, not a log: every progress tick repaints the
// status line (`thinking with…`, token counters, footer) and gets
// re-captured if we parse it line-by-line. The attached shell session
// shows the live TUI faithfully — see-the-shell is the user-facing
// path. We still spool the raw stream to raw.txt for error analysis
// on failure, and we detect early "command not found" so a missing
// binary fails fast instead of idling.
//
// While a grace window is open, every chunk is evidence about whether the
// provider came back; the gate closes itself the moment it is. 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)) {
appendLine(LIFECYCLE_LINES.providerSignalCleared({ command: tuiConfig.command }));
}
const fallbackSignal = detectImmediateFallbackSignal(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)) {
appendLine(LIFECYCLE_LINES.providerSignalHolding({ message: fallbackSignal.message, seconds: Math.round(fallbackSignal.graceMs / 1000) }));
}
} else if (fallbackSignal) {
await failOverToFallback(fallbackSignal);
return;
}
if (agyResumeGate && promptSubmittedAt) {
agyResumeGate.observe(stripped);
// A relaunched agy is up once its composer footer paints; only then is the
// completion request a message to the model rather than boot keystrokes.
if (agyResumeAwaitingComposer && AGY_INPUT_READY_PATTERN.test(stripped)) {
agyResumeAwaitingComposer = false;
if (pasteController?.resubmit({ text: STALL_NUDGE_TEXT, label: 'agy resume nudge' })) {
appendLine(LIFECYCLE_LINES.agyResumedNudged());
}
}
}
// Silence-nudge signals. A local inference OOM, a truncated response and a
// model-at-capacity rejection all kill the turn but leave the session
// intact, so each arms a nudge instead of killing the run; the
// provider-signal timer sends it once the session has actually gone quiet.
// Gated on promptSubmittedAt: before the prompt is in there is no turn to
// resume and the ordinary paste path still owns first delivery. A budget
// spent on a signal that came back again means the provider is not going to
// recover (the conversation no longer fits, or it keeps truncating): hand
// the task to a fallback provider.
if (promptSubmittedAt) {
for (const { detect, gate, pendingLine } of silenceNudgeSignals) {
const signal = detect(stripped);
if (!signal) continue;
const armed = gate.arm(signal, now);
if (armed === 'armed') {
appendLine(pendingLine());
} else if (armed === 'exhausted') {
await failOverToFallback(signal);
return;
}
}
}
// Same gating as the silence nudges above: before the prompt is in there is no
// request of ours for the provider to be retrying. Acted on by the
// provider-signal timer, on its own poll, like the other gates.
if (promptSubmittedAt) retryStallGate.observe(stripped, now);
// The permission dialog is Claude Code chrome. Watching another vendor's
// session for it would only ever match an ECHO — a Codex or agy agent
// investigating a stalled run cats its raw.txt straight into this stream
// — and answer a dialog that is not there with keystrokes into a working
// composer.
const permissionDialog = promptSubmittedAt && isClaudeCommand(tuiConfig.command)
? toolPermissionGate.observe(stripped, now)
: null;
if (permissionDialog === 'exhausted') {
await finish({
success: false,
exitCode: 1,
error: `${tuiConfig.command} kept asking for tool permissions an unattended run cannot grant (${TOOL_PERMISSION_DECLINE_MAX} dialogs declined) — the model keeps reaching outside the run's allowed scope`,
reason: 'permission-prompt-loop',
});
return;
}
if (permissionDialog) {
// "No" is the last option and option 1 is highlighted: arrow down to it,
// then Enter — lands under both of Ink's selection models, whereas a bare
// digit is immediate-select in some builds and ignored in others.
session.write(sessionId, `${'\x1b[B'.repeat(Math.max(0, permissionDialog.noOption - 1))}${SUBMIT_KEY}`);
appendLine(LIFECYCLE_LINES.permissionDeclined({ command: tuiConfig.command, toolCall: permissionDialog.toolCall || 'a tool call', count: permissionDialog.count, max: TOOL_PERMISSION_DECLINE_MAX }));
}
if (!promptSentAt) {
// Only the login-shell path can reach this: it is the shell PRINTING
// "command not found". A direct PTY resolves the executable before it
// spawns (createAgentTuiSession), because there is no shell to print it.
if (detectMissingTuiBinary(stripped, commandName)) {
// finish() uses try/finally internally: finalizeAgent errors re-throw after
// cleanup, so finish() can reject. The outer try/catch in handleData already
// handles any such rejection via emitLog — no additional .catch() needed here.
await finish({
success: false,
exitCode: 127,
error: `TUI command not found: ${tuiConfig.spawnCommand}`,
reason: 'command-not-found'
});
}
}
} catch (err) {
emitLog('error', `TUI agent ${agentId} handleData failed: ${err?.message || err}`, { agentId });
}
};
const handleExit = async ({ exitCode, killed, signal = null, outputTail = '' }) => {
if (isTerminal()) return;
// A durable runner can retain a startup error even when its matching
// `tui:output` socket event lost the race with process exit. Preserve its
// bounded tail before finish() drains raw.txt for error analysis. Cap again
// at this trust boundary so a malformed runner event cannot grow the spool.
if (!receivedTuiOutput && typeof outputTail === 'string' && outputTail) {
receivedTuiOutput = true;
pushRaw(outputTail.slice(-16 * 1024));
recordFirstOutput('tui-exit-tail');
}
// A host restart reaches here as a plain PTY exit (pm2's TreeKill walks
// portos-server's descendants), which the `success` reading below would
// record as a completed run. finish() intercepts that case — see its
// host-shutdown guard (#3202).
const code = typeof exitCode === 'number' ? exitCode : killed ? 130 : 0;
// A signal-terminated process reports the wait-status exit code — 0 for a
// plain SIGTERM/SIGHUP — so `code === 0` alone cannot mean "finished
// normally". Treat any signal as an abnormal end. This is the backstop for
// the case the host-shutdown guard can't cover: a SIGKILL'd or crashed
// portos-server never runs its shutdown handler, so the flag is never set,
// yet the agent's PTY still dies with us (#3202).
//
// The reading holds for BOTH session shapes. A login shell carried its
// hosted CLI's status out via the run-then-exit wrapper; a direct PTY
// (#6159) simply IS the CLI, so the code and signal are the CLI's own.
// Reason codes stay `shell-*`: that is what COMPLETION_REASON_ANALYSES
// registers.
const signaled = !!signal;
const outcome = killed
? { error: 'TUI session was killed', reason: 'shell-killed' }
: signaled
? { error: `TUI session was terminated by signal ${signal} — the run was cut short, not completed`, reason: 'shell-signaled' }
: { error: null, reason: 'shell-exit' };
await finish({ success: code === 0 && !killed && !signaled, exitCode: code, ...outcome });
};
// Finalize a startup failure WITHOUT pasting — surfacing whatever the CLI
// printed (raw.txt tail) so the real cause is visible instead of a wedged
// shell. Shared by the liveness guard (command exited) and the readiness cap
// (claude never showed its input prompt).
const finishStartupFailure = async (reason, summary) => {
if (isTerminal()) return;
// Flush any debounced raw-PTY chunks first so the captured tail includes
// the CLI's most recent output (e.g. claude's final error before exiting),
// not just whatever happened to be on disk before the pending raw batch.
await flushRaw().catch(() => {});
const raw = await readFile(rawFile, 'utf8').catch(() => '');
const tail = raw
? stripAnsi(raw).split('\n').map((s) => s.trimEnd()).filter(Boolean).slice(-12).join('\n')
: '';
appendLine(LIFECYCLE_LINES.failure({ summary }));
await finish({
success: false,
exitCode: 1,
error: `${summary}${tail ? `\nCaptured output:\n${tail}` : ' No output was captured.'}`,
reason,
});
};
/**
* Arm prompt delivery and the run's two polling timers against a live PTY.
*
* Called once, by the adapter, after `createAgentTuiSession` returns. Split
* from construction because `handleData`/`handleExit` are what OPEN the
* session: a run can fail (and must finalize) before there is any session id
* to attach.
*/
const attachSession = ({ sessionId: liveSessionId, pid }) => {
sessionId = liveSessionId;
// Send the bracketed-paste prompt only after the TUI has finished its initial
// repaint and gone quiet — pasting during the banner/loading screen is the
// failure mode that left the input empty. The `\r` is split from the paste
// write because a fixed delay races Claude Code's paste-commit on large
// prompts; instead we poll Claude Code's raw output for its
// provider paste-commit marker, then wait an extra
// PASTE_TO_ENTER_MIN_DELAY_MS before submitting. A fallback timer fires
// the Enter unconditionally if the marker never appears (very small
// prompts won't trigger the marker). All timers are tracked so finish()
// can cancel pending writes if the agent ends mid-handshake.
const sessionStartedAt = Date.now();
const sessionLabel = sessionId.slice(0, 8);
// Owns the paste-attempt counter, the post-paste accumulator, and the paste
// timers — see createPasteRetryController's own comment for why that cluster
// lives outside this closure. `isFinalized`/`markPromptSent`/
// `markPromptSubmitted` are accessors into THIS closure's `sessionPhase`/
// `promptSentAt`/`promptSubmittedAt`, which handleData and the
// provider-signal timer below still read directly. `isFinalized` is the
// controller's own name for "the run is over", which is what BOTH terminal
// phases mean.
pasteController = createPasteRetryController({
agentId,
sessionLabel,
write: (keys, options) => options
? session.write(sessionId, keys, options)
: session.write(sessionId, keys),
paste: (text, options) => (sessionId ? session.paste(sessionId, text, options) : false),
hasLiveChild: () => session.hasLiveChild(pid),
launchShape,
prompt,
tuiConfig,
mcpBoot,
isCodexSession,
appendLine,
isFinalized: () => isTerminal() || !!terminalRefusal,
markPromptSent: () => { promptSentAt = Date.now(); },
markPromptSubmitted: () => { if (promptSubmittedAt === null) promptSubmittedAt = Date.now(); },
noteInput: (evidence) => promptGate.noteInput(Date.now(), evidence),
finishStartupFailure,
});
// Claude Code renders a startup banner and (in unfamiliar folders) a
// folder-trust gate before its input box exists, and the old "saw output then
// went quiet" heuristic fired during those lulls — pasting the prompt into the
// banner / trust menu / a returned shell. For claude we instead gate on its
// POSITIVE input-ready footer (see createInputReadyTracker), auto-confirm the
// trust gate, and NEVER blind-paste: if the prompt never appears we surface a
// failure. Other TUI providers keep the original startup readiness deadline.
//
// Antigravity (agy) gets the SAME positive gate (issue #2705), but agy alone
// needs a second signal on top of paste mode: unlike claude it enables
// bracketed paste on ALT-SCREEN ENTRY, ~200ms after launch, while it is still
// signing in and before its trust gate has even painted. Gating on paste mode
// alone therefore raced agy's sign-in round trip — when that outran the 2.5s
// prompt delay the prompt was pasted into the still-pending trust gate, which
// swallowed it and all three retries (`paste-not-rendered`). agy's composer
// footer (AGY_INPUT_READY_PATTERN) renders only after the trust gate is
// resolved, so requiring it orders the two correctly. agy DOES have a
// first-run folder-trust gate ("Do you trust the contents of this project?")
// and `--dangerously-skip-permissions` does NOT bypass it — the auto-confirm
// branch below is load-bearing, matching its "Yes, I trust this folder" option
// via TUI_TRUST_PROMPT_PATTERN. If agy ever fails to signal ready, the
// requireInputReady path fails fast with a surfaced startup error instead of
// silently failing at startup.
const requireInputReady = isClaudeCommand(tuiConfig.command) || isAntigravityCommand(tuiConfig.command) || isOpencodeSession;
// sendPrompt / finishStartupFailure are async and dispatched fire-and-forget
// from the interval below. A setInterval callback can't await, and an
// unhandled rejection there (e.g. a finalizeAgent throw inside finish())
// would crash the process — the callback-boundary hazard AGENTS.md calls out.
// Wrap each floating call so a rejection is logged, not thrown.
const safeSendPrompt = (reason) => pasteController.sendPrompt(reason).catch((err) =>
emitLog('error', `TUI agent ${agentId} sendPrompt(${reason}) failed: ${err?.message || err}`, { agentId }));
const safeFinishStartupFailure = (reason, summary) => finishStartupFailure(reason, summary).catch((err) =>
emitLog('error', `TUI agent ${agentId} finishStartupFailure(${reason}) failed: ${err?.message || err}`, { agentId }));
// The one PTY writer the startup-dialog answers go through, bound once
// rather than rebuilt on every 300ms poll tick.
const writeToTuiSession = (keys) => session.write(sessionId, keys);
promptTimer = setInterval(() => {
if (isTerminal() || promptSentAt) {
clearInterval(promptTimer);
promptTimer = null;
return;
}
const now = Date.now();
const elapsed = now - sessionStartedAt;
// OpenCode answers an unresolvable model with a toast and then paints its
// composer for a replacement model. Composer readiness would pass, so stop
// here: the prompt must never reach a model this task did not select.
const opencodeRejection = isOpencodeSession ? inputReady.opencodeModelRejection : null;
if (opencodeRejection) {
clearInterval(promptTimer);
promptTimer = null;
immediateFallbackAnalysis = { ...opencodeRejection, configuredModel: model };
safeFinishStartupFailure('opencode-model-rejected', opencodeRejection.message);
return;
}
// Answer whatever startup dialog the TUI is showing — one per tick, in the
// order answerStartupDialogs declares (external imports, hook review,
// folder trust, OpenCode updates). These run for EVERY provider, not only the positive
// input-ready ones below, because codex takes the idle/deadline paste path
// and a dialog is at its quietest right after it paints.
//
// Answering rewinds the idle clock (`lastOutputAt`) AND clears
// `firstOutputAt`, which re-arms the idle path's "has it printed anything?"
// gate. Without that, the dismissal keystroke and an idle paste can go out
// inside the same window, landing the prompt in a menu that has not
// repainted. Demanding fresh output-then-silence AFTER the keystroke makes
// the paste wait for whatever the dismissal reveals; if the TUI ignores the
// keystroke entirely, PASTE_DEADLINE_MS still backstops delivery.
const answeredBeforeComposer = answerStartupDialogs({
inputReady,
answers: dialogAnswers,
stage: 'before-composer',
command: tuiConfig.command,
write: writeToTuiSession,
});
if (answeredBeforeComposer) {
lastOutputAt = now;
firstOutputAt = null;
appendLine(LIFECYCLE_LINES.startupDialogAnswered({ message: answeredBeforeComposer.message, session: sessionLabel }));
return;
}
// A recognized trust heading with unknown choices is not an input prompt.
// Never fall through to either positive-readiness or idle delivery and paste
// the task into it. Fail explicitly at the provider's normal readiness cap
// so a future wording change is diagnosable without accepting an unknown
// highlighted default (which may be "No, exit").
if (inputReady.needsTrust && !inputReady.trustChoiceReady) {
const trustDeadlineMs = requireInputReady ? TUI_INPUT_READY_DEADLINE_MS : PASTE_DEADLINE_MS;
if (elapsed >= trustDeadlineMs) {
clearInterval(promptTimer);
promptTimer = null;
safeFinishStartupFailure(
'tui-trust-choice-unrecognized',
`${tuiConfig.command} presented a folder-trust prompt whose affirmative choice PortOS could not identify, so no prompt was sent.`,
);
}
return;
}
if (requireInputReady) {
// Claude's auto-mode offer paints AFTER the composer is live, so it only
// reaches the positive input-ready providers — and unlike a dialog that
// paints before the composer, no idle rewind is needed here: this path
// gates on `inputReady.ready`, which the offer itself suppresses until
// it is acked.
const answeredAtComposer = answerStartupDialogs({
inputReady,
answers: dialogAnswers,
stage: 'after-composer',
command: tuiConfig.command,
write: writeToTuiSession,
});
if (answeredAtComposer) {
appendLine(LIFECYCLE_LINES.startupDialogAnswered({ message: answeredAtComposer.message, session: sessionLabel }));
return;
}
if (inputReady.ready && elapsed >= tuiConfig.promptDelayMs
&& (!isOpencodeSession || (firstOutputAt !== null && now - lastOutputAt >= READY_IDLE_THRESHOLD_MS))) {
safeSendPrompt('input-ready');
clearInterval(promptTimer);
promptTimer = null;
return;
}
// Never blind-paste for claude: if the input prompt never showed within
// the cap, finalize a startup failure with the captured output.
if (elapsed >= TUI_INPUT_READY_DEADLINE_MS) {
clearInterval(promptTimer);
promptTimer = null;
safeFinishStartupFailure(
'tui-not-ready',
`${tuiConfig.command} did not present an input prompt within ${Math.round(TUI_INPUT_READY_DEADLINE_MS / 1000)}s, so no prompt was sent.`,
);
}
return;
}
if (elapsed >= PASTE_DEADLINE_MS) {
safeSendPrompt('fallback');
clearInterval(promptTimer);
promptTimer = null;
return;
}
if (elapsed < tuiConfig.promptDelayMs) return;
if (firstOutputAt === null) return;
if (now - lastOutputAt < READY_IDLE_THRESHOLD_MS) return;
// Codex goes quiet for seconds mid-boot with no composer painted, and the
// idle heuristic alone reads that lull as ready — pasting into nothing.
// Hold the idle path until its composer placeholder has actually rendered;
// the PASTE_DEADLINE_MS fallback above still delivers if it never does, so
// this can only delay a paste, never cancel one.
if (isCodexSession && !codexComposerReady) return;
safeSendPrompt('ready');
clearInterval(promptTimer);
promptTimer = null;
}, READY_POLL_INTERVAL_MS);
// Provider-handshake retry timer. It is deliberately not an idle watchdog:
// a CoS TUI may remain silent for as long as the provider needs.
providerSignalTimer = setInterval(() => {
if (isTerminal() || terminalRefusal) return;
// One clock for every gate on this tick. They all measure the same silence,
// so reading the wall four times only invites them to disagree about it.
const now = Date.now();
// A completed Codex turn that rejected account model access cannot be
// repaired by any continuation nudge. Preserve its actionable outcome
// without changing the pinned model or authentication/billing mode.
const modelRejection = sessionPhase === 'running' && promptSubmittedAt
? codexModelRejectionGate?.takeRejected(now, lastOutputAt)
: null;
if (modelRejection && !sentinelPresent()) {
immediateFallbackAnalysis = { ...modelRejection, affectedModel: model, configuredModel: model };
appendLine(LIFECYCLE_LINES.failure({ summary: modelRejection.message }));
finish({ success: false, exitCode: 1, error: modelRejection.message, reason: 'model-access-rejected' })
.catch(err => emitLog('error', `TUI agent ${agentId} model-access finish failed: ${err?.message || err}`, { agentId }));
return;
}
const expired = selfClearingGate.takeExpired(now);
if (expired) {
// setInterval can't await, and an unhandled rejection here would crash the
// process (the callback-boundary hazard AGENTS.md calls out).
failOverToFallback(expired).catch((err) =>
emitLog('error', `TUI agent ${agentId} deferred fallback finish failed: ${err?.message || err}`, { agentId }));
return;
}
if (selfClearingGate.armed) {
resubmitAfterSignal();
return;
}
// agy fell back to the shell it was launched from: type its own resume
// command. Checked against the live process tree, not just the banner —
// the banner also scrolls past in a session that is still running.
const resumeId = agyResumeGate && sessionPhase === 'running' && promptSubmittedAt
? agyResumeGate.takeResume(now, lastOutputAt)
: null;
if (resumeId) {
Promise.resolve(session.hasLiveChild(pid)).then((alive) => {
if (alive || isTerminal()) return;
const wrote = session.write(sessionId, `${tuiConfig.commandLine} --conversation=${resumeId}\r`);
if (wrote === false) return;
agyResumeGate.recordRelaunch();
agyResumeAwaitingComposer = true;
appendLine(LIFECYCLE_LINES.agyRelaunched({ conversation: resumeId.slice(0, 8), attempt: agyResumeGate.attempts, max: AGY_RESUME_MAX_ATTEMPTS }));
}).catch((err) => emitLog('error', `TUI agent ${agentId} agy resume failed: ${err?.message || err}`, { agentId }));
return;
}
const stall = retryStallGate.takeStall();
if (stall) {
failOverToFallback(stall).catch((err) =>
emitLog('error', `TUI agent ${agentId} retry-stall fallback finish failed: ${err?.message || err}`, { agentId }));
return;
}
// A declined permission dialog ends the turn; once the session is quiet,
// tell it why and send it back to work.
const declined = toolPermissionGate.takeNudge(now, lastOutputAt);
if (declined) {
if (pasteController?.resubmit({ text: TOOL_PERMISSION_NUDGE_TEXT, label: 'declined-permission nudge' })) {
appendLine(LIFECYCLE_LINES.permissionDeclineNudged({ declined }));
}
return;
}
// Nudge a session parked by a silence-nudge signal (OOM, truncation, model
// capacity). Rides this timer rather than one of its own so the nudge
// cadence and the fail-over verdict stay on the same clock — and so there
// is one fewer interval to leak past finish().
for (const { gate, nudgeText, nudgeLabel, nudgedLine } of silenceNudgeSignals) {
const nudge = gate.takeNudge(now, lastOutputAt);
if (!nudge) continue;
if (pasteController?.resubmit({ text: nudgeText, label: nudgeLabel })) {
appendLine(nudgedLine(nudge));
}
return;
}
// A prompt still sitting unsubmitted gets the Enter it missed, long before
// the stall nudge below would paste a second message on top of it.
const enter = sessionPhase === 'running' && promptSubmittedAt ? promptGate.takeEnter(now, lastOutputAt) : 0;
if (enter) {
if (session.write(sessionId, SUBMIT_KEY, { promptSubmission: true }) !== false) {
appendLine(LIFECYCLE_LINES.unsubmittedPromptEntered({ attempt: enter, max: UNSUBMITTED_PROMPT_ENTER_MAX_ATTEMPTS }));
}
return;
}
// Last, and only once no gate above has a say: every one of them describes a
// session stalled for a KNOWN reason, and their own silence tests would be
// pre-empted by a nudge sent on plain quiet.
//
// `sessionPhase`, not `isTerminal()`: a finish() parked on the merge-gate
// contract check (a `gh` PR probe) sits in 'finishing' for as long as that
// network call takes, non-terminal the whole time, and it may yet paste a
// nudge of its own. And `promptSubmittedAt`, because before the prompt is
// in the promptTimer owns delivery — silence there is startup, not a stall.
// A no-deadline security audit may be quiet during the scan AND its later
// validation/fix work. Silence alone must not inject another turn or badge
// it as stalled. Explicit provider failures and terminal signals above stay active.
if (sessionPhase !== 'running' || !promptSubmittedAt || securityScanGrant?.timeLimitSeconds === 'unlimited') return;
// The task's schedule turned the nudge off (taskMetadata.stallNudge). Its
// quiet stretches are waits it owns — do-release parks on its release PR's
// CI — so silence there is not a stall to interrupt. Only once the prompt
// has started a turn: before that, these nudges are what detects a prompt
// that never ran and fails it (prompt-not-submitted) instead of holding
// its lane forever.
if (promptGate.worked && isFalsyMeta(task?.metadata?.stallNudge)) return;
const stalled = stallNudgeGate.takeNudge(now, lastOutputAt);
if (!stalled) return;
// Read the sentinel here rather than on every tick: its watcher polls on its
// own clock, so a run can be done-but-not-yet-finalized at this instant, and
// this is the only moment the answer is acted on.
if (sentinelPresent()) return;
if (stalled === 'exhausted' && !promptGate.worked) {
// Nothing but echoes of PortOS's own keystrokes since the submit: the
// prompt never started a turn. Parking it would keep a live run that
// registered as a possible claim owner (claimSelectionPending) holding
// every claim checkout in its repository; failing it releases them and
// requeues the task through the ordinary retry budget.
emitLog('warn', `🛑 TUI agent ${agentId} never started its prompt — failing it after ${stallNudgeGate.nudgesSent} stall nudges`, { agentId });
finishStartupFailure(
'prompt-not-submitted',
`${tuiConfig.command} never started working on the submitted prompt: the session stayed idle through ${stallNudgeGate.nudgesSent} stall nudges.`,
).catch(err => emitLog('error', `TUI agent ${agentId} finishStartupFailure(prompt-not-submitted) failed: ${err?.message || err}`, { agentId }));
return;
}
if (stalled === 'exhausted') {
// Every nudge in the streak was ignored (wedged below its composer), or the
// run spent its lifetime budget answering nudges without ever finishing
// (a model looping on "continue"). Either way more nudges won't help. There is no ceiling left to reap it, so say
// so loudly and badge the card — an agent nobody can see is stuck is the
// condition this gate exists to end, and only a human can end this one.
appendLine(LIFECYCLE_LINES.stallGaveUp({ nudges: stallNudgeGate.nudgesSent }));
emitLog('warn', `🛑 TUI agent ${agentId} is wedged — still idle after ${stallNudgeGate.nudgesSent} stall nudges`, { agentId });
persistence.updateAgent(agentId, { metadata: { phase: 'stalled' } }).catch((err) =>
emitLog('error', `TUI agent ${agentId} stalled-phase update failed: ${err?.message || err}`, { agentId }));
// Re-arm the onData handler's one-shot "phase: working" write, so a
// session that wakes up later (a provider call that finally returned)
// clears the badge on its next chunk instead of wearing it to the end.
hasStartedWorking = false;
return;
}
if (pasteController?.resubmit({ text: STALL_NUDGE_TEXT, label: 'stalled-session nudge' })) {
appendLine(LIFECYCLE_LINES.stallNudged({ attempt: stalled, max: STALL_NUDGE_MAX_ATTEMPTS, sent: stallNudgeGate.nudgesSent, total: STALL_NUDGE_MAX_TOTAL }));
}
}, PROVIDER_SIGNAL_POLL_MS);
doneSentinelWatcher = armSentinelWatcher();
};
return {
handleData,
handleExit,
refuseScanner: () => {
terminalRefusal = { category: 'content-refusal', origin: 'provider', permanent: true, actionable: false, requiresFallback: false,
message: 'Security scanner safety refusal; automatic continuation, retries and provider fallback are disabled.' };
executionInterruption = { category: 'content-refusal', source: 'security-scanner' };
immediateFallbackAnalysis = terminalRefusal;
pasteController?.cancel();
return finish({ success: false, exitCode: 1, error: terminalRefusal.message, reason: 'content-refusal' });
},
markCommandInjected: () => { commandInjected = true; },
isTerminal,
finish,
attachSession,
};
}