@cruxy/cli 1.5.0 → 1.7.0

package/README.md

@@ -143,6 +143,122 @@ 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.
 
+## Terminal & accessibility
+
+Cruxy probes the terminal once per run and reduces it to a handful of
+capabilities — color, unicode, cursor control, motion, screen-reader mode, size
+— which every rendered surface resolves a theme from. That is why degradation is
+consistent: there is one place that decides, not one decision per panel.
+
+Each axis has an environment override, and **the axes are independent**. Turning
+color off does not change which glyphs are used; asking for ASCII glyphs does not
+turn color off. A `NO_COLOR` terminal still gets `✓`, a colored `CRUXY_ASCII`
+terminal gets a green `[ok]`.
+
+### Color
+
+| Variable      | Effect                                                           |
+| ------------- | ---------------------------------------------------------------- |
+| `NO_COLOR`    | No ANSI color anywhere. Not muted color — **zero** escape bytes. |
+| `FORCE_COLOR` | Keep color even when stdout is a pipe or a file.                 |
+
+Color is on by default only when the stream is a TTY. `TERM=dumb` forces it off
+regardless.
+
+### Glyphs
+
+| Variable      | Effect                                                                                    |
+| ------------- | ----------------------------------------------------------------------------------------- |
+| `CRUXY_ASCII` | Use the ASCII glyph table: `[ok]` `[x]` `[ ]` `->` `...` in place of `✓` `✗` `○` `→` `…`. |
+
+Also implied by `TERM=dumb`. Piped output keeps unicode — writing `✓` to a file
+is fine, and forcing ASCII there would change long-standing behaviour for
+everything that already parses cruxy's output.
+
+### Screen readers
+
+| Variable              | Effect                                         |
+| --------------------- | ---------------------------------------------- |
+| `CRUXY_SCREEN_READER` | Screen-reader mode.                            |
+| `ACCESSIBLE`          | The same thing, under the ecosystem-wide name. |
+
+In this mode:
+
+- **status glyphs become words** — `✓ read_file` is announced as `done
+read_file`, and `◐` / `○` become `working` / `pending`, so a status mark is
+  never read out as bare punctuation;
+- **decorative marks collapse to nothing** — the `↻` cache marker, the text
+  cursor bar, and the cells of a progress bar all render as empty, because a run
+  of block characters announces as noise and the percentage beside it already
+  carries the whole meaning;
+- **animation is off** — screen-reader mode implies reduced motion, since a
+  spinner has no live region to animate into.
+
+**It is opt-in and never inferred.** Cruxy has no way to detect a screen reader,
+and inferring one from a non-TTY stdout would reword every piped and CI run in
+the world:
+
+```bash
+export CRUXY_SCREEN_READER=1
+```
+
+### Motion
+
+| Variable               | Effect                                         |
+| ---------------------- | ---------------------------------------------- |
+| `NO_MOTION`            | The ecosystem-wide reduced-motion signal.      |
+| `CRUXY_REDUCED_MOTION` | The explicit cruxy knob.                       |
+| `CRUXY_NO_SPINNER`     | Kept as an alias; flows through the same axis. |
+
+Any of them disables the frame clock outright — nothing is scheduled and no
+frame ever ticks, so every animation collapses to its static end-state, drawn
+once. Reduced motion is also implied by screen-reader mode.
+
+### The alternate screen
+
+| Variable              | Effect                                                                         |
+| --------------------- | ------------------------------------------------------------------------------ |
+| `CRUXY_NO_ALT_SCREEN` | Keep the full-screen TUI in the normal buffer instead of the alternate screen. |
+
+By default the TUI runs on the terminal's alternate screen — the second buffer
+`less` and `vim` use. Leaving it restores the normal buffer byte for byte, so
+the prompt you started cruxy from comes back exactly as it was, with no
+frame-shaped hole in your scrollback.
+
+On a clean exit the last dozen lines of the conversation are echoed into the
+normal buffer, so the session survives in the shell's scrollback rather than
+being discarded with the alternate screen. The full transcript is the session
+log; this is the tail.
+
+The opt-out exists because the alternate screen is not universally available or
+wanted — multiplexers and emulators can be configured to refuse it, some
+capture-and-replay tooling reads only the normal buffer, and you may simply
+prefer your shell to keep the frame. It changes nothing else about the TUI, and
+it is ignored where the TUI does not run at all (a pipe, a screen reader,
+`TERM=dumb`).
+
+However cruxy exits — quit, `kill -TERM`, a hangup when the window closes, an
+uncaught error — the terminal is handed back: the frame erased, the cursor
+shown, the alternate screen left.
+
+### Size
+
+| Variable  | Effect                                       |
+| --------- | -------------------------------------------- |
+| `COLUMNS` | Terminal width, overriding what it reports.  |
+| `LINES`   | Terminal height, overriding what it reports. |
+
+These win over the stream's own values, which is what makes
+`COLUMNS=100 cruxy …` work in CI where the terminal reports no size at all. They
+fall back to 80 × 24. Unlike the flags above they take a **positive integer**; a
+value that is not one is ignored rather than treated as "set".
+
+### The "set" convention
+
+Every variable except `COLUMNS` / `LINES` follows the `NO_COLOR` rule: **any
+non-empty value counts as set.** `CRUXY_ASCII=1` and `CRUXY_ASCII=false` both
+enable ASCII glyphs — to turn one off, unset it or set it to the empty string.
+
 ## Errors & exit codes
 
 Every user-facing error prints a title, the cause (when known), concrete next

package/dist/agent/session.js

@@ -1,11 +1,16 @@
 import { randomUUID } from "node:crypto";
+import { UNRESOLVED_TIER } from "../budget/index.js";
 import { loadProjectInstructions } from "../config/index.js";
+import { sessionBudgetExhausted } from "../errors/index.js";
+// The concrete module, not `session/index.js`: that barrel imports this file's
+// package for its own types, and the transform is a leaf that needs none of it.
+import { redactMessages } from "../session/redact.js";
 import { resolveTaskModel, } from "../routing/index.js";
 import { UsageCollector, accumulateCacheTokens, } from "../usage/index.js";
 import { Budget } from "./budget.js";
 import { estimateTokens, findCut } from "./context.js";
 import { runAgent, } from "./loop.js";
-import { DEFAULT_MODE, modeAutoApproves, modePlans, nextMode, parseMode, } from "./mode.js";
+import { DEFAULT_MODE, modeAutoApproves, modePlans, parseMode, } from "./mode.js";
 import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
 /**
  * Re-exported from `agent/context.ts`, where the estimate now lives beside the
@@ -65,6 +70,25 @@ export class Session {
      * previous iteration fully resolved its tool calls.
      */
     recordedCount = 0;
+    /**
+     * The tier the next turn will draw on, in the three-way shape admission needs.
+     *
+     * A session with no {@link SessionModel} is a bring-your-own-provider session:
+     * its tokens never reach the weighted pool, so there is nothing to weigh and
+     * `undefined` says so. `auto` is a cruxy request whose tier the gateway picks,
+     * which is a different unknown entirely — it WILL draw on the pool — so it is
+     * passed through as {@link UNRESOLVED_TIER} and weighed at the worst case.
+     */
+    turnTier() {
+        const choice = this.args.model?.current();
+        if (choice === undefined)
+            return undefined;
+        return choice === "auto" ? UNRESOLVED_TIER : choice;
+    }
+    /** The session's weighted-token budget, when one is wired (`/budget` reads it). */
+    get budget() {
+        return this.args.budget;
+    }
     constructor(args) {
         this.args = args;
         this.projectInstructions = args.projectInstructions ?? null;
@@ -165,10 +189,6 @@ export class Session {
         this.args.recorder?.mode(this.mode);
         return this.mode;
     }
-    /** Advance one step around the mode ring (Shift+Tab). Returns the new mode. */
-    cycleMode() {
-        return this.setMode(nextMode(this.mode));
-    }
     /** Whether this session proposes a plan before executing (C.31). */
     getPlanMode() {
         return modePlans(this.mode);
@@ -213,11 +233,29 @@ export class Session {
         // Unset/0 → no budget object at all, so the loop's budget check is a no-op
         // and behavior is byte-identical to before. Rebuilt each `send`, so the cap
         // is per-turn, never cumulative across the session (cost is C.22's concern).
+        //
+        // P10 track 3 narrows that cap further when a session `/budget` is set. The
+        // session budget is stated in WEIGHTED tokens (the unit the gateway meters)
+        // and this guard counts LOCAL ones, so the conversion is the budget's job,
+        // not this call site's — `admit` returns the local ceiling that fits.
+        // Refusal (nothing left) throws before the model is engaged: a turn that
+        // cannot run must not spend a request finding that out.
         const maxTokensPerTurn = this.args.config.agent.maxTokensPerTurn;
-        const budget = maxTokensPerTurn > 0
+        const admission = this.args.budget?.admit({
+            count: 1,
+            perRunTokens: maxTokensPerTurn,
+            tier: this.turnTier(),
+        });
+        if (admission?.kind === "refused") {
+            throw sessionBudgetExhausted(admission.reason);
+        }
+        // `admit` only ever narrows: `maxTokens: 0` from an unbudgeted session means
+        // "no cap", exactly as the config value does.
+        const turnTokenCap = admission?.maxTokens ?? maxTokensPerTurn;
+        const budget = turnTokenCap > 0
             ? new Budget({
                 maxIterations: Number.POSITIVE_INFINITY,
-                maxTokens: maxTokensPerTurn,
+                maxTokens: turnTokenCap,
             })
             : undefined;
         // before-run (C.19): a blocking pre-run hook — or an untrusted project's
@@ -272,6 +310,9 @@ export class Session {
         const record = collector.toRecord(randomUUID(), this.sessionId, startedAt);
         this.lastRun = record;
         this.args.onRunUsage?.(record);
+        // The budget draws down from the SAME record the usage store persists, so
+        // `/budget` and `/usage` can never report different spends for one turn.
+        this.args.budget?.record(record);
         // after-run (C.19): advisory by default (a blocking after-run hook throws
         // and surfaces at the boundary). The turn already completed and its history
         // is adopted above — an advisory failure never rewrites it.
@@ -296,6 +337,34 @@ export class Session {
         this.args.recorder?.clear();
         this.recordedCount = 0;
     }
+    /**
+     * `/redact` (P10 track 5) — mask every recognised secret in the history the
+     * model can still see, and record that it happened.
+     *
+     * THE LIVE ARRAY AND THE LOG'S FOLD RUN THE SAME TRANSFORM, so a resumed
+     * session sees exactly what this one sees from here on. The event carries no
+     * secret; replay re-derives the spans with the same detector.
+     *
+     * The recorder's watermark is deliberately NOT rewound. `recordedCount` says
+     * how many messages of the current history are already on disk, and every one
+     * of them still is — the redaction changed their CONTENT in memory, not how
+     * many there are. Rewinding would re-append the whole conversation as if it
+     * were new, doubling the file and (worse) writing the freshly-masked copies
+     * beside the originals, which is a second copy of nothing useful.
+     *
+     * Returns what it found, so the caller can say so — including zero, which is
+     * a real answer and not a no-op to swallow.
+     */
+    redact() {
+        const result = redactMessages(this.messages);
+        if (result.count > 0)
+            this.messages = result.messages;
+        // Recorded even at zero: the fold is idempotent, and a log that records the
+        // request rather than only its hits keeps meaning the same thing when a
+        // later build's denylist recognises something this one did not.
+        this.args.recorder?.redact(result.kinds, result.count);
+        return { kinds: result.kinds, count: result.count };
+    }
     /**
      * Compact `this.messages` only when it has grown past threshold, adopting the
      * result. On success logs a one-line notice and returns the number of older

package/dist/budget/index.js

@@ -0,0 +1,9 @@
+/**
+ * The session's weighted-token budget (P10 track 3 / cli#212).
+ *
+ * One object, two exposures: `/budget` (what the user sets and reads) and
+ * admission control at the fan-out seam (what stops a parallel batch draining a
+ * sliding window that refills by trickle). See `session-budget.ts` for why they
+ * are not two things.
+ */
+export { SessionBudget, UNRESOLVED_TIER, } from "./session-budget.js";

package/dist/budget/session-budget.js

@@ -0,0 +1,223 @@
+import { bindingWindow } from "../limits/index.js";
+import { compactTokens } from "../render/units.js";
+import { MAX_TIER_MULTIPLIER, multiplierForTier, weightedFor, } from "../usage/weighted.js";
+/**
+ * The tier is not knowable before the request — routing is `auto` and the
+ * gateway resolves it. Weighed at the worst case, never skipped.
+ */
+export const UNRESOLVED_TIER = "auto";
+export class SessionBudget {
+    opts;
+    limits;
+    limitWeighted = null;
+    spentWeighted = 0;
+    /** Requests whose weight could not be computed — surfaced, never assumed 0. */
+    unweighed = 0;
+    constructor(opts) {
+        this.opts = opts;
+        this.limits = opts.limits;
+    }
+    /**
+     * Adopt the server denominator once it exists.
+     *
+     * A seam rather than a constructor argument because of the order the real
+     * wiring happens in: the limits cache needs the resolved provider and key,
+     * which the session factory has already consumed by the time it returns, and
+     * the TUI attaches the SAME cache a few lines later. Handing both the one
+     * instance is the point — a budget reading one cache while the rail panel
+     * draws another would be two answers to one question, and they would disagree
+     * exactly when the pool is moving.
+     */
+    attachLimits(limits) {
+        this.limits = limits;
+    }
+    /** The session cap in weighted tokens, or `null` when the user has set none. */
+    get limit() {
+        return this.limitWeighted;
+    }
+    /**
+     * Set or clear the cap. SESSION STATE, never written to config — the same rule
+     * `/model` and `/mode` follow, and for the strongest version of the reason: a
+     * spending cap silently re-applied from a file to every future session would
+     * eventually refuse a turn with nothing on screen explaining why.
+     */
+    setLimit(weighted) {
+        this.limitWeighted = weighted !== null && weighted > 0 ? weighted : null;
+    }
+    /** Weighted tokens this session has drawn, as far as they could be weighed. */
+    get spent() {
+        return this.spentWeighted;
+    }
+    /** Requests this session could not weigh (a non-cruxy provider, or an old gateway). */
+    get unweighable() {
+        return this.unweighed;
+    }
+    /**
+     * Fold one completed run's usage in, per REQUEST rather than from the run's
+     * summed totals — the same discipline `summarizeRuns` states: the multiplier
+     * is per-tier, and a run can mix tiers and mix weighable with unweighable
+     * requests, so a sum multiplied once would weigh tokens that were never
+     * eligible.
+     */
+    record(run) {
+        for (const e of run.entries) {
+            const weighted = weightedFor(e.tier, e.billableInputTokens, e.outputTokens);
+            if (weighted === undefined) {
+                this.unweighed++;
+                continue;
+            }
+            this.spentWeighted += weighted;
+        }
+    }
+    /** Weighted tokens left on the SESSION cap, or `null` when none is set. */
+    remaining() {
+        if (this.limitWeighted === null)
+            return null;
+        return Math.max(0, this.limitWeighted - this.spentWeighted);
+    }
+    /** The server's denominator, resolved to a statement (see {@link ServerHeadroom}). */
+    serverHeadroom() {
+        const state = this.limits?.current();
+        if (!state)
+            return { kind: "unreadable", why: "no limits reading is wired" };
+        if (state.status === "pending") {
+            return {
+                kind: "unreadable",
+                why: "the limits reading has not arrived yet",
+            };
+        }
+        if (state.status === "error") {
+            return {
+                kind: "unreadable",
+                why: `the limits reading is ${state.reason}`,
+            };
+        }
+        const budget = state.reading.budget;
+        if (budget.kind === "unenforced")
+            return { kind: "uncapped" };
+        if (budget.kind !== "pool") {
+            // metered / credits / unknown: no weighted pool to bound against. Only
+            // `unknown` is a failure, but none of the three yields a weighted window,
+            // and inventing one from a dollar balance would be a unit error.
+            return {
+                kind: "unreadable",
+                why: `this account is ${budget.kind}, which has no weighted pool`,
+            };
+        }
+        const binding = bindingWindow(budget.monthly, budget.burst);
+        if (!binding) {
+            return {
+                kind: "unreadable",
+                why: "the pool reported no readable window",
+            };
+        }
+        return {
+            kind: "window",
+            name: binding.name,
+            remaining: binding.window.remaining,
+            cap: binding.window.cap,
+        };
+    }
+    /**
+     * THE ONE DECISION. Both exposures land here.
+     *
+     * The arithmetic is deliberately an UPPER BOUND on the draw, not an estimate:
+     * `perRunTokens × count × multiplier`. The local ceiling counts input+output
+     * including re-sent prompt, while the meter counts `billable_input` (cache
+     * reads excluded), so the true draw is lower — often much lower. Erring high is
+     * the only safe direction for an admission check: erring low admits a batch
+     * that then trips a sliding window which refills by trickle over twelve hours.
+     *
+     * A tier we cannot weigh (a non-cruxy provider, or routing unresolved) yields
+     * NO weighted bound, because there is no honest multiplier to apply. The run
+     * proceeds — those tokens never touch the weighted pool.
+     */
+    admit(req) {
+        const allow = (count, maxTokens) => ({
+            kind: "allow",
+            count,
+            maxTokens,
+        });
+        const configCap = this.opts.maxTokensPerTurn;
+        const perRun = req.perRunTokens > 0 ? req.perRunTokens : configCap > 0 ? configCap : 0;
+        const multiplier = req.tier === undefined
+            ? undefined
+            : req.tier === UNRESOLVED_TIER
+                ? MAX_TIER_MULTIPLIER
+                : multiplierForTier(req.tier);
+        const allowance = this.allowance();
+        // Nothing to enforce against, or nothing to enforce with.
+        if (allowance === null || multiplier === undefined || perRun === 0) {
+            return allow(req.count, req.perRunTokens);
+        }
+        if (allowance.weighted <= 0) {
+            return { kind: "refused", reason: exhaustedReason(allowance) };
+        }
+        // How many runs of `perRun` local tokens the allowance covers.
+        const perRunWeighted = perRun * multiplier;
+        const affordable = Math.floor(allowance.weighted / perRunWeighted);
+        if (affordable >= req.count)
+            return allow(req.count, req.perRunTokens);
+        if (affordable >= 1) {
+            return {
+                kind: "narrowed",
+                count: affordable,
+                maxTokens: req.perRunTokens,
+                reason: narrowedReason(req.count, affordable, req, allowance, multiplier),
+            };
+        }
+        // Not even one run at the caller's ceiling. A single run is still admitted,
+        // with its token cap cut to what the allowance covers — refusing outright
+        // would leave a user with real headroom unable to ask anything at all. A
+        // fan-out of many, though, is narrowed to exactly one.
+        const cap = Math.max(1, Math.floor(allowance.weighted / multiplier));
+        if (req.count === 1) {
+            return {
+                kind: "narrowed",
+                count: 1,
+                maxTokens: cap,
+                reason: `capped this turn at ${compactTokens(cap)} tokens — ` +
+                    `${allowanceLabel(allowance)} leaves room for about that much on ${req.tier}`,
+            };
+        }
+        return {
+            kind: "narrowed",
+            count: 1,
+            maxTokens: cap,
+            reason: narrowedReason(req.count, 1, req, allowance, multiplier),
+        };
+    }
+    /**
+     * The tighter of the two denominators, or `null` when neither bounds anything.
+     * Never their sum, and never one standing in for the other.
+     */
+    allowance() {
+        const session = this.remaining();
+        const server = this.serverHeadroom();
+        const serverRemaining = server.kind === "window"
+            ? { weighted: server.remaining, source: server.name }
+            : null;
+        if (session === null)
+            return serverRemaining;
+        const local = { weighted: session, source: "session" };
+        if (!serverRemaining)
+            return local;
+        return serverRemaining.weighted < local.weighted ? serverRemaining : local;
+    }
+}
+function allowanceLabel(a) {
+    return a.source === "session"
+        ? "your /budget for this session"
+        : `your ${a.source === "burst" ? "12h burst" : "monthly"} window`;
+}
+function exhaustedReason(a) {
+    return a.source === "session"
+        ? "this session's /budget is used up — raise it with `/budget <n>` or clear it with `/budget off`"
+        : `your ${a.source === "burst" ? "12h burst" : "monthly"} window has nothing left`;
+}
+function narrowedReason(asked, granted, req, a, multiplier) {
+    const wouldDraw = asked * req.perRunTokens * multiplier;
+    return (`narrowed ${asked} → ${granted}: ${asked} concurrent runs could draw up to ` +
+        `${compactTokens(wouldDraw)} weighted tokens on ${req.tier}, and ` +
+        `${allowanceLabel(a)} has ${compactTokens(a.weighted)} left`);
+}

package/dist/checkpoint/diff.js

@@ -0,0 +1,130 @@
+import { GitCheckpointStore } from "./git-store.js";
+import { CheckpointService, isGitWorkTree } from "./service.js";
+import { listSets, readSet } from "./set.js";
+/**
+ * Resolve `--since [id]` against the workspace.
+ *
+ * With no id: the most recent run, which is the same default `/undo-last` and
+ * `cruxy rollback` use — "since the last thing that happened" is the question
+ * being asked often enough that making it typed-out is friction for nothing.
+ *
+ * With an id: a set manifest first (so a background job's id works, C.28), then
+ * each root's own checkpoints. A checkpoint id is searched across EVERY declared
+ * root rather than only the primary, because a multi-root run writes one
+ * checkpoint per root and the id the user copied off a rollback preview may
+ * belong to any of them.
+ */
+export async function resolveCheckpointDiff(roots, id, config) {
+    const primary = roots.find((r) => r.primary) ?? roots[0];
+    if (id === undefined) {
+        const sets = await listSets(primary.absPath);
+        if (sets.length > 0) {
+            return {
+                kind: "run",
+                runId: sets[0].runId,
+                targets: await runTargets(sets[0].members, config),
+            };
+        }
+        // No set manifest — the pre-C.26 shape, and also a session whose only run
+        // touched nothing. Fall back to the primary root's newest checkpoint.
+        const newest = (await new CheckpointService({
+            root: primary.absPath,
+            config,
+        }).list())[0];
+        if (!newest)
+            return { kind: "none" };
+        return {
+            kind: "checkpoint",
+            targets: [await target(primary.name, primary.absPath, newest)],
+        };
+    }
+    // A run id first: `readSet` throws CHECKPOINT_SET_INCOMPLETE for a manifest
+    // that is missing OR corrupt, and only the second is worth reporting as an
+    // error — a plain miss just means the id was a checkpoint id.
+    const sets = await listSets(primary.absPath);
+    if (sets.some((s) => s.runId === id)) {
+        const set = await readSet(primary.absPath, id);
+        return {
+            kind: "run",
+            runId: set.runId,
+            targets: await runTargets(set.members, config),
+        };
+    }
+    for (const root of roots) {
+        const service = new CheckpointService({ root: root.absPath, config });
+        let checkpoint;
+        try {
+            checkpoint = await service.read(id);
+        }
+        catch {
+            continue; // not this root's — try the next
+        }
+        return {
+            kind: "checkpoint",
+            targets: [await target(root.name, root.absPath, checkpoint)],
+        };
+    }
+    return { kind: "not-found", id };
+}
+/** Build one target per set member, in the order the set records them. */
+async function runTargets(members, config) {
+    const targets = [];
+    for (const member of members) {
+        const service = new CheckpointService({
+            root: member.rootPath,
+            config,
+        });
+        let checkpoint;
+        try {
+            checkpoint = await service.read(member.checkpointId);
+        }
+        catch (err) {
+            // A missing member is fatal for a ROLLBACK (validate-all, R3) and merely
+            // a gap for a diff. Reporting it per root and showing the rest beats
+            // refusing to show anything — this command changes nothing.
+            targets.push({
+                rootName: member.rootName,
+                rootPath: member.rootPath,
+                checkpointId: member.checkpointId,
+                unavailable: `checkpoint ${member.checkpointId} is missing or unreadable (${err.message})`,
+            });
+            continue;
+        }
+        targets.push(await target(member.rootName, member.rootPath, checkpoint));
+    }
+    return targets;
+}
+/**
+ * One root's tree-ish, or the reason there isn't one.
+ *
+ * The two honest failures, both reported rather than papered over:
+ *   • a SHADOW-store checkpoint — written when the root is not a git work tree,
+ *     or when git plumbing failed mid-snapshot. Its content is a private blob
+ *     pool git has never heard of, so there is no tree-ish to hand `git diff`.
+ *     Rollback still works; only the preview does not.
+ *   • pruned objects — `treeish` throws what `readContent` throws, and for the
+ *     same reason.
+ */
+async function target(rootName, rootPath, checkpoint) {
+    const base = {
+        rootName,
+        rootPath,
+        checkpointId: checkpoint.id,
+    };
+    if (checkpoint.store !== "git" || !isGitWorkTree(rootPath)) {
+        return {
+            ...base,
+            unavailable: "this checkpoint was stored outside git (shadow copy), so there is no tree to diff against — " +
+                "`cruxy rollback` still restores it",
+        };
+    }
+    try {
+        return {
+            ...base,
+            treeish: await new GitCheckpointStore(rootPath).treeish(checkpoint.files),
+        };
+    }
+    catch (err) {
+        return { ...base, unavailable: err.message };
+    }
+}

package/dist/checkpoint/git-store.js

@@ -83,6 +83,58 @@ export class GitCheckpointStore {
             await fsp.rm(tmpDir, { recursive: true, force: true });
         }
     }
+    /**
+     * Rebuild a checkpoint's tree from its manifest entries and return the tree
+     * oid — a tree-ish that `git diff <treeish>` accepts (P10 track 2).
+     *
+     * WHY REBUILD RATHER THAN STORE. `snapshot` already calls `write-tree` and
+     * already throws the resulting oid away, on the grounds that per-file blob oids
+     * are what restore needs. Persisting it now would only help checkpoints written
+     * after this change and would leave every existing manifest undiffable, so the
+     * tree is reassembled instead — from the same manifest, into the same kind of
+     * temporary index, producing (by construction) the same oid.
+     *
+     * SAME FIVE-GIT-COMMAND DISCIPLINE as `snapshot`, and the same enforcement:
+     * `update-index --index-info` and `write-tree` both run against a
+     * `GIT_INDEX_FILE` in `os.tmpdir()`, no ref is created or moved, and the
+     * before/after fingerprint is asserted. This does not even write new objects —
+     * every blob it names is one the snapshot already wrote — so the only thing it
+     * can produce is a tree that was already there.
+     *
+     * Throws `CRUXY_E_CHECKPOINT_FAILED` when an object has been pruned out from
+     * under the manifest, which is the same failure `readContent` reports and for
+     * the same reason (`git gc --prune=now`).
+     */
+    async treeish(entries) {
+        const before = this.fingerprint();
+        const tmpDir = await fsp.mkdtemp(path.join(os.tmpdir(), "cruxy-ckdiff-"));
+        const indexFile = path.join(tmpDir, "index");
+        try {
+            const env = { GIT_INDEX_FILE: indexFile };
+            // `--index-info` with `-z`: "<mode> <oid>\t<path>" records, NUL-terminated,
+            // so a path containing a newline or a quote is carried verbatim.
+            const stdin = entries
+                .map((e) => `${e.mode} ${e.oid}\t${e.path}\0`)
+                .join("");
+            const add = this.git(["update-index", "-z", "--index-info"], {
+                env,
+                input: stdin,
+            });
+            if (!add.ok) {
+                throw checkpointFailed(`rebuilding the checkpoint tree failed — its objects may have been pruned ` +
+                    `by \`git gc --prune\` (${add.stderr.trim()})`);
+            }
+            const tree = this.git(["write-tree"], { env });
+            if (!tree.ok) {
+                throw checkpointFailed(`writing the checkpoint tree failed: ${tree.stderr.trim()}`);
+            }
+            assertGitStateUnchanged(before, this.fingerprint());
+            return tree.stdout.toString("utf8").trim();
+        }
+        finally {
+            await fsp.rm(tmpDir, { recursive: true, force: true });
+        }
+    }
     async readContent(entry) {
         const res = this.git(["cat-file", "blob", entry.oid]);
         if (!res.ok) {