@cruxy/cli 1.2.0 → 1.3.0

package/dist/config/project.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { PROJECT_INSTRUCTION_FILENAMES } from "../constants.js";
 /** Cap on instruction file size; the rest is dropped with a notice. */
@@ -34,3 +34,55 @@ export function loadProjectInstructions(cwd) {
     }
     return null;
 }
+/**
+ * The starting `CRUXY.md` (P6 track 4).
+ *
+ * Deliberately a SKELETON with prompts rather than filled-in guesses. cruxy
+ * cannot know this project's conventions at scaffold time, and a template that
+ * asserted some would be injected into every subsequent turn's system prompt as
+ * though the user had written it — instructions the agent follows and nobody
+ * chose. Empty headings ask; invented content misleads.
+ */
+export const PROJECT_INSTRUCTIONS_TEMPLATE = `# Project instructions for cruxy
+
+These notes are loaded into cruxy's context on every run. Keep them short and
+high-signal — conventions, where things live, how to build and test.
+
+## Conventions
+
+- (e.g. language, style, naming rules the agent should follow)
+
+## Build & test
+
+- (e.g. how to install deps, run the app, run the test suite)
+
+## Gotchas
+
+- (e.g. anything non-obvious about this codebase)
+`;
+/**
+ * Write the starter `CRUXY.md` into `cwd`, unless project instructions already
+ * exist there.
+ *
+ * NEVER OVERWRITES, and the check is {@link loadProjectInstructions} rather than
+ * a bare `existsSync("CRUXY.md")` — a project whose instructions live in
+ * `AGENTS.md` already has them, and scaffolding a second file beside it would
+ * create two sources for one thing where the loader honours only the first.
+ *
+ * Extracted from the onboarding scaffold step (P6 track 4) so `/init` and
+ * `cruxy init` write the same file. The step's own y/N prompt and IO stay in
+ * `onboarding/steps.ts`, which is the part that genuinely differs between an
+ * onboarding flow and a slash command.
+ */
+export function scaffoldProjectInstructions(cwd) {
+    if (loadProjectInstructions(cwd) !== null)
+        return { kind: "exists" };
+    const file = join(cwd, PROJECT_INSTRUCTION_FILENAMES[0]);
+    try {
+        writeFileSync(file, PROJECT_INSTRUCTIONS_TEMPLATE, "utf8");
+    }
+    catch (err) {
+        return { kind: "failed", message: err.message };
+    }
+    return { kind: "written", file };
+}

package/dist/config/schema.js

@@ -49,8 +49,14 @@ export const AgentConfigSchema = z
      * cumulative across turns.
      */
     maxTokensPerTurn: z.number().int().nonnegative().default(0),
-    /** Skip per-action confirmation prompts. */
-    autoApprove: z.boolean().default(false),
+    // `autoApprove` used to sit here (P5 track 3 removed it). It had ZERO
+    // consumers — nothing in the codebase ever read it — while promising to
+    // "skip per-action confirmation prompts", and `ApprovalConfigSchema` below
+    // stated in the same file that no such mode exists. A flag on disk also
+    // disarms every approval in every session that loads it, with nothing on
+    // screen to say so. Auto-approve is now a runtime SESSION MODE
+    // (`agent/mode.ts`): chosen in the session it affects, shown while active,
+    // gone when the session ends.
     /** Plan mode: propose a plan for approval before executing (C.31, opt-in). */
     planMode: z.boolean().default(false),
 })
@@ -120,9 +126,13 @@ export const ContextConfigSchema = z
     .strict();
 /**
  * How tool-action approval is resolved. Only `prompt` exists: ask interactively
- * and **deny by default** when non-interactive. There is deliberately no
- * auto-approve / skip mode — the policy seam for a future CI mode lives in
- * `src/approval` (see U.3), not behind a footgun flag.
+ * and **deny by default** when non-interactive.
+ *
+ * There is still deliberately no auto-approve mode HERE, and that is the point
+ * this schema has always made: not that unattended execution is forbidden, but
+ * that it must not be armed from a file. It is a runtime session mode
+ * (`agent/mode.ts`) reached through the policy seam in `src/approval` — chosen
+ * in the session it affects and visible the whole time it is on.
  */
 export const ApprovalConfigSchema = z
     .object({
@@ -436,7 +446,13 @@ export const LspConfigSchema = z
     maxResults: z.number().int().positive().default(100),
 })
     .strict();
-/** A per-tier price, in the user's own currency, PER MILLION TOKENS (C.22). */
+/**
+ * RETIRED (C.22): a per-tier price, in the user's own currency, PER MILLION
+ * TOKENS. Nothing reads it. Kept only so `usage.prices` still VALIDATES — see
+ * {@link UsageConfigSchema}.
+ *
+ * @deprecated cost comes from the gateway now; delete `usage.prices` from config.
+ */
 export const TierPriceSchema = z
     .object({
     /** Price per 1,000,000 input tokens. */
@@ -447,22 +463,39 @@ export const TierPriceSchema = z
     .strict();
 /**
  * Usage telemetry + cost tracking (C.22): LOCAL usage accounting only — nothing
- * here is ever transmitted. Costs are opt-in and honest: prices are per-TIER and
- * per-million-tokens, configured by the user; with none set, tokens are shown
- * and cost is omitted (cruxy ships no bundled price table). The `prices` keys are
- * the fixed {@link MODEL_TIERS}, so an upstream model name can never appear here
- * (U.8 gag holds by construction) and a mistyped tier is rejected at config load.
+ * here is ever transmitted.
+ *
+ * `currency` and `prices` are RETIRED and read by nothing. They modelled a
+ * per-million-token cost basis that no cruxy subscriber is billed on: the
+ * gateway meters a weighted token pool and quotes its own cost per request, and
+ * `cruxy usage` now shows both of those instead of arithmetic over a number the
+ * user typed in.
+ *
+ * They are still ACCEPTED, and deliberately so. This schema is `.strict()` and
+ * `loadConfig` turns any parse failure into a hard error, so deleting the keys
+ * would mean every user who had set them gets a CLI that refuses to start until
+ * they hand-edit a file — a broken binary as the punishment for having used a
+ * documented feature. Tolerating a dead key costs nothing; rejecting it costs
+ * the whole tool. `cruxy usage` tells anyone who still has them set that they no
+ * longer do anything, which is the part that actually needed saying.
+ *
+ * Both are now `.optional()` with NO default, so a freshly-initialized config
+ * doesn't write retired keys into a new file — absent is the new normal, present
+ * is the tolerated legacy.
  */
 export const UsageConfigSchema = z
     .object({
     /** Master switch. When false, no usage is collected, persisted, or shown. */
     enabled: z.boolean().default(true),
-    /** Currency label to prefix costs with (e.g. "$", "€"). Empty ⇒ no symbol is
-     * assumed — a bare number is shown, since the user configured the prices. */
-    currency: z.string().default(""),
+    /**
+     * @deprecated retired, unread. Cost is shown in the gateway's own currency.
+     */
+    currency: z.string().optional(),
     /** How many past runs to keep in the store; older ones are pruned oldest-first. */
     retention: z.number().int().positive().default(50),
-    /** Per-tier prices. Any tier omitted is simply unpriced (cost omitted for it). */
+    /**
+     * @deprecated retired, unread. Cost comes from the gateway per request.
+     */
     prices: z
         .object({
         kavi: TierPriceSchema.optional(),
@@ -470,7 +503,7 @@ export const UsageConfigSchema = z
         mira: TierPriceSchema.optional(),
     })
         .strict()
-        .default({}),
+        .optional(),
 })
     .strict();
 /**

package/dist/jobs/log-renderer.js

@@ -1,4 +1,5 @@
 import { themeForColor } from "../theme/index.js";
+import { changedSteps } from "../render/plan-view.js";
 /** Non-terminal capabilities: a background job renders to NOTHING on screen. */
 const OFFSCREEN_CAPS = {
     tty: false,
@@ -8,7 +9,12 @@ const OFFSCREEN_CAPS = {
     reducedMotion: true,
     screenReader: false,
     unicode: true,
+    // No stdin and no screen: a job is never interactive and never repaints, so
+    // both input-axis flags are false regardless of what the foreground has.
+    stdinTty: false,
+    interactive: false,
     width: 80,
+    height: 24,
 };
 /**
  * A {@link StreamRenderer} for a background job (C.28) that captures activity into
@@ -26,6 +32,8 @@ export class JobLogRenderer {
     caps = OFFSCREEN_CAPS;
     theme = themeForColor(false);
     pending = "";
+    /** Last plan snapshot logged, so `setPlan` records only what changed. */
+    planSteps = [];
     constructor(sink) {
         this.sink = sink;
     }
@@ -51,6 +59,14 @@ export class JobLogRenderer {
     note(text) {
         this.sink("out", text);
     }
+    /**
+     * Ignored: a job log is an append-only transcript, and a served tier is
+     * standing state rather than an event. The run's tier is recorded by the
+     * usage store, which is where a job's accounting is read from.
+     */
+    servedRouting() {
+        // no-op
+    }
     toolLifecycle(event) {
         if (event.event !== "end")
             return; // only the committed outcome is log-worthy
@@ -60,6 +76,37 @@ export class JobLogRenderer {
     endTurn() {
         this.endSegment();
     }
+    /**
+     * Plan steps are committed outcomes, so a background job's log records them —
+     * one line per step whose status actually changed (the whole list arrives on
+     * every transition). Status is a word, not a glyph, matching this log's
+     * `[ok]`/`[fail]` style: nothing here is a terminal, so a themed mark would
+     * only add bytes `cruxy logs` has to strip.
+     */
+    setPlan(steps) {
+        if (steps === null) {
+            this.planSteps = [];
+            return;
+        }
+        for (const step of changedSteps(this.planSteps, steps)) {
+            this.sink(step.status === "failed" ? "err" : "out", `[${step.status}] ${step.id}. ${step.title}`);
+        }
+        this.planSteps = steps.map((s) => ({ ...s }));
+    }
+    /**
+     * A job's test run is exactly the kind of outcome `cruxy logs` exists to
+     * show. Plain text, no theme glyphs, matching this log's `[ok]`/`[fail]`
+     * style — and no count this renderer was not given.
+     */
+    testResult(report) {
+        const counted = report.total !== undefined
+            ? ` ${report.failures.length}/${report.total} failed`
+            : "";
+        this.sink(report.passed ? "out" : "err", `[${report.passed ? "tests ok" : "tests failed"}]${report.passed ? "" : counted} ${report.command} (${Math.round(report.durationMs)}ms)`);
+        for (const f of report.failures) {
+            this.sink("err", `  ${f.name}${f.file === undefined ? "" : ` ${f.file}${f.line === undefined ? "" : `:${f.line}`}`}`);
+        }
+    }
     // Transient decor / previews have no place in an append-only job log.
     preview() { }
     status() { }

package/dist/onboarding/steps.js

@@ -1,8 +1,6 @@
-import { writeFileSync } from "node:fs";
-import { join } from "node:path";
 import { themeForColor } from "../theme/index.js";
 import { CREATE_KEY_URL } from "../constants.js";
-import { loadProjectInstructions } from "../config/index.js";
+import { loadProjectInstructions, scaffoldProjectInstructions, } from "../config/index.js";
 /**
  * The individual onboarding steps (U.6). Each returns a {@link StepResult} and
  * never throws across its boundary; the secret is read masked and is never echoed
@@ -45,26 +43,14 @@ export async function acquireKeyStep(io, deps, provider) {
     }
     return { status: "failed", message: "key rejected after 3 attempts" };
 }
-const CRUXY_MD_TEMPLATE = `# Project instructions for cruxy
-
-These notes are loaded into cruxy's context on every run. Keep them short and
-high-signal — conventions, where things live, how to build and test.
-
-## Conventions
-
-- (e.g. language, style, naming rules the agent should follow)
-
-## Build & test
-
-- (e.g. how to install deps, run the app, run the test suite)
-
-## Gotchas
-
-- (e.g. anything non-obvious about this codebase)
-`;
 /**
  * Offer to scaffold a project `CRUXY.md`. Skipped silently when one already
  * exists (or `AGENTS.md`); otherwise a `y` confirmation writes the template.
+ *
+ * The template and the write moved to `config/project.ts` (P6 track 4) so
+ * `/init` writes the same file. What stays here is the part that genuinely
+ * differs between an onboarding flow and a slash command: the y/N prompt and
+ * the IO it is drawn on.
  */
 export async function scaffoldStep(io, cwd) {
     const col = c(io);
@@ -76,8 +62,13 @@ export async function scaffoldStep(io, cwd) {
     io.write("\n");
     if (key !== "y")
         return { status: "skipped" };
-    const file = join(cwd, "CRUXY.md");
-    writeFileSync(file, CRUXY_MD_TEMPLATE, "utf8");
+    const outcome = scaffoldProjectInstructions(cwd);
+    if (outcome.kind === "failed") {
+        // Previously this threw out of the step on an unwritable directory. A step
+        // must not throw across its boundary, so a failed write is reported.
+        io.write(`${col.danger(col.glyph.failure)} could not write CRUXY.md — ${outcome.message}\n`);
+        return { status: "failed", message: outcome.message };
+    }
     io.write(`${col.success(col.glyph.success)} wrote ${col.strong("CRUXY.md")}\n`);
     return { status: "ok" };
 }

package/dist/plan/approve.js

@@ -10,27 +10,33 @@ import { renderPlan } from "./render.js";
  */
 export async function promptPlanDecision(plan, io) {
     const t = themeForColor(io.color);
-    io.write(renderPlan(plan, io.color));
-    io.write("\n\n");
-    io.write(`  ${t.muted("Approving consents to the shape of the work — every action still asks before it runs.")}\n`);
-    io.write(`  ${t.muted(`[a] approve ${t.glyph.sep}`)} [g] approve ${t.strong("+ allow the read/mutate steps")} this run ${t.muted("(destructive still confirms)")} ${t.muted(`${t.glyph.sep} [e] reject & revise`)} `);
-    const key = (await io.readKey()).toLowerCase();
-    io.write("\n");
-    switch (key) {
-        case "a":
-            return { kind: "approve" };
-        case "g":
-            return { kind: "approve-grant" };
-        case "e":
-        case "n": {
-            io.write("  what should change about the plan? ");
-            const feedback = (await io.readLine()).trim();
-            // No feedback ⇒ treat as an abort, not an empty revision request.
-            return feedback ? { kind: "revise", feedback } : { kind: "abort" };
+    io.beginPrompt?.();
+    try {
+        io.write(renderPlan(plan, io.color));
+        io.write("\n\n");
+        io.write(`  ${t.muted("Approving consents to the shape of the work — every action still asks before it runs.")}\n`);
+        io.write(`  ${t.muted(`[a] approve ${t.glyph.sep}`)} [g] approve ${t.strong("+ allow the read/mutate steps")} this run ${t.muted("(destructive still confirms)")} ${t.muted(`${t.glyph.sep} [e] reject & revise`)} `);
+        const key = (await io.readKey()).toLowerCase();
+        io.write("\n");
+        switch (key) {
+            case "a":
+                return { kind: "approve" };
+            case "g":
+                return { kind: "approve-grant" };
+            case "e":
+            case "n": {
+                io.write("  what should change about the plan? ");
+                const feedback = (await io.readLine()).trim();
+                // No feedback ⇒ treat as an abort, not an empty revision request.
+                return feedback ? { kind: "revise", feedback } : { kind: "abort" };
+            }
+            default:
+                // Unrecognized key, empty, EOF, Ctrl-C → default-deny.
+                return { kind: "abort" };
         }
-        default:
-            // Unrecognized key, empty, EOF, Ctrl-C → default-deny.
-            return { kind: "abort" };
+    }
+    finally {
+        io.endPrompt?.();
     }
 }
 /**
@@ -39,8 +45,14 @@ export async function promptPlanDecision(plan, io) {
  */
 export async function promptContinueAfterFailure(io) {
     const t = themeForColor(io.color);
-    io.write(`  ${t.danger("step failed.")} ${t.muted(`[c] continue with the remaining steps ${t.glyph.sep} [any other key] abort`)} `);
-    const key = (await io.readKey()).toLowerCase();
-    io.write("\n");
-    return key === "c";
+    io.beginPrompt?.();
+    try {
+        io.write(`  ${t.danger("step failed.")} ${t.muted(`[c] continue with the remaining steps ${t.glyph.sep} [any other key] abort`)} `);
+        const key = (await io.readKey()).toLowerCase();
+        io.write("\n");
+        return key === "c";
+    }
+    finally {
+        io.endPrompt?.();
+    }
 }

package/dist/plan/execute.js

@@ -1,6 +1,5 @@
 import { CruxyError } from "../errors/index.js";
 import { promptContinueAfterFailure } from "./approve.js";
-import { renderStepStatus } from "./render.js";
 export async function executePlan(plan, deps) {
     const { runStep, io, renderer } = deps;
     try {
@@ -13,20 +12,20 @@ export async function executePlan(plan, deps) {
                 title: step.title,
             });
             renderer?.setPhase({ kind: "executing-step" });
-            io.write(renderStepStatus(step, io.color) + "\n");
+            renderer?.setPlan(plan.steps);
             try {
                 await runStep(step);
                 step.status = "done";
-                io.write(renderStepStatus(step, io.color) + "\n");
+                renderer?.setPlan(plan.steps);
             }
             catch (err) {
                 step.status = "failed";
-                io.write(renderStepStatus(step, io.color) + "\n");
+                renderer?.setPlan(plan.steps);
                 // Surface the failure via the U.5 shape when we have it.
                 const detail = err instanceof CruxyError
                     ? `${err.title}${err.cause ? ` — ${err.cause}` : ""}`
                     : err.message;
-                io.write(`  ${detail}\n`);
+                renderer?.note(`  ${detail}`);
                 const cont = await promptContinueAfterFailure(io);
                 if (!cont) {
                     return { completed: false, halted: true, failedStepId: step.id };
@@ -38,8 +37,11 @@ export async function executePlan(plan, deps) {
         return { completed, halted: false };
     }
     finally {
-        // The plan owns the progress register; release it on every exit path so
-        // no stale "[i/n]" prefix outlives the run.
+        // The plan owns both registers; release them on every exit path so no stale
+        // "[i/n]" prefix and no stale checklist outlives the run. A renderer that
+        // keeps its checklist live rather than committing each transition (the TUI)
+        // commits one final copy as it clears, so the record survives the release.
         renderer?.progress(null);
+        renderer?.setPlan(null);
     }
 }

package/dist/plan/render.js

@@ -1,25 +1,17 @@
 import { themeForColor } from "../theme/index.js";
+import { statusMark } from "../render/index.js";
 /**
  * Plan rendering (C.31): data → string so it's testable and color is gated on a
- * boolean (NO_COLOR / non-TTY aware, passed in by the caller). Used both for the
- * approval prompt and for live status during execution. Glyphs and colors are
- * sourced from the theme (U.1); status is carried by the glyph (○/◐/✓/✗) and
- * risk by the `[read]/[mutate]/[destructive]` label, so meaning survives
- * NO_COLOR.
+ * boolean (NO_COLOR / non-TTY aware, passed in by the caller). This is the
+ * APPROVAL view — the whole plan, with each step's risk tag and rationale,
+ * shown once before execution. Per-step status DURING execution is the
+ * renderer's `setPlan` surface (`render/plan-view.ts`), which shares the status
+ * glyph below so the two views mark a step identically.
+ *
+ * Glyphs and colors are sourced from the theme (U.1); status is carried by the
+ * glyph (○/◐/✓/✗) and risk by the `[read]/[mutate]/[destructive]` label, so
+ * meaning survives NO_COLOR.
  */
-/** Status glyph, colored when enabled. */
-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);
-    }
-}
 /** A short tag for the step's risk estimate. */
 function kindTag(kind, t) {
     switch (kind) {
@@ -48,8 +40,3 @@ export function renderPlan(plan, color) {
         lines.push(renderStep(step, t));
     return lines.join("\n");
 }
-/** A one-line status update for a single step (used during execution). */
-export function renderStepStatus(step, color) {
-    const t = themeForColor(color);
-    return `${statusMark(step.status, t)} ${t.strong(step.id + ".")} ${step.title}`;
-}

package/dist/plan/service.js

@@ -86,7 +86,10 @@ export async function runPlanSession(args) {
         const plan = holder.plan;
         const decision = await promptPlanDecision(plan, args.io);
         if (decision.kind === "abort") {
-            args.io.write("plan aborted — nothing was executed.\n");
+            // Committed output goes through the renderer, not the prompt io (P3):
+            // the io is for asking, and a plain write on it bypasses the live region
+            // that owns the screen.
+            args.renderer?.note("plan aborted — nothing was executed.");
             return finish();
         }
         if (decision.kind !== "revise") {

package/dist/render/capabilities.js

@@ -6,6 +6,8 @@ function isSet(value) {
 }
 /** Fallback width when the terminal reports none (non-TTY, pipe, unknown). */
 export const DEFAULT_COLUMNS = 80;
+/** Fallback height when the terminal reports none (non-TTY, pipe, unknown). */
+export const DEFAULT_ROWS = 24;
 /**
  * Resolve the terminal width (U.12) — the single rule behind
  * {@link RenderCapabilities.width} and every resize recompute. `COLUMNS` wins
@@ -22,6 +24,20 @@ export function resolveColumns(stream = process.stdout, env = process.env) {
         return stream.columns;
     return DEFAULT_COLUMNS;
 }
+/**
+ * Resolve the terminal height — the vertical twin of {@link resolveColumns},
+ * with the identical precedence rule: `LINES` wins when set (so `LINES=40 cruxy`
+ * and CI overrides work), then the stream's own `rows`, then
+ * {@link DEFAULT_ROWS}. Never returns a non-positive height.
+ */
+export function resolveRows(stream = process.stdout, env = process.env) {
+    const fromEnv = env.LINES === undefined ? NaN : Number.parseInt(env.LINES, 10);
+    if (Number.isFinite(fromEnv) && fromEnv > 0)
+        return fromEnv;
+    if (typeof stream.rows === "number" && stream.rows > 0)
+        return stream.rows;
+    return DEFAULT_ROWS;
+}
 /**
  * Reduced-motion (U.11) — the ecosystem `NO_MOTION` signal, the explicit cruxy
  * knob `CRUXY_REDUCED_MOTION`, and `CRUXY_NO_SPINNER` kept as an alias flowing
@@ -44,12 +60,19 @@ export function detectReducedMotion(env = process.env) {
  * The axes are independent (U.1/U.11): a NO_COLOR terminal still supports
  * in-place status updates; a dumb terminal supports neither; reduced motion and
  * screen-reader mode compose orthogonally with color and unicode.
+ *
+ * `stdin` is probed separately from `stream` because they are genuinely
+ * different channels: `echo hi | cruxy` has a piped stdin and a TTY stdout, and
+ * `cruxy > log` the reverse. Resolving both here — and their conjunction as
+ * `interactive` — is what lets every call site stop reading
+ * `process.stdin.isTTY` for itself.
  */
-export function detectCapabilities(stream = process.stdout, env = process.env) {
+export function detectCapabilities(stream = process.stdout, env = process.env, stdin = process.stdin) {
     const tty = Boolean(stream.isTTY);
     const dumb = env.TERM === "dumb";
     const cursor = tty && !dumb;
     const reducedMotion = detectReducedMotion(env);
+    const stdinTty = Boolean(stdin.isTTY);
     return {
         tty,
         color: shouldUseColor(stream, env) && !dumb,
@@ -62,6 +85,12 @@ export function detectCapabilities(stream = process.stdout, env = process.env) {
         // Unicode glyph safety (U.1) — independent of color. dumb / CRUXY_ASCII →
         // ASCII glyphs; everything else (incl. pipes) keeps unicode.
         unicode: detectUnicode(env),
+        stdinTty,
+        // The one interactivity rule, resolved once: a key read needs a terminal to
+        // read FROM and a terminal that can be repainted. Either half missing and
+        // no component may draw a frame or block on a key.
+        interactive: stdinTty && cursor,
         width: resolveColumns(stream, env),
+        height: resolveRows(stream, env),
     };
 }

package/dist/render/context-view.js

@@ -0,0 +1,106 @@
+import { formatTokens } from "./state.js";
+import { fit } from "./layout.js";
+/**
+ * Rendering `/context` (P6 track 3) — the DETAIL VIEW behind the rail's two
+ * numbers, not a second copy of them.
+ *
+ * THE PANEL'S RULES STILL APPLY HERE, and nothing below may weaken them. The
+ * context panel's doc comment is explicit that two plain numbers are the honest
+ * presentation and that a progress bar would not be: a filled bar reads as a
+ * measurement, and this is a chars/4 heuristic measured against a local config
+ * default. So there is no bar here either, no percentage-of-window, and every
+ * figure carries a `~`. "budget", never "window".
+ *
+ * WHAT THIS ADDS is the two things that genuinely cannot live in a 24-column
+ * strip without implying a precision they do not have:
+ *
+ *  1. **Where the tokens are.** A breakdown by what the content IS — prompts,
+ *     assistant text, tool calls, tool results, and summaries a previous
+ *     compaction already folded in — plus the individual messages large enough
+ *     to be worth naming. "60% of your context is one grep result" is
+ *     actionable; a single occupancy figure is not.
+ *  2. **What compaction would actually drop.** Computed by the SAME `findCut`
+ *     the seam uses, so the explanation cannot be subtly wrong exactly where it
+ *     matters. Including the case that surprises people: a history with no safe
+ *     cut point, where `/compact` will do nothing at all.
+ *
+ * The reserve is shown as its own row rather than folded into a total. It is
+ * part of `used`, it is present in no message, and a breakdown that omitted it
+ * would leave several thousand tokens looking unexplained.
+ */
+/** `~34k`, `~900` — the leading tilde is not decoration. See the module note. */
+function approx(n) {
+    return `~${formatTokens(n)}`;
+}
+/** `12%` — a share of the measured history, never of the model's real window. */
+function share(tokens, of) {
+    if (of <= 0)
+        return "";
+    return `${Math.round((tokens / of) * 100)}%`;
+}
+/**
+ * The full `/context` report as lines to print.
+ *
+ * `width` fits each row so a narrow terminal truncates rather than soft-wrapping
+ * a table into a misaligned mess; the default is unbounded for callers that
+ * reflow themselves (the TUI's main column).
+ */
+export function contextReportLines(report, t, width = Infinity) {
+    const { reading, compaction } = report;
+    const lines = [t.heading("context")];
+    // The headline, worded exactly as the panel words it — same estimate, same
+    // caveats, so the detail view can never read as the more authoritative one.
+    lines.push(`${t.strong(`${approx(reading.used)} / ${formatTokens(reading.total)} budget`)} ` +
+        t.muted(`(estimated · budget is a local setting, not the model's window)`));
+    lines.push(t.muted(`${report.messages} message${report.messages === 1 ? "" : "s"} · compacts above ${approx(reading.compactAt)}`));
+    // ── where the tokens are ──────────────────────────────────────────────────
+    const historyTokens = report.parts.reduce((sum, p) => sum + p.tokens, 0);
+    lines.push("");
+    lines.push(t.strong("where it is"));
+    if (report.parts.length === 0) {
+        lines.push(t.muted("  no conversation yet"));
+    }
+    else {
+        for (const part of report.parts) {
+            lines.push(`  ${part.part.padEnd(13)} ${approx(part.tokens).padStart(7)} ` +
+                t.muted(`${share(part.tokens, historyTokens).padStart(4)}  ${part.messages} msg`));
+        }
+    }
+    // Named separately because it is real, unavoidable, and in no message — the
+    // one part of the figure a user cannot shrink by pruning the conversation.
+    lines.push(`  ${"reserve".padEnd(13)} ${approx(report.reserveTokens).padStart(7)} ` +
+        t.muted("       system prompt + tool schemas"));
+    // ── the biggest single messages ───────────────────────────────────────────
+    if (report.largest.length > 0) {
+        lines.push("");
+        lines.push(t.strong("largest messages"));
+        for (const c of report.largest) {
+            const head = `  ${String(c.position).padStart(3)}. ${approx(c.tokens).padStart(7)}  ${c.label}`;
+            lines.push(`${head}${c.excerpt === "" ? "" : t.muted(` — ${c.excerpt}`)}`);
+        }
+    }
+    // ── what compaction would do ──────────────────────────────────────────────
+    lines.push("");
+    lines.push(t.strong("if you compact now"));
+    if (compaction.cut === null) {
+        // The case that surprises people, and the reason this section exists at all.
+        lines.push(t.muted("  nothing — there is no safe cut point yet. A summary can only replace"));
+        lines.push(t.muted("  whole completed turns, so an in-progress turn (or a history with no"));
+        lines.push(t.muted("  finished turn behind it) has nothing it can fold away."));
+    }
+    else {
+        lines.push(t.muted(`  ${compaction.droppedMessages} message${compaction.droppedMessages === 1 ? "" : "s"} ` +
+            `(${approx(compaction.droppedTokens)}) folded into a summary; ` +
+            `${compaction.keptMessages} kept verbatim (${approx(compaction.keptTokens)})`));
+        // A ceiling, not a saving: the summary that replaces the prefix costs
+        // tokens of its own, and how many is not knowable until the model writes it.
+        lines.push(t.muted(`  frees at most ${approx(compaction.droppedTokens)} — the summary that replaces them costs`));
+        lines.push(t.muted("  tokens of its own, which cannot be known in advance."));
+    }
+    lines.push(compaction.overThreshold
+        ? t.warning("  the next turn will compact on its own")
+        : t.muted("  below the threshold — the next turn will not compact"));
+    return Number.isFinite(width)
+        ? lines.map((l) => fit(l, width, t.glyph.ellipsis))
+        : lines;
+}