@cruxy/cli 0.22.1 → 0.24.0

package/dist/agent/loop.d.ts

@@ -5,11 +5,19 @@ import type { StreamRenderer } from "../render/index.js";
 import { type Router, type TaskClass } from "../routing/index.js";
 import type { ToolContext } from "../tools/index.js";
 import { ToolRegistry } from "../tools/index.js";
+/** Optional per-fire context (C.26 step 5). For tool-scoped events the loop
+ * passes the raw tool-call `input` so a multi-root {@link HookRouter} can resolve
+ * the ONE acting root and fire only that root's hooks. Session lifecycle events
+ * (`before-run`/`after-run`) carry no hint — they have no acting root and fan
+ * every trusted root. Ignored by the single-root runner. */
+export interface HookFireHint {
+    input?: unknown;
+}
 /** The lifecycle-hook firing seam (C.19). Structural so the loop stays
  * decoupled from the concrete `HookRunner`. `fire` resolves when hooks pass (or
  * advisory ones fail) and throws `CRUXY_E_HOOK_FAILED` on a blocking failure. */
 export interface LifecycleHookRunner {
-    fire(event: HookEvent, ctx: ToolContext): Promise<void>;
+    fire(event: HookEvent, ctx: ToolContext, hint?: HookFireHint): Promise<void>;
 }
 export interface RunAgentArgs {
     /**
@@ -84,6 +92,17 @@ export interface RunAgentArgs {
         tier?: string;
         usage?: Usage;
     }) => void;
+    /**
+     * Cooperative cancellation (C.33). When the signal aborts, the loop stops at
+     * the NEXT turn boundary and returns `stop: "aborted"` with the coherent
+     * partial history — the in-flight turn (model call + its tool executions)
+     * always completes first, exactly like a tripped {@link budget}, so overshoot
+     * is bounded by one turn. Used by the parallel orchestrator to cancel sibling
+     * subagents on a fatal failure or Ctrl-C; omitted → no cancellation (unchanged).
+     * The same signal reaches tools via `ctx.signal`, so an in-flight shell child
+     * is kill-tree'd rather than orphaned.
+     */
+    signal?: AbortSignal;
 }
 /**
  * The budget seam for {@link runAgent}: implementations track their own caps
@@ -107,7 +126,7 @@ export interface AgentResult {
     /** Number of model turns consumed. */
     iterations: number;
     /** Why the loop ended. */
-    stop: "completed" | "max_iterations" | "budget";
+    stop: "completed" | "max_iterations" | "budget" | "aborted";
     /** Which cap tripped, when `stop === "budget"` (from {@link LoopBudget}). */
     stopReason?: string;
     /** Accumulated token usage (stashed for cost tracking in C.22). */

package/dist/agent/loop.js

@@ -62,6 +62,19 @@ async function driveLoop(args, renderer, routed) {
     });
     let iterations = 0;
     for (let i = 0; i < maxIterations; i++) {
+        // Cancellation check (C.33), before committing to another model turn: a
+        // signalled abort returns the history as it stands, at a clean turn boundary
+        // (the prior iteration fully resolved its tool calls). Checked ahead of the
+        // budget so a cancelled fan-out never spends one more turn's tokens.
+        if (args.signal?.aborted) {
+            return {
+                messages,
+                iterations,
+                stop: "aborted",
+                stopReason: "cancelled",
+                usage,
+            };
+        }
         // 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.
@@ -184,7 +197,10 @@ async function driveLoop(args, renderer, routed) {
             // fail-closed — the tool never runs; the model is told via an error
             // result. The hook command itself went through the U.3 gate + C.16 sandbox
             // (same path as run_command), so a hook is never an approval bypass.
-            const blocked = await fireBeforeTool(args.hooks, ctx, call.id);
+            // The raw input lets a multi-root HookRouter resolve the ONE acting root
+            // (same precedence the tool uses) and fire only that root's hooks.
+            const hint = { input: call.input };
+            const blocked = await fireBeforeTool(args.hooks, ctx, call.id, hint);
             if (blocked) {
                 renderer?.toolLifecycle({ event: "end", label, ok: false });
                 toolResults.push(blocked);
@@ -196,9 +212,9 @@ async function driveLoop(args, renderer, routed) {
             // after-tool + on-file-change (C.19): fire once the action is done.
             // Advisory by default (report, don't rewrite history); a hook explicitly
             // marked blocking here throws and aborts the run.
-            await args.hooks?.fire("after-tool", ctx);
+            await args.hooks?.fire("after-tool", ctx, hint);
             if (!result.is_error && FILE_MUTATING_TOOLS.has(call.name)) {
-                await args.hooks?.fire("on-file-change", ctx);
+                await args.hooks?.fire("on-file-change", ctx, hint);
             }
         }
         messages.push({ role: "user", content: toolResults });
@@ -250,11 +266,11 @@ function describeToolCall(call) {
  * the failure is greppable. A non-blocking (advisory) hook failure never reaches
  * here — the runner reports it and resolves normally.
  */
-async function fireBeforeTool(hooks, ctx, toolUseId) {
+async function fireBeforeTool(hooks, ctx, toolUseId, hint) {
     if (!hooks)
         return null;
     try {
-        await hooks.fire("before-tool", ctx);
+        await hooks.fire("before-tool", ctx, hint);
         return null;
     }
     catch (err) {

package/dist/approval/classify.js

@@ -121,6 +121,24 @@ function vcsRequest(action, root) {
  * carries the full blast radius; the summary names the checkpoint.
  */
 function rollbackRequest(action, root) {
+    // A multi-root set rollback (C.26): one destructive, ungrantable approval over
+    // every touched root of a run. Never session-grantable (scope `none`), and its
+    // targets span roots so they are not resolved here — the grouped preview carries
+    // the full per-root blast radius.
+    if (action.preview?.type === "rollback-set") {
+        const preview = action.preview;
+        const fileCount = preview.roots.reduce((n, r) => n + r.files.length, 0);
+        return {
+            action,
+            tier: "destructive",
+            scope: { kind: "none" },
+            summary: `rollback: restore run ${preview.runId} across ${preview.roots.length} ` +
+                `root${preview.roots.length === 1 ? "" : "s"} ` +
+                `(${fileCount} file${fileCount === 1 ? "" : "s"})`,
+            targets: [],
+            cwd: 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"})`

package/dist/approval/index.d.ts

@@ -3,3 +3,4 @@ export * from "./classify.js";
 export * from "./policy.js";
 export * from "./prompt.js";
 export * from "./service.js";
+export * from "./mutex.js";

package/dist/approval/index.js

@@ -3,3 +3,4 @@ export * from "./classify.js";
 export * from "./policy.js";
 export * from "./prompt.js";
 export * from "./service.js";
+export * from "./mutex.js";

package/dist/approval/mutex.d.ts

@@ -0,0 +1,45 @@
+import type { ApprovalDecision } from "./types.js";
+import type { ApproveAction } from "../tools/types.js";
+/**
+ * The approval mutex (C.33, JC-C) — the spine of the concurrent-subagent safety
+ * model. Node is single-threaded, so the only hazard between parallel subagents
+ * is interleaving at `await` boundaries; the one resource they genuinely contend
+ * for is the interactive terminal (one prompt at a time) and the run's shared
+ * checkpoint state (one snapshot/set-write at a time). Serializing every
+ * *gated write* through this one lock resolves BOTH with a single mechanism:
+ *
+ *   • **one prompt at a time** — a child blocked awaiting the user's keypress
+ *     holds the lock, so no sibling can paint a second prompt over it (the
+ *     keypress is always attributable to the one displayed prompt); and
+ *   • **serialized gated writes** — the checkpoint hook (snapshot + per-root set
+ *     member write) runs inside the same critical section, so two concurrent
+ *     writes to disjoint roots can never race on `ensureCheckpoint`'s latch or
+ *     the set manifest.
+ *
+ * It is a plain promise-chain serializer: `runExclusive(fn)` runs `fn` only
+ * after every previously-enqueued `fn` has settled. It is a LEAF lock — nothing
+ * is acquired while holding it except the terminal and the filesystem, neither
+ * of which waits on a subagent resource — so it cannot take part in a cycle
+ * (see the deadlock argument in the C.33 design doc).
+ */
+export declare class ApprovalMutex {
+    /** The settled-marker chain: always resolves (never rejects), so a rejecting
+     * critical section never wedges the queue for the next waiter. */
+    private tail;
+    /** Run `fn` in mutual exclusion with every other `runExclusive` on this mutex. */
+    runExclusive<T>(fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Wrap a fully-built gate (`ApprovalService.requestApproval` behind the C.32
+ * checkpoint hook) so that every gated action serializes through `mutex`.
+ *
+ * Every action that actually reaches the gate is a *mutation* — read-only tools
+ * never call `requestApproval` at all (see the ToolContext contract), so a
+ * parallel READ fan-out is already free of the lock and never stalls behind a
+ * sibling's pending prompt. The `read`-tier short-circuit below is therefore
+ * defensive belt-and-suspenders (mirroring `ApprovalService`'s own read check):
+ * if a read-classified action ever did flow here, it would bypass the spine
+ * rather than needlessly hold it. What the mutex serializes in practice is the
+ * mutating set — exactly the prompt + checkpoint work that must be one-at-a-time.
+ */
+export declare function serializeGate(gate: (action: ApproveAction) => Promise<ApprovalDecision>, mutex: ApprovalMutex, cwd: string): (action: ApproveAction) => Promise<ApprovalDecision>;

package/dist/approval/mutex.js

@@ -0,0 +1,57 @@
+import { classify } from "./classify.js";
+/**
+ * The approval mutex (C.33, JC-C) — the spine of the concurrent-subagent safety
+ * model. Node is single-threaded, so the only hazard between parallel subagents
+ * is interleaving at `await` boundaries; the one resource they genuinely contend
+ * for is the interactive terminal (one prompt at a time) and the run's shared
+ * checkpoint state (one snapshot/set-write at a time). Serializing every
+ * *gated write* through this one lock resolves BOTH with a single mechanism:
+ *
+ *   • **one prompt at a time** — a child blocked awaiting the user's keypress
+ *     holds the lock, so no sibling can paint a second prompt over it (the
+ *     keypress is always attributable to the one displayed prompt); and
+ *   • **serialized gated writes** — the checkpoint hook (snapshot + per-root set
+ *     member write) runs inside the same critical section, so two concurrent
+ *     writes to disjoint roots can never race on `ensureCheckpoint`'s latch or
+ *     the set manifest.
+ *
+ * It is a plain promise-chain serializer: `runExclusive(fn)` runs `fn` only
+ * after every previously-enqueued `fn` has settled. It is a LEAF lock — nothing
+ * is acquired while holding it except the terminal and the filesystem, neither
+ * of which waits on a subagent resource — so it cannot take part in a cycle
+ * (see the deadlock argument in the C.33 design doc).
+ */
+export class ApprovalMutex {
+    /** The settled-marker chain: always resolves (never rejects), so a rejecting
+     * critical section never wedges the queue for the next waiter. */
+    tail = Promise.resolve();
+    /** Run `fn` in mutual exclusion with every other `runExclusive` on this mutex. */
+    runExclusive(fn) {
+        const result = this.tail.then(fn);
+        // Advance the chain on a branch that swallows the outcome, so the caller
+        // still observes `fn`'s rejection while the next waiter is not poisoned.
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}
+/**
+ * Wrap a fully-built gate (`ApprovalService.requestApproval` behind the C.32
+ * checkpoint hook) so that every gated action serializes through `mutex`.
+ *
+ * Every action that actually reaches the gate is a *mutation* — read-only tools
+ * never call `requestApproval` at all (see the ToolContext contract), so a
+ * parallel READ fan-out is already free of the lock and never stalls behind a
+ * sibling's pending prompt. The `read`-tier short-circuit below is therefore
+ * defensive belt-and-suspenders (mirroring `ApprovalService`'s own read check):
+ * if a read-classified action ever did flow here, it would bypass the spine
+ * rather than needlessly hold it. What the mutex serializes in practice is the
+ * mutating set — exactly the prompt + checkpoint work that must be one-at-a-time.
+ */
+export function serializeGate(gate, mutex, cwd) {
+    return (action) => {
+        // Same classifier the gate uses; read tier contends for nothing → no lock.
+        if (classify(action, cwd).tier === "read")
+            return gate(action);
+        return mutex.runExclusive(() => gate(action));
+    };
+}

package/dist/approval/prompt.js

@@ -74,6 +74,17 @@ function detail(request, t) {
         // point of the call, not just at trust time.
         return `  ${t.muted(`external MCP server "${request.action.server ?? ""}" — runs unsandboxed with your privileges`)}`;
     }
+    if (request.action.kind === "vcs" && request.action.root) {
+        // C.26 Step 4 (⚖︎JC-4): name the acting root alongside the resolved owner/repo
+        // (rendered inside the preview), so the human sees BOTH which declared root the
+        // PR acts in and the real API destination before approving.
+        return [
+            `  ${t.muted(`root ${request.action.root}`)}`,
+            renderActionPreview(request.action.preview, t),
+        ]
+            .filter((l) => l !== "")
+            .join("\n");
+    }
     return renderActionPreview(request.action.preview, t);
 }
 /** The choices line, including a short label of what an `a` grant would cover. */

package/dist/checkpoint/gate.d.ts

@@ -0,0 +1,65 @@
+import type { CruxyConfig } from "../config/index.js";
+import { CheckpointService } from "./service.js";
+import type { CheckpointSet } from "./types.js";
+/**
+ * Per-root checkpoint gate (C.26 step 3). One run may mutate several declared
+ * roots; this owns one {@link CheckpointService} PER touched root (created lazily
+ * the first time a mutation is gated for that root) plus the run's
+ * {@link CheckpointSet} accumulator, so `cruxy rollback` can restore exactly the
+ * roots the run touched — no more, no less.
+ *
+ * Two invariants live here:
+ *   • **exactly-touched** — {@link serviceFor} is the ONLY construction site for a
+ *     per-root service, and it is called only when a mutation is actually gated for
+ *     that root, so an untouched root's service is never constructed and never
+ *     appears in the set.
+ *   • **one set per run, shared across subagents** — the parent and every subagent
+ *     share this one gate (C.14 wires the child gate over the same object), so a
+ *     subagent's writes join the run's single set and are covered by the run's
+ *     rollback (⚖︎JC-δ). The set manifest lives under the PRIMARY root (⚖︎#7).
+ */
+export type CreateCheckpointService = (root: string, config: CruxyConfig) => CheckpointService;
+export interface CheckpointGateOptions {
+    config: CruxyConfig;
+    /** Absolute path of the primary root — home of the set manifest (⚖︎#7). */
+    primaryRoot: string;
+    /**
+     * Test seam: the sole factory for per-root services. A constructor spy passed
+     * here proves an untouched root's service is never built.
+     */
+    createService?: CreateCheckpointService;
+}
+export declare class CheckpointGate {
+    private readonly config;
+    private readonly primaryRoot;
+    private readonly create;
+    private readonly services;
+    private runId;
+    private summary;
+    private set;
+    constructor(opts: CheckpointGateOptions);
+    /**
+     * Start a new undo unit for the WHOLE run (every root + the set). Resets each
+     * existing per-root service's once-per-run latch and clears the set so the next
+     * mutation begins a fresh run. The set is materialized lazily on the first member
+     * (so its `createdAt` marks the run's first mutation, and a no-mutation run
+     * writes no manifest).
+     */
+    beginRun(summary: string): void;
+    /**
+     * Get-or-create the per-root service. The first time a root is touched this
+     * process, its service is constructed and joined to the current run; an untouched
+     * root's service is never built.
+     */
+    serviceFor(rootName: string, rootAbsPath: string): CheckpointService;
+    /**
+     * Record that `rootName` was checkpointed this run: append its member to the set
+     * and persist the manifest under the primary root. Idempotent — later mutations
+     * to the same root this run are no-ops (the root already has exactly one member).
+     */
+    recordMember(rootName: string, rootAbsPath: string, checkpointId: string): Promise<void>;
+    /** Root names that got a per-root service this process (inspection/tests). */
+    get touchedRoots(): readonly string[];
+    /** The current run's set, or null before its first mutation (inspection/tests). */
+    get currentSet(): CheckpointSet | null;
+}

package/dist/checkpoint/gate.js

@@ -0,0 +1,86 @@
+import { CheckpointService } from "./service.js";
+import { newRunId, writeSet } from "./set.js";
+/** Trim a run summary to one line ≤80 chars, matching CheckpointService.beginRun. */
+function trimSummary(summary) {
+    const firstLine = summary.split("\n", 1)[0].trim();
+    return firstLine.length > 80
+        ? `${firstLine.slice(0, 79)}…`
+        : firstLine || "agent run";
+}
+export class CheckpointGate {
+    config;
+    primaryRoot;
+    create;
+    services = new Map();
+    runId = null;
+    summary = "agent run";
+    set = null;
+    constructor(opts) {
+        this.config = opts.config;
+        this.primaryRoot = opts.primaryRoot;
+        this.create =
+            opts.createService ??
+                ((root, config) => new CheckpointService({ root, config }));
+    }
+    /**
+     * Start a new undo unit for the WHOLE run (every root + the set). Resets each
+     * existing per-root service's once-per-run latch and clears the set so the next
+     * mutation begins a fresh run. The set is materialized lazily on the first member
+     * (so its `createdAt` marks the run's first mutation, and a no-mutation run
+     * writes no manifest).
+     */
+    beginRun(summary) {
+        this.summary = summary;
+        this.runId = newRunId();
+        this.set = null;
+        for (const svc of this.services.values())
+            svc.beginRun(summary);
+    }
+    /**
+     * Get-or-create the per-root service. The first time a root is touched this
+     * process, its service is constructed and joined to the current run; an untouched
+     * root's service is never built.
+     */
+    serviceFor(rootName, rootAbsPath) {
+        let svc = this.services.get(rootName);
+        if (!svc) {
+            svc = this.create(rootAbsPath, this.config);
+            svc.beginRun(this.summary);
+            this.services.set(rootName, svc);
+        }
+        return svc;
+    }
+    /**
+     * Record that `rootName` was checkpointed this run: append its member to the set
+     * and persist the manifest under the primary root. Idempotent — later mutations
+     * to the same root this run are no-ops (the root already has exactly one member).
+     */
+    async recordMember(rootName, rootAbsPath, checkpointId) {
+        if (!this.runId)
+            return; // no run in progress — defensive
+        if (this.set?.members.some((m) => m.rootName === rootName))
+            return;
+        if (!this.set) {
+            this.set = {
+                runId: this.runId,
+                createdAt: new Date().toISOString(),
+                runSummary: trimSummary(this.summary),
+                members: [],
+            };
+        }
+        this.set.members.push({
+            rootName,
+            rootPath: rootAbsPath,
+            checkpointId,
+        });
+        await writeSet(this.primaryRoot, this.set);
+    }
+    /** Root names that got a per-root service this process (inspection/tests). */
+    get touchedRoots() {
+        return [...this.services.keys()];
+    }
+    /** The current run's set, or null before its first mutation (inspection/tests). */
+    get currentSet() {
+        return this.set;
+    }
+}

package/dist/checkpoint/index.d.ts

@@ -5,3 +5,5 @@ export * from "./shadow-store.js";
 export * from "./restore.js";
 export * from "./service.js";
 export * from "./set.js";
+export * from "./set-rollback.js";
+export * from "./gate.js";

package/dist/checkpoint/index.js

@@ -5,3 +5,5 @@ export * from "./shadow-store.js";
 export * from "./restore.js";
 export * from "./service.js";
 export * from "./set.js";
+export * from "./set-rollback.js";
+export * from "./gate.js";

package/dist/checkpoint/service.d.ts

@@ -48,6 +48,14 @@ export declare class CheckpointService {
     private readonly pinnedStore?;
     private runSummary;
     private active;
+    /** In-flight `ensureCheckpoint` construction (C.33). PROMISE-latched, not
+     * value-latched: two concurrent gated writes to this root await the SAME
+     * snapshot instead of each taking one (the once-per-run latch `this.active`
+     * is only set AFTER several awaits, so a boolean/value latch would let a
+     * second caller slip through and double-snapshot). The approval mutex already
+     * serializes gated writes, so this is defense-in-depth — but it makes the
+     * service correct on its own, independent of the caller's discipline. */
+    private pending;
     constructor(opts: CheckpointServiceOptions);
     /** Start a new undo unit: reset the once-per-run latch and name the run. */
     beginRun(summary: string): void;
@@ -59,6 +67,7 @@ export declare class CheckpointService {
      * either substrate, the run must not mutate without its undo protection.
      */
     ensureCheckpoint(): Promise<Checkpoint | null>;
+    private buildCheckpoint;
     /** Attribute mutated paths to the current run (persisted for later rollback). */
     recordTouched(absPaths: string[]): Promise<void>;
     /** The run ran a shell command: per-path attribution is no longer possible. */

package/dist/checkpoint/service.js

@@ -36,6 +36,14 @@ export class CheckpointService {
     pinnedStore;
     runSummary = "agent run";
     active = null;
+    /** In-flight `ensureCheckpoint` construction (C.33). PROMISE-latched, not
+     * value-latched: two concurrent gated writes to this root await the SAME
+     * snapshot instead of each taking one (the once-per-run latch `this.active`
+     * is only set AFTER several awaits, so a boolean/value latch would let a
+     * second caller slip through and double-snapshot). The approval mutex already
+     * serializes gated writes, so this is defense-in-depth — but it makes the
+     * service correct on its own, independent of the caller's discipline. */
+    pending = null;
     constructor(opts) {
         this.root = path.resolve(opts.root);
         this.config = opts.config;
@@ -44,6 +52,7 @@ export class CheckpointService {
     /** Start a new undo unit: reset the once-per-run latch and name the run. */
     beginRun(summary) {
         this.active = null;
+        this.pending = null;
         const firstLine = summary.split("\n", 1)[0].trim();
         this.runSummary =
             firstLine.length > 80
@@ -62,6 +71,17 @@ export class CheckpointService {
             return null;
         if (this.active)
             return this.active;
+        // Coalesce concurrent first-use: a second caller awaits the first's snapshot
+        // rather than starting a second one. Cleared on settle so a FAILED attempt
+        // (which leaves `this.active` null) lets the next call retry.
+        if (this.pending)
+            return this.pending;
+        this.pending = this.buildCheckpoint().finally(() => {
+            this.pending = null;
+        });
+        return this.pending;
+    }
+    async buildCheckpoint() {
         const gitWorkTree = this.pinnedStore
             ? this.pinnedStore.kind === "git"
             : isGitWorkTree(this.root);

package/dist/checkpoint/set-rollback.d.ts

@@ -0,0 +1,51 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { ActionPreview } from "../tools/types.js";
+import { CheckpointService } from "./service.js";
+import type { CheckpointSet, CheckpointStore, RollbackPlan, SetRollbackApplied } from "./types.js";
+/**
+ * Set-based rollback orchestration (C.26 step 3). Restore every member of a run's
+ * {@link CheckpointSet} as one gated operation, with the R3/⚖︎#8 guarantees:
+ *   1. **validate-all before any apply** — every member's checkpoint must load and
+ *      plan cleanly first ({@link validateSet}); a missing/corrupt one throws
+ *      `CRUXY_E_CHECKPOINT_SET_INCOMPLETE` and NOTHING is applied.
+ *   2. **one combined preview** grouped by root ({@link buildSetPreview}), each with
+ *      its own external-change warnings, behind one U.3 approval (⚖︎JC-ι).
+ *   3. **sequential apply, stop on first failure** ({@link applySet}) →
+ *      `CRUXY_E_CHECKPOINT_SET_PARTIAL` carrying restored-vs-not; the plan is
+ *      recomputed from disk each run, so an idempotent re-run finishes the job.
+ */
+export type CreateService = (root: string, config: CruxyConfig) => CheckpointService;
+/** A member whose rollback has been fully validated + planned, ready to apply. */
+export interface ValidatedMember {
+    rootName: string;
+    rootPath: string;
+    checkpointId: string;
+    plan: RollbackPlan;
+    store: CheckpointStore;
+    preview: Extract<ActionPreview, {
+        type: "rollback";
+    }>;
+}
+/**
+ * Validate + plan EVERY member up front (R3 gate #1). Loads each root's checkpoint
+ * and computes its rollback plan/preview; the first member that cannot be loaded
+ * throws `CRUXY_E_CHECKPOINT_SET_INCOMPLETE` — before any filesystem apply — so a
+ * partial rollback can never masquerade as success.
+ */
+export declare function validateSet(set: CheckpointSet, config: CruxyConfig, createService?: CreateService): Promise<ValidatedMember[]>;
+/**
+ * One combined preview grouped by root (⚖︎JC-ι): each root keeps its own file diffs
+ * and external-change warnings, so a single U.3 approval covers the whole set.
+ */
+export declare function buildSetPreview(set: CheckpointSet, members: ValidatedMember[]): Extract<ActionPreview, {
+    type: "rollback-set";
+}>;
+/**
+ * Apply the validated set sequentially, stopping on the first failure (R3/⚖︎#8).
+ * On any member's failure this throws `CRUXY_E_CHECKPOINT_SET_PARTIAL` with the
+ * restored-vs-not split; re-running (which recomputes each plan from disk) safely
+ * finishes the job.
+ */
+export declare function applySet(set: CheckpointSet, members: ValidatedMember[]): Promise<SetRollbackApplied>;
+/** Is a validated set a no-op (every member's plan is empty)? */
+export declare function setIsNoop(members: ValidatedMember[]): boolean;

package/dist/checkpoint/set-rollback.js

@@ -0,0 +1,74 @@
+import { checkpointSetIncomplete } from "../errors/index.js";
+import { applyRollback, buildRollbackPreview, computeRollbackPlan, } from "./restore.js";
+import { CheckpointService, createCheckpointStore, isGitWorkTree, } from "./service.js";
+import { applySetRollback } from "./set.js";
+function defaultCreate(root, config) {
+    return new CheckpointService({ root, config });
+}
+/**
+ * Validate + plan EVERY member up front (R3 gate #1). Loads each root's checkpoint
+ * and computes its rollback plan/preview; the first member that cannot be loaded
+ * throws `CRUXY_E_CHECKPOINT_SET_INCOMPLETE` — before any filesystem apply — so a
+ * partial rollback can never masquerade as success.
+ */
+export async function validateSet(set, config, createService = defaultCreate) {
+    const validated = [];
+    for (const member of set.members) {
+        const svc = createService(member.rootPath, config);
+        let checkpoint;
+        try {
+            checkpoint = await svc.read(member.checkpointId);
+        }
+        catch (err) {
+            throw checkpointSetIncomplete(set.runId, `root "${member.rootName}" checkpoint ${member.checkpointId} is missing or unreadable ` +
+                `(${err.message})`);
+        }
+        const store = createCheckpointStore(member.rootPath, checkpoint.store);
+        const plan = await computeRollbackPlan(member.rootPath, checkpoint, store, isGitWorkTree(member.rootPath));
+        const preview = await buildRollbackPreview(member.rootPath, plan, store);
+        validated.push({
+            rootName: member.rootName,
+            rootPath: member.rootPath,
+            checkpointId: member.checkpointId,
+            plan,
+            store,
+            preview,
+        });
+    }
+    return validated;
+}
+/**
+ * One combined preview grouped by root (⚖︎JC-ι): each root keeps its own file diffs
+ * and external-change warnings, so a single U.3 approval covers the whole set.
+ */
+export function buildSetPreview(set, members) {
+    return {
+        type: "rollback-set",
+        runId: set.runId,
+        createdAt: set.createdAt,
+        runSummary: set.runSummary,
+        roots: members.map((m) => ({
+            rootName: m.rootName,
+            checkpointId: m.checkpointId,
+            files: m.preview.files,
+            externalPaths: m.preview.externalPaths,
+            attributionUnknown: m.preview.attributionUnknown,
+        })),
+    };
+}
+/**
+ * Apply the validated set sequentially, stopping on the first failure (R3/⚖︎#8).
+ * On any member's failure this throws `CRUXY_E_CHECKPOINT_SET_PARTIAL` with the
+ * restored-vs-not split; re-running (which recomputes each plan from disk) safely
+ * finishes the job.
+ */
+export async function applySet(set, members) {
+    return applySetRollback(set.runId, members.map((m) => ({
+        rootName: m.rootName,
+        restore: () => applyRollback(m.rootPath, m.plan, m.store),
+    })));
+}
+/** Is a validated set a no-op (every member's plan is empty)? */
+export function setIsNoop(members) {
+    return members.every((m) => m.plan.entries.length === 0);
+}

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

@@ -1,10 +1,15 @@
 import { Command } from "commander";
 /**
- * `cruxy rollback [id]` (C.32) — restore the working tree to a checkpoint,
- * undoing everything an agent run changed (creates, edits, deletes) in one
- * operation. Destructive by definition, so it is preview-first and gated
- * through U.3 at the destructive tier, ungrantable; non-TTY is refused with a
- * coded error before anything is computed. Out of scope, stated in the
- * preview: commits, pushes, and PRs made during the run are not undone.
+ * `cruxy rollback [id]` (C.32/C.26) — restore the working tree to a run's
+ * checkpoint(s), undoing everything an agent run changed in one operation.
+ * Destructive by definition, so it is preview-first and gated through U.3 at the
+ * destructive tier, ungrantable; non-TTY is refused with a coded error before
+ * anything is computed. Out of scope, stated in the preview: commits, pushes, and
+ * PRs made during the run are not undone.
+ *
+ * Routing:
+ *   • an explicit `<id>` → single-root rollback of that checkpoint (escape hatch);
+ *   • no id, a set manifest exists → set-based rollback of the latest run;
+ *   • no id, no set manifest → JC-F fallback to legacy single-root, logged.
  */
 export declare function rollbackCommand(): Command;