@cruxy/cli 0.22.0 → 0.23.0

package/dist/checkpoint/types.d.ts

@@ -115,3 +115,50 @@ export interface RollbackApplied {
     reverted: number;
     deleted: number;
 }
+/**
+ * One touched root inside a {@link CheckpointSet}: the declared root's name (for
+ * attribution in the preview), its absolute path, and the id of the per-root
+ * checkpoint that protects it. There is exactly ONE member per root the run
+ * mutated — an untouched root has no member and is never opened at rollback.
+ */
+export interface CheckpointSetMember {
+    /** Declared workspace-root name (shown in the grouped preview). */
+    rootName: string;
+    /** Absolute path of the root (where its `.cruxy/checkpoints/` live). */
+    rootPath: string;
+    /** The checkpoint id within that root. */
+    checkpointId: string;
+}
+/**
+ * A run's rollback unit across N repos (C.26). `cruxy rollback` restores **all
+ * members** of a set as one gated operation — exactly the roots the run touched,
+ * no more (untouched roots are absent) and no less (a touched root missing its
+ * member is a loud `CRUXY_E_CHECKPOINT_SET_INCOMPLETE`, never a silent partial).
+ *
+ * The set manifest lives under the PRIMARY root's `.cruxy/checkpoints/sets/`, so
+ * it travels with the workspace and survives `rm -rf ~/.cruxy`. The member
+ * checkpoints themselves live in each root, exactly as in the single-root case.
+ */
+export interface CheckpointSet {
+    /** Stable run id, e.g. `run-20260708T031500-a4f2`. */
+    runId: string;
+    /** ISO-8601 creation time (of the set, i.e. the run's first mutation). */
+    createdAt: string;
+    /** One line describing the run this set protects. */
+    runSummary: string;
+    /** One entry per TOUCHED root. */
+    members: CheckpointSetMember[];
+}
+/**
+ * The outcome of a successful all-roots rollback: which roots were restored and
+ * what each did. On a mid-apply failure this is NOT returned — a
+ * `CRUXY_E_CHECKPOINT_SET_PARTIAL` is thrown instead, carrying the restored-vs-not
+ * split (R3), so a partial can never read as success.
+ */
+export interface SetRollbackApplied {
+    runId: string;
+    /** Root names restored, in apply order. */
+    restored: string[];
+    /** Per-root counts, keyed by root name. */
+    perRoot: Record<string, RollbackApplied>;
+}

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

package/dist/cli/onboard.js

@@ -1,6 +1,7 @@
 import { resolveApiKey } from "../config/index.js";
 import { createDefaultDeps, defaultOnboardingIO, isFirstRun, runOnboarding, } from "../onboarding/index.js";
 import { createRenderer } from "../render/index.js";
+import { singleRootWorkspace } from "../workspace/index.js";
 import { buildAgentSession } from "./session-factory.js";
 /**
  * CLI-layer glue between the entry points and the onboarding module (U.6). Keeps
@@ -24,7 +25,9 @@ export async function runFirstWinTask(config, cwd, prompt) {
     if (!apiKey)
         return; // defensive — the key was just persisted
     const renderer = createRenderer();
-    const session = buildAgentSession(config, apiKey, cwd, true, false, renderer);
+    // The onboarding first-win is inherently single-root (it runs before any
+    // `--root` is parsed), so it acts over a trivial workspace on its cwd.
+    const session = buildAgentSession(config, apiKey, singleRootWorkspace(cwd), true, false, renderer);
     try {
         await session.send(prompt, renderer);
     }

package/dist/cli/repl.d.ts

@@ -1,6 +1,6 @@
 import type { Readable, Writable } from "node:stream";
 import type { Session } from "../agent/index.js";
-import type { CheckpointService } from "../checkpoint/index.js";
+import type { CheckpointGate } from "../checkpoint/index.js";
 import { type SlashCommandSpec } from "../hooks/index.js";
 import { type StreamRenderer } from "../render/index.js";
 /**
@@ -24,4 +24,4 @@ export interface ReplIO {
  * live region, anything else the plain append-only renderer); `cruxy run`
  * passes its own so the approval prompt's status-suspend hook shares it.
  */
-export declare function runInteractive(session: Session, io?: ReplIO, renderer?: StreamRenderer, checkpoints?: CheckpointService, slashCommands?: readonly SlashCommandSpec[]): Promise<void>;
+export declare function runInteractive(session: Session, io?: ReplIO, renderer?: StreamRenderer, checkpoints?: CheckpointGate, slashCommands?: readonly SlashCommandSpec[]): Promise<void>;

package/dist/cli/session-factory.d.ts

@@ -1,10 +1,11 @@
 import type { CruxyConfig } from "../config/index.js";
 import type { ApprovalDecision } from "../approval/index.js";
-import type { CheckpointService } from "../checkpoint/index.js";
+import type { CheckpointGate } from "../checkpoint/index.js";
 import type { SandboxService } from "../sandbox/index.js";
 import type { StreamRenderer } from "../render/index.js";
 import { type ApproveAction, type Tool } from "../tools/index.js";
 import { Session, type LifecycleHookRunner } from "../agent/index.js";
+import type { Workspace } from "../workspace/index.js";
 /**
  * Wrap the approval gate with the C.32 auto-checkpoint hook. Ordering is the
  * whole point: a tool mutates only *after* `requestApproval` resolves, so
@@ -14,7 +15,7 @@ import { Session, type LifecycleHookRunner } from "../agent/index.js";
  * (file actions) or that attribution is lost (shell), for rollback's
  * external-change detection.
  */
-export declare function withCheckpointGate(requestApproval: (action: ApproveAction) => Promise<ApprovalDecision>, checkpoints: CheckpointService | undefined, cwd: string): (action: ApproveAction) => Promise<ApprovalDecision>;
+export declare function withCheckpointGate(requestApproval: (action: ApproveAction) => Promise<ApprovalDecision>, gate: CheckpointGate | undefined, ws: Workspace): (action: ApproveAction) => Promise<ApprovalDecision>;
 /**
  * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
  * shared by `cruxy run` and the onboarding first-win task (so they can't drift).
@@ -24,4 +25,4 @@ export declare function withCheckpointGate(requestApproval: (action: ApproveActi
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointService, sandbox?: SandboxService, hooks?: LifecycleHookRunner, mcpTools?: Tool[]): Session;
+export declare function buildAgentSession(config: CruxyConfig, apiKey: string, workspace: Workspace, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointGate, sandbox?: SandboxService, hooks?: LifecycleHookRunner, mcpTools?: Tool[]): Session;

package/dist/cli/session-factory.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { createProvider } from "@cruxy/sdk";
 import { loadProjectInstructions } from "../config/index.js";
 import { logger } from "../utils/logger.js";
@@ -61,28 +62,90 @@ function resumeLineAfterApproval(requestApproval, renderer) {
  * (file actions) or that attribution is lost (shell), for rollback's
  * external-change detection.
  */
-export function withCheckpointGate(requestApproval, checkpoints, cwd) {
-    if (!checkpoints)
+export function withCheckpointGate(requestApproval, gate, ws) {
+    if (!gate)
         return requestApproval;
     return async (action) => {
         const decision = await requestApproval(action);
         if (!decision.allow)
             return decision;
-        const request = classify(action, cwd);
+        const request = classify(action, ws.primary().absPath);
         if (request.tier === "read")
             return decision;
-        await checkpoints.ensureCheckpoint();
-        // Shell AND test executions (C.13) can mutate files we can't attribute
-        // (scripts, snapshot writers) — record the lost attribution the same way.
         if (action.kind === "shell" || action.kind === "test") {
-            await checkpoints.recordShellMutation();
+            // JC-β residual: non-primary shell/test are Step 5, so they are still
+            // hard-attributed to the primary root regardless of `action.root` (which
+            // those tools populate as the seam). They can mutate files we cannot
+            // attribute (scripts, snapshot writers) — record the lost attribution.
+            const root = ws.primary();
+            const svc = gate.serviceFor(root.name, root.absPath);
+            const checkpoint = await svc.ensureCheckpoint();
+            await svc.recordShellMutation();
+            if (checkpoint) {
+                await gate.recordMember(root.name, root.absPath, checkpoint.id);
+            }
+            return decision;
+        }
+        if (action.kind === "vcs") {
+            // C.26 Step 4: a PR now names its root (⚖︎#11), so the checkpoint is
+            // attributed to THAT selected root — its git commit stages/lands in that
+            // root's working tree, never the primary's. `recordShellMutation` because a
+            // `git add -A` + commit mutates the tree opaquely (no per-file attribution).
+            // Fall back to the primary only if a root name is somehow absent (defensive).
+            const root = (action.root ? ws.tryRootByName(action.root) : undefined) ??
+                ws.primary();
+            const svc = gate.serviceFor(root.name, root.absPath);
+            const checkpoint = await svc.ensureCheckpoint();
+            await svc.recordShellMutation();
+            if (checkpoint) {
+                await gate.recordMember(root.name, root.absPath, checkpoint.id);
+            }
+            return decision;
         }
-        else {
-            await checkpoints.recordTouched([...request.targets]);
+        // File actions (write/edit/patch): attribute each RESOLVED target to its root
+        // (JC-G — post-confinement truth) and checkpoint every touched root. A patch
+        // may span roots; each root gets its own checkpoint + set member.
+        for (const [rootName, group] of attributeFileTargets(action, ws)) {
+            const svc = gate.serviceFor(rootName, group.rootAbsPath);
+            const checkpoint = await svc.ensureCheckpoint();
+            await svc.recordTouched(group.paths);
+            if (checkpoint) {
+                await gate.recordMember(rootName, group.rootAbsPath, checkpoint.id);
+            }
         }
         return decision;
     };
 }
+/**
+ * Group a file action's resolved absolute targets by the root that contains each
+ * (JC-G). write/edit carry an already-absolute `path`; patch preview paths are
+ * relative to the PRIMARY cwd (`path.relative(ctx.cwd, abs)` in apply_patch), so
+ * we reconstruct the absolute path from the primary root rather than trusting
+ * classify's `targets` — which also correctly handles a patch spanning roots.
+ */
+function attributeFileTargets(action, ws) {
+    const abs = [];
+    if (action.kind === "write" || action.kind === "edit") {
+        if (action.path)
+            abs.push(action.path);
+    }
+    else if (action.kind === "patch" && action.preview?.type === "patch") {
+        for (const file of action.preview.files) {
+            abs.push(path.resolve(ws.primary().absPath, file.path));
+        }
+    }
+    const byRoot = new Map();
+    for (const target of abs) {
+        const root = ws.rootContaining(target);
+        const group = byRoot.get(root.name) ?? {
+            rootAbsPath: root.absPath,
+            paths: [],
+        };
+        group.paths.push(target);
+        byRoot.set(root.name, group);
+    }
+    return byRoot;
+}
 /**
  * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
  * shared by `cruxy run` and the onboarding first-win task (so they can't drift).
@@ -92,7 +155,14 @@ export function withCheckpointGate(requestApproval, checkpoints, cwd) {
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer, checkpoints, sandbox, hooks, mcpTools = []) {
+export function buildAgentSession(config, apiKey, workspace, ttyInteractive, planMode = false, renderer, checkpoints, sandbox, hooks, mcpTools = []) {
+    // The workspace is the single source of truth for "which roots" (C.26). Every
+    // primary-scoped subsystem below (git context, project instructions, memory,
+    // checkpoints, subagents, the approval gate) derives its cwd from the primary
+    // root, so cwd can never disagree with `workspace.primary()`. The full workspace
+    // is threaded onto the ToolContext so the fan tools see every root; the subagent
+    // orchestrator receives it too, so a child sees the SAME roots as the main loop.
+    const cwd = workspace.primary().absPath;
     const provider = createProvider({
         provider: config.model.provider,
         apiKey,
@@ -173,7 +243,11 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
     // prompt + same checkpoint hook, but a new (empty) session allowlist — a
     // grant in the parent never silently widens a child's authority.
     const io = suspendStatusOnPrompt(defaultPromptIO(shouldUseColor()), renderer);
-    const gate = (approval) => withCheckpointGate(resumeLineAfterApproval((action) => approval.requestApproval(action), renderer), checkpoints, cwd);
+    // The C.26 coupling: `checkpointsActive` is true exactly when a per-root gate is
+    // wired, and it is set on the SAME ctx whose `requestApproval` IS that gate — so
+    // lifting the non-primary-write refusal and capturing the write are one decision.
+    const checkpointsActive = Boolean(checkpoints);
+    const gate = (approval) => withCheckpointGate(resumeLineAfterApproval((action) => approval.requestApproval(action), renderer), checkpoints, workspace);
     // Subagent orchestration (C.14): spawn_subagent goes on the main registry
     // only when depth allows (maxDepth 0 disables the feature structurally).
     // Registered before the plan wiring so plan-mode execution steps can
@@ -184,11 +258,13 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         router,
         parentRegistry: execRegistry,
         cwd,
+        workspace,
         logger,
         git,
         projectInstructions,
         renderer,
         sandbox,
+        checkpointsActive,
         makeChildApproval: () => gate(new ApprovalService({ cwd, interactive: ttyInteractive, io })),
     });
     if (config.subagent.maxDepth > 0) {
@@ -207,9 +283,11 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         });
         const ctx = {
             cwd,
+            workspace,
             config,
             logger,
             requestApproval: gate(approval),
+            checkpointsActive,
             sandbox,
         };
         const planRunner = ({ messages, projectInstructions, recalledMemory: turnMemory, renderer: turnRenderer, onRequestUsage, }) => runPlanSession({
@@ -248,7 +326,15 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         interactive: ttyInteractive,
         io,
     });
-    const ctx = { cwd, config, logger, requestApproval: gate(approval), sandbox };
+    const ctx = {
+        cwd,
+        workspace,
+        config,
+        logger,
+        requestApproval: gate(approval),
+        checkpointsActive,
+        sandbox,
+    };
     return new Session({
         provider,
         registry: execRegistry,