@cruxy/cli 0.7.0 → 0.9.0

package/README.md

@@ -58,6 +58,12 @@ export CRUXY_API_KEY=cxy_live_...   # …or just use an env var (always wins)
   validated, and never auto-executed.
 - **Agent** — streaming output, multi-turn interactive sessions, context
   compaction, and awareness of git state and project instructions (`CRUXY.md`).
+- **Streaming render** — flicker-free live output: a single in-place status line
+  (spinner while the model thinks / tools run), append-only committed text,
+  syntax-highlighted code fences, tool-call notes, and diffs drawn by the same
+  renderer as the approval prompt. Degrades cleanly: piped/CI output is plain
+  append-only text with zero ANSI (chrome on stderr), `NO_COLOR` drops color,
+  and `CRUXY_NO_SPINNER=1` stills the animation.
 - **Plan mode** (opt-in: `cruxy run --plan`, `/plan`, or `agent.planMode`) — the
   agent proposes a structured, step-by-step plan; you approve it once, then it
   executes with live per-step status. Approving consents to the _shape_ of the
@@ -110,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
@@ -118,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

@@ -1,5 +1,6 @@
 import type { Message, Provider, Usage } from "@cruxy/sdk";
 import type { CruxyConfig } from "../config/index.js";
+import type { StreamRenderer } from "../render/index.js";
 import type { ToolContext } from "../tools/index.js";
 import { ToolRegistry } from "../tools/index.js";
 export interface RunAgentArgs {
@@ -17,12 +18,13 @@ export interface RunAgentArgs {
     /** Ambient capabilities handed to each tool. */
     ctx: ToolContext;
     /**
-     * Optional sink for assistant text as it streams: called per text delta, then
-     * once with a lone "\n" to close each non-empty text segment on its own line.
-     * When set, `runAgent` streams live and does not buffer-print the turn (the
-     * caller renders); when omitted, behavior is unchanged (one buffered print).
+     * The render seam (U.2): assistant text streams through `renderer.write`
+     * delta by delta (each non-empty segment closed via `endSegment`), and
+     * tool-call progress is surfaced as transient `status` + committed `note`
+     * lines. When omitted, behavior is unchanged (one buffered print per turn,
+     * no tool-call chrome). The loop never touches stdout directly.
      */
-    onText?: (delta: string) => void;
+    renderer?: StreamRenderer;
     /** Git context (branch + dirty) for the system prompt's Environment section. */
     git?: {
         branch: string;
@@ -32,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. */
@@ -39,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

@@ -10,10 +10,23 @@ import { buildSystemPrompt } from "./prompts.js";
  * silently running tool-less.
  */
 export async function runAgent(args) {
-    const { provider, registry, config, ctx } = args;
+    const { provider, config, renderer } = args;
     if (!provider.supportsTools) {
         throw providerUnsupported(config.model.provider);
     }
+    renderer?.beginTurn();
+    try {
+        return await driveLoop(args, renderer);
+    }
+    finally {
+        // Always leave the terminal clean: no orphaned status line, no held text —
+        // even when a provider error aborts the turn mid-stream.
+        renderer?.endTurn();
+    }
+}
+/** The body of {@link runAgent}, split out so turn cleanup lives in one finally. */
+async function driveLoop(args, renderer) {
+    const { provider, registry, config, ctx } = args;
     const { logger } = ctx;
     // Work on a copy so we never mutate the caller's array as a side effect; the
     // extended history is returned for the caller to adopt.
@@ -33,15 +46,38 @@ export async function runAgent(args) {
         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 ──────────────────────────────────────────────
         let turnText = "";
         const pending = new Map();
         const toolUses = [];
+        // Live progress while waiting on the model; dismissed by the first delta.
+        // 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,
@@ -50,7 +86,7 @@ export async function runAgent(args) {
             switch (ev.type) {
                 case "text_delta":
                     turnText += ev.text;
-                    args.onText?.(ev.text);
+                    renderer?.write(ev.text);
                     break;
                 case "tool_use_start":
                     pending.set(ev.index, { id: ev.id, name: ev.name });
@@ -83,13 +119,13 @@ export async function runAgent(args) {
         }
         // ── Record the assistant turn ───────────────────────────────────────────
         if (turnText) {
-            // Streaming (onText set): the text already reached the user delta by delta,
-            // so close the segment with a single newline through the *same* sink — no
-            // separate buffered print racing the stream — so tool output, the next
-            // turn, or an approval prompt starts on its own line. Otherwise render the
-            // whole buffered block (no-callback path, unchanged).
-            if (args.onText)
-                args.onText("\n");
+            // Streaming (renderer set): the text already reached the user delta by
+            // delta, so close the segment through the *same* renderer — it flushes any
+            // held partial line and terminates with one newline, so tool output, the
+            // next turn, or an approval prompt starts on its own line. Otherwise
+            // render the whole buffered block (no-renderer path, unchanged).
+            if (renderer)
+                renderer.endSegment();
             else
                 logger.print(turnText);
         }
@@ -105,13 +141,51 @@ export async function runAgent(args) {
         // ── Execute each tool call, collecting one tool_result per call ──────────
         const toolResults = [];
         for (const call of toolUses) {
-            toolResults.push(await runToolCall(call, registry, ctx));
+            const label = describeToolCall(call);
+            // 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?.toolLifecycle({ event: "end", label, ok: !result.is_error });
+            toolResults.push(result);
         }
         messages.push({ role: "user", content: toolResults });
     }
     logger.warn(`reached maxIterations (${maxIterations}) without completing`);
     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",
+    "task",
+];
+/** Longest hint shown before truncation — chrome, not information of record. */
+const HINT_MAX = 60;
+/**
+ * A short human label for a tool call ("read_file src/x.ts"): the tool name
+ * plus the first recognizable scalar argument, if any. Best-effort — unknown
+ * shapes fall back to the bare name.
+ */
+function describeToolCall(call) {
+    const input = call.input;
+    if (typeof input === "object" && input !== null) {
+        for (const key of HINT_KEYS) {
+            const value = input[key];
+            if (typeof value === "string" && value !== "") {
+                const flat = value.replace(/\s+/g, " ").trim();
+                const hint = flat.length > HINT_MAX ? flat.slice(0, HINT_MAX - 1) + "…" : flat;
+                return `${call.name} ${hint}`;
+            }
+        }
+    }
+    return call.name;
+}
 /**
  * Dispatch a single reassembled tool call to its tool and shape the outcome as
  * a `tool_result` block. Unknown tools and invalid arguments become `is_error`

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/agent/session.d.ts

@@ -1,5 +1,6 @@
 import type { Message, Provider, Usage } from "@cruxy/sdk";
 import type { CruxyConfig } from "../config/index.js";
+import type { StreamRenderer } from "../render/index.js";
 import type { ToolContext } from "../tools/index.js";
 import type { ToolRegistry } from "../tools/index.js";
 import { type AgentResult } from "./loop.js";
@@ -12,7 +13,7 @@ import { type AgentResult } from "./loop.js";
 export type PlanRunner = (args: {
     messages: Message[];
     projectInstructions: string | null;
-    onText?: (delta: string) => void;
+    renderer?: StreamRenderer;
 }) => Promise<AgentResult>;
 export interface SessionArgs {
     /** A constructed provider to stream from. */
@@ -76,10 +77,11 @@ export declare class Session {
      * the threshold, drive the agent loop over the full history, adopt the
      * extended history, and accumulate usage. Returns the turn's `AgentResult`.
      *
-     * `onText`, when supplied, receives assistant text deltas as they stream so the
-     * caller can render them live (see the REPL); history is unaffected.
+     * `renderer`, when supplied, receives assistant text deltas and tool-call
+     * progress as they stream so the caller sees the turn live (see the REPL);
+     * history is unaffected.
      */
-    send(userPrompt: string, onText?: (delta: string) => void): Promise<AgentResult>;
+    send(userPrompt: string, renderer?: StreamRenderer): Promise<AgentResult>;
     /**
      * Re-read project instructions (CRUXY.md / AGENTS.md) from the working
      * directory so edits take effect without restarting. Returns the new text, or

package/dist/agent/session.js

@@ -74,10 +74,11 @@ export class Session {
      * the threshold, drive the agent loop over the full history, adopt the
      * extended history, and accumulate usage. Returns the turn's `AgentResult`.
      *
-     * `onText`, when supplied, receives assistant text deltas as they stream so the
-     * caller can render them live (see the REPL); history is unaffected.
+     * `renderer`, when supplied, receives assistant text deltas and tool-call
+     * progress as they stream so the caller sees the turn live (see the REPL);
+     * history is unaffected.
      */
-    async send(userPrompt, onText) {
+    async send(userPrompt, renderer) {
         this.messages.push({ role: "user", content: userPrompt });
         // Compact *before* the agent call so the turn runs against a bounded history.
         await this.maybeCompact();
@@ -88,7 +89,7 @@ export class Session {
             ? await this.args.planRunner({
                 messages: this.messages,
                 projectInstructions: this.projectInstructions,
-                onText,
+                renderer,
             })
             : await runAgent({
                 messages: this.messages,
@@ -96,7 +97,7 @@ export class Session {
                 // After the spread so a mid-session `/reload` wins over the initial value.
                 projectInstructions: this.projectInstructions,
                 planMode: false, // the plan directive belongs only to the runner's propose phase
-                onText,
+                renderer,
             });
         this.messages = result.messages;
         this.usage.input_tokens += result.usage.input_tokens;

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/approval/prompt.d.ts

@@ -1,4 +1,13 @@
 import type { ApprovalRequest } from "./types.js";
+/**
+ * The interactive prompt: render a pending action (a real diff for file edits,
+ * the exact command + cwd for shell) and read a 4-way choice. Rendering is data
+ * → string so it's testable; color is gated on `io.color` (NO_COLOR / non-TTY
+ * aware). **Default-deny**: EOF / Ctrl-C / any unrecognized key → reject.
+ *
+ * Diff/preview rendering is the shared implementation in `render/diff.ts` —
+ * the streaming path and this prompt draw the same bytes for the same change.
+ */
 /** The four user choices (plus the implicit default-deny). */
 export type PromptChoice = {
     kind: "once";

package/dist/approval/prompt.js

@@ -1,7 +1,6 @@
 import path from "node:path";
 import pc from "picocolors";
-/** Cap on rendered preview lines before collapsing the rest. */
-const PREVIEW_MAX_LINES = 40;
+import { renderActionPreview } from "../render/diff.js";
 /**
  * Render the action, read one key, and map it to a {@link PromptChoice}. `n`/`t`
  * read a follow-up line (reason / instruction). Anything else — including EOF —
@@ -53,7 +52,7 @@ function detail(request, c) {
             `  ${c.dim(`in ${request.cwd}`)}`,
         ].join("\n");
     }
-    return renderPreview(request.action.preview, c);
+    return renderActionPreview(request.action.preview, c);
 }
 /** The choices line, including a short label of what an `a` grant would cover. */
 function choices(scope, c) {
@@ -71,80 +70,6 @@ function scopeLabel(scope) {
         return `changes under ${path.basename(scope.root)}/`;
     return null;
 }
-// ── diff rendering (shared with the old C.6 renderer) ──────────────────────────
-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;
-}
-/** 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;
-}
-function renderPreview(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 {
-        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");
-}
 // ── default stdin-backed PromptIO ──────────────────────────────────────────────
 /** Build the real PromptIO: prompt to stderr, read keys/lines from stdin. */
 export function defaultPromptIO(color) {

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;
+}