@cruxy/cli 0.24.0 → 0.25.0

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/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;

package/dist/config/schema.js

@@ -204,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,
@@ -490,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({}),

package/dist/errors/constructors.d.ts

@@ -219,6 +219,24 @@ export declare function subagentScopeOverlap(conflicts: readonly ScopeConflict[]
  * 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

@@ -792,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

@@ -173,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

@@ -193,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
@@ -304,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/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;
+}