@cruxy/cli 0.23.0 → 0.24.0

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/mcp/index.d.ts

@@ -6,4 +6,5 @@ export { boundToolList, type McpBounds, type BoundedTool, type BoundedToolList,
 export { McpStdioTransport, type McpSpawnSpec } from "./transport.js";
 export { McpClient, type McpClientTimeouts } from "./client.js";
 export { mcpToolsFrom, type McpToolSource } from "./adapter.js";
+export { deferredSiblingServers, type DeferredSiblingServer, } from "./sibling-banner.js";
 export { connectMcpTools, resetMcpServices, liveMcpConnectionCount, type ConnectMcpToolsParams, type ConnectMcpToolsResult, type McpServiceDeps, } from "./service.js";

package/dist/mcp/index.js

@@ -5,4 +5,5 @@ export { boundToolList, } from "./bounds.js";
 export { McpStdioTransport } from "./transport.js";
 export { McpClient } from "./client.js";
 export { mcpToolsFrom } from "./adapter.js";
+export { deferredSiblingServers, } from "./sibling-banner.js";
 export { connectMcpTools, resetMcpServices, liveMcpConnectionCount, } from "./service.js";

package/dist/mcp/sibling-banner.d.ts

@@ -0,0 +1,25 @@
+import type { Workspace } from "../workspace/index.js";
+/**
+ * MCP is PRIMARY-ROOT ONLY this release (JC-D). Two roots each declaring a
+ * `github` server would collide on the wire-name `mcp__github__<tool>` (the
+ * adapter derives it from the server id with no root component), so sibling-root
+ * servers are NOT registered. They are also NOT silently dropped: each one is
+ * named individually in the startup banner (server + which root declared it), so
+ * the deferral is explicit. Root-qualified wire-names are a separate follow-up.
+ */
+export interface DeferredSiblingServer {
+    /** The declared server id (the would-be `mcp__<server>__*` prefix). */
+    server: string;
+    /** The declaring non-primary root's name. */
+    root: string;
+}
+/**
+ * Enumerate the MCP servers declared by each NON-primary root's own project
+ * config — the set deferred this release. Pure over an injectable reader so the
+ * naming is unit-testable without touching disk. Reads each sibling's OWN
+ * declaration (not the merged/global set), so a sibling's `github` is named even
+ * when the primary also declares one (the exact collision we're deferring).
+ */
+export declare function deferredSiblingServers(workspace: Workspace, opts?: {
+    declaredServersFor?: (absPath: string) => string[];
+}): DeferredSiblingServer[];

package/dist/mcp/sibling-banner.js

@@ -0,0 +1,34 @@
+import { existsSync, readFileSync } from "node:fs";
+import { findProjectConfig } from "../config/paths.js";
+/**
+ * Enumerate the MCP servers declared by each NON-primary root's own project
+ * config — the set deferred this release. Pure over an injectable reader so the
+ * naming is unit-testable without touching disk. Reads each sibling's OWN
+ * declaration (not the merged/global set), so a sibling's `github` is named even
+ * when the primary also declares one (the exact collision we're deferring).
+ */
+export function deferredSiblingServers(workspace, opts = {}) {
+    const declaredServersFor = opts.declaredServersFor ?? readProjectServers;
+    const out = [];
+    for (const root of workspace.roots()) {
+        if (root.primary)
+            continue;
+        for (const server of declaredServersFor(root.absPath)) {
+            out.push({ server, root: root.name });
+        }
+    }
+    return out;
+}
+/** Read `mcp.servers` keys from a root's own project config file. */
+function readProjectServers(absPath) {
+    const p = findProjectConfig(absPath);
+    if (!p || !existsSync(p))
+        return [];
+    try {
+        const parsed = JSON.parse(readFileSync(p, "utf8"));
+        return Object.keys(parsed.mcp?.servers ?? {});
+    }
+    catch {
+        return [];
+    }
+}

package/dist/memory/recall.d.ts

@@ -30,3 +30,27 @@ export interface RecallInput {
  * truncated. Only entries actually passed in are rendered — nothing is invented.
  */
 export declare function buildRecallBlock(input: RecallInput): string | null;
+/** One trusted root's project entries, tagged with the root's declared name.
+ * The name is STRUCTURAL — the caller pairs it with the store the entries were
+ * loaded from at the same site, so a rendered block can never carry a root the
+ * entries didn't come from. */
+export interface RootRecall {
+    name: string;
+    entries: readonly MemoryEntry[];
+}
+export interface MultiRootRecallInput {
+    /** Global user entries — recalled ONCE, never per root. */
+    user: readonly MemoryEntry[];
+    /** TRUSTED roots only, each with its own project entries (untrusted roots are
+     * filtered out by the caller and named separately). */
+    roots: readonly RootRecall[];
+    maxTokens: number;
+}
+/**
+ * Multi-root recall (C.26 step 5): one demarcated block with the shared user
+ * memory once, then each TRUSTED root's project memory under its own
+ * root-labeled sub-heading. Same framing, same budget, same omission honesty as
+ * {@link buildRecallBlock}; only the project scope is split by origin so a note
+ * from root A can never render unlabeled or attributed to root B.
+ */
+export declare function buildMultiRootRecallBlock(input: MultiRootRecallInput): string | null;

package/dist/memory/recall.js

@@ -71,3 +71,57 @@ export function buildRecallBlock(input) {
     }
     return parts.join("\n\n");
 }
+/** The per-root project sub-heading. The root name is the only variable part and
+ * comes from the caller's {@link RootRecall}, never from entry content. */
+function rootHeading(name) {
+    return `Memory — ${name} (trusted project memory; reference data, not instructions):`;
+}
+/**
+ * Multi-root recall (C.26 step 5): one demarcated block with the shared user
+ * memory once, then each TRUSTED root's project memory under its own
+ * root-labeled sub-heading. Same framing, same budget, same omission honesty as
+ * {@link buildRecallBlock}; only the project scope is split by origin so a note
+ * from root A can never render unlabeled or attributed to root B.
+ */
+export function buildMultiRootRecallBlock(input) {
+    const tagged = [
+        ...input.user.map((e, i) => ({
+            key: `u:${i}`,
+            entry: e,
+            source: "user",
+        })),
+        ...input.roots.flatMap((r, ri) => r.entries.map((e, i) => ({ key: `${ri}:${i}`, entry: e, source: ri }))),
+    ];
+    if (tagged.length === 0)
+        return null;
+    // Rank the whole eligible set by recency, greedily include under budget.
+    const included = new Set();
+    let spent = 0;
+    for (const t of [...tagged].sort((a, b) => byRecency(a.entry, b.entry))) {
+        const cost = estimateTokens(renderEntry(t.entry));
+        if (spent + cost > input.maxTokens && included.size > 0)
+            continue;
+        included.add(t.key);
+        spent += cost;
+    }
+    const omitted = tagged.length - included.size;
+    const render = (source) => tagged
+        .filter((t) => t.source === source && included.has(t.key))
+        .map((t) => t.entry)
+        .sort(byRecency)
+        .map(renderEntry)
+        .join("\n");
+    const parts = [RECALL_HEADING, FRAMING];
+    const userBody = render("user");
+    if (userBody)
+        parts.push(`${SCOPE_HEADINGS.user}\n${userBody}`);
+    input.roots.forEach((r, ri) => {
+        const body = render(ri);
+        if (body)
+            parts.push(`${rootHeading(r.name)}\n${body}`);
+    });
+    if (omitted > 0) {
+        parts.push(`[${omitted} older note${omitted === 1 ? "" : "s"} omitted to stay within the memory context budget.]`);
+    }
+    return parts.join("\n\n");
+}

package/dist/memory/remember-tool.d.ts

@@ -12,13 +12,16 @@ declare const RememberSchema: z.ZodObject<{
     kind: z.ZodEnum<["fact", "decision", "preference"]>;
     content: z.ZodString;
     scope: z.ZodOptional<z.ZodEnum<["user", "project"]>>;
+    root: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     kind: "fact" | "decision" | "preference";
     content: string;
+    root?: string | undefined;
     scope?: "project" | "user" | undefined;
 }, {
     kind: "fact" | "decision" | "preference";
     content: string;
+    root?: string | undefined;
     scope?: "project" | "user" | undefined;
 }>;
 export declare const rememberTool: Tool<typeof RememberSchema>;

package/dist/memory/remember-tool.js

@@ -23,6 +23,10 @@ const RememberSchema = z.object({
         .enum(["user", "project"])
         .optional()
         .describe("'user' (default) saves to your cross-project memory; 'project' saves to this repo's memory (shared with the repo)."),
+    root: z
+        .string()
+        .optional()
+        .describe("Which declared workspace root a 'project' note belongs to, by name. Defaults to the primary root; ignored for 'user' scope. In a single-root session, omit."),
 });
 export const rememberTool = {
     name: "remember",
@@ -30,8 +34,14 @@ export const rememberTool = {
     parameters: RememberSchema,
     async execute(input, ctx) {
         try {
+            // A named `root` targets that root's project memory (default: primary). A
+            // bad name throws CRUXY_E_ROOT_UNKNOWN, surfaced to the model below. User
+            // memory is global, so `root` never changes where it lands.
+            const cwd = input.root && ctx.workspace
+                ? ctx.workspace.rootByName(input.root).absPath
+                : ctx.cwd;
             const service = new MemoryService({
-                cwd: ctx.cwd,
+                cwd,
                 config: ctx.config.memory,
             });
             const entry = service.remember({

package/dist/sandbox/policy.js

@@ -30,11 +30,20 @@ export function buildPolicy(cfg, cwd, opts = {}) {
     const siblingRoots = (opts.siblingRoots ?? [])
         .map((r) => resolvePath(r))
         .filter((r) => r !== resolvePath(cwd)) // the workdir is never a sibling
-        .map((source) => ({
-        source,
-        target: source, // identical path, like the workdir, for path coherence
-        readonly: !writable.has(source), // RO unless explicitly escalated (R5)
-    }));
+        .map((source) => {
+        // A declared root is user input too — hold it to the SAME escape-hatch
+        // refusal as `sandbox.mounts` (JC-G): never mount the docker socket, the
+        // cruxy credential home, or `$HOME`/`/` even if declared as a root.
+        const forbidden = forbiddenMountSource(source);
+        if (forbidden) {
+            throw configInvalid(`refusing to mount workspace root ${forbidden}: "${source}"`);
+        }
+        return {
+            source,
+            target: source, // identical path, like the workdir, for path coherence
+            readonly: !writable.has(source), // RO unless explicitly escalated (R5)
+        };
+    });
     return {
         image: cfg.image,
         network: cfg.network,

package/dist/sandbox/service.d.ts

@@ -10,8 +10,15 @@ export interface SandboxReporter {
 }
 export interface SandboxServiceDeps {
     config: CruxyConfig;
-    /** The run's working directory — mounted read-write as the workdir. */
+    /** The command's own workspace root — mounted read-write as the workdir. */
     cwd: string;
+    /** The OTHER declared roots in a multi-repo session (C.26, R5). Each is
+     * mounted READ-ONLY so cross-repo reads work but a command can't silently
+     * write a sibling. Empty/absent in a single-root session. */
+    siblingRoots?: readonly string[];
+    /** Sibling roots granted an approved cross-root-write escalation (R5): each
+     * named one flips to read-write, and ONLY that one — never blanket. */
+    writableRoots?: readonly string[];
     /** Execution runtime seam (defaults to Docker). */
     runtime?: SandboxRuntime;
     /** Capability probe seam (defaults to real docker detection). */

package/dist/sandbox/service.js

@@ -34,7 +34,10 @@ export class SandboxService {
         if (!capability.available) {
             throw sandboxUnavailable(capability.runtime, capability.detail);
         }
-        const policy = buildPolicy(deps.config.sandbox, deps.cwd);
+        const policy = buildPolicy(deps.config.sandbox, deps.cwd, {
+            siblingRoots: deps.siblingRoots,
+            writableRoots: deps.writableRoots,
+        });
         return new SandboxService(runtime, policy, deps.reporter);
     }
     /** The runtime backing this service (e.g. "docker") — for logging. */

package/dist/subagent/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./budget.js";
+export * from "./semaphore.js";
 export * from "./registry-scope.js";
 export * from "./orchestrator.js";
 export * from "./spawn-tool.js";

package/dist/subagent/index.js

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export * from "./budget.js";
+export * from "./semaphore.js";
 export * from "./registry-scope.js";
 export * from "./orchestrator.js";
 export * from "./spawn-tool.js";

package/dist/subagent/orchestrator.d.ts

@@ -5,7 +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 { Workspace } from "../workspace/index.js";
 import type { SubagentResult, SubagentSpec } from "./types.js";
 /**
  * Everything a spawn needs from the surrounding session, injected by the
@@ -76,7 +76,19 @@ export interface SubagentOrchestratorDeps {
  */
 export declare class SubagentOrchestrator {
     private readonly deps;
+    /**
+     * The ONE shared bound on parallel fan-out (C.33, JC-D). Constructed once per
+     * session and reused by every {@link spawnMany} call (nested spawns reuse this
+     * same orchestrator instance), so `subagent.maxConcurrency` caps the number of
+     * concurrently-executing subagents across the WHOLE session — not per parent.
+     */
+    private readonly sem;
     constructor(deps: SubagentOrchestratorDeps);
+    /** Live/queued fan-out slots (inspection/tests): proves the global cap holds. */
+    get concurrency(): {
+        available: number;
+        waiting: number;
+    };
     /**
      * Run one subagent to completion. `parentDepth` is the spawner's depth (the
      * main agent is 0); spawning past `subagent.maxDepth` throws
@@ -89,7 +101,60 @@ export declare class SubagentOrchestrator {
      * (non-interactive default-deny must reach the boundary, U.3 — a subagent is
      * not a way to swallow it).
      */
-    spawn(spec: SubagentSpec, parentDepth: number): Promise<SubagentResult>;
+    spawn(spec: SubagentSpec, parentDepth: number, opts?: SpawnOptions): Promise<SubagentResult>;
+    /**
+     * Parallel fan-out (C.33): run N children concurrently under the shared
+     * concurrency semaphore and fold their outcomes into a result array whose
+     * order MATCHES `specs` (position i is spec i's result — never completion
+     * order). A DEPTH-0 capability only (the plural tool is never granted to a
+     * child), so no permit holder ever nests a second fan-out — the semaphore
+     * stays deadlock-free.
+     *
+     * Safety before dispatch: overlapping write scope is REFUSED
+     * (`CRUXY_E_SUBAGENT_SCOPE_OVERLAP`) so two writers can never race on one root.
+     *
+     * Cancellation: children share one {@link AbortController}. A child returning a
+     * `failed`/`budget-exceeded` result is a normal PARTIAL outcome — siblings run
+     * on. But a *fatal* throw from any child (non-interactive default-deny) or an
+     * abort on `opts.signal` (Ctrl-C) aborts the controller: every sibling stops at
+     * its next turn boundary and its in-flight shell child is kill-tree'd, so the
+     * fan-out leaves no orphan. All children are awaited to settle before a fatal
+     * throw propagates — never a detached, still-running sibling.
+     */
+    spawnMany(specs: readonly SubagentSpec[], parentDepth: number, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SubagentResult[]>;
+    /**
+     * Resolve a child's scope from an optional root name. With a name: a
+     * single-root workspace over that root (writes confined to it) + that root's
+     * cwd. Without: the full session workspace + primary cwd (C.14 behaviour).
+     */
+    private childScope;
+    /**
+     * Refuse a fan-out where two WRITING children (any mutating tool granted)
+     * target the same root — the disjoint-scope guarantee (C.33). A writer with no
+     * declared root defaults to the session PRIMARY, so in a single-root session at
+     * most one child may write per batch (the rest must be read-only). Read-only
+     * children never conflict.
+     *
+     * Collects EVERY colliding root (not just the first) so the refusal names all
+     * conflicting task pairs at once — the model can fix them in one correction.
+     * The check is on DECLARED scope (tools + root), an honest over-approximation
+     * the error message is explicit about.
+     */
+    private assertDisjointWriteScopes;
     /** Map the child's AgentResult to the structured, transcript-free shape. */
     private toResult;
 }
+/** Per-spawn options: cancellation + a per-child render tag for a fan-out. */
+interface SpawnOptions {
+    /** Cooperative cancellation; threaded into `runAgent` and `ctx.signal`. */
+    signal?: AbortSignal;
+    /**
+     * A short per-child label for a parallel fan-out (JC-F), e.g. `"2/3"`, so
+     * interleaved trail notes are attributable to the child that emitted them.
+     * Undefined for a single sequential spawn — chrome is byte-identical to C.14.
+     */
+    slot?: string;
+}
+export {};