@cruxy/cli 0.8.0 → 0.9.0

package/dist/config/schema.d.ts

@@ -203,6 +203,65 @@ export declare const IndexConfigSchema: z.ZodObject<{
         overlapLines?: number | undefined;
     } | undefined;
 }>;
+/**
+ * Working-tree checkpoints (C.32): a snapshot taken before an agent run's first
+ * file mutation, so `cruxy rollback` can undo the whole run atomically.
+ */
+export declare const CheckpointConfigSchema: z.ZodObject<{
+    /** Auto-checkpoint before a run's first mutation (and enable `cruxy rollback`). */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /** How many checkpoints to keep; older ones are pruned oldest-first. */
+    retention: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    enabled: boolean;
+    retention: number;
+}, {
+    enabled?: boolean | undefined;
+    retention?: number | undefined;
+}>;
+/**
+ * Subagent orchestration (C.14): scoped child agents the main agent can spawn
+ * for bounded subtasks. Every cap here is a hard bound — a subagent can narrow
+ * its budget at spawn time but never exceed these ceilings.
+ */
+export declare const SubagentConfigSchema: z.ZodObject<{
+    /**
+     * Maximum subagent nesting depth. The main agent is depth 0; the default of
+     * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
+     */
+    maxDepth: z.ZodDefault<z.ZodNumber>;
+    /** Per-subagent budget ceilings; spawn-time overrides are clamped to these. */
+    defaultBudget: z.ZodDefault<z.ZodObject<{
+        /** Hard cap on the subagent's model turns. */
+        maxIterations: z.ZodDefault<z.ZodNumber>;
+        /** Hard cap on the subagent's combined input+output tokens. */
+        maxTokens: z.ZodDefault<z.ZodNumber>;
+        /** Optional wall-clock cap; unset means no time limit. */
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        maxTokens: number;
+        maxIterations: number;
+        timeoutMs?: number | undefined;
+    }, {
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        timeoutMs?: number | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    maxDepth: number;
+    defaultBudget: {
+        maxTokens: number;
+        maxIterations: number;
+        timeoutMs?: number | undefined;
+    };
+}, {
+    maxDepth?: number | undefined;
+    defaultBudget?: {
+        maxTokens?: number | undefined;
+        maxIterations?: number | undefined;
+        timeoutMs?: number | undefined;
+    } | undefined;
+}>;
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export declare const McpServerSchema: z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;
@@ -405,6 +464,56 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | undefined;
     }>>;
+    checkpoint: z.ZodDefault<z.ZodObject<{
+        /** Auto-checkpoint before a run's first mutation (and enable `cruxy rollback`). */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** How many checkpoints to keep; older ones are pruned oldest-first. */
+        retention: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        retention: number;
+    }, {
+        enabled?: boolean | undefined;
+        retention?: number | undefined;
+    }>>;
+    subagent: z.ZodDefault<z.ZodObject<{
+        /**
+         * Maximum subagent nesting depth. The main agent is depth 0; the default of
+         * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
+         */
+        maxDepth: z.ZodDefault<z.ZodNumber>;
+        /** Per-subagent budget ceilings; spawn-time overrides are clamped to these. */
+        defaultBudget: z.ZodDefault<z.ZodObject<{
+            /** Hard cap on the subagent's model turns. */
+            maxIterations: z.ZodDefault<z.ZodNumber>;
+            /** Hard cap on the subagent's combined input+output tokens. */
+            maxTokens: z.ZodDefault<z.ZodNumber>;
+            /** Optional wall-clock cap; unset means no time limit. */
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+        }, "strict", z.ZodTypeAny, {
+            maxTokens: number;
+            maxIterations: number;
+            timeoutMs?: number | undefined;
+        }, {
+            maxTokens?: number | undefined;
+            maxIterations?: number | undefined;
+            timeoutMs?: number | undefined;
+        }>>;
+    }, "strict", z.ZodTypeAny, {
+        maxDepth: number;
+        defaultBudget: {
+            maxTokens: number;
+            maxIterations: number;
+            timeoutMs?: number | undefined;
+        };
+    }, {
+        maxDepth?: number | undefined;
+        defaultBudget?: {
+            maxTokens?: number | undefined;
+            maxIterations?: number | undefined;
+            timeoutMs?: number | undefined;
+        } | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -471,6 +580,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines: number;
         };
     };
+    checkpoint: {
+        enabled: boolean;
+        retention: number;
+    };
+    subagent: {
+        maxDepth: number;
+        defaultBudget: {
+            maxTokens: number;
+            maxIterations: number;
+            timeoutMs?: number | undefined;
+        };
+    };
     mcpServers: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;
@@ -529,6 +650,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | undefined;
     } | undefined;
+    checkpoint?: {
+        enabled?: boolean | undefined;
+        retention?: number | undefined;
+    } | undefined;
+    subagent?: {
+        maxDepth?: number | undefined;
+        defaultBudget?: {
+            maxTokens?: number | undefined;
+            maxIterations?: number | undefined;
+            timeoutMs?: number | undefined;
+        } | undefined;
+    } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;
         args?: string[] | undefined;

package/dist/config/schema.js

@@ -137,6 +137,44 @@ export const IndexConfigSchema = z
         .default({}),
 })
     .strict();
+/**
+ * Working-tree checkpoints (C.32): a snapshot taken before an agent run's first
+ * file mutation, so `cruxy rollback` can undo the whole run atomically.
+ */
+export const CheckpointConfigSchema = z
+    .object({
+    /** Auto-checkpoint before a run's first mutation (and enable `cruxy rollback`). */
+    enabled: z.boolean().default(true),
+    /** How many checkpoints to keep; older ones are pruned oldest-first. */
+    retention: z.number().int().positive().default(10),
+})
+    .strict();
+/**
+ * Subagent orchestration (C.14): scoped child agents the main agent can spawn
+ * for bounded subtasks. Every cap here is a hard bound — a subagent can narrow
+ * its budget at spawn time but never exceed these ceilings.
+ */
+export const SubagentConfigSchema = z
+    .object({
+    /**
+     * Maximum subagent nesting depth. The main agent is depth 0; the default of
+     * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
+     */
+    maxDepth: z.number().int().nonnegative().default(1),
+    /** Per-subagent budget ceilings; spawn-time overrides are clamped to these. */
+    defaultBudget: z
+        .object({
+        /** Hard cap on the subagent's model turns. */
+        maxIterations: z.number().int().positive().default(10),
+        /** Hard cap on the subagent's combined input+output tokens. */
+        maxTokens: z.number().int().positive().default(32000),
+        /** Optional wall-clock cap; unset means no time limit. */
+        timeoutMs: z.number().int().positive().optional(),
+    })
+        .strict()
+        .default({}),
+})
+    .strict();
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export const McpServerSchema = z
     .object({
@@ -156,6 +194,8 @@ export const CruxyConfigSchema = z
     context: ContextConfigSchema.default({}),
     approval: ApprovalConfigSchema.default({}),
     index: IndexConfigSchema.default({}),
+    checkpoint: CheckpointConfigSchema.default({}),
+    subagent: SubagentConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

package/dist/errors/constructors.d.ts

@@ -53,6 +53,31 @@ export declare function planRevisionLimit(limit: number): CruxyError;
  * tell it apart from a per-action approval requirement.
  */
 export declare function planApprovalRequired(): CruxyError;
+/**
+ * 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 declare function checkpointFailed(reason: string, underlying?: unknown): CruxyError;
+/** The requested checkpoint id doesn't exist (or no checkpoints exist at all). */
+export declare function checkpointNotFound(id?: string): CruxyError;
+/**
+ * Rollback needs interactive approval but cruxy is running non-interactively.
+ * Restoring is destructive and deliberate — there is no auto-rollback path, ever.
+ */
+export declare function rollbackApprovalRequired(): CruxyError;
+/**
+ * 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 declare function subagentDepthExceeded(depth: number, maxDepth: number): CruxyError;
+/**
+ * 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 declare function subagentFailed(underlying?: unknown): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed

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.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")