@cruxy/cli 0.22.0 → 0.23.0

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
@@ -119,6 +146,44 @@ 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 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
+ * 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

@@ -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
@@ -551,6 +595,130 @@ 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 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,
+        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,52 @@ 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 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. */
+    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";
+    /** 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

@@ -138,6 +138,53 @@ 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 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. */
+    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",
+    /** 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
@@ -228,6 +275,23 @@ 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.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;

package/dist/lsp/tools/common.js

@@ -1,13 +1,20 @@
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { CruxyError } from "../../errors/index.js";
-import { resolveInRoot } from "../../tools/file/paths.js";
+import { contextWorkspace, labelPath, resolveToolPath, } from "../../tools/file/paths.js";
 import { getLspService } from "../service.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 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
@@ -21,9 +28,11 @@ export async function runLspTool(ctx, file, query) {
             error: "LSP tools are disabled (set lsp.enabled = true to use language-server features)",
         };
     }
+    const ws = contextWorkspace(ctx);
+    let root;
     let absFile;
     try {
-        absFile = await resolveInRoot(ctx, file);
+        ({ root, abs: absFile } = await resolveToolPath(ctx, { path: file }));
     }
     catch (err) {
         return { ok: false, error: err.message };
@@ -38,8 +47,8 @@ export async function runLspTool(ctx, file, query) {
         return { ok: false, error: `file not found: ${file}` };
     }
     try {
-        const service = getLspService(ctx.cwd, ctx.config, ctx.logger);
-        return await query(service, absFile);
+        const service = getLspService(root.absPath, ctx.config, ctx.logger);
+        return await query(service, absFile, { root, isMultiRoot: ws.isMultiRoot });
     }
     catch (err) {
         return { ok: false, error: describeError(err) };
@@ -54,14 +63,27 @@ function describeError(err) {
     }
     return err.message;
 }
+/**
+ * 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 function crossRootNote(rc) {
+    return rc.isMultiRoot
+        ? `\n(note: only root ‹${rc.root.name}› was searched — a per-root language server does not resolve symbols across roots)`
+        : "";
+}
 /**
  * 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 function formatLocations(locations, max) {
+export function formatLocations(locations, max, rc) {
     const shown = locations.slice(0, max);
-    const lines = shown.map((l) => `${l.path}:${l.startLine}:${l.startCol}-${l.endLine}:${l.endCol}`);
+    const lines = shown.map((l) => `${labelPath(rc.root, l.path, rc.isMultiRoot)}:${l.startLine}:${l.startCol}-${l.endLine}:${l.endCol}`);
     const omitted = locations.length - shown.length;
     if (omitted > 0) {
         lines.push(`… [${omitted} more location(s) omitted]`);

package/dist/lsp/tools/find-definition.js

@@ -27,14 +27,14 @@ export const findDefinitionTool = {
     description: "Resolve where a symbol is defined using the project's language server (go-to-definition). Give the file and the 1-based line/column of the identifier. Returns definition locations as 'path:line:col-endLine:endCol'. Read-only, no approval. Precise where grep is textual — prefer this to jump to a symbol's definition.",
     parameters,
     execute(input, ctx) {
-        return runLspTool(ctx, input.file, async (service, absFile) => {
+        return runLspTool(ctx, input.file, async (service, absFile, rc) => {
             const locations = await service.definition(absFile, input.line, input.column);
             if (locations.length === 0) {
                 return { ok: true, output: "(no definition found)" };
             }
             return {
                 ok: true,
-                output: formatLocations(locations, ctx.config.lsp.maxResults),
+                output: formatLocations(locations, ctx.config.lsp.maxResults, rc),
             };
         });
     },