@cruxy/cli 0.24.0 → 0.26.0

package/dist/cli/repl.js

@@ -5,10 +5,14 @@ import { runGatedShell } from "../tools/shell/exec.js";
 import { addRootToWorkspace } from "../workspace/index.js";
 import { themeForColor } from "../theme/index.js";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
-import { createRenderer } from "../render/index.js";
+import { createRenderer, fit, resolveColumns, } from "../render/index.js";
 import { logger } from "../utils/logger.js";
 /** The REPL prompts on stdout; its chrome resolves against stdout's color. */
 const theme = themeForColor(shouldUseColor(process.stdout));
+/** Fit a committed REPL line to stdout's current width (U.12), id/status-first. */
+function fitOut(line) {
+    return fit(line, resolveColumns(process.stdout), theme.glyph.ellipsis);
+}
 const PROMPT = `${theme.accent("cruxy")} ${theme.muted(theme.glyph.caret)} `;
 /**
  * The REPL's slash commands — the autocomplete candidate set (U.7). Keep in
@@ -20,6 +24,9 @@ export const REPL_COMMANDS = [
     "/compact",
     "/reload",
     "/plan",
+    "/jobs",
+    "/logs",
+    "/cancel",
     "/exit",
     "/quit",
 ];
@@ -29,6 +36,9 @@ const HELP = `Commands:
   /compact       summarize older history to free up context now
   /reload        re-read project instructions (CRUXY.md)
   /plan          toggle plan mode (propose a plan before executing)
+  /jobs          list background jobs and their status
+  /logs <id>     show a background job's log
+  /cancel <id>   cancel a background job
   /exit, /quit   leave cruxy
   Ctrl+D         leave cruxy`;
 const defaultIO = () => ({
@@ -148,6 +158,91 @@ async function handleAddRoot(input, session) {
         printReplError(err);
     }
 }
+/**
+ * Service any background-job approvals that piled up (C.28) — the auto-surface
+ * point. Called when the foreground is idle (between turns), so a paused job's
+ * gated action is decided through the SAME U.3 prompt as a foreground one, one at
+ * a time. No pending → a no-op (nothing printed). The job resumes on approval.
+ */
+async function drainJobApprovals(session) {
+    const jobs = session.jobs;
+    if (!jobs || !jobs.hasPendingApprovals())
+        return;
+    logger.print(theme.muted(`\n${theme.glyph.bullet} a background job needs your approval:`));
+    await jobs.serviceApprovals();
+}
+/** Render the background-job list (`/jobs`). */
+function handleJobsList(session) {
+    const jobs = session.jobs;
+    if (!jobs) {
+        logger.print(theme.muted("background jobs are disabled — enable with `cruxy config set jobs.enabled true`"));
+        return;
+    }
+    const list = jobs.list();
+    if (list.length === 0) {
+        logger.print(theme.muted("no background jobs this session"));
+        return;
+    }
+    for (const j of list) {
+        const status = j.status === "failed" ? theme.danger(j.status) : theme.accent(j.status);
+        const pending = j.pendingApproval
+            ? theme.muted(` — needs approval: ${j.pendingApproval}`)
+            : "";
+        const err = j.error ? theme.muted(` (${j.error})`) : "";
+        // Fit id-first so the job id + status always survive; the label/notes tail
+        // truncates with an honest ellipsis at narrow width (U.12).
+        logger.print(fitOut(`${theme.strong(j.id)}  ${status}  ${j.label}${pending}${err}`));
+    }
+}
+/** Print one job's log (`/logs <id>`). */
+function handleJobLogs(input, session) {
+    const jobs = session.jobs;
+    if (!jobs) {
+        logger.print(theme.muted("background jobs are disabled"));
+        return;
+    }
+    const id = input.slice("/logs".length).trim();
+    if (!id) {
+        logger.print(theme.muted("usage: /logs <id>"));
+        return;
+    }
+    try {
+        const log = jobs.logs(id);
+        if (log.dropped > 0) {
+            logger.print(theme.muted(`… ${log.dropped} earlier line(s) rolled off`));
+        }
+        for (const line of log.lines) {
+            const text = line.stream === "err" ? theme.danger(line.text) : line.text;
+            logger.print(fitOut(text));
+        }
+        logger.print(theme.muted(`(${log.status})`));
+    }
+    catch (err) {
+        printReplError(err);
+    }
+}
+/** Cancel a job (`/cancel <id>`). */
+async function handleJobCancel(input, session) {
+    const jobs = session.jobs;
+    if (!jobs) {
+        logger.print(theme.muted("background jobs are disabled"));
+        return;
+    }
+    const id = input.slice("/cancel".length).trim();
+    if (!id) {
+        logger.print(theme.muted("usage: /cancel <id>"));
+        return;
+    }
+    try {
+        const cancelled = jobs.cancel(id);
+        logger.print(theme.muted(cancelled
+            ? `cancelling ${id} (its process tree is killed; any checkpoint survives for rollback)`
+            : `${id} is already finished`));
+    }
+    catch (err) {
+        printReplError(err);
+    }
+}
 /**
  * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
  * commands or run a turn, repeat. Assistant text and tool-call progress stream
@@ -170,6 +265,11 @@ export async function runInteractive(session, io = defaultIO(), renderer = creat
 }
 async function replLoop(session, io, renderer, checkpoints, slashCommands = []) {
     for (;;) {
+        // Auto-surface (C.28): before prompting, service any background-job approvals
+        // that piled up while the last turn ran — one at a time, through the same U.3
+        // prompt. Done here (foreground idle, no readline interface live) so a job's
+        // prompt never contends with the line reader.
+        await drainJobApprovals(session);
         const line = await readLine(io, PROMPT);
         // EOF / Ctrl+D.
         if (line === null) {
@@ -217,6 +317,18 @@ async function replLoop(session, io, renderer, checkpoints, slashCommands = [])
             logger.print(HELP);
             continue;
         }
+        if (trimmed === "/jobs") {
+            handleJobsList(session);
+            continue;
+        }
+        if (trimmed === "/logs" || trimmed.startsWith("/logs ")) {
+            handleJobLogs(trimmed, session);
+            continue;
+        }
+        if (trimmed === "/cancel" || trimmed.startsWith("/cancel ")) {
+            await handleJobCancel(trimmed, session);
+            continue;
+        }
         if (trimmed === "/add-root" || trimmed.startsWith("/add-root ")) {
             await handleAddRoot(trimmed, session);
             continue;

package/dist/cli/session-factory.d.ts

@@ -1,21 +1,12 @@
 import type { CruxyConfig } from "../config/index.js";
-import type { ApprovalDecision } from "../approval/index.js";
+import { withCheckpointGate } from "../checkpoint/index.js";
 import type { CheckpointGate } from "../checkpoint/index.js";
+export { withCheckpointGate };
 import type { SandboxService } from "../sandbox/index.js";
 import type { StreamRenderer } from "../render/index.js";
-import { ToolRegistry, type ApproveAction, type Tool } from "../tools/index.js";
+import { ToolRegistry, type Tool } from "../tools/index.js";
 import { Session, type LifecycleHookRunner } from "../agent/index.js";
 import type { Workspace } from "../workspace/index.js";
-/**
- * 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 declare function withCheckpointGate(requestApproval: (action: ApproveAction) => Promise<ApprovalDecision>, gate: CheckpointGate | undefined, ws: Workspace): (action: ApproveAction) => Promise<ApprovalDecision>;
 /**
  * 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
@@ -37,6 +28,7 @@ export declare function registerRuntimeTools(registry: ToolRegistry, config: Cru
     mcpTools?: Tool[];
     spawnTool?: Tool;
     spawnManyTool?: Tool;
+    jobTool?: Tool;
 }): void;
 /**
  * Build a ready-to-run agent {@link Session} from a resolved key — the wiring

package/dist/cli/session-factory.js

@@ -1,9 +1,14 @@
-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 { ApprovalMutex, ApprovalService, InteractivePolicy, SessionAllowlist, classify, defaultPromptIO, serializeGate, } 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";
@@ -13,7 +18,8 @@ import { MemoryService, buildMultiRootRecallBlock, rememberTool, } from "../memo
 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, makeSpawnSubagentsTool, } 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
@@ -53,99 +59,6 @@ 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.
- */
-function attributeFileTargets(action, ws) {
-    const abs = [];
-    if (action.kind === "write" || action.kind === "edit") {
-        if (action.path)
-            abs.push(action.path);
-    }
-    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));
-        }
-    }
-    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);
-    }
-    return byRoot;
-}
 /**
  * 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
@@ -198,6 +111,11 @@ export function registerRuntimeTools(registry, config, opts = {}) {
         if (opts.spawnManyTool)
             registry.register(opts.spawnManyTool);
     }
+    // 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
@@ -326,6 +244,13 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
     // 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).
@@ -344,8 +269,34 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
         renderer,
         sandbox,
         checkpointsActive,
+        executionSemaphore,
         makeChildApproval: () => gate(new ApprovalService({ cwd, interactive: ttyInteractive, io })),
     });
+    // 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.
@@ -359,6 +310,7 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
         mcpTools,
         spawnTool,
         spawnManyTool,
+        jobTool,
     });
     if (planMode) {
         // One allowlist shared by the plan-approval prompt and the per-action
@@ -409,6 +361,7 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
             hooks,
             router,
             onRunUsage,
+            jobs: jobManager,
         });
     }
     const approval = new ApprovalService({
@@ -436,5 +389,6 @@ export function buildAgentSession(config, apiKey, workspace, ttyInteractive, pla
         hooks,
         router,
         onRunUsage,
+        jobs: jobManager,
     });
 }

package/dist/components/frame.d.ts

@@ -1,6 +1,7 @@
+import { stripAnsi } from "../render/layout.js";
 import type { RenderCapabilities } from "../render/index.js";
-/** The visible text of a possibly-styled row. */
-export declare function stripAnsi(text: string): string;
+/** The visible text of a possibly-styled row (re-exported from the U.12 home). */
+export { stripAnsi };
 /**
  * The transient multi-line region interactive components draw into (U.7) —
  * the multi-row analog of the TTY renderer's single managed status line, with
@@ -12,6 +13,8 @@ export declare function stripAnsi(text: string): string;
  *   soft-wrap; wrapped rows would break erasure and leave artifacts.
  * - `clear()` removes the frame entirely — after a component resolves, the
  *   screen holds zero leftover bytes from the interaction.
+ * - On resize (U.12) the frame reflows its current rows in place at the new
+ *   width; committed output above is untouched. `clear()` also unsubscribes.
  *
  * Requires cursor control (`caps.cursor`); components guard on that before
  * constructing one.
@@ -19,7 +22,7 @@ export declare function stripAnsi(text: string): string;
 export interface Frame {
     /** Repaint the frame with these rows (erases the previous paint first). */
     render(lines: string[]): void;
-    /** Erase the frame completely. Idempotent. */
+    /** Erase the frame completely and release the resize subscription. Idempotent. */
     clear(): void;
 }
 export declare function createFrame(write: (text: string) => void, caps: RenderCapabilities): Frame;

package/dist/components/frame.js

@@ -1,32 +1,22 @@
+import { fit, stripAnsi } from "../render/layout.js";
 import { resolveTheme } from "../theme/index.js";
 /** Erase the current line and return the cursor to column 0 (same as U.2). */
 const CLEAR_LINE = "\r\x1b[2K";
 /** Move the cursor up one row. */
 const CURSOR_UP = "\x1b[1A";
-/** SGR escape sequences (the only ANSI the components emit — via picocolors). */
-// eslint-disable-next-line no-control-regex
-const SGR = /\x1b\[[0-9;]*m/g;
-/** The visible text of a possibly-styled row. */
-export function stripAnsi(text) {
-    return text.replace(SGR, "");
-}
+/** The visible text of a possibly-styled row (re-exported from the U.12 home). */
+export { stripAnsi };
 export function createFrame(write, caps) {
     let drawn = 0;
+    let lastLines = [];
     const ellipsis = resolveTheme(caps).glyph.ellipsis;
     /**
      * Truncate to width-1 (cursor rests after the last cell; a full-width row
      * would auto-wrap on some terminals). Width is measured on VISIBLE
-     * characters — rows may carry ANSI color. A row that fits passes through
-     * styled; an overflowing row is truncated on its stripped text (style is
-     * dropped rather than risking a cut escape sequence).
+     * characters (U.12 {@link fit}) — rows may carry ANSI color; a row that fits
+     * passes through styled, an overflowing row is truncated on its visible text.
      */
-    const fit = (line) => {
-        const room = Math.max(1, caps.width - 1);
-        const plain = stripAnsi(line);
-        if (plain.length <= room)
-            return line;
-        return plain.slice(0, room - 1) + ellipsis;
-    };
+    const fitRow = (line) => fit(line, Math.max(1, caps.width - 1), ellipsis);
     const erase = () => {
         if (drawn === 0)
             return;
@@ -38,14 +28,22 @@ export function createFrame(write, caps) {
         write(out);
         drawn = 0;
     };
+    const paint = (lines) => {
+        erase();
+        lastLines = lines;
+        if (lines.length === 0)
+            return;
+        write(lines.map(fitRow).join("\n"));
+        drawn = lines.length;
+    };
+    // Reflow the live frame at the new width; committed output above is immutable.
+    const unsubscribe = caps.onResize?.(() => paint(lastLines)) ?? null;
     return {
-        render(lines) {
+        render: paint,
+        clear() {
             erase();
-            if (lines.length === 0)
-                return;
-            write(lines.map(fit).join("\n"));
-            drawn = lines.length;
+            lastLines = [];
+            unsubscribe?.();
         },
-        clear: erase,
     };
 }

package/dist/components/fuzzy.js

@@ -1,3 +1,4 @@
+import { fitMiddle } from "../render/layout.js";
 import { resolveTheme } from "../theme/index.js";
 import { createFrame } from "./frame.js";
 import { defaultComponentIO, resolveNonInteractive, } from "./input.js";
@@ -117,7 +118,10 @@ export async function fuzzyFind(items, opts, io = defaultComponentIO()) {
             for (const [i, row] of visible.entries()) {
                 const selected = top + i === cursor;
                 const marker = selected ? t.accent(g.pointer) : " ";
-                const label = highlightMatch(row.label, row.match.positions, t);
+                // Middle-truncate so a long hit keeps its basename at narrow width
+                // (U.12); the match highlight survives when the label fits and is
+                // dropped (plain text) only when it must truncate — identity over decor.
+                const label = fitMiddle(highlightMatch(row.label, row.match.positions, t), Math.max(1, io.caps.width - 2), g.ellipsis);
                 lines.push(`${marker} ${selected ? label : t.muted(label)}`);
             }
             const hidden = ranked.length - visible.length;

package/dist/components/select.js

@@ -1,3 +1,4 @@
+import { fitMiddle } from "../render/layout.js";
 import { resolveTheme } from "../theme/index.js";
 import { createFrame } from "./frame.js";
 import { defaultComponentIO, resolveNonInteractive, } from "./input.js";
@@ -29,7 +30,9 @@ export async function selectList(items, opts = {}, io = defaultComponentIO()) {
         for (const [i, item] of visible.entries()) {
             const selected = top + i === cursor;
             const marker = selected ? t.accent(g.pointer) : " ";
-            const label = toLabel(item);
+            // Middle-truncate the label so a long path keeps its basename (identity)
+            // at narrow width (U.12); reserve the marker + space.
+            const label = fitMiddle(toLabel(item), Math.max(1, io.caps.width - 2), g.ellipsis);
             lines.push(`${marker} ${selected ? label : t.muted(label)}`);
         }
         const hidden = items.length - visible.length;

package/dist/config/schema.d.ts

@@ -291,6 +291,53 @@ export declare const SubagentConfigSchema: z.ZodObject<{
         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,
@@ -1081,6 +1128,35 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             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>;
@@ -1532,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;
@@ -1677,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;