@cruxy/cli 0.22.1 → 0.23.0

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

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { formatLocations, runLspTool } from "./common.js";
+import { crossRootNote, formatLocations, runLspTool } from "./common.js";
 const parameters = z.object({
     file: z
         .string()
@@ -27,14 +27,20 @@ export const findReferencesTool = {
     description: "Find all references to a symbol using the project's language server. Give the file and the 1-based line/column of the identifier. Returns use sites as 'path:line:col-endLine:endCol' (capped, with an 'N more' note). Read-only, no approval. Precise where grep is textual — prefer this to see every caller/user of a symbol.",
     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.references(absFile, input.line, input.column);
+            // The cross-root note is appended even to an empty result: "(no references)"
+            // from a per-root server must not read as "no references anywhere" (⚖︎JC-7).
             if (locations.length === 0) {
-                return { ok: true, output: "(no references found)" };
+                return {
+                    ok: true,
+                    output: `(no references found)${crossRootNote(rc)}`,
+                };
             }
             return {
                 ok: true,
-                output: formatLocations(locations, ctx.config.lsp.maxResults),
+                output: formatLocations(locations, ctx.config.lsp.maxResults, rc) +
+                    crossRootNote(rc),
             };
         });
     },

package/dist/lsp/tools/get-diagnostics.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { labelPath } from "../../tools/file/paths.js";
 import { runLspTool } from "./common.js";
 const parameters = z.object({
     file: z
@@ -17,23 +18,24 @@ export const getDiagnosticsTool = {
     description: "Get the language server's diagnostics (errors, warnings) for a file. Give the project-relative path. Returns diagnostics as 'severity path:line:col message'. Read-only, no approval. Use this after an edit to see type errors the compiler/linter reports, without running a build.",
     parameters,
     execute(input, ctx) {
-        return runLspTool(ctx, input.file, async (service, absFile) => {
+        return runLspTool(ctx, input.file, async (service, absFile, rc) => {
             const diagnostics = await service.diagnostics(absFile);
             if (diagnostics.length === 0) {
                 return { ok: true, output: "(no diagnostics)" };
             }
             return {
                 ok: true,
-                output: formatDiagnostics(diagnostics, ctx.config.lsp.maxResults),
+                output: formatDiagnostics(diagnostics, ctx.config.lsp.maxResults, rc),
             };
         });
     },
 };
-function formatDiagnostics(diagnostics, max) {
+function formatDiagnostics(diagnostics, max, rc) {
     const shown = diagnostics.slice(0, max);
     const lines = shown.map((d) => {
         const src = d.source ? ` [${d.source}]` : "";
-        return `${d.severity} ${d.path}:${d.range.startLine}:${d.range.startCol} ${d.message}${src}`;
+        const loc = labelPath(rc.root, d.path, rc.isMultiRoot);
+        return `${d.severity} ${loc}:${d.range.startLine}:${d.range.startCol} ${d.message}${src}`;
     });
     const omitted = diagnostics.length - shown.length;
     if (omitted > 0) {

package/dist/render/diff.js

@@ -36,6 +36,10 @@ function renderPatchFiles(files, c) {
 /** Render a `vcs` pull-request publish plan: branch, commit, and PR body. */
 function renderPrPreview(preview, c) {
     const out = [];
+    // The resolved forge destination (⚖︎JC-4): the human sees the real owner/repo the
+    // PR will open against — not just a branch — and it is exactly the target the
+    // wrong-repo guard re-checks before the API call.
+    out.push(`${c.strong("target")}  ${c.accent(`${preview.target.host}/${preview.target.owner}/${preview.target.repo}`)}`);
     out.push(`${c.strong("branch")}  ${c.success(preview.branch)} ${c.glyph.arrow} ${preview.base}`);
     out.push("");
     out.push(c.strong("commit"));
@@ -60,16 +64,46 @@ function renderRollbackPreview(preview, c) {
     if (preview.runSummary)
         out.push(c.muted(`run: ${preview.runSummary}`));
     out.push(c.muted("working-tree files only — commits, pushes, and PRs made during the run are not undone"));
-    if (preview.externalPaths.length > 0) {
+    out.push(...rollbackWarnings(preview.externalPaths, preview.attributionUnknown, c));
+    out.push("");
+    out.push(...renderPatchFiles(preview.files, c));
+    return out;
+}
+/**
+ * The blast-radius warnings for one checkpoint: paths changed outside the tracked
+ * run (which rollback will overwrite), and the shell-attribution caveat. Emitted
+ * BEFORE the file diffs so the global collapse cap can never hide them.
+ */
+function rollbackWarnings(externalPaths, attributionUnknown, c) {
+    const out = [];
+    if (externalPaths.length > 0) {
         out.push(c.danger(c.strong("changed outside this run — rollback will overwrite these too:")));
-        for (const p of preview.externalPaths)
+        for (const p of externalPaths)
             out.push(c.danger(`! ${p}`));
     }
-    if (preview.attributionUnknown) {
+    if (attributionUnknown) {
         out.push(c.warning("this run executed shell commands; some changes below may not have been made by the run"));
     }
-    out.push("");
-    out.push(...renderPatchFiles(preview.files, c));
+    return out;
+}
+/**
+ * Render a multi-root set rollback (C.26): one run header, then each touched root
+ * as its own labeled block with its own warnings + diffs. Grouping is the point —
+ * a reviewer sees which repo each change lands in before the single approval.
+ */
+function renderRollbackSetPreview(preview, c) {
+    const out = [];
+    out.push(`${c.strong("restore run")} ${c.accent(preview.runId)} ${c.muted(`(${preview.createdAt})`)}`);
+    if (preview.runSummary)
+        out.push(c.muted(`run: ${preview.runSummary}`));
+    out.push(c.muted(`${preview.roots.length} root${preview.roots.length === 1 ? "" : "s"} — ` +
+        "working-tree files only; commits, pushes, and PRs made during the run are not undone"));
+    for (const r of preview.roots) {
+        out.push("");
+        out.push(`${c.strong(`root ${r.rootName}`)} ${c.muted(`checkpoint ${r.checkpointId}`)}`);
+        out.push(...rollbackWarnings(r.externalPaths, r.attributionUnknown, c));
+        out.push(...renderPatchFiles(r.files, c));
+    }
     return out;
 }
 /** Split a multi-line body into trimmed-of-trailing lines, dropping a trailing blank. */
@@ -98,6 +132,9 @@ export function renderActionPreview(preview, c) {
     else if (preview.type === "rollback") {
         lines = renderRollbackPreview(preview, c);
     }
+    else if (preview.type === "rollback-set") {
+        lines = renderRollbackSetPreview(preview, c);
+    }
     else {
         const header = preview.exists
             ? c.warning("OVERWRITE existing")

package/dist/subagent/orchestrator.d.ts

@@ -5,6 +5,7 @@ import type { StreamRenderer } from "../render/index.js";
 import type { Router } from "../routing/index.js";
 import type { ApproveAction, ToolContext, ToolRegistry } from "../tools/index.js";
 import type { SandboxService } from "../sandbox/index.js";
+import type { Workspace } from "../workspace/index.js";
 import type { SubagentResult, SubagentSpec } from "./types.js";
 /**
  * Everything a spawn needs from the surrounding session, injected by the
@@ -24,6 +25,13 @@ export interface SubagentOrchestratorDeps {
     /** The parent's registry — the ceiling every child scope derives from. */
     parentRegistry: ToolRegistry;
     cwd: string;
+    /**
+     * The session's declared workspace (C.26). Threaded onto the child ctx so a
+     * subagent sees the SAME roots as the main loop — without it the child would
+     * fall back to a single-root workspace over `cwd` and its fan tools would go
+     * silently primary-only (a split-brain WITHIN one session).
+     */
+    workspace: Workspace;
     logger: ToolContext["logger"];
     git?: {
         branch: string;
@@ -45,6 +53,13 @@ export interface SubagentOrchestratorDeps {
      * one checkpoint, C.32).
      */
     makeChildApproval(): (action: ApproveAction) => Promise<ApprovalDecision>;
+    /**
+     * Whether per-root checkpointing is active for the run (C.26 step 3). Threaded
+     * onto the child ctx so a subagent's non-primary writes lift the JC-1 refusal on
+     * the SAME condition as the parent — and, because `makeChildApproval` wraps the
+     * same shared checkpoint gate, those writes join the run's one set (⚖︎JC-δ).
+     */
+    checkpointsActive?: boolean;
 }
 /**
  * Spawns subagents (C.14): the existing agent loop re-driven over isolated

package/dist/subagent/orchestrator.js

@@ -57,6 +57,7 @@ export class SubagentOrchestrator {
         const artifacts = new Set();
         const ctx = {
             cwd: deps.cwd,
+            workspace: deps.workspace,
             config: deps.config,
             logger: deps.logger,
             requestApproval: async (action) => {
@@ -65,6 +66,7 @@ export class SubagentOrchestrator {
                     recordArtifacts(action, artifacts, deps.cwd);
                 return decision;
             },
+            checkpointsActive: deps.checkpointsActive,
             sandbox: deps.sandbox,
         };
         const label = taskLabel(spec.task);

package/dist/testing/run-tests-tool.js

@@ -97,6 +97,9 @@ export function makeRunTestsTool(deps = {}) {
             const decision = await ctx.requestApproval({
                 kind: "test",
                 command: resolved.command,
+                // C.26 attribution seam (JC-β): primary root name for Steps 4/5. Tests are
+                // primary-only this release; the gate hard-attributes to the primary.
+                root: ctx.workspace?.primary().name,
             });
             if (!decision.allow) {
                 return {

package/dist/tools/create-pull-request.d.ts

@@ -8,14 +8,17 @@ import type { Tool } from "./types.js";
  * never prompted for or stored.
  */
 declare const parameters: z.ZodObject<{
+    root: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
     body: z.ZodOptional<z.ZodString>;
     base: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    root?: string | undefined;
     body?: string | undefined;
     base?: string | undefined;
     title?: string | undefined;
 }, {
+    root?: string | undefined;
     body?: string | undefined;
     base?: string | undefined;
     title?: string | undefined;

package/dist/tools/create-pull-request.js

@@ -1,6 +1,8 @@
+import path from "node:path";
 import { z } from "zod";
-import { CruxyError, ErrorCode } from "../errors/index.js";
-import { createForgeProvider, createPrService, fillContent, loadCommitGuidance, resolveForgeToken, } from "../vcs/index.js";
+import { CruxyError, ErrorCode, vcsCrossRoot } from "../errors/index.js";
+import { createForgeProvider, createPrService, fillContent, gitToplevel, loadCommitGuidance, resolveForgeToken, } from "../vcs/index.js";
+import { contextWorkspace, resolveMutationRoot } from "./file/paths.js";
 /**
  * Open a pull request from the agent's work (C.15): branch → conventional commit
  * → push → open PR, all behind the one U.3 approval. The model authors `title`
@@ -9,6 +11,12 @@ import { createForgeProvider, createPrService, fillContent, loadCommitGuidance,
  * never prompted for or stored.
  */
 const parameters = z.object({
+    root: z
+        .string()
+        .optional()
+        .describe("Workspace root to open the pull request for, by its declared name. Required " +
+        "when the session declares more than one root (a PR targets exactly one " +
+        "repository, so it must not be guessed); optional in a single-root session."),
     title: z
         .string()
         .optional()
@@ -31,11 +39,18 @@ export const createPullRequestTool = {
     parameters,
     async execute(input, ctx) {
         try {
+            // ⚖︎#11 / JC-1: commit to exactly one root first. Multi-root with no `root`
+            // refuses (ROOT_AMBIGUOUS) BEFORE any git runs; single-root defaults to the
+            // primary (byte-identical to pre-C.26). A cross-root PR (a sibling root in the
+            // same repo) is refused too — a PR is a single-repo artifact (JC-3).
+            const selected = resolveMutationRoot(ctx, { root: input.root }, "a pull request");
+            assertSingleRepoRoot(contextWorkspace(ctx), selected);
             const token = resolveForgeToken();
             const forge = createForgeProvider(token);
-            const guidance = await loadCommitGuidance(ctx.cwd);
+            const guidance = await loadCommitGuidance(selected.absPath);
             const service = createPrService({
-                cwd: ctx.cwd,
+                cwd: selected.absPath,
+                rootName: selected.name,
                 config: ctx.config,
                 forge,
                 requestApproval: ctx.requestApproval,
@@ -75,6 +90,37 @@ export const createPullRequestTool = {
         }
     },
 };
+/**
+ * Refuse a PR whose selected root shares one git working tree with a SIBLING
+ * declared root (JC-3). Filesystem-overlap refusal (ROOT_OVERLAP) only catches
+ * nesting; two non-overlapping roots — `packages/a` and `packages/b` under one
+ * `.git` — pass that check yet still share a repo. Committing in one would
+ * `git add -A` the other's changes, so the PR would span both. We detect it by
+ * comparing git top-levels: same top-level ⇒ same repo ⇒ refuse (naming both).
+ *
+ * If the selected root is not in a git repo, there is nothing to compare — the PR
+ * flow fails loudly later at `getRepoInfo`/`currentBranch`. Read-only `rev-parse`
+ * only; this runs after selection, so a no-root multi-root call still spawns zero
+ * git before its ROOT_AMBIGUOUS refusal.
+ */
+function assertSingleRepoRoot(ws, selected) {
+    if (!ws.isMultiRoot)
+        return;
+    const topSelected = gitToplevel(selected.absPath);
+    if (topSelected === null)
+        return;
+    const canonical = path.resolve(topSelected);
+    for (const sibling of ws.roots()) {
+        if (sibling.name === selected.name)
+            continue;
+        const topSibling = gitToplevel(sibling.absPath);
+        if (topSibling === null)
+            continue;
+        if (path.resolve(topSibling) === canonical) {
+            throw vcsCrossRoot(selected.name, sibling.name, canonical);
+        }
+    }
+}
 /** One-line, model-readable rendering of a coded error + its next steps. */
 function formatCoded(err) {
     const head = err.cause ? `${err.title} — ${err.cause}` : err.title;

package/dist/tools/file/apply-patch.js

@@ -1,7 +1,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
-import { resolveInRoot } from "./paths.js";
+import { resolveToolPath } from "./paths.js";
 import { countOccurrences } from "./edit-file.js";
 /** How many leading lines of a created file the approval preview shows. */
 const PREVIEW_LINES = 20;
@@ -62,7 +62,7 @@ export const applyPatchTool = {
             const op = input.operations[i];
             let abs;
             try {
-                abs = await resolveInRoot(ctx, op.path);
+                ({ abs } = await resolveToolPath(ctx, { path: op.path }, { deferNonPrimaryWrite: true }));
             }
             catch (err) {
                 return { ok: false, error: opError(i, op, err.message) };

package/dist/tools/file/edit-file.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import { z } from "zod";
-import { resolveInRoot } from "./paths.js";
+import { resolveToolPath } from "./paths.js";
 /** Count non-overlapping exact occurrences of `needle` in `haystack`. */
 export function countOccurrences(haystack, needle) {
     let count = 0;
@@ -32,7 +32,7 @@ export const editFileTool = {
     async execute(input, ctx) {
         let abs;
         try {
-            abs = await resolveInRoot(ctx, input.path);
+            ({ abs } = await resolveToolPath(ctx, { path: input.path }, { deferNonPrimaryWrite: true }));
         }
         catch (err) {
             return { ok: false, error: err.message };

package/dist/tools/file/glob.d.ts

@@ -1,10 +1,17 @@
 import { z } from "zod";
 import type { Tool } from "../types.js";
 /**
- * Find files by glob pattern within the project root. Read-only — no approval.
- * The pattern is constrained to the root (no absolute or `..` patterns) so glob
+ * Find files by glob pattern within the workspace. Read-only — no approval.
+ * The pattern is constrained to a root (no absolute or `..` patterns) so glob
  * can't reach outside, consistent with the other file tools.
+ *
+ * Multi-repo (C.26, Funnel B): with more than one declared root, glob fans every
+ * root — an independent walk rooted at each root's own `absPath` — and labels each
+ * match `‹root› ▸ path`. There is no path to confine here; the boundary is which
+ * root's `absPath` each walk starts from, so a match can only ever come from the
+ * root its label names. A `root` argument scopes the walk to that one root.
  */
 export declare const globTool: Tool<z.ZodObject<{
     pattern: z.ZodString;
+    root: z.ZodOptional<z.ZodString>;
 }>>;

package/dist/tools/file/glob.js

@@ -1,13 +1,19 @@
-import path from "node:path";
 import { glob } from "tinyglobby";
 import { z } from "zod";
+import { contextWorkspace, isEscapingPattern, labelPath, resolveReadRoots, } from "./paths.js";
 /** Cap on returned paths — beyond this we truncate with a notice. */
 const MAX_RESULTS = 200;
 const DEFAULT_IGNORE = ["**/node_modules/**", "**/.git/**"];
 /**
- * Find files by glob pattern within the project root. Read-only — no approval.
- * The pattern is constrained to the root (no absolute or `..` patterns) so glob
+ * Find files by glob pattern within the workspace. Read-only — no approval.
+ * The pattern is constrained to a root (no absolute or `..` patterns) so glob
  * can't reach outside, consistent with the other file tools.
+ *
+ * Multi-repo (C.26, Funnel B): with more than one declared root, glob fans every
+ * root — an independent walk rooted at each root's own `absPath` — and labels each
+ * match `‹root› ▸ path`. There is no path to confine here; the boundary is which
+ * root's `absPath` each walk starts from, so a match can only ever come from the
+ * root its label names. A `root` argument scopes the walk to that one root.
  */
 export const globTool = {
     name: "glob",
@@ -16,37 +22,85 @@ export const globTool = {
         pattern: z
             .string()
             .describe("Glob pattern, relative to the project root (e.g. 'src/**/*.ts')."),
+        root: z
+            .string()
+            .optional()
+            .describe("In a multi-repo session, restrict the search to a single declared root by name. Omit to search every root and label each match with its root."),
     }),
     async execute(input, ctx) {
         const pattern = input.pattern;
-        if (path.isAbsolute(pattern) || pattern.split(/[/\\]/).includes("..")) {
+        // Walk-rooted tool: the pattern is not a resolvable path, so confinement is
+        // (a) rejecting a pattern that could escape (shared with grep_files) and
+        // (b) rooting each walk at a declared root's absPath, never a bare ctx.cwd.
+        if (isEscapingPattern(pattern)) {
             return {
                 ok: false,
                 error: "pattern must be relative to the project root (no '..' or absolute paths)",
             };
         }
+        const ws = contextWorkspace(ctx);
+        let roots;
+        try {
+            roots = resolveReadRoots(ctx, { root: input.root });
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
         try {
-            const matches = await glob(pattern, {
-                cwd: path.resolve(ctx.cwd),
-                ignore: DEFAULT_IGNORE,
-                onlyFiles: true,
-                dot: false,
-            });
-            matches.sort();
-            if (matches.length === 0) {
+            // Fan: one independent walk per root; each match is attributed to (and, in
+            // multi-root, labelled with) the root whose absPath produced it.
+            const rows = [];
+            const totalByRoot = new Map();
+            for (const root of roots) {
+                const matches = await glob(pattern, {
+                    cwd: root.absPath,
+                    ignore: DEFAULT_IGNORE,
+                    onlyFiles: true,
+                    dot: false,
+                });
+                matches.sort();
+                totalByRoot.set(root.name, matches.length);
+                for (const m of matches) {
+                    rows.push({
+                        root: root.name,
+                        line: labelPath(root, m, ws.isMultiRoot),
+                    });
+                }
+            }
+            if (rows.length === 0) {
                 return { ok: true, output: "(no matches)" };
             }
-            if (matches.length > MAX_RESULTS) {
-                const shown = matches.slice(0, MAX_RESULTS).join("\n");
-                return {
-                    ok: true,
-                    output: `${shown}\n\n[truncated: showing ${MAX_RESULTS} of ${matches.length} matches]`,
-                };
+            if (rows.length > MAX_RESULTS) {
+                const shownRows = rows.slice(0, MAX_RESULTS);
+                const shown = shownRows.map((r) => r.line).join("\n");
+                const footer = ws.isMultiRoot
+                    ? truncationFooter(rows.length, shownRows, totalByRoot)
+                    : `[truncated: showing ${MAX_RESULTS} of ${rows.length} matches]`;
+                return { ok: true, output: `${shown}\n\n${footer}` };
             }
-            return { ok: true, output: matches.join("\n") };
+            return { ok: true, output: rows.map((r) => r.line).join("\n") };
         }
         catch (err) {
             return { ok: false, error: err.message };
         }
     },
 };
+/**
+ * Truncation footer for a fanned walk: the overall count plus a per-root note for
+ * every root whose matches the cap dropped — so a root cut off by the cap is
+ * named, never silently read as having no files.
+ */
+function truncationFooter(total, shownRows, totalByRoot) {
+    const shownByRoot = new Map();
+    for (const r of shownRows) {
+        shownByRoot.set(r.root, (shownByRoot.get(r.root) ?? 0) + 1);
+    }
+    const lines = [`[truncated: showing ${MAX_RESULTS} of ${total} matches]`];
+    for (const [name, count] of totalByRoot) {
+        const dropped = count - (shownByRoot.get(name) ?? 0);
+        if (dropped > 0) {
+            lines.push(`— ${name}: ${dropped} more not shown`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/tools/file/grep-files.d.ts

@@ -6,27 +6,37 @@ declare const parameters: z.ZodObject<{
     glob: z.ZodOptional<z.ZodString>;
     ignoreCase: z.ZodOptional<z.ZodBoolean>;
     maxResults: z.ZodOptional<z.ZodNumber>;
+    root: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     pattern: string;
     path?: string | undefined;
+    root?: string | undefined;
     maxResults?: number | undefined;
     glob?: string | undefined;
     ignoreCase?: boolean | undefined;
 }, {
     pattern: string;
     path?: string | undefined;
+    root?: string | undefined;
     maxResults?: number | undefined;
     glob?: string | undefined;
     ignoreCase?: boolean | undefined;
 }>;
 /**
- * Search file *contents* for a regex within the project root. Read-only — no
+ * Search file *contents* for a regex within the workspace. Read-only — no
  * approval — so the model should prefer this over shelling out to grep/rg via
  * run_command (which is platform-dependent and routes through the approval gate).
  *
  * Files are enumerated with the same glob mechanism as the `glob` tool (so
  * node_modules and .git are always ignored), binary files are skipped, and the
- * search is bounded by the project-root path boundary shared by every file tool.
+ * search is bounded by the same root boundary as every file tool.
+ *
+ * Multi-repo (C.26, Funnel B): with more than one declared root and no root-
+ * selecting argument, the search FANS every root — a bare relative `path` is
+ * applied under each root (⚖︎JC-6) — and labels each match `‹root› ▸ path`. A
+ * `root` argument, or an absolute / `‹root›/…`-prefixed `path`, scopes it to that
+ * one root. Each walk starts at exactly one confined root directory, so a match
+ * can only come from the root its label names.
  */
 export declare const grepFilesTool: Tool<typeof parameters>;
 export {};