@cruxy/cli 0.7.0 → 0.9.0

package/dist/errors/constructors.js

@@ -335,6 +335,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

@@ -19,6 +19,7 @@ export declare const ErrorCode: {
     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 +35,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 +43,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

@@ -21,6 +21,7 @@ export const ErrorCode = {
     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 +42,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 +53,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
@@ -64,6 +72,7 @@ const EXIT_CODES = {
     [ErrorCode.GitProtectedBranch]: 2,
     [ErrorCode.PlanInvalid]: 2,
     [ErrorCode.PlanRevisionLimit]: 2,
+    [ErrorCode.CheckpointNotFound]: 2,
     [ErrorCode.ConfigParse]: 3,
     [ErrorCode.ConfigInvalid]: 3,
     [ErrorCode.AuthMissingKey]: 4,
@@ -79,6 +88,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 +96,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/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.d.ts

@@ -3,6 +3,7 @@ import type { CruxyConfig } from "../config/index.js";
 import type { PromptIO } from "../approval/index.js";
 import { ToolRegistry, type ToolContext } from "../tools/index.js";
 import { type AgentResult } from "../agent/loop.js";
+import type { StreamRenderer } from "../render/index.js";
 import { PlanExecutionPolicy } from "./policy.js";
 /**
  * Orchestrates a plan-mode turn (C.31): propose → approve/revise (capped) →
@@ -32,7 +33,7 @@ export interface PlanSessionArgs {
         dirty: boolean;
     } | null;
     projectInstructions?: string | null;
-    onText?: (delta: string) => void;
+    renderer?: StreamRenderer;
     /** Revision cap (defaults to {@link MAX_PLAN_REVISIONS}). */
     maxRevisions?: number;
 }

package/dist/plan/service.js

@@ -73,7 +73,7 @@ export async function runPlanSession(args) {
             ctx: args.ctx,
             git: args.git,
             projectInstructions: args.projectInstructions,
-            onText: args.onText,
+            renderer: args.renderer,
             planMode: true,
         }));
         if (!holder.plan) {
@@ -105,10 +105,14 @@ export async function runPlanSession(args) {
                     ctx: args.ctx,
                     git: args.git,
                     projectInstructions: args.projectInstructions,
-                    onText: args.onText,
+                    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/capabilities.d.ts

@@ -0,0 +1,12 @@
+import type { RenderCapabilities, RenderStream } from "./types.js";
+/**
+ * Probe the environment once and reduce it to {@link RenderCapabilities}. Pure
+ * given its inputs (stream + env are injectable), so every row of the
+ * degradation matrix is directly testable.
+ *
+ * Color reuses {@link shouldUseColor} (NO_COLOR / FORCE_COLOR / TTY) with one
+ * refinement: `TERM=dumb` terminals get no color even though they are TTYs.
+ * Cursor control and color are independent axes — a NO_COLOR terminal still
+ * supports in-place status updates; a dumb terminal supports neither.
+ */
+export declare function detectCapabilities(stream?: RenderStream, env?: NodeJS.ProcessEnv): RenderCapabilities;

package/dist/render/capabilities.js

@@ -0,0 +1,27 @@
+import { shouldUseColor } from "../errors/index.js";
+/**
+ * Probe the environment once and reduce it to {@link RenderCapabilities}. Pure
+ * given its inputs (stream + env are injectable), so every row of the
+ * degradation matrix is directly testable.
+ *
+ * Color reuses {@link shouldUseColor} (NO_COLOR / FORCE_COLOR / TTY) with one
+ * refinement: `TERM=dumb` terminals get no color even though they are TTYs.
+ * Cursor control and color are independent axes — a NO_COLOR terminal still
+ * supports in-place status updates; a dumb terminal supports neither.
+ */
+export function detectCapabilities(stream = process.stdout, env = process.env) {
+    const tty = Boolean(stream.isTTY);
+    const dumb = env.TERM === "dumb";
+    const cursor = tty && !dumb;
+    return {
+        tty,
+        color: shouldUseColor(stream, env) && !dumb,
+        cursor,
+        // Same set-and-non-empty convention as NO_COLOR: any value disables.
+        spinner: cursor &&
+            !(env.CRUXY_NO_SPINNER !== undefined && env.CRUXY_NO_SPINNER !== ""),
+        width: typeof stream.columns === "number" && stream.columns > 0
+            ? stream.columns
+            : 80,
+    };
+}

package/dist/render/diff.d.ts

@@ -0,0 +1,19 @@
+import pc from "picocolors";
+import type { ActionPreview } from "../tools/types.js";
+/**
+ * The one diff/action-preview renderer (U.2). The approval prompt, PR preview,
+ * and the streaming render path all draw diffs through here — there is no
+ * second implementation to drift. Pure data → string; color is gated on a
+ * picocolors instance, so NO_COLOR/non-TTY callers get symbol-only `+`/`-`
+ * lines from the exact same code path.
+ */
+/** The picocolors instance type (colorless or not), from createColors. */
+export type Colors = ReturnType<typeof pc.createColors>;
+/** Cap on rendered preview lines before collapsing the rest. */
+export declare const PREVIEW_MAX_LINES = 40;
+/**
+ * Render any {@link ActionPreview} as an indented block: a diff for edits and
+ * patches, a create/overwrite listing for writes, the publish plan for PRs.
+ * Long previews collapse past {@link PREVIEW_MAX_LINES}.
+ */
+export declare function renderActionPreview(preview: ActionPreview | undefined, c: Colors): string;

package/dist/render/diff.js

@@ -0,0 +1,107 @@
+/** Cap on rendered preview lines before collapsing the rest. */
+export const PREVIEW_MAX_LINES = 40;
+function diffLines(oldStr, newStr, c) {
+    const removed = oldStr.split("\n").map((l) => c.red(`- ${l}`));
+    const added = newStr.split("\n").map((l) => c.green(`+ ${l}`));
+    return [...removed, ...added];
+}
+function renderPatchFiles(files, c) {
+    const out = [];
+    for (const file of files) {
+        if (file.op === "delete") {
+            out.push(c.red(`delete ${file.path}`));
+        }
+        else if (file.op === "create") {
+            out.push(c.green(`create ${file.path}`));
+            out.push(...file.lines.map((l) => c.green(`+ ${l}`)));
+            if (file.omittedLines > 0)
+                out.push(c.dim(`  ...${file.omittedLines} more lines`));
+        }
+        else {
+            out.push(c.yellow(`update ${file.path}`));
+            for (const hunk of file.hunks)
+                out.push(...diffLines(hunk.oldStr, hunk.newStr, c));
+        }
+    }
+    return out;
+}
+/** Render a `vcs` pull-request publish plan: branch, commit, and PR body. */
+function renderPrPreview(preview, c) {
+    const out = [];
+    out.push(`${c.bold("branch")}  ${c.green(preview.branch)} → ${preview.base}`);
+    out.push("");
+    out.push(c.bold("commit"));
+    out.push(`  ${preview.commitSubject}`);
+    for (const line of bodyLines(preview.commitBody))
+        out.push(c.dim(`  ${line}`));
+    out.push("");
+    out.push(`${c.bold("pull request")}  ${preview.prTitle}`);
+    for (const line of bodyLines(preview.prBody))
+        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");
+    return lines.length === 1 && lines[0] === "" ? [] : lines;
+}
+/**
+ * Render any {@link ActionPreview} as an indented block: a diff for edits and
+ * patches, a create/overwrite listing for writes, the publish plan for PRs.
+ * Long previews collapse past {@link PREVIEW_MAX_LINES}.
+ */
+export function renderActionPreview(preview, c) {
+    if (!preview)
+        return "";
+    let lines;
+    if (preview.type === "edit") {
+        lines = diffLines(preview.oldStr, preview.newStr, c);
+    }
+    else if (preview.type === "patch") {
+        lines = renderPatchFiles(preview.files, 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")
+            : c.green("create");
+        const body = preview.lines.map((l) => `  ${l}`);
+        if (preview.omittedLines > 0)
+            body.push(c.dim(`  ...${preview.omittedLines} more lines`));
+        lines = [header, ...body];
+    }
+    if (lines.length > PREVIEW_MAX_LINES) {
+        const hidden = lines.length - PREVIEW_MAX_LINES;
+        lines = [...lines.slice(0, PREVIEW_MAX_LINES), c.dim(`...${hidden} more`)];
+    }
+    return lines.map((l) => `  ${l}`).join("\n");
+}

package/dist/render/highlight.d.ts

@@ -0,0 +1,47 @@
+import type { Colors } from "./diff.js";
+/**
+ * Best-effort, bounded syntax highlighting for fenced code blocks in streamed
+ * markdown (U.2). Priorities, in order: never crash the stream, never hold the
+ * stream back, then look nice.
+ *
+ * - Prose passes through immediately, byte for byte. The only hold-back is a
+ *   line that is still a plausible fence opener (a leading backtick run), held
+ *   until disambiguated — bounded by one short line, never a block.
+ * - Inside a fence, lines are highlighted incrementally: each line is emitted
+ *   the moment its newline arrives, so latency is one line, and committed
+ *   output is never repainted.
+ * - Unknown language → plain text. A tokenizer throw → that line plain. The
+ *   tokenizer is hand-rolled (no highlighter dependency, in the same spirit as
+ *   the hand-rolled HTTP client) and colors only what it is sure about:
+ *   comments, strings, keywords, numbers.
+ */
+/** Cross-line tokenizer state (block comments / multi-line strings). */
+export interface HighlightCarry {
+    /** Inside a block comment (`/* … *``/`). */
+    blockComment: boolean;
+    /** Inside a multi-line string; the delimiter that will close it. */
+    stringDelim: string | null;
+}
+/** One line of code → styled line + the carry for the next line. */
+export type LineHighlighter = (line: string, lang: string | null, carry: HighlightCarry) => {
+    text: string;
+    carry: HighlightCarry;
+};
+/** Incremental highlighter for one streamed text segment. */
+export interface StreamHighlighter {
+    /** Feed a delta; returns the styled text that is safe to emit now. */
+    push(delta: string): string;
+    /** Return whatever is still held (segment end); resets to prose state. */
+    flush(): string;
+}
+/**
+ * Create the per-segment streaming highlighter. `highlightLine` is injectable
+ * for tests (e.g. to prove a throwing tokenizer degrades to plain text).
+ */
+export declare function createStreamHighlighter(c: Colors, highlightLine?: LineHighlighter): StreamHighlighter;
+/**
+ * Build the default per-line tokenizer over `c`. A plain left-to-right scan:
+ * comments dim, strings green, keywords magenta, numbers yellow, everything
+ * else untouched. Unknown language → identity.
+ */
+export declare function defaultLineHighlighter(c: Colors): LineHighlighter;