@cruxy/cli 0.22.1 → 0.23.0

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,

package/dist/errors/constructors.d.ts

@@ -90,6 +90,33 @@ export declare function forgeAuth(host?: string): CruxyError;
 export declare function gitProtectedBranch(branch: string): CruxyError;
 /** The forge REST API returned an error (non-auth) while opening a PR. */
 export declare function forgeApi(title: string, underlying?: unknown, meta?: Record<string, unknown>): CruxyError;
+/**
+ * The `origin` remote of the acting root resolved to a DIFFERENT `owner/repo`
+ * between the U.3 preview (what the human approved) and the moment the pull-request
+ * API call is made — a concurrent `git remote set-url` on a mutable `.git/config`
+ * (C.26 Step 4). The PR is NOT opened: we refuse rather than warn-and-proceed,
+ * because opening it would target a repo the human never saw. Both targets are
+ * named so the discrepancy is legible. `owner/repo` are already-parsed identifiers
+ * (never an upstream model id), so the message is gag-safe by construction (U.8).
+ */
+export declare function vcsRemoteChanged(approved: {
+    host: string;
+    owner: string;
+    repo: string;
+}, current: {
+    host: string;
+    owner: string;
+    repo: string;
+}, rootName: string): CruxyError;
+/**
+ * A pull request was requested for one declared root while a SIBLING declared root
+ * shares the same git working tree — two non-overlapping roots inside one repo
+ * (e.g. `packages/a` + `packages/b` under one `.git`), which filesystem-overlap
+ * refusal does not catch (C.26 Step 4). A commit there `git add -A`s the sibling's
+ * changes too, so the PR would span both roots. A PR is a single-repo artifact, so
+ * we refuse (naming both) rather than silently PR one half.
+ */
+export declare function vcsCrossRoot(root: string, sibling: string, repoPath: string): CruxyError;
 /**
  * `git push` failed — most often the husky `pre-push` verify hook (build ·
  * typecheck · lint · test) or a rejected non-fast-forward. We never `--force` or
@@ -137,6 +164,7 @@ export declare function rootAmbiguous(ref: string, candidates: string[]): CruxyE
  * session start — overlap makes "which root owns this path" ambiguous and lets two
  * checkpoints/grants fight over the same bytes.
  */
+export declare function multirootWriteDeferred(root: string, primary: string): CruxyError;
 export declare function rootOverlap(a: string, b: string): CruxyError;
 /**
  * An interactive add-root was refused: no TTY to confirm, or the user declined the

package/dist/errors/constructors.js

@@ -440,6 +440,50 @@ export function forgeApi(title, underlying, meta) {
         meta,
     });
 }
+/**
+ * The `origin` remote of the acting root resolved to a DIFFERENT `owner/repo`
+ * between the U.3 preview (what the human approved) and the moment the pull-request
+ * API call is made — a concurrent `git remote set-url` on a mutable `.git/config`
+ * (C.26 Step 4). The PR is NOT opened: we refuse rather than warn-and-proceed,
+ * because opening it would target a repo the human never saw. Both targets are
+ * named so the discrepancy is legible. `owner/repo` are already-parsed identifiers
+ * (never an upstream model id), so the message is gag-safe by construction (U.8).
+ */
+export function vcsRemoteChanged(approved, current, rootName) {
+    const fmt = (r) => `${r.host}/${r.owner}/${r.repo}`;
+    return new CruxyError({
+        code: ErrorCode.VcsRemoteChanged,
+        title: "refusing to open the pull request — the target repository changed",
+        cause: `you approved a PR against ${fmt(approved)}, but the "${rootName}" root's ` +
+            `origin remote now resolves to ${fmt(current)}`,
+        nextSteps: [
+            "check `git remote get-url origin` in that root — it was changed mid-run",
+            "re-run `cruxy pr` (or the tool) so the approval matches the current remote",
+        ],
+        meta: { approved, current, root: rootName },
+    });
+}
+/**
+ * A pull request was requested for one declared root while a SIBLING declared root
+ * shares the same git working tree — two non-overlapping roots inside one repo
+ * (e.g. `packages/a` + `packages/b` under one `.git`), which filesystem-overlap
+ * refusal does not catch (C.26 Step 4). A commit there `git add -A`s the sibling's
+ * changes too, so the PR would span both roots. A PR is a single-repo artifact, so
+ * we refuse (naming both) rather than silently PR one half.
+ */
+export function vcsCrossRoot(root, sibling, repoPath) {
+    return new CruxyError({
+        code: ErrorCode.VcsCrossRoot,
+        title: `refusing to open a pull request that would span two roots`,
+        cause: `the "${root}" and "${sibling}" roots share one git repository (${repoPath}), ` +
+            "so a commit for one would sweep in the other's changes",
+        nextSteps: [
+            "open the pull request from that repository directly, outside cruxy's multi-root session",
+            "or declare only one root inside that repository (the roots share a single `.git`)",
+        ],
+        meta: { root, sibling, repoPath },
+    });
+}
 /**
  * `git push` failed — most often the husky `pre-push` verify hook (build ·
  * typecheck · lint · test) or a rejected non-fast-forward. We never `--force` or
@@ -596,6 +640,21 @@ export function rootAmbiguous(ref, candidates) {
  * session start — overlap makes "which root owns this path" ambiguous and lets two
  * checkpoints/grants fight over the same bytes.
  */
+export function multirootWriteDeferred(root, primary) {
+    return new CruxyError({
+        code: ErrorCode.MultirootWriteDeferred,
+        title: `writes to non-primary root "${root}" are deferred until per-root ` +
+            `checkpoints ship in the next step — write to the primary root ` +
+            `"${primary}", or run single-root (omit --root) to edit this repo now`,
+        cause: "per-root checkpoints are not yet wired, so a write outside the primary " +
+            "root could not be rolled back — it is refused rather than left un-restorable",
+        nextSteps: [
+            `write to the primary root "${primary}" instead`,
+            "or run single-root (omit --root) if you need to edit this repo now",
+        ],
+        meta: { root, primary },
+    });
+}
 export function rootOverlap(a, b) {
     return new CruxyError({
         code: ErrorCode.RootOverlap,

package/dist/errors/types.d.ts

@@ -137,6 +137,12 @@ export declare const ErrorCode: {
      * 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 write targeted a NON-PRIMARY root while per-root checkpoints are not yet
+     * wired (C.26 Step 2b). Refused so "every write cruxy makes is checkpointed and
+     * rollback-able" stays true — an un-checkpointed write to a sibling root would be
+     * silently un-restorable when rollback reverts the primary. Lifted in Step 3 when
+     * per-root checkpoints ship. Reads to any root are unaffected. */
+    readonly MultirootWriteDeferred: "CRUXY_E_MULTIROOT_WRITE_DEFERRED";
     /** 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. */
@@ -145,6 +151,20 @@ export declare const ErrorCode: {
      * 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";
+    /** VCS target-integrity guard (C.26 Step 4): the `origin` remote of the acting
+     * root resolved to a DIFFERENT `owner/repo` between the U.3 preview (what the
+     * human approved) and the moment the pull-request API call is made (a concurrent
+     * `git remote set-url` on a mutable `.git/config`). The PR is NOT opened —
+     * refused, never warn-and-proceed — and both the approved and current targets are
+     * named. Reachable single-root too; introduced with the multi-root VCS hardening. */
+    readonly VcsRemoteChanged: "CRUXY_E_VCS_REMOTE_CHANGED";
+    /** A pull request was requested for one declared root while a SIBLING declared
+     * root shares the same git working tree (two non-overlapping roots inside one
+     * repo, e.g. `packages/a` + `packages/b` under one `.git`). A commit there would
+     * `git add -A` the sibling's changes too, so the PR would span both roots — a PR
+     * is a single-repo artifact, so it is refused (naming both) rather than silently
+     * PR one half. */
+    readonly VcsCrossRoot: "CRUXY_E_VCS_CROSS_ROOT";
 };
 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

@@ -157,6 +157,12 @@ export const ErrorCode = {
      * 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 write targeted a NON-PRIMARY root while per-root checkpoints are not yet
+     * wired (C.26 Step 2b). Refused so "every write cruxy makes is checkpointed and
+     * rollback-able" stays true — an un-checkpointed write to a sibling root would be
+     * silently un-restorable when rollback reverts the primary. Lifted in Step 3 when
+     * per-root checkpoints ship. Reads to any root are unaffected. */
+    MultirootWriteDeferred: "CRUXY_E_MULTIROOT_WRITE_DEFERRED",
     /** 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. */
@@ -165,6 +171,20 @@ export const ErrorCode = {
      * 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",
+    /** VCS target-integrity guard (C.26 Step 4): the `origin` remote of the acting
+     * root resolved to a DIFFERENT `owner/repo` between the U.3 preview (what the
+     * human approved) and the moment the pull-request API call is made (a concurrent
+     * `git remote set-url` on a mutable `.git/config`). The PR is NOT opened —
+     * refused, never warn-and-proceed — and both the approved and current targets are
+     * named. Reachable single-root too; introduced with the multi-root VCS hardening. */
+    VcsRemoteChanged: "CRUXY_E_VCS_REMOTE_CHANGED",
+    /** A pull request was requested for one declared root while a SIBLING declared
+     * root shares the same git working tree (two non-overlapping roots inside one
+     * repo, e.g. `packages/a` + `packages/b` under one `.git`). A commit there would
+     * `git add -A` the sibling's changes too, so the PR would span both roots — a PR
+     * is a single-repo artifact, so it is refused (naming both) rather than silently
+     * PR one half. */
+    VcsCrossRoot: "CRUXY_E_VCS_CROSS_ROOT",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -264,8 +284,14 @@ const EXIT_CODES = {
     [ErrorCode.RootAmbiguous]: 18,
     [ErrorCode.RootOverlap]: 18,
     [ErrorCode.RootAddRefused]: 18,
+    [ErrorCode.MultirootWriteDeferred]: 18,
     [ErrorCode.CheckpointSetIncomplete]: 18,
     [ErrorCode.CheckpointSetPartial]: 18,
+    // VCS multi-root safety (C.26 Step 4). A remote that changed under the acting
+    // root, and a PR that would span two same-repo roots, are both target-integrity
+    // refusals kin to the other cross-root guards — they share the greppable code.
+    [ErrorCode.VcsRemoteChanged]: 18,
+    [ErrorCode.VcsCrossRoot]: 18,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/indexing/retriever.d.ts

@@ -8,6 +8,21 @@ export interface SearchOptions {
     k?: number;
     /** Optional glob restricting results by path, e.g. `src/**\/*.ts`. */
     pathGlob?: string;
+    /**
+     * The declared name of the root being searched (C.26). Stamped onto every
+     * returned hit so a fanned multi-root search can attribute each hit to its
+     * source root. Required: this retriever runs against exactly one root's store,
+     * so the caller that selected that store names it here — no hit is unattributed.
+     */
+    root: string;
+    /**
+     * Per-call override of the snippet token budget (C.26). A fanned multi-root
+     * search passes `Infinity` so each root returns its top-k by score *unbudgeted*,
+     * then applies the real budget ONCE over the merged set ({@link mergeRankedHits},
+     * ⚖︎JC-I) — a true global budget, not the budget applied N× (once per root).
+     * Omitted by single-root callers, who keep the config budget (byte-identical).
+     */
+    tokenBudget?: number;
 }
 /** Collaborators + budget knobs for the retriever. */
 export interface RetrieverDeps {
@@ -30,3 +45,17 @@ export interface RetrieverDeps {
  * context window.
  */
 export declare function searchCodebase(deps: RetrieverDeps, opts: SearchOptions): Promise<SearchHit[]>;
+/**
+ * Merge per-root hit lists into one globally-ranked, budgeted, k-capped list —
+ * the cross-root half of a fanned {@link searchCodebase}. The cap and the token
+ * budget are applied **after** the merge (⚖︎JC-I), so `k` is a global top-k across
+ * all roots (a strong hit in root B is never crowded out by weaker hits in root A
+ * that a per-root cap happened to keep), and the combined snippet budget is
+ * honored once for the whole result — not N× as it would be if each root budgeted
+ * independently. Hits already carry their `root`, so the merge never loses
+ * attribution. Mirrors the single-root budget rule: always keep the top hit.
+ */
+export declare function mergeRankedHits(perRoot: readonly (readonly SearchHit[])[], opts: {
+    k: number;
+    tokenBudget: number;
+}): SearchHit[];

package/dist/indexing/retriever.js

@@ -23,6 +23,7 @@ export async function searchCodebase(deps, opts) {
             break;
         remaining -= cost;
         hits.push({
+            root: opts.root,
             path: record.path,
             startLine: record.startLine,
             endLine: record.endLine,
@@ -32,6 +33,31 @@ export async function searchCodebase(deps, opts) {
     }
     return hits;
 }
+/**
+ * Merge per-root hit lists into one globally-ranked, budgeted, k-capped list —
+ * the cross-root half of a fanned {@link searchCodebase}. The cap and the token
+ * budget are applied **after** the merge (⚖︎JC-I), so `k` is a global top-k across
+ * all roots (a strong hit in root B is never crowded out by weaker hits in root A
+ * that a per-root cap happened to keep), and the combined snippet budget is
+ * honored once for the whole result — not N× as it would be if each root budgeted
+ * independently. Hits already carry their `root`, so the merge never loses
+ * attribution. Mirrors the single-root budget rule: always keep the top hit.
+ */
+export function mergeRankedHits(perRoot, opts) {
+    const all = perRoot.flat().sort((a, b) => b.score - a.score);
+    const kept = [];
+    let remaining = opts.tokenBudget;
+    for (const hit of all) {
+        if (kept.length >= opts.k)
+            break;
+        const cost = estimateTokens(hit.snippet);
+        if (kept.length > 0 && cost > remaining)
+            break;
+        remaining -= cost;
+        kept.push(hit);
+    }
+    return kept;
+}
 /** Build a path predicate from a glob (compiled once). */
 function buildPathFilter(glob) {
     const re = globToRegExp(glob);

package/dist/indexing/service.js

@@ -52,7 +52,9 @@ class IndexServiceImpl {
             store: this.store,
             embedder: this.embedder,
             defaultK: this.config.search.defaultK,
-            tokenBudget: this.config.search.tokenBudget,
+            // A fanned multi-root search overrides this with Infinity so the budget
+            // is applied once globally after the merge, not once per root (⚖︎JC-I).
+            tokenBudget: opts.tokenBudget ?? this.config.search.tokenBudget,
             maxSnippetLines: this.config.search.maxSnippetLines,
         }, opts);
     }

package/dist/indexing/types.d.ts

@@ -31,6 +31,13 @@ export interface ScoredRecord {
 }
 /** One ranked search result handed back to the agent. */
 export interface SearchHit {
+    /**
+     * The declared name of the root this hit was indexed from (C.26). Required —
+     * so a hit can never be un-attributed — and stamped at construction from the
+     * same root whose store produced it, which is what lets a fanned multi-root
+     * search label each hit with its true source (the honesty pin).
+     */
+    root: string;
     path: string;
     startLine: number;
     endLine: number;

package/dist/lsp/tools/common.d.ts

@@ -1,23 +1,50 @@
 import type { ToolContext, ToolResult } from "../../tools/types.js";
+import type { DeclaredRoot } from "../../workspace/index.js";
 import { type LspService } from "../service.js";
 import type { LspLocation } from "../types.js";
 /**
- * The shared spine of every LSP tool (C.12): enforce the master switch, validate
- * the target path stays in the project root, prove it exists, get the per-cwd
- * service, and run `query`. Read-only throughout — no `ctx.requestApproval`, so
- * these bypass the U.3 gate exactly like `search_codebase` and `grep_files`.
+ * The root a query ran against, threaded to the tool so it can label locations by
+ * their source root and — for references — name the per-root limitation (C.26).
+ */
+export interface LspRootContext {
+    /** The declared root whose language-server pool answered the query. */
+    root: DeclaredRoot;
+    /** Whether this is a genuine multi-root session (labels render only then). */
+    isMultiRoot: boolean;
+}
+/**
+ * The shared spine of every LSP tool (C.12): enforce the master switch, resolve
+ * the target file to the ONE declared root that contains it, prove it exists, get
+ * THAT root's language-server pool, and run `query`. Read-only throughout — no
+ * `ctx.requestApproval`, so these bypass the U.3 gate exactly like `search_codebase`
+ * and `grep_files`.
+ *
+ * Multi-repo (C.26, Funnel A→pool): the file is resolved through the shared
+ * `resolveToolPath`, so it commits to exactly one root, and the pool is keyed by
+ * THAT root's `absPath` (`getLspService` caches per resolved cwd → a per-root map
+ * for free). A file in root B is answered by B's server, never A's — the
+ * `(file → root)` selection and the `(root → pool)` key are the same value.
  *
  * Errors are surfaced as `{ ok:false }` text the agent can act on: a coded LSP
  * failure (no server / timeout / crash) is rendered WITH its next step, so the
  * agent can reroute (e.g. to grep) or the user can install the server. A genuine
  * empty answer never reaches here as an error — `query` returns it as `ok:true`.
  */
-export declare function runLspTool(ctx: ToolContext, file: string, query: (service: LspService, absFile: string) => Promise<ToolResult>): Promise<ToolResult>;
+export declare function runLspTool(ctx: ToolContext, file: string, query: (service: LspService, absFile: string, rc: LspRootContext) => Promise<ToolResult>): Promise<ToolResult>;
+/**
+ * A note stating that a per-root language server only sees its own root, so
+ * references/definitions in sibling roots are NOT searched (⚖︎JC-7) — returned only
+ * in a multi-root session, so a references list is never read as complete when it
+ * silently could not span roots. Empty string in single-root (byte-identical).
+ */
+export declare function crossRootNote(rc: LspRootContext): string;
 /**
  * Render up to `max` locations as `path:line:col-endLine:endCol`, one per line,
  * with a trailing "N more" note when capped — the same bounded-honest pattern as
- * grep_files and search_codebase (never silently drop the overflow).
+ * grep_files and search_codebase (never silently drop the overflow). In a
+ * multi-root session each path is labelled `‹root› ▸ path` (the query ran against
+ * one root, so every location carries that root's label).
  */
-export declare function formatLocations(locations: LspLocation[], max: number): string;
+export declare function formatLocations(locations: LspLocation[], max: number, rc: LspRootContext): string;
 /** Relative label for a validated absolute path, for tool messages. */
 export declare function relLabel(cwd: string, absFile: string): string;