@cruxy/cli 0.22.1 → 0.23.0

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/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/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;

package/dist/cli/commands/rollback.js

@@ -1,7 +1,8 @@
+import path from "node:path";
 import { Command } from "commander";
 import { themeForColor } from "../../theme/index.js";
 import { loadConfig } from "../../config/index.js";
-import { CheckpointService } from "../../checkpoint/index.js";
+import { CheckpointService, applySet, buildSetPreview, listSets, setIsNoop, validateSet, } from "../../checkpoint/index.js";
 import { ApprovalService, defaultPromptIO } from "../../approval/index.js";
 import { fuzzyFind, selectList } from "../../components/index.js";
 import { rollbackApprovalRequired, shouldUseColor, } from "../../errors/index.js";
@@ -41,17 +42,88 @@ async function pickCheckpoint(service) {
     return result.kind === "selected" ? result.value : null;
 }
 /**
- * `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.
+ * Legacy single-root rollback (C.32): restore one root's checkpoint. Reached for
+ * an explicit `cruxy rollback <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 pre-set-manifest run.
+ */
+async function legacyRollback(root, config, approval, interactive, id, t) {
+    const service = new CheckpointService({ root, config });
+    if (id === undefined) {
+        const picked = await pickCheckpoint(service);
+        if (picked === null) {
+            logger.print(t.muted("rollback cancelled — nothing was changed"));
+            return;
+        }
+        id = picked?.id;
+    }
+    const result = await service.rollback(id, {
+        requestApproval: (action) => approval.requestApproval(action),
+        interactive,
+    });
+    if (result.kind === "noop") {
+        logger.print(t.muted(`working tree already matches checkpoint ${result.checkpoint.id} — nothing to roll back`));
+        return;
+    }
+    if (result.kind === "rejected") {
+        logger.print(t.muted("rollback declined — nothing was changed"));
+        return;
+    }
+    const { recreated, reverted, deleted } = result.applied;
+    logger.print(`${t.success(t.glyph.success)} restored checkpoint ${t.accent(result.checkpoint.id)} — ` +
+        `${reverted} reverted, ${recreated} recreated, ${deleted} deleted`);
+    logger.print(t.muted("note: commits, pushes, and PRs made during the run are not undone"));
+}
+/**
+ * Set-based rollback (C.26): restore every touched root of the latest run as one
+ * gated operation. Validate-ALL members up front (missing/corrupt →
+ * `CHECKPOINT_SET_INCOMPLETE`, nothing applied), one combined per-root preview and
+ * one U.3 approval, then a sequential apply that stops on first failure
+ * (`CHECKPOINT_SET_PARTIAL`, R3). Both coded errors propagate to the boundary.
+ */
+async function setRollback(primaryRoot, config, approval, t) {
+    const sets = await listSets(primaryRoot); // newest first
+    const set = sets[0];
+    // Validate-all BEFORE any apply — a missing/corrupt member throws here.
+    const members = await validateSet(set, config);
+    if (setIsNoop(members)) {
+        logger.print(t.muted(`working tree already matches run ${set.runId} — nothing to roll back`));
+        return;
+    }
+    const decision = await approval.requestApproval({
+        kind: "rollback",
+        preview: buildSetPreview(set, members),
+    });
+    if (!decision.allow) {
+        logger.print(t.muted("rollback declined — nothing was changed"));
+        return;
+    }
+    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)`;
+    });
+    logger.print(`${t.success(t.glyph.success)} restored run ${t.accent(set.runId)} across ` +
+        `${applied.restored.length} root${applied.restored.length === 1 ? "" : "s"} — ${parts.join("; ")}`);
+    logger.print(t.muted("note: 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 function rollbackCommand() {
     return new Command("rollback")
         .description("restore the working tree to a checkpoint, undoing a run's file changes")
-        .argument("[id]", "checkpoint id (defaults to the most recent)")
+        .argument("[id]", "checkpoint id (defaults to the most recent run)")
         .action(async (id) => {
         const interactive = Boolean(process.stdin.isTTY);
         // Refuse before touching anything: rollback is a deliberate, interactive
@@ -60,38 +132,26 @@ export function rollbackCommand() {
             throw rollbackApprovalRequired();
         const t = themeForColor(shouldUseColor(process.stdout));
         const { config } = loadConfig();
-        const root = process.cwd();
-        const service = new CheckpointService({ root, config });
+        const primaryRoot = process.cwd();
         const approval = new ApprovalService({
-            cwd: root,
+            cwd: primaryRoot,
             interactive,
             io: defaultPromptIO(shouldUseColor()),
         });
-        // No id given → pick one interactively (U.7). Enter-once still restores
-        // the newest, exactly as before the picker existed.
-        if (id === undefined) {
-            const picked = await pickCheckpoint(service);
-            if (picked === null) {
-                logger.print(t.muted("rollback cancelled — nothing was changed"));
-                return;
-            }
-            id = picked?.id;
-        }
-        const result = await service.rollback(id, {
-            requestApproval: (action) => approval.requestApproval(action),
-            interactive,
-        });
-        if (result.kind === "noop") {
-            logger.print(t.muted(`working tree already matches checkpoint ${result.checkpoint.id} — nothing to roll back`));
+        // Explicit id → single-root path (the per-member escape hatch; also the
+        // recovery route if the primary root — and its set index — was removed).
+        if (id !== undefined) {
+            await legacyRollback(primaryRoot, config, approval, interactive, id, t);
             return;
         }
-        if (result.kind === "rejected") {
-            logger.print(t.muted("rollback declined — nothing was changed"));
+        // No set manifest → JC-F: fall back to legacy single-root, logged (never
+        // silent). The primary root name matches single-root workspace naming.
+        const sets = await listSets(primaryRoot);
+        if (sets.length === 0) {
+            logger.info(`no set manifest — single-root rollback against ${path.basename(primaryRoot)}`);
+            await legacyRollback(primaryRoot, config, approval, interactive, undefined, t);
             return;
         }
-        const { recreated, reverted, deleted } = result.applied;
-        logger.print(`${t.success(t.glyph.success)} restored checkpoint ${t.accent(result.checkpoint.id)} — ` +
-            `${reverted} reverted, ${recreated} recreated, ${deleted} deleted`);
-        logger.print(t.muted("note: commits, pushes, and PRs made during the run are not undone"));
+        await setRollback(primaryRoot, config, approval, t);
     });
 }

package/dist/cli/commands/run.js

@@ -5,7 +5,7 @@ import { authMissingKey, shouldUseColor, usageError, } from "../../errors/index.
 import { createRenderer } from "../../render/index.js";
 import { themeForColor } from "../../theme/index.js";
 import { summarizeRuns, renderSummary, } from "../../usage/index.js";
-import { CheckpointService } from "../../checkpoint/index.js";
+import { CheckpointGate } from "../../checkpoint/index.js";
 import { SandboxService } from "../../sandbox/index.js";
 import { buildHooksService } from "../../hooks/index.js";
 import { runInteractive } from "../repl.js";
@@ -14,12 +14,27 @@ import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 import { resetLspServices } from "../../lsp/index.js";
 import { connectMcpTools, resetMcpServices } from "../../mcp/index.js";
 import { defaultPromptIO } from "../../approval/index.js";
+import { buildWorkspace, singleRootWorkspace, } from "../../workspace/index.js";
+/**
+ * Parse one repeatable `--root` value into a {@link RootSpec} and append it. Form
+ * `name=path` (explicit name) or a bare `path` (basename-named by buildWorkspace).
+ * All existence/dir/overlap/name validation is delegated to buildWorkspace, which
+ * fails loud — this only splits the flag.
+ */
+function collectRoot(value, acc) {
+    const eq = value.indexOf("=");
+    const spec = eq === -1
+        ? { path: value }
+        : { name: value.slice(0, eq), path: value.slice(eq + 1) };
+    return [...acc, spec];
+}
 export function runCommand() {
     return new Command("run")
         .description("run a task once, or start an interactive session")
         .argument("[prompt...]", "the task for cruxy to perform (omit for interactive)")
         .option("--plan", "plan mode: propose a step-by-step plan for approval before executing")
         .option("--sandbox", "run shell + test commands inside an isolated container (fails loud if no runtime)")
+        .option("--root <spec>", "declare a workspace root (repeatable): name=path or path; the first is primary", collectRoot, [])
         .action(async (promptParts, opts) => {
         const prompt = promptParts.join(" ").trim();
         const t = themeForColor(shouldUseColor(process.stdout));
@@ -31,8 +46,40 @@ export function runCommand() {
         }
         const { config, sources } = loadConfig();
         let apiKey = resolveApiKey(config.model.provider);
+        // Declared workspace roots (C.26). This is the ONE place `run` reads the
+        // process working directory — the invocation directory is the base for
+        // resolving `--root` paths and the sole root when none are declared. Every
+        // subsystem below derives its cwd from the WORKSPACE (`primaryRoot`), never
+        // re-reads the invocation directory, so nothing can silently split-brain to
+        // a different dir than the roots the tools see (the guard test pins this).
+        const invocationCwd = process.cwd();
+        // No --root → a trivial single-root workspace (byte-identical to pre-C.26).
+        // --root builds a genuine multi-root Workspace and fails fast HERE — a
+        // missing / non-dir / overlapping root (CRUXY_E_ROOT_OVERLAP) throws before
+        // onboarding or the session starts, never a half-built session.
+        const workspace = opts.root.length
+            ? await buildWorkspace(opts.root, { cwd: invocationCwd })
+            : singleRootWorkspace(invocationCwd);
+        const primaryRoot = workspace.primary().absPath;
         logger.info(t.muted(`model:   ${config.model.provider}/${config.model.model}`));
         logger.info(t.muted(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
+        // Multi-root honesty (JC-6/C.26): reads fan every root. With per-root
+        // checkpoints active (C.26 step 3), writes fan every root too — each is
+        // checkpointed and rollback-able. With checkpoints DISABLED, a non-primary
+        // write is still refused (CRUXY_E_MULTIROOT_WRITE_DEFERRED) rather than left
+        // un-restorable. Hooks + MCP still scope to the primary this release. Named
+        // at start, never a silent primary-default.
+        if (workspace.isMultiRoot) {
+            const names = workspace
+                .roots()
+                .map((r) => r.name)
+                .join(", ");
+            const writes = config.checkpoint.enabled
+                ? "writes fan all roots (each checkpointed)"
+                : "writes scope to primary (checkpoints disabled)";
+            logger.info(t.muted(`roots:   ${workspace.roots().length} (${names}); primary ${workspace.primary().name} — ` +
+                `reads fan all roots; ${writes}; hooks/MCP scope to primary this release`));
+        }
         // First-run with no key (and a TTY) → guided onboarding instead of the
         // dead-end auth error. The first-win demo is offered only in the no-prompt
         // (REPL) path; with a real prompt, that prompt IS the first win.
@@ -40,7 +87,7 @@ export function runCommand() {
             const onboarding = maybeRunOnboarding(config, {
                 ttyInteractive: Boolean(process.stdin.isTTY),
                 offerFirstWin: interactive,
-                cwd: process.cwd(),
+                cwd: primaryRoot,
             });
             if (onboarding === null) {
                 // Not a first run (non-TTY, or onboarded then key removed) → fail loud.
@@ -62,11 +109,13 @@ export function runCommand() {
         // One renderer for the whole run (U.2): the streaming path and the
         // approval prompt's status-suspend hook must share the same live region.
         const renderer = createRenderer();
-        // Checkpoint-before-first-mutation (C.32): the service is latched per run
-        // and fires from the approval seam inside the session, so one instance
-        // covers the one-shot path, every REPL turn, and plan-mode execution.
+        // Checkpoint-before-first-mutation (C.32/C.26): the gate owns one
+        // CheckpointService PER touched root (lazy) plus the run's CheckpointSet,
+        // and fires from the approval seam inside the session — so one instance
+        // covers the one-shot path, every REPL turn, plan-mode execution, and
+        // subagents (they share this gate, so their writes join the run's set).
         const checkpoints = config.checkpoint.enabled
-            ? new CheckpointService({ root: process.cwd(), config })
+            ? new CheckpointGate({ config, primaryRoot })
             : undefined;
         // Sandbox (C.16): opt-in via --sandbox or sandbox.enabled. Resolving the
         // service probes the runtime and THROWS CRUXY_E_SANDBOX_UNAVAILABLE if it
@@ -77,7 +126,7 @@ export function runCommand() {
         const sandbox = sandboxEnabled
             ? await SandboxService.create({
                 config,
-                cwd: process.cwd(),
+                cwd: primaryRoot,
                 reporter: renderer,
             })
             : undefined;
@@ -88,7 +137,7 @@ export function runCommand() {
         // layered catalog and yields the lifecycle runner (threaded into the
         // session) + the resolved custom slash commands (given to the REPL).
         const hooksService = await buildHooksService({
-            cwd: process.cwd(),
+            cwd: primaryRoot,
             config,
             interactive: Boolean(process.stdin.isTTY),
             logger,
@@ -98,13 +147,13 @@ export function runCommand() {
         // default (no servers connect). A non-interactive run with an untrusted
         // config THROWS CRUXY_E_MCP_UNTRUSTED here — before any server spawns.
         const mcp = await connectMcpTools({
-            cwd: process.cwd(),
+            cwd: primaryRoot,
             config,
             logger,
             interactive: Boolean(process.stdin.isTTY),
             io: defaultPromptIO(shouldUseColor()),
         });
-        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksService.runner, mcp.tools);
+        const session = buildAgentSession(config, apiKey, workspace, Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksService.runner, mcp.tools);
         if (interactive) {
             try {
                 await runInteractive(session, undefined, renderer, checkpoints, hooksService.commands);