@cruxy/cli 0.22.0 → 0.22.1

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,
@@ -150,7 +152,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/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/index.d.ts

@@ -4,3 +4,4 @@ export * from "./git-store.js";
 export * from "./shadow-store.js";
 export * from "./restore.js";
 export * from "./service.js";
+export * from "./set.js";

package/dist/checkpoint/index.js

@@ -4,3 +4,4 @@ export * from "./git-store.js";
 export * from "./shadow-store.js";
 export * from "./restore.js";
 export * from "./service.js";
+export * from "./set.js";

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");
+    });
+}

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/errors/constructors.d.ts

@@ -119,6 +119,43 @@ export declare function checkpointNotFound(id?: string): CruxyError;
  * Restoring is destructive and deliberate — there is no auto-rollback path, ever.
  */
 export declare function rollbackApprovalRequired(): CruxyError;
+/**
+ * A path/selector names a workspace root that is not in the declared set — an
+ * unknown root name, or an absolute path that lands in no declared root. Fail-loud
+ * by design and NEVER fuzzy-matched to a nearby root (R1): a silent near-match is
+ * a cross-root misfire. Refused before any FS access.
+ */
+export declare function rootUnknown(ref: string, known: readonly string[]): CruxyError;
+/**
+ * A path is ambiguous across the declared root set: an absolute path inside ≥2
+ * declared roots, or a mutating tool given no root when there is no unambiguous
+ * choice. Writes fail closed rather than guess which repo to touch.
+ */
+export declare function rootAmbiguous(ref: string, candidates: string[]): CruxyError;
+/**
+ * Declaration-time: a declared root nests inside / overlaps another. Refused at
+ * session start — overlap makes "which root owns this path" ambiguous and lets two
+ * checkpoints/grants fight over the same bytes.
+ */
+export declare function rootOverlap(a: string, b: string): CruxyError;
+/**
+ * An interactive add-root was refused: no TTY to confirm, or the user declined the
+ * confirm/trust prompt. The root set only ever grows by an explicit human act —
+ * never the model, never a repo-local config.
+ */
+export declare function rootAddRefused(reason: string): CruxyError;
+/**
+ * A multi-root rollback set references a member checkpoint that is missing or
+ * corrupt, or a touched root has no member. Loud — a partial rollback must never
+ * masquerade as success.
+ */
+export declare function checkpointSetIncomplete(runId: string, reason: string): CruxyError;
+/**
+ * A multi-root rollback failed mid-apply (R3): it restored some roots and not
+ * others, and it STOPPED rather than continue best-effort. Carries the exact
+ * restored-vs-not split; re-running rollback is idempotent and safe.
+ */
+export declare function checkpointSetPartial(runId: string, restored: string[], notRestored: string[], underlying?: unknown): CruxyError;
 /**
  * A subagent spawn was attempted past the configured nesting cap (C.14). The
  * spawn tool is structurally withheld at the cap, so reaching this means the

package/dist/errors/constructors.js

@@ -551,6 +551,115 @@ export function rollbackApprovalRequired() {
         ],
     });
 }
+// ── multi-repo / workspace (exit 18) — C.26 ───────────────────────────────────
+/**
+ * A path/selector names a workspace root that is not in the declared set — an
+ * unknown root name, or an absolute path that lands in no declared root. Fail-loud
+ * by design and NEVER fuzzy-matched to a nearby root (R1): a silent near-match is
+ * a cross-root misfire. Refused before any FS access.
+ */
+export function rootUnknown(ref, known) {
+    return new CruxyError({
+        code: ErrorCode.RootUnknown,
+        title: `no workspace root named "${ref}"`,
+        cause: "the root set is fixed at session start and matched exactly — never by prefix or nearest-name",
+        nextSteps: [
+            known.length
+                ? `declared roots: ${known.join(", ")}`
+                : "no additional roots are declared this session",
+            "pass --root <name>=<path> at startup, or add one interactively",
+        ],
+        meta: { ref, known: [...known] },
+    });
+}
+/**
+ * A path is ambiguous across the declared root set: an absolute path inside ≥2
+ * declared roots, or a mutating tool given no root when there is no unambiguous
+ * choice. Writes fail closed rather than guess which repo to touch.
+ */
+export function rootAmbiguous(ref, candidates) {
+    return new CruxyError({
+        code: ErrorCode.RootAmbiguous,
+        title: `"${ref}" is ambiguous across the declared roots`,
+        cause: candidates.length > 1
+            ? `it resolves inside more than one declared root: ${candidates.join(", ")}`
+            : "a mutating action must name exactly one root",
+        nextSteps: [
+            "name the root explicitly with the `root` argument",
+            "declare either the monorepo root OR its packages, never both (overlap is refused)",
+        ],
+        meta: { ref, candidates },
+    });
+}
+/**
+ * Declaration-time: a declared root nests inside / overlaps another. Refused at
+ * session start — overlap makes "which root owns this path" ambiguous and lets two
+ * checkpoints/grants fight over the same bytes.
+ */
+export function rootOverlap(a, b) {
+    return new CruxyError({
+        code: ErrorCode.RootOverlap,
+        title: "declared workspace roots overlap",
+        cause: `"${a}" nests inside or equals "${b}"`,
+        nextSteps: [
+            "declare the monorepo root OR specific package roots, never both",
+            "remove one of the overlapping --root entries",
+        ],
+        meta: { a, b },
+    });
+}
+/**
+ * An interactive add-root was refused: no TTY to confirm, or the user declined the
+ * confirm/trust prompt. The root set only ever grows by an explicit human act —
+ * never the model, never a repo-local config.
+ */
+export function rootAddRefused(reason) {
+    return new CruxyError({
+        code: ErrorCode.RootAddRefused,
+        title: "adding a workspace root was refused",
+        cause: reason,
+        nextSteps: [
+            "declare roots up front with --root at startup",
+            "add a root only from an interactive terminal, where it can be confirmed and trusted",
+        ],
+        meta: { reason },
+    });
+}
+/**
+ * A multi-root rollback set references a member checkpoint that is missing or
+ * corrupt, or a touched root has no member. Loud — a partial rollback must never
+ * masquerade as success.
+ */
+export function checkpointSetIncomplete(runId, reason) {
+    return new CruxyError({
+        code: ErrorCode.CheckpointSetIncomplete,
+        title: `rollback set "${runId}" is incomplete`,
+        cause: reason,
+        nextSteps: [
+            "run `cruxy checkpoint list` to inspect each root's checkpoints",
+            "roll back an individual root's checkpoint with `cruxy rollback <id>` if needed",
+        ],
+        meta: { runId, reason },
+    });
+}
+/**
+ * A multi-root rollback failed mid-apply (R3): it restored some roots and not
+ * others, and it STOPPED rather than continue best-effort. Carries the exact
+ * restored-vs-not split; re-running rollback is idempotent and safe.
+ */
+export function checkpointSetPartial(runId, restored, notRestored, underlying) {
+    return new CruxyError({
+        code: ErrorCode.CheckpointSetPartial,
+        title: `rollback of set "${runId}" stopped partway`,
+        cause: `restored: ${restored.join(", ") || "none"}; not restored: ${notRestored.join(", ") || "none"}`,
+        nextSteps: [
+            "re-run `cruxy rollback` — it recomputes each root from disk and is safe to retry",
+            "the not-restored roots are unchanged; no root is left half-applied silently",
+        ],
+        underlying,
+        meta: { runId, restored, notRestored },
+    });
+}
 // ── subagent (exit 2 / 11) ────────────────────────────────────────────────────
 /**
  * A subagent spawn was attempted past the configured nesting cap (C.14). The

package/dist/errors/types.d.ts

@@ -119,6 +119,32 @@ export declare const ErrorCode: {
      * (SSRF guard — e.g. 127.0.0.1, 169.254.169.254, 10.x, internal DNS). A
      * security stop, kept distinct from an ordinary fetch failure for grep-ability. */
     readonly WebBlockedHost: "CRUXY_E_WEB_BLOCKED_HOST";
+    /** A path/selector names a workspace root that is not in the declared set (or an
+     * absolute path that lands in no declared root). Fail-loud and NEVER fuzzy- or
+     * prefix-matched to a nearby root — a silent near-match is a cross-root misfire.
+     * Refused before any FS access; never falls through to the host filesystem. */
+    readonly RootUnknown: "CRUXY_E_ROOT_UNKNOWN";
+    /** A path is ambiguous across the declared root set: an absolute path that falls
+     * inside ≥2 declared roots, or a mutating tool given no root when there's no
+     * unambiguous choice. Writes fail closed rather than guess a root. */
+    readonly RootAmbiguous: "CRUXY_E_ROOT_AMBIGUOUS";
+    /** Declaration-time: a declared root nests inside / overlaps another. Refused at
+     * session start — overlap makes "which root owns this path" ambiguous and lets
+     * two checkpoints/grants fight over the same bytes. Declare the monorepo root OR
+     * its packages, never both. */
+    readonly RootOverlap: "CRUXY_E_ROOT_OVERLAP";
+    /** An interactive add-root was refused: no TTY to confirm, or the user declined
+     * the confirm/trust prompt. The root set only ever grows by an explicit human
+     * act — never by the model or a repo-local config. */
+    readonly RootAddRefused: "CRUXY_E_ROOT_ADD_REFUSED";
+    /** A multi-root rollback set references a member checkpoint that is missing or
+     * corrupt, or a touched root has no member. Loud — a partial rollback must never
+     * masquerade as success. */
+    readonly CheckpointSetIncomplete: "CRUXY_E_CHECKPOINT_SET_INCOMPLETE";
+    /** A multi-root rollback failed mid-apply (R3): carries which roots were restored
+     * and which were not. The set is left recoverable by an idempotent re-run and is
+     * NEVER reported as success. */
+    readonly CheckpointSetPartial: "CRUXY_E_CHECKPOINT_SET_PARTIAL";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -138,6 +138,33 @@ export const ErrorCode = {
      * (SSRF guard — e.g. 127.0.0.1, 169.254.169.254, 10.x, internal DNS). A
      * security stop, kept distinct from an ordinary fetch failure for grep-ability. */
     WebBlockedHost: "CRUXY_E_WEB_BLOCKED_HOST",
+    // multi-repo / workspace (exit 18) — C.26
+    /** A path/selector names a workspace root that is not in the declared set (or an
+     * absolute path that lands in no declared root). Fail-loud and NEVER fuzzy- or
+     * prefix-matched to a nearby root — a silent near-match is a cross-root misfire.
+     * Refused before any FS access; never falls through to the host filesystem. */
+    RootUnknown: "CRUXY_E_ROOT_UNKNOWN",
+    /** A path is ambiguous across the declared root set: an absolute path that falls
+     * inside ≥2 declared roots, or a mutating tool given no root when there's no
+     * unambiguous choice. Writes fail closed rather than guess a root. */
+    RootAmbiguous: "CRUXY_E_ROOT_AMBIGUOUS",
+    /** Declaration-time: a declared root nests inside / overlaps another. Refused at
+     * session start — overlap makes "which root owns this path" ambiguous and lets
+     * two checkpoints/grants fight over the same bytes. Declare the monorepo root OR
+     * its packages, never both. */
+    RootOverlap: "CRUXY_E_ROOT_OVERLAP",
+    /** An interactive add-root was refused: no TTY to confirm, or the user declined
+     * the confirm/trust prompt. The root set only ever grows by an explicit human
+     * act — never by the model or a repo-local config. */
+    RootAddRefused: "CRUXY_E_ROOT_ADD_REFUSED",
+    /** A multi-root rollback set references a member checkpoint that is missing or
+     * corrupt, or a touched root has no member. Loud — a partial rollback must never
+     * masquerade as success. */
+    CheckpointSetIncomplete: "CRUXY_E_CHECKPOINT_SET_INCOMPLETE",
+    /** A multi-root rollback failed mid-apply (R3): carries which roots were restored
+     * and which were not. The set is left recoverable by an idempotent re-run and is
+     * NEVER reported as success. */
+    CheckpointSetPartial: "CRUXY_E_CHECKPOINT_SET_PARTIAL",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -228,6 +255,17 @@ const EXIT_CODES = {
     [ErrorCode.WebSearch]: 17,
     [ErrorCode.WebFetch]: 17,
     [ErrorCode.WebBlockedHost]: 17,
+    // Multi-repo / workspace (C.26). Declaration-time root-set problems
+    // (unknown/ambiguous/overlap/add-refused) and multi-root rollback failures
+    // (incomplete/partial) share a greppable exit code. A cross-root *path* is NOT
+    // here — it reuses CRUXY_E_PATH_ESCAPE (a cross-root path is an escape from the
+    // acting root; a distinct code would wrongly imply "less bad").
+    [ErrorCode.RootUnknown]: 18,
+    [ErrorCode.RootAmbiguous]: 18,
+    [ErrorCode.RootOverlap]: 18,
+    [ErrorCode.RootAddRefused]: 18,
+    [ErrorCode.CheckpointSetIncomplete]: 18,
+    [ErrorCode.CheckpointSetPartial]: 18,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/sandbox/docker-runtime.js

@@ -151,7 +151,10 @@ export function buildRunArgs(policy, container, command) {
         "--tmpfs",
         `${policy.tmpfs}:rw,nosuid,nodev,size=64m`, // … except an in-memory tmp
         "-v",
-        mountSpec(policy.workdir), // ONLY the workdir, read-write
+        mountSpec(policy.workdir), // the command's own root, read-write
+        // Other declared roots (C.26, R5): read-only unless a per-command escalation
+        // flipped one to rw. Ambient cross-root write is never the default.
+        ...(policy.siblingRoots ?? []).flatMap((m) => ["-v", mountSpec(m)]),
         ...policy.mounts.flatMap((m) => ["-v", mountSpec(m)]),
         "-w",
         policy.workdir.target,

package/dist/sandbox/policy.d.ts

@@ -5,8 +5,12 @@ import type { IsolationPolicy } from "./types.js";
  * {@link IsolationPolicy}. This is where the security posture is decided, and
  * every default here is deny/minimal:
  *
- * - the ONLY read-write mount is the project workdir (at its identical absolute
- *   path, so paths stay coherent with the host and the C.32 checkpoint);
+ * - the DEFAULT read-write mount is the command's own project workdir (at its
+ *   identical absolute path, so paths stay coherent with the host and the C.32
+ *   checkpoint);
+ * - other declared roots in a multi-repo session (C.26, R5) are mounted READ-ONLY
+ *   — readable for legit cross-repo builds, never writable unless an explicit
+ *   per-command escalation names that root in `writableRoots`;
  * - extra mounts come solely from `sandbox.mounts` (explicit by construction),
  *   and a mount of the docker socket, the cruxy home, or the user's home root
  *   is rejected — those are the escape hatches we refuse to open;
@@ -14,4 +18,9 @@ import type { IsolationPolicy } from "./types.js";
  *   writable and never left root-owned;
  * - network defaults to `none`; any widening can only come from explicit config.
  */
-export declare function buildPolicy(cfg: SandboxConfig, cwd: string): IsolationPolicy;
+export declare function buildPolicy(cfg: SandboxConfig, cwd: string, opts?: {
+    /** Absolute paths of the OTHER declared roots (this command's siblings). */
+    siblingRoots?: readonly string[];
+    /** Sibling roots that got an approved cross-root-write escalation (R5). */
+    writableRoots?: readonly string[];
+}): IsolationPolicy;