@cruxy/cli 0.8.0 → 0.9.0

package/README.md

@@ -116,6 +116,33 @@ before anything runs. On a protected branch (`main`/`master`/configured via
 `git.protectedBranches`) cruxy branches off first; the base defaults to
 `git.defaultBase`, then the repo's default branch, then `main`.
 
+### Checkpoints & rollback
+
+Before an agent run's first file mutation, cruxy snapshots the working tree
+(tracked + untracked non-ignored files; gitignored paths and the secrets
+denylist are never captured). `cruxy rollback` undoes the whole run — creates,
+edits, deletes — in one operation:
+
+```bash
+cruxy checkpoint list        # saved checkpoints, newest first
+cruxy rollback               # restore the most recent checkpoint
+cruxy rollback <id>          # restore a specific one
+```
+
+Rollback is destructive, so it previews exactly what will change (including
+anything that changed _outside_ the run — surfaced, never silently clobbered)
+and always asks for approval; it cannot be session-granted and refuses to run
+non-interactively (`CRUXY_E_ROLLBACK_APPROVAL_REQUIRED`).
+
+In a git repo, snapshots go into the git object database via a temporary index
+— HEAD, your index, the stash, and every ref are untouched, and nothing shows
+up in `git status`. Outside a repo, a content-addressed shadow copy under
+`.cruxy/checkpoints/` is used. Retention is bounded (`checkpoint.retention`,
+default 10; disable with `checkpoint.enabled = false`).
+
+**Boundary:** checkpoints cover working-tree files only. Commits, pushes, and
+PRs made during a run are never undone — the rollback preview says so.
+
 ## Errors & exit codes
 
 Every user-facing error prints a title, the cause (when known), concrete next
@@ -124,19 +151,19 @@ steps, and a stable code (e.g. `CRUXY_E_GATEWAY_UNREACHABLE`). Pass `--verbose`
 `NO_COLOR` disables color. Exit codes are stable per category, so scripts can
 branch on them:
 
-| Exit | Category   | Example codes                                                                                                                                                        |
-| ---- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `0`  | success    | —                                                                                                                                                                    |
-| `1`  | internal   | `CRUXY_E_INTERNAL`                                                                                                                                                   |
-| `2`  | usage      | `CRUXY_E_USAGE`, `CRUXY_E_CONFIG_KEY_UNKNOWN`, `CRUXY_E_PROVIDER_UNSUPPORTED`, `CRUXY_E_GIT_PROTECTED_BRANCH`, `CRUXY_E_PLAN_INVALID`, `CRUXY_E_PLAN_REVISION_LIMIT` |
-| `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`                                                                                                                     |
-| `4`  | auth       | `CRUXY_E_AUTH_MISSING_KEY`, `CRUXY_E_AUTH_INVALID`, `CRUXY_E_FORGE_AUTH`                                                                                             |
-| `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`, `CRUXY_E_GIT_PUSH_FAILED`                                                                                                             |
-| `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`, `CRUXY_E_FORGE_API`                                                   |
-| `7`  | filesystem | `CRUXY_E_FILE_NOT_FOUND`, `CRUXY_E_PERMISSION_DENIED`, `CRUXY_E_PATH_ESCAPE`                                                                                         |
-| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED`                                                                      |
-| `9`  | skill      | `CRUXY_E_SKILL_INVALID`, `CRUXY_E_SKILL_NOT_FOUND`                                                                                                                   |
-| `10` | approval   | `CRUXY_E_APPROVAL_REQUIRED`, `CRUXY_E_PLAN_APPROVAL_REQUIRED`                                                                                                        |
+| Exit | Category   | Example codes                                                                                                                                                                                        |
+| ---- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0`  | success    | —                                                                                                                                                                                                    |
+| `1`  | internal   | `CRUXY_E_INTERNAL`                                                                                                                                                                                   |
+| `2`  | usage      | `CRUXY_E_USAGE`, `CRUXY_E_CONFIG_KEY_UNKNOWN`, `CRUXY_E_PROVIDER_UNSUPPORTED`, `CRUXY_E_GIT_PROTECTED_BRANCH`, `CRUXY_E_PLAN_INVALID`, `CRUXY_E_PLAN_REVISION_LIMIT`, `CRUXY_E_CHECKPOINT_NOT_FOUND` |
+| `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`                                                                                                                                                     |
+| `4`  | auth       | `CRUXY_E_AUTH_MISSING_KEY`, `CRUXY_E_AUTH_INVALID`, `CRUXY_E_FORGE_AUTH`                                                                                                                             |
+| `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`, `CRUXY_E_GIT_PUSH_FAILED`                                                                                                                                             |
+| `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`, `CRUXY_E_FORGE_API`                                                                                   |
+| `7`  | filesystem | `CRUXY_E_FILE_NOT_FOUND`, `CRUXY_E_PERMISSION_DENIED`, `CRUXY_E_PATH_ESCAPE`, `CRUXY_E_CHECKPOINT_FAILED`                                                                                            |
+| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED`                                                                                                      |
+| `9`  | skill      | `CRUXY_E_SKILL_INVALID`, `CRUXY_E_SKILL_NOT_FOUND`                                                                                                                                                   |
+| `10` | approval   | `CRUXY_E_APPROVAL_REQUIRED`, `CRUXY_E_PLAN_APPROVAL_REQUIRED`, `CRUXY_E_ROLLBACK_APPROVAL_REQUIRED`                                                                                                  |
 
 The LLM client is [`@cruxy/sdk`](https://www.npmjs.com/package/@cruxy/sdk) —
 provider-agnostic, built over `fetch`, with no vendor SDKs.

package/dist/agent/loop.d.ts

@@ -34,6 +34,31 @@ export interface RunAgentArgs {
     projectInstructions?: string | null;
     /** Plan mode's propose phase (C.31): inject the plan-first system directive. */
     planMode?: boolean;
+    /** Subagent runs (C.14): inject the bounded-subtask system directive. */
+    subagent?: boolean;
+    /**
+     * Optional hard budget (C.14): checked before every model turn; a non-null
+     * reason stops the loop with `stop: "budget"` and the partial history. The
+     * in-flight turn (model call + its tool executions) always completes, so
+     * histories stay coherent — overshoot is bounded by one turn.
+     */
+    budget?: LoopBudget;
+}
+/**
+ * The budget seam for {@link runAgent}: implementations track their own caps
+ * (iterations, tokens, wall clock — see `subagent/budget.ts`); the loop only
+ * asks "may I start another turn?". Kept a one-method interface so future
+ * callers (C.22 cost tracking) can slot in without touching the loop again.
+ */
+export interface LoopBudget {
+    /**
+     * Return a human-readable reason to stop *before* the next model turn, or
+     * `null` to continue. `iterations` = model turns completed so far.
+     */
+    exceeded(state: {
+        iterations: number;
+        usage: Usage;
+    }): string | null;
 }
 export interface AgentResult {
     /** The full conversation, including assistant tool calls and tool results. */
@@ -41,7 +66,9 @@ export interface AgentResult {
     /** Number of model turns consumed. */
     iterations: number;
     /** Why the loop ended. */
-    stop: "completed" | "max_iterations";
+    stop: "completed" | "max_iterations" | "budget";
+    /** Which cap tripped, when `stop === "budget"` (from {@link LoopBudget}). */
+    stopReason?: string;
     /** Accumulated token usage (stashed for cost tracking in C.22). */
     usage: Usage;
 }

package/dist/agent/loop.js

@@ -46,9 +46,23 @@ async function driveLoop(args, renderer) {
         git: args.git ?? null,
         projectInstructions: args.projectInstructions ?? null,
         planMode: args.planMode ?? false,
+        subagent: args.subagent ?? false,
     });
     let iterations = 0;
     for (let i = 0; i < maxIterations; i++) {
+        // Budget check before committing to another model turn (C.14): a tripped
+        // cap returns the history as it stands — always at a clean turn boundary,
+        // because the previous iteration fully resolved its tool calls.
+        const budgetReason = args.budget?.exceeded({ iterations, usage }) ?? null;
+        if (budgetReason !== null) {
+            return {
+                messages,
+                iterations,
+                stop: "budget",
+                stopReason: budgetReason,
+                usage,
+            };
+        }
         iterations = i + 1;
         const tools = registry.toToolSpecs();
         // ── Consume one model turn ──────────────────────────────────────────────
@@ -56,7 +70,14 @@ async function driveLoop(args, renderer) {
         const pending = new Map();
         const toolUses = [];
         // Live progress while waiting on the model; dismissed by the first delta.
-        renderer?.status("thinking…");
+        // Token context is whatever the loop has actually accumulated (U.4): zero
+        // on the first turn → no figure shown, never a fabricated number.
+        renderer?.setPhase({
+            kind: "thinking",
+            tokens: usage.input_tokens + usage.output_tokens > 0
+                ? { input: usage.input_tokens, output: usage.output_tokens }
+                : undefined,
+        });
         for await (const ev of provider.stream({
             system,
             messages,
@@ -121,9 +142,12 @@ async function driveLoop(args, renderer) {
         const toolResults = [];
         for (const call of toolUses) {
             const label = describeToolCall(call);
-            renderer?.status(`${label}…`);
+            // Semantic lifecycle (U.4): start paints the live state (+ elapsed on
+            // long calls), end commits the ✓/✗ trail note. Same information as the
+            // old status/note pair, now typed and duration-aware.
+            renderer?.toolLifecycle({ event: "start", label });
             const result = await runToolCall(call, registry, ctx);
-            renderer?.note(`${result.is_error ? "✗" : "✓"} ${label}`);
+            renderer?.toolLifecycle({ event: "end", label, ok: !result.is_error });
             toolResults.push(result);
         }
         messages.push({ role: "user", content: toolResults });
@@ -132,7 +156,15 @@ async function driveLoop(args, renderer) {
     return { messages, iterations, stop: "max_iterations", usage };
 }
 /** Input keys worth surfacing in tool-call chrome, in preference order. */
-const HINT_KEYS = ["path", "file_path", "command", "pattern", "query", "url"];
+const HINT_KEYS = [
+    "path",
+    "file_path",
+    "command",
+    "pattern",
+    "query",
+    "url",
+    "task",
+];
 /** Longest hint shown before truncation — chrome, not information of record. */
 const HINT_MAX = 60;
 /**

package/dist/agent/prompts.d.ts

@@ -30,6 +30,8 @@ export interface PromptContext {
     projectInstructions?: string | null;
     /** Plan mode's propose phase (C.31): inject the plan-first directive. */
     planMode?: boolean;
+    /** Subagent run (C.14): inject the bounded-subtask directive. */
+    subagent?: boolean;
 }
 /** Assemble the full system prompt for a session. */
 export declare function buildSystemPrompt(ctx: PromptContext): string;

package/dist/agent/prompts.js

@@ -10,6 +10,12 @@
 const PLAN_MODE_SECTION = `## Plan mode
 You are in plan mode. Do NOT edit files, run commands, or take any side-effecting action yet.
 First investigate with the read-only tools if you need to, then call \`submit_plan\` with an ordered list of steps — each with a title, a one-line rationale, and a kind (read | mutate | destructive). Cover the whole task; keep steps concrete and minimal. After you call \`submit_plan\`, stop and end your turn — the user reviews and approves the plan before you execute it.`;
+/** The subagent directive (C.14), injected only into a spawned subagent's runs. */
+const SUBAGENT_SECTION = `## Subagent context
+You are a subagent: a scoped worker handling ONE bounded subtask for a parent agent, under a hard iteration and token budget. Only your final message is returned to the parent — its transcript does not include your intermediate steps. Therefore:
+- Stay strictly within the given subtask; do not expand scope or start follow-on work.
+- Work efficiently — prefer few, well-chosen tool calls over exhaustive exploration.
+- End with a concise, self-contained summary of what you found or changed (concrete file paths, identifiers, outcomes). That summary IS your deliverable.`;
 /**
  * The static core of cruxy's behaviour. Phrased as direct instruction to the
  * model. Keep this tight — every line earns its place; vague prose dilutes the
@@ -80,6 +86,8 @@ export function buildSystemPrompt(ctx) {
     const sections = [core, renderEnvironment(ctx), renderTools(ctx.tools)];
     if (ctx.planMode)
         sections.push(PLAN_MODE_SECTION);
+    if (ctx.subagent)
+        sections.push(SUBAGENT_SECTION);
     if (ctx.projectInstructions?.trim()) {
         sections.push(`## Project instructions\nThe following came from this project's configuration; honor it unless it conflicts with the rules above:\n\n${ctx.projectInstructions.trim()}`);
     }

package/dist/approval/classify.js

@@ -18,6 +18,8 @@ export function classify(action, cwd) {
             return shellRequest(action, root);
         case "vcs":
             return vcsRequest(action, root);
+        case "rollback":
+            return rollbackRequest(action, root);
         default:
             return {
                 action,
@@ -85,6 +87,30 @@ function vcsRequest(action, root) {
         cwd: root,
     };
 }
+// ── rollback (restore checkpoint) ──────────────────────────────────────────────
+/**
+ * A checkpoint restore (C.32): overwrite the working tree with a pre-run
+ * snapshot. Always `destructive` (it reverts edits, deletes created files, and
+ * recreates deleted ones in one operation) and never session-grantable — scope
+ * `none`, so every rollback is a deliberate, one-off approval. The preview
+ * carries the full blast radius; the summary names the checkpoint.
+ */
+function rollbackRequest(action, root) {
+    const preview = action.preview?.type === "rollback" ? action.preview : undefined;
+    const summary = preview
+        ? `rollback: restore checkpoint ${preview.checkpointId} (${preview.files.length} file${preview.files.length === 1 ? "" : "s"})`
+        : "rollback: restore a checkpoint";
+    return {
+        action,
+        tier: "destructive",
+        scope: { kind: "none" },
+        summary,
+        targets: preview
+            ? preview.files.map((f) => path.resolve(root, f.path))
+            : [],
+        cwd: root,
+    };
+}
 // ── file (write / edit / patch) ────────────────────────────────────────────────
 function fileRequest(action, tier, root) {
     const targets = fileTargets(action, root);

package/dist/checkpoint/capture.d.ts

@@ -0,0 +1,17 @@
+import type { CaptureFile } from "./types.js";
+/**
+ * Snapshot-scope enumeration (C.32): every regular file the agent could touch —
+ * tracked + untracked-non-ignored — and nothing it must never see:
+ *   • gitignored paths (they are not the run's undo unit and may be huge),
+ *   • the C.17 secrets denylist ({@link isSecretPath} — a checkpoint must never
+ *     copy a secret into `.cruxy/` or the git object DB),
+ *   • `.cruxy/` itself (a checkpoint of the checkpoints would recurse),
+ *   • symlinks and other non-regular files (restore writes plain files only).
+ *
+ * In a git repo the file list comes from `git ls-files` (read-only), which
+ * honors `.gitignore`, `.git/info/exclude`, and the user's global excludes
+ * exactly. Outside a repo, the indexing walker enumerates with its gitignore
+ * emulation — with binaries included and no size cap, because a snapshot that
+ * skips files cannot restore them.
+ */
+export declare function captureFiles(root: string, gitWorkTree: boolean): Promise<CaptureFile[]>;

package/dist/checkpoint/capture.js

@@ -0,0 +1,73 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { runGitCapture } from "../vcs/git.js";
+import { isSecretPath, walkRepo } from "../indexing/walker.js";
+import { GLOBAL_DIR_NAME } from "../constants.js";
+/**
+ * Snapshot-scope enumeration (C.32): every regular file the agent could touch —
+ * tracked + untracked-non-ignored — and nothing it must never see:
+ *   • gitignored paths (they are not the run's undo unit and may be huge),
+ *   • the C.17 secrets denylist ({@link isSecretPath} — a checkpoint must never
+ *     copy a secret into `.cruxy/` or the git object DB),
+ *   • `.cruxy/` itself (a checkpoint of the checkpoints would recurse),
+ *   • symlinks and other non-regular files (restore writes plain files only).
+ *
+ * In a git repo the file list comes from `git ls-files` (read-only), which
+ * honors `.gitignore`, `.git/info/exclude`, and the user's global excludes
+ * exactly. Outside a repo, the indexing walker enumerates with its gitignore
+ * emulation — with binaries included and no size cap, because a snapshot that
+ * skips files cannot restore them.
+ */
+export async function captureFiles(root, gitWorkTree) {
+    const absRoot = path.resolve(root);
+    const candidates = gitWorkTree
+        ? await gitCandidates(absRoot)
+        : await walkerCandidates(absRoot);
+    const files = [];
+    for (const relPath of candidates) {
+        if (relPath === "" || isExcluded(relPath))
+            continue;
+        const absPath = path.join(absRoot, ...relPath.split("/"));
+        // lstat: a symlink must be seen as a symlink, not its target.
+        let stat;
+        try {
+            stat = await fsp.lstat(absPath);
+        }
+        catch {
+            continue; // listed but gone (e.g. tracked file deleted from the worktree)
+        }
+        if (!stat.isFile())
+            continue;
+        files.push({ path: relPath, absPath });
+    }
+    files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return files;
+}
+/** Never capture cruxy's own state dir or a secret-bearing path. */
+function isExcluded(relPath) {
+    return (relPath === GLOBAL_DIR_NAME ||
+        relPath.startsWith(`${GLOBAL_DIR_NAME}/`) ||
+        isSecretPath(relPath));
+}
+/** Tracked + untracked-non-ignored, straight from git (paths relative to root). */
+async function gitCandidates(absRoot) {
+    const res = runGitCapture(["ls-files", "-z", "--cached", "--others", "--exclude-standard"], absRoot);
+    if (!res.ok) {
+        // The caller decided this is a work tree; a failing ls-files means git is
+        // in a state we can't reason about — let the store fallback handle it.
+        throw new Error(`git ls-files failed: ${res.stderr.trim()}`);
+    }
+    // -z output: NUL-separated, no quoting, trailing NUL yields one empty entry.
+    return [...new Set(res.stdout.split("\0"))];
+}
+/** Walker enumeration for non-git dirs: gitignore-style ignores, no content filters. */
+async function walkerCandidates(absRoot) {
+    const out = [];
+    for await (const entry of walkRepo(absRoot, {
+        maxFileBytes: Number.MAX_SAFE_INTEGER,
+        includeBinary: true,
+    })) {
+        out.push(entry.relPath);
+    }
+    return out;
+}

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

@@ -0,0 +1,61 @@
+import type { CaptureFile, CheckpointStore, FileEntry } from "./types.js";
+/**
+ * Git-object-backed checkpoint content store (C.32 primary substrate).
+ *
+ * How a snapshot works — and exactly why it can never disturb the user's git
+ * state. Every git invocation is one of these five, and nothing else:
+ *
+ *   1. `git rev-parse --absolute-git-dir`          (read-only)
+ *   2. `git update-index --add -z --stdin`, with `GIT_INDEX_FILE` pointing at a
+ *      **temporary index file in os.tmpdir()**. Git hashes each captured file
+ *      into `.git/objects` as loose blobs and stages them *in the temp index*.
+ *      The user's `.git/index` is never opened for writing.
+ *   3. `git write-tree`, same `GIT_INDEX_FILE` — writes tree objects, returns
+ *      the root tree oid.
+ *   4. `git ls-files --stage -z`, same `GIT_INDEX_FILE` — reads back
+ *      `mode oid stage\tpath` per file for the manifest. The temp index is then
+ *      deleted.
+ *   5. `git cat-file blob <oid>` on restore/preview                (read-only)
+ *
+ * No `commit-tree`, no `update-ref`, no `stash`, no branch: **no ref is ever
+ * created or moved, and HEAD / the index / the stash are never written.** The
+ * blobs and trees are deliberately *dangling* — referenced only by the manifest
+ * JSON under `.cruxy/checkpoints/`.
+ *
+ * Enforced, not assumed: {@link snapshot} fingerprints the user-visible state
+ * (raw `.git/HEAD` bytes, a hash of `.git/index`, `git for-each-ref`, and
+ * `git stash list`) before and after, and throws CRUXY_E_CHECKPOINT_FAILED
+ * naming what moved if anything drifted.
+ *
+ * Accepted trade-off: dangling objects are subject to `git gc --prune`. The
+ * default two-week grace plus retention pruning makes that a non-issue, but a
+ * user running `git gc --prune=now` can orphan a manifest — then rollback fails
+ * loudly (never restores partial state), and the shadow store remains the
+ * fallback substrate for new checkpoints.
+ */
+export declare class GitCheckpointStore implements CheckpointStore {
+    private readonly root;
+    readonly kind: "git";
+    constructor(root: string);
+    /** Git blob sha-1: `sha1("blob <len>\0" + content)` — matches `git hash-object`. */
+    hashContent(content: Buffer): string;
+    snapshot(files: CaptureFile[]): Promise<FileEntry[]>;
+    readContent(entry: FileEntry): Promise<Buffer>;
+    /** Dangling objects belong to git's own gc; nothing for us to sweep. */
+    collect(): Promise<void>;
+    /** Parse `git ls-files --stage -z` from the temp index into manifest entries. */
+    private readStagedEntries;
+    /**
+     * Run git with binary-safe stdout (restore must round-trip arbitrary bytes),
+     * optional stdin, and optional extra env. Local to this store on purpose —
+     * `runGitCapture` is text-mode and env-less, and the rest of the CLI should
+     * stay that way.
+     */
+    private git;
+    /**
+     * Everything a user can observe of their git state, byte-for-byte: HEAD file,
+     * index contents, every ref (branches, tags, remotes, stash tip — packed or
+     * loose, via for-each-ref), and the full stash reflog (stash list).
+     */
+    private fingerprint;
+}

package/dist/checkpoint/git-store.js

@@ -0,0 +1,171 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { promises as fsp, readFileSync, existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { checkpointFailed } from "../errors/index.js";
+import { runGitCapture } from "../vcs/git.js";
+/**
+ * Git-object-backed checkpoint content store (C.32 primary substrate).
+ *
+ * How a snapshot works — and exactly why it can never disturb the user's git
+ * state. Every git invocation is one of these five, and nothing else:
+ *
+ *   1. `git rev-parse --absolute-git-dir`          (read-only)
+ *   2. `git update-index --add -z --stdin`, with `GIT_INDEX_FILE` pointing at a
+ *      **temporary index file in os.tmpdir()**. Git hashes each captured file
+ *      into `.git/objects` as loose blobs and stages them *in the temp index*.
+ *      The user's `.git/index` is never opened for writing.
+ *   3. `git write-tree`, same `GIT_INDEX_FILE` — writes tree objects, returns
+ *      the root tree oid.
+ *   4. `git ls-files --stage -z`, same `GIT_INDEX_FILE` — reads back
+ *      `mode oid stage\tpath` per file for the manifest. The temp index is then
+ *      deleted.
+ *   5. `git cat-file blob <oid>` on restore/preview                (read-only)
+ *
+ * No `commit-tree`, no `update-ref`, no `stash`, no branch: **no ref is ever
+ * created or moved, and HEAD / the index / the stash are never written.** The
+ * blobs and trees are deliberately *dangling* — referenced only by the manifest
+ * JSON under `.cruxy/checkpoints/`.
+ *
+ * Enforced, not assumed: {@link snapshot} fingerprints the user-visible state
+ * (raw `.git/HEAD` bytes, a hash of `.git/index`, `git for-each-ref`, and
+ * `git stash list`) before and after, and throws CRUXY_E_CHECKPOINT_FAILED
+ * naming what moved if anything drifted.
+ *
+ * Accepted trade-off: dangling objects are subject to `git gc --prune`. The
+ * default two-week grace plus retention pruning makes that a non-issue, but a
+ * user running `git gc --prune=now` can orphan a manifest — then rollback fails
+ * loudly (never restores partial state), and the shadow store remains the
+ * fallback substrate for new checkpoints.
+ */
+export class GitCheckpointStore {
+    root;
+    kind = "git";
+    constructor(root) {
+        this.root = root;
+    }
+    /** Git blob sha-1: `sha1("blob <len>\0" + content)` — matches `git hash-object`. */
+    hashContent(content) {
+        return createHash("sha1")
+            .update(`blob ${content.length}\0`)
+            .update(content)
+            .digest("hex");
+    }
+    async snapshot(files) {
+        const before = this.fingerprint();
+        const tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), "cruxy-checkpoint-"));
+        const indexFile = path.join(tmpDir, "index");
+        try {
+            const env = { GIT_INDEX_FILE: indexFile };
+            // Stage every captured path into the temp index (writes blobs).
+            const stdin = files.map((f) => `${f.path}\0`).join("");
+            const add = this.git(["update-index", "--add", "-z", "--stdin"], {
+                env,
+                input: stdin,
+            });
+            if (!add.ok) {
+                throw checkpointFailed(`staging files into the temporary index failed: ${add.stderr.trim()}`);
+            }
+            // Persist the tree objects. The oid itself isn't stored — per-file blob
+            // oids from ls-files --stage are what restore needs — but write-tree is
+            // what makes the whole snapshot a single connected object graph.
+            const tree = this.git(["write-tree"], { env });
+            if (!tree.ok) {
+                throw checkpointFailed(`writing the snapshot tree failed: ${tree.stderr.trim()}`);
+            }
+            const entries = this.readStagedEntries(env);
+            const after = this.fingerprint();
+            assertGitStateUnchanged(before, after);
+            return entries;
+        }
+        finally {
+            await fsp.rm(tmpDir, { recursive: true, force: true });
+        }
+    }
+    async readContent(entry) {
+        const res = this.git(["cat-file", "blob", entry.oid]);
+        if (!res.ok) {
+            throw checkpointFailed(`checkpoint content for ${entry.path} is gone from the git object database ` +
+                `(blob ${entry.oid}) — most likely pruned by \`git gc --prune\``);
+        }
+        return res.stdout;
+    }
+    /** Dangling objects belong to git's own gc; nothing for us to sweep. */
+    async collect() {
+        /* no-op by design */
+    }
+    // ── internals ───────────────────────────────────────────────────────────────
+    /** Parse `git ls-files --stage -z` from the temp index into manifest entries. */
+    readStagedEntries(env) {
+        const res = this.git(["ls-files", "--stage", "-z"], { env });
+        if (!res.ok) {
+            throw checkpointFailed(`reading back the staged snapshot failed: ${res.stderr.trim()}`);
+        }
+        const entries = [];
+        for (const record of res.stdout.toString("utf8").split("\0")) {
+            if (record === "")
+                continue;
+            // "<mode> <oid> <stage>\t<path>"
+            const tab = record.indexOf("\t");
+            const [mode, oid] = record.slice(0, tab).split(" ");
+            const relPath = record.slice(tab + 1);
+            if (mode !== "100644" && mode !== "100755") {
+                // Capture filters to regular files, so anything else staging here is a
+                // bug or a race — refuse to write a manifest we can't faithfully restore.
+                throw checkpointFailed(`unsupported file mode ${mode} for ${relPath} in the snapshot`);
+            }
+            entries.push({ path: relPath, mode, oid });
+        }
+        return entries;
+    }
+    /**
+     * Run git with binary-safe stdout (restore must round-trip arbitrary bytes),
+     * optional stdin, and optional extra env. Local to this store on purpose —
+     * `runGitCapture` is text-mode and env-less, and the rest of the CLI should
+     * stay that way.
+     */
+    git(args, opts = {}) {
+        const res = spawnSync("git", args, {
+            cwd: this.root,
+            windowsHide: true,
+            maxBuffer: 1024 * 1024 * 1024,
+            input: opts.input,
+            env: opts.env ? { ...process.env, ...opts.env } : process.env,
+        });
+        const stdout = Buffer.isBuffer(res.stdout) ? res.stdout : Buffer.alloc(0);
+        const stderr = (res.stderr?.toString("utf8") ?? "") ||
+            (res.error ? res.error.message : "");
+        return { ok: res.status === 0 && !res.error, stdout, stderr };
+    }
+    /**
+     * Everything a user can observe of their git state, byte-for-byte: HEAD file,
+     * index contents, every ref (branches, tags, remotes, stash tip — packed or
+     * loose, via for-each-ref), and the full stash reflog (stash list).
+     */
+    fingerprint() {
+        const gitDirRes = runGitCapture(["rev-parse", "--absolute-git-dir"], this.root);
+        const gitDir = gitDirRes.ok ? gitDirRes.stdout.trim() : "";
+        return {
+            head: readFileOr(path.join(gitDir, "HEAD")),
+            index: hashFileOr(path.join(gitDir, "index")),
+            refs: runGitCapture(["for-each-ref", "--format=%(refname) %(objectname)"], this.root).stdout,
+            stash: runGitCapture(["stash", "list"], this.root).stdout,
+        };
+    }
+}
+function readFileOr(file, fallback = "<absent>") {
+    return existsSync(file) ? readFileSync(file, "utf8") : fallback;
+}
+function hashFileOr(file, fallback = "<absent>") {
+    if (!existsSync(file))
+        return fallback;
+    return createHash("sha256").update(readFileSync(file)).digest("hex");
+}
+/** The runtime self-check: any drift in user-visible git state is a hard failure. */
+function assertGitStateUnchanged(before, after) {
+    const drifted = Object.keys(before).filter((k) => before[k] !== after[k]);
+    if (drifted.length > 0) {
+        throw checkpointFailed(`snapshot invariant violated: user-visible git state changed (${drifted.join(", ")}) — refusing to continue`);
+    }
+}

package/dist/checkpoint/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./capture.js";
+export * from "./git-store.js";
+export * from "./shadow-store.js";
+export * from "./restore.js";
+export * from "./service.js";

package/dist/checkpoint/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./capture.js";
+export * from "./git-store.js";
+export * from "./shadow-store.js";
+export * from "./restore.js";
+export * from "./service.js";

package/dist/checkpoint/restore.d.ts

@@ -0,0 +1,23 @@
+import type { ActionPreview } from "../tools/types.js";
+import type { Checkpoint, CheckpointStore, RollbackApplied, RollbackPlan } from "./types.js";
+/**
+ * Diff the current working tree against a checkpoint by content address.
+ * External attribution: a differing path the tracked run never touched is
+ * flagged `external` — unless the run executed shell commands, in which case
+ * attribution is unknowable and the plan says so instead of guessing.
+ */
+export declare function computeRollbackPlan(root: string, checkpoint: Checkpoint, store: CheckpointStore, gitWorkTree: boolean): Promise<RollbackPlan>;
+/**
+ * Build the U.2 preview for a plan: patch-style entries (byte-identical with
+ * apply_patch previews) plus the external-change and boundary annotations that
+ * `renderActionPreview` places *above* the diff.
+ */
+export declare function buildRollbackPreview(root: string, plan: RollbackPlan, store: CheckpointStore): Promise<Extract<ActionPreview, {
+    type: "rollback";
+}>>;
+/**
+ * Apply a plan: recreate deleted files, revert edited ones (content and mode),
+ * then remove run-created files (and any directories that emptied out). Any
+ * failure is a loud CRUXY_E_CHECKPOINT_FAILED; re-running rollback resumes.
+ */
+export declare function applyRollback(root: string, plan: RollbackPlan, store: CheckpointStore): Promise<RollbackApplied>;