@cruxy/cli 1.2.1 → 1.3.0

package/dist/session/types.js

@@ -0,0 +1,223 @@
+import { z } from "zod";
+/**
+ * Session persistence (P2): the on-disk shape of a conversation.
+ *
+ * The file is an APPEND-ONLY event log (JSONL), not a snapshot of the message
+ * array. That distinction is the whole design:
+ *
+ * - `Session.messages` is rewritten in place — compaction replaces an older
+ *   prefix with a synthetic summary pair (see `agent/session.ts`). A snapshot
+ *   format would have to rewrite the whole file on every turn, which is O(n²)
+ *   in turns and loses the history of what was compacted away.
+ * - An event log records the rewrite as an EVENT (`compaction`, carrying what
+ *   it replaced), so the file only ever grows, and replay reconstructs the
+ *   current array exactly. What the model can still see and what the user
+ *   actually said stay separately recoverable.
+ *
+ * Replay is a fold over the events; see `replay.ts`.
+ */
+/**
+ * Bump when the event shapes change incompatibly. Present on the `meta` line
+ * only — every subsequent line is self-describing via `kind`.
+ */
+export const SESSION_FILE_VERSION = 1;
+/**
+ * FORWARD COMPATIBILITY — why every schema below is `.passthrough()`.
+ *
+ * This is the same decision, for the same recorded reason, as
+ * `usage/types.ts`: a `.strict()` schema means the first field a NEWER cruxy
+ * writes makes an OLDER binary reject the line. For usage that silently lost
+ * accounting; here it would silently lose a user's CONVERSATION, which is
+ * strictly worse. Downgrading a CLI, or running two versions against one home
+ * directory, is ordinary — losing a session to it is not acceptable.
+ *
+ * `.passthrough()` also PRESERVES unknown keys rather than stripping them, so
+ * anything that reads and re-emits an event hands a newer CLI's fields back
+ * intact.
+ *
+ * The tradeoff accepted, identically: a typo'd key is no longer a parse error.
+ * Worth it — every field the code actually reads is still fully validated, and
+ * a malformed LINE is skipped rather than taking the session down (see
+ * `replay.ts`).
+ */
+// ── message shapes (mirrors @cruxy/sdk, validated on the way back in) ────────
+/**
+ * The SDK's content blocks, restated as schemas.
+ *
+ * These must round-trip EXACTLY. `tool_use` / `tool_result` pairing is
+ * load-bearing: the provider rejects a history where a `tool_use` has no
+ * matching `tool_result`, which is the entire reason `Session.findCut` walks
+ * back to a real user prompt before compacting. A replay that dropped, merged
+ * or reordered a block would produce a history that fails on the next turn —
+ * so nothing here is lossy, and unknown block types are preserved rather than
+ * filtered (a newer CLI's block must survive an older one reading the file).
+ */
+export const TextBlockSchema = z
+    .object({ type: z.literal("text"), text: z.string() })
+    .passthrough();
+export const ToolUseBlockSchema = z
+    .object({
+    type: z.literal("tool_use"),
+    id: z.string(),
+    name: z.string(),
+    input: z.unknown(),
+})
+    .passthrough();
+export const ToolResultBlockSchema = z
+    .object({
+    type: z.literal("tool_result"),
+    tool_use_id: z.string(),
+    content: z.string(),
+    is_error: z.boolean().optional(),
+})
+    .passthrough();
+/**
+ * A block of a kind this build knows, OR any other object carrying a string
+ * `type`. The fallback arm is deliberate: a newer cruxy that adds a block kind
+ * must not have its sessions truncated by an older one. The block is carried
+ * through untouched and handed back to the provider as-is.
+ */
+export const ContentBlockSchema = z.union([
+    TextBlockSchema,
+    ToolUseBlockSchema,
+    ToolResultBlockSchema,
+    z.object({ type: z.string() }).passthrough(),
+]);
+export const MessageSchema = z
+    .object({
+    role: z.enum(["user", "assistant"]),
+    content: z.union([z.string(), z.array(ContentBlockSchema)]),
+})
+    .passthrough();
+// ── events ───────────────────────────────────────────────────────────────────
+/** One declared workspace root, recorded so a resume can validate against it. */
+export const RootRefSchema = z
+    .object({ name: z.string(), path: z.string() })
+    .passthrough();
+/**
+ * The first line of every session file: everything needed to identify the
+ * session and to decide whether resuming it HERE is safe.
+ *
+ * `cwd` and `roots` are metadata, never restored. Resuming a session recorded
+ * in another directory would silently point a history full of file paths, diffs
+ * and tool results at an unrelated tree — so the resume path compares and warns
+ * loudly rather than quietly proceeding (see `replay.ts`/`resume.ts`).
+ */
+export const SessionMetaSchema = z
+    .object({
+    kind: z.literal("meta"),
+    version: z.literal(SESSION_FILE_VERSION),
+    sessionId: z.string(),
+    startedAt: z.string(),
+    /** The primary root at session start — the directory history refers to. */
+    cwd: z.string(),
+    /** Every declared root (C.26). Multi-root sessions key on the primary, so
+     * this is what makes the asymmetry visible rather than silently dropped. */
+    roots: z.array(RootRefSchema).default([]),
+    cliVersion: z.string().optional(),
+    provider: z.string().optional(),
+    model: z.string().optional(),
+})
+    .passthrough();
+/**
+ * Messages appended since the last event. The ONLY growth path — every turn's
+ * user prompt, assistant blocks and tool results arrive through here.
+ *
+ * `runId` is the CheckpointGate's run id for the turn (see `gate.ts`), NOT a
+ * second id minted here: `cruxy rollback <id>` and this log must agree on what
+ * a turn is, or the undo unit means two different things. It is absent when
+ * checkpoints are disabled — the only case where no run id exists at all.
+ */
+export const AppendEventSchema = z
+    .object({
+    kind: z.literal("append"),
+    at: z.string(),
+    runId: z.string().optional(),
+    messages: z.array(MessageSchema),
+})
+    .passthrough();
+/**
+ * A compaction: the oldest `replaced` messages were folded into `summary`
+ * (the synthetic user/assistant pair carrying `COMPACTION_MARKER`).
+ *
+ * Recording the COUNT plus the replacement — rather than rewriting the array —
+ * is what keeps the file append-only. The replaced messages remain earlier in
+ * the log, so the full conversation is still recoverable even though the model
+ * can no longer see it.
+ */
+export const CompactionEventSchema = z
+    .object({
+    kind: z.literal("compaction"),
+    at: z.string(),
+    runId: z.string().optional(),
+    /** How many messages from the head were folded away. */
+    replaced: z.number().int().nonnegative(),
+    /** What replaced them (the synthetic pair). */
+    summary: z.array(MessageSchema),
+})
+    .passthrough();
+/** `/clear`: history dropped, session kept. Replay resets to an empty array. */
+export const ClearEventSchema = z
+    .object({ kind: z.literal("clear"), at: z.string() })
+    .passthrough();
+/**
+ * `/plan` toggled. The last one wins on replay.
+ *
+ * Superseded by {@link SessionModeEventSchema} (P5 track 3) and still READ, never
+ * written: sessions recorded before modes existed carry these, and dropping the
+ * case would silently resume them in manual. Expand-contract — the new writer
+ * emits `mode`, the reader understands both, and a pre-P5 log keeps meaning what
+ * it meant.
+ */
+export const PlanModeEventSchema = z
+    .object({
+    kind: z.literal("plan-mode"),
+    at: z.string(),
+    enabled: z.boolean(),
+})
+    .passthrough();
+/**
+ * The session mode changed (P5 track 3). The last one wins on replay, exactly
+ * like the event it replaces.
+ *
+ * `mode` is a plain string here rather than an enum so an unknown value — a log
+ * written by a newer build that added a mode — parses instead of poisoning the
+ * whole line. The fold decides what to do with one it does not recognise.
+ */
+export const SessionModeEventSchema = z
+    .object({
+    kind: z.literal("mode"),
+    at: z.string(),
+    mode: z.string(),
+})
+    .passthrough();
+/**
+ * One turn's token usage, as the provider reported it. Summed on replay to
+ * restore `Session.usage`.
+ *
+ * This is a COPY, deliberately. `~/.cruxy/usage/runs.json` keeps only the last
+ * 50 runs (`usage/store.ts`), while sessions are kept indefinitely — so a
+ * session will routinely outlive its own usage records. Without this the
+ * restored `Session.usage` would silently read 0 for an older conversation.
+ * `runId` still points at the usage store for the richer per-tier/cost
+ * breakdown WHEN it is still there; nothing here assumes it is.
+ */
+export const UsageEventSchema = z
+    .object({
+    kind: z.literal("usage"),
+    at: z.string(),
+    runId: z.string().optional(),
+    inputTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+})
+    .passthrough();
+/** Every event, discriminated on `kind`. */
+export const SessionEventSchema = z.discriminatedUnion("kind", [
+    SessionMetaSchema,
+    AppendEventSchema,
+    CompactionEventSchema,
+    ClearEventSchema,
+    PlanModeEventSchema,
+    SessionModeEventSchema,
+    UsageEventSchema,
+]);

package/dist/subagent/orchestrator.js

@@ -437,6 +437,29 @@ class SubagentRenderer {
     }
     /** The plan executor owns the progress register (C.31) — never the child. */
     progress() { }
+    /**
+     * Same ownership rule for the plan checklist (P3): a child running its own
+     * task must never overwrite the parent's plan on screen.
+     */
+    setPlan() { }
+    /**
+     * Forwarded: a child's test run is a real outcome the user should see, unlike
+     * its assistant text. The label is not prefixed — the report carries the
+     * command it ran, which already identifies it.
+     */
+    /**
+     * NOT forwarded, deliberately. A subagent may run on a different tier from
+     * the main loop (C.30 routes by task class), and the parent's model panel and
+     * header describe the SESSION's tier. Forwarding would let a subagent's tier
+     * overwrite it and linger after the subagent finished — the header would
+     * report a tier the conversation is not running on.
+     */
+    servedRouting() {
+        // no-op
+    }
+    testResult(report) {
+        this.inner.testResult(report);
+    }
     toolLifecycle(event) {
         this.inner.toolLifecycle({
             ...event,

package/dist/testing/run-tests-tool.js

@@ -144,6 +144,14 @@ export function makeRunTestsTool(deps = {}) {
                 shell: ctx.config.shell,
             });
             budget.record(result.passed);
+            // The structured result goes to the renderer here, from the same object
+            // the payload below is built from — never from re-reading that payload.
+            try {
+                deps.onResult?.(result, resolved);
+            }
+            catch {
+                // A renderer problem is not a test-run problem.
+            }
             const payload = renderResult(result, resolved, {
                 run: result.passed ? 0 : budget.spent,
                 max,

package/dist/tools/registry.js

@@ -3,7 +3,7 @@ import { listFilesTool } from "./list-files.js";
 import { gitStatusTool } from "./git-status.js";
 import { readFileTool, writeFileTool, editFileTool, applyPatchTool, globTool, grepFilesTool, } from "./file/index.js";
 import { runCommandTool } from "./shell/index.js";
-import { makeRunTestsTool } from "../testing/run-tests-tool.js";
+import { makeRunTestsTool, } from "../testing/run-tests-tool.js";
 import { searchCodebaseTool } from "./search-codebase.js";
 import { listSkillsTool } from "./list-skills.js";
 import { loadSkillTool } from "./load-skill.js";
@@ -55,7 +55,7 @@ function toInputSchema(schema) {
     return json;
 }
 /** Build the default registry with every built-in tool registered. */
-export function buildDefaultRegistry() {
+export function buildDefaultRegistry(opts = {}) {
     const registry = new ToolRegistry();
     registry.register(listFilesTool);
     registry.register(readFileTool);
@@ -67,7 +67,7 @@ export function buildDefaultRegistry() {
     registry.register(gitStatusTool);
     registry.register(runCommandTool);
     // A fresh tool per registry — its iteration budget (C.13) is session-scoped.
-    registry.register(makeRunTestsTool());
+    registry.register(makeRunTestsTool(opts.onTestResult ? { onResult: opts.onTestResult } : {}));
     registry.register(searchCodebaseTool);
     registry.register(listSkillsTool);
     registry.register(loadSkillTool);

package/dist/tui/app.js

@@ -0,0 +1,385 @@
+import { DEFAULT_MODE, MODE_LABELS, modeAutoApproves, } from "../agent/index.js";
+import { completeLine } from "../components/autocomplete.js";
+import { SHARED_COMMANDS, SHARED_HELP, announceMode, dispatchCommand, } from "../cli/session-commands.js";
+import { selectList } from "../components/select.js";
+import { canOverlay, createKeyLease, createOverlayIO, } from "./overlay.js";
+import { openPalette } from "./palette.js";
+import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
+import { CLOSABLE_PANELS, columnOf, RAIL_PANELS, } from "./layout.js";
+import { COLUMN_LABELS, PANEL_LABELS } from "./panels.js";
+/**
+ * The TUI's input loop (P1) — the piece that replaces `repl.ts`'s readline
+ * loop. It owns exactly two things: the edit buffer and command dispatch.
+ * Everything visible is the renderer's; everything the agent does is the
+ * session's.
+ *
+ * The stdin discipline is inherited from the REPL for the same reason it
+ * existed there: while a turn runs, the approval prompt grabs stdin in raw mode
+ * through the shared `readSingleKey`. Two raw-mode readers on one stdin would
+ * contend, so this loop takes stdin only while collecting a line and RELEASES it
+ * (`restore()` in a `finally`) before `session.send` — the approval prompt then
+ * has uncontested ownership, exactly as with the per-line readline interface.
+ *
+ * P5 track 1 keeps that behaviour and changes what enforces it. The loop now
+ * reads through a {@link KeyLease} rather than a reader of its own: one reader
+ * for the whole session, refcounted, so releasing between lines still leaves
+ * raw mode (the count returns to zero, and the approval prompt's ownership is
+ * unchanged) while a modal opened DURING a read borrows the live reader instead
+ * of opening a second one. Release-before-send stops being the only thing
+ * standing between the TUI and two readers on one stdin.
+ */
+/**
+ * Every command the TUI completes on Tab — the shared set plus this shell's own
+ * panel commands (P5 track 5).
+ *
+ * This constant existed before and was consumed by NOTHING: exported from
+ * `tui/index.ts`, imported nowhere, while the TUI had no completion at all.
+ * It is wired to Tab now rather than deleted, because the thing it was reaching
+ * for — the REPL's readline completer, which the TUI cannot use — is real.
+ */
+export const TUI_COMMANDS = [
+    ...SHARED_COMMANDS,
+    "/close",
+    "/open",
+].sort();
+const HELP = [
+    "commands:",
+    ...SHARED_HELP,
+    "  /close <panel>   hide a panel (sidebar | context | model | git | tools)",
+    "                   or a whole column (rail = all four rail panels)",
+    "  /open <panel>    show a hidden panel",
+    "  Tab              complete a slash command",
+    "  Ctrl+K           open the command palette",
+    "  Shift+Tab        cycle mode (manual · auto-approve · plan · full-auto)",
+    "  Ctrl+D           leave cruxy",
+];
+/**
+ * Group names `/close` and `/open` accept beside individual panels. `rail` is
+ * the one that matters for compatibility: it is what P1 shipped and what users
+ * already have in their fingers, so it keeps working — as the whole stack.
+ */
+const PANEL_GROUPS = {
+    rail: RAIL_PANELS,
+};
+const emptyEditor = () => ({ text: "", cursor: 0 });
+/**
+ * Render the input row: mode chip, prompt, text, and a visible caret at the
+ * cursor. The caret is drawn rather than moved, because the frame owns the real
+ * cursor — it parks after the last painted row so a repaint can erase upward.
+ *
+ * The chip is shown for every mode EXCEPT `manual` (P5 track 4). Manual is the
+ * default and asks about everything, so a chip there would be noise on every
+ * session; the modes worth a permanent marker are the ones where the agent is
+ * doing something you did not individually agree to, and those must never be
+ * inferable only from what has already happened. `full-auto` and `auto-approve`
+ * carry the warning role rather than the muted one for the same reason.
+ */
+export function renderInput(editor, theme, mode = DEFAULT_MODE) {
+    const chip = mode === DEFAULT_MODE
+        ? ""
+        : `${modeAutoApproves(mode) ? theme.warning(`[${MODE_LABELS[mode]}]`) : theme.muted(`[${MODE_LABELS[mode]}]`)} `;
+    const prompt = `${chip}${theme.accent("cruxy")} ${theme.muted(theme.glyph.caret)} `;
+    const before = editor.text.slice(0, editor.cursor);
+    const at = editor.text.slice(editor.cursor, editor.cursor + 1);
+    const after = editor.text.slice(editor.cursor + 1);
+    const caret = at === "" ? theme.accent(theme.glyph.cursorBar) : theme.strong(at);
+    return prompt + before + caret + after;
+}
+/**
+ * Parse `/close git` → ["git"], `/close rail` → the four rail panels. Returns
+ * null when the argument is missing or unknown — never a guess, so a typo can
+ * not close something the user did not name.
+ */
+function panelArg(input, command) {
+    const arg = input.slice(command.length).trim().toLowerCase();
+    const group = PANEL_GROUPS[arg];
+    if (group)
+        return { label: arg, panels: group };
+    const match = CLOSABLE_PANELS.find((p) => p === arg);
+    return match ? { label: PANEL_LABELS[match], panels: [match] } : null;
+}
+/**
+ * Read one line from the TUI's input row. Takes raw stdin for the duration and
+ * always releases it. Resolves `null` on Ctrl+D / EOF.
+ */
+async function readLine(keys, renderer, hooks) {
+    const editor = emptyEditor();
+    const paint = () => renderer.setInput(renderInput(editor, renderer.theme, hooks.mode()));
+    paint();
+    keys.begin();
+    try {
+        for (;;) {
+            const key = await keys.read();
+            switch (key.kind) {
+                case "enter": {
+                    const text = editor.text;
+                    editor.text = "";
+                    editor.cursor = 0;
+                    paint();
+                    return text;
+                }
+                case "eof":
+                    return null;
+                case "ctrl-c":
+                    // A populated buffer: clear it (an escape hatch from a half-typed
+                    // line). An empty one: Ctrl-C means leave, same as the REPL.
+                    if (editor.text === "")
+                        return null;
+                    editor.text = "";
+                    editor.cursor = 0;
+                    paint();
+                    break;
+                case "backspace":
+                    if (editor.cursor > 0) {
+                        editor.text =
+                            editor.text.slice(0, editor.cursor - 1) +
+                                editor.text.slice(editor.cursor);
+                        editor.cursor--;
+                        paint();
+                    }
+                    break;
+                case "left":
+                    if (editor.cursor > 0) {
+                        editor.cursor--;
+                        paint();
+                    }
+                    break;
+                case "right":
+                    if (editor.cursor < editor.text.length) {
+                        editor.cursor++;
+                        paint();
+                    }
+                    break;
+                case "char":
+                    editor.text =
+                        editor.text.slice(0, editor.cursor) +
+                            key.char +
+                            editor.text.slice(editor.cursor);
+                    editor.cursor += key.char.length;
+                    paint();
+                    break;
+                case "tab": {
+                    // Complete a slash command in place (P5 track 5). Only the leading
+                    // word of a `/…` line completes — everything else is prose bound for
+                    // the model, and Tab must never mangle it. Completing REWRITES the
+                    // buffer and never submits: Enter stays the only trigger, exactly as
+                    // the REPL's readline completer behaves.
+                    const head = editor.text.slice(0, editor.cursor);
+                    if (head.startsWith("/") && !/\s/.test(head)) {
+                        const { line, suggestions } = completeLine(head, TUI_COMMANDS);
+                        if (suggestions.length > 1) {
+                            renderer.println(renderer.theme.muted(suggestions.join("  ")));
+                        }
+                        if (line !== head) {
+                            editor.text = line + editor.text.slice(editor.cursor);
+                            editor.cursor = line.length;
+                        }
+                        paint();
+                    }
+                    break;
+                }
+                case "ctrl-k": {
+                    // The command palette (P5 track 6). It runs on the SAME reader this
+                    // loop is holding — track 1's lease makes the nested claim a no-op —
+                    // and paints into the same frame, so the conversation stays behind it.
+                    const picked = await hooks.openPalette();
+                    if (picked !== null) {
+                        // Inserted at the cursor, not appended: the palette is reachable
+                        // mid-line, and a command pasted onto the end of a half-typed
+                        // sentence is not what anyone meant by it.
+                        editor.text =
+                            editor.text.slice(0, editor.cursor) +
+                                picked +
+                                editor.text.slice(editor.cursor);
+                        editor.cursor += picked.length;
+                    }
+                    // Repaint either way: the drawer coming down leaves rows to reclaim.
+                    paint();
+                    break;
+                }
+                case "shift-tab":
+                    // Cycle the mode WITHOUT disturbing the line being typed (P5 track 4).
+                    // Mode is a property of the session, not of the message — losing a
+                    // half-written prompt to a mode switch would make the binding one
+                    // people learn not to press.
+                    hooks.cycleMode();
+                    paint();
+                    break;
+                default:
+                    // escape / arrows up-down / ctrl-k: no binding yet, deliberately
+                    // inert rather than leaking a control char into the buffer.
+                    break;
+            }
+        }
+    }
+    finally {
+        keys.restore();
+    }
+}
+/** Render a failed turn into the conversation and carry on — never exit. */
+function printTurnError(renderer, err) {
+    const cruxy = fromUnknown(err);
+    const text = formatError(cruxy, {
+        verbose: isVerbose(),
+        color: shouldUseColor(process.stdout),
+    });
+    for (const line of text.split("\n"))
+        renderer.println(line);
+}
+/** Echo the submitted line into the conversation, the way the REPL echoes a turn. */
+function echoPrompt(renderer, text) {
+    const t = renderer.theme;
+    renderer.println(`${t.accent("cruxy")} ${t.muted(t.glyph.caret)} ${text}`);
+}
+/**
+ * Dispatch one submitted line. Returns `"exit"` when the loop should end,
+ * `null` to continue.
+ */
+async function dispatch(input, session, renderer, out, slashCommands, checkpoints, pick) {
+    const trimmed = input.trim();
+    if (trimmed === "")
+        return null;
+    // This shell's own commands first — they are about panels, which the REPL
+    // has none of.
+    if (trimmed === "/help") {
+        for (const line of HELP)
+            renderer.println(renderer.theme.muted(line));
+        renderer.println();
+        return null;
+    }
+    if (trimmed === "/close" || trimmed.startsWith("/close ")) {
+        handlePanel(trimmed, "/close", false, renderer);
+        return null;
+    }
+    if (trimmed === "/open" || trimmed.startsWith("/open ")) {
+        handlePanel(trimmed, "/open", true, renderer);
+        return null;
+    }
+    // Everything else is the SHARED implementation (P5 track 5). P1 forked this
+    // loop out of `repl.ts` and left every one of these behind — including
+    // `/plan`, which was then the only way to reach plan mode at all.
+    const outcome = await dispatchCommand(input, {
+        session,
+        out,
+        slashCommands,
+        tty: true, // the TUI only runs on a terminal
+        ...(pick ? { pick } : {}),
+    });
+    if (outcome.kind === "exit")
+        return "exit";
+    if (outcome.kind === "handled")
+        return null;
+    // A real turn. Assistant text streams into the main column through the
+    // renderer; the loop below owns nothing but input.
+    echoPrompt(renderer, outcome.text);
+    try {
+        checkpoints?.beginRun(outcome.text);
+        await session.send(outcome.text, renderer);
+    }
+    catch (err) {
+        printTurnError(renderer, err);
+    }
+    return null;
+}
+/** `/close <panel>` and `/open <panel>` share everything but the target state. */
+function handlePanel(input, command, open, renderer) {
+    const t = renderer.theme;
+    const target = panelArg(input, command);
+    if (target === null) {
+        const names = [...CLOSABLE_PANELS.map((p) => PANEL_LABELS[p]), "rail"].join(" | ");
+        renderer.println(t.muted(`usage: ${command} <${names}>`));
+        return;
+    }
+    const { label, panels } = target;
+    // A group counts as changed when ANY of its panels moved, so `/open rail`
+    // with one panel already open still opens the other three.
+    const changed = panels
+        .map((p) => renderer.setPanelOpen(p, open))
+        .some(Boolean);
+    if (!changed) {
+        renderer.println(t.muted(`${label} is already ${open ? "open" : "closed"}`));
+        return;
+    }
+    const verb = open ? "opened" : "closed";
+    const restore = open ? "/close" : "/open";
+    renderer.println(t.muted(`${label} ${verb} — ${restore} ${label} to undo`));
+    if (!open)
+        return;
+    // Opening a panel the screen cannot show must SAY so; silently painting
+    // nothing would read as a broken command. Width and height fail differently
+    // and are fixed differently, so they are reported separately rather than
+    // collapsed into one vague "doesn't fit".
+    const columns = renderer.droppedColumns();
+    const lost = columns.find((c) => panels.some((p) => columnOf(p) === c));
+    if (lost !== undefined) {
+        renderer.println(t.muted(`(not enough width for the ${COLUMN_LABELS[lost]} — widen the terminal)`));
+        return;
+    }
+    const short = renderer.droppedRailPanels();
+    if (panels.some((p) => p !== "sidebar" && short.includes(p))) {
+        renderer.println(t.muted(`(not enough height to show it yet — make the terminal taller)`));
+    }
+}
+/**
+ * Drive the TUI: paint the shell, then prompt → read → dispatch until the user
+ * leaves. `initialMessage` (from `cruxy "<message>"`) runs as the first turn
+ * before the first prompt, so the shell is already on screen while it streams.
+ */
+export async function runTui(session, renderer, opts = {}) {
+    const stdin = opts.stdin ?? process.stdin;
+    renderer.setInput(renderInput(emptyEditor(), renderer.theme, session.getMode()));
+    if (opts.initialMessage && opts.initialMessage.trim() !== "") {
+        const first = opts.initialMessage.trim();
+        echoPrompt(renderer, first);
+        try {
+            opts.checkpoints?.beginRun(first);
+            await session.send(first, renderer);
+        }
+        catch (err) {
+            printTurnError(renderer, err);
+        }
+    }
+    // One reader for the whole session, leased per line. Released before any turn
+    // runs — see the stdin note at the top of this file.
+    const lease = opts.lease ?? createKeyLease(stdin);
+    // The TUI's command output: committed into the conversation column. No
+    // width fitting — `main` reflows at paint time, so truncating here would
+    // clip a line the column was about to wrap correctly.
+    const out = {
+        print: (line = "") => renderer.println(line),
+        theme: renderer.theme,
+        fit: (line) => line,
+    };
+    const hooks = {
+        mode: () => session.getMode(),
+        cycleMode: () => announceMode(out, session.cycleMode()),
+        openPalette: () => openPalette(renderer, lease, opts.slashCommands ?? []),
+    };
+    // The TUI's picker (P6 track 1): an overlay drawer on the SAME reader this
+    // loop holds, exactly like the palette. Declines rather than painting into a
+    // terminal with no room for a drawer — a modal that renders nothing while
+    // still eating every keystroke is indistinguishable from a hang.
+    const pick = async (items, pickOpts) => {
+        if (!canOverlay(renderer))
+            return null;
+        const result = await selectList(items, {
+            title: pickOpts.title,
+            toLabel: pickOpts.toLabel,
+            ...(pickOpts.initialIndex === undefined
+                ? {}
+                : { initialIndex: pickOpts.initialIndex }),
+            // The drawer's budget, minus the title row and the key hint the
+            // component draws around the list.
+            maxVisible: Math.max(1, renderer.overlayRows() - 2),
+        }, createOverlayIO(renderer, lease));
+        return result.kind === "selected" ? result.value : null;
+    };
+    for (;;) {
+        const line = await readLine(lease.handle(), renderer, hooks);
+        if (line === null)
+            return "eof";
+        const outcome = await dispatch(line, session, renderer, out, opts.slashCommands ?? [], opts.checkpoints, pick);
+        if (outcome !== null)
+            return outcome;
+    }
+}