@cruxy/cli 0.23.0 → 0.25.0

package/dist/errors/constructors.d.ts

@@ -190,12 +190,53 @@ export declare function checkpointSetPartial(runId: string, restored: string[],
  * orchestrator seam was driven directly — fail loud, never spawn.
  */
 export declare function subagentDepthExceeded(depth: number, maxDepth: number): CruxyError;
+/** One workspace root claimed by two-or-more WRITING children of a single
+ * `spawn_subagents` call — the unit of a disjoint-scope violation (C.33). */
+export interface ScopeConflict {
+    /** The root name both children declared write scope on. */
+    root: string;
+    /** The task labels of every writing child that claimed `root` (always ≥2). */
+    tasks: string[];
+}
+/**
+ * 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 declare function subagentScopeOverlap(conflicts: readonly ScopeConflict[]): CruxyError;
 /**
  * A subagent run failed outright (provider error, tool crash) before producing
  * a result. Normally folded into the structured `SubagentResult` the parent
  * reasons over; thrown only when the orchestrator itself cannot proceed.
  */
 export declare function subagentFailed(underlying?: unknown): CruxyError;
+/**
+ * A `run_in_background` dispatch was refused because the session already holds
+ * `jobs.maxJobs` live jobs (queued + running + paused). The MODEL corrects it, so
+ * this is a coded tool error, not a silent drop: wait for a job to finish (or
+ * cancel one) and retry, or run the work in the foreground.
+ */
+export declare function jobLimitExceeded(maxJobs: number, live: number): CruxyError;
+/**
+ * `cruxy cancel/logs/rollback <id>` named a job that does not exist in this
+ * session. Jobs are session-scoped (NOT a daemon), so an id from a prior session
+ * is legitimately gone — fail loud with the id rather than a silent no-op.
+ */
+export declare function jobNotFound(id: string): CruxyError;
+/**
+ * A background-jobs command was used while the feature is disabled. Surfaced with
+ * how to enable it rather than pretending there are simply no jobs.
+ */
+export declare function jobsDisabled(): CruxyError;
 /**
  * No test command could be detected and none is configured (C.13). cruxy never
  * invents a test command — the fix is always to declare one.

package/dist/errors/constructors.js

@@ -737,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
@@ -754,6 +792,55 @@ export function subagentFailed(underlying) {
         underlying,
     });
 }
+// ── background jobs (exit 2 / 19) — C.28 ──────────────────────────────────────
+/**
+ * A `run_in_background` dispatch was refused because the session already holds
+ * `jobs.maxJobs` live jobs (queued + running + paused). The MODEL corrects it, so
+ * this is a coded tool error, not a silent drop: wait for a job to finish (or
+ * cancel one) and retry, or run the work in the foreground.
+ */
+export function jobLimitExceeded(maxJobs, live) {
+    return new CruxyError({
+        code: ErrorCode.JobLimit,
+        title: `too many background jobs: ${live} live, limit ${maxJobs}`,
+        cause: "the count of queued + running + paused jobs is at `jobs.maxJobs`; a new " +
+            "dispatch would exceed the ceiling on OUTSTANDING jobs (distinct from the " +
+            "shared execution cap `subagent.maxConcurrency`)",
+        nextSteps: [
+            "wait for a running job to finish, or `cruxy cancel <id>` one you no longer need",
+            "raise `jobs.maxJobs` in config if more concurrent jobs are intended",
+            "or run this task in the foreground instead of the background",
+        ],
+        meta: { maxJobs, live },
+    });
+}
+/**
+ * `cruxy cancel/logs/rollback <id>` named a job that does not exist in this
+ * session. Jobs are session-scoped (NOT a daemon), so an id from a prior session
+ * is legitimately gone — fail loud with the id rather than a silent no-op.
+ */
+export function jobNotFound(id) {
+    return new CruxyError({
+        code: ErrorCode.JobNotFound,
+        title: `no background job with id "${id}" in this session`,
+        cause: "background jobs live only for the session that dispatched them; an id from " +
+            "a previous session, or a mistyped one, has no live job",
+        nextSteps: ["run `cruxy jobs` to list the live jobs and their ids"],
+        meta: { id },
+    });
+}
+/**
+ * A background-jobs command was used while the feature is disabled. Surfaced with
+ * how to enable it rather than pretending there are simply no jobs.
+ */
+export function jobsDisabled() {
+    return new CruxyError({
+        code: ErrorCode.JobsDisabled,
+        title: "background jobs are disabled",
+        cause: "`jobs.enabled` is false, so no jobs can be dispatched or listed",
+        nextSteps: ["enable it: `cruxy config set jobs.enabled true`"],
+    });
+}
 // ── testing (exit 2) ──────────────────────────────────────────────────────────
 /**
  * No test command could be detected and none is configured (C.13). cruxy never

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";
@@ -165,6 +173,19 @@ export declare const ErrorCode: {
      * is a single-repo artifact, so it is refused (naming both) rather than silently
      * PR one half. */
     readonly VcsCrossRoot: "CRUXY_E_VCS_CROSS_ROOT";
+    /** A `run_in_background` dispatch was refused because the live job count
+     * (queued + running + paused) already sits at `jobs.maxJobs`. The MODEL corrects
+     * it — wait for a job to finish (or cancel one) and retry — so it is a usage-tier
+     * coded error, never a silently-dropped dispatch. */
+    readonly JobLimit: "CRUXY_E_JOB_LIMIT";
+    /** `cruxy cancel/logs/rollback <id>` named a job id that does not exist in this
+     * session. Jobs are session-scoped (NOT a daemon), so an id from a prior session
+     * is legitimately unknown — fail loud with the id rather than a silent no-op. */
+    readonly JobNotFound: "CRUXY_E_JOB_NOT_FOUND";
+    /** A background-jobs command (`cruxy jobs/logs/cancel`) was used while
+     * `jobs.enabled` is false. The feature is opt-in; surfaced with how to enable it
+     * rather than pretending there are simply no jobs. */
+    readonly JobsDisabled: "CRUXY_E_JOBS_DISABLED";
 };
 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. */
@@ -185,6 +193,20 @@ export const ErrorCode = {
      * is a single-repo artifact, so it is refused (naming both) rather than silently
      * PR one half. */
     VcsCrossRoot: "CRUXY_E_VCS_CROSS_ROOT",
+    // session-scoped background jobs (exit 2 / 19) — C.28
+    /** A `run_in_background` dispatch was refused because the live job count
+     * (queued + running + paused) already sits at `jobs.maxJobs`. The MODEL corrects
+     * it — wait for a job to finish (or cancel one) and retry — so it is a usage-tier
+     * coded error, never a silently-dropped dispatch. */
+    JobLimit: "CRUXY_E_JOB_LIMIT",
+    /** `cruxy cancel/logs/rollback <id>` named a job id that does not exist in this
+     * session. Jobs are session-scoped (NOT a daemon), so an id from a prior session
+     * is legitimately unknown — fail loud with the id rather than a silent no-op. */
+    JobNotFound: "CRUXY_E_JOB_NOT_FOUND",
+    /** A background-jobs command (`cruxy jobs/logs/cancel`) was used while
+     * `jobs.enabled` is false. The feature is opt-in; surfaced with how to enable it
+     * rather than pretending there are simply no jobs. */
+    JobsDisabled: "CRUXY_E_JOBS_DISABLED",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -230,6 +252,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,
@@ -292,6 +318,13 @@ const EXIT_CODES = {
     // refusals kin to the other cross-root guards — they share the greppable code.
     [ErrorCode.VcsRemoteChanged]: 18,
     [ErrorCode.VcsCrossRoot]: 18,
+    // Background jobs (C.28). The dispatch-limit refusal is model-correctable, so
+    // it shares the usage exit code (2) with the other model-facing coded errors
+    // (subagent depth/scope). The CLI-facing ones — an unknown job id, the feature
+    // disabled — get a distinct greppable category (19).
+    [ErrorCode.JobLimit]: 2,
+    [ErrorCode.JobNotFound]: 19,
+    [ErrorCode.JobsDisabled]: 19,
 };
 /** 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/jobs/approval-queue.d.ts

@@ -0,0 +1,85 @@
+import type { ApprovalDecision, RiskTier } from "../approval/index.js";
+/**
+ * The single foreground pending-approval queue (C.28) — the seam that lets a
+ * NON-interactive background job get a gated action approved by the ONE
+ * interactive foreground human, without becoming a second interactive context.
+ *
+ * The §0 model: a background job is not a competing consumer of the terminal —
+ * it is a PRODUCER on this queue. When a job hits a gated action it `submit`s the
+ * request here and blocks on the returned promise; it holds no terminal, no
+ * mutex, and (having released its execution slot) no compute while it waits. The
+ * foreground drains the queue when it is idle (between turns): {@link serviceAll}
+ * runs each request's `finalize` — the REAL U.3 prompt + checkpoint, serialized
+ * through the shared approval mutex INSIDE `finalize` — and settles the producer
+ * with the human's decision. Because the prompt happens on the foreground under
+ * the shared mutex, a background job can never paint a second prompt over a
+ * foreground one, and the action never executes until a human has decided.
+ *
+ * This queue is pure transport: it holds pending entries and settles them. It
+ * knows nothing about checkpoints, the mutex, or how a decision is reached — the
+ * manager composes that into each entry's `finalize`.
+ */
+/** A read-only view of one pending request (for `/jobs` display + tests). */
+export interface PendingApproval {
+    /** Queue-unique id. */
+    readonly id: string;
+    /** The job that is blocked on this decision. */
+    readonly jobId: string;
+    /** One plain line describing the action (e.g. "run: rm -rf build"). */
+    readonly summary: string;
+    /** Risk tier (mutate | destructive — reads never reach the queue). */
+    readonly tier: RiskTier;
+}
+/** What a producing job submits: how to describe it, and how to actually decide. */
+export interface ApprovalSubmission {
+    jobId: string;
+    summary: string;
+    tier: RiskTier;
+    /**
+     * Run the REAL decision: the interactive U.3 prompt + the job's checkpoint
+     * snapshot, serialized on the shared approval mutex. Composed by the manager so
+     * this queue stays decoupled. Called by {@link serviceAll} on the foreground;
+     * its resolved decision settles the producer's `submit` promise. A throw
+     * (e.g. a checkpoint failure) rejects the producer's promise so the job fails
+     * loud rather than hanging.
+     */
+    finalize: () => Promise<ApprovalDecision>;
+}
+export declare class ApprovalQueue {
+    private readonly queue;
+    private seq;
+    /**
+     * A job submits a gated action and awaits the decision. Resolves when the
+     * foreground services it ({@link serviceAll}) or a caller {@link withdraw}s it;
+     * rejects if the finalize throws. The action does NOT execute here — the caller
+     * only proceeds after this resolves `{allow:true}`.
+     */
+    submit(sub: ApprovalSubmission): Promise<ApprovalDecision>;
+    /** Whether any request is waiting to be serviced. */
+    hasPending(): boolean;
+    /** Count of requests waiting. */
+    get size(): number;
+    /** Read-only snapshot of every pending request, FIFO order. */
+    pending(): PendingApproval[];
+    /** The pending request for one job (a job has at most one at a time), if any. */
+    pendingFor(jobId: string): PendingApproval | undefined;
+    /**
+     * Foreground drain: service every currently-pending request, FIFO, ONE AT A
+     * TIME — each `finalize` fully settles (including the human's keypress) before
+     * the next begins, so two background prompts never overlap and the shared mutex
+     * inside `finalize` also serializes them against any foreground action. Returns
+     * the number serviced. Requests that arrive AFTER draining starts wait for the
+     * next drain (bounded work per idle window). A finalize throw rejects that one
+     * producer and drains on — one job's checkpoint failure never wedges the queue.
+     */
+    serviceAll(): Promise<number>;
+    /**
+     * Withdraw a job's pending request WITHOUT prompting — used when the job is
+     * cancelled (or the session exits) while it is paused: settle the producer with
+     * `decision` (a deny) so its `submit` promise resolves and the job can finish
+     * tearing down instead of blocking forever. Returns true if one was withdrawn.
+     */
+    withdraw(jobId: string, decision: ApprovalDecision): boolean;
+    /** Settle an entry exactly once (double-settle is a defensive no-op). */
+    private settle;
+}