@cruxy/cli 0.22.1 → 0.24.0

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,
@@ -678,6 +737,44 @@ export function subagentDepthExceeded(depth, maxDepth) {
         meta: { depth, maxDepth },
     });
 }
+/**
+ * A parallel fan-out (C.33) declared children with overlapping write scope — two
+ * or more target the SAME workspace root while both hold mutating tools. The
+ * ENTIRE batch is refused BEFORE any child is dispatched, so concurrent siblings
+ * can never race on one root's files or checkpoint. Every colliding group is
+ * named (the conflicting task pairs, per root) so the model can fix all of them
+ * at once. Surfaced as a tool error to correct (assign distinct roots, or drop
+ * write tools on all but one child per root).
+ *
+ * THE HONEST LIMIT, stated in the message: the check is on DECLARED scope — the
+ * tools + root each child was granted — NOT the files actually written. Two
+ * children could still touch disjoint paths under one root; cruxy refuses anyway
+ * rather than let two potential writers race on that root's single checkpoint.
+ */
+export function subagentScopeOverlap(conflicts) {
+    const list = conflicts
+        .map((c) => `root "${c.root}" ← ${c.tasks.map((t) => `“${t}”`).join(", ")}`)
+        .join("; ");
+    return new CruxyError({
+        code: ErrorCode.SubagentScopeOverlap,
+        title: conflicts.length === 1
+            ? `parallel subagents overlap on root "${conflicts[0].root}"`
+            : `parallel subagents overlap on ${conflicts.length} roots`,
+        cause: `these children of one spawn_subagents call declared write scope on the ` +
+            `same root — ${list}. The check is on DECLARED scope (the tools and root ` +
+            `each child was granted), NOT the files actually written — two children ` +
+            `could still touch disjoint paths — but cruxy refuses the whole batch ` +
+            `rather than let two writers race on one root's checkpoint.`,
+        nextSteps: [
+            "give each writing child a distinct `root` (parallel writes require disjoint roots)",
+            "or grant write/shell tools to only one child per root and keep the rest read-only",
+            "or run the conflicting subtasks sequentially with spawn_subagent",
+        ],
+        meta: {
+            conflicts: conflicts.map((c) => ({ root: c.root, tasks: [...c.tasks] })),
+        },
+    });
+}
 /**
  * A subagent run failed outright (provider error, tool crash) before producing
  * a result. Normally folded into the structured `SubagentResult` the parent

package/dist/errors/types.d.ts

@@ -52,6 +52,14 @@ export declare const ErrorCode: {
     /** Carried inside a SubagentResult (informational) — never fatal by itself. */
     readonly SubagentBudget: "CRUXY_E_SUBAGENT_BUDGET";
     readonly SubagentFailed: "CRUXY_E_SUBAGENT_FAILED";
+    /** Two children of one parallel fan-out (C.33) declare overlapping write scope
+     * (same root). Refused pre-dispatch so concurrent siblings can never race on a
+     * root — the model corrects it (distinct roots, or read-only). */
+    readonly SubagentScopeOverlap: "CRUXY_E_SUBAGENT_SCOPE_OVERLAP";
+    /** Carried inside a SubagentResult (informational): the run was cancelled — a
+     * fatal sibling failure or Ctrl-C aborted the whole fan-out (C.33). Never a
+     * fabricated success; the parent sees exactly which children did not finish. */
+    readonly SubagentCancelled: "CRUXY_E_SUBAGENT_CANCELLED";
     readonly TestCommandNotFound: "CRUXY_E_TEST_COMMAND_NOT_FOUND";
     /** Carried inside a run_tests result (informational) — never fatal by itself. */
     readonly TestIterationLimit: "CRUXY_E_TEST_ITERATION_LIMIT";
@@ -137,6 +145,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 +159,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

@@ -63,6 +63,14 @@ export const ErrorCode = {
     /** Carried inside a SubagentResult (informational) — never fatal by itself. */
     SubagentBudget: "CRUXY_E_SUBAGENT_BUDGET",
     SubagentFailed: "CRUXY_E_SUBAGENT_FAILED",
+    /** Two children of one parallel fan-out (C.33) declare overlapping write scope
+     * (same root). Refused pre-dispatch so concurrent siblings can never race on a
+     * root — the model corrects it (distinct roots, or read-only). */
+    SubagentScopeOverlap: "CRUXY_E_SUBAGENT_SCOPE_OVERLAP",
+    /** Carried inside a SubagentResult (informational): the run was cancelled — a
+     * fatal sibling failure or Ctrl-C aborted the whole fan-out (C.33). Never a
+     * fabricated success; the parent sees exactly which children did not finish. */
+    SubagentCancelled: "CRUXY_E_SUBAGENT_CANCELLED",
     // testing (exit 2 / 11)
     TestCommandNotFound: "CRUXY_E_TEST_COMMAND_NOT_FOUND",
     /** Carried inside a run_tests result (informational) — never fatal by itself. */
@@ -157,6 +165,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 +179,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
@@ -210,6 +238,10 @@ const EXIT_CODES = {
     [ErrorCode.SubagentDepthExceeded]: 2,
     [ErrorCode.SubagentBudget]: 11,
     [ErrorCode.SubagentFailed]: 11,
+    // Overlapping fan-out scope is a spawn misuse (usage, model-correctable);
+    // cancellation surfaces inside a SubagentResult and is never fatal by itself.
+    [ErrorCode.SubagentScopeOverlap]: 2,
+    [ErrorCode.SubagentCancelled]: 11,
     // No test command is a configuration gap (usage); the iteration limit
     // surfaces inside a run_tests result and is never fatal by itself.
     [ErrorCode.TestCommandNotFound]: 2,
@@ -264,8 +296,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/hooks/index.d.ts

@@ -4,3 +4,4 @@ export { fileTrustStore, fingerprintHooks, isTrusted, memoryTrustStore, trustPat
 export { HookRunner, type HookRunnerDeps, type TrustPromptInfo, } from "./runner.js";
 export { BUILTIN_SLASH_COMMANDS, expandTemplate, isBuiltinSlash, resolveSlash, type SlashResolution, } from "./slash.js";
 export { buildHooksService, type BuildHooksServiceOptions, type HooksService, } from "./service.js";
+export { buildHooksRouter, type BuildHooksRouterOptions, type HooksRouterResult, type UntrustedHookRoot, } from "./router.js";

package/dist/hooks/index.js

@@ -4,3 +4,4 @@ export { fileTrustStore, fingerprintHooks, isTrusted, memoryTrustStore, trustPat
 export { HookRunner, } from "./runner.js";
 export { BUILTIN_SLASH_COMMANDS, expandTemplate, isBuiltinSlash, resolveSlash, } from "./slash.js";
 export { buildHooksService, } from "./service.js";
+export { buildHooksRouter, } from "./router.js";

package/dist/hooks/router.d.ts

@@ -0,0 +1,58 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { LifecycleHookRunner } from "../agent/loop.js";
+import type { logger as Logger } from "../utils/logger.js";
+import type { DeclaredRoot, Workspace } from "../workspace/index.js";
+import { type TrustStore } from "./trust.js";
+import type { HookCatalog, SlashCommandSpec } from "./types.js";
+/**
+ * Per-root hook dispatch for a multi-root session (C.26 step 5).
+ *
+ * The isolation here is a PROPERTY OF CONSTRUCTION, not a guard: each root gets
+ * its OWN {@link HookRunner} (own project-hook catalog, own trust key), so there
+ * is no code path from root A's runner to a root-B action. The router only
+ * decides WHICH runner to invoke:
+ *
+ *   - Tool-scoped events (`before-tool` / `after-tool` / `on-file-change`) fire
+ *     exactly the ONE acting root's runner — the same root the tool resolved via
+ *     {@link selectRoot}. A's project hooks structurally cannot fire for a
+ *     B-scoped call (⚖︎10, pinned by test).
+ *   - Session lifecycle events (`before-run` / `after-run`) have NO acting root,
+ *     so they fan EVERY trusted root sequentially, in declaration order,
+ *     root-labeled; a blocking failure in any root aborts the run naming that
+ *     root (JC-1). Untrusted roots are skipped and named in the startup banner —
+ *     never silent (a user's pre-run guard in an untrusted root must not vanish
+ *     without a word).
+ *
+ * User-scope hooks (`~/.cruxy`) are session-global — authored by you, shared by
+ * every root — so they fire EXACTLY ONCE per event through a single shared
+ * runner, never once per root.
+ */
+/** A root whose project hooks exist but are not trusted → named in the banner. */
+export interface UntrustedHookRoot {
+    name: string;
+    absPath: string;
+    count: number;
+}
+export interface HooksRouterResult {
+    /** The lifecycle firing seam (a {@link LifecycleHookRunner}). */
+    runner: LifecycleHookRunner;
+    /** Custom slash commands (primary root only this release). */
+    commands: SlashCommandSpec[];
+    /** Roots with untrusted project hooks — named in the banner, never silent. */
+    untrustedHookRoots: UntrustedHookRoot[];
+}
+export interface BuildHooksRouterOptions {
+    workspace: Workspace;
+    config: CruxyConfig;
+    logger: typeof Logger;
+    trust?: TrustStore;
+    /** Per-root catalog loader; defaults to the layered on-disk loader. */
+    loadCatalog?: (root: DeclaredRoot) => Promise<HookCatalog>;
+    now?: () => string;
+}
+/**
+ * Build the multi-root hook router. One project-hook runner per declared root
+ * (trust-gated against that root's key) plus one shared user-hook runner. Load
+ * errors are surfaced through the logger exactly as the single-root path does.
+ */
+export declare function buildHooksRouter(opts: BuildHooksRouterOptions): Promise<HooksRouterResult>;

package/dist/hooks/router.js

@@ -0,0 +1,136 @@
+import { selectRoot } from "../workspace/index.js";
+import { defaultHookSources, loadHookCatalog } from "./config.js";
+import { HookRunner } from "./runner.js";
+import { fileTrustStore } from "./trust.js";
+const LIFECYCLE_EVENTS = new Set(["before-run", "after-run"]);
+/**
+ * Resolve the ONE acting root for a tool-scoped event from the raw tool-call
+ * input, reusing the exact {@link selectRoot} precedence the tool itself uses so
+ * the hook's root always matches the tool's root. Bare/ambiguous/unknown → the
+ * primary (a hook never crosses into a root the call didn't address).
+ */
+function resolveActingRoot(ws, input) {
+    if (input && typeof input === "object") {
+        const rec = input;
+        const root = typeof rec.root === "string" ? rec.root : undefined;
+        const p = typeof rec.path === "string" ? rec.path : undefined;
+        if (root !== undefined || p !== undefined) {
+            try {
+                return selectRoot(ws, { root, path: p ?? "." }).root;
+            }
+            catch {
+                // Unknown root name / not-contained absolute path → fall to primary.
+            }
+        }
+    }
+    return ws.primary();
+}
+class HookRouter {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async fire(event, ctx, hint) {
+        if (!this.deps.enabled)
+            return;
+        if (LIFECYCLE_EVENTS.has(event)) {
+            // Session lifecycle: user hooks once, then every TRUSTED root in order.
+            await this.deps.userRunner.fire(event, ctx);
+            for (const root of this.deps.workspace.roots()) {
+                const runner = this.deps.perRoot.get(root.absPath);
+                if (!runner || !runner.projectTrusted)
+                    continue; // skipped; banner-named
+                // A blocking failure throws `hookFailed("<root> ▸ <hook>", …)` — the run
+                // aborts naming which root refused (the runner carries `label`).
+                await runner.fire(event, rootCtx(ctx, root));
+            }
+            return;
+        }
+        // Tool-scoped: exactly the ONE acting root (+ the shared user hooks).
+        const acting = resolveActingRoot(this.deps.workspace, hint?.input);
+        const actingCtx = rootCtx(ctx, acting);
+        await this.deps.userRunner.fire(event, actingCtx);
+        const runner = this.deps.perRoot.get(acting.absPath);
+        if (runner && runner.projectTrusted) {
+            await runner.fire(event, actingCtx);
+        }
+    }
+}
+/** A per-root view of the tool context: the hook command runs in THAT root's
+ * directory (`runGatedShell` uses `ctx.cwd`), so a root's hook always executes
+ * against its own tree — never the primary's. */
+function rootCtx(ctx, root) {
+    return { ...ctx, cwd: root.absPath };
+}
+/**
+ * Build the multi-root hook router. One project-hook runner per declared root
+ * (trust-gated against that root's key) plus one shared user-hook runner. Load
+ * errors are surfaced through the logger exactly as the single-root path does.
+ */
+export async function buildHooksRouter(opts) {
+    const trust = opts.trust ?? fileTrustStore();
+    const enabled = opts.config.hooks.enabled;
+    const perRoot = new Map();
+    const untrustedHookRoots = [];
+    let userHooks = [];
+    let primaryCommands = [];
+    const loadCatalog = opts.loadCatalog ??
+        ((root) => loadHookCatalog(defaultHookSources(root.absPath)));
+    for (const root of opts.workspace.roots()) {
+        const catalog = await loadCatalog(root);
+        for (const err of catalog.errors) {
+            opts.logger.warn(`ignoring malformed ${err.source} hook/command "${err.name}" in ${root.name}: ${err.message}`);
+        }
+        // Each root's runner owns ONLY its project hooks. User hooks are global —
+        // loaded once (from the primary, whose `sources.user` is identical for every
+        // root) and fired through the shared runner, never per-root.
+        const projectHooks = catalog.hooks.filter((h) => h.source === "project");
+        if (root.primary) {
+            userHooks = catalog.hooks.filter((h) => h.source === "user");
+            primaryCommands = catalog.commands;
+        }
+        const runner = new HookRunner({
+            hooks: projectHooks,
+            trust,
+            enabled,
+            // Multi-root never lazy-prompts (a barrage of per-sibling prompts mid-run
+            // is worse than a named skip). Untrusted roots are skipped + banner-named;
+            // `cruxy hooks trust <path>` is the deliberate opt-in.
+            trustPrompt: false,
+            interactive: false,
+            cwd: root.absPath,
+            label: root.name,
+            announce: (m) => opts.logger.info(`[${root.name}] ${m}`),
+            reportFailure: (m) => opts.logger.warn(`[${root.name}] ${m}`),
+            now: opts.now,
+        });
+        perRoot.set(root.absPath, runner);
+        if (!runner.projectTrusted) {
+            untrustedHookRoots.push({
+                name: root.name,
+                absPath: root.absPath,
+                count: runner.projectHookCount,
+            });
+        }
+    }
+    // Shared user-hook runner: user hooks carry no project source, so its trust
+    // gate never triggers (you authored them) — it just fires them once.
+    const userRunner = new HookRunner({
+        hooks: userHooks,
+        trust,
+        enabled,
+        trustPrompt: false,
+        interactive: false,
+        cwd: opts.workspace.primary().absPath,
+        announce: (m) => opts.logger.info(m),
+        reportFailure: (m) => opts.logger.warn(m),
+        now: opts.now,
+    });
+    const runner = new HookRouter({
+        workspace: opts.workspace,
+        perRoot,
+        userRunner,
+        enabled,
+    });
+    return { runner, commands: primaryCommands, untrustedHookRoots };
+}

package/dist/hooks/runner.d.ts

@@ -36,6 +36,10 @@ export interface HookRunnerDeps {
     interactive: boolean;
     /** Project root — the trust key and fingerprint scope. */
     cwd: string;
+    /** Root label for multi-root fan-out (C.26 step 5). When set, a blocking
+     * failure names its root (`<label> ▸ <hook>`) so an aborted run says which
+     * root refused. Undefined in the single-root path → messages unchanged. */
+    label?: string;
     /** Interactive trust prompt (returns true to trust). Required only when a
      * project defines hooks and `trustPrompt` + `interactive` are both on. */
     promptTrust?: (info: TrustPromptInfo) => Promise<boolean>;
@@ -51,6 +55,14 @@ export declare class HookRunner {
     constructor(deps: HookRunnerDeps);
     /** The project hooks — the trust-gated subset. */
     private get projectHooks();
+    /** Prefix a hook name with the root label (multi-root), else leave it. */
+    private qualify;
+    /** Whether this root's project hooks are trusted for their current
+     * fingerprint. Read-only (never prompts/records) — the router uses it to skip
+     * untrusted roots and to name them in the banner. */
+    get projectTrusted(): boolean;
+    /** Count of project (trust-gated) hooks — for the untrusted-root banner. */
+    get projectHookCount(): number;
     /**
      * Fire every hook registered for `event`, in catalog order. Resolves normally
      * when all hooks pass (or advisory ones fail); THROWS `CRUXY_E_HOOK_FAILED`

package/dist/hooks/runner.js

@@ -10,12 +10,33 @@ export class HookRunner {
     get projectHooks() {
         return this.deps.hooks.filter((h) => h.source === "project");
     }
+    /** Prefix a hook name with the root label (multi-root), else leave it. */
+    qualify(name) {
+        return this.deps.label ? `${this.deps.label} ▸ ${name}` : name;
+    }
+    /** Whether this root's project hooks are trusted for their current
+     * fingerprint. Read-only (never prompts/records) — the router uses it to skip
+     * untrusted roots and to name them in the banner. */
+    get projectTrusted() {
+        const projectHooks = this.projectHooks;
+        if (projectHooks.length === 0)
+            return true;
+        return isTrusted(this.deps.trust, this.deps.cwd, fingerprintHooks(projectHooks));
+    }
+    /** Count of project (trust-gated) hooks — for the untrusted-root banner. */
+    get projectHookCount() {
+        return this.projectHooks.length;
+    }
     /**
      * Fire every hook registered for `event`, in catalog order. Resolves normally
      * when all hooks pass (or advisory ones fail); THROWS `CRUXY_E_HOOK_FAILED`
      * when a blocking hook fails, or `CRUXY_E_HOOK_UNTRUSTED` when a project's
      * hooks are not trusted. A no-op when hooks are disabled or none match.
      */
+    // The LifecycleHookRunner seam passes an optional acting-root hint as a 3rd
+    // arg; the single-root runner owns exactly one root and ignores it (a method
+    // with fewer params is still assignable to the interface), so single-root
+    // firing stays byte-identical.
     async fire(event, ctx) {
         if (!this.deps.enabled)
             return;
@@ -33,7 +54,8 @@ export class HookRunner {
                 continue;
             if (hook.blocking) {
                 // Fail-closed: stop, do not run the remaining hooks, abort the action.
-                throw hookFailed(hook.name, verdict.reason ?? "hook failed");
+                // `label` (multi-root) names the refusing root in the aborted-run error.
+                throw hookFailed(this.qualify(hook.name), verdict.reason ?? "hook failed");
             }
             // Advisory: the action already happened (or proceeds) — report, continue.
             this.deps.reportFailure?.(`hook "${hook.name}" failed (advisory): ${verdict.reason ?? "unknown"}`);

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;