@cruxy/cli 1.2.0 → 1.3.0

package/dist/cli/commands/run.js

@@ -1,5 +1,9 @@
 import { Command } from "commander";
+import { randomUUID } from "node:crypto";
 import { logger } from "../../utils/logger.js";
+import { SessionLog, listSessions, resumeById, resumePicker, shortId, } from "../../session/index.js";
+/** Sessions shown in the TUI sidebar — the same depth as the resume picker. */
+const SIDEBAR_SESSIONS = 10;
 import { loadConfig, resolveApiKey } from "../../config/index.js";
 import { agentIncomplete, authMissingKey, shouldUseColor, usageError, } from "../../errors/index.js";
 import { createRenderer } from "../../render/index.js";
@@ -8,7 +12,9 @@ import { summarizeRuns, renderSummary, } from "../../usage/index.js";
 import { CheckpointGate } from "../../checkpoint/index.js";
 import { SandboxService } from "../../sandbox/index.js";
 import { buildHooksService, buildHooksRouter } from "../../hooks/index.js";
+import { DEFAULT_MODE, } from "../../agent/index.js";
 import { runInteractive } from "../repl.js";
+import { ContextGauge, createKeyLease, runTui, TuiRenderer, } from "../../tui/index.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 import { resetLspServices } from "../../lsp/index.js";
@@ -35,256 +41,397 @@ export function runCommand() {
         .option("--plan", "plan mode: propose a step-by-step plan for approval before executing")
         .option("--sandbox", "run shell + test commands inside an isolated container (fails loud if no runtime)")
         .option("--root <spec>", "declare a workspace root (repeatable): name=path or path; the first is primary", collectRoot, [])
-        .action(async (promptParts, opts) => {
-        const prompt = promptParts.join(" ").trim();
-        const t = themeForColor(shouldUseColor(process.stdout));
-        const interactive = prompt === "";
-        // No prompt and stdin isn't a terminal: there's no way to read input and
-        // nothing to do — fail fast instead of hanging on a line that never comes.
-        if (interactive && !process.stdin.isTTY) {
-            throw usageError("cruxy run needs a prompt when stdin is not a terminal", ['provide a task, e.g. cruxy run "fix the failing test"']);
+        .action((promptParts, opts) => executeRun(promptParts, opts));
+}
+/**
+ * The `run` pipeline, extracted from the command action so the bare-`cruxy`
+ * entry can reuse it verbatim (P1). `cruxy run` calls it with `tui: false`, so
+ * that path is byte-for-byte what it was; the TUI entry differs only in the
+ * renderer it asks for and the loop it hands the session to.
+ */
+export async function executeRun(promptParts, opts) {
+    const prompt = promptParts.join(" ").trim();
+    const t = themeForColor(shouldUseColor(process.stdout));
+    const invokedAs = opts.commandName ?? "cruxy run";
+    const interactive = prompt === "";
+    // No prompt and stdin isn't a terminal: there's no way to read input and
+    // nothing to do — fail fast instead of hanging on a line that never comes.
+    //
+    // `--resume` reaches here too, and gets its own wording: restoring a session
+    // with nothing to say to it is a no-op, and the fix is a message rather than
+    // a different id. A resume WITH a message is fine and never lands here — it
+    // continues the restored history as a one-shot.
+    if (interactive && !process.stdin.isTTY) {
+        throw usageError(opts.resume !== undefined
+            ? `${invokedAs} --resume needs a terminal, or a message to continue with`
+            : `${invokedAs} needs a prompt when stdin is not a terminal`, opts.resume !== undefined
+            ? [
+                `add a message, e.g. ${invokedAs} --resume <id> "keep going"`,
+                "or run it in a terminal to continue interactively",
+            ]
+            : [`provide a task, e.g. ${invokedAs} "fix the failing test"`]);
+    }
+    const { config, sources } = loadConfig();
+    let apiKey = resolveApiKey(config.model.provider);
+    // Declared workspace roots (C.26). This is the ONE place `run` reads the
+    // process working directory — the invocation directory is the base for
+    // resolving `--root` paths and the sole root when none are declared. Every
+    // subsystem below derives its cwd from the WORKSPACE (`primaryRoot`), never
+    // re-reads the invocation directory, so nothing can silently split-brain to
+    // a different dir than the roots the tools see (the guard test pins this).
+    const invocationCwd = process.cwd();
+    // No --root → a trivial single-root workspace (byte-identical to pre-C.26).
+    // --root builds a genuine multi-root Workspace and fails fast HERE — a
+    // missing / non-dir / overlapping root (CRUXY_E_ROOT_OVERLAP) throws before
+    // onboarding or the session starts, never a half-built session.
+    const workspace = opts.root.length
+        ? await buildWorkspace(opts.root, { cwd: invocationCwd })
+        : sessionWorkspace(invocationCwd);
+    const primaryRoot = workspace.primary().absPath;
+    logger.info(t.muted(`model:   ${config.model.provider}/${config.model.model}`));
+    logger.info(t.muted(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
+    // Multi-root honesty (JC-6/C.26): reads fan every root. With per-root
+    // checkpoints active (C.26 step 3), writes fan every root too — each is
+    // checkpointed and rollback-able. With checkpoints DISABLED, a non-primary
+    // write is still refused (CRUXY_E_MULTIROOT_WRITE_DEFERRED) rather than left
+    // un-restorable. Hooks + MCP still scope to the primary this release. Named
+    // at start, never a silent primary-default.
+    if (workspace.isMultiRoot) {
+        const names = workspace
+            .roots()
+            .map((r) => r.name)
+            .join(", ");
+        const writes = config.checkpoint.enabled
+            ? "writes fan all roots (each checkpointed)"
+            : "writes scope to primary (checkpoints disabled)";
+        logger.info(t.muted(`roots:   ${workspace.roots().length} (${names}); primary ${workspace.primary().name} — ` +
+            `reads fan all roots; ${writes}; hooks fan per trusted root; MCP loads from primary only this release`));
+    }
+    // First-run with no key (and a TTY) → guided onboarding instead of the
+    // dead-end auth error. The first-win demo is offered only in the no-prompt
+    // (REPL) path; with a real prompt, that prompt IS the first win.
+    if (!apiKey) {
+        const onboarding = maybeRunOnboarding(config, {
+            ttyInteractive: Boolean(process.stdin.isTTY),
+            offerFirstWin: interactive,
+            cwd: primaryRoot,
+        });
+        if (onboarding === null) {
+            // Not a first run (non-TTY, or onboarded then key removed) → fail loud.
+            throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
         }
-        const { config, sources } = loadConfig();
-        let apiKey = resolveApiKey(config.model.provider);
-        // Declared workspace roots (C.26). This is the ONE place `run` reads the
-        // process working directory — the invocation directory is the base for
-        // resolving `--root` paths and the sole root when none are declared. Every
-        // subsystem below derives its cwd from the WORKSPACE (`primaryRoot`), never
-        // re-reads the invocation directory, so nothing can silently split-brain to
-        // a different dir than the roots the tools see (the guard test pins this).
-        const invocationCwd = process.cwd();
-        // No --root → a trivial single-root workspace (byte-identical to pre-C.26).
-        // --root builds a genuine multi-root Workspace and fails fast HERE — a
-        // missing / non-dir / overlapping root (CRUXY_E_ROOT_OVERLAP) throws before
-        // onboarding or the session starts, never a half-built session.
-        const workspace = opts.root.length
-            ? await buildWorkspace(opts.root, { cwd: invocationCwd })
-            : sessionWorkspace(invocationCwd);
-        const primaryRoot = workspace.primary().absPath;
-        logger.info(t.muted(`model:   ${config.model.provider}/${config.model.model}`));
-        logger.info(t.muted(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
-        // Multi-root honesty (JC-6/C.26): reads fan every root. With per-root
-        // checkpoints active (C.26 step 3), writes fan every root too — each is
-        // checkpointed and rollback-able. With checkpoints DISABLED, a non-primary
-        // write is still refused (CRUXY_E_MULTIROOT_WRITE_DEFERRED) rather than left
-        // un-restorable. Hooks + MCP still scope to the primary this release. Named
-        // at start, never a silent primary-default.
-        if (workspace.isMultiRoot) {
-            const names = workspace
-                .roots()
-                .map((r) => r.name)
-                .join(", ");
-            const writes = config.checkpoint.enabled
-                ? "writes fan all roots (each checkpointed)"
-                : "writes scope to primary (checkpoints disabled)";
-            logger.info(t.muted(`roots:   ${workspace.roots().length} (${names}); primary ${workspace.primary().name} — ` +
-                `reads fan all roots; ${writes}; hooks fan per trusted root; MCP loads from primary only this release`));
+        const result = await onboarding;
+        if (!result.completed) {
+            // Aborted/failed mid-setup — guidance already shown; exit cleanly.
+            logger.print(t.muted("run `cruxy login` to finish setup."));
+            return;
         }
-        // First-run with no key (and a TTY) → guided onboarding instead of the
-        // dead-end auth error. The first-win demo is offered only in the no-prompt
-        // (REPL) path; with a real prompt, that prompt IS the first win.
+        apiKey = result.apiKey ?? resolveApiKey(config.model.provider);
         if (!apiKey) {
-            const onboarding = maybeRunOnboarding(config, {
-                ttyInteractive: Boolean(process.stdin.isTTY),
-                offerFirstWin: interactive,
-                cwd: primaryRoot,
-            });
-            if (onboarding === null) {
-                // Not a first run (non-TTY, or onboarded then key removed) → fail loud.
-                throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
-            }
-            const result = await onboarding;
-            if (!result.completed) {
-                // Aborted/failed mid-setup — guidance already shown; exit cleanly.
-                logger.print(t.muted("run `cruxy login` to finish setup."));
-                return;
-            }
-            apiKey = result.apiKey ?? resolveApiKey(config.model.provider);
-            if (!apiKey) {
-                throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
-            }
+            throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
         }
-        // Plan mode is opt-in: --plan flag overrides the config default.
-        const planMode = opts.plan ?? config.agent.planMode;
-        // One renderer for the whole run (U.2): the streaming path and the
-        // approval prompt's status-suspend hook must share the same live region.
-        const renderer = createRenderer();
-        // Checkpoint-before-first-mutation (C.32/C.26): the gate owns one
-        // CheckpointService PER touched root (lazy) plus the run's CheckpointSet,
-        // and fires from the approval seam inside the session — so one instance
-        // covers the one-shot path, every REPL turn, plan-mode execution, and
-        // subagents (they share this gate, so their writes join the run's set).
-        const checkpoints = config.checkpoint.enabled
-            ? new CheckpointGate({ config, primaryRoot })
-            : undefined;
-        // Sandbox (C.16): opt-in via --sandbox or sandbox.enabled. Resolving the
-        // service probes the runtime and THROWS CRUXY_E_SANDBOX_UNAVAILABLE if it
-        // is missing — fail loud here, before the agent starts, rather than
-        // silently running un-sandboxed. When off, ctx.sandbox stays undefined and
-        // execution runs on the host, unchanged.
-        const sandboxEnabled = opts.sandbox ?? config.sandbox.enabled;
-        const sandbox = sandboxEnabled
-            ? await SandboxService.create({
-                config,
-                cwd: primaryRoot,
-                // R5 (C.26): the command's root (primary — shell/test attribute to
-                // it this release) mounts read-write; every OTHER declared root
-                // mounts read-only. Cross-root write is only ever granted per-root
-                // via a named escalation, never blanket.
-                siblingRoots: workspace
-                    .roots()
-                    .filter((r) => !r.primary)
-                    .map((r) => r.absPath),
-                reporter: renderer,
-            })
-            : undefined;
-        if (sandbox) {
-            logger.info(t.muted(`sandbox: ${sandbox.runtimeName} (network ${config.sandbox.network})`));
+    }
+    // Resume (P2), resolved BEFORE the renderer and the session: `--resume <id>`
+    // restores that session directly and fails loud on an unknown or ambiguous
+    // id; bare `--resume` offers the last ten plus "new session", and a decline
+    // (or a cancel) falls through to a fresh session with no further ceremony.
+    //
+    // Warnings — a cwd mismatch, or lines the replay could not read — are printed
+    // here, before any turn runs, because they change what the restored history
+    // means. Resuming still proceeds: the user asked for it, and refusing because
+    // a repo moved would be worse than saying so plainly.
+    let resumed = null;
+    if (opts.resume !== undefined && opts.resume !== false) {
+        resumed =
+            typeof opts.resume === "string" && opts.resume !== ""
+                ? resumeById(primaryRoot, opts.resume)
+                : await resumePicker(primaryRoot, { logger });
+        if (resumed) {
+            for (const warning of resumed.warnings)
+                logger.warn(warning);
+            logger.info(t.muted(`resumed session ${shortId(resumed.session.sessionId)} — ${resumed.session.turns} turn(s), ${resumed.state.messages.length} message(s)`));
         }
-        // Hooks + custom slash commands (C.19). Single-root uses the unchanged
-        // service (byte-identical: one runner, lazy trust prompt). Multi-root
-        // (C.26 step 5) builds ONE runner per root behind a HookRouter — tool
-        // events fire the acting root's hooks, lifecycle events fan every trusted
-        // root. Untrusted roots are skipped and NAMED here (never a silent loss).
-        let hooksRunner;
-        let hookCommands;
-        if (workspace.isMultiRoot) {
-            const router = await buildHooksRouter({ workspace, config, logger });
-            hooksRunner = router.runner;
-            hookCommands = router.commands;
-            for (const u of router.untrustedHookRoots) {
-                logger.info(t.muted(`hooks:   root "${u.name}" has ${u.count} untrusted hook${u.count === 1 ? "" : "s"} — ` +
-                    `not firing (run \`cruxy hooks trust ${u.absPath}\`)`));
-            }
-        }
-        else {
-            const hooksService = await buildHooksService({
-                cwd: primaryRoot,
-                config,
-                interactive: Boolean(process.stdin.isTTY),
-                logger,
-            });
-            hooksRunner = hooksService.runner;
-            hookCommands = hooksService.commands;
+    }
+    // The mode a fresh session STARTS in (P5 track 3). `--plan` and the config
+    // default still mean plan mode; they now name a point in the mode ring rather
+    // than flipping a boolean, and the user can cycle away from it at runtime. A
+    // resumed session's recorded mode is restored by the Session itself, so this
+    // only decides the starting value for a fresh one.
+    const startMode = (opts.plan ?? config.agent.planMode) ? "plan" : DEFAULT_MODE;
+    // One renderer for the whole run (U.2): the streaming path and the
+    // approval prompt's status-suspend hook must share the same live region.
+    // `tui` is a request the factory may decline (pipe / screen reader /
+    // dumb terminal), in which case this is the unchanged live-line or
+    // append-only renderer.
+    const renderer = createRenderer(process.stdout, process.stderr, process.env, {
+        tui: opts.tui ?? false,
+        headerRight: `${config.model.provider}/${config.model.model}`,
+        // The model panel and the composed header (P4 track 4) have been reaching
+        // for these since #181 and NOTHING supplied them: `provider`/`model` were
+        // never passed from here, so the panel rendered "not wired yet" for the life
+        // of every real session while the header showed the static string above,
+        // frozen at whatever config said. Both surfaces were built and tested; only
+        // the two arguments were missing. P6 track 1 needs them live anyway.
+        provider: config.model.provider,
+        model: config.model.model,
+        // The WORKSPACE root, not the invocation cwd — the same root the session,
+        // checkpoints and tools work against, so the rail reports on the repo the
+        // run is actually changing. A multi-root workspace reports its primary.
+        gitCwd: primaryRoot,
+    });
+    // Checkpoint-before-first-mutation (C.32/C.26): the gate owns one
+    // CheckpointService PER touched root (lazy) plus the run's CheckpointSet,
+    // and fires from the approval seam inside the session — so one instance
+    // covers the one-shot path, every REPL turn, plan-mode execution, and
+    // subagents (they share this gate, so their writes join the run's set).
+    const checkpoints = config.checkpoint.enabled
+        ? new CheckpointGate({ config, primaryRoot })
+        : undefined;
+    // Sandbox (C.16): opt-in via --sandbox or sandbox.enabled. Resolving the
+    // service probes the runtime and THROWS CRUXY_E_SANDBOX_UNAVAILABLE if it
+    // is missing — fail loud here, before the agent starts, rather than
+    // silently running un-sandboxed. When off, ctx.sandbox stays undefined and
+    // execution runs on the host, unchanged.
+    const sandboxEnabled = opts.sandbox ?? config.sandbox.enabled;
+    const sandbox = sandboxEnabled
+        ? await SandboxService.create({
+            config,
+            cwd: primaryRoot,
+            // R5 (C.26): the command's root (primary — shell/test attribute to
+            // it this release) mounts read-write; every OTHER declared root
+            // mounts read-only. Cross-root write is only ever granted per-root
+            // via a named escalation, never blanket.
+            siblingRoots: workspace
+                .roots()
+                .filter((r) => !r.primary)
+                .map((r) => r.absPath),
+            reporter: renderer,
+        })
+        : undefined;
+    if (sandbox) {
+        logger.info(t.muted(`sandbox: ${sandbox.runtimeName} (network ${config.sandbox.network})`));
+    }
+    // Hooks + custom slash commands (C.19). Single-root uses the unchanged
+    // service (byte-identical: one runner, lazy trust prompt). Multi-root
+    // (C.26 step 5) builds ONE runner per root behind a HookRouter — tool
+    // events fire the acting root's hooks, lifecycle events fan every trusted
+    // root. Untrusted roots are skipped and NAMED here (never a silent loss).
+    let hooksRunner;
+    let hookCommands;
+    if (workspace.isMultiRoot) {
+        const router = await buildHooksRouter({ workspace, config, logger });
+        hooksRunner = router.runner;
+        hookCommands = router.commands;
+        for (const u of router.untrustedHookRoots) {
+            logger.info(t.muted(`hooks:   root "${u.name}" has ${u.count} untrusted hook${u.count === 1 ? "" : "s"} — ` +
+                `not firing (run \`cruxy hooks trust ${u.absPath}\`)`));
         }
-        // MCP servers (C.27): connect + trust-gate BEFORE building the session so
-        // the tool catalogue is complete when the model first runs. Off by
-        // default (no servers connect). A non-interactive run with an untrusted
-        // config THROWS CRUXY_E_MCP_UNTRUSTED here — before any server spawns.
-        const mcp = await connectMcpTools({
+    }
+    else {
+        const hooksService = await buildHooksService({
             cwd: primaryRoot,
             config,
-            logger,
             interactive: Boolean(process.stdin.isTTY),
-            io: defaultPromptIO(shouldUseColor()),
+            logger,
         });
-        // MCP is primary-root only this release (JC-D). Name each sibling-root
-        // server individually — never one generic line, never a silent drop —
-        // so a user who declared `github` in a sibling knows exactly why its
-        // tools aren't present (and that root-qualified names are a follow-up).
-        if (workspace.isMultiRoot) {
-            for (const d of deferredSiblingServers(workspace)) {
-                logger.info(t.muted(`mcp:     server "${d.server}" declared in ${d.root} not loaded (primary-root MCP only this release)`));
-            }
+        hooksRunner = hooksService.runner;
+        hookCommands = hooksService.commands;
+    }
+    // MCP servers (C.27): connect + trust-gate BEFORE building the session so
+    // the tool catalogue is complete when the model first runs. Off by
+    // default (no servers connect). A non-interactive run with an untrusted
+    // config THROWS CRUXY_E_MCP_UNTRUSTED here — before any server spawns.
+    const mcp = await connectMcpTools({
+        cwd: primaryRoot,
+        config,
+        logger,
+        interactive: Boolean(process.stdin.isTTY),
+        io: defaultPromptIO(shouldUseColor()),
+    });
+    // MCP is primary-root only this release (JC-D). Name each sibling-root
+    // server individually — never one generic line, never a silent drop —
+    // so a user who declared `github` in a sibling knows exactly why its
+    // tools aren't present (and that root-qualified names are a follow-up).
+    if (workspace.isMultiRoot) {
+        for (const d of deferredSiblingServers(workspace)) {
+            logger.info(t.muted(`mcp:     server "${d.server}" declared in ${d.root} not loaded (primary-root MCP only this release)`));
         }
-        // One-shot vs REPL turn ceiling. A one-shot run caps at
-        // `agent.maxIterationsOneShot` (default 40): a headless run can't be
-        // resumed by a human, so hitting the cap abandons the whole task — it
-        // needs headroom above the interactive cap to clear legit long work,
-        // while still bounding a runaway (and it now exits non-zero, see below).
-        // The REPL keeps `agent.maxIterations` (a soft checkpoint). Keyed on the
-        // one-shot MODE, never on TTY, so `cruxy run "task"` behaves the same
-        // piped into CI or run in a terminal.
-        const sessionConfig = interactive
-            ? config
-            : {
-                ...config,
-                agent: {
-                    ...config.agent,
-                    maxIterations: config.agent.maxIterationsOneShot,
+    }
+    // Did the factory actually give us the TUI? Asking the renderer beats
+    // re-deriving it: `opts.tui` is only a REQUEST, and `supportsTui` may
+    // have declined it (screen reader, piped stdin, TERM=dumb). A declined
+    // TUI must behave exactly like the REPL, which is what this yields.
+    const tui = renderer instanceof TuiRenderer ? renderer : null;
+    // A TUI session is multi-turn even when it opened with a message, so it
+    // takes the interactive ceiling, not the one-shot one.
+    const multiTurn = interactive || tui !== null;
+    // One-shot vs REPL turn ceiling. A one-shot run caps at
+    // `agent.maxIterationsOneShot` (default 40): a headless run can't be
+    // resumed by a human, so hitting the cap abandons the whole task — it
+    // needs headroom above the interactive cap to clear legit long work,
+    // while still bounding a runaway (and it now exits non-zero, see below).
+    // The REPL keeps `agent.maxIterations` (a soft checkpoint). Keyed on the
+    // one-shot MODE, never on TTY, so `cruxy run "task"` behaves the same
+    // piped into CI or run in a terminal.
+    const sessionConfig = multiTurn
+        ? config
+        : {
+            ...config,
+            agent: {
+                ...config.agent,
+                maxIterations: config.agent.maxIterationsOneShot,
+            },
+        };
+    // Session persistence (P2). The log is opened AFTER resume resolution so a
+    // restored session continues writing to its own file rather than starting a
+    // second one, and it borrows the CheckpointGate's per-turn run id rather than
+    // minting one — `cruxy rollback <id>` and the transcript must agree on what a
+    // turn is. Opening can fail (unwritable home); that degrades to running
+    // without persistence, never to failing the run.
+    const restore = resumed?.state;
+    const sessionId = restore?.meta.sessionId ?? randomUUID();
+    const recorder = SessionLog.open({
+        sessionId,
+        cwd: primaryRoot,
+        roots: workspace.roots().map((r) => ({ name: r.name, path: r.absPath })),
+        provider: config.model.provider,
+        model: config.model.model,
+        logger,
+        currentRunId: () => checkpoints?.currentRunId(),
+        ...(resumed ? { file: resumed.session.file } : {}),
+    }) ?? undefined;
+    // The TUI sidebar lists the same tree the `--resume` picker reads (P2).
+    // Populated AFTER the log is opened so the running session is itself listed —
+    // its meta line has to exist before `listSessions` can see it.
+    if (renderer instanceof TuiRenderer) {
+        renderer.setSessions(listSessions(primaryRoot, SIDEBAR_SESSIONS), sessionId);
+    }
+    // ONE key reader for the whole TUI session (P5): the input loop and the
+    // approval prompt's modal both lease it, so the two can never be live on
+    // stdin at the same time. Built here — above both consumers — because it is
+    // the shared thing, and created only on the TUI path; every other shell keeps
+    // the stderr prompt and its own reader.
+    const keyLease = tui ? createKeyLease(process.stdin) : undefined;
+    const session = buildAgentSession(sessionConfig, apiKey, workspace, Boolean(process.stdin.isTTY), startMode, renderer, checkpoints, sandbox, hooksRunner, mcp.tools, {
+        recorder,
+        ...(keyLease ? { keyLease } : {}),
+        ...(restore
+            ? {
+                restore: {
+                    messages: restore.messages,
+                    usage: restore.usage,
+                    sessionId: restore.meta.sessionId,
+                    mode: restore.mode,
                 },
-            };
-        const session = buildAgentSession(sessionConfig, apiKey, workspace, Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksRunner, mcp.tools);
-        if (interactive) {
-            try {
-                await runInteractive(session, undefined, renderer, checkpoints, hookCommands);
-            }
-            finally {
-                // Background jobs (C.28): cancel every live job on session exit —
-                // kill-tree'ing each job's process group (no orphan) and reporting an
-                // honest "N job(s) cancelled". A paused job is cancelled too, but any
-                // checkpoint it took survives for review/rollback.
-                const cancelled = (await session.jobs?.cancelAll("session exit")) ?? 0;
-                if (cancelled > 0) {
-                    logger.print(t.muted(`${cancelled} background job${cancelled === 1 ? "" : "s"} cancelled on exit`));
-                }
-                // LSP (C.12) + MCP (C.27): gracefully shut down any external server
-                // processes spawned during the session (the shared process-exit
-                // kill-tree is the fail-safe for a hard kill).
-                await resetLspServices();
-                await resetMcpServices();
             }
-            return;
-        }
-        checkpoints?.beginRun(prompt);
-        // One-shot: a single turn, then exit. Preserves scripting/pipe use.
-        // Assistant text streams to stdout delta by delta (same as the REPL);
-        // piped output degrades to the plain renderer (no ANSI, chrome on stderr).
-        logger.print(`${t.accent("cruxy")} ${t.muted(t.glyph.caret)} ${prompt}\n`);
-        // Provider/network/auth failures propagate to the top-level boundary,
-        // which classifies them (e.g. CRUXY_E_GATEWAY_UNREACHABLE) and exits with
-        // the matching code — a one-shot run must fail non-zero on error.
-        let result;
+            : {}),
+    });
+    // The context rail panel (P4 track 3). Attached AFTER the session exists,
+    // because the gauge measures that session's live history — and deliberately
+    // reads `session.messages`, never `session.usage`, which is cumulative across
+    // turns and would never fall when a compaction frees the window.
+    tui?.attachContext(new ContextGauge(() => session.messages, config.context));
+    // The model panel's configured value becomes LIVE (P6 track 1) — the same
+    // object `/model` moves, so the panel, the header and the status line cannot
+    // disagree about what this session is set to. Absent on a bring-your-own
+    // provider, where the constructor's static value stands and `/model` declines.
+    if (session.model)
+        tui?.attachModel(session.model);
+    if (multiTurn) {
         try {
-            result = await session.send(prompt, renderer);
-            logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
-                `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
+            // Same session, same renderer seam, two shells: the TUI when the
+            // entry asked for it and the environment allowed it, the readline
+            // REPL otherwise. `cruxy run` never reaches the first branch.
+            if (tui) {
+                await runTui(session, tui, {
+                    initialMessage: prompt,
+                    checkpoints,
+                    // The TUI reached P5 without these (P5 track 5): every custom slash
+                    // command a project defines was unreachable from the default shell.
+                    slashCommands: hookCommands,
+                    ...(keyLease ? { lease: keyLease } : {}),
+                });
+            }
+            else {
+                await runInteractive(session, undefined, renderer, checkpoints, hookCommands);
+            }
         }
         finally {
-            renderer.close();
-            // Background jobs (C.28): a one-shot run has no between-turns servicing
-            // loop, so cancel every live job on exit (kill-tree, no orphan) rather
-            // than leave one paused forever. Checkpoints taken survive for rollback.
-            await session.jobs?.cancelAll("session exit");
+            // Tear the shell down FIRST: the TUI owns the whole viewport, so
+            // every line below would land inside (and be erased with) the frame
+            // unless the screen is released before anything else prints. The
+            // REPL path closes its own renderer inside `runInteractive`.
+            tui?.close();
+            // Background jobs (C.28): cancel every live job on session exit —
+            // kill-tree'ing each job's process group (no orphan) and reporting an
+            // honest "N job(s) cancelled". A paused job is cancelled too, but any
+            // checkpoint it took survives for review/rollback.
+            const cancelled = (await session.jobs?.cancelAll("session exit")) ?? 0;
+            if (cancelled > 0) {
+                logger.print(t.muted(`${cancelled} background job${cancelled === 1 ? "" : "s"} cancelled on exit`));
+            }
             // LSP (C.12) + MCP (C.27): gracefully shut down any external server
-            // processes spawned during the run (the shared process-exit kill-tree
-            // is the fail-safe for a hard kill).
+            // processes spawned during the session (the shared process-exit
+            // kill-tree is the fail-safe for a hard kill).
             await resetLspServices();
             await resetMcpServices();
         }
-        // End-of-run usage summary (C.22): honest tokens + per-tier breakdown +
-        // cost (only when priced). Printed after the live region is torn down, for
-        // BOTH a completed run and one that gave up below — the tokens burned are
-        // useful either way. A thrown run (provider error) propagates past it.
-        if (config.usage.enabled && session.lastRun) {
-            printRunUsage(session.lastRun, config);
-        }
-        // Fail loud on a non-completed stop (#3/#5): a one-shot run that hit the
-        // iteration cap or a token budget (or was cancelled) MUST exit non-zero —
-        // otherwise CI reads a gave-up run as success. The partial history already
-        // streamed to stdout stands; the boundary prints the coded reason to stderr
-        // and exits with CRUXY_E_AGENT_INCOMPLETE's code. `result` is always set
-        // here — a thrown send would have propagated past this point.
-        if (result && result.stop !== "completed") {
-            throw agentIncomplete({
-                stop: result.stop,
-                iterations: result.iterations,
-                reason: result.stopReason,
-                // The effective one-shot cap (agent.maxIterationsOneShot), so the
-                // message names the limit the run actually hit.
-                maxIterations: sessionConfig.agent.maxIterations,
-            });
-        }
-    });
+        return;
+    }
+    checkpoints?.beginRun(prompt);
+    // One-shot: a single turn, then exit. Preserves scripting/pipe use.
+    // Assistant text streams to stdout delta by delta (same as the REPL);
+    // piped output degrades to the plain renderer (no ANSI, chrome on stderr).
+    logger.print(`${t.accent("cruxy")} ${t.muted(t.glyph.caret)} ${prompt}\n`);
+    // Provider/network/auth failures propagate to the top-level boundary,
+    // which classifies them (e.g. CRUXY_E_GATEWAY_UNREACHABLE) and exits with
+    // the matching code — a one-shot run must fail non-zero on error.
+    let result;
+    try {
+        result = await session.send(prompt, renderer);
+        logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
+            `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
+    }
+    finally {
+        renderer.close();
+        // Background jobs (C.28): a one-shot run has no between-turns servicing
+        // loop, so cancel every live job on exit (kill-tree, no orphan) rather
+        // than leave one paused forever. Checkpoints taken survive for rollback.
+        await session.jobs?.cancelAll("session exit");
+        // LSP (C.12) + MCP (C.27): gracefully shut down any external server
+        // processes spawned during the run (the shared process-exit kill-tree
+        // is the fail-safe for a hard kill).
+        await resetLspServices();
+        await resetMcpServices();
+    }
+    // End-of-run usage summary (C.22): honest tokens + per-tier breakdown +
+    // cost (only when priced). Printed after the live region is torn down, for
+    // BOTH a completed run and one that gave up below — the tokens burned are
+    // useful either way. A thrown run (provider error) propagates past it.
+    if (config.usage.enabled && session.lastRun) {
+        printRunUsage(session.lastRun);
+    }
+    // Fail loud on a non-completed stop (#3/#5): a one-shot run that hit the
+    // iteration cap or a token budget (or was cancelled) MUST exit non-zero —
+    // otherwise CI reads a gave-up run as success. The partial history already
+    // streamed to stdout stands; the boundary prints the coded reason to stderr
+    // and exits with CRUXY_E_AGENT_INCOMPLETE's code. `result` is always set
+    // here — a thrown send would have propagated past this point.
+    if (result && result.stop !== "completed") {
+        throw agentIncomplete({
+            stop: result.stop,
+            iterations: result.iterations,
+            reason: result.stopReason,
+            // The effective one-shot cap (agent.maxIterationsOneShot), so the
+            // message names the limit the run actually hit.
+            maxIterations: sessionConfig.agent.maxIterations,
+        });
+    }
 }
 /** Render the just-finished run's usage as a single themed line (C.22). */
-function printRunUsage(record, config) {
+function printRunUsage(record) {
     if (record.entries.length === 0)
         return;
     const t = themeForColor(shouldUseColor(process.stdout));
-    const summary = summarizeRuns([record], {
-        prices: config.usage.prices,
-        currency: config.usage.currency,
-    });
-    logger.print(renderSummary(summary, t));
+    logger.print(renderSummary(summarizeRuns([record]), t));
 }