@cruxy/cli 0.22.0 → 0.23.0

package/dist/approval/classify.js

@@ -62,7 +62,7 @@ function shellRequest(action, root) {
     // scope is the program token. Complex commands get `none` (approve-once only).
     const tokens = commandTokens(command);
     const scope = tokens
-        ? { kind: "shell-prefix", token: tokens[0] }
+        ? { kind: "shell-prefix", token: tokens[0], root }
         : { kind: "none" };
     return {
         action,
@@ -86,7 +86,9 @@ function testRequest(action, root) {
     return {
         action,
         tier: "destructive",
-        scope: command === "" ? { kind: "none" } : { kind: "shell-exact", command },
+        scope: command === ""
+            ? { kind: "none" }
+            : { kind: "shell-exact", command, root },
         summary: `run tests: ${command}`,
         targets: [],
         cwd: root,
@@ -119,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"})`
@@ -150,7 +170,9 @@ function mcpRequest(action, root) {
     return {
         action,
         tier: "destructive",
-        scope: grantable ? { kind: "mcp-tool", server, tool } : { kind: "none" },
+        scope: grantable
+            ? { kind: "mcp-tool", server, tool, root }
+            : { kind: "none" },
         summary: `call MCP tool ${tool || "(unknown)"} on server ${server || "(unknown)"}`,
         targets: [],
         cwd: root,

package/dist/approval/policy.d.ts

@@ -20,6 +20,12 @@ export declare class SessionAllowlist {
  * ({@link commandTokens}) and its program token must equal the granted token —
  * so a `git` grant never matches `git push && rm -rf /`. File: every target must
  * resolve inside the granted subtree.
+ *
+ * Multi-repo (C.26): `shell-prefix`, `shell-exact`, and `mcp-tool` grants are
+ * additionally **bound to the root they were taken in** — the grant only covers a
+ * request whose `cwd` is the same root. So "allow `git` this session" in repo A
+ * never auto-approves `git` in repo B. `file-subtree` needs no such check: it is
+ * an absolute path, so a different root is already a different subtree.
  */
 export declare function scopeCovers(scope: Exclude<Scope, {
     kind: "none";

package/dist/approval/policy.js

@@ -30,28 +30,40 @@ export class SessionAllowlist {
  * ({@link commandTokens}) and its program token must equal the granted token —
  * so a `git` grant never matches `git push && rm -rf /`. File: every target must
  * resolve inside the granted subtree.
+ *
+ * Multi-repo (C.26): `shell-prefix`, `shell-exact`, and `mcp-tool` grants are
+ * additionally **bound to the root they were taken in** — the grant only covers a
+ * request whose `cwd` is the same root. So "allow `git` this session" in repo A
+ * never auto-approves `git` in repo B. `file-subtree` needs no such check: it is
+ * an absolute path, so a different root is already a different subtree.
  */
 export function scopeCovers(scope, request) {
     if (scope.kind === "shell-prefix") {
         if (request.action.kind !== "shell")
             return false;
+        if (scope.root !== request.cwd)
+            return false; // C.26: same root only
         const tokens = commandTokens(request.action.command ?? "");
         return tokens !== null && tokens[0] === scope.token;
     }
     if (scope.kind === "shell-exact") {
         // Test grants (C.13): the exact command string, test actions only — a
-        // grant for `pnpm test` can never cover run_command or any other command.
+        // grant for `pnpm test` can never cover run_command or any other command,
+        // and (C.26) never a test in a different root.
         return (request.action.kind === "test" &&
+            scope.root === request.cwd &&
             (request.action.command ?? "").trim() === scope.command);
     }
     if (scope.kind === "mcp-tool") {
         // MCP grants (C.27): the exact server+tool pair, mcp actions only — a grant
-        // for one server's tool can never cover another tool or another server.
+        // for one server's tool can never cover another tool, another server, or
+        // (C.26) the same tool invoked from a different root.
         return (request.action.kind === "mcp" &&
+            scope.root === request.cwd &&
             request.action.server === scope.server &&
             request.action.tool === scope.tool);
     }
-    // file-subtree
+    // file-subtree — absolute path, inherently root-scoped.
     return (request.targets.length > 0 &&
         request.targets.every((t) => isInside(scope.root, t)));
 }

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

@@ -17,20 +17,26 @@ export type RiskTier = "read" | "mutate" | "destructive";
  * The tight scope a session grant is keyed by. Never blanket.
  * - `shell-prefix` — a command's leading program token (e.g. `git`); only ever
  *   matches commands we can *positively* prove are simple (no shell features).
+ *   **Bound to `root`** (C.26): a `git` grant in repo A never covers `git` in B.
  * - `shell-exact` — one exact command string, for `test` actions only (C.13):
  *   a grant covers re-runs of precisely that test command, nothing else.
+ *   **Bound to `root`**: a `pnpm test` grant in A never covers B.
  * - `file-subtree` — an absolute directory (or, under the root-cap, an exact
- *   file path); matches targets that resolve inside it.
+ *   file path); matches targets that resolve inside it. Inherently root-safe —
+ *   different roots are different absolute subtrees, so it needs no `root` field.
  * - `mcp-tool` — one exact MCP server+tool pair (C.27): a grant covers re-calls
  *   of precisely that tool on that server, and never any other MCP tool.
+ *   **Bound to `root`**: the same server+tool in another root still prompts.
  * - `none` — nothing safe to grant (e.g. a multi-file patch spanning the root).
  */
 export type Scope = {
     readonly kind: "shell-prefix";
     readonly token: string;
+    readonly root: string;
 } | {
     readonly kind: "shell-exact";
     readonly command: string;
+    readonly root: string;
 } | {
     readonly kind: "file-subtree";
     readonly root: string;
@@ -38,6 +44,7 @@ export type Scope = {
     readonly kind: "mcp-tool";
     readonly server: string;
     readonly tool: string;
+    readonly root: string;
 } | {
     readonly kind: "none";
 };

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

@@ -4,3 +4,6 @@ export * from "./git-store.js";
 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

@@ -4,3 +4,6 @@ export * from "./git-store.js";
 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/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/checkpoint/set.d.ts

@@ -0,0 +1,44 @@
+import type { CheckpointSet, RollbackApplied, SetRollbackApplied } from "./types.js";
+/**
+ * Multi-root rollback sets (C.26). A run that mutates N repos produces one
+ * per-root checkpoint plus a {@link CheckpointSet} that ties them together, so
+ * `cruxy rollback` restores exactly the touched roots as one gated operation.
+ *
+ * Two guarantees live here:
+ *   • **exactly the touched roots** — the applier iterates ONLY `set.members`, so
+ *     an untouched root (absent from the set) is never opened;
+ *   • **stop-and-report, never silent partial** (R3) — validate every member up
+ *     front (missing/corrupt → `CHECKPOINT_SET_INCOMPLETE`), then apply
+ *     sequentially and STOP on the first failure, throwing
+ *     `CHECKPOINT_SET_PARTIAL` with the exact restored-vs-not split.
+ */
+/** `run-<utc-stamp>-<rand>` — sortable, collision-safe enough for a local CLI. */
+export declare function newRunId(): string;
+/** The set-manifest directory under the PRIMARY root (⚖︎#7). */
+export declare function setDir(primaryRoot: string): string;
+/** Persist a set manifest (atomic temp-then-rename), self-ignoring from git. */
+export declare function writeSet(primaryRoot: string, set: CheckpointSet): Promise<void>;
+/** Read a set manifest, or throw `CHECKPOINT_SET_INCOMPLETE` if missing/corrupt. */
+export declare function readSet(primaryRoot: string, runId: string): Promise<CheckpointSet>;
+/** List all set manifests under the primary root, newest first. */
+export declare function listSets(primaryRoot: string): Promise<CheckpointSet[]>;
+/**
+ * One root's rollback, pre-validated (its plan already computed): `restore`
+ * actually applies it. The orchestrator builds one per member.
+ */
+export interface MemberRollback {
+    rootName: string;
+    restore: () => Promise<RollbackApplied>;
+}
+/**
+ * Apply an all-roots rollback: run each member's `restore` in order and STOP on
+ * the first failure (R3). On success, returns the restored-vs-per-root summary.
+ * On failure, throws `CHECKPOINT_SET_PARTIAL` naming the roots restored (before
+ * the failure) and those not restored (the failing one + all not-yet-attempted)
+ * — so a partial rollback can never be reported as success, and re-running (which
+ * recomputes each root from disk) safely finishes the job.
+ *
+ * The applier only ever touches roots present in `rollbacks`; an untouched root
+ * (never added to the set) is structurally impossible to open here.
+ */
+export declare function applySetRollback(runId: string, rollbacks: readonly MemberRollback[]): Promise<SetRollbackApplied>;

package/dist/checkpoint/set.js

@@ -0,0 +1,142 @@
+import { randomBytes } from "node:crypto";
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { checkpointSetIncomplete, checkpointSetPartial, } from "../errors/index.js";
+/**
+ * Multi-root rollback sets (C.26). A run that mutates N repos produces one
+ * per-root checkpoint plus a {@link CheckpointSet} that ties them together, so
+ * `cruxy rollback` restores exactly the touched roots as one gated operation.
+ *
+ * Two guarantees live here:
+ *   • **exactly the touched roots** — the applier iterates ONLY `set.members`, so
+ *     an untouched root (absent from the set) is never opened;
+ *   • **stop-and-report, never silent partial** (R3) — validate every member up
+ *     front (missing/corrupt → `CHECKPOINT_SET_INCOMPLETE`), then apply
+ *     sequentially and STOP on the first failure, throwing
+ *     `CHECKPOINT_SET_PARTIAL` with the exact restored-vs-not split.
+ */
+/** `run-<utc-stamp>-<rand>` — sortable, collision-safe enough for a local CLI. */
+export function newRunId() {
+    const stamp = new Date()
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\..+$/, "");
+    return `run-${stamp}-${randomBytes(2).toString("hex")}`;
+}
+/** The set-manifest directory under the PRIMARY root (⚖︎#7). */
+export function setDir(primaryRoot) {
+    return path.join(primaryRoot, ".cruxy", "checkpoints", "sets");
+}
+/** Persist a set manifest (atomic temp-then-rename), self-ignoring from git. */
+export async function writeSet(primaryRoot, set) {
+    const dir = setDir(primaryRoot);
+    await fsp.mkdir(dir, { recursive: true });
+    // The parent checkpoints/ dir already carries a `*` .gitignore; add one here
+    // too so a set manifest is never seen by git even if the layout changes.
+    const ignoreFile = path.join(dir, ".gitignore");
+    try {
+        await fsp.access(ignoreFile);
+    }
+    catch {
+        await fsp.writeFile(ignoreFile, "*\n");
+    }
+    const file = path.join(dir, `${set.runId}.json`);
+    const tmp = `${file}.tmp-${process.pid}`;
+    await fsp.writeFile(tmp, `${JSON.stringify(set, null, 2)}\n`);
+    await fsp.rename(tmp, file);
+}
+/** Read a set manifest, or throw `CHECKPOINT_SET_INCOMPLETE` if missing/corrupt. */
+export async function readSet(primaryRoot, runId) {
+    const file = path.join(setDir(primaryRoot), `${runId}.json`);
+    let raw;
+    try {
+        raw = await fsp.readFile(file, "utf8");
+    }
+    catch {
+        throw checkpointSetIncomplete(runId, `the set manifest is missing or unreadable (${file})`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw checkpointSetIncomplete(runId, "the set manifest is not valid JSON");
+    }
+    if (!isSetShape(parsed)) {
+        throw checkpointSetIncomplete(runId, "the set manifest is malformed");
+    }
+    return parsed;
+}
+/** List all set manifests under the primary root, newest first. */
+export async function listSets(primaryRoot) {
+    const dir = setDir(primaryRoot);
+    let names;
+    try {
+        names = await fsp.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const sets = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const parsed = JSON.parse(await fsp.readFile(path.join(dir, name), "utf8"));
+            if (isSetShape(parsed))
+                sets.push(parsed);
+        }
+        catch {
+            // A corrupt individual manifest is skipped in a listing (it fails loud
+            // only when that specific run is rolled back).
+        }
+    }
+    return sets.sort((a, b) => b.runId.localeCompare(a.runId));
+}
+/**
+ * Apply an all-roots rollback: run each member's `restore` in order and STOP on
+ * the first failure (R3). On success, returns the restored-vs-per-root summary.
+ * On failure, throws `CHECKPOINT_SET_PARTIAL` naming the roots restored (before
+ * the failure) and those not restored (the failing one + all not-yet-attempted)
+ * — so a partial rollback can never be reported as success, and re-running (which
+ * recomputes each root from disk) safely finishes the job.
+ *
+ * The applier only ever touches roots present in `rollbacks`; an untouched root
+ * (never added to the set) is structurally impossible to open here.
+ */
+export async function applySetRollback(runId, rollbacks) {
+    const restored = [];
+    const perRoot = {};
+    for (let i = 0; i < rollbacks.length; i++) {
+        const { rootName, restore } = rollbacks[i];
+        try {
+            perRoot[rootName] = await restore();
+            restored.push(rootName);
+        }
+        catch (err) {
+            const notRestored = rollbacks.slice(i).map((r) => r.rootName);
+            throw checkpointSetPartial(runId, restored, notRestored, err);
+        }
+    }
+    return { runId, restored, perRoot };
+}
+/** Structural check for a parsed set manifest — enough to fail loud on corruption. */
+function isSetShape(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (typeof v.runId !== "string" ||
+        typeof v.createdAt !== "string" ||
+        typeof v.runSummary !== "string" ||
+        !Array.isArray(v.members)) {
+        return false;
+    }
+    return v.members.every((m) => {
+        if (typeof m !== "object" || m === null)
+            return false;
+        const mm = m;
+        return (typeof mm.rootName === "string" &&
+            typeof mm.rootPath === "string" &&
+            typeof mm.checkpointId === "string");
+    });
+}