@cruxy/cli 0.23.0 → 0.25.0

package/dist/cli/session-factory.js

@@ -1,19 +1,25 @@
-import path from "node:path";
 import { createProvider } from "@cruxy/sdk";
 import { loadProjectInstructions } from "../config/index.js";
 import { logger } from "../utils/logger.js";
 import { getGitInfo } from "../utils/git.js";
-import { ApprovalService, InteractivePolicy, SessionAllowlist, classify, defaultPromptIO, } from "../approval/index.js";
+import { ApprovalMutex, ApprovalService, InteractivePolicy, SessionAllowlist, defaultPromptIO, serializeGate, } from "../approval/index.js";
+import { withCheckpointGate } from "../checkpoint/index.js";
+// Re-exported for back-compat: the checkpoint hook moved to the checkpoint
+// package (so the subagent orchestrator and C.28 jobs can compose it without
+// importing the CLI layer). Existing imports of `withCheckpointGate` from the
+// session factory keep working.
+export { withCheckpointGate };
 import { shouldUseColor } from "../errors/index.js";
 import { buildDefaultRegistry, } from "../tools/index.js";
 import { Session, } from "../agent/index.js";
 import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
 import { routerForConfig } from "../routing/index.js";
-import { MemoryService, rememberTool } from "../memory/index.js";
+import { MemoryService, buildMultiRootRecallBlock, rememberTool, } from "../memory/index.js";
 import { findDefinitionTool, findReferencesTool, getDiagnosticsTool, hoverTool, } from "../lsp/index.js";
 import { createWebSearchTool, createWebFetchTool } from "../web/index.js";
 import { appendRun } from "../usage/index.js";
-import { SubagentOrchestrator, makeSpawnSubagentTool, } from "../subagent/index.js";
+import { Semaphore, SubagentOrchestrator, makeSpawnSubagentTool, makeSpawnSubagentsTool, } from "../subagent/index.js";
+import { ApprovalQueue, JobManager, makeRunInBackgroundTool, } from "../jobs/index.js";
 /**
  * Wrap a PromptIO so the live region yields before any prompt text lands
  * (U.2/U.4): the prompt writes to stderr while the status line owns the last
@@ -54,97 +60,62 @@ function resumeLineAfterApproval(requestApproval, renderer) {
     };
 }
 /**
- * Wrap the approval gate with the C.32 auto-checkpoint hook. Ordering is the
- * whole point: a tool mutates only *after* `requestApproval` resolves, so
- * snapshotting after an `allow` decision but before returning it means the
- * checkpoint always lands before the run's first mutation — and a denied
- * action never creates one. The same seam records which paths the run touched
- * (file actions) or that attribution is lost (shell), for rollback's
- * external-change detection.
- */
-export function withCheckpointGate(requestApproval, gate, ws) {
-    if (!gate)
-        return requestApproval;
-    return async (action) => {
-        const decision = await requestApproval(action);
-        if (!decision.allow)
-            return decision;
-        const request = classify(action, ws.primary().absPath);
-        if (request.tier === "read")
-            return decision;
-        if (action.kind === "shell" || action.kind === "test") {
-            // JC-β residual: non-primary shell/test are Step 5, so they are still
-            // hard-attributed to the primary root regardless of `action.root` (which
-            // those tools populate as the seam). They can mutate files we cannot
-            // attribute (scripts, snapshot writers) — record the lost attribution.
-            const root = ws.primary();
-            const svc = gate.serviceFor(root.name, root.absPath);
-            const checkpoint = await svc.ensureCheckpoint();
-            await svc.recordShellMutation();
-            if (checkpoint) {
-                await gate.recordMember(root.name, root.absPath, checkpoint.id);
-            }
-            return decision;
-        }
-        if (action.kind === "vcs") {
-            // C.26 Step 4: a PR now names its root (⚖︎#11), so the checkpoint is
-            // attributed to THAT selected root — its git commit stages/lands in that
-            // root's working tree, never the primary's. `recordShellMutation` because a
-            // `git add -A` + commit mutates the tree opaquely (no per-file attribution).
-            // Fall back to the primary only if a root name is somehow absent (defensive).
-            const root = (action.root ? ws.tryRootByName(action.root) : undefined) ??
-                ws.primary();
-            const svc = gate.serviceFor(root.name, root.absPath);
-            const checkpoint = await svc.ensureCheckpoint();
-            await svc.recordShellMutation();
-            if (checkpoint) {
-                await gate.recordMember(root.name, root.absPath, checkpoint.id);
-            }
-            return decision;
-        }
-        // File actions (write/edit/patch): attribute each RESOLVED target to its root
-        // (JC-G — post-confinement truth) and checkpoint every touched root. A patch
-        // may span roots; each root gets its own checkpoint + set member.
-        for (const [rootName, group] of attributeFileTargets(action, ws)) {
-            const svc = gate.serviceFor(rootName, group.rootAbsPath);
-            const checkpoint = await svc.ensureCheckpoint();
-            await svc.recordTouched(group.paths);
-            if (checkpoint) {
-                await gate.recordMember(rootName, group.rootAbsPath, checkpoint.id);
-            }
-        }
-        return decision;
-    };
-}
-/**
- * Group a file action's resolved absolute targets by the root that contains each
- * (JC-G). write/edit carry an already-absolute `path`; patch preview paths are
- * relative to the PRIMARY cwd (`path.relative(ctx.cwd, abs)` in apply_patch), so
- * we reconstruct the absolute path from the primary root rather than trusting
- * classify's `targets` — which also correctly handles a patch spanning roots.
+ * Register every CONDITIONALLY-enabled runtime tool onto `registry`, in the fixed
+ * order the model sees them: `remember` (memory), the four LSP tools, the two web
+ * tools, the trusted MCP tools, then `spawn_subagent`. Factored out of
+ * {@link buildAgentSession} for ONE reason beyond tidiness: it makes the *complete
+ * runtime* tool set enumerable by a test (JC-B). The default registry only covers
+ * the 14 always-on tools; the allowlist test that pins "no tool can add a workspace
+ * root" is only sound if it runs against the SAME set the session ships — so the
+ * session factory and that test both build the surface through this one seam. A new
+ * conditionally-registered tool added here fails the allowlist test until it is
+ * consciously listed and audited.
+ *
+ * Each family is opt-in and inert when its feature flag is off, exactly as before —
+ * this function is a pure move of the inline registration, same guards, same order.
+ * `spawnTool` is passed in (already depth-bound) because it needs the orchestrator;
+ * it registers only when nesting is allowed (`subagent.maxDepth > 0`).
  */
-function attributeFileTargets(action, ws) {
-    const abs = [];
-    if (action.kind === "write" || action.kind === "edit") {
-        if (action.path)
-            abs.push(action.path);
+export function registerRuntimeTools(registry, config, opts = {}) {
+    // Persistent memory write tool (C.29) — inert unless enabled.
+    if (config.memory.enabled)
+        registry.register(rememberTool);
+    // Per-language LSP introspection (C.12): four read-only tools that spawn
+    // EXTERNAL language servers, so opt-in; none registered when off.
+    if (config.lsp.enabled) {
+        registry.register(findDefinitionTool);
+        registry.register(findReferencesTool);
+        registry.register(getDiagnosticsTool);
+        registry.register(hoverTool);
     }
-    else if (action.kind === "patch" && action.preview?.type === "patch") {
-        for (const file of action.preview.files) {
-            abs.push(path.resolve(ws.primary().absPath, file.path));
-        }
+    // Web search + fetch (C.20): read-only, reach the PUBLIC internet and inject
+    // untrusted data, so opt-in; neither registered (nor a provider constructed)
+    // when off.
+    if (config.web.enabled) {
+        registry.register(createWebSearchTool());
+        registry.register(createWebFetchTool());
     }
-    const byRoot = new Map();
-    for (const target of abs) {
-        const root = ws.rootContaining(target);
-        const group = byRoot.get(root.name) ?? {
-            rootAbsPath: root.absPath,
-            paths: [],
-        };
-        group.paths.push(target);
-        byRoot.set(root.name, group);
+    // MCP servers (C.27): already connected, trusted, and adapted to bounded,
+    // destructive-gated, `mcp__`-namespaced tools before we got here — a plain
+    // hand-off. Empty unless mcp is enabled with a trusted server.
+    for (const tool of opts.mcpTools ?? [])
+        registry.register(tool);
+    // Subagent spawn (C.14) + parallel fan-out (C.33): only when nesting depth
+    // allows (maxDepth 0 disables the feature structurally). Both are read-only to
+    // propose; the plan propose phase filters them out. The plural `spawn_subagents`
+    // is registered ONLY here (the main registry) — never on a child's scoped
+    // registry — so parallel fan-out stays a depth-0 capability.
+    if (config.subagent.maxDepth > 0) {
+        if (opts.spawnTool)
+            registry.register(opts.spawnTool);
+        if (opts.spawnManyTool)
+            registry.register(opts.spawnManyTool);
     }
-    return byRoot;
+    // Background jobs (C.28): the non-blocking `run_in_background` dispatch tool,
+    // registered only when the feature is enabled (off by default). Bound to the
+    // session's job manager by the caller.
+    if (config.jobs.enabled && opts.jobTool)
+        registry.register(opts.jobTool);
 }
 /**
  * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
@@ -191,51 +162,71 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
     const execRegistry = buildDefaultRegistry();
     const git = getGitInfo(cwd);
     const projectInstructions = loadProjectInstructions(cwd);
-    // Persistent memory (C.29): register the write tool and build the recall block
-    // ONCE at session start. User memory is always eligible; project memory is
-    // recalled only when trusted (a cloned repo's notes never inject silently).
-    // Fully inert when disabled. Recall is best-effort — a load problem degrades to
-    // "no memory", never a hard failure at session start.
+    // Persistent memory (C.29): build the recall block ONCE at session start (the
+    // `remember` write tool is registered via registerRuntimeTools below). User
+    // memory is always eligible; project memory is recalled only when trusted (a
+    // cloned repo's notes never inject silently). Fully inert when disabled. Recall
+    // is best-effort — a load problem degrades to "no memory", never a hard failure.
     let recalledMemory = null;
     if (config.memory.enabled) {
-        execRegistry.register(rememberTool);
-        const recall = new MemoryService({ cwd, config: config.memory }).recall();
-        recalledMemory = recall.block;
-        if (recall.projectPresentButUntrusted) {
-            logger.info("project memory found but not trusted — run `cruxy memory trust .` to recall it");
+        if (workspace.isMultiRoot) {
+            // Recall project memory from EVERY trusted root, each under its own
+            // root-labeled block; user memory (global) once. Untrusted roots are not
+            // injected and are NAMED — a cloned repo's notes never inject silently,
+            // and a root whose notes you've never trusted is called out, not dropped.
+            const roots = [];
+            let userEntries = [];
+            for (const r of workspace.roots()) {
+                const svc = new MemoryService({
+                    cwd: r.absPath,
+                    config: config.memory,
+                });
+                const st = svc.status();
+                // The label is paired with the store HERE — structurally, a block can
+                // never carry a root the entries didn't come from.
+                if (r.primary) {
+                    userEntries = st.user;
+                    for (const e of st.errors) {
+                        logger.warn(`memory: excluded ${e.scope} entry ${e.id} — ${e.message}`);
+                    }
+                }
+                else {
+                    // Siblings share the same global user file — surface only their own
+                    // project-scope load errors (user errors already reported by primary).
+                    for (const e of st.errors.filter((e) => e.scope === "project")) {
+                        logger.warn(`memory: excluded ${e.scope} entry ${e.id} in ${r.name} — ${e.message}`);
+                    }
+                }
+                if (st.projectTrusted) {
+                    if (st.project.length > 0)
+                        roots.push({ name: r.name, entries: st.project });
+                }
+                else if (st.project.length > 0) {
+                    logger.info(`memory:  root "${r.name}" project memory not trusted — run \`cruxy memory trust ${r.absPath}\` to recall it`);
+                }
+            }
+            recalledMemory = buildMultiRootRecallBlock({
+                user: userEntries,
+                roots,
+                maxTokens: config.memory.maxRecallTokens,
+            });
         }
-        for (const e of recall.errors) {
-            logger.warn(`memory: excluded ${e.scope} entry ${e.id} — ${e.message}`);
+        else {
+            const recall = new MemoryService({ cwd, config: config.memory }).recall();
+            recalledMemory = recall.block;
+            if (recall.projectPresentButUntrusted) {
+                logger.info("project memory found but not trusted — run `cruxy memory trust .` to recall it");
+            }
+            for (const e of recall.errors) {
+                logger.warn(`memory: excluded ${e.scope} entry ${e.id} — ${e.message}`);
+            }
         }
     }
-    // Per-language LSP (C.12): register the four read-only introspection tools
-    // only when enabled. They spawn and manage EXTERNAL language-server processes,
-    // so — like the sandbox — the feature is opt-in; when off, none is registered
-    // and no server ever spawns. Read-only (no approval), so they bypass the U.3
-    // gate like search_codebase and are available to subagents and plan proposals.
-    if (config.lsp.enabled) {
-        execRegistry.register(findDefinitionTool);
-        execRegistry.register(findReferencesTool);
-        execRegistry.register(getDiagnosticsTool);
-        execRegistry.register(hoverTool);
-    }
-    // Web search + fetch (C.20): register the two read-only web tools only when
-    // enabled. They reach the PUBLIC internet and inject attacker-controllable data
-    // (results/pages are demarcated as untrusted and never persisted), so — like
-    // LSP and MCP — the feature is opt-in; when off, neither tool is registered and
-    // no search provider is ever constructed. Read-only (no approval), so they
-    // bypass the U.3 gate like search_codebase.
-    if (config.web.enabled) {
-        execRegistry.register(createWebSearchTool());
-        execRegistry.register(createWebFetchTool());
-    }
-    // MCP servers (C.27): the caller connected + trusted the servers and produced
-    // these tools through the single adapter seam BEFORE building the session, so
-    // registration here is a plain hand-off — every one is destructive-gated,
-    // demarcated, and bounded by construction. Empty unless `mcp.enabled` and at
-    // least one trusted server produced tools, so the default path is unchanged.
-    for (const tool of mcpTools)
-        execRegistry.register(tool);
+    // The conditionally-registered runtime tools (remember / LSP / web / MCP) are
+    // added below via registerRuntimeTools — the single seam the JC-B allowlist test
+    // also builds through, so the audited surface can never drift from the shipped
+    // one. spawn_subagent joins them there too (it needs the orchestrator built
+    // first). See registerRuntimeTools.
     // One io shared by every prompt in the session (plan approval, the U.3 gate,
     // and any gate inside a subagent), so they all coordinate with the same live
     // region. The full wrapper stack around an ApprovalService is factored here
@@ -247,7 +238,20 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
     // wired, and it is set on the SAME ctx whose `requestApproval` IS that gate — so
     // lifting the non-primary-write refusal and capturing the write are one decision.
     const checkpointsActive = Boolean(checkpoints);
-    const gate = (approval) => withCheckpointGate(resumeLineAfterApproval((action) => approval.requestApproval(action), renderer), checkpoints, workspace);
+    // The C.33 spine: ONE approval mutex shared by the main loop and every subagent
+    // gate, so across concurrent siblings only one non-read action is in its gate at
+    // a time — one prompt on screen, one checkpoint snapshot/set-write in flight.
+    // Read-tier actions bypass it (see serializeGate), so a parallel read fan-out is
+    // never stalled behind an unrelated pending prompt.
+    const approvalMutex = new ApprovalMutex();
+    // The ONE execution semaphore for the whole session (C.28 + C.33): subagent
+    // fan-out AND background jobs draw permits from THIS instance, so
+    // `subagent.maxConcurrency` bounds their COMBINED concurrency — not one cap
+    // each. The ONE pending-approval queue background jobs produce onto is created
+    // here too, so foreground servicing and job production share it.
+    const executionSemaphore = new Semaphore(config.subagent.maxConcurrency);
+    const approvalQueue = new ApprovalQueue();
+    const gate = (approval) => serializeGate(withCheckpointGate(resumeLineAfterApproval((action) => approval.requestApproval(action), renderer), checkpoints, workspace), approvalMutex, cwd);
     // Subagent orchestration (C.14): spawn_subagent goes on the main registry
     // only when depth allows (maxDepth 0 disables the feature structurally).
     // Registered before the plan wiring so plan-mode execution steps can
@@ -265,11 +269,49 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
         renderer,
         sandbox,
         checkpointsActive,
+        executionSemaphore,
         makeChildApproval: () => gate(new ApprovalService({ cwd, interactive: ttyInteractive, io })),
     });
-    if (config.subagent.maxDepth > 0) {
-        execRegistry.register(makeSpawnSubagentTool(orchestrator, 0));
-    }
+    // Background jobs (C.28): the session-scoped manager the `run_in_background`
+    // tool dispatches onto. Built only when enabled. It shares the SAME execution
+    // semaphore, approval queue, and approval mutex as the foreground/subagents —
+    // one system, one cap, one queue — and each job gets its OWN checkpoint gate
+    // (keyed by job id) so `cruxy rollback <id>` isolates a job.
+    const jobManager = config.jobs.enabled
+        ? new JobManager({
+            config,
+            provider,
+            router,
+            parentRegistry: execRegistry,
+            cwd,
+            workspace,
+            logger,
+            git,
+            projectInstructions,
+            sandbox,
+            semaphore: executionSemaphore,
+            approvalQueue,
+            approvalMutex,
+            foregroundInteractive: ttyInteractive,
+            promptIO: io,
+        })
+        : undefined;
+    const jobTool = jobManager ? makeRunInBackgroundTool(jobManager) : undefined;
+    // Now that the orchestrator exists, register every conditionally-enabled tool
+    // (remember / LSP / web / MCP / spawn_subagent) through the one seam the JC-B
+    // allowlist test also uses — order preserved, behaviour byte-identical.
+    const spawnTool = config.subagent.maxDepth > 0
+        ? makeSpawnSubagentTool(orchestrator, 0)
+        : undefined;
+    const spawnManyTool = config.subagent.maxDepth > 0
+        ? makeSpawnSubagentsTool(orchestrator, 0)
+        : undefined;
+    registerRuntimeTools(execRegistry, config, {
+        mcpTools,
+        spawnTool,
+        spawnManyTool,
+        jobTool,
+    });
     if (planMode) {
         // One allowlist shared by the plan-approval prompt and the per-action
         // gate, so a grant recorded during execution is honored by U.3's own check.
@@ -319,6 +361,7 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
             hooks,
             router,
             onRunUsage,
+            jobs: jobManager,
         });
     }
     const approval = new ApprovalService({
@@ -346,5 +389,6 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
         hooks,
         router,
         onRunUsage,
+        jobs: jobManager,
     });
 }

package/dist/config/schema.d.ts

@@ -248,6 +248,15 @@ export declare const SubagentConfigSchema: z.ZodObject<{
      * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
      */
     maxDepth: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Parallel fan-out breadth (C.33): the maximum number of subagents that run
+     * concurrently across the whole session, enforced by one shared semaphore.
+     * Parallel fan-out happens at depth 0 only and everything beneath it is
+     * sequential, so this composes with {@link maxDepth} into a LINEAR global
+     * ceiling (≤ maxConcurrency × maxDepth live agents) — never an exponential
+     * depth×breadth fork bomb. Default 3.
+     */
+    maxConcurrency: z.ZodDefault<z.ZodNumber>;
     /** Per-subagent budget ceilings; spawn-time overrides are clamped to these. */
     defaultBudget: z.ZodDefault<z.ZodObject<{
         /** Hard cap on the subagent's model turns. */
@@ -267,6 +276,7 @@ export declare const SubagentConfigSchema: z.ZodObject<{
     }>>;
 }, "strict", z.ZodTypeAny, {
     maxDepth: number;
+    maxConcurrency: number;
     defaultBudget: {
         maxTokens: number;
         maxIterations: number;
@@ -274,12 +284,60 @@ export declare const SubagentConfigSchema: z.ZodObject<{
     };
 }, {
     maxDepth?: number | undefined;
+    maxConcurrency?: number | undefined;
     defaultBudget?: {
         timeoutMs?: number | undefined;
         maxTokens?: number | undefined;
         maxIterations?: number | undefined;
     } | undefined;
 }>;
+/**
+ * Session-scoped background jobs (C.28): non-interactive orchestration the main
+ * agent dispatches with `run_in_background`, running CONCURRENTLY with the
+ * foreground session but bound to it — nothing survives session exit (NOT a
+ * daemon). A job hitting a gated action enqueues an approval request into the one
+ * foreground queue and pauses until a human services it; a paused job releases
+ * its execution slot.
+ *
+ * Two distinct ceilings, stated explicitly because they bound different things:
+ *   • {@link maxJobs} — how many background JOBS may exist at once (queued +
+ *     running + paused). A dispatch past it is refused (`CRUXY_E_JOB_LIMIT`).
+ *   • the shared execution cap is `subagent.maxConcurrency` (default 3) — how many
+ *     runs (subagents AND jobs, combined) may EXECUTE at once. It is NOT
+ *     duplicated here: jobs and subagents draw from the one semaphore. So up to
+ *     `maxJobs` jobs can be alive while only `maxConcurrency` execute; the rest
+ *     wait for a slot (or are paused on a human).
+ */
+export declare const JobsConfigSchema: z.ZodObject<{
+    /**
+     * Master switch. When true, the `run_in_background` tool is registered so the
+     * agent can dispatch background jobs. OFF by default — background work is an
+     * opt-in capability, and a session that never enables it behaves exactly as
+     * before (no tool, no manager, no queue).
+     */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Ceiling on live background jobs (queued + running + paused). Distinct from
+     * the shared execution cap (`subagent.maxConcurrency`): this bounds how many
+     * jobs can be OUTSTANDING, not how many run at once. Default 5.
+     */
+    maxJobs: z.ZodDefault<z.ZodNumber>;
+    /**
+     * How many of a job's most-recent log lines are retained in its ring buffer
+     * for `cruxy logs <id>`. Bounded so a chatty job can't grow memory without
+     * limit; older lines roll off oldest-first. Default 1000.
+     */
+    logBufferLines: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    maxJobs: number;
+    enabled: boolean;
+    logBufferLines: number;
+}, {
+    maxJobs?: number | undefined;
+    enabled?: boolean | undefined;
+    logBufferLines?: number | undefined;
+}>;
+export type JobsConfig = z.infer<typeof JobsConfigSchema>;
 /**
  * Sandbox / container execution (C.16): defense-in-depth beneath the U.3 gate.
  * When enabled, `run_command` and `run_tests` execute inside an isolated,
@@ -1027,6 +1085,15 @@ export declare const CruxyConfigSchema: z.ZodObject<{
          * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
          */
         maxDepth: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Parallel fan-out breadth (C.33): the maximum number of subagents that run
+         * concurrently across the whole session, enforced by one shared semaphore.
+         * Parallel fan-out happens at depth 0 only and everything beneath it is
+         * sequential, so this composes with {@link maxDepth} into a LINEAR global
+         * ceiling (≤ maxConcurrency × maxDepth live agents) — never an exponential
+         * depth×breadth fork bomb. Default 3.
+         */
+        maxConcurrency: z.ZodDefault<z.ZodNumber>;
         /** Per-subagent budget ceilings; spawn-time overrides are clamped to these. */
         defaultBudget: z.ZodDefault<z.ZodObject<{
             /** Hard cap on the subagent's model turns. */
@@ -1046,6 +1113,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         }>>;
     }, "strict", z.ZodTypeAny, {
         maxDepth: number;
+        maxConcurrency: number;
         defaultBudget: {
             maxTokens: number;
             maxIterations: number;
@@ -1053,12 +1121,42 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         };
     }, {
         maxDepth?: number | undefined;
+        maxConcurrency?: number | undefined;
         defaultBudget?: {
             timeoutMs?: number | undefined;
             maxTokens?: number | undefined;
             maxIterations?: number | undefined;
         } | undefined;
     }>>;
+    jobs: z.ZodDefault<z.ZodObject<{
+        /**
+         * Master switch. When true, the `run_in_background` tool is registered so the
+         * agent can dispatch background jobs. OFF by default — background work is an
+         * opt-in capability, and a session that never enables it behaves exactly as
+         * before (no tool, no manager, no queue).
+         */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Ceiling on live background jobs (queued + running + paused). Distinct from
+         * the shared execution cap (`subagent.maxConcurrency`): this bounds how many
+         * jobs can be OUTSTANDING, not how many run at once. Default 5.
+         */
+        maxJobs: z.ZodDefault<z.ZodNumber>;
+        /**
+         * How many of a job's most-recent log lines are retained in its ring buffer
+         * for `cruxy logs <id>`. Bounded so a chatty job can't grow memory without
+         * limit; older lines roll off oldest-first. Default 1000.
+         */
+        logBufferLines: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        maxJobs: number;
+        enabled: boolean;
+        logBufferLines: number;
+    }, {
+        maxJobs?: number | undefined;
+        enabled?: boolean | undefined;
+        logBufferLines?: number | undefined;
+    }>>;
     test: z.ZodDefault<z.ZodObject<{
         /** Explicit test command (overrides package.json detection). */
         command: z.ZodOptional<z.ZodString>;
@@ -1450,6 +1548,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     };
     subagent: {
         maxDepth: number;
+        maxConcurrency: number;
         defaultBudget: {
             maxTokens: number;
             maxIterations: number;
@@ -1509,6 +1608,11 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         idleTimeout: number;
         maxResults: number;
     };
+    jobs: {
+        maxJobs: number;
+        enabled: boolean;
+        logBufferLines: number;
+    };
     test: {
         maxIterations: number;
         captureBytes: number;
@@ -1594,6 +1698,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     } | undefined;
     subagent?: {
         maxDepth?: number | undefined;
+        maxConcurrency?: number | undefined;
         defaultBudget?: {
             timeoutMs?: number | undefined;
             maxTokens?: number | undefined;
@@ -1653,6 +1758,11 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         idleTimeout?: number | undefined;
         maxResults?: number | undefined;
     } | undefined;
+    jobs?: {
+        maxJobs?: number | undefined;
+        enabled?: boolean | undefined;
+        logBufferLines?: number | undefined;
+    } | undefined;
     test?: {
         command?: string | undefined;
         maxIterations?: number | undefined;

package/dist/config/schema.js

@@ -181,6 +181,15 @@ export const SubagentConfigSchema = z
      * 1 lets it spawn subagents that cannot themselves spawn (no fork bombs).
      */
     maxDepth: z.number().int().nonnegative().default(1),
+    /**
+     * Parallel fan-out breadth (C.33): the maximum number of subagents that run
+     * concurrently across the whole session, enforced by one shared semaphore.
+     * Parallel fan-out happens at depth 0 only and everything beneath it is
+     * sequential, so this composes with {@link maxDepth} into a LINEAR global
+     * ceiling (≤ maxConcurrency × maxDepth live agents) — never an exponential
+     * depth×breadth fork bomb. Default 3.
+     */
+    maxConcurrency: z.number().int().positive().default(3),
     /** Per-subagent budget ceilings; spawn-time overrides are clamped to these. */
     defaultBudget: z
         .object({
@@ -195,6 +204,46 @@ export const SubagentConfigSchema = z
         .default({}),
 })
     .strict();
+/**
+ * Session-scoped background jobs (C.28): non-interactive orchestration the main
+ * agent dispatches with `run_in_background`, running CONCURRENTLY with the
+ * foreground session but bound to it — nothing survives session exit (NOT a
+ * daemon). A job hitting a gated action enqueues an approval request into the one
+ * foreground queue and pauses until a human services it; a paused job releases
+ * its execution slot.
+ *
+ * Two distinct ceilings, stated explicitly because they bound different things:
+ *   • {@link maxJobs} — how many background JOBS may exist at once (queued +
+ *     running + paused). A dispatch past it is refused (`CRUXY_E_JOB_LIMIT`).
+ *   • the shared execution cap is `subagent.maxConcurrency` (default 3) — how many
+ *     runs (subagents AND jobs, combined) may EXECUTE at once. It is NOT
+ *     duplicated here: jobs and subagents draw from the one semaphore. So up to
+ *     `maxJobs` jobs can be alive while only `maxConcurrency` execute; the rest
+ *     wait for a slot (or are paused on a human).
+ */
+export const JobsConfigSchema = z
+    .object({
+    /**
+     * Master switch. When true, the `run_in_background` tool is registered so the
+     * agent can dispatch background jobs. OFF by default — background work is an
+     * opt-in capability, and a session that never enables it behaves exactly as
+     * before (no tool, no manager, no queue).
+     */
+    enabled: z.boolean().default(false),
+    /**
+     * Ceiling on live background jobs (queued + running + paused). Distinct from
+     * the shared execution cap (`subagent.maxConcurrency`): this bounds how many
+     * jobs can be OUTSTANDING, not how many run at once. Default 5.
+     */
+    maxJobs: z.number().int().positive().default(5),
+    /**
+     * How many of a job's most-recent log lines are retained in its ring buffer
+     * for `cruxy logs <id>`. Bounded so a chatty job can't grow memory without
+     * limit; older lines roll off oldest-first. Default 1000.
+     */
+    logBufferLines: z.number().int().positive().default(1000),
+})
+    .strict();
 /**
  * Sandbox / container execution (C.16): defense-in-depth beneath the U.3 gate.
  * When enabled, `run_command` and `run_tests` execute inside an isolated,
@@ -481,6 +530,7 @@ export const CruxyConfigSchema = z
     lsp: LspConfigSchema.default({}),
     checkpoint: CheckpointConfigSchema.default({}),
     subagent: SubagentConfigSchema.default({}),
+    jobs: JobsConfigSchema.default({}),
     test: TestConfigSchema.default({}),
     sandbox: SandboxConfigSchema.default({}),
     hooks: HooksConfigSchema.default({}),