@cruxy/cli 1.5.0 → 1.6.0

package/dist/agent/session.js

@@ -1,5 +1,10 @@
 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";
@@ -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;
@@ -213,11 +237,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 +314,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 +341,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) {

package/dist/checkpoint/index.js

@@ -6,5 +6,7 @@ export * from "./restore.js";
 export * from "./service.js";
 export * from "./set.js";
 export * from "./set-rollback.js";
+export * from "./run-rollback.js";
+export * from "./diff.js";
 export * from "./gate.js";
 export * from "./gate-hook.js";

package/dist/checkpoint/run-rollback.js

@@ -0,0 +1,100 @@
+import path from "node:path";
+import { CheckpointService } from "./service.js";
+import { listSets } from "./set.js";
+import { applySet, buildSetPreview, setIsNoop, validateSet, } from "./set-rollback.js";
+/**
+ * Restore every touched root of one run's {@link CheckpointSet} as a single gated
+ * operation (C.26): validate-all up front, ONE combined preview behind ONE
+ * approval, then a sequential apply that stops and reports on first failure.
+ */
+export async function rollbackSet(set, deps) {
+    const { report } = deps;
+    const t = report.theme;
+    // Validate-all BEFORE any apply — a missing/corrupt member throws here.
+    const members = await validateSet(set, deps.config);
+    if (setIsNoop(members)) {
+        report.print(t.muted(`working tree already matches run ${set.runId} — nothing to roll back`));
+        return { kind: "noop" };
+    }
+    const decision = await deps.requestApproval({
+        kind: "rollback",
+        preview: buildSetPreview(set, members),
+    });
+    if (!decision.allow) {
+        report.print(t.muted("rollback declined — nothing was changed"));
+        return { kind: "declined" };
+    }
+    const applied = await applySet(set, members);
+    const parts = applied.restored.map((name) => {
+        const counts = applied.perRoot[name];
+        return `${name} (${counts.reverted} reverted, ${counts.recreated} recreated, ${counts.deleted} deleted)`;
+    });
+    report.print(`${t.success(t.glyph.success)} restored run ${t.accent(set.runId)} across ` +
+        `${applied.restored.length} root${applied.restored.length === 1 ? "" : "s"} — ${parts.join("; ")}`);
+    printCaveat(report);
+    return { kind: "applied", roots: applied.restored.length };
+}
+/**
+ * Single-root rollback (C.32): restore ONE root to one checkpoint. Reached for an
+ * explicit checkpoint id (the per-member escape hatch — including when the
+ * primary root was removed mid-session and its set index is gone, ⚖︎#7) and as
+ * the JC-F back-compat fallback for a run that predates set manifests.
+ *
+ * `id` omitted → the newest checkpoint for that root.
+ */
+export async function rollbackCheckpoint(root, id, deps) {
+    const { report } = deps;
+    const t = report.theme;
+    const service = new CheckpointService({ root, config: deps.config });
+    const result = await service.rollback(id, {
+        requestApproval: deps.requestApproval,
+        interactive: deps.interactive,
+    });
+    if (result.kind === "noop") {
+        report.print(t.muted(`working tree already matches checkpoint ${result.checkpoint.id} — nothing to roll back`));
+        return { kind: "noop" };
+    }
+    if (result.kind === "rejected") {
+        report.print(t.muted("rollback declined — nothing was changed"));
+        return { kind: "declined" };
+    }
+    const { recreated, reverted, deleted } = result.applied;
+    report.print(`${t.success(t.glyph.success)} restored checkpoint ${t.accent(result.checkpoint.id)} — ` +
+        `${reverted} reverted, ${recreated} recreated, ${deleted} deleted`);
+    printCaveat(report);
+    return { kind: "applied", roots: 1 };
+}
+/**
+ * Roll back the MOST RECENT run under `primaryRoot`, with no picker and no id to
+ * supply — the shape `/undo-last` needs, and the shape `cruxy rollback` already
+ * had for its no-argument case once its picker declines to appear.
+ *
+ * Prefers the set manifest, which is the only record that knows how many roots a
+ * run touched; falls back to the newest single-root checkpoint (logged through
+ * the reporter, never silently) for a run that predates set manifests.
+ *
+ * Returns `null` when there is nothing recorded at all — a fact the caller
+ * phrases, because "no checkpoints yet" means something different at a shell
+ * prompt than it does three turns into a session.
+ */
+export async function rollbackLatestRun(primaryRoot, deps) {
+    const sets = await listSets(primaryRoot); // newest first
+    if (sets.length > 0)
+        return rollbackSet(sets[0], deps);
+    const service = new CheckpointService({
+        root: primaryRoot,
+        config: deps.config,
+    });
+    if ((await service.list()).length === 0)
+        return null;
+    deps.report.print(deps.report.theme.muted(`no set manifest — single-root rollback against ${path.basename(primaryRoot)}`));
+    return rollbackCheckpoint(primaryRoot, undefined, deps);
+}
+/**
+ * The one thing a successful rollback must always say. A user who has just
+ * watched a run be undone will reasonably assume it was undone; the parts that
+ * left the working tree were never in the checkpoint to begin with.
+ */
+function printCaveat(report) {
+    report.print(report.theme.muted("note: commits, pushes, and PRs made during the run are not undone"));
+}