@cruxy/cli 0.7.0 → 0.9.0

package/dist/checkpoint/service.js

@@ -0,0 +1,276 @@
+import { randomBytes } from "node:crypto";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { checkpointFailed, checkpointNotFound, rollbackApprovalRequired, CruxyError, } from "../errors/index.js";
+import { logger } from "../utils/logger.js";
+import { runGitCapture } from "../vcs/git.js";
+import { captureFiles } from "./capture.js";
+import { GitCheckpointStore } from "./git-store.js";
+import { ShadowCheckpointStore } from "./shadow-store.js";
+import { applyRollback, buildRollbackPreview, computeRollbackPlan, } from "./restore.js";
+/** Is `root` inside a git working tree? (Decides the checkpoint substrate.) */
+export function isGitWorkTree(root) {
+    const res = runGitCapture(["rev-parse", "--is-inside-work-tree"], root);
+    return res.ok && res.stdout.trim() === "true";
+}
+/**
+ * The substrate factory: git-object store inside a repo, shadow store outside.
+ * Pass `kind` to pin the substrate (rollback must read a checkpoint back with
+ * the store that wrote it, recorded in its manifest).
+ */
+export function createCheckpointStore(root, kind) {
+    const resolved = kind ?? (isGitWorkTree(root) ? "git" : "shadow");
+    return resolved === "git"
+        ? new GitCheckpointStore(root)
+        : new ShadowCheckpointStore(root);
+}
+/**
+ * Checkpoint lifecycle (C.32): create once before a run's first mutation,
+ * record what the run touches, list/prune, and drive the gated rollback.
+ * Manifests are JSON under `.cruxy/checkpoints/` — they survive process exit,
+ * so `cruxy rollback` works in a later invocation.
+ */
+export class CheckpointService {
+    root;
+    config;
+    pinnedStore;
+    runSummary = "agent run";
+    active = null;
+    constructor(opts) {
+        this.root = path.resolve(opts.root);
+        this.config = opts.config;
+        this.pinnedStore = opts.store;
+    }
+    /** Start a new undo unit: reset the once-per-run latch and name the run. */
+    beginRun(summary) {
+        this.active = null;
+        const firstLine = summary.split("\n", 1)[0].trim();
+        this.runSummary =
+            firstLine.length > 80
+                ? `${firstLine.slice(0, 79)}…`
+                : firstLine || "agent run";
+    }
+    /**
+     * The auto-checkpoint hook, called from the approval seam after every allowed
+     * mutating action and latched to fire once per run — before the first
+     * mutation ever reaches disk. Returns the run's checkpoint, or `null` when
+     * the feature is disabled. Fail-loud: if a checkpoint cannot be written by
+     * either substrate, the run must not mutate without its undo protection.
+     */
+    async ensureCheckpoint() {
+        if (!this.config.checkpoint.enabled)
+            return null;
+        if (this.active)
+            return this.active;
+        const gitWorkTree = this.pinnedStore
+            ? this.pinnedStore.kind === "git"
+            : isGitWorkTree(this.root);
+        let store = this.pinnedStore ??
+            createCheckpointStore(this.root, gitWorkTree ? "git" : "shadow");
+        let entries;
+        try {
+            entries = await store.snapshot(await captureFiles(this.root, gitWorkTree));
+        }
+        catch (err) {
+            // Git plumbing failed mid-snapshot → shadow-copy fallback (the manifest
+            // records which substrate actually wrote the checkpoint). A pinned store
+            // (tests) never falls back; a shadow failure has nowhere left to go.
+            if (store.kind !== "git" || this.pinnedStore) {
+                throw CruxyError.is(err)
+                    ? err
+                    : checkpointFailed("snapshotting the working tree failed", err);
+            }
+            logger.warn(`git-backed checkpoint failed (${err.message}); falling back to a shadow copy`);
+            store = new ShadowCheckpointStore(this.root);
+            entries = await store.snapshot(await captureFiles(this.root, false));
+        }
+        const checkpoint = {
+            id: newCheckpointId(),
+            createdAt: new Date().toISOString(),
+            runSummary: this.runSummary,
+            store: store.kind,
+            files: entries,
+            touchedPaths: [],
+            hasShellMutations: false,
+        };
+        await this.writeManifest(checkpoint);
+        await this.prune();
+        this.active = checkpoint;
+        logger.debug(`checkpoint ${checkpoint.id} created (${entries.length} files, ${store.kind} store)`);
+        return checkpoint;
+    }
+    /** Attribute mutated paths to the current run (persisted for later rollback). */
+    async recordTouched(absPaths) {
+        if (!this.active || absPaths.length === 0)
+            return;
+        const known = new Set(this.active.touchedPaths);
+        let added = false;
+        for (const abs of absPaths) {
+            const rel = path.relative(this.root, abs).split(path.sep).join("/");
+            if (rel === "" || rel.startsWith("..") || known.has(rel))
+                continue;
+            known.add(rel);
+            this.active.touchedPaths.push(rel);
+            added = true;
+        }
+        if (added)
+            await this.writeManifest(this.active);
+    }
+    /** The run ran a shell command: per-path attribution is no longer possible. */
+    async recordShellMutation() {
+        if (!this.active || this.active.hasShellMutations)
+            return;
+        this.active.hasShellMutations = true;
+        await this.writeManifest(this.active);
+    }
+    /** All checkpoints, newest first. Corrupt manifests are warned about, not fatal. */
+    async list() {
+        let names;
+        try {
+            names = await fsp.readdir(this.dir());
+        }
+        catch {
+            return []; // no checkpoints dir yet
+        }
+        const checkpoints = [];
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            try {
+                checkpoints.push(await this.readManifestFile(path.join(this.dir(), name)));
+            }
+            catch (err) {
+                logger.warn(`skipping unreadable checkpoint manifest ${name}: ${err.message}`);
+            }
+        }
+        checkpoints.sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id));
+        return checkpoints;
+    }
+    /** One checkpoint by id, or the newest when `id` is omitted. Fail-loud. */
+    async read(id) {
+        if (id === undefined) {
+            const newest = (await this.list())[0];
+            if (!newest)
+                throw checkpointNotFound();
+            return newest;
+        }
+        const file = path.join(this.dir(), `${id}.json`);
+        try {
+            await fsp.access(file);
+        }
+        catch {
+            throw checkpointNotFound(id);
+        }
+        return this.readManifestFile(file);
+    }
+    /**
+     * The whole gated restore: preview → U.3 destructive approval → apply.
+     * Non-interactive callers are refused up front — there is no auto-rollback.
+     */
+    async rollback(id, deps) {
+        if (!deps.interactive)
+            throw rollbackApprovalRequired();
+        const checkpoint = await this.read(id);
+        const store = this.pinnedStore ?? createCheckpointStore(this.root, checkpoint.store);
+        const plan = await computeRollbackPlan(this.root, checkpoint, store, isGitWorkTree(this.root));
+        if (plan.entries.length === 0)
+            return { kind: "noop", checkpoint };
+        const preview = await buildRollbackPreview(this.root, plan, store);
+        const decision = await deps.requestApproval({ kind: "rollback", preview });
+        if (!decision.allow) {
+            return { kind: "rejected", feedback: decision.feedback };
+        }
+        const applied = await applyRollback(this.root, plan, store);
+        return { kind: "applied", checkpoint, applied };
+    }
+    /** Enforce `checkpoint.retention`: drop oldest manifests, then GC content. */
+    async prune() {
+        const all = await this.list();
+        const doomed = all.slice(this.config.checkpoint.retention);
+        if (doomed.length === 0)
+            return;
+        for (const checkpoint of doomed) {
+            await fsp.rm(path.join(this.dir(), `${checkpoint.id}.json`), {
+                force: true,
+            });
+        }
+        const survivors = all.slice(0, this.config.checkpoint.retention);
+        const referenced = new Set(survivors.flatMap((c) => c.files.map((f) => f.oid)));
+        // The shadow pool is ours to sweep; git's dangling objects belong to git gc.
+        await new ShadowCheckpointStore(this.root).collect(referenced);
+    }
+    // ── manifest persistence ────────────────────────────────────────────────────
+    dir() {
+        return path.join(this.root, ".cruxy", "checkpoints");
+    }
+    async writeManifest(checkpoint) {
+        const dir = this.dir();
+        try {
+            await fsp.mkdir(dir, { recursive: true });
+            // Self-ignoring: git never sees checkpoint state, and the user's own
+            // .gitignore is never edited. Written once, only if absent.
+            const ignoreFile = path.join(dir, ".gitignore");
+            try {
+                await fsp.access(ignoreFile);
+            }
+            catch {
+                await fsp.writeFile(ignoreFile, "*\n");
+            }
+            const file = path.join(dir, `${checkpoint.id}.json`);
+            const tmp = `${file}.tmp-${process.pid}`;
+            await fsp.writeFile(tmp, `${JSON.stringify(checkpoint, null, 2)}\n`);
+            await fsp.rename(tmp, file);
+        }
+        catch (err) {
+            throw checkpointFailed(`writing the checkpoint manifest for ${checkpoint.id} failed`, err);
+        }
+    }
+    async readManifestFile(file) {
+        let raw;
+        try {
+            raw = await fsp.readFile(file, "utf8");
+        }
+        catch (err) {
+            throw checkpointFailed(`reading checkpoint manifest ${file} failed`, err);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw checkpointFailed(`checkpoint manifest ${file} is not valid JSON`, err);
+        }
+        if (!isCheckpointShape(parsed)) {
+            throw checkpointFailed(`checkpoint manifest ${file} is malformed`);
+        }
+        return parsed;
+    }
+}
+/** `ck-<utc-stamp>-<rand>` — sortable, collision-safe enough for a local CLI. */
+function newCheckpointId() {
+    const stamp = new Date()
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\..+$/, "");
+    return `ck-${stamp}-${randomBytes(2).toString("hex")}`;
+}
+/** Structural check for a parsed manifest — enough to fail loud on corruption. */
+function isCheckpointShape(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.id === "string" &&
+        typeof v.createdAt === "string" &&
+        typeof v.runSummary === "string" &&
+        (v.store === "git" || v.store === "shadow") &&
+        Array.isArray(v.files) &&
+        v.files.every((f) => typeof f === "object" &&
+            f !== null &&
+            typeof f.path === "string" &&
+            typeof f.oid === "string" &&
+            (f.mode === "100644" ||
+                f.mode === "100755")) &&
+        Array.isArray(v.touchedPaths) &&
+        v.touchedPaths.every((p) => typeof p === "string") &&
+        typeof v.hasShellMutations === "boolean");
+}

package/dist/checkpoint/shadow-store.d.ts

@@ -0,0 +1,23 @@
+import type { CaptureFile, CheckpointStore, FileEntry } from "./types.js";
+/**
+ * Shadow-copy checkpoint content store (C.32 fallback substrate): used outside
+ * a git repo, or when git plumbing fails mid-snapshot. File contents live in a
+ * content-addressed pool at `.cruxy/checkpoints/objects/<sha256>` — identical
+ * content across files or checkpoints is stored once, and pruning sweeps
+ * objects no longer referenced by any surviving manifest.
+ *
+ * Writes are temp-file-then-rename so a crash can never leave a torn object; a
+ * torn *read* is impossible because an object either exists complete or not at
+ * all, and a missing object fails loudly.
+ */
+export declare class ShadowCheckpointStore implements CheckpointStore {
+    readonly kind: "shadow";
+    private readonly objectsDir;
+    constructor(root: string);
+    hashContent(content: Buffer): string;
+    snapshot(files: CaptureFile[]): Promise<FileEntry[]>;
+    readContent(entry: FileEntry): Promise<Buffer>;
+    collect(referenced: ReadonlySet<string>): Promise<void>;
+    /** Content-addressed write: skip if present, else temp-then-rename (atomic). */
+    private writeObject;
+}

package/dist/checkpoint/shadow-store.js

@@ -0,0 +1,93 @@
+import { createHash } from "node:crypto";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { checkpointFailed } from "../errors/index.js";
+/**
+ * Shadow-copy checkpoint content store (C.32 fallback substrate): used outside
+ * a git repo, or when git plumbing fails mid-snapshot. File contents live in a
+ * content-addressed pool at `.cruxy/checkpoints/objects/<sha256>` — identical
+ * content across files or checkpoints is stored once, and pruning sweeps
+ * objects no longer referenced by any surviving manifest.
+ *
+ * Writes are temp-file-then-rename so a crash can never leave a torn object; a
+ * torn *read* is impossible because an object either exists complete or not at
+ * all, and a missing object fails loudly.
+ */
+export class ShadowCheckpointStore {
+    kind = "shadow";
+    objectsDir;
+    constructor(root) {
+        this.objectsDir = path.join(root, ".cruxy", "checkpoints", "objects");
+    }
+    hashContent(content) {
+        return createHash("sha256").update(content).digest("hex");
+    }
+    async snapshot(files) {
+        await fsp.mkdir(this.objectsDir, { recursive: true });
+        const entries = [];
+        for (const file of files) {
+            let content;
+            let stat;
+            try {
+                stat = await fsp.lstat(file.absPath);
+                if (!stat.isFile())
+                    continue; // raced from regular file to something else
+                content = await fsp.readFile(file.absPath);
+            }
+            catch (err) {
+                throw checkpointFailed(`could not read ${file.path} for snapshot`, err);
+            }
+            const oid = this.hashContent(content);
+            await this.writeObject(oid, content);
+            entries.push({
+                path: file.path,
+                mode: stat.mode & 0o100 ? "100755" : "100644",
+                oid,
+            });
+        }
+        return entries;
+    }
+    async readContent(entry) {
+        try {
+            return await fsp.readFile(path.join(this.objectsDir, entry.oid));
+        }
+        catch (err) {
+            throw checkpointFailed(`checkpoint content for ${entry.path} is missing from .cruxy/checkpoints/objects (${entry.oid})`, err);
+        }
+    }
+    async collect(referenced) {
+        let names;
+        try {
+            names = await fsp.readdir(this.objectsDir);
+        }
+        catch {
+            return; // no pool yet — nothing to sweep
+        }
+        for (const name of names) {
+            if (referenced.has(name))
+                continue;
+            // Best-effort: a failed unlink just leaves an unreferenced object behind.
+            await fsp.rm(path.join(this.objectsDir, name), { force: true });
+        }
+    }
+    /** Content-addressed write: skip if present, else temp-then-rename (atomic). */
+    async writeObject(oid, content) {
+        const dest = path.join(this.objectsDir, oid);
+        try {
+            await fsp.access(dest);
+            return; // already stored — content-addressing dedupes for free
+        }
+        catch {
+            /* not present — write it */
+        }
+        const tmp = `${dest}.tmp-${process.pid}-${Date.now()}`;
+        try {
+            await fsp.writeFile(tmp, content);
+            await fsp.rename(tmp, dest);
+        }
+        catch (err) {
+            await fsp.rm(tmp, { force: true });
+            throw checkpointFailed(`could not store checkpoint object ${oid}`, err);
+        }
+    }
+}

package/dist/checkpoint/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Working-tree checkpoints (C.32): a complete snapshot of everything the agent
+ * could touch, captured before a run's first mutation, so `cruxy rollback` can
+ * undo the entire run — creates, edits, deletes — in one gated operation.
+ *
+ * Two layers, deliberately separated:
+ *   • {@link CheckpointStore} — the *content substrate* (where file bytes
+ *     live), swappable like VectorStore: git-object-backed in a repo, a
+ *     content-addressed shadow copy otherwise.
+ *   • The manifest — uniform JSON under `.cruxy/checkpoints/`, owned by the
+ *     service regardless of substrate, so list/prune/rollback never care which
+ *     store wrote a checkpoint.
+ *
+ * Explicit boundary: checkpoints cover WORKING-TREE file state only. They can
+ * never undo git commits, pushes, or PRs made during a run (C.15) — that is
+ * stated in the rollback preview, not silently implied.
+ */
+/** A file selected for capture: project-relative POSIX path + where it is on disk. */
+export interface CaptureFile {
+    path: string;
+    absPath: string;
+}
+/** Which content substrate a checkpoint was written with. */
+export type CheckpointStoreKind = "git" | "shadow";
+/**
+ * One captured file in a checkpoint manifest. `oid` is the content address in
+ * the store that wrote it: a git blob sha-1 for the git store, a sha-256 for
+ * the shadow store. `mode` preserves the executable bit across restore.
+ */
+export interface FileEntry {
+    path: string;
+    mode: "100644" | "100755";
+    oid: string;
+}
+/** A persisted checkpoint: identity, provenance, and the full pre-run manifest. */
+export interface Checkpoint {
+    /** Stable id, e.g. `ck-20260703T141530-a4f2`. */
+    id: string;
+    /** ISO-8601 creation time. */
+    createdAt: string;
+    /** One line describing the run this checkpoint protects. */
+    runSummary: string;
+    store: CheckpointStoreKind;
+    /** Every file that existed (and was capturable) before the run's first mutation. */
+    files: FileEntry[];
+    /**
+     * Project-relative paths the tracked run mutated through file tools, recorded
+     * as the run proceeds. At rollback time, a difference on a path NOT in this
+     * list is an *external* change — surfaced loudly in the preview.
+     */
+    touchedPaths: string[];
+    /**
+     * True when the run executed approved shell commands: a shell command can
+     * touch any path, so per-file attribution becomes impossible and the preview
+     * says so instead of guessing.
+     */
+    hasShellMutations: boolean;
+}
+/**
+ * The content substrate seam. Implementations persist and retrieve file
+ * *contents* only — manifests are the service's job.
+ *
+ * THE invariant (git store): snapshot/read must never disturb user-visible git
+ * state — HEAD, the index, the stash, or any ref. The git store self-checks
+ * this at runtime and fails loudly on drift.
+ */
+export interface CheckpointStore {
+    readonly kind: CheckpointStoreKind;
+    /** Persist the current contents of `files`; returns the manifest entries. */
+    snapshot(files: CaptureFile[]): Promise<FileEntry[]>;
+    /** The content address `snapshot` would give this buffer (for diffing). */
+    hashContent(content: Buffer): string;
+    /** Read one captured file's bytes back. Throws CRUXY_E_CHECKPOINT_FAILED if gone. */
+    readContent(entry: FileEntry): Promise<Buffer>;
+    /**
+     * Best-effort GC after prune: drop stored content whose oid is no longer
+     * referenced by any surviving manifest. The git store is a no-op (dangling
+     * objects belong to git's own gc); the shadow store sweeps its object pool.
+     */
+    collect(referenced: ReadonlySet<string>): Promise<void>;
+}
+/** What rollback will do to one path. */
+export type RollbackAction = 
+/** The run deleted it — recreate from the checkpoint. */
+"recreate"
+/** The run edited it — revert content (and mode) to the checkpoint. */
+ | "revert"
+/** The run created it — delete it. */
+ | "delete";
+export interface RollbackEntry {
+    path: string;
+    action: RollbackAction;
+    /**
+     * True when this path changed since the checkpoint but the tracked run never
+     * touched it — concurrent user (or other-tool) work that rollback would
+     * clobber. Always surfaced in the preview; never overwritten silently.
+     */
+    external: boolean;
+    /** Checkpoint-side content to restore (recreate/revert; absent for delete). */
+    entry?: FileEntry;
+}
+/** The computed diff between the current working tree and a checkpoint. */
+export interface RollbackPlan {
+    checkpoint: Checkpoint;
+    /** Sorted by path; empty means the tree already matches the checkpoint. */
+    entries: RollbackEntry[];
+    /** The `external: true` paths, for the preview's warning block. */
+    externalPaths: string[];
+    /** Mirrors {@link Checkpoint.hasShellMutations}: attribution is unknowable. */
+    attributionUnknown: boolean;
+}
+/** Counts of what a successful rollback actually did. */
+export interface RollbackApplied {
+    recreated: number;
+    reverted: number;
+    deleted: number;
+}

package/dist/checkpoint/types.js

@@ -0,0 +1,18 @@
+/**
+ * Working-tree checkpoints (C.32): a complete snapshot of everything the agent
+ * could touch, captured before a run's first mutation, so `cruxy rollback` can
+ * undo the entire run — creates, edits, deletes — in one gated operation.
+ *
+ * Two layers, deliberately separated:
+ *   • {@link CheckpointStore} — the *content substrate* (where file bytes
+ *     live), swappable like VectorStore: git-object-backed in a repo, a
+ *     content-addressed shadow copy otherwise.
+ *   • The manifest — uniform JSON under `.cruxy/checkpoints/`, owned by the
+ *     service regardless of substrate, so list/prune/rollback never care which
+ *     store wrote a checkpoint.
+ *
+ * Explicit boundary: checkpoints cover WORKING-TREE file state only. They can
+ * never undo git commits, pushes, or PRs made during a run (C.15) — that is
+ * stated in the rollback preview, not silently implied.
+ */
+export {};

package/dist/cli/commands/checkpoint.d.ts

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+/**
+ * `cruxy checkpoint` (C.32) — inspect the working-tree snapshots that back
+ * `cruxy rollback`. Creation is automatic (before a run's first mutation);
+ * this command only lists.
+ */
+export declare function checkpointCommand(): Command;

package/dist/cli/commands/checkpoint.js

@@ -0,0 +1,31 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { loadConfig } from "../../config/index.js";
+import { CheckpointService } from "../../checkpoint/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy checkpoint` (C.32) — inspect the working-tree snapshots that back
+ * `cruxy rollback`. Creation is automatic (before a run's first mutation);
+ * this command only lists.
+ */
+export function checkpointCommand() {
+    const cmd = new Command("checkpoint").description("working-tree checkpoints — the undo units behind `cruxy rollback`");
+    cmd
+        .command("list")
+        .description("list saved checkpoints, newest first")
+        .action(async () => {
+        const { config } = loadConfig();
+        const service = new CheckpointService({ root: process.cwd(), config });
+        const checkpoints = await service.list();
+        if (checkpoints.length === 0) {
+            logger.print(pc.dim("no checkpoints yet — one is created automatically before an agent run's first file change"));
+            return;
+        }
+        for (const c of checkpoints) {
+            const files = `${c.files.length} file${c.files.length === 1 ? "" : "s"}`;
+            logger.print(`${pc.cyan(c.id)}  ${pc.dim(c.createdAt)}  ${pc.dim(`[${c.store}]`)}  ${files}  ${c.runSummary}`);
+        }
+        logger.print(pc.dim(`\nrestore one with \`cruxy rollback <id>\` (or \`cruxy rollback\` for the newest)`));
+    });
+    return cmd;
+}

package/dist/cli/commands/rollback.d.ts

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+/**
+ * `cruxy rollback [id]` (C.32) — restore the working tree to a checkpoint,
+ * undoing everything an agent run changed (creates, edits, deletes) in one
+ * operation. Destructive by definition, so it is preview-first and gated
+ * through U.3 at the destructive tier, ungrantable; non-TTY is refused with a
+ * coded error before anything is computed. Out of scope, stated in the
+ * preview: commits, pushes, and PRs made during the run are not undone.
+ */
+export declare function rollbackCommand(): Command;

package/dist/cli/commands/rollback.js

@@ -0,0 +1,51 @@
+import { Command } from "commander";
+import pc from "picocolors";
+import { loadConfig } from "../../config/index.js";
+import { CheckpointService } from "../../checkpoint/index.js";
+import { ApprovalService, defaultPromptIO } from "../../approval/index.js";
+import { rollbackApprovalRequired, shouldUseColor, } from "../../errors/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy rollback [id]` (C.32) — restore the working tree to a checkpoint,
+ * undoing everything an agent run changed (creates, edits, deletes) in one
+ * operation. Destructive by definition, so it is preview-first and gated
+ * through U.3 at the destructive tier, ungrantable; non-TTY is refused with a
+ * coded error before anything is computed. Out of scope, stated in the
+ * preview: commits, pushes, and PRs made during the run are not undone.
+ */
+export function rollbackCommand() {
+    return new Command("rollback")
+        .description("restore the working tree to a checkpoint, undoing an agent run's file changes")
+        .argument("[id]", "checkpoint id (defaults to the most recent)")
+        .action(async (id) => {
+        const interactive = Boolean(process.stdin.isTTY);
+        // Refuse before touching anything: rollback is a deliberate, interactive
+        // act. There is no flag to bypass this, by design.
+        if (!interactive)
+            throw rollbackApprovalRequired();
+        const { config } = loadConfig();
+        const root = process.cwd();
+        const service = new CheckpointService({ root, config });
+        const approval = new ApprovalService({
+            cwd: root,
+            interactive,
+            io: defaultPromptIO(shouldUseColor()),
+        });
+        const result = await service.rollback(id, {
+            requestApproval: (action) => approval.requestApproval(action),
+            interactive,
+        });
+        if (result.kind === "noop") {
+            logger.print(pc.dim(`working tree already matches checkpoint ${result.checkpoint.id} — nothing to roll back`));
+            return;
+        }
+        if (result.kind === "rejected") {
+            logger.print(pc.dim("rollback declined — nothing was changed"));
+            return;
+        }
+        const { recreated, reverted, deleted } = result.applied;
+        logger.print(`${pc.green("✓")} restored checkpoint ${pc.cyan(result.checkpoint.id)} — ` +
+            `${reverted} reverted, ${recreated} recreated, ${deleted} deleted`);
+        logger.print(pc.dim("note: commits, pushes, and PRs made during the run are not undone"));
+    });
+}