@cruxy/cli 0.8.0 → 0.10.0

package/dist/errors/constructors.js

@@ -23,6 +23,21 @@ export function usageError(title, nextSteps) {
         nextSteps: nextSteps ?? ["run `cruxy --help` for usage"],
     });
 }
+/**
+ * An interactive component (picker, fuzzy finder) was needed but stdin is not
+ * an interactive terminal and the caller supplied no default (U.7). Never
+ * silently picks an option, never blocks on a pipe — same discipline as the
+ * approval/onboarding layers.
+ */
+export function interactiveRequired(what, alternatives = []) {
+    return new CruxyError({
+        code: ErrorCode.InteractiveRequired,
+        title: `${what} needs an interactive terminal`,
+        cause: "stdin is not a TTY (or the terminal cannot render an interactive picker)",
+        nextSteps: ["run cruxy in an interactive terminal", ...alternatives],
+        meta: { what },
+    });
+}
 export function configKeyUnknown(key) {
     return new CruxyError({
         code: ErrorCode.ConfigKeyUnknown,
@@ -335,6 +350,92 @@ export function planApprovalRequired() {
         ],
     });
 }
+// ── checkpoint + rollback (exit 7 / 2 / 10) ───────────────────────────────────
+/**
+ * Creating, reading, or restoring a working-tree checkpoint failed (C.32).
+ * Fail-loud by design: an agent run never mutates files without its undo
+ * protection unless the user explicitly disables it.
+ */
+export function checkpointFailed(reason, underlying) {
+    return new CruxyError({
+        code: ErrorCode.CheckpointFailed,
+        title: "the working-tree checkpoint operation failed",
+        cause: reason,
+        nextSteps: [
+            "re-run with --verbose for details",
+            "if this happened during rollback, re-run `cruxy rollback <id>` — it recomputes from disk and is safe to retry",
+            "set `checkpoint.enabled = false` in config to run without undo protection (not recommended)",
+        ],
+        underlying,
+        meta: { reason },
+    });
+}
+/** The requested checkpoint id doesn't exist (or no checkpoints exist at all). */
+export function checkpointNotFound(id) {
+    return new CruxyError({
+        code: ErrorCode.CheckpointNotFound,
+        title: id
+            ? `checkpoint "${id}" not found`
+            : "no checkpoints exist in this project",
+        cause: id
+            ? "no manifest with that id under .cruxy/checkpoints/"
+            : "a checkpoint is created automatically before an agent run's first file change",
+        nextSteps: [
+            "run `cruxy checkpoint list` to see the saved checkpoints",
+            "checkpoints are pruned by retention — adjust `checkpoint.retention` in config to keep more",
+        ],
+        meta: { id },
+    });
+}
+/**
+ * Rollback needs interactive approval but cruxy is running non-interactively.
+ * Restoring is destructive and deliberate — there is no auto-rollback path, ever.
+ */
+export function rollbackApprovalRequired() {
+    return new CruxyError({
+        code: ErrorCode.RollbackApprovalRequired,
+        title: "rollback needs your approval, but cruxy is running non-interactively",
+        cause: "restoring a checkpoint overwrites working-tree files and can only be confirmed in an interactive terminal",
+        nextSteps: [
+            "run `cruxy rollback` in an interactive terminal to review the preview and confirm",
+        ],
+    });
+}
+// ── subagent (exit 2 / 11) ────────────────────────────────────────────────────
+/**
+ * A subagent spawn was attempted past the configured nesting cap (C.14). The
+ * spawn tool is structurally withheld at the cap, so reaching this means the
+ * orchestrator seam was driven directly — fail loud, never spawn.
+ */
+export function subagentDepthExceeded(depth, maxDepth) {
+    return new CruxyError({
+        code: ErrorCode.SubagentDepthExceeded,
+        title: `subagent nesting depth ${depth + 1} exceeds the configured cap (${maxDepth})`,
+        cause: "subagents may not spawn subagents beyond subagent.maxDepth",
+        nextSteps: [
+            "raise `subagent.maxDepth` in config if deeper nesting is intended",
+            "or restructure the task so the parent dispatches the subtasks directly",
+        ],
+        meta: { depth, maxDepth },
+    });
+}
+/**
+ * A subagent run failed outright (provider error, tool crash) before producing
+ * a result. Normally folded into the structured `SubagentResult` the parent
+ * reasons over; thrown only when the orchestrator itself cannot proceed.
+ */
+export function subagentFailed(underlying) {
+    return new CruxyError({
+        code: ErrorCode.SubagentFailed,
+        title: "the subagent run failed",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "re-run with --verbose for details",
+            "retry the task, or narrow the subagent's scope",
+        ],
+        underlying,
+    });
+}
 // ── internal (exit 1) ─────────────────────────────────────────────────────────
 export function internal(underlying) {
     return new CruxyError({

package/dist/errors/types.d.ts

@@ -14,11 +14,13 @@
 export declare const ErrorCode: {
     readonly Internal: "CRUXY_E_INTERNAL";
     readonly Usage: "CRUXY_E_USAGE";
+    readonly InteractiveRequired: "CRUXY_E_INTERACTIVE_REQUIRED";
     readonly ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN";
     readonly ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED";
     readonly GitProtectedBranch: "CRUXY_E_GIT_PROTECTED_BRANCH";
     readonly PlanInvalid: "CRUXY_E_PLAN_INVALID";
     readonly PlanRevisionLimit: "CRUXY_E_PLAN_REVISION_LIMIT";
+    readonly CheckpointNotFound: "CRUXY_E_CHECKPOINT_NOT_FOUND";
     readonly ConfigParse: "CRUXY_E_CONFIG_PARSE";
     readonly ConfigInvalid: "CRUXY_E_CONFIG_INVALID";
     readonly AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY";
@@ -34,6 +36,7 @@ export declare const ErrorCode: {
     readonly FileNotFound: "CRUXY_E_FILE_NOT_FOUND";
     readonly PermissionDenied: "CRUXY_E_PERMISSION_DENIED";
     readonly PathEscape: "CRUXY_E_PATH_ESCAPE";
+    readonly CheckpointFailed: "CRUXY_E_CHECKPOINT_FAILED";
     readonly IndexEmbedderUnavailable: "CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE";
     readonly IndexStoreUnavailable: "CRUXY_E_INDEX_STORE_UNAVAILABLE";
     readonly IndexFailed: "CRUXY_E_INDEX_FAILED";
@@ -41,6 +44,11 @@ export declare const ErrorCode: {
     readonly SkillNotFound: "CRUXY_E_SKILL_NOT_FOUND";
     readonly ApprovalRequired: "CRUXY_E_APPROVAL_REQUIRED";
     readonly PlanApprovalRequired: "CRUXY_E_PLAN_APPROVAL_REQUIRED";
+    readonly RollbackApprovalRequired: "CRUXY_E_ROLLBACK_APPROVAL_REQUIRED";
+    readonly SubagentDepthExceeded: "CRUXY_E_SUBAGENT_DEPTH_EXCEEDED";
+    /** Carried inside a SubagentResult (informational) — never fatal by itself. */
+    readonly SubagentBudget: "CRUXY_E_SUBAGENT_BUDGET";
+    readonly SubagentFailed: "CRUXY_E_SUBAGENT_FAILED";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -16,11 +16,13 @@ export const ErrorCode = {
     Internal: "CRUXY_E_INTERNAL",
     // usage (exit 2)
     Usage: "CRUXY_E_USAGE",
+    InteractiveRequired: "CRUXY_E_INTERACTIVE_REQUIRED",
     ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN",
     ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED",
     GitProtectedBranch: "CRUXY_E_GIT_PROTECTED_BRANCH",
     PlanInvalid: "CRUXY_E_PLAN_INVALID",
     PlanRevisionLimit: "CRUXY_E_PLAN_REVISION_LIMIT",
+    CheckpointNotFound: "CRUXY_E_CHECKPOINT_NOT_FOUND",
     // config (exit 3)
     ConfigParse: "CRUXY_E_CONFIG_PARSE",
     ConfigInvalid: "CRUXY_E_CONFIG_INVALID",
@@ -41,6 +43,7 @@ export const ErrorCode = {
     FileNotFound: "CRUXY_E_FILE_NOT_FOUND",
     PermissionDenied: "CRUXY_E_PERMISSION_DENIED",
     PathEscape: "CRUXY_E_PATH_ESCAPE",
+    CheckpointFailed: "CRUXY_E_CHECKPOINT_FAILED",
     // index (exit 8)
     IndexEmbedderUnavailable: "CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE",
     IndexStoreUnavailable: "CRUXY_E_INDEX_STORE_UNAVAILABLE",
@@ -51,6 +54,12 @@ export const ErrorCode = {
     // approval (exit 10)
     ApprovalRequired: "CRUXY_E_APPROVAL_REQUIRED",
     PlanApprovalRequired: "CRUXY_E_PLAN_APPROVAL_REQUIRED",
+    RollbackApprovalRequired: "CRUXY_E_ROLLBACK_APPROVAL_REQUIRED",
+    // subagent (exit 2 / 11)
+    SubagentDepthExceeded: "CRUXY_E_SUBAGENT_DEPTH_EXCEEDED",
+    /** Carried inside a SubagentResult (informational) — never fatal by itself. */
+    SubagentBudget: "CRUXY_E_SUBAGENT_BUDGET",
+    SubagentFailed: "CRUXY_E_SUBAGENT_FAILED",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -59,11 +68,13 @@ export const ErrorCode = {
 const EXIT_CODES = {
     [ErrorCode.Internal]: 1,
     [ErrorCode.Usage]: 2,
+    [ErrorCode.InteractiveRequired]: 2,
     [ErrorCode.ConfigKeyUnknown]: 2,
     [ErrorCode.ProviderUnsupported]: 2,
     [ErrorCode.GitProtectedBranch]: 2,
     [ErrorCode.PlanInvalid]: 2,
     [ErrorCode.PlanRevisionLimit]: 2,
+    [ErrorCode.CheckpointNotFound]: 2,
     [ErrorCode.ConfigParse]: 3,
     [ErrorCode.ConfigInvalid]: 3,
     [ErrorCode.AuthMissingKey]: 4,
@@ -79,6 +90,7 @@ const EXIT_CODES = {
     [ErrorCode.FileNotFound]: 7,
     [ErrorCode.PermissionDenied]: 7,
     [ErrorCode.PathEscape]: 7,
+    [ErrorCode.CheckpointFailed]: 7,
     [ErrorCode.IndexEmbedderUnavailable]: 8,
     [ErrorCode.IndexStoreUnavailable]: 8,
     [ErrorCode.IndexFailed]: 8,
@@ -86,6 +98,12 @@ const EXIT_CODES = {
     [ErrorCode.SkillNotFound]: 9,
     [ErrorCode.ApprovalRequired]: 10,
     [ErrorCode.PlanApprovalRequired]: 10,
+    [ErrorCode.RollbackApprovalRequired]: 10,
+    // Depth-exceed is a misuse of the spawn seam (usage); the other two surface
+    // inside a SubagentResult and only exit the process if thrown directly.
+    [ErrorCode.SubagentDepthExceeded]: 2,
+    [ErrorCode.SubagentBudget]: 11,
+    [ErrorCode.SubagentFailed]: 11,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/indexing/walker.d.ts

@@ -18,7 +18,18 @@ export interface WalkOptions {
     maxFileBytes: number;
     /** Ignore-file names to honor, relative to each directory (gitignore syntax). */
     ignoreFileNames?: string[];
+    /**
+     * Yield binary files too (default false). The index never wants them; the
+     * checkpoint capturer (C.32) does — a snapshot must be complete to restore.
+     */
+    includeBinary?: boolean;
 }
+/**
+ * The C.17 secrets denylist test, shared beyond the index: the checkpoint
+ * capturer (C.32) applies the exact same rule so a working-tree snapshot can
+ * never contain a secret-bearing file either.
+ */
+export declare function isSecretPath(relPath: string): boolean;
 /**
  * A compiled set of gitignore-style patterns, matched against paths relative to
  * the file's own directory. Supports comments, blank lines, `!` negation,

package/dist/indexing/walker.js

@@ -16,7 +16,12 @@ const SECRET_PATTERNS = [
     /(^|\/)\.(npmrc|netrc|pgpass)$/i, // credential dotfiles
     /(^|\/)\.aws\/credentials$/i,
 ];
-function isSecretPath(relPath) {
+/**
+ * The C.17 secrets denylist test, shared beyond the index: the checkpoint
+ * capturer (C.32) applies the exact same rule so a working-tree snapshot can
+ * never contain a secret-bearing file either.
+ */
+export function isSecretPath(relPath) {
     return SECRET_PATTERNS.some((re) => re.test(relPath));
 }
 /**
@@ -121,9 +126,9 @@ async function isBinaryFile(absPath) {
 export async function* walkRepo(root, opts) {
     const absRoot = path.resolve(root);
     const ignoreFileNames = opts.ignoreFileNames ?? DEFAULT_IGNORE_FILES;
-    yield* walkDir(absRoot, absRoot, [], ignoreFileNames, opts.maxFileBytes);
+    yield* walkDir(absRoot, absRoot, [], ignoreFileNames, opts);
 }
-async function* walkDir(dir, root, parentStack, ignoreFileNames, maxFileBytes) {
+async function* walkDir(dir, root, parentStack, ignoreFileNames, opts) {
     const scope = await loadIgnoreScope(dir, ignoreFileNames);
     const stack = scope ? [...parentStack, scope] : parentStack;
     let entries;
@@ -147,7 +152,7 @@ async function* walkDir(dir, root, parentStack, ignoreFileNames, maxFileBytes) {
         if (isIgnored(stack, absPath, isDir))
             continue;
         if (isDir) {
-            yield* walkDir(absPath, root, stack, ignoreFileNames, maxFileBytes);
+            yield* walkDir(absPath, root, stack, ignoreFileNames, opts);
             continue;
         }
         let size;
@@ -157,9 +162,9 @@ async function* walkDir(dir, root, parentStack, ignoreFileNames, maxFileBytes) {
         catch {
             continue;
         }
-        if (size > maxFileBytes)
+        if (size > opts.maxFileBytes)
             continue;
-        if (await isBinaryFile(absPath))
+        if (!opts.includeBinary && (await isBinaryFile(absPath)))
             continue;
         yield { relPath, absPath, size };
     }

package/dist/onboarding/io.d.ts

@@ -2,7 +2,8 @@ import type { OnboardingIO } from "./types.js";
 /**
  * The real stdin/stderr-backed {@link OnboardingIO}. Prompts go to stderr (stdout
  * stays clean for piping); the secret reader echoes `*` per keystroke and never
- * the real character. All readers restore cooked mode on the way out, even on
- * Ctrl-C / EOF — the terminal is never left in raw mode.
+ * the real character. Raw-mode key handling is the shared U.7 reader
+ * (`components/input.ts`) — the single owner of `setRawMode` — so cooked mode
+ * is restored on every exit path, Ctrl-C / EOF included.
  */
 export declare function defaultOnboardingIO(color?: boolean): OnboardingIO;

package/dist/onboarding/io.js

@@ -1,54 +1,21 @@
+import { createKeyReader, readSingleKey } from "../components/input.js";
 import { shouldUseColor } from "../errors/index.js";
 /**
  * The real stdin/stderr-backed {@link OnboardingIO}. Prompts go to stderr (stdout
  * stays clean for piping); the secret reader echoes `*` per keystroke and never
- * the real character. All readers restore cooked mode on the way out, even on
- * Ctrl-C / EOF — the terminal is never left in raw mode.
+ * the real character. Raw-mode key handling is the shared U.7 reader
+ * (`components/input.ts`) — the single owner of `setRawMode` — so cooked mode
+ * is restored on every exit path, Ctrl-C / EOF included.
  */
 export function defaultOnboardingIO(color = shouldUseColor()) {
     return {
         write: (text) => void process.stderr.write(text),
         readLine: readLineFromStdin,
-        readKey: readKeyFromStdin,
+        readKey: () => readSingleKey(),
         readSecret: readSecretFromStdin,
         color,
     };
 }
-const CTRL_C = 0x03;
-const CTRL_D = 0x04;
-const BACKSPACE = 0x08;
-const DELETE = 0x7f;
-const LF = 0x0a;
-const CR = 0x0d;
-/** Read one keypress in raw mode; "" on EOF / Ctrl-C / Ctrl-D. Restores cooked mode. */
-function readKeyFromStdin() {
-    const stdin = process.stdin;
-    return new Promise((resolve) => {
-        const cleanup = () => {
-            stdin.removeListener("data", onData);
-            stdin.removeListener("end", onEnd);
-            if (stdin.isTTY)
-                stdin.setRawMode(false);
-            stdin.pause();
-        };
-        const onData = (buf) => {
-            cleanup();
-            const code = buf[0];
-            resolve(code === CTRL_C || code === CTRL_D
-                ? ""
-                : buf.toString("utf8").slice(0, 1));
-        };
-        const onEnd = () => {
-            cleanup();
-            resolve("");
-        };
-        if (stdin.isTTY)
-            stdin.setRawMode(true);
-        stdin.resume();
-        stdin.once("data", onData);
-        stdin.once("end", onEnd);
-    });
-}
 /** Read one line in cooked mode; "" on EOF. */
 function readLineFromStdin() {
     const stdin = process.stdin;
@@ -80,54 +47,41 @@ function readLineFromStdin() {
 }
 /**
  * Read a secret with no echo: each printable keystroke shows a `*`, backspace
- * erases one, Enter submits, Ctrl-C / Ctrl-D / EOF resolve "" (abort). The real
- * characters are never written anywhere.
+ * erases one, Enter submits, Ctrl-C / Ctrl-D / EOF resolve "" (abort). The
+ * real characters are never written anywhere. Built on the shared key reader,
+ * which also keeps arrow/escape sequences from leaking into the secret.
  */
-function readSecretFromStdin() {
-    const stdin = process.stdin;
+async function readSecretFromStdin() {
     const out = process.stderr;
-    return new Promise((resolve) => {
-        let buf = "";
-        let done = false;
-        const cleanup = () => {
-            stdin.removeListener("data", onData);
-            stdin.removeListener("end", onEnd);
-            if (stdin.isTTY)
-                stdin.setRawMode(false);
-            stdin.pause();
-        };
-        const finish = (value) => {
-            if (done)
-                return;
-            done = true;
-            cleanup();
-            out.write("\n");
-            resolve(value);
-        };
-        const onData = (chunk) => {
-            for (const byte of chunk) {
-                if (byte === CR || byte === LF)
-                    return finish(buf); // Enter → submit
-                if (byte === CTRL_C || byte === CTRL_D)
-                    return finish(""); // abort
-                if (byte === DELETE || byte === BACKSPACE) {
+    const keys = createKeyReader(process.stdin);
+    keys.begin();
+    let buf = "";
+    try {
+        for (;;) {
+            const key = await keys.read();
+            switch (key.kind) {
+                case "enter":
+                    return buf;
+                case "ctrl-c":
+                case "eof":
+                    return "";
+                case "backspace":
                     if (buf.length > 0) {
                         buf = buf.slice(0, -1);
                         out.write("\b \b"); // erase one star
                     }
-                    continue;
-                }
-                if (byte < 0x20)
-                    continue; // ignore other control chars
-                buf += String.fromCharCode(byte);
-                out.write("*");
+                    break;
+                case "char":
+                    buf += key.char;
+                    out.write("*");
+                    break;
+                default:
+                    break; // arrows / tab / escape: ignored, never echoed
             }
-        };
-        const onEnd = () => finish("");
-        if (stdin.isTTY)
-            stdin.setRawMode(true);
-        stdin.resume();
-        stdin.on("data", onData);
-        stdin.once("end", onEnd);
-    });
+        }
+    }
+    finally {
+        keys.restore();
+        out.write("\n");
+    }
 }

package/dist/plan/execute.d.ts

@@ -1,4 +1,5 @@
 import type { PromptIO } from "../approval/index.js";
+import type { StreamRenderer } from "../render/index.js";
 import type { Plan, PlanExecutionResult, PlanStep } from "./types.js";
 /**
  * Execute an approved plan step-by-step (C.31): mark each step `running`, run it,
@@ -16,5 +17,12 @@ export interface ExecuteDeps {
      */
     runStep: (step: PlanStep) => Promise<void>;
     io: PromptIO;
+    /**
+     * Live step progress (U.4): each step feeds `[i/n] title` to the renderer's
+     * progress register, straight from this walk of `plan.steps` — the same
+     * statuses the committed trail renders, never recomputed. Optional so the
+     * executor stays drivable without a terminal (tests, future CI mode).
+     */
+    renderer?: StreamRenderer;
 }
 export declare function executePlan(plan: Plan, deps: ExecuteDeps): Promise<PlanExecutionResult>;

package/dist/plan/execute.js

@@ -2,30 +2,44 @@ 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 } = deps;
-    for (const step of plan.steps) {
-        step.status = "running";
-        io.write(renderStepStatus(step, io.color) + "\n");
-        try {
-            await runStep(step);
-            step.status = "done";
+    const { runStep, io, renderer } = deps;
+    try {
+        for (const [index, step] of plan.steps.entries()) {
+            step.status = "running";
+            // Live: "[2/5] title · working…" until the step's agent turn takes over.
+            renderer?.progress({
+                step: index + 1,
+                of: plan.steps.length,
+                title: step.title,
+            });
+            renderer?.setPhase({ kind: "executing-step" });
             io.write(renderStepStatus(step, io.color) + "\n");
-        }
-        catch (err) {
-            step.status = "failed";
-            io.write(renderStepStatus(step, io.color) + "\n");
-            // 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`);
-            const cont = await promptContinueAfterFailure(io);
-            if (!cont) {
-                return { completed: false, halted: true, failedStepId: step.id };
+            try {
+                await runStep(step);
+                step.status = "done";
+                io.write(renderStepStatus(step, io.color) + "\n");
+            }
+            catch (err) {
+                step.status = "failed";
+                io.write(renderStepStatus(step, io.color) + "\n");
+                // 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`);
+                const cont = await promptContinueAfterFailure(io);
+                if (!cont) {
+                    return { completed: false, halted: true, failedStepId: step.id };
+                }
+                // User chose to continue despite the failure; move to the next step.
             }
-            // User chose to continue despite the failure; move to the next step.
         }
+        const completed = plan.steps.every((s) => s.status === "done");
+        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.
+        renderer?.progress(null);
     }
-    const completed = plan.steps.every((s) => s.status === "done");
-    return { completed, halted: false };
 }

package/dist/plan/service.js

@@ -108,7 +108,11 @@ export async function runPlanSession(args) {
                     renderer: args.renderer,
                 }));
             };
-            await executePlan(plan, { runStep, io: args.io });
+            await executePlan(plan, {
+                runStep,
+                io: args.io,
+                renderer: args.renderer,
+            });
             return finish();
         }
         feedback = decision.feedback;

package/dist/plan/submit-plan.d.ts

@@ -7,24 +7,24 @@ declare const parameters: z.ZodObject<{
         rationale: z.ZodString;
         kind: z.ZodEnum<["read", "mutate", "destructive"]>;
     }, "strip", z.ZodTypeAny, {
-        title: string;
         kind: "read" | "mutate" | "destructive";
+        title: string;
         rationale: string;
     }, {
-        title: string;
         kind: "read" | "mutate" | "destructive";
+        title: string;
         rationale: string;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     steps: {
-        title: string;
         kind: "read" | "mutate" | "destructive";
+        title: string;
         rationale: string;
     }[];
 }, {
     steps: {
-        title: string;
         kind: "read" | "mutate" | "destructive";
+        title: string;
         rationale: string;
     }[];
 }>;

package/dist/render/diff.js

@@ -40,6 +40,30 @@ function renderPrPreview(preview, c) {
         out.push(c.dim(`  ${line}`));
     return out;
 }
+/**
+ * Render a `rollback` restore plan (C.32). Header, warnings, and the
+ * out-of-scope note come **before** the file diffs on purpose: the global
+ * {@link PREVIEW_MAX_LINES} collapse trims from the tail, and the blast-radius
+ * warnings must never be the part that gets hidden.
+ */
+function renderRollbackPreview(preview, c) {
+    const out = [];
+    out.push(`${c.bold("restore checkpoint")} ${c.cyan(preview.checkpointId)} ${c.dim(`(${preview.createdAt})`)}`);
+    if (preview.runSummary)
+        out.push(c.dim(`run: ${preview.runSummary}`));
+    out.push(c.dim("working-tree files only — commits, pushes, and PRs made during the run are not undone"));
+    if (preview.externalPaths.length > 0) {
+        out.push(c.red(c.bold("changed outside this run — rollback will overwrite these too:")));
+        for (const p of preview.externalPaths)
+            out.push(c.red(`! ${p}`));
+    }
+    if (preview.attributionUnknown) {
+        out.push(c.yellow("this run executed shell commands; some changes below may not have been made by the run"));
+    }
+    out.push("");
+    out.push(...renderPatchFiles(preview.files, c));
+    return out;
+}
 /** Split a multi-line body into trimmed-of-trailing lines, dropping a trailing blank. */
 function bodyLines(body) {
     const lines = body.replace(/\s+$/, "").split("\n");
@@ -63,6 +87,9 @@ export function renderActionPreview(preview, c) {
     else if (preview.type === "pr") {
         lines = renderPrPreview(preview, c);
     }
+    else if (preview.type === "rollback") {
+        lines = renderRollbackPreview(preview, c);
+    }
     else {
         const header = preview.exists
             ? c.yellow("OVERWRITE existing")

package/dist/render/index.d.ts

@@ -1,6 +1,7 @@
 import type { RenderStream, StreamRenderer } from "./types.js";
-export type { RenderCapabilities, RenderStream, StreamRenderer, } from "./types.js";
+export type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, StreamRenderer, TokenUsage, ToolLifecycleEvent, } from "./types.js";
 export { detectCapabilities } from "./capabilities.js";
+export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
 export { renderActionPreview, PREVIEW_MAX_LINES, type Colors } from "./diff.js";
 export { createStreamHighlighter, defaultLineHighlighter, type HighlightCarry, type LineHighlighter, type StreamHighlighter, } from "./highlight.js";
 export { PlainRenderer } from "./plain-renderer.js";

package/dist/render/index.js

@@ -2,6 +2,7 @@ import { detectCapabilities } from "./capabilities.js";
 import { PlainRenderer } from "./plain-renderer.js";
 import { TtyRenderer } from "./tty-renderer.js";
 export { detectCapabilities } from "./capabilities.js";
+export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
 export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
 export { createStreamHighlighter, defaultLineHighlighter, } from "./highlight.js";
 export { PlainRenderer } from "./plain-renderer.js";

package/dist/render/plain-renderer.d.ts

@@ -1,5 +1,5 @@
 import type { ActionPreview } from "../tools/types.js";
-import type { RenderCapabilities, RenderStream, StreamRenderer } from "./types.js";
+import type { RenderCapabilities, RenderStream, StreamRenderer, ToolLifecycleEvent } from "./types.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
@@ -19,6 +19,8 @@ export declare class PlainRenderer implements StreamRenderer {
     /** Per-turn leading-newline trim; also tells endSegment whether to newline. */
     private print;
     private wroteInSegment;
+    /** In-flight tool call (serial by contract) for the end-note duration. */
+    private toolStart;
     constructor(caps: RenderCapabilities, out: RenderStream, err: RenderStream);
     private newPrinter;
     beginTurn(): void;
@@ -27,6 +29,10 @@ export declare class PlainRenderer implements StreamRenderer {
     note(text: string): void;
     preview(preview: ActionPreview): void;
     status(): void;
+    setPhase(): void;
+    progress(): void;
+    toolLifecycle(event: ToolLifecycleEvent): void;
+    promptResolved(): void;
     endTurn(): void;
     close(): void;
 }