@cruxy/cli 1.2.1 → 1.4.0

package/dist/render/index.js

@@ -3,32 +3,58 @@ import { PlainRenderer } from "./plain-renderer.js";
 import { attachResize } from "./resize.js";
 import { ScreenReaderRenderer } from "./screen-reader-renderer.js";
 import { TtyRenderer } from "./tty-renderer.js";
-export { detectCapabilities, detectReducedMotion, resolveColumns, DEFAULT_COLUMNS, } from "./capabilities.js";
+// Imported from the concrete modules (not `../tui/index.js`) to keep the
+// factory's runtime graph narrow — the TUI's app loop is not pulled in here.
+import { TuiRenderer } from "../tui/renderer.js";
+import { GitStatusCache } from "../tui/git-status.js";
+import { ToolVersions } from "../tui/tool-versions.js";
+import { supportsTui } from "../tui/supports.js";
+export { detectCapabilities, detectReducedMotion, resolveColumns, resolveRows, DEFAULT_COLUMNS, DEFAULT_ROWS, } from "./capabilities.js";
 export { attachResize, processResizeSignal, } from "./resize.js";
 export { fit, fitMiddle, reflow, stripAnsi, visibleWidth, kvStack, MIN_VALUE_COLS, } from "./layout.js";
 export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, fitStatusLine, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
 export { createFrameClock, inTransition, intervalFrameTimer, spinnerGlyph, FRAME_INTERVAL_MS, TRANSITION_TICKS, } from "./motion.js";
-export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
+export { renderActionPreview, renderUnifiedDiff, PREVIEW_MAX_LINES, } from "./diff.js";
+export { changedSteps, planChecklist, statusMark, stepStatusLine, } from "./plan-view.js";
+export { formatDuration, testResultLines, MAX_LISTED_FAILURES, } from "./test-view.js";
 export { createStreamHighlighter, defaultLineHighlighter, } from "./highlight.js";
 export { PlainRenderer } from "./plain-renderer.js";
 export { ScreenReaderRenderer } from "./screen-reader-renderer.js";
 export { TtyRenderer } from "./tty-renderer.js";
 /**
- * Build the renderer for the detected environment (U.11 adds the first branch):
+ * Build the renderer for the detected environment (U.11 adds the screen-reader
+ * branch; P1 adds the TUI one):
  * - `screenReader` → the linear, worded {@link ScreenReaderRenderer}, regardless
  *   of cursor support (a screen-reader TTY must not get the live region);
+ * - else TUI requested *and* supported → the full-viewport {@link TuiRenderer};
  * - else cursor-safe → the managed-live-region {@link TtyRenderer} (static, no
  *   timer, when `reducedMotion`);
  * - else → the append-only {@link PlainRenderer} (pipes, CI, `TERM=dumb`).
  * Everything downstream talks to {@link StreamRenderer} and never re-probes.
  */
-export function createRenderer(out = process.stdout, err = process.stderr, env = process.env) {
-    const caps = detectCapabilities(out, env);
+export function createRenderer(out = process.stdout, err = process.stderr, env = process.env, opts = {}) {
+    const caps = detectCapabilities(out, env, opts.stdin);
     // Wire resize reactivity onto the one caps object before any surface reads
     // its width (U.12). A no-op for non-TTY streams; the live region subscribes.
     attachResize(caps, out, env);
     if (caps.screenReader)
         return new ScreenReaderRenderer(caps, out, err);
+    if (opts.tui && supportsTui(caps)) {
+        return new TuiRenderer(caps, out, {
+            headerRight: opts.headerRight,
+            // Constructed only on the TUI branch: the cache probes nothing until the
+            // renderer asks it to, so an unused one would still be a wasted object on
+            // every piped run.
+            ...(opts.gitCwd === undefined
+                ? {}
+                : { git: new GitStatusCache(opts.gitCwd) }),
+            ...(opts.provider === undefined ? {} : { provider: opts.provider }),
+            ...(opts.model === undefined ? {} : { model: opts.model }),
+            // Constructed, not started: `ToolVersions` probes nothing until the
+            // renderer paints the panel, so this costs an object and no subprocess.
+            tools: new ToolVersions(),
+        });
+    }
     return caps.cursor
         ? new TtyRenderer(caps, out)
         : new PlainRenderer(caps, out, err);

package/dist/render/plain-renderer.js

@@ -2,6 +2,8 @@ import { resolveTheme } from "../theme/index.js";
 import { createStreamPrinter } from "../cli/stream-print.js";
 import { renderActionPreview } from "./diff.js";
 import { ELAPSED_AFTER_MS, formatElapsed } from "./state.js";
+import { changedSteps, stepStatusLine } from "./plan-view.js";
+import { testResultLines } from "./test-view.js";
 /**
  * The append-only renderer for pipes, CI, and cursor-less terminals. Emits no
  * cursor-control sequences ever, and no color unless the capabilities say so
@@ -23,6 +25,8 @@ export class PlainRenderer {
     wroteInSegment = false;
     /** In-flight tool call (serial by contract) for the end-note duration. */
     toolStart = null;
+    /** Last plan snapshot committed, so `setPlan` prints only what changed. */
+    planSteps = [];
     constructor(caps, out, err) {
         this.caps = caps;
         this.out = out;
@@ -69,11 +73,43 @@ export class PlainRenderer {
             return;
     }
     progress(state) {
-        // The committed plan trail (C.31, via PromptIO) is the record in this
-        // medium; a live [i/n] prefix would just duplicate it line by line.
+        // `setPlan`'s committed trail is the record in this medium (C.31/P3); a
+        // live [i/n] prefix would just duplicate it line by line.
         if (state !== null)
             return;
     }
+    /**
+     * Commit one line per step whose status actually changed (P3). The whole list
+     * arrives on every transition, so without the diff this would reprint the
+     * entire plan once per step.
+     *
+     * `ScreenReaderRenderer` inherits this unchanged: the line is already a
+     * committed announcement, and its glyph table renders the status marks as
+     * words (`done 2. fix the assertion`), so there is nothing to special-case.
+     */
+    setPlan(steps) {
+        if (steps === null) {
+            this.planSteps = [];
+            return;
+        }
+        for (const step of changedSteps(this.planSteps, steps)) {
+            this.err.write(stepStatusLine(step, this.theme) + "\n");
+        }
+        this.planSteps = steps.map((s) => ({ ...s }));
+    }
+    /** Committed, to `err` with the rest of the chrome. */
+    /**
+     * Ignored: a served tier is standing state, not an event. Committing a line
+     * per request would be noise on an append-only surface, and the run's tier is
+     * already reported by `cruxy usage`.
+     */
+    servedRouting() {
+        // no-op
+    }
+    testResult(report) {
+        for (const line of testResultLines(report, this.theme))
+            this.err.write(line + "\n");
+    }
     toolLifecycle(event) {
         if (event.event === "start") {
             // Silent: the end note is the single durable line per call — a start

package/dist/render/plan-view.js

@@ -0,0 +1,108 @@
+import { fit } from "./layout.js";
+/**
+ * Rendering the executing plan (P3): the shared formatter behind
+ * {@link StreamRenderer.setPlan}, so the full-viewport checklist and the
+ * append-only trail draw the same step the same way.
+ *
+ * Pure data → string[], like `render/diff.ts` and `tui/layout.ts`. Meaning is
+ * carried by the glyph (○/◐/✓/✗), never by color alone, so NO_COLOR and
+ * screen-reader mode (whose glyph table words them) lose nothing.
+ */
+/** Status glyph for a step, colored when the theme colors. */
+export function statusMark(status, t) {
+    switch (status) {
+        case "pending":
+            return t.muted(t.glyph.pending);
+        case "running":
+            return t.accent(t.glyph.running);
+        case "done":
+            return t.success(t.glyph.success);
+        case "failed":
+            return t.danger(t.glyph.failure);
+    }
+}
+/** One step as a committed trail line: `✓ 2. fix the assertion`. */
+export function stepStatusLine(step, t) {
+    return `${statusMark(step.status, t)} ${t.strong(step.id + ".")} ${step.title}`;
+}
+/**
+ * The steps whose status differs between two snapshots — what an append-only
+ * medium must commit. `setPlan` re-sends the WHOLE list on every transition, so
+ * without this a trail renderer would reprint every step on every step.
+ *
+ * A step absent from `before` (a plan that grew, or the first call) counts as
+ * changed: its status has not been reported yet.
+ */
+export function changedSteps(before, after) {
+    const previous = new Map(before.map((s) => [s.id, s.status]));
+    return after.filter((s) => previous.get(s.id) !== s.status);
+}
+/** Index of the step a reader cares about: the running one, else the last
+ * finished one, so the window follows execution rather than pinning to the top. */
+function focusIndex(steps) {
+    const running = steps.findIndex((s) => s.status === "running");
+    if (running !== -1)
+        return running;
+    const lastSettled = steps.reduce((acc, s, i) => (s.status === "done" || s.status === "failed" ? i : acc), -1);
+    return lastSettled === -1 ? 0 : lastSettled;
+}
+/**
+ * The live checklist block, at most `maxRows` rows including its header.
+ *
+ * A plan longer than the room available is WINDOWED around the active step
+ * rather than truncated to its head: during execution the interesting rows are
+ * the ones near what is running. Hidden steps are counted in an explicit
+ * `↑ N more` / `↓ N more` marker — a silently clipped checklist would read as a
+ * complete one, which is exactly the lie the collapse markers in
+ * `render/diff.ts` exist to avoid.
+ */
+export function planChecklist(steps, t, maxRows = Infinity, width = Infinity) {
+    if (steps.length === 0)
+        return [];
+    const done = steps.filter((s) => s.status === "done").length;
+    const failed = steps.filter((s) => s.status === "failed").length;
+    const header = t.strong(`plan ${done}/${steps.length}${failed > 0 ? t.danger(` · ${failed} failed`) : ""}`);
+    const finish = (lines) => Number.isFinite(width)
+        ? lines.map((l) => fit(l, width, t.glyph.ellipsis))
+        : lines;
+    const more = (n, where) => t.muted(`${t.glyph.ellipsis} ${n} more ${where}`);
+    // The header always costs one row; `room` is what is left for steps AND any
+    // elision markers. Markers are part of the budget, not an overflow of it —
+    // getting that wrong is how a "max 2 rows" checklist renders 4.
+    const room = (Number.isFinite(maxRows) ? maxRows : Infinity) - 1;
+    if (room <= 0)
+        return finish([header]);
+    if (steps.length <= room)
+        return finish([header, ...steps.map((s) => stepStatusLine(s, t))]);
+    const centered = (size) => {
+        const start = Math.min(Math.max(0, focusIndex(steps) - Math.floor(size / 2)), steps.length - size);
+        return [start, start + size];
+    };
+    const markersFor = (start, end) => (start > 0 ? 1 : 0) + (end < steps.length ? 1 : 0);
+    // Take the largest window that still leaves room for the markers it actually
+    // needs. One marker is always needed here (something is elided by
+    // definition), so only two candidate sizes exist.
+    for (const size of [room - 1, room - 2]) {
+        if (size < 1)
+            continue;
+        const [start, end] = centered(size);
+        if (size + markersFor(start, end) > room)
+            continue;
+        return finish([
+            header,
+            ...(start > 0 ? [more(start, "above")] : []),
+            ...steps.slice(start, end).map((s) => stepStatusLine(s, t)),
+            ...(end < steps.length ? [more(steps.length - end, "below")] : []),
+        ]);
+    }
+    // Too tight for any window plus its markers. Keep the step that matters and
+    // one honest count, or — with a single row left — just the count. Never a
+    // silently clipped list.
+    return finish(room >= 2
+        ? [
+            header,
+            stepStatusLine(steps[focusIndex(steps)], t),
+            more(steps.length - 1, "hidden"),
+        ]
+        : [header, t.muted(`${t.glyph.ellipsis} ${steps.length} steps`)]);
+}

package/dist/render/resize.js

@@ -1,4 +1,4 @@
-import { resolveColumns } from "./capabilities.js";
+import { resolveColumns, resolveRows } from "./capabilities.js";
 /** The real signal: Node emits `SIGWINCH` on the process when a TTY resizes. */
 export const processResizeSignal = {
     on(listener) {
@@ -24,9 +24,14 @@ export function attachResize(caps, stream = process.stdout, env = process.env, s
     let off = null;
     const onSignal = () => {
         const next = resolveColumns(stream, env);
-        if (next === caps.width)
+        const nextRows = resolveRows(stream, env);
+        // Height moves independently of width — a vertical-only drag changes rows
+        // and not columns, and a full-viewport surface must still reflow for it.
+        // So both are refreshed, and either change notifies.
+        if (next === caps.width && nextRows === caps.height)
             return;
         caps.width = next; // the single source stays current — no second copy.
+        caps.height = nextRows;
         for (const l of [...listeners])
             l(next);
     };

package/dist/render/status-view.js

@@ -0,0 +1,66 @@
+import { fit } from "./layout.js";
+import { formatTokens } from "./state.js";
+/** `key  value`, aligned on a fixed gutter so the column is scannable. */
+function row(key, value, t) {
+    return `  ${t.muted(key.padEnd(11))} ${value}`;
+}
+/** The full `/status` block as lines to print. */
+export function sessionStatusLines(status, t, width = Infinity) {
+    const lines = [t.heading("status")];
+    lines.push(row("session", `${status.sessionId.slice(0, 8)} ${t.muted(`· ${status.turns} turn${status.turns === 1 ? "" : "s"}`)}`, t));
+    // The mode leads the safety half, and carries its description rather than its
+    // name alone. The objection that removed the auto-approve config flag was that
+    // it disarmed the gate with nothing on screen saying so; a status screen
+    // reporting "mode: full-auto" and no more would repeat that in miniature.
+    lines.push(row("mode", `${t.strong(status.mode)} ${t.muted(`— ${status.modeDescription}`)}`, t));
+    const model = status.model === undefined
+        ? t.muted(`${status.provider} (no cruxy tiers)`)
+        : status.servedTier === undefined || status.servedTier === status.model
+            ? `${status.provider}/${status.servedTier ?? status.model}`
+            : `${status.provider}/${status.model} ${t.glyph.arrow} ${status.servedTier}`;
+    lines.push(row("model", model, t));
+    if (status.context) {
+        const { used, total, compactAt } = status.context;
+        lines.push(row("context", `${t.strong(`~${formatTokens(used)} / ${formatTokens(total)} budget`)} ` +
+            t.muted(`· compacts above ~${formatTokens(compactAt)}`), t));
+    }
+    // A sandbox that is ON but whose runtime we cannot name is reported as on
+    // WITHOUT a name, rather than omitted — the safety-relevant half is that it
+    // is engaged at all.
+    lines.push(row("sandbox", status.sandboxEnabled
+        ? t.warning(status.sandboxRuntime ?? "on")
+        : t.muted("off — commands run on this host"), t));
+    lines.push(row("checkpoints", status.checkpoints
+        ? t.muted("on — `cruxy rollback` can undo a run's file changes")
+        : t.warning("off — file changes are not restorable"), t));
+    if (status.jobs) {
+        const { total, running, needingApproval } = status.jobs;
+        const detail = total === 0
+            ? t.muted("none this session")
+            : `${total} · ${running} running` +
+                (needingApproval > 0
+                    ? t.warning(` · ${needingApproval} awaiting approval`)
+                    : "");
+        lines.push(row("jobs", detail, t));
+    }
+    lines.push(row("tools", t.muted(`${status.tools} available to the model`), t));
+    // Roots last: one line each, so a multi-root session shows which repo each
+    // change lands in — the fact the startup banner states once and then loses.
+    lines.push("");
+    lines.push(t.strong(status.roots.length === 1 ? "root" : "roots"));
+    for (const r of status.roots) {
+        const mark = r.primary ? t.accent(t.glyph.pointer) : " ";
+        const git = r.git === undefined
+            ? t.muted(`checking${t.glyph.ellipsis}`)
+            : r.git === null
+                ? t.muted("not a git repo")
+                : `${t.strong(r.git.branch)} ${r.git.changed > 0
+                    ? t.warning(`${r.git.changed} changed`)
+                    : t.success("clean")}`;
+        lines.push(`${mark} ${r.name.padEnd(12)} ${git}`);
+        lines.push(`  ${t.muted(r.path)}`);
+    }
+    return Number.isFinite(width)
+        ? lines.map((l) => fit(l, width, t.glyph.ellipsis))
+        : lines;
+}

package/dist/render/test-view.js

@@ -0,0 +1,89 @@
+import { fit } from "./layout.js";
+/**
+ * Rendering a test run (P3): the shared formatter behind
+ * {@link StreamRenderer.testResult}, so every medium reports the same run the
+ * same way.
+ *
+ * The honesty rules are `testing/`'s, carried through rather than re-derived:
+ * `passed` comes from the exit code and nothing else, `total` exists only when
+ * a parser confidently extracted it, and `failures` can be empty even for a
+ * failing run. So this NEVER computes a count it was not given — no
+ * `total - failures.length` passed-count, no "1 test failed" inferred from a
+ * non-zero exit. When the numbers are absent it reports the outcome and the
+ * duration, and says that it could not recognize the details.
+ */
+/** Failures listed before the rest are summarized. */
+export const MAX_LISTED_FAILURES = 5;
+/** `4.2s`, `380ms` — a measured duration, never estimated. */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    const seconds = ms / 1000;
+    return seconds < 10 ? `${seconds.toFixed(1)}s` : `${Math.round(seconds)}s`;
+}
+/**
+ * The count clause, or "" when nothing countable was extracted.
+ *
+ * `total` is the only number a parser is allowed to produce, and `failures` is
+ * a best-effort list — so "N of M failed" is claimable only when both are
+ * present, and a bare failure list is reported as "N failures" without implying
+ * it is exhaustive.
+ */
+function counts(report, t) {
+    const failed = report.failures.length;
+    if (report.total !== undefined) {
+        if (report.passed)
+            return t.muted(`${report.total} tests`);
+        if (failed > 0)
+            return t.danger(`${failed} of ${report.total} failed`);
+        return t.muted(`${report.total} tests`);
+    }
+    if (!report.passed && failed > 0)
+        return t.danger(`${failed} failure${failed === 1 ? "" : "s"}`);
+    return "";
+}
+/** One failure: its name, then `file:line` when the parser recognized them. */
+function failureLine(failure, t) {
+    const where = failure.file === undefined
+        ? ""
+        : ` ${t.muted(failure.file + (failure.line === undefined ? "" : `:${failure.line}`))}`;
+    return `  ${t.danger(t.glyph.failure)} ${failure.name}${where}`;
+}
+/**
+ * A test run as committed lines: a headline, then the recognized failures.
+ *
+ * This is committed output, not live state — a run is an event that happened,
+ * so every medium keeps it rather than redrawing it.
+ */
+export function testResultLines(report, t, width = Infinity) {
+    const mark = report.passed
+        ? t.success(t.glyph.success)
+        : t.danger(t.glyph.failure);
+    const headline = report.passed
+        ? t.success("tests passed")
+        : t.danger("tests failed");
+    const parts = [
+        counts(report, t),
+        t.muted(formatDuration(report.durationMs)),
+        t.muted(report.command),
+    ].filter((p) => p !== "");
+    const lines = [
+        `${mark} ${headline} ${t.muted(t.glyph.sep)} ${parts.join(t.muted(` ${t.glyph.sep} `))}`,
+    ];
+    for (const failure of report.failures.slice(0, MAX_LISTED_FAILURES))
+        lines.push(failureLine(failure, t));
+    if (report.failures.length > MAX_LISTED_FAILURES) {
+        lines.push(t.muted(`  ${t.glyph.ellipsis} ${report.failures.length - MAX_LISTED_FAILURES} more`));
+    }
+    // Say what is NOT known, rather than letting a bare "tests failed" imply the
+    // details were simply absent from the run.
+    if (!report.passed && report.failures.length === 0) {
+        lines.push(t.muted("  no individual failures were recognized in the output"));
+    }
+    if (report.outputTruncated && report.failures.length > 0) {
+        lines.push(t.muted("  output was capped — the failures above may be incomplete"));
+    }
+    return Number.isFinite(width)
+        ? lines.map((l) => fit(l, width, t.glyph.ellipsis))
+        : lines;
+}

package/dist/render/tty-renderer.js

@@ -5,6 +5,8 @@ import { createStreamHighlighter, } from "./highlight.js";
 import { fit } from "./layout.js";
 import { createFrameClock, inTransition, spinnerGlyph, } from "./motion.js";
 import { ELAPSED_AFTER_MS, fitStatusLine, formatElapsed, phaseIdentity, } from "./state.js";
+import { changedSteps, stepStatusLine } from "./plan-view.js";
+import { testResultLines } from "./test-view.js";
 /** Erase the current line and return the cursor to column 0. */
 const CLEAR_LINE = "\r\x1b[2K";
 /**
@@ -52,6 +54,8 @@ export class TtyRenderer {
     rawStatus = null;
     phase = null;
     progressState = null;
+    /** Last plan snapshot committed, so `setPlan` notes only what changed. */
+    planSteps = [];
     /** When the current phase *identity* began — drives honest elapsed display. */
     phaseStartedAt = 0;
     /** In-flight tool call (serial by contract) for end-note duration. */
@@ -277,6 +281,42 @@ export class TtyRenderer {
         this.progressState = state;
         this.refresh();
     }
+    /**
+     * Commit one trail line per step whose status actually changed (P3). This
+     * medium owns a single live line, which `progress` already uses for the
+     * `[i/n] title` prefix — the checklist itself belongs in committed output,
+     * exactly where the plan executor used to write it through the approval io.
+     *
+     * `note` is the right sink: it hides the live line, writes, and lets the next
+     * transition redraw — so a step line can never land inside the managed row.
+     */
+    setPlan(steps) {
+        if (this.closed)
+            return;
+        if (steps === null) {
+            this.planSteps = [];
+            return;
+        }
+        for (const step of changedSteps(this.planSteps, steps)) {
+            this.note(stepStatusLine(step, this.theme));
+        }
+        this.planSteps = steps.map((s) => ({ ...s }));
+    }
+    /** Committed via `note`, so the live line yields before the block lands. */
+    /**
+     * Ignored: a served tier is standing state, not an event. Committing a line
+     * per request would be noise on an append-only surface, and the run's tier is
+     * already reported by `cruxy usage`.
+     */
+    servedRouting() {
+        // no-op
+    }
+    testResult(report) {
+        if (this.closed)
+            return;
+        for (const line of testResultLines(report, this.theme, this.caps.width))
+            this.note(line);
+    }
     toolLifecycle(event) {
         if (this.closed)
             return;

package/dist/routing/index.js

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export { ConfigRouter, DEFAULT_TIER, routerForConfig, resolveTaskModel, } from "./router.js";
+export { MODEL_CHOICES, SessionModel, describeModelChoice, parseModelChoice, } from "./session-model.js";
 // `resolve.ts` (tier → wire model-id) is deliberately NOT re-exported: the
 // mapping is internal to routing, so it can never be reached from a user-facing
 // render path (the internal-mapping-isolation guarantee, U.8).

package/dist/routing/router.js

@@ -1,6 +1,7 @@
 import { MODEL_TIERS } from "../brand/voice.js";
 import { routingTierUnavailable } from "../errors/index.js";
 import { resolveModelId } from "./resolve.js";
+import { AUTO_MODEL, } from "./types.js";
 /**
  * The tier a config resolves to when nothing else pins one down — mirrors the
  * gateway's `auto` fallback (`AUTO_FALLBACK_TIER` in the SDK), so an unrouted
@@ -73,12 +74,20 @@ export function routerForConfig(config) {
     });
 }
 /**
- * Resolve a declared task class to `{ tier, model }`: the tier for honest
- * surfacing (the U.4 state line), the wire model id for the request. The model
- * id comes from the internal {@link resolveModelId} — callers never touch that
+ * Resolve a declared task class to the wire model for the request, plus the tier
+ * for honest surfacing (the U.4 state line) when there is one. The model id
+ * comes from the internal {@link resolveModelId} — callers never touch that
  * mapping directly, so it stays the single source of truth.
+ *
+ * `tier` is ABSENT exactly when the router declined and the request is going out
+ * as {@link AUTO_MODEL}: no tier has been chosen client-side, so there is
+ * nothing honest to put on the status line until the gateway's opening frame
+ * says what it actually served. Absent is the whole point — a fabricated
+ * "probably vaani" here is precisely the claim `auto` cannot support.
  */
 export function resolveTaskModel(router, taskClass) {
     const tier = router.select(taskClass);
-    return { tier, model: resolveModelId(tier) };
+    return tier === null
+        ? { model: AUTO_MODEL }
+        : { tier, model: resolveModelId(tier) };
 }

package/dist/routing/session-model.js

@@ -0,0 +1,109 @@
+import { MODEL_TIERS } from "../brand/voice.js";
+import { multiplierForTier } from "../usage/weighted.js";
+import { AUTO_MODEL } from "./types.js";
+/**
+ * Everything `/model` offers, in the order it lists them. `auto` leads because
+ * it is the default and because it is the only entry that is not a tier — a
+ * list that buried it among the three would read as a four-tier menu.
+ */
+export const MODEL_CHOICES = [
+    AUTO_MODEL,
+    ...MODEL_TIERS,
+];
+/** Parse a user-typed model name, or `null` — never a guess, never a nearest match. */
+export function parseModelChoice(text) {
+    const want = text.trim().toLowerCase();
+    return MODEL_CHOICES.includes(want)
+        ? want
+        : null;
+}
+/**
+ * One line describing a choice, for the picker and for `/model` with no picker.
+ *
+ * THE ONLY THING SAID ABOUT A TIER IS ITS WEIGHT, and that is deliberate. cruxy
+ * publishes no capability ordering for `kavi`/`vaani`/`mira` — nothing in this
+ * codebase knows which is "smarter" — so a description like "fastest" or "best
+ * for hard problems" would be invented at the exact moment a user is deciding
+ * on it. The weighted multiplier is a real, checkable number this CLI already
+ * meters with (`TIER_MULTIPLIERS`, mirrored from the gateway's budget config),
+ * so it is what the picker says. A tier this build has no multiplier for gets no
+ * claim at all rather than a made-up one.
+ */
+export function describeModelChoice(choice) {
+    if (choice === AUTO_MODEL) {
+        return "the gateway picks a tier per request (not a tier itself)";
+    }
+    const multiplier = multiplierForTier(choice);
+    return multiplier === undefined
+        ? "a routing tier"
+        : `a routing tier · ${multiplier}× weighted`;
+}
+/**
+ * The session's model choice, and the router every part of the session selects
+ * through.
+ */
+export class SessionModel {
+    choice;
+    base;
+    listeners = new Set();
+    /**
+     * @param initial the starting choice — `config.model.model` when it names one
+     *                of {@link MODEL_CHOICES}, else `auto`.
+     * @param base    the config-driven router (`routing.default` / `routing.map`),
+     *                or null when the user configured none. Consulted ONLY while
+     *                the choice is `auto`: a tier picked at runtime is an explicit
+     *                instruction for this session and outranks a config table, the
+     *                same precedence a CLI flag has over a config file.
+     */
+    constructor(initial, base = null) {
+        this.choice = initial;
+        this.base = base;
+    }
+    /** The current choice. The ONE read every surface makes. */
+    current() {
+        return this.choice;
+    }
+    /** Whether a config routing table is in play — so `/model` can say when a pick overrides it. */
+    get hasRoutingTable() {
+        return this.base !== null;
+    }
+    /**
+     * Adopt a new choice. Returns whether anything changed, so a caller can stay
+     * quiet about a no-op rather than announcing a switch that did not happen.
+     * Listeners fire only on a real change.
+     */
+    set(choice) {
+        if (choice === this.choice)
+            return false;
+        this.choice = choice;
+        for (const listener of this.listeners)
+            listener();
+        return true;
+    }
+    /**
+     * Subscribe to changes; returns the unsubscribe. The renderer uses this to
+     * drop the served tier the moment the choice moves — see the note on
+     * `TuiRenderer.attachModel`.
+     */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * A pinned tier wins for every task class. `auto` defers to the config table
+     * when there is one (unchanged C.30 behaviour) and otherwise declines, which
+     * sends the request out as `auto` for the gateway to route.
+     *
+     * A pinned tier deliberately flattens the per-task map. The user named one
+     * model for this session; honouring `routing.map` underneath would quietly
+     * send some of their work somewhere else, which is the silent-substitution
+     * failure `ConfigRouter` already refuses to make.
+     */
+    select(taskClass) {
+        if (this.choice !== AUTO_MODEL)
+            return this.choice;
+        return this.base === null ? null : this.base.select(taskClass);
+    }
+}

package/dist/routing/types.js

@@ -25,3 +25,17 @@ export const TASK_CLASSES = [
     /** Context compaction / summarization. */
     "summarize",
 ];
+/**
+ * The server-routing sentinel: a valid `model.model` (and cruxy's default), but
+ * deliberately **not** a {@link Tier} and never a member of `MODEL_TIERS`.
+ *
+ * The distinction is load-bearing rather than pedantic. A tier names one model
+ * for the whole run, fixed before `provider.stream` opens. `auto` names no model
+ * at all — the gateway resolves it PER REQUEST and may downgrade it under budget
+ * pressure, which is why the served tier arrives on the stream's opening frame
+ * and why `auto` can never be reported as "the tier this run used". Anything
+ * that shows a model choice has to say which of the two it is holding; a picker
+ * that listed `auto` alongside the tiers as though it were a fourth one would be
+ * asserting a fixed model where there is none.
+ */
+export const AUTO_MODEL = "auto";