@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/cli.js

@@ -0,0 +1,2564 @@
+#!/usr/bin/env node
+import { randomUUID } from 'node:crypto';
+import { bootMark } from './boot-trace.js';
+import { createSessionTrajectory } from './trajectory.js';
+import { hostedDecisionPolicy } from './decision/hostedPolicy.js';
+import { parseArgs, stripVTControlCharacters } from 'node:util';
+import { appendFile, mkdir, open, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { workspacePermissionKey, permissionLabel } from './permissions.js';
+import { configDirectory, loadConfig, resolveCodeIntelConfig, resolveConfiguredLimits, saveConfig } from './config.js';
+import { compactHistory, compactedContextEstimate, executeCommand, HELP } from './commands.js';
+import { applyModelContextWindow, createAdapter, providerSecrets, recordProviderModel } from './providers.js';
+import { createTools } from './tools.js';
+import { QA_SYSTEM_GUIDANCE, disposeAllQaProcesses, disposeAllQaPtys, getQaPtyManager } from './qa/index.js';
+import { disposePooledPowerShell } from './powershell-pool.js';
+import { loadWorkspaceInstructions } from './workspace-instructions.js';
+import { runGraph, stopReasonPhrase } from './runtime.js';
+import { validateGraph } from './graphs.js';
+import { checkGraphModelHealth, formatGraphHealthFailure } from './graph-health.js';
+import { getMembership, loadAccessibleGraph, PaidMembershipRequiredError } from './membership.js';
+import { configuredSurface, createRunHandle, drainTelemetry, graphShape, reportInterruptedRuns, reportRunFinished, reportRunStarted, reportSessionStarted } from './telemetry/surface.js';
+import { createRunTelemetry, recordModelUse } from './telemetry/capture.js';
+import { pricingFor } from './model-tiers.js';
+import { GraphProviderUnavailableError } from './graph-provider-portability.js';
+import { MAX_SUBAGENT_TASK_CHARS, SubagentInvalidArgumentError, SubagentProviderNotSetError, SubagentRunInProgressError, SubagentRunner, SubagentSelectionError } from './subagent-run.js';
+/** Shown when a saved per-account graph selection is denied account access at launch or refresh. */
+const GRAPH_FALLBACK_NOTICE = 'The selected graph needs paid account access, which is currently unavailable. Starting with the local Default graph; once access is restored, switch back with /graph.';
+/** The free allowance names its own reason; any other membership refusal is an access outage. */
+const graphFallbackReason = (error) => error instanceof FreeTierLimitError ? `${error.message} Starting with the local Default graph.` : GRAPH_FALLBACK_NOTICE;
+import { configuredGraphSelection, currentGraphSubject } from './graph-selection.js';
+import { launchGraphEditor } from './graph-server.js';
+import { createGraphEditorSession } from './graph-editor-session.js';
+import { FreeTierLimitError } from './graph-quota.js';
+import { updateInstallation } from './update.js';
+import { RunControl } from './run-control.js';
+import { TimerRegistry } from './timers.js';
+import { TerminalUI } from './terminal-ui.js';
+import { meterStreamedRequest } from './token-rate.js';
+import { attachmentLabel, attachmentReadRoots, attachmentReferenceBlock, pruneAttachments, readClipboardImage, resolveAttachments, writeClipboardText } from './attachments.js';
+import { describeTool, formatEvent, formatRunResult } from './transcript.js';
+import { staticToolTimestamp } from './tool-call-clock.js';
+import { LocalToolMemory } from './memory/LocalToolMemory.js';
+import { askClarification } from './clarification-ui.js';
+import { refreshModelContext, resolveModelContext, withEvaluationReasoningEffort } from './model-metadata.js';
+import { isScreenCommand, runCommandScreen } from './command-screens.js';
+import { CodeIntelligenceManager } from './code-intelligence/CodeIntelligenceManager.js';
+import { ToolActivity, activityForRuntimeEvent } from './tool-activity.js';
+import { extensionSnapshot, resolveSkillInvocation } from './extensions.js';
+import { isBuiltinSlashCommand } from './skill-commands.js';
+import { executeAuthCommand } from './auth-commands.js';
+import { setAuthSignOutReporter } from './auth/index.js';
+import { getAccountPresentation } from './account-presentation.js';
+import { acquireSessionMutationLock, clearOpenRunClaim, noteCheckpointWriteFailure, removeRunCheckpoint, RUNNING_TURN_SUMMARY, reconcileInterruptedRuns, runRecordPath, runRecordsDirectory, writeOpenRunRecord, writeRunCheckpoint, writeStudioRunSummary } from './run-records.js';
+import { gitChangeSummary } from './git-summary.js';
+import { writeActivity } from './activity.js';
+import { TodoStore } from './todos.js';
+import { canExtendLineage, carryRailOwnedFields, displayHistory, lineagePoints, lineageThrough, SessionStore, sessionName, projectIdentity } from './sessions.js';
+import { SessionTitle } from './session-title.js';
+import { createBrowserBridge } from './browser-bridge.js';
+import { startBrowserServer, openBrowserUrl } from './browser-server.js';
+/**
+ * The version this build reports, read from the package manifest rather than hard-coded.
+ *
+ * The release workflow rewrites `package.json` and then publishes; a literal here would keep
+ * reporting the old version forever, so `andorra --version` would disagree with the package that
+ * was actually installed. `dist/src/cli.js` sits two directories below the manifest
+ * (`dist/src/cli.js` -> `dist` -> repository root), both in a checkout and in an installed
+ * package. A manifest that cannot be read leaves the version unknown rather than wrong.
+ */
+export async function cliVersion() {
+    try {
+        const manifest = JSON.parse(await readFile(fileURLToPath(new URL('../../package.json', import.meta.url)), 'utf8'));
+        return typeof manifest.version === 'string' ? manifest.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Display-only Git metadata must never run workspace-controlled PATH helpers. */
+export async function gitBranch(workspace) {
+    try {
+        const root = await realpath(workspace);
+        const contained = (target) => {
+            const suffix = relative(root, target);
+            return suffix === '' || (!isAbsolute(suffix) && suffix !== '..' && !suffix.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`));
+        };
+        const metadataPath = async (target) => {
+            // Check lexical paths before resolution, then reject symlink/junction escapes.
+            if (!contained(resolve(target)))
+                throw new Error('Git metadata is outside the workspace');
+            const canonical = await realpath(target);
+            if (!contained(canonical))
+                throw new Error('Git metadata is outside the workspace');
+            return canonical;
+        };
+        const metadataText = async (target) => {
+            const canonical = await metadataPath(target);
+            const handle = await open(canonical, 'r');
+            try {
+                const info = await handle.stat();
+                if (!info.isFile() || info.size > 4096)
+                    throw new Error('Invalid Git metadata');
+                const buffer = Buffer.alloc(4097);
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                if (bytesRead > 4096)
+                    throw new Error('Invalid Git metadata');
+                return buffer.subarray(0, bytesRead).toString('utf8').trim();
+            }
+            finally {
+                await handle.close();
+            }
+        };
+        let gitDirectory = await metadataPath(join(root, '.git'));
+        if (!(await stat(gitDirectory)).isDirectory()) {
+            const pointer = /^gitdir: (.+)$/.exec(await metadataText(gitDirectory));
+            if (!pointer)
+                return 'No Git branch';
+            gitDirectory = await metadataPath(resolve(root, pointer[1]));
+            if (!(await stat(gitDirectory)).isDirectory())
+                return 'No Git branch';
+        }
+        const head = await metadataText(join(gitDirectory, 'HEAD'));
+        const branch = /^ref: refs\/heads\/([^\x00-\x20\x7f]+)$/.exec(head);
+        if (branch)
+            return branch[1];
+        return /^[a-f0-9]{40,64}$/i.test(head) ? `HEAD (detached at ${head.slice(0, 7)})` : 'No Git branch';
+    }
+    catch {
+        return 'No Git branch';
+    }
+}
+export function safeTerminal(text) {
+    return stripVTControlCharacters(text).replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '');
+}
+/** Short follow-up directions that mean "continue the unfinished work" rather than start a new task. */
+export function isContinuationPrompt(text) {
+    const normalized = text.trim().replace(/[.!?]+$/, '').trim();
+    return normalized.length <= 160 && /^(?:continue|resume|retry|try again|keep going|keep working)(?:\b.*)?$/i.test(normalized);
+}
+/** Retain an unfinished run's plan only when the next prompt explicitly continues that work. */
+export function continuedTodos(task, lastRun) {
+    return lastRun && lastRun.status !== 'succeeded' && isContinuationPrompt(task)
+        ? (lastRun.todos ?? []).map(todo => ({ ...todo }))
+        : [];
+}
+// Re-exported for the callers that already imported it from the CLI; the definition moved beside
+// the provider configuration it reads so the app-server can register secrets without the CLI.
+export { providerSecrets };
+/**
+ * Append one runtime event to the record of the run it belongs to.
+ *
+ * Not every event belongs to a run. The memory health check emitted while the memory manager is
+ * constructed, and code-intelligence state before the first run starts, carry no run identity at
+ * all: they describe the session. They are skipped, because a per-run file cannot name them --
+ * writing one anyway is what used to leave a `runs/undefined.jsonl` behind in the installation.
+ * An identity that is present but not well formed is a bug in whatever produced it rather than an
+ * absent one, so `runRecordPath` still throws for it.
+ * @param directory - the installation directory holding `runs/`.
+ * @param event - the runtime event to persist.
+ */
+export async function appendRunEvent(directory, event) {
+    const runId = event.data.runId;
+    if (runId === undefined || runId === null)
+        return;
+    await appendFile(runRecordPath(directory, runId, 'jsonl'), JSON.stringify(event) + '\n', { mode: 0o600 });
+}
+/**
+ * Add the reasoning effort and context window of a root node's own resolution to its
+ * `agent.session.started` data, so the footer can describe the model that is answering.
+ *
+ * The executor reports the provider and model a node resolved but not the effort or window that
+ * came with them, and those differ per node: a node that overrides the model loses the provider's
+ * saved effort and window (`resolveModelContext`), so reusing the session's numbers would put
+ * values on the footer that belong to a model that is not running. Only a root node session is
+ * decorated -- a delegated child repeats its parent's node id, and a plain prompt run has no
+ * graph node at all -- and the caller's event object is never mutated, so the events the run
+ * record holds stay exactly as the runtime emitted them. Both keys are always written together,
+ * even when unknown: the terminal reads their presence as proof that this node's resolution is
+ * authoritative, so an unknown window cannot silently inherit the session's.
+ * @param event - the runtime event on its way to the terminal.
+ * @param lookup - the memoized resolution of a provider/model pair, as the node's executor asked for it.
+ * @returns the event to hand to the terminal; the original event when there is nothing to add.
+ */
+export async function withNodeModelResolution(event, lookup) {
+    if (event.type !== 'agent.session.started' || typeof event.data.subagentId === 'string')
+        return event;
+    const { provider, model } = event.data;
+    if (typeof provider !== 'string' || typeof model !== 'string')
+        return event;
+    let resolved;
+    try {
+        resolved = await lookup(provider, model);
+    }
+    catch {
+        return event;
+    }
+    if (!resolved)
+        return event;
+    return { ...event, data: { ...event.data, reasoningEffort: resolved.reasoningEffort, contextWindow: resolved.contextWindow } };
+}
+const SIGN_OUT_NOTICE = 'Your Andorra session was revoked or expired, so the stored login was removed. Run /login to sign in again.';
+/**
+ * Report an automatic sign-out where the current surface can see it, and record it.
+ *
+ * `--json` paths reserve stdout for the machine-readable result, the interactive path must print
+ * through the terminal (its alternate screen owns stdout), and the early command paths have
+ * neither, so the destination is chosen per call. The journal callback is optional because a
+ * sign-out can be discovered before the session journal exists (`auth status`, `--configure`).
+ */
+function reportSignOut(json, terminal, reason, journal) {
+    if (json)
+        process.stderr.write(safeTerminal(SIGN_OUT_NOTICE) + '\n');
+    else if (terminal)
+        terminal.print(SIGN_OUT_NOTICE);
+    else
+        process.stdout.write(safeTerminal(SIGN_OUT_NOTICE) + '\n');
+    journal?.(reason);
+}
+export async function main(argv = process.argv.slice(2), dependencies = {}) {
+    bootMark('cli.main');
+    const persistConfig = dependencies.saveConfig ?? saveConfig;
+    const loadGraph = dependencies.loadGraph ?? loadAccessibleGraph;
+    const checkGraphHealth = dependencies.checkGraphHealth ?? checkGraphModelHealth;
+    // MCP uses stdio for JSON-RPC; never install the ordinary auth reporter here,
+    // because a mid-session sign-out notice on stdout would corrupt the protocol.
+    if (argv[0] === 'mcp-server') {
+        if (argv.length !== 2 || argv[1] !== '--stdio')
+            throw new Error('Usage: andorra mcp-server --stdio');
+        const { runAgentMcpServer } = await import('./agent-mcp.js');
+        return await runAgentMcpServer();
+    }
+    // Registered before the early authenticated commands (`login`, `logout`, `auth status`,
+    // `graph`, `--configure`): each can refresh a stale token and discover a revoked session, and
+    // that sign-out must not be silent. The registration after the journal exists replaces this one
+    // so the notice also reaches the terminal and the `--debug` journal.
+    // The subagent command prints one JSON line on stdout and --json is optional there, so its
+    // sign-out notice belongs on stderr like the other machine-output paths.
+    const machineOutput = argv.includes('--json') || argv[0] === 'subagent' || argv[0] === 'automations';
+    setAuthSignOutReporter(error => reportSignOut(machineOutput, undefined, error.message));
+    if (argv[0] === 'login' || argv[0] === 'logout' || argv[0] === 'auth') {
+        if ((argv[0] === 'auth' && (argv.length !== 2 || argv[1] !== 'status')) || (argv[0] !== 'auth' && argv.length !== 1))
+            throw new Error('Usage: andorra login | andorra logout | andorra auth status');
+        const controller = new AbortController();
+        const cancel = () => controller.abort();
+        process.once('SIGINT', cancel);
+        process.once('SIGTERM', cancel);
+        try {
+            const print = (message) => process.stdout.write(safeTerminal(message) + '\n');
+            print(await executeAuthCommand(argv[0] === 'auth' ? 'status' : argv[0], { signal: controller.signal, print }));
+        }
+        finally {
+            process.removeListener('SIGINT', cancel);
+            process.removeListener('SIGTERM', cancel);
+        }
+        return 0;
+    }
+    if (argv[0] === 'graph') {
+        if (argv.length > 2 || (argv[1] !== undefined && argv[1] !== '--no-open'))
+            throw new Error('Usage: andorra graph [--no-open]');
+        await launchGraphEditor(argv[1] === '--no-open');
+        return 0;
+    }
+    if (argv[0] === 'app-server') {
+        if (argv.length !== 2 || argv[1] !== '--stdio')
+            throw new Error('Usage: andorra app-server --stdio');
+        // Loaded on demand: the machine-client surface pulls in the PTY, QA, and graph-server modules,
+        // and an ordinary TUI or headless invocation must not pay for them.
+        const { runAppServer } = await import('./app-server.js');
+        bootMark('app-server.imported');
+        // The desktop client owns this process and its stdio; in this mode nothing may print to stdout.
+        return await runAppServer();
+    }
+    if (argv[0] === 'automations') {
+        const { runAutomationCommand } = await import('./automation-service.js');
+        return runAutomationCommand(argv.slice(1), line => process.stdout.write(line + '\n'));
+    }
+    if (argv[0] === 'remote') {
+        // Loaded on demand like `app-server`: the remote modules pull in TLS, x509, and the peer
+        // client, and no other command path needs them.
+        const { REMOTE_USAGE, runRemoteCommand } = await import('./remote/command.js');
+        if (argv.includes('--help') || argv.includes('-h')) {
+            process.stdout.write(`${REMOTE_USAGE}\n`);
+            return 0;
+        }
+        const version = await cliVersion().catch(() => '0.0.0');
+        return await runRemoteCommand(argv.slice(1), line => process.stdout.write(safeTerminal(line) + '\n'), { version });
+    }
+    if (argv[0] === 'setup') {
+        if (argv.length !== 1)
+            throw new Error('Usage: andorra setup');
+        process.stdout.write('Provider setup has moved. Run andorra, open /providers, and press Right Arrow or e to edit a provider or choose Add provider.\n');
+        return 0;
+    }
+    if (argv[0] === 'subagent')
+        return await runSubagentCommand(argv.slice(1));
+    if (argv[0] === 'update') {
+        if (argv.length > 2 || (argv.length === 2 && argv[1] !== '--break-lock'))
+            throw new Error('Usage: andorra update [--break-lock]');
+        process.stdout.write('Updating Andorra from GitHub main...\n');
+        const notify = (message) => process.stdout.write(safeTerminal(message) + '\n');
+        process.stdout.write(safeTerminal(await updateInstallation({ breakLock: argv[1] === '--break-lock', notify })) + '\n');
+        return 0;
+    }
+    const { values } = parseArgs({ args: argv, options: {
+            help: { type: 'boolean', short: 'h' }, version: { type: 'boolean' },
+            prompt: { type: 'string', short: 'p' }, 'no-tui': { type: 'boolean' },
+            provider: { type: 'string' }, model: { type: 'string' }, graph: { type: 'string' },
+            cwd: { type: 'string' }, yolo: { type: 'boolean' }, jev: { type: 'string' }, json: { type: 'boolean' }, debug: { type: 'boolean' },
+            configure: { type: 'boolean' }, 'run-input': { type: 'string' }, 'run-state': { type: 'string' },
+        } });
+    const readValues = async (path, flag) => {
+        if (!path)
+            return undefined;
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error(`${flag} must reference a JSON object file`);
+        return value;
+    };
+    const runInput = await readValues(values['run-input'], '--run-input');
+    const runState = await readValues(values['run-state'], '--run-state');
+    let terminal;
+    const print = (text) => terminal ? terminal.print(text) : process.stdout.write(safeTerminal(text) + '\n');
+    if (values.help) {
+        print(`Andorra Code\nUsage: andorra [--cwd path] [--provider id] [--model id] [--graph id] [--run-input file.json] [--run-state file.json] [--yolo] [--jev on|off] [--debug]\n       andorra --prompt "task" [--json] [--yolo] [--jev on|off] [--debug]\n       andorra subagent --prompt "task" [--provider id] [--model id] [--read-only]\n       andorra graph [--no-open]\n       andorra automations list|run|service|serve\n       andorra app-server --stdio\n       andorra mcp-server --stdio\n       andorra remote serve|status|code|devices|revoke|share|unshare|pair|workspaces|unpair|rotate-cert\n       andorra update\n       andorra login\n       andorra logout\n       andorra auth status\n\n${HELP}`);
+        return 0;
+    }
+    if (values.version) {
+        print(await cliVersion());
+        return 0;
+    }
+    if (values.configure) {
+        await launchGraphEditor();
+        return 0;
+    }
+    const interactive = values.prompt === undefined;
+    const sessionStartedAt = Date.now();
+    // Declared early because the startup guard's closing record reads it before the signal
+    // handlers below exist; nothing sets it true until terminate() runs.
+    let terminated = false;
+    // The journal starts before the first fallible startup step (graph flag, config load,
+    // workspace resolution), so a failed `--debug` invocation still explains itself. Provider
+    // credentials are not known until the config loads; they register once it does.
+    let trajectory = await createSessionTrajectory({
+        // The log lives beside the sessions this terminal writes, so the window can find a session's
+        // conversation: it reads the log of the session it is showing.
+        directory: dependencies.trajectoryDirectory ?? join(configDirectory(), 'trajectories'),
+        onError: message => { if (values.json)
+            process.stderr.write(safeTerminal(message) + '\n');
+        else
+            print(message); },
+        ...(values.debug ? { meta: {
+                debug: true, argv, pid: process.pid, platform: process.platform, arch: process.arch, nodeVersion: process.version,
+                version: await cliVersion(), interactive,
+            } } : {}),
+    });
+    // The trajectory just recorded `session.started`; the conversation began here. It is emitted once
+    // per creation, never for a reopen. The promise is retained so the drain at exit runs after the
+    // enqueue: a drain that starts first exits with the event still pending in a tearing-down home.
+    // The conversation does not exist yet: an interactive session opened and closed without a task
+    // creates no saved conversation, so the start is emitted where the first one is created.
+    let sessionStarted = Promise.resolve();
+    const noteSessionStarted = (extra = {}) => {
+        sessionStarted = sessionStarted.then(() => currentGraphSubject().catch(() => undefined)).then(subject => reportSessionStarted({ home: configDirectory(), surface: configuredSurface('cli'), ...(subject === undefined ? {} : { subject }), ...extra })).catch(() => { });
+    };
+    /**
+     * The log a session's conversation is written to.
+     *
+     * A session has one log. The process opens one before the configuration is read, so a failed
+     * start still explains itself, and a session the user picks or forks takes a log of its own: the
+     * records of two conversations must never share a file, or the window would show them mixed. The
+     * log is named after the session, so the window finds it by the session's own id.
+     */
+    const openSessionTrajectory = async (sessionId) => {
+        const directory = dependencies.trajectoryDirectory ?? join(configDirectory(), 'trajectories');
+        const path = join(directory, `${sessionId}.jsonl`);
+        const reopened = await stat(path).then(() => true, () => false);
+        trajectory = await createSessionTrajectory({
+            sessionId, directory, reopened,
+            onError: message => { if (values.json)
+                process.stderr.write(safeTerminal(message) + '\n');
+            else
+                print(message); },
+            ...(values.debug ? { meta: { debug: true, argv, pid: process.pid, platform: process.platform, arch: process.arch, nodeVersion: process.version, version: await cliVersion(), interactive } } : {}),
+        });
+        if (!reopened)
+            noteSessionStarted({ workspace });
+        trajectory.addSecrets(providerSecrets(config.providers));
+    };
+    /**
+     * `--debug` session accounting: every user command with its wall-clock cost, CLI-level
+     * errors that never reach a runtime event, and a closing summary. Model requests, tool
+     * calls and their timings are recorded unconditionally through the adapter wrapper and
+     * runtime events; these records add the conversation layer around them.
+     */
+    const debugRecord = (type, data) => values.debug ? trajectory.record(type, data) : undefined;
+    const sessionEndedRecord = (extra = {}) => debugRecord('session.ended', { durationMs: Date.now() - sessionStartedAt, usage: sessionUsage(), interactive, terminated, ...extra });
+    // An automatic sign-out must be visible and recorded: the wipe removes the credential itself,
+    // so without this the user only sees authenticated features stop working. Explicit /logout is
+    // reported by its own command and never reaches this reporter. This registration replaces the
+    // early one, so the notice also reaches the terminal and the `--debug` journal.
+    setAuthSignOutReporter(error => reportSignOut(values.json === true, terminal, error.message, message => { void debugRecord('auth.signed-out', { message }); }));
+    /**
+     * Startup failures after the journal exists must still close it: a `--debug` invocation
+     * that dies during validation or initialization would otherwise leave the log open at
+     * `session.started` with no explanation. No provider call can have happened yet, so the
+     * closing summary reports zero usage; whatever manager was created is released.
+     */
+    let releaseCodeIntel;
+    const startupGuard = async (operation) => {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            await debugRecord('session.ended', {
+                durationMs: Date.now() - sessionStartedAt, usage: { requests: 0, inputTokens: 0, outputTokens: 0 },
+                interactive, terminated, startupError: error instanceof Error ? error.message : String(error),
+            });
+            await trajectory.flush();
+            try {
+                await releaseCodeIntel?.();
+            }
+            catch { /* Disposal is best effort during startup failure. */ }
+            throw error;
+        }
+    };
+    /** Fails startup under the journal-closing guard; the guard rethrows the wrapped error. */
+    const startupReject = (message) => startupGuard(async () => { throw new Error(message); });
+    if (values.graph && values.graph !== 'default')
+        await startupGuard(() => loadGraph(values.graph));
+    if (values.json && !values.prompt)
+        await startupReject('--json requires --prompt');
+    if (values['no-tui'] && !values.prompt)
+        await startupReject('--no-tui requires --prompt');
+    if (values.jev !== undefined && !['on', 'off'].includes(values.jev))
+        await startupReject('--jev takes on or off');
+    if (values.prompt !== undefined && !values.prompt.trim())
+        await startupReject('--prompt must not be empty');
+    if (interactive && (!process.stdin.isTTY || !process.stdout.isTTY))
+        await startupReject('Interactive mode requires a terminal. Use --prompt "task" for headless execution.');
+    const config = await startupGuard(() => loadConfig());
+    const workspace = await startupGuard(async () => {
+        const resolved = await realpath(values.cwd ?? process.cwd());
+        if (!(await stat(resolved)).isDirectory())
+            throw new Error('--cwd must be a directory');
+        return resolved;
+    });
+    if (!config.providers.length && !interactive)
+        await startupReject('No providers configured. Run andorra, then /providers to add a provider before starting a task.');
+    await startupGuard(async () => {
+        if (values.provider) {
+            if (!config.providers.some(p => p.id === values.provider))
+                throw new Error(`Unknown provider: ${values.provider}`);
+            config.provider = values.provider;
+        }
+        if (values.model) {
+            const selected = config.providers.find(p => p.id === config.provider);
+            if (!selected)
+                throw new Error('Add a provider in /providers before choosing a model.');
+            if (selected.model !== values.model) {
+                applyModelContextWindow(selected, values.model);
+                delete selected.reasoningEffort;
+            }
+            recordProviderModel(selected, values.model);
+            selected.model = values.model;
+        }
+    });
+    const permissions = values.yolo ? 'full-access' : config.workspacePermissions?.[workspacePermissionKey(workspace)] ?? 'ask-for-approval';
+    // `--jev on|off` is this session's decision policy the way `--yolo` is its permission mode: it is
+    // never written to the configuration, and an explicit `/jev on|off` during the session replaces it.
+    let jevOverride = values.jev === undefined ? undefined : values.jev === 'on';
+    const jevOn = () => jevOverride ?? config.jevEnabled !== false;
+    const afterJevCommand = (input, result) => {
+        const match = /^\/jev(?:\s+(on|off|status))?\s*$/.exec(input.trim());
+        if (!match || jevOverride === undefined)
+            return;
+        if (match[1] === 'on' || match[1] === 'off')
+            jevOverride = undefined;
+        else
+            result.text += `\nThis session started with --jev ${jevOverride ? 'on' : 'off'}, which overrides the saved preference until /jev on|off.`;
+    };
+    const state = await startupGuard(async () => ({ config, workspace, graph: values.graph ?? configuredGraphSelection(config, await currentGraphSubject()), permissions, yolo: permissions === 'full-access', usage: { inputTokens: 0, outputTokens: 0, requests: 0 }, notify: print, history: [],
+        // Direct /model shares the graph-override question with the /model screen; without a
+        // terminal the answer is always "keep", so nothing is ever overridden unobserved.
+        confirmModelOverride: async (question) => {
+            if (!terminal)
+                return false;
+            const choice = await terminal.select('Override graph models?', [
+                { id: 'override', label: 'Override every node with the new model', description: 'Saves the graph; every node and delegation follows this model.' },
+                { id: 'keep', label: 'Keep the models selected in the graph', description: 'Cancels this model change; nothing is saved.' },
+            ], { description: question });
+            return choice === 'override';
+        } }));
+    // A saved per-account graph selection re-checks membership on every launch, so a transient
+    // account-service failure or a membership lapse must not deny the whole session: fall back
+    // to the local Software Engineer graph and say so. A selection whose providers this machine
+    // cannot serve stays selected instead — the session refresh reports it and the header asks for
+    // the model override that runs it, so /model is one command away rather than a re-selection.
+    // An explicit --graph flag still fails fast because the caller asked for that exact graph.
+    let startupGraph;
+    let startupGraphSelection;
+    let startupGraphReused = false;
+    let graphFallbackNotice;
+    await startupGuard(async () => {
+        const selection = state.graph ?? 'default';
+        if (selection === 'default')
+            return;
+        try {
+            startupGraph = await loadGraph(selection);
+            startupGraphSelection = selection;
+        }
+        catch (error) {
+            // Nothing is printed here: the refresh right below the terminal's start reports the
+            // binding failure and sets the override hint, so the reason and the way out arrive together.
+            if (error instanceof GraphProviderUnavailableError && values.graph === undefined)
+                return;
+            if (values.graph !== undefined || !(error instanceof PaidMembershipRequiredError))
+                throw error;
+            state.graph = 'default';
+            graphFallbackNotice = graphFallbackReason(error);
+            if (!interactive)
+                process.stderr.write(safeTerminal(graphFallbackNotice) + '\n');
+        }
+    });
+    let activeUsage = { inputTokens: 0, outputTokens: 0, requests: 0, cacheRead: 0, cacheWrite: 0 };
+    // Cache totals stay sparse: a provider that reports no cache counts must not
+    // materialize explicit zeros in persisted session state or the /usage screen.
+    const foldCache = (target, cacheRead, cacheWrite) => {
+        const read = (target.cacheRead ?? 0) + (cacheRead ?? 0);
+        if (read > 0)
+            target.cacheRead = read;
+        const write = (target.cacheWrite ?? 0) + (cacheWrite ?? 0);
+        if (write > 0)
+            target.cacheWrite = write;
+    };
+    // Input size of the most recent model request, i.e. how full the live conversation
+    // context currently is. Providers that report no usage leave it at its last value.
+    let contextUsedTokens = 0;
+    // The reading the record keeps for the desktop's context ring: only what the current run
+    // measured, never the footer's estimates. The window is left out — the footer sizes against
+    // the active provider, not the model that answered — so the desktop sizes it from configuration.
+    let runContext;
+    const sessionUsage = () => ({
+        requests: state.usage.requests + activeUsage.requests,
+        inputTokens: state.usage.inputTokens + activeUsage.inputTokens,
+        outputTokens: state.usage.outputTokens + activeUsage.outputTokens,
+        cacheRead: (state.usage.cacheRead ?? 0) + activeUsage.cacheRead,
+        cacheWrite: (state.usage.cacheWrite ?? 0) + activeUsage.cacheWrite,
+        contextUsed: contextUsedTokens,
+    });
+    const sessionContexts = new Map();
+    const contextKey = (provider) => JSON.stringify([
+        provider.id, provider.type, provider.baseUrl, provider.model, provider.apiKeyEnv, provider.contextWindow,
+    ]);
+    const runtimeProvider = (provider) => ({
+        ...provider, contextWindow: sessionContexts.get(contextKey(provider)) ?? provider.contextWindow,
+    });
+    // Config is known only now (the journal starts before config load), so provider credentials
+    // register here; mid-session /providers edits re-register through the same helper.
+    trajectory.addSecrets(providerSecrets(config.providers));
+    const selectedProvider = config.providers.find(p => p.id === config.provider);
+    await debugRecord('session.context', {
+        workspace, yolo: state.yolo, graph: state.graph ?? 'default', provider: config.provider, model: selectedProvider?.model,
+        providers: config.providers.map(provider => ({ id: provider.id, type: provider.type, baseUrl: provider.baseUrl, model: provider.model, ...(provider.contextWindow !== undefined ? { contextWindow: provider.contextWindow } : {}) })),
+    });
+    const sessionDescription = () => `Conversation ID: ${savedSession?.id ?? trajectory.sessionId}\nTrajectory: ${trajectory.path}`;
+    const sessions = new SessionStore(configDirectory());
+    const tabTitle = new SessionTitle({ isTTY: interactive && process.stdout.isTTY, write: text => process.stdout.write(text) });
+    let savedSession;
+    let sessionArchive = [];
+    let awaitingInput = 0;
+    const updateTitle = (working = true) => tabTitle.set(savedSession?.name ?? '', working ? (awaitingInput || runControl?.isPaused ? 'input' : 'working') : 'idle');
+    const persistSession = async (pendingTask, pendingRunId, pendingAttachments) => {
+        if (!savedSession)
+            return;
+        const pendingHistory = pendingTask ? [{ task: pendingTask, completion: { summary: RUNNING_TURN_SUMMARY, tests: [], status: 'running' }, ...(pendingRunId === undefined ? {} : { runId: pendingRunId }), ...(pendingAttachments?.length ? { attachments: pendingAttachments } : {}) }] : [];
+        savedSession = { projectId: savedSession.projectId ?? projectIdentity(workspace), ...savedSession, contextHistory: [...state.history ?? [], ...pendingHistory].slice(-6), updatedAt: new Date().toISOString(), history: [...sessionArchive, ...pendingHistory], usage: { ...state.usage }, trajectoryId: trajectory.sessionId };
+        const record = savedSession;
+        try {
+            // This command's copy of the session was read when it started, while the desktop archives
+            // and renames through its own process. Take the same per-session mutation lock every rail
+            // mutation takes, read the stored record under it, and carry the fields that belong to the
+            // rail, or a save here silently returns an archived session to the working rail. A lock
+            // another process will not give up is not a reason to lose this turn: the save then goes
+            // through unmerged, which is exactly what it did before.
+            let releaseRailLock;
+            try {
+                releaseRailLock = await acquireSessionMutationLock(configDirectory(), record.id);
+            }
+            catch { /* held elsewhere: save unmerged rather than not at all */ }
+            try {
+                if (releaseRailLock) {
+                    let stored;
+                    try {
+                        stored = JSON.parse(await readFile(join(configDirectory(), 'sessions', `${record.id}.json`), 'utf8'));
+                    }
+                    catch { /* no record yet: nothing to carry */ }
+                    carryRailOwnedFields(record, stored);
+                }
+                if (browserBridge)
+                    await browserBridge.persist(() => sessions.save(record));
+                else
+                    await sessions.save(record);
+            }
+            finally {
+                await releaseRailLock?.().catch(() => { });
+            }
+        }
+        catch (error) {
+            const message = `Could not save session: ${error instanceof Error ? error.message : String(error)}`;
+            if (values.json)
+                process.stderr.write(safeTerminal(message) + '\n');
+            else
+                print(message);
+        }
+    };
+    const directory = configDirectory();
+    // Spooled attachments are files, not records: retire the ones no conversation can still reference.
+    void pruneAttachments(directory).catch(() => { });
+    let browserApp;
+    let browserBridge;
+    const browserSteering = [];
+    let browserPrompt;
+    let browserAcceptance = Promise.resolve();
+    let browserRollbackFailed = false;
+    // Finalization keeps the session non-idle so the browser cannot submit into
+    // a terminal whose next question is not armed yet. A cancellation recorded
+    // while a durably accepted prompt is still starting aborts it at run start.
+    let browserDraining = false;
+    let browserCancelPending = false;
+    const rollbackFailureMessage = 'Session storage rollback failed. Repair local storage and inspect session history before restarting this CLI.';
+    await startupGuard(() => mkdir(runRecordsDirectory(directory), { recursive: true }));
+    // Attempts a previous process left in flight (or never opened a record for at all) are classified
+    // before this one can write any: the pass reads pids and rewrites markers, and sessions are not
+    // loaded yet here, so it can never race an in-memory copy. Best-effort: a damaged home must not
+    // block opening the CLI.
+    try {
+        const recovered = await reconcileInterruptedRuns(directory, undefined, { skipOwnProcess: true, includePending: true });
+        // A recovered run still owes its `interrupted` finish, so the pair joins through the same
+        // telemetry id the open record carried.
+        await reportInterruptedRuns({ home: directory, surface: configuredSurface('cli') }, recovered.interrupted);
+        const parts = [];
+        if (recovered.runs.length > 0)
+            parts.push(`${recovered.runs.length} interrupted run${recovered.runs.length === 1 ? '' : 's'}`);
+        if (recovered.markers > 0)
+            parts.push(`${recovered.markers} unfinished turn${recovered.markers === 1 ? '' : 's'}`);
+        if (parts.length > 0) {
+            const notice = `Recovered ${parts.join(' and ')} from earlier sessions.`;
+            if (values.json)
+                process.stderr.write(safeTerminal(notice) + '\n');
+            else
+                print(notice);
+        }
+    }
+    catch { /* Recovery is best effort. */ }
+    let runEventSink;
+    const codeIntelLabel = (state) => state === 'indexing' ? 'Indexing' : state === 'ready' ? 'Ready' : state === 'syncing' ? 'Updating'
+        : state === 'degraded' ? 'Degraded' : state === 'error' ? 'Error' : undefined;
+    const codeIntelNotice = (event) => {
+        if (event.type === 'codeintel.state') {
+            const label = codeIntelLabel(event.data.state);
+            terminal?.setStatus({ codeIntel: label });
+            if (event.data.state === 'error')
+                process.stderr.write(`CodeGraph: ${String(event.data.detail ?? 'unavailable')}\n`);
+        }
+    };
+    // A shell commonly starts in the user's home. Never recursively index that
+    // personal tree as an implicit side effect of opening the coding client.
+    // This override is session-only; /codegraph enable remains an explicit opt-in.
+    const homeWorkspace = workspace === await realpath(homedir()).catch(() => homedir());
+    const codeIntel = await startupGuard(() => CodeIntelligenceManager.create({
+        permissions: state.permissions,
+        config: homeWorkspace ? { ...resolveCodeIntelConfig(config), enabled: false, enabledRepos: [] } : resolveCodeIntelConfig(config), workspace,
+        onEvent: event => (runEventSink ?? codeIntelNotice)(event),
+    }));
+    releaseCodeIntel = () => codeIntel.dispose();
+    state.codeIntel = codeIntel;
+    /**
+     * Feed the side panel's live sections: the working tree, the branch, and the terminals.
+     *
+     * The Git summary spawns `git`, so it runs at most once at a time and not more often than the
+     * panel could show a difference - a run that writes a file per second must not spawn a process
+     * per file, and a reader only needs the count to move. A call the throttle or an in-flight read
+     * turns away is not dropped: it is remembered as pending and re-run when the read settles, so
+     * the last event before a quiet stretch is still reflected. The branch is read here rather than
+     * only at run boundaries because a tool can switch branches mid-run, and reading it is two
+     * bounded file reads (`gitBranch` never executes anything). The terminal list needs no care at
+     * all: the QA PTY sessions live in this process, so listing them is a map walk.
+     * @param force - read the working tree now, ignoring the throttle. Run boundaries pass it;
+     *   tool completions do not, so a tool-heavy run cannot spawn hundreds of git processes.
+     */
+    let changesInFlight = false;
+    let changesReadAt = 0;
+    let changesPending;
+    let changesEverRead = false;
+    let changesTimer;
+    let terminalsTimer;
+    const panelReads = new AbortController();
+    const CHANGE_REFRESH_MS = 2_000;
+    const TERMINAL_WATCH_MS = 1_000;
+    const listTerminals = () => getQaPtyManager(workspace).list().map(session => ({ id: session.id, command: session.command, running: session.running, startedAt: session.startedAt }));
+    /**
+     * Notice a background terminal that exits on its own.
+     *
+     * The manager records the exit in its own session, but nothing in the tool flow reports it:
+     * without this watch the panel would keep a finished session as running, keep counting its age
+     * up, and keep the frame's clock ticking until the run ended. The watch exists only while a
+     * displayed session is running, and the map walk it performs is free.
+     */
+    const watchTerminals = (sessions) => {
+        const running = sessions.some(session => session.running);
+        if (running && !terminalsTimer) {
+            terminalsTimer = setInterval(() => {
+                // The ages it maintains are only drawn by the panel: hidden, the watch stops and the
+                // `panel` event re-arms it when the panel comes back.
+                if (!terminal || !terminal.panelVisible()) {
+                    clearInterval(terminalsTimer);
+                    terminalsTimer = undefined;
+                    return;
+                }
+                const listed = listTerminals();
+                terminal.setStatus({ terminals: listed });
+                if (!listed.some(session => session.running)) {
+                    clearInterval(terminalsTimer);
+                    terminalsTimer = undefined;
+                }
+            }, TERMINAL_WATCH_MS);
+            terminalsTimer.unref?.();
+        }
+        else if (!running && terminalsTimer) {
+            clearInterval(terminalsTimer);
+            terminalsTimer = undefined;
+        }
+    };
+    const readChanges = () => {
+        changesInFlight = true;
+        changesPending = undefined;
+        if (changesTimer) {
+            clearTimeout(changesTimer);
+            changesTimer = undefined;
+        }
+        void gitChangeSummary(workspace, { signal: panelReads.signal })
+            .then(changes => { changesReadAt = Date.now(); changesEverRead = true; terminal?.setStatus({ changes }); })
+            .catch(() => {
+            // A read that failed leaves the last good reading in place, and it counts as an attempt:
+            // a repository that rejects every read (an unreadable index, a filter it cannot vouch for)
+            // must not make each following tool event start another full scan. With nothing to keep,
+            // the section is told the reading is unavailable instead of claiming to still read.
+            changesReadAt = Date.now();
+            if (!changesEverRead) {
+                terminal?.setStatus({ changes: { isGit: true, files: 0, untracked: 0, insertions: 0, deletions: 0, unavailable: 'the working tree could not be read' } });
+            }
+        })
+            .finally(() => {
+            changesInFlight = false;
+            const pending = changesPending;
+            changesPending = undefined;
+            if (panelReads.signal.aborted || pending === undefined)
+                return;
+            // A queued forced read (a run boundary) starts now; a queued tool boundary waits out the
+            // rest of the window it was turned away from, so draining the queue cannot run two scans
+            // milliseconds apart.
+            // Through the gate even here: the panel may have been hidden (a narrowed terminal, the
+            // dashboard, a modal) between the request and this drain.
+            if (pending === 'force')
+                refreshPanelStatus(true);
+            else
+                scheduleChanges(CHANGE_REFRESH_MS - (Date.now() - changesReadAt));
+        });
+    };
+    /**
+     * Read now, or at the end of the throttle window - never later, and never not at all.
+     *
+     * A request that arrives inside the window is queued rather than dropped, and because nothing
+     * else would come back for it, the queue is drained by a timer armed for the remainder of the
+     * window: the last tool completion of a quiet task must still reach the panel, and a run that
+     * ends while a read is in flight must not leave the counts behind an unsettled snapshot.
+     */
+    const scheduleChanges = (delayMs) => {
+        if (changesTimer || panelReads.signal.aborted)
+            return;
+        // Through the gate, not around it: the panel may have been hidden (a narrowed terminal, the
+        // dashboard) between the request and its timer, and a hidden panel buys no git process.
+        changesTimer = setTimeout(() => { changesTimer = undefined; refreshPanelStatus(true); }, Math.max(0, delayMs));
+        changesTimer.unref?.();
+    };
+    const refreshPanelStatus = (force = false) => {
+        if (!terminal)
+            return;
+        // The panel is the only consumer of both reads, so a terminal that cannot show it - too
+        // narrow, too short, or on the dashboard or a modal screen - costs nothing: no terminal list,
+        // no branch read and, above all, no git process. `panel-visible` brings the summary back when
+        // a resize or a closed screen makes the panel reachable again.
+        if (!terminal.panelVisible()) {
+            changesPending = undefined;
+            return;
+        }
+        const sessions = listTerminals();
+        terminal.setStatus({ terminals: sessions });
+        watchTerminals(sessions);
+        void gitBranch(workspace).then(branch => terminal?.setStatus({ branch }));
+        // The queue remembers which kind of request is waiting, because the two are drained
+        // differently and a forced request must not be softened into a throttled one.
+        if (changesInFlight) {
+            changesPending = force || changesPending === 'force' ? 'force' : 'throttled';
+            return;
+        }
+        const remaining = CHANGE_REFRESH_MS - (Date.now() - changesReadAt);
+        if (!force && remaining > 0) {
+            scheduleChanges(remaining);
+            return;
+        }
+        readChanges();
+    };
+    let jevEnabled = jevOn();
+    if (interactive)
+        await startupGuard(async () => {
+            const selected = config.providers.find(p => p.id === config.provider);
+            const codeIntelState = codeIntelLabel((await codeIntel.getStatus()).state);
+            terminal = new TerminalUI({ account: { label: 'Checking account...', notice: 'Checking member access. Local Software Engineer remains available.' }, workspace, provider: selected?.id ?? 'No provider', model: selected?.model ?? '/providers to configure', providerModels: Object.fromEntries(config.providers.map(p => [p.id, p.model])), reasoningEffort: selected?.reasoningEffort, contextWindow: selected?.contextWindow, version: await cliVersion(), branch: await gitBranch(workspace), yolo: state.yolo, permissions: permissionLabel(state.permissions), graphSelection: state.graph ?? 'default', // The refresh below reads the definition of a graph that cannot bind, so construction must not depend on binding it.
+                graph: startupGraph ?? await loadGraph(state.graph ?? 'default').catch(() => undefined), ...(codeIntelState ? { codeIntel: codeIntelState } : {}), clipboardImageProbe: readClipboardImage, clipboardTextWriter: writeClipboardText });
+            terminal.setLocalCommandHandler((input, mode, durationMs) => {
+                // Local view commands never reach either CLI command loop.
+                void debugRecord('command.started', { input, mode });
+                void debugRecord('command.completed', { input, mode, durationMs });
+            });
+            terminal.setStatus({ codeIntel: codeIntelLabel((await codeIntel.getStatus()).state), jevEnabled });
+            // The first render after `start()` announces the panel when it is visible, and that event owns
+            // the first summary: asking here as well would run the whole multi-process read twice on every
+            // wide-terminal launch.
+            terminal.on('panel', () => refreshPanelStatus(true));
+            if (graphFallbackNotice)
+                terminal.print(graphFallbackNotice);
+        });
+    const refreshStatus = () => {
+        jevEnabled = jevOn();
+        const configured = config.providers.find(p => p.id === config.provider);
+        const selected = configured ? runtimeProvider(configured) : undefined;
+        terminal?.setStatus({ provider: selected?.id ?? 'No provider', model: selected?.model ?? '/providers to configure', providerModels: Object.fromEntries(config.providers.map(p => [p.id, p.model])), reasoningEffort: selected?.reasoningEffort, contextWindow: selected?.contextWindow, yolo: state.yolo, permissions: permissionLabel(state.permissions), jevEnabled, ...sessionUsage() });
+    };
+    let graphModelsHealthy = false;
+    const refreshGraphStatus = async () => {
+        if (terminal) {
+            const controller = active ?? new AbortController();
+            const ownsController = !active;
+            if (ownsController)
+                active = controller;
+            terminal.setStatus({ activity: 'Checking graph models' });
+            graphModelsHealthy = false;
+            // Run preflights reuse the startup graph until a refresh replaces it; dropping the
+            // cache first means a failed refresh falls back to loading again at run time.
+            startupGraph = undefined;
+            startupGraphSelection = undefined;
+            startupGraphReused = false;
+            try {
+                let graph;
+                try {
+                    graph = await loadGraph(state.graph ?? 'default', controller.signal);
+                }
+                catch (error) {
+                    // A graph that cannot bind keeps the selection: `/graph` has just accepted it (or the
+                    // user is about to repair it with /model), the run is what refuses it, and replacing it
+                    // with Default here would silently undo the choice — and point /model's repair at the
+                    // wrong graph. Its definition is still read, unbound, so the status bar names it; the
+                    // run preflight keeps loading the bound graph, so the refusal stays where it belongs.
+                    if (error instanceof GraphProviderUnavailableError) {
+                        const definition = await loadGraph(state.graph ?? 'default', controller.signal, undefined, { bindProviders: false }).catch(() => undefined);
+                        if (!controller.signal.aborted) {
+                            // The hint is what the session should do about the selection, so it is set from the
+                            // binding failure itself; the unbound definition only names the graph beside it.
+                            terminal.setStatus({ graphSelection: state.graph ?? 'default', ...(definition === undefined ? {} : { graph: definition }), graphNeedsOverride: true, jevEnabled: jevOn() });
+                            print(error.message);
+                        }
+                        return;
+                    }
+                    // The refresh path applies the same membership fallback as startup: without it the
+                    // denial would only print here while state.graph stays on the paid graph and the first
+                    // task retries the denied selection.
+                    if (values.graph !== undefined || (state.graph ?? 'default') === 'default' || !(error instanceof PaidMembershipRequiredError))
+                        throw error;
+                    state.graph = 'default';
+                    graphFallbackNotice = graphFallbackReason(error);
+                    print(graphFallbackNotice);
+                    graph = await loadGraph('default', controller.signal);
+                }
+                startupGraph = graph;
+                startupGraphSelection = state.graph ?? 'default';
+                jevEnabled = jevOn();
+                terminal.setStatus({ graphSelection: state.graph ?? 'default', graph, graphNeedsOverride: false, jevEnabled });
+                const health = await checkGraphHealth(graph, config, controller.signal);
+                graphModelsHealthy = health.healthy;
+                if (!health.healthy)
+                    print(formatGraphHealthFailure(health));
+            }
+            finally {
+                if (ownsController)
+                    active = undefined;
+                terminal.setStatus({ activity: graphModelsHealthy ? 'Ready' : 'Graph models unavailable' });
+            }
+        }
+    };
+    const graphEditor = createGraphEditorSession();
+    let accountRefresh;
+    let accountRefreshTimer;
+    let accountPolling;
+    const refreshAccountStatus = async () => {
+        accountRefresh?.abort();
+        const request = accountRefresh = new AbortController();
+        try {
+            const account = await getAccountPresentation(request.signal);
+            if (!request.signal.aborted)
+                terminal?.setStatus({ account });
+        }
+        catch { /* Cancellation leaves the next refresh in control. */ }
+    };
+    let active;
+    let exiting = false;
+    const scheduleAccountRefresh = () => {
+        if (!terminal || exiting || accountRefreshTimer)
+            return;
+        accountRefreshTimer = setTimeout(() => { accountRefreshTimer = undefined; if (!exiting)
+            void refreshAccountStatus(); }, 250);
+        accountRefreshTimer.unref?.();
+    };
+    let runControl;
+    let approvePending;
+    // Self-wake prompts armed by the agent's set_timer tool. A due prompt goes to whichever
+    // surface can take it right now: a live terminal-graph run consumes it as steering at its
+    // next turn boundary, and an idle conversation composer receives it as a new task. Anywhere
+    // else - a command screen, a browser task, the save/teardown window between runs - it waits
+    // in `timerPending` until a composer or a turn boundary comes back to collect it, so a
+    // prompt is never delivered to the wrong surface and never silently dropped.
+    const sessionTimers = new TimerRegistry();
+    const timerSteering = [];
+    const timerPending = [];
+    // Set when a timer's prompt resumed a paused run: prepareTurn injects steering *before*
+    // the direction queue, so any later timer must hold in `timerPending` until the poll that
+    // carried the resume direction has happened, and only then join the steering channel.
+    // Without the hold, the later prompt would reach the model ahead of the earliest deadline.
+    let timerResumePending = false;
+    const deliverTimerPrompts = () => {
+        // Canceled runs may not receive a prompt that no conversation will ever read, so past
+        // teardown the due timers are reaped and discarded rather than queued.
+        if (exiting) {
+            sessionTimers.takeDue();
+            return;
+        }
+        // `takeDue` returns prompts soonest-deadline first, so every channel below preserves order.
+        for (const due of sessionTimers.takeDue())
+            timerPending.push(`[Timer] ${due.prompt}`);
+        while (timerPending.length) {
+            const text = timerPending[0];
+            if (runControl && active && !active.signal.aborted) {
+                // A paused run is blocked in RunControl.wait() until resume(): only that call both
+                // clears the pause and carries a direction in, which is why user steering from the
+                // browser resumes with its text instead of queueing. A timer due mid-pause must wake
+                // the run the same way, or the promised self-wake waits for the user to type.
+                if (runControl.isPaused) {
+                    if (runControl.resume(text)) {
+                        timerResumePending = true;
+                        timerPending.shift();
+                    }
+                    else
+                        break;
+                }
+                else if (timerResumePending)
+                    break;
+                else
+                    timerSteering.push(timerPending.shift());
+                continue;
+            }
+            // Runs this process executes through `run()` — terminal tasks and prompts accepted by
+            // the authenticated browser bridge — drain `timerSteering` at their turn boundaries. A
+            // task owned by the standalone browser server polls its own queue instead, so a timer
+            // due then waits in `timerPending` and reaches the composer when the terminal is idle.
+            if (terminal?.acceptConversationPrompt(text)) {
+                timerPending.shift();
+                continue;
+            }
+            break;
+        }
+    };
+    sessionTimers.onDue = deliverTimerPrompts;
+    // Ctrl+C escalates: the first press stops the live run — pausing interactive runs so a
+    // message can resume them, aborting everything else — and the next press, or a press with
+    // nothing left to stop, terminates the program. A run that keeps running past its abort
+    // signal would otherwise leave Ctrl+C with no remaining effect.
+    const interrupt = () => {
+        if (runControl) {
+            if (runControl.isPaused)
+                kill();
+            else
+                runControl.pause();
+        }
+        else if (active) {
+            if (active.signal.aborted)
+                kill();
+            else
+                active.abort();
+        }
+        else
+            kill();
+    };
+    const teardown = () => { terminated = true; exiting = true; active?.abort(); sessionTimers.clear(); terminal?.close(); };
+    // The Ctrl+C escalation must not become a suggestion: after the terminal is restored, a
+    // run wedged past its abort signal gets a short grace window and then a hard exit.
+    // SIGTERM keeps the patient teardown instead — cleanup of a canceled shell tree is a
+    // bounded wait that outlives this window, and its contract is tested to finish it.
+    // The timer stays referenced on purpose: a wedge can leave main() awaiting a promise
+    // with no other live handle, and an unreferenced timer would let the event loop drain
+    // and the process exit with the implicit status 0 before the backstop ever fires.
+    let killBackstop;
+    const kill = () => {
+        teardown();
+        if (!killBackstop)
+            killBackstop = setTimeout(() => process.exit(143), 2_000);
+    };
+    process.on('SIGINT', interrupt);
+    process.on('SIGTERM', teardown);
+    terminal?.on('SIGINT', interrupt);
+    terminal?.on('close', () => { tabTitle.close(); exiting = true; active?.abort(); });
+    /**
+     * Carry one attempt into the next turn's context. The turns live on `state` so commands
+     * such as /compact and /clear can replace them and the next run sees the result.
+     *
+     * A turn that failed, was cancelled, or crashed still happened: the user asked for this
+     * work and the agent may already have read files or changed the workspace. Dropping it
+     * would make the next message start from a blank history, so the task is retained with a
+     * plain statement of how it ended instead of a fabricated success.
+     * @param task - the task the user submitted.
+     * @param completion - the validated completion, or a summary of the outcome.
+     */
+    const rememberTurn = (task, completion, runId, attachments) => {
+        sessionArchive.push({ task, completion, runId, ...(attachments?.length ? { attachments } : {}) });
+        state.history = [...state.history ?? [], { task, completion, runId, ...(attachments?.length ? { attachments } : {}) }].slice(-6);
+    };
+    /** Render how an attempt ended as history the next turn can read. */
+    const outcomeCompletion = (status, reason, limits) => ({
+        summary: status === 'cancelled'
+            ? 'This attempt was cancelled before it finished; its work may be incomplete.'
+            : `This attempt did not finish: ${stopReasonPhrase(reason, limits)}.`,
+        tests: [], ...(status === 'succeeded' ? {} : { status: status }),
+    });
+    const toolActivity = new ToolActivity();
+    /** The task text an attachment-only submission runs with; both surfaces substitute the same words. */
+    const ATTACHMENT_ONLY_TASK = 'See the attached file(s).';
+    const run = async (task, pending = []) => {
+        if (browserRollbackFailed)
+            throw new Error(rollbackFailureMessage);
+        if (!config.providers.length) {
+            print('Add a provider in /providers before starting a task.');
+            return 1;
+        }
+        // Attachments resolve to disk-backed refs once, before any record names them: a bad
+        // reference refuses the whole turn rather than half-attaching.
+        if (pending.length && terminal)
+            terminal.print(`⌷ attached: ${pending.map(attachmentLabel).join('  ·  ')}`);
+        let attachments;
+        // Spool directories this run's attached content lives in: the tool layer reads them as
+        // trusted paths, so a paste is readable in every permission mode, steers included. The
+        // replayed history's spools count too — the model is told to read those files again — but
+        // they are owned by the persisted turns, so only this run's steers are cleaned up below.
+        const attachmentSpools = new Set();
+        const steeredSpools = new Set();
+        for (const root of await attachmentReadRoots(directory, (state.history ?? []).flatMap(turn => turn.attachments ?? [])))
+            attachmentSpools.add(root);
+        if (pending.length) {
+            try {
+                attachments = await resolveAttachments(directory, workspace, pending);
+            }
+            catch (error) {
+                print(`Could not attach the queued attachments: ${error instanceof Error ? error.message : String(error)}. The task was not started; re-attach and resend.`);
+                return 1;
+            }
+            for (const root of await attachmentReadRoots(directory, attachments.refs))
+                attachmentSpools.add(root);
+        }
+        // Cancellation must already own this run while its first snapshot is pending.
+        active = new AbortController();
+        if (browserCancelPending) {
+            browserCancelPending = false;
+            active.abort(new Error('Cancelled from browser'));
+        }
+        browserPrompt = task;
+        trajectory.addSecrets(providerSecrets(config.providers));
+        if (!savedSession) {
+            savedSession = { version: 1, id: trajectory.sessionId, name: sessionName(task), workspace, updatedAt: new Date().toISOString(), history: [], usage: { ...state.usage } };
+            // This is the creation this event names: the first task that lands on the session.
+            noteSessionStarted({ workspace });
+        }
+        const accepted = browserAcceptance;
+        browserAcceptance = Promise.resolve();
+        try {
+            await accepted;
+        }
+        catch (error) {
+            active = undefined;
+            browserPrompt = undefined;
+            throw error;
+        }
+        browserBridge?.startRun();
+        const runId = randomUUID();
+        // The telemetry id is random and unrelated to the persisted run id, which is derived from local
+        // state. It is written into the open record so recovery can still join a crash's pair.
+        const telemetryRunId = randomUUID();
+        const startedAt = new Date().toISOString();
+        // Whether a checkpoint could not be written. A checkpoint is the conversation a resume
+        // re-enters the node with, so a run whose checkpoint failed is one no resume may replay: the
+        // resume would re-enter the node from its opening task and repeat the tool calls it had
+        // already made. The failure is marked, and the record carries it past a crash.
+        let checkpointFailed = false;
+        // The selector this attempt runs on, captured at start. Every record the attempt writes
+        // carries it: the result's own `graph` is the pinned graph object, whose id is the bundled
+        // harness's id rather than the selection that loaded it ('default' loads `software-engineer`),
+        // and a resume has to re-select through the same access rules — so it needs this, not the
+        // pinned identity. Captured here rather than re-read at finalize, where a later /graph change
+        // could mislabel the attempt.
+        const runGraphSelection = state.graph ?? 'default';
+        // Bind persisted run inspection to the signed-in account at run creation.
+        const accountSubject = await currentGraphSubject();
+        // The flushable telemetry handle, created before the first terminal path can reach it. The
+        // graph's own size is filled in once it is pinned; until then the open record and a crash carry
+        // zeros rather than a guess.
+        const telemetrySurface = { home: directory, config, ...(accountSubject ? { subject: accountSubject } : {}), surface: configuredSurface('cli') };
+        const telemetryHandle = createRunHandle(telemetryRunId, startedAt, {
+            graphId: runGraphSelection, nodes: 0, subagents: false, permissionMode: state.permissions,
+            jevEnabled: jevOn(), decisionRouting: config.decisions?.mode ?? 'off',
+        }, workspace);
+        let telemetryFinished = false;
+        let telemetryStart;
+        let telemetrySettled = Promise.resolve();
+        // One start per run, and the finish waits for it: a preflight failure reaches the finish before
+        // the normal start site, and emitting the finish alone would leave a run with no start.
+        const startTelemetry = () => {
+            telemetryStart ??= reportRunStarted(telemetrySurface, telemetryHandle).catch(() => { });
+            return telemetryStart;
+        };
+        // Preflight probes are billed requests this attempt made, so they get their own model tuples:
+        // without one, `models[].requests` and the token totals omit every probe, and a run that failed
+        // the health check alone would report no model at all.
+        const probeModels = new Map();
+        // Set when the health check was rejected by the provider: the run never reached the graph, so
+        // the finish has to classify it from this evidence rather than from a missing result.
+        let healthProviderFailed = false;
+        const finishTelemetry = (status, reason, result) => {
+            if (telemetryFinished)
+                return;
+            telemetryFinished = true;
+            // The probes precede the graph, so their tuples are added to whatever capture the finish
+            // reports; a run with no result still reports them, which is the probe-only failure.
+            const capture = result?.telemetry ?? createRunTelemetry();
+            for (const probe of probeModels.values()) {
+                const provider = config.providers.find(item => item.id === probe.provider);
+                recordModelUse(capture, {
+                    ...(provider === undefined ? {} : { providerType: provider.type, baseUrl: provider.baseUrl }),
+                    model: probe.model, role: 'other', usage: probe.usage,
+                    // A probe is a billed request like any other: the user's routing prices cost it too.
+                    ...(provider === undefined ? {} : { pricing: pricingFor(config.efficiency?.adaptiveRouting, probe.provider, probe.model) }),
+                });
+            }
+            telemetrySettled = startTelemetry().then(() => reportRunFinished(telemetrySurface, telemetryHandle, {
+                status, reason,
+                ...(result?.providerRequestFailed || healthProviderFailed ? { providerRequestFailed: true } : {}),
+                ...(result?.providerOverflow ? { providerOverflow: true } : {}),
+                ...(result?.telemetry !== undefined || probeModels.size > 0 ? { telemetry: capture } : {}),
+                ...(result ? { toolCalls: result.toolCalls } : {}),
+            })).catch(() => { });
+        };
+        // Any terminal rewrite of this attempt's record keeps its identity fields and folds in the
+        // partial usage accumulated before the failure, so the Runs view never reports a crashed
+        // attempt's model calls as zero while the session totals already count them.
+        const finalizeRunRecord = async (status, reason) => {
+            const record = { id: runId, status, reason, graphSelection: runGraphSelection,
+                ...(accountSubject ? { accountSubject } : {}), usage: { ...activeUsage },
+                ...(savedSession ? { sessionId: savedSession.id } : {}), startedAt,
+                // A record that stopped being a live run says when it did. A terminal status alone cannot tell a
+                // closed attempt apart from the open claim of a run that reused this id, and that difference is
+                // what lets a claim left by a failed cleanup be reclaimed instead of holding the session busy.
+                endedAt: new Date().toISOString(),
+                // The flag a resume consults before it trusts this attempt's conversation: a checkpoint
+                // that could not be written leaves the node to be re-entered from its opening task.
+                ...(checkpointFailed ? { checkpointIntegrity: 'failed' } : {}),
+                ...(runInput === undefined ? {} : { runInput }), ...(runState === undefined ? {} : { runState }) };
+            try {
+                await writeFile(runRecordPath(directory, runId, 'json'), JSON.stringify(record, null, 2) + '\n', { mode: 0o600 });
+                await writeStudioRunSummary(directory, record).catch(() => { });
+            }
+            catch (writeError) {
+                process.stderr.write(`Could not record the stopped run: ${writeError instanceof Error ? writeError.message : String(writeError)}\n`);
+            }
+            finishTelemetry(status, reason);
+        };
+        // The attempt ends by landing this process's own session record and only then withdrawing the
+        // open claim that names the run to every engine's mutation guard. Clearing the claim before the
+        // save would let a rename, archive or delete be accepted into the window that save — written
+        // from the record this process captured at start — then silently overwrites, or recreates for a
+        // delete. Until this point the claim keeps the guard's answer true: the run may be finished, but
+        // its record is still the one arriving. On a failed save the open record and the claim both
+        // stay, and startup recovery owns that pair.
+        const settleRunRecord = async () => {
+            await persistSession();
+            await clearOpenRunClaim(directory, runId);
+        };
+        // The open record names the session and the process that own this attempt, and it lands before
+        // both the cancellation check below and the marker turn: a second engine's startup recovery
+        // must never see the marker before the record that proves the attempt is live — otherwise it
+        // classifies the live attempt as a crash and races its synthesized record against this one,
+        // exactly as the app-server path's ordering prevents. A stop arriving while the first snapshot
+        // is still saving must leave a record the Runs view can find, and the early return finalizes
+        // that record in place. The normal finalizer replaces it too; a crash before then leaves it on
+        // disk, where startup recovery turns it into an interrupted one instead of the run vanishing
+        // with only a journal behind.
+        // The run's own scope and effort ride in the open record too, not only in the result the
+        // finalizer writes: a hard kill leaves this record as the only thing recovery preserves, and a
+        // later resume of an attempt that never finalized rebuilds `$run.input.*`/`$run.state.*` from
+        // it. Persisting them only at the end would make a crashed run resume under a different scope
+        // than the one it was started with — silently dropping or changing mapped inputs.
+        // Kept in a variable because the pinned graph's real shape is stamped into it after preflight:
+        // a crash before finalization then emits an interrupted finish that matches the start instead
+        // of the zeros written here.
+        const openRecord = {
+            id: runId, status: 'running', sessionId: savedSession.id, startedAt, pid: process.pid,
+            graphSelection: runGraphSelection, ...(accountSubject ? { accountSubject } : {}),
+            graph: { id: state.graph ?? 'default' }, provider: config.provider, model: config.providers.find(p => p.id === config.provider)?.model ?? '',
+            // The producing surface travels with the record: recovery can run on another surface in the
+            // same home, and an interrupted finish must still be labeled with the one that started.
+            surface: telemetrySurface.surface,
+            // `startSent` stays false until the start is queued: this record is written before graph
+            // loading and the model-health check, and recovery reads the flag to decide whether it owes
+            // the missing start as well as the finish.
+            telemetry: { runId: telemetryRunId, nodes: 0, subagents: false, jevEnabled: jevOn(), decisionRouting: config.decisions?.mode ?? 'off', permissions: state.permissions, startSent: false },
+            ...(runInput === undefined ? {} : { runInput }), ...(runState === undefined ? {} : { runState }),
+        };
+        const openRecordWritten = await writeOpenRunRecord(directory, openRecord).then(() => true).catch(error => {
+            process.stderr.write(`Could not write the open run record: ${error instanceof Error ? error.message : String(error)}\n`);
+            return false;
+        });
+        // The marker's in-flight claim is only provable through that record: without it recovery would
+        // read the marker as an orphaned crash, so the marker stays unwritten and the run proceeds —
+        // the same order and fallback the app-server start uses.
+        // The saved reading belongs to the newest run: one this session inherited (a fork of a desktop
+        // session) or an earlier run left must not describe the run starting now.
+        runContext = undefined;
+        if (savedSession?.context !== undefined)
+            savedSession = { ...savedSession, context: undefined };
+        if (openRecordWritten)
+            await persistSession(task, runId, attachments?.refs);
+        if (active.signal.aborted || exiting) {
+            // Cancellation can arrive while the accepted prompt is still being saved,
+            // before the graph's try/finally owns cleanup. Retain the cancelled turn and
+            // clear its pending state before persisting the idle browser snapshot.
+            await finalizeRunRecord('cancelled', 'the user stopped this run');
+            rememberTurn(task, outcomeCompletion('cancelled', undefined, undefined), runId, attachments?.refs);
+            browserDraining = true;
+            active = undefined;
+            browserPrompt = undefined;
+            browserSteering.length = 0;
+            browserCancelPending = false;
+            updateTitle(false);
+            await settleRunRecord();
+            browserDraining = false;
+            return terminated ? 143 : 130;
+        }
+        updateTitle();
+        terminal?.setStatus({ session: savedSession.name });
+        // The node's furthest conversation, persisted as it is reached so a stopped run leaves a
+        // resumable checkpoint (`run.resume` in the app-server re-enters it). Writes serialize —
+        // concurrent branches must not leave an older conversation as the file's final content — and
+        // a failure only costs durability, never the run.
+        let checkpointWrites = Promise.resolve();
+        const persistCheckpoint = (nodeId, messages, state, meta) => {
+            checkpointWrites = checkpointWrites
+                .then(() => writeRunCheckpoint(directory, runId, { nodeId, messages, state, revision: state.directionRevision, savedAt: new Date().toISOString(), ...(meta?.generation === undefined ? {} : { generation: meta.generation }), ...(meta?.provider === undefined ? {} : { provider: meta.provider }), ...(meta?.model === undefined ? {} : { model: meta.model }), ...(meta?.routedFrom === undefined ? {} : { routedFrom: meta.routedFrom }) }))
+                .catch(async (error) => {
+                checkpointFailed = true;
+                await noteCheckpointWriteFailure(directory, runId, error instanceof Error ? error.message : String(error));
+                process.stderr.write(`Could not write the run checkpoint: ${error instanceof Error ? error.message : String(error)}\n`);
+            });
+            // The write is handed back so the runtime can await it: the checkpoint is the conversation a
+            // resume re-enters the node with, and a run that advanced past a mutating tool call while its
+            // checkpoint was still queued could be killed with that conversation unwritten.
+            return checkpointWrites;
+        };
+        // Interactive runs stream the model's reasoning into the terminal's live preview
+        // line. The wrap sits outside the trajectory so reasoning deltas never reach run
+        // records. Subagent calls are excluded, and so are calls that arrive while another
+        // previewing call is in flight: concurrent graph branches and parallel modifier
+        // copies carry no subagentId, and several streams sharing one preview line would
+        // interleave and flicker. The flag is claimed synchronously before the first await,
+        // so exactly one concurrent call ever owns the preview.
+        let previewInFlight = false;
+        const tracedAdapter = (provider) => {
+            if (provider.apiKey)
+                trajectory.addSecrets([provider.apiKey]);
+            if (provider.apiKeyEnv && process.env[provider.apiKeyEnv])
+                trajectory.addSecrets([process.env[provider.apiKeyEnv]]);
+            const traced = trajectory.wrap(createAdapter(provider), () => ({ runId, providerId: provider.id }));
+            if (!terminal)
+                return traced;
+            return {
+                ...(traced.listModels ? { listModels: (signal) => traced.listModels(signal) } : {}),
+                async generate(request) {
+                    // Every runtime call, previewing or not, feeds the footer's speed readout as it
+                    // streams, so a long thinking stream moves the number instead of holding it until
+                    // usage arrives. A new attempt or a failure drops the estimate; a success leaves it
+                    // for the usage delta to replace, so the reading does not flick back to the old
+                    // average in between. Calls without an invocation id (health probes) are not metered.
+                    const invocationId = request.context?.invocationId;
+                    const metered = meterStreamedRequest(request, terminal);
+                    const generate = async (call) => {
+                        try {
+                            return await traced.generate(call);
+                        }
+                        catch (error) {
+                            if (invocationId !== undefined)
+                                terminal.noteStreamEnded(invocationId);
+                            throw error;
+                        }
+                    };
+                    if (request.context?.subagentId || previewInFlight)
+                        return generate(metered);
+                    previewInFlight = true;
+                    terminal.clearThinking();
+                    // Each HTTP attempt retraces the preview, so a retried stream replaces the
+                    // failed attempt's text instead of concatenating with it.
+                    try {
+                        return await generate({
+                            ...metered,
+                            onRequest: () => { terminal.clearThinking(); metered.onRequest?.(); },
+                            onReasoning: delta => { terminal.appendThinking(delta); metered.onReasoning?.(delta); },
+                        });
+                    }
+                    finally {
+                        previewInFlight = false;
+                        terminal.clearThinking();
+                    }
+                },
+            };
+        };
+        await writeActivity(directory, 'running', { detail: task, runId });
+        // Back to running after a prompt, unless the user paused the run while it waited; paused
+        // runs are themselves waiting on the user's next message.
+        const runResumed = () => runControl?.isPaused
+            ? writeActivity(directory, 'awaiting-input', { kind: 'steering', detail: 'Paused - send a message in the terminal to steer the run', runId })
+            : writeActivity(directory, 'running', { runId });
+        runControl = terminal ? new RunControl() : undefined;
+        // A fresh control cannot hold a timer resume, so a latch left set by a run that ended
+        // between the resume and its next poll must not hold this run's first due batch.
+        timerResumePending = false;
+        if (runControl) {
+            runControl.yolo = state.yolo;
+            runControl.permissions = state.permissions;
+        }
+        const removeControlListener = runControl?.onChange(paused => {
+            updateTitle();
+            terminal?.setStatus({ activity: paused ? 'Paused' : 'Thinking' });
+            print(paused ? 'Paused. Send a message to resume with new direction; /yolo on|off changes permissions, Ctrl+C again exits.' : 'Resuming with your direction.');
+            if (paused)
+                void writeActivity(directory, 'awaiting-input', { kind: 'steering', detail: 'Paused - send a message in the terminal to steer the run', runId });
+            else
+                void writeActivity(directory, 'running', { runId });
+        });
+        let liveCommands = Promise.resolve();
+        terminal?.setRunInputHandler(text => {
+            // Composer input during a run bypasses the question loop, so it gets no outer
+            // command pair: steering text gets a single marker (delivery is traced by
+            // agent.messages.injected), while the live commands below keep full timing records.
+            if (!text.startsWith('/')) {
+                void debugRecord('command.steer', { input: text });
+                return runControl?.isPaused ? runControl.resume(text) : false;
+            }
+            const command = text.split(/\s/, 1)[0];
+            if (command === '/exit' || command === '/quit') {
+                void debugRecord('command.steer', { input: text });
+                exiting = true;
+                active?.abort();
+                terminal?.close();
+                return true;
+            }
+            if (command === '/attach') {
+                // Mid-run, an attachment rides the next steer rather than a new task.
+                void debugRecord('command.steer', { input: text });
+                const argument = text.slice('/attach'.length).trim().replace(/^"(.*)"$/, '$1');
+                const target = argument ? resolve(workspace, argument) : '';
+                if (!target || !existsSync(target))
+                    print('Usage: /attach <existing path> — attaches to your next steer.');
+                else if (terminal.addAttachment({ kind: 'file', path: target }))
+                    print(`Attached ${target}. It rides your next steer.`);
+                return true;
+            }
+            if (!['/browser', '/yolo', '/permissions', '/jev', '/help', '/status', '/usage', '/tools'].includes(command)) {
+                void debugRecord('command.steer', { input: text });
+                print(`${command} is unavailable during a run. Use /permissions <mode>, /yolo on|off, /jev on|off, /status, /usage, /help, or /exit.`);
+                return true;
+            }
+            const commandStartedAt = Date.now();
+            void debugRecord('command.started', { input: text, mode: 'in-run' });
+            // Create each command's draft only after prior saves and live updates finish.
+            // Even status commands must queue: executeCommand commits their draft too.
+            liveCommands = liveCommands.then(async () => {
+                if (command === '/browser') {
+                    browserApp ??= await startBrowserServer();
+                    // Teardown can pass the cleanup loop while this startup is pending;
+                    // a server that finishes after exiting must neither open nor linger.
+                    if (exiting)
+                        await browserApp.close().catch(() => { });
+                    else {
+                        print(`Andorra Browser: ${browserApp.url}`);
+                        openBrowserUrl(browserApp.url);
+                    }
+                }
+                else {
+                    // `/jev` saves at once but the run keeps the decision policy it started with; the reply says so.
+                    // The spread shares `state.config`, so the saved value lands on the session's configuration.
+                    const commandState = command === '/usage' ? { ...state, usage: sessionUsage() } : command === '/jev' ? { ...state, running: true } : state;
+                    const result = await executeCommand(text, commandState, persistConfig);
+                    afterJevCommand(text, result);
+                    if (runControl) {
+                        runControl.yolo = state.yolo;
+                        runControl.permissions = state.permissions;
+                    }
+                    if (state.yolo)
+                        approvePending?.();
+                    print(result.text);
+                    if (command === '/status')
+                        print(sessionDescription());
+                    refreshStatus();
+                }
+                void debugRecord('command.completed', { input: text, mode: 'in-run', durationMs: Date.now() - commandStartedAt });
+            }).catch(error => {
+                const message = error instanceof Error ? error.message : String(error);
+                print(message);
+                void debugRecord('command.error', { input: text, mode: 'in-run', message });
+                void debugRecord('command.completed', { input: text, mode: 'in-run', durationMs: Date.now() - commandStartedAt });
+            });
+            return true;
+        });
+        terminal?.startTask();
+        // A run's own preflight and teardown both change what the working tree holds.
+        refreshPanelStatus(true);
+        const retainedTodos = continuedTodos(task, state.lastRun);
+        const todoStore = new TodoStore();
+        if (retainedTodos.length)
+            todoStore.update(retainedTodos);
+        toolActivity.clear();
+        // A short "Continue"/"Resume" after an unfinished run is the same work. Keep the
+        // previous plan visible and seed it into the new graph run until the agent updates it.
+        if (retainedTodos.length)
+            terminal?.setTodos(retainedTodos);
+        else
+            terminal?.setTodos([]);
+        terminal?.setStatus({ activity: 'Thinking' });
+        // Interactive runs keep the composer live so the user can steer the run in place;
+        // approved/clarification questions still take precedence over steering.
+        terminal?.setSteering(true);
+        const selected = config.providers.find(p => p.id === config.provider);
+        const preflight = async (operation) => {
+            while (true) {
+                if (active.signal.aborted)
+                    return operation(active.signal);
+                await runControl?.wait(active.signal);
+                const interruption = runControl?.signal;
+                const signal = interruption ? AbortSignal.any([active.signal, interruption]) : active.signal;
+                try {
+                    return await operation(signal);
+                }
+                catch (error) {
+                    if (!interruption?.aborted || active.signal.aborted)
+                        throw error;
+                }
+            }
+        };
+        let mcp;
+        try {
+            // The startup preflight already loaded this selection through the membership gate, so the
+            // initial run reuses it rather than spending a second account-service round trip whose
+            // transient failure could still deny the run. Later runs load again so on-disk graph
+            // edits stay observable mid-session; a graph refresh arms one more reuse.
+            const loadedGraph = startupGraph && !startupGraphReused && startupGraphSelection === (state.graph ?? 'default')
+                ? (startupGraphReused = true, startupGraph)
+                : await preflight(signal => loadGraph(state.graph ?? 'default', signal));
+            terminal?.setStatus({ activity: 'Checking graph models' });
+            graphModelsHealthy = false;
+            const health = await preflight(signal => checkGraphHealth(loadedGraph, config, signal, {
+                onUsage: (delta, reference) => {
+                    const key = `${reference.provider}\0${reference.model}`;
+                    const entry = probeModels.get(key) ?? { provider: reference.provider, model: reference.model, usage: {} };
+                    // Only the measurements the provider actually reported are carried, so the tuple keeps
+                    // its coverage instead of claiming a measured zero.
+                    for (const field of ['requests', 'inputTokens', 'outputTokens', 'cacheRead', 'cacheWrite']) {
+                        const value = delta[field];
+                        if (typeof value === 'number')
+                            entry.usage[field] = (entry.usage[field] ?? 0) + value;
+                    }
+                    probeModels.set(key, entry);
+                },
+                // The probes are model calls this attempt pays for, so they belong in the trajectory
+                // beside the run's own calls.
+                createAdapter: provider => tracedAdapter(provider),
+            }));
+            graphModelsHealthy = health.healthy;
+            if (!health.healthy) {
+                healthProviderFailed = health.failures.some(failure => failure.providerError === true);
+                throw new Error(formatGraphHealthFailure(health));
+            }
+            const graph = validateGraph(loadedGraph, { providers: config.providers, defaultProvider: config.provider, spawnAvailable: true });
+            // The pinned graph is known now, so the start carries its real size and delegation shape.
+            Object.assign(telemetryHandle.dimensions, { graphId: runGraphSelection, ...graphShape(graph) });
+            const startQueued = startTelemetry();
+            if (!openRecordWritten)
+                void startQueued;
+            // Stamp the same shape into the open record, because a crash before finalization is
+            // recovered from that file: zeros there would produce a finish that disagrees with its start.
+            // `startSent` is stamped only once the start is actually queued, so a crash in between is
+            // recovered as a pair rather than as a finish with no start.
+            if (openRecordWritten) {
+                await startQueued.catch(() => { });
+                openRecord.telemetry = { ...openRecord.telemetry, ...graphShape(graph), startSent: telemetryHandle.started !== false };
+                await writeOpenRunRecord(directory, openRecord).catch(() => { });
+            }
+            // The in-flight record is created before graph preflight. Once the pinned
+            // revision is known, stamp its small sidecar so live runs can safely show
+            // revision-matched node and edge overlays before finalization.
+            await writeStudioRunSummary(directory, {
+                id: runId, status: 'running', startedAt, graphSelection: runGraphSelection,
+                ...(accountSubject ? { accountSubject } : {}),
+                graph: { id: graph.id, revision: graph.revision }
+            }).catch(() => { });
+            terminal?.setStatus({ activity: 'Thinking' });
+            const workspaceGuidance = await preflight(signal => loadWorkspaceInstructions(workspace, signal, config.systemPromptOverride));
+            // QA workflow guidance rides the same channel as the workspace guide; it is
+            // guidance only — permission gates and the command policy still enforce.
+            const invocation = isBuiltinSlashCommand(task) ? undefined : await preflight(signal => resolveSkillInvocation(task, config, signal, directory));
+            const snapshot = await preflight(signal => extensionSnapshot(config, signal, directory, invocation?.id));
+            for (const notice of snapshot.notices)
+                terminal ? terminal.print(notice) : process.stderr.write(safeTerminal(notice) + '\n');
+            const instructions = `${workspaceGuidance}\n${QA_SYSTEM_GUIDANCE}${snapshot.instructions}`;
+            const resolvedModels = new Map();
+            const onRunEvent = async (event) => {
+                if (!/reasoning|thinking\.delta/.test(event.type))
+                    browserBridge?.event(trajectory.sanitize(event));
+                event = { ...event, data: { ...event.data, conversationId: savedSession?.id ?? trajectory.sessionId } };
+                if (event.data.provider === 'andorra' && ['decision.completed', 'decision.fallback', 'decision.provider_error'].includes(event.type))
+                    scheduleAccountRefresh();
+                if (event.type === 'codeintel.state')
+                    codeIntelNotice(event);
+                await appendRunEvent(directory, event);
+                await trajectory.recordEvent(event);
+                terminal?.setStatus({ session: savedSession?.name ?? trajectory.sessionId });
+                // The executor's own resolution of this node's model is memoized here, so the footer can
+                // follow the node instead of the session's selection.
+                terminal?.handleRuntimeEvent(await withNodeModelResolution(event, (provider, model) => resolvedModels.get(JSON.stringify([provider, model]))));
+                // Tool boundaries are when the panel's live sections can have moved: a completion may
+                // have written files or ended a background terminal, a start may have opened one. These
+                // stay on the summary's own throttle - a tool-heavy run would otherwise spawn a git
+                // process per tool - while the run boundaries above force the read.
+                if (event.type === 'node.tool.started' || event.type === 'node.tool.completed' || event.type === 'node.tool.failed')
+                    refreshPanelStatus();
+                if (terminal && event.type === 'graph.todos.updated') {
+                    terminal.setTodos(event.data.todos);
+                    return;
+                }
+                const activity = activityForRuntimeEvent(event, toolActivity);
+                if (activity !== undefined)
+                    terminal?.setStatus({ activity: runControl?.isPaused ? 'Paused' : activity });
+                if (terminal && event.type === 'agent.model.completed') {
+                    terminal.setStatus(sessionUsage());
+                }
+                if (!values.json) {
+                    const entry = formatEvent(event);
+                    if (entry) {
+                        if (terminal)
+                            terminal.print(entry.text, entry.detail, entry.toolCall, false, /failed|error|stopped/.test(event.type));
+                        // The plain path has no Ctrl+O, so an agent message whose code block collapsed into
+                        // `detail` must print the full rendering, not the truncated summary.
+                        else if (event.type === 'agent.message' && entry.detail)
+                            print(staticToolTimestamp(entry.detail, entry.toolCall));
+                        else
+                            print(staticToolTimestamp(entry.text, entry.toolCall));
+                    }
+                }
+            };
+            runEventSink = onRunEvent;
+            mcp = Object.keys(snapshot.servers).length ? await preflight(async (signal) => {
+                const extensionContext = { workspace, signal, runControl, get yolo() { return state.yolo; }, get permissions() { return state.permissions; },
+                    onApprovalEvent: (type, data) => onRunEvent({ type, time: new Date().toISOString(), data: { ...data, runId } }),
+                    approvalMode: terminal ? 'interactive' : 'headless', approve: async (name, args, signal) => {
+                        if (!terminal || exiting)
+                            return false;
+                        awaitingInput++;
+                        updateTitle();
+                        terminal.setStatus({ activity: `Approval needed: ${name}` });
+                        await writeActivity(directory, 'awaiting-input', { kind: 'approval', detail: `Approval needed: ${name}`, runId });
+                        terminal.print(`Approval details for ${describeTool(name, args)}`, JSON.stringify(args, null, 2));
+                        const answerPromise = terminal.chooseQuestion(safeTerminal(`Approve ${describeTool(name, args)}?`), [{ id: 'deny', label: 'Deny' }, { id: 'approve', label: 'Approve' }], { signal, kind: 'approval', approvalDetails: { name, arguments: args } });
+                        const grant = () => terminal.resolveQuestion('policy-changed');
+                        approvePending = grant;
+                        try {
+                            const answer = await answerPromise;
+                            return answer === 'policy-changed' ? answer : answer === 'approve';
+                        }
+                        finally {
+                            awaitingInput--;
+                            updateTitle();
+                            if (approvePending === grant)
+                                approvePending = undefined;
+                            terminal.setStatus({ activity: runControl?.isPaused ? 'Paused' : 'Thinking' });
+                            await runResumed();
+                        }
+                    } };
+                return (await import('./mcp.js')).connectMcpServers(snapshot.servers, extensionContext, message => terminal ? terminal.print(message) : process.stderr.write(safeTerminal(message) + '\n'), active.signal);
+            }) : { tools: [], close: async () => { } };
+            if (terminal) {
+                try {
+                    const refreshed = await preflight(signal => refreshModelContext(selected, signal));
+                    resolvedModels.set(JSON.stringify([selected.id, selected.model]), Promise.resolve({ model: refreshed.model, adapter: tracedAdapter(refreshed), contextWindow: refreshed.contextWindow, reasoningEffort: refreshed.reasoningEffort, providerType: selected.type, baseUrl: selected.baseUrl }));
+                    if (refreshed.contextWindow !== undefined)
+                        sessionContexts.set(contextKey(selected), refreshed.contextWindow);
+                    else
+                        sessionContexts.delete(contextKey(selected));
+                }
+                catch (error) {
+                    if (!active.signal.aborted)
+                        throw error;
+                }
+                refreshStatus();
+            }
+            // A cancelled metadata lookup must not create a graph run after preflight.
+            active.signal.throwIfAborted();
+            let membership = !jevOn() ? { paid: false } : await preflight(signal => getMembership(signal));
+            if (jevOn() && !membership.subject && membership.unavailable) {
+                // The lookup has a five-second budget and the account service cold-starts past it after a
+                // quiet spell; the second lookup then answers in well under a second. Without the retry
+                // Jev is off for the whole run and nothing says so (7 of 12 Jev runs in the 2026-11-01
+                // A/B ran without a single decision round).
+                membership = await preflight(signal => getMembership(signal));
+            }
+            if (jevOn() && !membership.subject) {
+                const reason = membership.unavailable ? membership.failureReason ?? 'membership_unavailable' : 'not_signed_in';
+                await onRunEvent({ type: 'decision.unavailable', time: new Date().toISOString(), data: { runId, provider: 'andorra', reason } });
+                const notice = `Jev is off for this run: ${reason === 'not_signed_in' ? 'no signed-in account' : `the account lookup was unavailable (${reason})`}.`;
+                if (terminal)
+                    terminal.print(notice);
+                else
+                    process.stderr.write(safeTerminal(notice) + '\n');
+            }
+            const decisionPolicy = hostedDecisionPolicy(membership, jevOn(), config.decisions);
+            jevEnabled = jevOn();
+            terminal?.setStatus({ graph, jevEnabled });
+            const commandMemory = config.commandMemory === false ? undefined : await LocalToolMemory.open({ workspace, directory });
+            const execute = (options) => runGraph(graph, { ...options, runInput, runState, commandMemory, todoStore,
+                ...(invocation ? { inheritedSkills: [invocation.id], skillInvocationInstruction: invocation.task } : {}),
+                resolveModel: (id, model) => {
+                    const provider = config.providers.find(item => item.id === id);
+                    if (!provider)
+                        throw new Error(`Unknown provider: ${id}. Use /providers to add or edit providers.`);
+                    const key = JSON.stringify([id, model || provider.model]);
+                    let pending = resolvedModels.get(key);
+                    if (!pending) {
+                        pending = preflight(signal => resolveModelContext(provider, model || provider.model, signal))
+                            .then(snapshot => withEvaluationReasoningEffort(snapshot, process.env.ANDORRA_EVAL_REASONING_EFFORT))
+                            .then(snapshot => ({ model: snapshot.model, adapter: tracedAdapter(snapshot), contextWindow: snapshot.contextWindow, reasoningEffort: snapshot.reasoningEffort, providerType: provider.type, baseUrl: provider.baseUrl }));
+                        resolvedModels.set(key, pending);
+                        void pending.catch(() => { if (resolvedModels.get(key) === pending)
+                            resolvedModels.delete(key); });
+                    }
+                    return pending;
+                },
+                resolveProvider: id => {
+                    const provider = config.providers.find(item => item.id === id);
+                    if (!provider)
+                        throw new Error(`Unknown provider: ${id}. Use /providers to add or edit providers.`);
+                    const snapshot = withEvaluationReasoningEffort(runtimeProvider(provider), process.env.ANDORRA_EVAL_REASONING_EFFORT);
+                    return { model: snapshot.model, adapter: tracedAdapter(snapshot), contextWindow: snapshot.contextWindow, providerType: snapshot.type, baseUrl: snapshot.baseUrl };
+                },
+            });
+            const result = await execute({ task, runId, provider: selected.id, model: selected.model, ...(attachments ? { attachments } : {}),
+                ...(config.efficiency ? { efficiency: config.efficiency } : {}),
+                // A `--model`/`--provider` flag is the user's choice; adaptive routing leaves it alone.
+                modelPinned: Boolean(values.model || values.provider),
+                configuredModels: config.providers.map(item => ({ id: item.id, model: item.model, ...(item.models ? { models: [...item.models] } : {}) })),
+                onNodeCheckpoint: persistCheckpoint,
+                onUsage: (usage, origin) => {
+                    activeUsage.requests += usage.requests;
+                    activeUsage.inputTokens += usage.inputTokens;
+                    activeUsage.outputTokens += usage.outputTokens;
+                    activeUsage.cacheRead += usage.cacheRead ?? 0;
+                    activeUsage.cacheWrite += usage.cacheWrite ?? 0;
+                    // The delta's input size is the live conversation: every request resends the
+                    // whole context, so the latest measured one shows how full the window currently
+                    // is. Deltas that carry no measurement - transport attempts, a completion whose
+                    // provider omitted usage, a failed request's close signal - report zeros by
+                    // design, and treating them as a context size would wipe the last real estimate
+                    // (model-backed distillation runs last, so its no-usage close would otherwise
+                    // leave the idle footer at `context: 0%`).
+                    if (usage.inputTokens > 0) {
+                        contextUsedTokens = usage.inputTokens;
+                        runContext = { usedTokens: usage.inputTokens, ...(usage.cacheRead === undefined ? {} : { cacheRead: usage.cacheRead }) };
+                    }
+                    // The same per-request delta feeds the footer speed readout. Providers report a
+                    // request's tokens only as it completes, so this is the number credited to the
+                    // window that produced it - the streamed decode window when the adapter measured
+                    // one, so prompt processing does not count as generating time; the origin's
+                    // invocation id names that request, so a completion pairs with its own window even
+                    // when concurrent requests finish out of order. Diffing the cumulative totals
+                    // instead would smear or drop it in a graph whose nodes each report their own totals.
+                    terminal?.noteGeneratedTokens(usage.outputTokens, origin?.invocationId, origin?.final === true, usage.decodeMs);
+                    terminal?.setStatus(sessionUsage());
+                },
+                adapter: tracedAdapter(runtimeProvider(selected)), tools: [...createTools(), ...snapshot.tools, ...mcp.tools], history: state.history, instructions, codeIntel, ...decisionPolicy,
+                // Installation-wide bounds. Nothing is set by default, which leaves the run with no
+                // wall clock and no iteration ceiling; a graph or node bound still narrows these.
+                limits: resolveConfiguredLimits(config),
+                // Polled at turn boundaries: each queued steer becomes a user message in the live
+                // conversation, so the run redirects without restarting or losing its context.
+                getSteeringMessages: terminal ? async () => {
+                    if (exiting)
+                        return [];
+                    deliverTimerPrompts();
+                    // Release held timer prompts only after the poll that carried a timer's resume
+                    // direction: this poll runs immediately before prepareTurn injects those directions,
+                    // so prompts released from the next poll onward reach the model strictly later.
+                    timerResumePending = false;
+                    // A steered turn carries its own attachments: each queued steer is one user message,
+                    // so its files and images are resolved against that steer alone, never pooled.
+                    const steered = terminal.takeSteeringTurns();
+                    const messages = [];
+                    for (const turn of steered) {
+                        if (!turn.attachments.length) {
+                            messages.push({ role: 'user', content: turn.text });
+                            continue;
+                        }
+                        try {
+                            const resolved = await resolveAttachments(directory, workspace, turn.attachments);
+                            for (const root of await attachmentReadRoots(directory, resolved.refs)) {
+                                attachmentSpools.add(root);
+                                steeredSpools.add(root);
+                            }
+                            // An attachment-only steer arrives with empty text; the stand-in names what the
+                            // chips carry, exactly as an attachment-only task does (ATTACHMENT_ONLY_TASK).
+                            messages.push({ role: 'user', content: `${turn.text || ATTACHMENT_ONLY_TASK}\n\n${attachmentReferenceBlock(resolved.refs)}`, ...(resolved.images.length ? { images: resolved.images } : {}) });
+                        }
+                        catch (error) {
+                            messages.push({ role: 'user', content: `${turn.text}\n\n[Attachment failed: ${error instanceof Error ? error.message : String(error)}]` });
+                        }
+                    }
+                    messages.push(...browserSteering.splice(0).map(text => ({ role: 'user', content: text })), ...timerSteering.splice(0).map(text => ({ role: 'user', content: text })));
+                    return messages;
+                } : undefined,
+                context: { workspace, signal: active.signal, runControl, timers: terminal ? sessionTimers : undefined,
+                    // Both terminal surfaces create future work through this context. Carry the run's
+                    // selections, including CLI overrides; the graph selector must retain 'default'
+                    // rather than the resolved harness id so replay follows the same access rules.
+                    automationDirectory: directory,
+                    wakeCarry: { provider: selected.id, model: selected.model, graph: runGraphSelection,
+                        ...(selected.reasoningEffort === undefined ? {} : { reasoningEffort: selected.reasoningEffort }) },
+                    get yolo() { return state.yolo; }, get permissions() { return state.permissions; }, get attachmentRoots() { return [...attachmentSpools]; }, approvalMode: terminal ? 'interactive' : 'headless',
+                    askUser: terminal ? async (question, signal, choices) => {
+                        if (exiting)
+                            return undefined;
+                        awaitingInput++;
+                        updateTitle();
+                        terminal.setStatus({ activity: 'Clarifying requirements' });
+                        await writeActivity(directory, 'awaiting-input', { kind: 'clarification', detail: safeTerminal(question), runId });
+                        try {
+                            return await askClarification(terminal, safeTerminal(question), signal, choices);
+                        }
+                        finally {
+                            awaitingInput--;
+                            updateTitle();
+                            terminal.setStatus({ activity: runControl?.isPaused ? 'Paused' : 'Planning' });
+                            await runResumed();
+                        }
+                    } : undefined,
+                    approve: async (name, args, signal) => {
+                        if (!terminal || exiting)
+                            return false;
+                        awaitingInput++;
+                        updateTitle();
+                        terminal.setStatus({ activity: `Approval needed: ${name}` });
+                        terminal.print(`Approval details for ${describeTool(name, args)}`, JSON.stringify(args, null, 2));
+                        await writeActivity(directory, 'awaiting-input', { kind: 'approval', detail: `Approval needed: ${name}`, runId });
+                        const answerPromise = terminal.chooseQuestion(safeTerminal(`Approve ${describeTool(name, args)}? (Ctrl+O: details)`), [
+                            { id: 'deny', label: 'Deny' }, { id: 'approve', label: 'Approve' },
+                        ], { signal, kind: 'approval', approvalDetails: { name, arguments: args } });
+                        const grant = () => terminal.resolveQuestion('policy-changed');
+                        approvePending = grant;
+                        try {
+                            const answer = await answerPromise;
+                            return answer === 'policy-changed' ? answer : answer === 'approve';
+                        }
+                        finally {
+                            awaitingInput--;
+                            updateTitle();
+                            if (approvePending === grant)
+                                approvePending = undefined;
+                            terminal.setStatus({ activity: runControl?.isPaused ? 'Paused' : `Running ${name}` });
+                            await runResumed();
+                        }
+                    },
+                },
+                onEvent: onRunEvent, });
+            state.lastRun = result;
+            state.usage.requests += result.usage.requests;
+            state.usage.inputTokens += result.usage.inputTokens;
+            state.usage.outputTokens += result.usage.outputTokens;
+            foldCache(state.usage, result.usage.cacheRead, result.usage.cacheWrite);
+            activeUsage = { inputTokens: 0, outputTokens: 0, requests: 0, cacheRead: 0, cacheWrite: 0 };
+            // Let the last checkpoint land before the record and the cleanup below decide whether one
+            // survives: deleting while a write was in flight would recreate the file a succeeded run is
+            // meant to leave behind nothing to resume.
+            await checkpointWrites;
+            // The final record keeps the open record's identity fields: recovery and the Runs view key a
+            // run by its session and start time, and the finalizer replaces the open record in place.
+            const finishedRecord = { ...result, graphSelection: runGraphSelection,
+                ...(accountSubject ? { accountSubject } : {}),
+                ...(savedSession ? { sessionId: savedSession.id } : {}), startedAt,
+                // The stamp the mutation guard needs to tell a closed attempt from a live claim of the same run id.
+                endedAt: new Date().toISOString(),
+                // The flag a resume consults before it trusts this attempt's conversation: a checkpoint
+                // that could not be written leaves the node to be re-entered from its opening task.
+                ...(checkpointFailed ? { checkpointIntegrity: 'failed' } : {}),
+                ...(runInput === undefined ? {} : { runInput }), ...(runState === undefined ? {} : { runState }) };
+            await writeFile(runRecordPath(directory, result.id, 'json'), JSON.stringify(finishedRecord, null, 2) + '\n', { mode: 0o600 });
+            finishTelemetry(result.status, result.reason, result);
+            await writeStudioRunSummary(directory, {
+                id: result.id, status: result.status, startedAt, graphSelection: runGraphSelection,
+                ...(accountSubject ? { accountSubject } : {}),
+                graph: { id: result.graph.id, revision: typeof result.graph.revision === 'number' ? result.graph.revision : undefined },
+                toolCalls: result.toolCalls
+            }).catch(() => { });
+            // A multi-node graph can finish an early node and stop in a later one, keeping that node's
+            // completion on a non-success result; the status is the attempt's last word, so stamp it.
+            rememberTurn(task, { ...(result.completion ?? outcomeCompletion(result.status, result.reason, result.limits)), ...(result.status === 'succeeded' ? {} : { status: result.status }) }, runId, attachments?.refs);
+            // The run's final widget values are the session's newest; a result without widgets clears
+            // older ones so a persisted record never shows values its graph no longer defines.
+            // The context reading is the run's too: what it last measured, or nothing.
+            if (savedSession)
+                savedSession = { ...savedSession, widgets: result.widgets, context: runContext };
+            // A finished run has nothing to resume: only stopped attempts keep a durable checkpoint.
+            if (result.status === 'succeeded') {
+                await removeRunCheckpoint(directory, result.id);
+                // Nothing resumes a finished run, and only the opening turn's refs are persisted — a
+                // steer's spools have no reader left once its checkpoint is gone. Until then (stopped,
+                // failed) they stay: the checkpoint's conversation still names those files.
+                await Promise.all([...steeredSpools].map(root => rm(root, { recursive: true, force: true }).catch(() => { })));
+            }
+            if (values.json)
+                process.stdout.write(JSON.stringify(result) + '\n');
+            else {
+                const summary = result.completion?.summary ?? (result.status === 'cancelled' ? 'Cancelled.' : `The run did not finish: ${stopReasonPhrase(result.reason, result.limits)}.`);
+                if (terminal) {
+                    // The summary is markdown like every agent message: render it, and keep a collapsed
+                    // code block's full text behind Ctrl+O instead of printing fences verbatim.
+                    const entry = formatRunResult({ id: result.id, status: result.status, summary, tests: result.completion?.tests });
+                    terminal.print(entry.text, entry.detail, undefined, true);
+                }
+                else
+                    print(summary);
+                if (!terminal)
+                    for (const check of result.completion?.tests ?? [])
+                        print(`  ${check}`);
+                if (!terminal)
+                    print(`Run ${result.id} · ${result.status}`);
+            }
+            return terminated ? 143 : result.status === 'succeeded' ? 0 : result.status === 'cancelled' ? 130 : 1;
+        }
+        catch (error) {
+            // An attempt that never reached `runGraph` still owns its open record: leaving it `running`
+            // tells the Runs view a task is working until the process dies, and recovery then calls a
+            // deliberate stop a crash. Replace it with the outcome this path actually knows — the shared
+            // finalizer carries the identity fields and whatever usage the run had already spent.
+            if (active?.signal.aborted) {
+                await finalizeRunRecord('cancelled', 'the user stopped this run');
+                rememberTurn(task, outcomeCompletion('cancelled', undefined, undefined), runId, attachments?.refs);
+                return terminated ? 143 : 130;
+            }
+            // A crash is an attempt too. Record it before rethrowing so the caller's error report
+            // does not also cost the user the context of what they asked for.
+            await finalizeRunRecord('infrastructure_error', error instanceof Error ? error.message : 'the run failed unexpectedly');
+            rememberTurn(task, outcomeCompletion('infrastructure_error', error instanceof Error ? error.message : 'the run failed unexpectedly', undefined), runId, attachments?.refs);
+            throw error;
+        }
+        finally {
+            browserDraining = true;
+            // Stop accepting live commands before draining; idle commands must not race
+            // a permission save accepted just before the run completed.
+            terminal?.setRunInputHandler(undefined);
+            // A cancelled or crashed attempt leaves its checkpoint in place for `run.resume`, but the
+            // pending write itself has to finish before the process moves on; the chain never rejects.
+            await checkpointWrites;
+            await liveCommands;
+            // A crashed run's partial provider spend still happened: fold it into the session
+            await mcp?.close();
+            // totals before the live counter resets, or a crashed command's usage vanishes from
+            // /usage and the --debug summary even though the journal recorded the model calls.
+            state.usage.requests += activeUsage.requests;
+            state.usage.inputTokens += activeUsage.inputTokens;
+            state.usage.outputTokens += activeUsage.outputTokens;
+            foldCache(state.usage, activeUsage.cacheRead, activeUsage.cacheWrite);
+            activeUsage = { inputTokens: 0, outputTokens: 0, requests: 0, cacheRead: 0, cacheWrite: 0 };
+            terminal?.finishTask();
+            runEventSink = undefined;
+            // The run is over: detach its live state before the awaited cleanup below, so a
+            // Ctrl+C landing during slow cleanup I/O reads as idle and exits instead of pausing
+            // a run that no longer exists (and the pause listener cannot re-attach to claim
+            // input is needed when nothing is listening anymore).
+            removeControlListener?.();
+            runControl = undefined;
+            approvePending = undefined;
+            browserPrompt = undefined;
+            browserSteering.length = 0;
+            awaitingInput = 0;
+            updateTitle(false);
+            await settleRunRecord();
+            // Deliver what this run queued before the process leaves; a no-op while no endpoint exists.
+            await telemetrySettled;
+            await sessionStarted;
+            await drainTelemetry(telemetrySurface);
+            active?.abort();
+            active = undefined;
+            try {
+                await browserBridge?.persist();
+            }
+            catch (error) {
+                print(`Could not save browser activity: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            await writeActivity(directory, 'idle');
+            refreshStatus();
+            // Release the composer back to the normal question flow before the next prompt. A steer
+            // submitted after the executor's final poll has nowhere to go; say so rather than
+            // dropping text the user watched being accepted.
+            for (const undelivered of terminal?.setSteering(false) ?? []) {
+                // An attachment-only steer returns empty text: its chips went back to the queue, where
+                // they are visible, so a blank "Not delivered" line would report nothing at all.
+                if (undelivered)
+                    terminal?.print(`Not delivered — the run had already finished: ${undelivered}`);
+            }
+            // A timer prompt that queued as steering after the executor's final poll still owes its
+            // delivery: it goes back to `timerPending` so the next composer hand-off runs it as a
+            // fresh task rather than dropping a wake-up the agent asked for.
+            for (const queued of timerSteering.splice(0))
+                timerPending.push(queued);
+            if (terminal)
+                terminal.setStatus({ activity: graphModelsHealthy ? 'Ready' : 'Graph models unavailable', branch: await gitBranch(workspace) });
+            refreshPanelStatus(true);
+            scheduleAccountRefresh();
+            browserDraining = false;
+            browserCancelPending = false;
+        }
+    };
+    try {
+        if (values.prompt !== undefined) {
+            if (!values.json)
+                print(sessionDescription());
+            // Machine consumers keep stdout pure JSON, so the debug log location goes to stderr.
+            else if (values.debug)
+                process.stderr.write(safeTerminal(sessionDescription()) + '\n');
+            const commandStartedAt = Date.now();
+            await debugRecord('command.started', { input: values.prompt, mode: 'headless' });
+            try {
+                return await run(values.prompt);
+            }
+            catch (error) {
+                await debugRecord('command.error', { input: values.prompt, mode: 'headless', message: error instanceof Error ? error.message : String(error) });
+                throw error;
+            }
+            finally {
+                await debugRecord('command.completed', { input: values.prompt, mode: 'headless', durationMs: Date.now() - commandStartedAt });
+            }
+        }
+        terminal.start();
+        browserBridge = await createBrowserBridge(directory, () => {
+            const snapshot = {
+                ...(savedSession ?? { version: 1, id: trajectory.sessionId, name: 'New CLI session', workspace, updatedAt: new Date(sessionStartedAt).toISOString(), history: [], usage: { ...state.usage } }),
+                projectId: projectIdentity(workspace), contextHistory: structuredClone(state.history ?? []), history: sessionArchive, status: browserDraining || (browserPrompt && browserCancelPending) ? 'cancelling' : browserPrompt || (runControl && active) ? active?.signal.aborted ? 'cancelling' : 'running' : 'idle', prompt: browserPrompt, events: [], pending: runControl && active && !active.signal.aborted ? terminal.browserQuestion() : undefined, permissions: state.permissions, provider: config.provider, model: config.providers.find(item => item.id === config.provider)?.model, graph: state.graph,
+            };
+            // The authenticated bridge also persists this snapshot. Preserve canonical
+            // routing/storage metadata; the server separately redacts public paths.
+            return { ...trajectory.sanitize(snapshot), id: snapshot.id, parentId: snapshot.parentId, workspace: snapshot.workspace, updatedAt: snapshot.updatedAt, status: snapshot.status };
+        }, {
+            prompt: async (text) => {
+                if (browserDraining)
+                    throw new Error('The previous task is still finishing its save; try again in a moment.');
+                if (browserRollbackFailed)
+                    throw new Error(rollbackFailureMessage);
+                text = text.trim();
+                if (text.startsWith('/') && (isBuiltinSlashCommand(text) || !await resolveSkillInvocation(text, config, undefined, directory)))
+                    throw new Error('Run built-in slash commands in the terminal, or invoke an enabled skill as /skillname.');
+                if (!config.providers.length)
+                    throw new Error('Add a provider in /providers before starting a task.');
+                if (!terminal.acceptConversationPrompt(text))
+                    throw new Error('Terminal is displaying a command screen; return to its prompt first.');
+                const previousSession = savedSession;
+                browserPrompt = text;
+                if (!savedSession)
+                    savedSession = { version: 1, id: trajectory.sessionId, name: sessionName(text), workspace, updatedAt: new Date().toISOString(), history: [], usage: { ...state.usage } };
+                // A fresh acceptance timestamp keeps the acknowledged interrupted task
+                // inside the history age window even if the CLI exits before the run's
+                // own persistence. Rejection restores the untouched previous record.
+                else
+                    savedSession = { ...savedSession, updatedAt: new Date().toISOString() };
+                // Register fresh sessions as well as their recoverable browser prompt.
+                // The terminal run waits for these writes before updating either record.
+                const record = { projectId: projectIdentity(workspace), ...savedSession, history: sessionArchive, contextHistory: state.history ?? [] };
+                browserAcceptance = browserBridge.persist(() => sessions.save(record)).catch(async (error) => {
+                    // The archive may commit before the primary fails. Clear the rejected
+                    // prompt through the same queue before allowing another terminal task.
+                    // Steering queued during the pending start must not leak into the
+                    // next task either.
+                    active = undefined;
+                    browserPrompt = undefined;
+                    browserSteering.length = 0;
+                    browserCancelPending = false;
+                    savedSession = previousSession;
+                    try {
+                        if (previousSession)
+                            await browserBridge.persist(() => sessions.save(previousSession));
+                        else {
+                            // There was no durable session before this rejected first prompt.
+                            // Do not create an empty archive that would reappear after restart,
+                            // or retry the same unavailable archive write during rollback.
+                            const cleanup = await Promise.allSettled([
+                                rm(join(directory, 'browser-history', `${record.id}.json`), { force: true }),
+                                rm(join(directory, 'sessions', `${record.id}.json`), { force: true }),
+                            ]);
+                            const failures = cleanup.filter(result => result.status === 'rejected');
+                            if (failures.length)
+                                throw new AggregateError(failures.map(result => result.reason), 'Fresh session cleanup failed');
+                        }
+                    }
+                    catch (rollbackError) {
+                        // An archive-first acceptance can leave a rejected prompt recoverable
+                        // against the old primary. Remove it even if rollback storage fails,
+                        // and fence both browser and terminal tasks until storage is repaired.
+                        browserRollbackFailed = true;
+                        const cleanup = await Promise.allSettled([
+                            rm(join(directory, 'browser-history', `${record.id}.json`), { force: true }),
+                            // Fresh sessions have no previous primary to preserve. Retry its
+                            // removal independently even if the archive cleanup still fails.
+                            ...(!previousSession ? [rm(join(directory, 'sessions', `${record.id}.json`), { force: true })] : []),
+                        ]);
+                        const failures = cleanup.filter(result => result.status === 'rejected');
+                        const remaining = `${cleanup[0].status === 'rejected' ? ' Its partial archive could not be removed.' : ''}${cleanup[1]?.status === 'rejected' ? ' Its partial primary session could not be removed.' : ''}`;
+                        throw new AggregateError([error, rollbackError, ...failures.map(result => result.reason)], `Prompt rejected; ${rollbackFailureMessage}${remaining}`);
+                    }
+                    throw error;
+                });
+                const accepted = browserAcceptance;
+                void accepted.catch(() => { });
+                return accepted;
+            },
+            steer: text => {
+                // Command screens also own `active`, but cannot consume graph steering.
+                // Reject here so their input cannot be queued into the next task. An
+                // acknowledged or starting prompt owns browserPrompt before runControl
+                // exists: queue its steering for the run's first poll instead of
+                // rejecting text the UI already advertises as steerable.
+                if (browserDraining || active?.signal.aborted || (!browserPrompt && (!runControl || !active)))
+                    throw new Error('No task is accepting steering; return to the terminal prompt first.');
+                if (runControl?.isPaused)
+                    runControl.resume(text);
+                else
+                    browserSteering.push(text);
+            },
+            cancel: () => {
+                // Command screens own `active` too. A task prompt identifies the
+                // accepted/preflight window before its graph RunControl is installed.
+                // While that acknowledged prompt is still starting, record the
+                // cancellation intent: run() honors it as soon as it owns a signal.
+                if (!active && browserPrompt) {
+                    browserCancelPending = true;
+                    return;
+                }
+                if ((!runControl && !browserPrompt) || !active || active.signal.aborted)
+                    throw new Error('No task is accepting cancellation; return to the terminal prompt first.');
+                active.abort(new Error('Cancelled from browser'));
+            },
+            answer: answer => {
+                // Configuration wizards also ask terminal questions, but only live
+                // graph questions and approvals belong to the browser runtime controls.
+                if (!runControl || !active || active.signal.aborted)
+                    throw new Error('No task is accepting answers; return to the terminal prompt first.');
+                terminal.resolveQuestion(answer);
+            },
+        });
+        terminal.setStatus({ session: trajectory.sessionId });
+        // Keep the startup transcript focused on the task. Full identifiers and journal paths
+        // remain available through /status, and --debug opts into their startup display.
+        if (values.debug)
+            print(sessionDescription());
+        void refreshAccountStatus();
+        try {
+            await refreshGraphStatus();
+        }
+        catch (error) {
+            if (!exiting)
+                print(`Graph check failed: ${error instanceof Error ? error.message : 'Unknown failure'}`);
+        }
+        accountPolling = setInterval(scheduleAccountRefresh, 60_000);
+        accountPolling.unref?.();
+        while (!exiting) {
+            let line;
+            try {
+                const asked = terminal.question('Describe a task, or type /help', { conversationPrompt: true });
+                // A timer may have come due while the previous task was still saving, or while a
+                // command screen or an approval owned the terminal; now the composer is armed again,
+                // so hand it every self-wake prompt that had to wait.
+                deliverTimerPrompts();
+                line = (await asked).trim();
+            }
+            catch {
+                break;
+            }
+            if (!line) {
+                // An empty submission is a real submission when attachments are queued — paste-then-Enter
+                // is the primary flow — and the substitute text names the intent the paste carried.
+                if (!(terminal?.hasQueuedAttachments() ?? false))
+                    continue;
+                line = ATTACHMENT_ONLY_TASK;
+            }
+            const commandStartedAt = Date.now();
+            await debugRecord('command.started', { input: line, mode: 'interactive' });
+            try {
+                if (line === '/browser') {
+                    browserApp ??= await startBrowserServer();
+                    // A pending startup can outlive teardown; close instead of opening.
+                    if (exiting)
+                        await browserApp.close().catch(() => { });
+                    else {
+                        print(`Andorra Browser: ${browserApp.url}`);
+                        openBrowserUrl(browserApp.url);
+                    }
+                    continue;
+                }
+                if (line === '/session') {
+                    await persistSession();
+                    const records = await sessions.list(workspace);
+                    if (!records.length) {
+                        print('No saved sessions in this workspace yet. Send a task to create one.');
+                        continue;
+                    }
+                    const selected = await terminal.select('Sessions - most recently touched first', records.map(record => ({ id: record.id, label: record.name, description: `${record.id.slice(-10)} - ${new Date(record.updatedAt).toLocaleString()}` })), { description: 'Enter resumes saved conversation context in this workspace. Esc returns. Current model and graph settings are retained.', selectedId: savedSession?.id });
+                    const record = records.find(item => item.id === selected);
+                    if (!record || record.id === savedSession?.id)
+                        continue;
+                    // The lineage and the fork points that go with it are what make the totals exact, so
+                    // they are kept whole: a chain that was cut short would lose the older ancestors. The
+                    // refusal runs before the current conversation's timers are cleared, because a switch
+                    // that cannot happen must not leave the conversation it was leaving without them.
+                    if (!canExtendLineage(record.ancestors)) {
+                        throw new Error('This session has been resumed too many times to keep its lineage, so it cannot be resumed again.');
+                    }
+                    // Armed timers and undelivered prompts belong to the conversation being replaced:
+                    // firing one into a different resumed conversation would wake that session with a
+                    // prompt nobody inside it asked for. Cancel them at the switch, visibly.
+                    const abandonedTimers = sessionTimers.list().length + timerPending.length + timerSteering.length;
+                    sessionTimers.clear();
+                    timerPending.length = 0;
+                    timerSteering.length = 0;
+                    // Fork the saved snapshot so concurrent terminals never overwrite one another.
+                    // Archive files the record the user picked, not the work: the resumed conversation is a
+                    // live task, so the fork starts unarchived even when its source is put away.
+                    const { archived: _archived, autoArchived: _autoArchived, ...resumedRecord } = record;
+                    // The fork copies the parent's history and the parent's totals. The totals it inherited
+                    // are recorded as they are now, so the work this fork does itself can be told from the
+                    // work it was given, even if the parent keeps working afterwards. The lineage is written
+                    // down as well, so a session deleted later in the chain does not leave this fork looking
+                    // like the root of its own work.
+                    savedSession = { ...resumedRecord, id: randomUUID(), parentId: record.id,
+                        ancestors: lineageThrough(record.ancestors, record.id), inheritedUsage: { ...record.usage },
+                        inheritedTurns: record.history.length, lineage: lineagePoints(record, record.usage, record.history.length) };
+                    // The conversation that is being replaced keeps the log it was written to, and this one
+                    // takes a log of its own, so neither session shows the other's records.
+                    await openSessionTrajectory(savedSession.id);
+                    await trajectory.record('session.resumed', { resumedSessionId: savedSession.id, sourceSessionId: record.id });
+                    sessionArchive = structuredClone(record.history);
+                    state.history = structuredClone(record.contextHistory ?? record.history).slice(-6);
+                    state.usage = { ...record.usage };
+                    terminal.resetDashboardSession(record.usage);
+                    delete state.lastRun;
+                    contextUsedTokens = compactedContextEstimate(state.history);
+                    sessionContexts.clear();
+                    terminal.clearConversation();
+                    terminal.setTodos([]);
+                    // A continued turn leads with the direction the user sent after the stop — the same line the
+                    // desktop's timeline shows — because that message, not the stopped attempt's original task,
+                    // is what this turn's work answers to; the stopped turn above it still carries the original.
+                    for (const turn of displayHistory(sessionArchive)) {
+                        terminal.printPrompt(turn.direction ?? turn.task);
+                        terminal.print(turn.completion.summary);
+                    }
+                    print(`Resumed ${record.name} (${record.id.slice(-10)}) in a new session. Saved task/outcome context restored; current model and graph settings retained.`);
+                    if (abandonedTimers)
+                        print(`${abandonedTimers} self-wake timer${abandonedTimers === 1 ? '' : 's'} from the previous conversation ${abandonedTimers === 1 ? 'was' : 'were'} cancelled at the session switch.`);
+                    terminal.setStatus({ session: record.name, contextUsed: contextUsedTokens });
+                    refreshStatus();
+                    updateTitle(false);
+                    await persistSession();
+                    continue;
+                }
+                if (/^\/attach(?:\s|$)/.test(line)) {
+                    // Composer-local, so it lives beside the loop rather than in the command table:
+                    // it queues an attachment for the next task instead of running to completion.
+                    const argument = line.slice('/attach'.length).trim().replace(/^"(.*)"$/, '$1');
+                    if (!argument) {
+                        print('Usage: /attach <path> — queue a file or folder with your next task. Large pastes and dropped files attach automatically.');
+                        continue;
+                    }
+                    const target = resolve(workspace, argument);
+                    if (!existsSync(target)) {
+                        print(`No such file or folder: ${target}`);
+                        continue;
+                    }
+                    if (terminal.addAttachment({ kind: 'file', path: target }))
+                        print(`Attached ${target}. It rides your next task.`);
+                    continue;
+                }
+                if (isScreenCommand(line)) {
+                    active = new AbortController();
+                    try {
+                        const result = await runCommandScreen(line, state, terminal, persistConfig, active.signal, undefined, undefined, (signal, mode) => graphEditor.open(signal, mode));
+                        if (result.clear) {
+                            state.history = [];
+                            contextUsedTokens = 0;
+                            sessionContexts.clear();
+                            terminal?.setTodos([]);
+                            browserBridge?.startRun();
+                            trajectory.addSecrets(providerSecrets(config.providers));
+                        }
+                        if (/^\/graph(?:\s|$)/.test(line) || result.clear && /^\/(providers|model)(?:\s|$)/.test(line))
+                            await refreshGraphStatus();
+                        trajectory.addSecrets(providerSecrets(config.providers));
+                        refreshStatus();
+                    }
+                    finally {
+                        active = undefined;
+                    }
+                    continue;
+                }
+                if (terminal)
+                    terminal.printPrompt(line);
+                else
+                    print(`You > ${line}`);
+                const skillInvocation = line.startsWith('/') && !isBuiltinSlashCommand(line)
+                    ? await resolveSkillInvocation(line, config, undefined, directory) : undefined;
+                if (line.startsWith('/') && !skillInvocation) {
+                    let command;
+                    if (/^\/codegraph\s+rebuild\s*$|^\/(login|logout|auth)(?:\s|$)/.test(line.trim())) {
+                        active = new AbortController();
+                        terminal?.setStatus({ activity: line.startsWith('/codegraph') ? 'Rebuilding CodeGraph' : 'Account authentication' });
+                        try {
+                            command = await executeCommand(line, state, persistConfig, active.signal);
+                        }
+                        finally {
+                            active = undefined;
+                            terminal?.setStatus({ activity: 'Ready' });
+                            if (/^\/(login|logout|auth)(?:\s|$)/.test(line.trim()))
+                                void refreshAccountStatus();
+                        }
+                    }
+                    else
+                        command = await executeCommand(line, state, persistConfig);
+                    afterJevCommand(line, command);
+                    trajectory.addSecrets(providerSecrets(config.providers));
+                    if (/^\/graph(?:\s|$)|^\/(?:auth\s+)?logout\s*$/.test(line) || command.clear && /^\/(providers|model)(?:\s|$)/.test(line))
+                        await refreshGraphStatus();
+                    refreshStatus();
+                    // `/clear` drops the chat entries before its own notice is printed, so the notice lands on
+                    // the wiped screen and survives it. The headless paths have no terminal (and no screen
+                    // entries), so they keep their plain stdout stream.
+                    if (command.resetScreen)
+                        terminal?.clearConversation();
+                    if (command.text)
+                        print(command.text);
+                    if (line === '/status')
+                        print(sessionDescription());
+                    if (command.clear) {
+                        state.history = [];
+                        contextUsedTokens = 0;
+                        terminal?.setTodos([]);
+                        browserBridge?.startRun();
+                        terminal?.setStatus({ contextUsed: 0 });
+                    }
+                    if (command.compact && state.history?.length) {
+                        state.history = compactHistory(state.history);
+                        // Until the next request reports the real input size, show the compacted
+                        // seed's estimated footprint so the utilization meter drops immediately.
+                        contextUsedTokens = compactedContextEstimate(state.history);
+                        terminal?.setStatus({ contextUsed: contextUsedTokens });
+                    }
+                    if (command.exit)
+                        break;
+                    if (command.discover) {
+                        active = new AbortController();
+                        terminal?.setStatus({ activity: 'Fetching models' });
+                        try {
+                            const adapter = createAdapter(config.providers.find(p => p.id === config.provider));
+                            if (!adapter.listModels)
+                                print('Model discovery unavailable. Select a model with /model <id>.');
+                            // Only the user's own cancellation is passed through: the adapter bounds the listing
+                            // itself (MODEL_LISTING_TIMEOUT_MS) and reports that deadline as a timeout, whereas a
+                            // timer armed here would fire first and be reported as a user cancellation.
+                            else
+                                print((await adapter.listModels(active.signal)).join('\n'));
+                        }
+                        finally {
+                            active = undefined;
+                            terminal?.setStatus({ activity: 'Ready' });
+                        }
+                    }
+                }
+                else
+                    await run(line, terminal?.takeAttachments() ?? []);
+            }
+            catch (error) {
+                await debugRecord('command.error', { input: line, mode: 'interactive', message: error instanceof Error ? error.message : String(error) });
+                print(`Error: ${error instanceof Error ? error.message : 'Unknown failure'}`);
+            }
+            finally {
+                await persistSession();
+                await debugRecord('command.completed', { input: line, mode: 'interactive', durationMs: Date.now() - commandStartedAt });
+            }
+        }
+        return terminated ? 143 : 0;
+    }
+    finally {
+        const cleanupErrors = [];
+        // Each resource must be released even when another close rejects. In
+        // particular, an app persistence error must not strand the CLI bridge.
+        for (const cleanup of [
+            // The panel's Git read is a display-only child process: it must not keep the process
+            // alive behind a slow or network-backed worktree once the session is closing.
+            () => {
+                panelReads.abort();
+                if (terminalsTimer)
+                    clearInterval(terminalsTimer);
+                terminalsTimer = undefined;
+                if (changesTimer)
+                    clearTimeout(changesTimer);
+                changesTimer = undefined;
+            },
+            () => browserApp?.close(),
+            () => browserBridge?.close(),
+            () => tabTitle.close(),
+            () => sessionEndedRecord(),
+            // The session-start enqueue is part of the session's records: an exit that skips it leaves a
+            // conversation the user created out of the counts, so this path waits for it like the flush.
+            () => sessionStarted,
+            () => trajectory.flush(),
+            () => { if (accountPolling)
+                clearInterval(accountPolling); if (accountRefreshTimer)
+                clearTimeout(accountRefreshTimer); accountRefresh?.abort(); process.off('SIGINT', interrupt); process.off('SIGTERM', teardown); },
+            () => terminal?.close(),
+            () => graphEditor.close(),
+            () => codeIntel.dispose(),
+            // QA dev servers are owned by this CLI session.
+            () => Promise.all([disposeAllQaProcesses(), disposeAllQaPtys(), disposePooledPowerShell()]).catch(() => { }),
+        ]) {
+            try {
+                await cleanup();
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+            }
+        }
+        // The hard-exit backstop stays armed through the cleanup above: a hung trajectory
+        // flush, editor close or code-intel dispose must not outlive the user's kill. It is
+        // disarmed only once every await has settled, and reset so a later kill() can re-arm.
+        if (killBackstop) {
+            clearTimeout(killBackstop);
+            killBackstop = undefined;
+        }
+        if (cleanupErrors.length)
+            throw new AggregateError(cleanupErrors, 'CLI cleanup failed');
+    }
+}
+if (process.argv[1] && await realpath(fileURLToPath(import.meta.url)) === await realpath(process.argv[1]).catch(() => undefined)) {
+    main().then(code => { process.exitCode = code; }, error => {
+        process.stderr.write(safeTerminal(`Error: ${error instanceof Error ? error.message : 'Unknown failure'}`) + '\n');
+        process.exitCode = 1;
+    });
+}
+/**
+ * The exit code a finished subagent command reports.
+ *
+ * A signal that arrived while the records were still being written is still a signal: the
+ * supervisor that sent it is told the run was interrupted, not that it succeeded. The run's own
+ * cancellation is refused that late, and the refusal must not turn into a success.
+ */
+export function subagentExitCode(outcome, signals) {
+    if (signals.interrupted)
+        return 130;
+    if (signals.terminated)
+        return 143;
+    if (outcome.status === 'succeeded')
+        return 0;
+    if (outcome.status === 'cancelled')
+        return 143;
+    return 1;
+}
+/**
+ * `andorra subagent`: one Andorra run driven by an external host (Claude CLI, Codex CLI).
+ *
+ * The graph is always the bundled Software Engineer harness and the provider/model is mandatory:
+ * the call's own flags win, the saved `/subagent` setting is next, and with neither the command
+ * answers on stdout with the PROVIDER_NOT_SET envelope carrying every configured provider and
+ * model, so a Bash-spawning host can ask its user and retry with the pick. Stdout stays reserved
+ * for machine-readable output — one JSON line either way; progress notes go to stderr.
+ */
+async function runSubagentCommand(argv) {
+    const accepted = ['--prompt', '-p', '--provider', '--model', '--read-only', '--cwd', '--json', '--help', '-h'];
+    // Every failure of this command answers on stdout with the same JSON envelope, so a host that
+    // always parses a result-or-error line is not left with a bare stderr message.
+    const fail = (code, message, extra = {}, exit = 1) => {
+        process.stdout.write(JSON.stringify({ ok: false, error: { code, message, ...extra } }) + '\n');
+        return exit;
+    };
+    // The options that take a value. The value that follows one is the option's value, even when it
+    // begins with a hyphen: a prompt may well start with one, and the configuration permits a
+    // provider or model id that does.
+    const valued = new Set(['--prompt', '-p', '--provider', '--model', '--cwd']);
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (!argument.startsWith('-'))
+            continue;
+        const name = argument.split('=')[0];
+        if (!accepted.includes(name)) {
+            fail('INVALID_ARGUMENTS', `Unknown option ${name}. andorra subagent accepts --prompt, --provider, --model, --read-only and --cwd, and always runs the Software Engineer default graph.`);
+            return 1;
+        }
+        if (valued.has(name) && !argument.includes('='))
+            index += 1;
+    }
+    let values;
+    try {
+        ({ values } = parseArgs({ args: argv, options: {
+                help: { type: 'boolean', short: 'h' }, prompt: { type: 'string', short: 'p' },
+                provider: { type: 'string' }, model: { type: 'string' }, 'read-only': { type: 'boolean' },
+                cwd: { type: 'string' }, json: { type: 'boolean' },
+            } }));
+    }
+    catch (error) {
+        // The parser refuses a malformed invocation — an option without its value, an unknown one it
+        // did not see — and that refusal is an answer this command owes on stdout, like every other
+        // failure of it: a host that parses a result-or-error line must not be left with a bare
+        // stderr message.
+        fail('INVALID_ARGUMENTS', error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    if (values.help) {
+        process.stdout.write('Usage: andorra subagent --prompt "task" [--provider id] [--model id] [--read-only] [--cwd path]\n'
+            + 'Runs the built-in Software Engineer graph once and prints the run result as one JSON line on stdout.\n'
+            + 'Provider/model is mandatory: pass --provider/--model, or set it in Andorra with /subagent. Without either,\n'
+            + 'the output is a PROVIDER_NOT_SET error listing every configured provider and model — show that list to\n'
+            + 'the user, ask which pair to use, and retry with --provider and --model.\n'
+            + 'Writes are allowed by default; pass --read-only to deny them. Exit codes: 0 succeeded, 1 failed or\n'
+            + 'provider not set, 130 cancelled, 143 terminated.\n');
+        return 0;
+    }
+    if (values.prompt === undefined || !values.prompt.trim()) {
+        fail('INVALID_ARGUMENTS', 'andorra subagent requires --prompt "task".');
+        return 1;
+    }
+    // The same bound the MCP tools apply, checked before the run is prepared: a task this long is
+    // persisted and turned into model context, and the CLI path must refuse it the way the MCP
+    // path does rather than write it out and refuse later.
+    if (values.prompt.length > MAX_SUBAGENT_TASK_CHARS) {
+        fail('INVALID_ARGUMENTS', `The task must be at most ${MAX_SUBAGENT_TASK_CHARS} characters.`);
+        return 1;
+    }
+    const runner = new SubagentRunner();
+    let interrupted = false;
+    let terminated = false;
+    const cancel = () => { runner.cancel(); };
+    const onInterrupt = () => { interrupted = true; cancel(); };
+    const onTerminate = () => { terminated = true; cancel(); };
+    // The handlers are installed before the first asynchronous work: a signal that arrives while
+    // the command resolves its workspace or classifies the attempts a previous process left in
+    // flight would otherwise terminate the process directly, and the command would promise neither
+    // its JSON error line nor its exit code.
+    process.once('SIGINT', onInterrupt);
+    process.once('SIGTERM', onTerminate);
+    try {
+        let workspace;
+        try {
+            workspace = await realpath(values.cwd ?? process.cwd());
+            if (!(await stat(workspace)).isDirectory())
+                throw new Error('--cwd must be a directory');
+        }
+        catch (error) {
+            // A signal that arrived while the workspace was resolved is the command's to answer: the
+            // filesystem error is not what the supervisor asked about.
+            const signalled = subagentExitCode({ status: 'infrastructure_error' }, { interrupted, terminated });
+            if (signalled !== 1) {
+                return fail(interrupted ? 'CANCELLED' : 'TERMINATED', interrupted ? 'The run was interrupted before it started.' : 'The run was terminated before it started.', {}, signalled);
+            }
+            fail('INVALID_ARGUMENTS', error instanceof Error ? error.message : String(error));
+            return 1;
+        }
+        // Attempts a previous process left in flight are classified before this one starts: this
+        // command returns before the CLI's own startup recovery, so without this pass a crashed
+        // subagent run would keep its record and its session turn `running` until an unrelated
+        // interactive CLI or app-server was opened. Best effort: a damaged home must not block the run.
+        // A run this process is still executing is not debris: an embedding process can call this
+        // command while another engine works in the same home, and terminalizing that run would
+        // remove the claim that holds its session and let a mutation in while it saves over it.
+        try {
+            const recovered = await reconcileInterruptedRuns(configDirectory(), undefined, { skipOwnProcess: true, includePending: true });
+            // The reconciliation has already rewritten these records, so a later interactive startup
+            // will not see them again: the finish is owed here or the start stays unmatched forever.
+            await reportInterruptedRuns({ home: configDirectory(), surface: configuredSurface('subagent') }, recovered.interrupted);
+        }
+        catch { /* Recovery is best effort. */ }
+        // A signal that arrived while the command was preparing is the command's to answer: a run that
+        // starts now would be a full-access, billable run after the supervisor asked it to stop.
+        const signalled = subagentExitCode({ status: 'infrastructure_error' }, { interrupted, terminated });
+        if (signalled !== 1) {
+            return fail(interrupted ? 'CANCELLED' : 'TERMINATED', interrupted ? 'The run was interrupted before it started.' : 'The run was terminated before it started.', {}, signalled);
+        }
+        const started = await runner.start({
+            task: values.prompt, workspace,
+            ...(values.provider !== undefined ? { provider: values.provider } : {}),
+            ...(values.model !== undefined ? { model: values.model } : {}),
+            permissions: values['read-only'] ? 'read-only' : 'full-access',
+        });
+        process.stderr.write(safeTerminal(`Subagent run ${started.runId} on ${started.provider}/${started.model} (${started.permissions}).\n`));
+        let outcome = await runner.result(60_000);
+        while (outcome.state === 'running')
+            outcome = await runner.result(60_000);
+        process.stdout.write(JSON.stringify(outcome.result ?? { status: outcome.status, ...(outcome.reason !== undefined ? { reason: outcome.reason } : {}) }) + '\n');
+        // A signal that arrived while the records were still being written is still a signal: the
+        // supervisor that sent it is told the run was interrupted, not that it succeeded. The run's
+        // own cancellation is refused that late, and the refusal must not turn into a success.
+        return subagentExitCode(outcome, { interrupted, terminated });
+    }
+    catch (error) {
+        // A signal that arrived while the start was preparing is still a signal: the supervising host
+        // is told the run was interrupted, not that it failed for some reason of its own.
+        const signalled = subagentExitCode({ status: 'infrastructure_error' }, { interrupted, terminated });
+        if (signalled !== 1) {
+            // The command promises one JSON line on stdout: a host that parses a result-or-error line
+            // must not be left with an empty answer.
+            return fail(interrupted ? 'CANCELLED' : 'TERMINATED', interrupted ? 'The run was interrupted before it started.' : 'The run was terminated before it started.', {}, signalled);
+        }
+        if (error instanceof SubagentProviderNotSetError)
+            return fail('PROVIDER_NOT_SET', error.message, { providers: error.providers });
+        if (error instanceof SubagentRunInProgressError)
+            return fail('RUN_IN_PROGRESS', error.message);
+        if (error instanceof SubagentSelectionError)
+            return fail('INVALID_ARGUMENTS', error.message);
+        if (error instanceof SubagentInvalidArgumentError)
+            return fail('INVALID_ARGUMENTS', error.message);
+        return fail('SUBAGENT_FAILED', error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        // Only this command own handlers go: an embedding process may have listeners of its own,
+        // and they are not this command to remove.
+        process.removeListener('SIGINT', onInterrupt);
+        process.removeListener('SIGTERM', onTerminate);
+    }
+}