@cruxy/cli 0.24.0 → 0.25.0

package/dist/jobs/manager.js

@@ -0,0 +1,397 @@
+import { runAgent } from "../agent/loop.js";
+import { ApprovalService, classify, serializeGate, } from "../approval/index.js";
+import { CheckpointGate, withCheckpointGate } from "../checkpoint/index.js";
+import { CruxyError, ErrorCode, approvalRequired, jobLimitExceeded, jobNotFound, jobsDisabled, messageOf, } from "../errors/index.js";
+import { Budget, resolveBudget, scopeRegistry, } from "../subagent/index.js";
+import { Workspace } from "../workspace/index.js";
+import { LogBuffer } from "./log-buffer.js";
+import { JobLogRenderer } from "./log-renderer.js";
+import { isTerminal } from "./types.js";
+/** Longest task excerpt kept as a job label (display, not record). */
+const LABEL_MAX = 60;
+/**
+ * Session-scoped background jobs (C.28). The main agent dispatches a job with
+ * `run_in_background`; it runs the SAME agent loop as a subagent but CONCURRENTLY
+ * with the foreground session, off screen (its output goes to a log buffer). A
+ * gated action pauses the job, releases its execution slot, and enqueues an
+ * approval request the foreground human services between turns; on approval the
+ * job re-acquires a slot (with priority) and runs on — its pre- AND post-pause
+ * mutations coalescing under ONE checkpoint. Cancel and session exit kill-tree a
+ * job's process tree (via its cancellation signal), leaving no orphan.
+ *
+ * The manager is session-scoped and dies with the session (NOT a daemon): nothing
+ * here persists a live registry across processes. What survives on disk is a
+ * job's checkpoint set, so `cruxy rollback <id>` still works afterwards.
+ */
+export class JobManager {
+    deps;
+    jobs = new Map();
+    /** In-flight executions, awaited on {@link cancelAll} so teardown completes. */
+    running = new Set();
+    idFactory;
+    now;
+    runAgentFn;
+    seq = 0;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.runAgentFn = deps.runAgentFn ?? runAgent;
+        this.idFactory =
+            deps.idFactory ??
+                (() => `job-${++this.seq}-${Math.random().toString(36).slice(2, 6)}`);
+    }
+    /**
+     * Dispatch a background job (the `run_in_background` seam). Fails loud when the
+     * feature is disabled, when the live-job ceiling is reached, or when a named
+     * root is unknown — all BEFORE the job is registered, so a refused dispatch
+     * leaves no ghost. Returns a view immediately; the job runs asynchronously.
+     */
+    dispatch(spec) {
+        const { config } = this.deps;
+        if (!config.jobs.enabled)
+            throw jobsDisabled();
+        const live = this.liveCount();
+        if (live >= config.jobs.maxJobs) {
+            throw jobLimitExceeded(config.jobs.maxJobs, live);
+        }
+        // Resolve (and validate) the job's scope up front — an unknown root name
+        // throws CRUXY_E_ROOT_UNKNOWN here, which the dispatch tool surfaces to the
+        // model, rather than failing silently inside the background run.
+        const scope = this.jobScope(spec.root);
+        const id = this.idFactory();
+        const checkpoints = config.checkpoint.enabled
+            ? new CheckpointGate({
+                config,
+                primaryRoot: scope.workspace.primary().absPath,
+            })
+            : undefined;
+        const job = {
+            id,
+            spec,
+            label: taskLabel(spec.task),
+            status: "queued",
+            iterations: 0,
+            usage: { input_tokens: 0, output_tokens: 0 },
+            summary: "",
+            logs: new LogBuffer(config.jobs.logBufferLines),
+            controller: new AbortController(),
+            checkpoints,
+            scope,
+            holdsSlot: false,
+        };
+        this.jobs.set(id, job);
+        this.log(job, "out", `dispatched: ${job.label}`);
+        // Fire-and-forget, but TRACKED: cancelAll awaits these so no execution is
+        // left detached at session exit. `execute` never rejects (it maps every
+        // failure onto the job's status), so the catch is purely defensive.
+        const p = this.execute(job)
+            .catch((err) => {
+            job.status = "failed";
+            job.error = `${ErrorCode.Internal}: ${messageOf(err) ?? "job crashed"}`;
+        })
+            .finally(() => this.running.delete(p));
+        this.running.add(p);
+        return this.view(job);
+    }
+    /** Live view of every job this session, dispatch order. */
+    list() {
+        return [...this.jobs.values()].map((j) => this.view(j));
+    }
+    /** One job's view, or undefined if the id is unknown. */
+    get(id) {
+        const job = this.jobs.get(id);
+        return job ? this.view(job) : undefined;
+    }
+    /** One job's full log (for `/logs <id>`). Fails loud on an unknown id. */
+    logs(id) {
+        const job = this.requireJob(id);
+        return {
+            id: job.id,
+            status: job.status,
+            lines: job.logs.snapshot(),
+            dropped: job.logs.dropped,
+        };
+    }
+    /**
+     * Cancel one job: abort its run (kill-tree'ing any in-flight process via the
+     * signal reaching `ctx.signal`) and, if it is paused, withdraw its queued
+     * approval so it stops waiting. A checkpoint it already took SURVIVES for
+     * review/rollback. Fails loud on an unknown id; a no-op on an already-terminal
+     * job (returns false).
+     */
+    cancel(id) {
+        const job = this.requireJob(id);
+        if (isTerminal(job.status))
+            return false;
+        this.abort(job);
+        return true;
+    }
+    /**
+     * Cancel EVERY live job (session exit / teardown) and AWAIT their teardown, so
+     * nothing is left running or orphaned. Returns how many were cancelled — the
+     * caller prints the honest "N job(s) cancelled". Idempotent.
+     */
+    async cancelAll(reason) {
+        let cancelled = 0;
+        for (const job of this.jobs.values()) {
+            if (!isTerminal(job.status))
+                this.log(job, "out", `cancelling: ${reason}`);
+        }
+        for (const job of this.jobs.values()) {
+            if (!isTerminal(job.status)) {
+                this.abort(job);
+                cancelled++;
+            }
+        }
+        // Await every in-flight execution so a caller (session exit) does not race
+        // ahead of the kill-tree teardown.
+        await Promise.allSettled([...this.running]);
+        return cancelled;
+    }
+    /** Jobs that are not yet terminal (queued + running + paused). */
+    liveCount() {
+        let n = 0;
+        for (const job of this.jobs.values())
+            if (!isTerminal(job.status))
+                n++;
+        return n;
+    }
+    /** Whether any job is paused awaiting a foreground approval (drive the drain). */
+    hasPendingApprovals() {
+        return this.deps.approvalQueue.hasPending();
+    }
+    /** Service every pending job approval on the foreground (called between turns). */
+    serviceApprovals() {
+        return this.deps.approvalQueue.serviceAll();
+    }
+    // ── internals ────────────────────────────────────────────────────────────
+    /** Abort a job's run and unblock it if paused (shared by cancel/cancelAll). */
+    abort(job) {
+        job.controller.abort();
+        // If paused on the queue, withdraw with a deny so its `submit` resolves and
+        // the run tears down at its next turn boundary instead of hanging.
+        this.deps.approvalQueue.withdraw(job.id, { allow: false });
+        this.log(job, "out", "cancel requested");
+    }
+    /** Drive one job to completion, mapping every outcome onto its status. */
+    async execute(job) {
+        const signal = job.controller.signal;
+        try {
+            // Wait for an execution permit — a queued job holds none until a slot frees
+            // (the shared cap, contended with subagents). This is the queued→running
+            // gate.
+            await this.deps.semaphore.acquire();
+            job.holdsSlot = true;
+            if (signal.aborted) {
+                job.status = "cancelled";
+                return;
+            }
+            job.status = "running";
+            // ONE undo unit for the WHOLE job, keyed by the job id — begun here and
+            // NEVER again (a pause is not a checkpoint boundary), so pre- and post-pause
+            // mutations coalesce and `cruxy rollback <id>` reverts the whole job.
+            job.checkpoints?.beginRun(job.spec.task, job.id);
+            const result = await this.runAgentFn(this.runArgs(job, signal));
+            job.iterations = result.iterations;
+            job.usage = result.usage;
+            job.summary = lastAssistantText(result.messages);
+            job.status = this.statusFor(result, job);
+            if (job.status === "failed")
+                job.error = this.errorFor(result);
+        }
+        catch (err) {
+            if (signal.aborted) {
+                job.status = "cancelled";
+            }
+            else if (CruxyError.is(err) &&
+                err.code === ErrorCode.ApprovalRequired) {
+                // A gated action with no interactive foreground to service it — the
+                // pinned fail-loud path. The job FAILS with the coded reason; it never
+                // auto-approves.
+                job.status = "failed";
+                job.error = `${err.code}: ${err.title}`;
+            }
+            else {
+                job.status = "failed";
+                job.error = `${ErrorCode.SubagentFailed}: ${messageOf(err) ?? "unknown error"}`;
+            }
+        }
+        finally {
+            if (job.holdsSlot) {
+                this.deps.semaphore.release();
+                job.holdsSlot = false;
+            }
+            this.log(job, "out", `job ${job.status}`);
+        }
+    }
+    /** Build the {@link runAgent} args for a job: scoped registry, budget, ctx. */
+    runArgs(job, signal) {
+        const { deps } = this;
+        const registry = scopeRegistry(deps.parentRegistry, job.spec.tools);
+        const budget = new Budget(resolveBudget(deps.config.subagent.defaultBudget, {
+            ...(job.spec.budget?.maxIterations !== undefined
+                ? { maxIterations: job.spec.budget.maxIterations }
+                : {}),
+            ...(job.spec.budget?.maxTokens !== undefined
+                ? { maxTokens: job.spec.budget.maxTokens }
+                : {}),
+        }));
+        const ctx = {
+            cwd: job.scope.cwd,
+            workspace: job.scope.workspace,
+            config: deps.config,
+            logger: deps.logger,
+            requestApproval: this.makeJobApproval(job),
+            checkpointsActive: Boolean(job.checkpoints),
+            sandbox: deps.sandbox,
+            signal,
+        };
+        const messages = [{ role: "user", content: job.spec.task }];
+        return {
+            messages,
+            provider: deps.provider,
+            registry,
+            config: deps.config,
+            ctx,
+            renderer: new JobLogRenderer((stream, text) => this.log(job, stream, text)),
+            git: deps.git,
+            projectInstructions: deps.projectInstructions,
+            subagent: true,
+            budget,
+            router: deps.router,
+            taskClass: "subagent",
+            signal,
+        };
+    }
+    /**
+     * The job's approval gate — the producer side of the pending-approval queue.
+     * A read-tier action passes freely. A mutate/destructive action with NO
+     * interactive foreground fails loud (never auto-approve, never hang). Otherwise
+     * the job PAUSES: it releases its execution slot (JC-D), enqueues the request
+     * for the foreground human, and blocks. On resolution it re-acquires a slot
+     * with PRIORITY (so it is not starved by work dispatched while it waited) and
+     * returns the decision. The real prompt + this job's checkpoint snapshot happen
+     * inside `finalize` on the foreground, serialized on the shared mutex.
+     */
+    makeJobApproval(job) {
+        const { approvalQueue, semaphore, approvalMutex, foregroundInteractive } = this.deps;
+        const cwd = job.scope.cwd;
+        const interactive = new ApprovalService({
+            cwd,
+            interactive: foregroundInteractive,
+            io: this.deps.promptIO,
+        });
+        // The foreground-serviced decision: the interactive U.3 prompt, wrapped in
+        // THIS job's checkpoint hook, serialized on the SHARED approval mutex — so a
+        // job's prompt/checkpoint serialize against a foreground action's on the same
+        // lock, and the snapshot lands under the job's own gate.
+        const foregroundGate = serializeGate(withCheckpointGate((a) => interactive.requestApproval(a), job.checkpoints, job.scope.workspace), approvalMutex, cwd);
+        return async (action) => {
+            const req = classify(action, cwd);
+            if (req.tier === "read")
+                return { allow: true };
+            if (!foregroundInteractive)
+                throw approvalRequired(req.summary);
+            // Pause: release the slot and enqueue for the foreground human.
+            if (job.holdsSlot) {
+                semaphore.release();
+                job.holdsSlot = false;
+            }
+            job.status = "paused-needs-approval";
+            this.log(job, "out", `paused — needs approval: ${req.summary}`);
+            try {
+                return await approvalQueue.submit({
+                    jobId: job.id,
+                    summary: req.summary,
+                    tier: req.tier,
+                    finalize: () => foregroundGate(action),
+                });
+            }
+            finally {
+                // Resume: re-take a slot with PRIORITY unless the job was cancelled while
+                // paused (in which case the run aborts at its next turn boundary and the
+                // outer finally, seeing holdsSlot=false, does not double-release).
+                if (!job.controller.signal.aborted) {
+                    await semaphore.acquire({ priority: true });
+                    job.holdsSlot = true;
+                    job.status = "running";
+                    this.log(job, "out", "resumed after approval");
+                }
+            }
+        };
+    }
+    /** Resolve a job's scope from an optional root name (fail-loud on unknown). */
+    jobScope(rootName) {
+        if (rootName === undefined) {
+            return { cwd: this.deps.cwd, workspace: this.deps.workspace };
+        }
+        const root = this.deps.workspace.rootByName(rootName); // throws ROOT_UNKNOWN
+        return {
+            cwd: root.absPath,
+            workspace: new Workspace([
+                { name: root.name, absPath: root.absPath, primary: true },
+            ]),
+        };
+    }
+    statusFor(result, job) {
+        if (result.stop === "completed")
+            return "done";
+        if (result.stop === "aborted" || job.controller.signal.aborted) {
+            return "cancelled";
+        }
+        return "failed"; // budget / max_iterations — partial, honestly not "done"
+    }
+    errorFor(result) {
+        const reason = result.stop === "budget"
+            ? (result.stopReason ?? "budget cap reached")
+            : `agent.maxIterations ceiling reached (${this.deps.config.agent.maxIterations})`;
+        return `${ErrorCode.SubagentBudget}: ${reason}`;
+    }
+    requireJob(id) {
+        const job = this.jobs.get(id);
+        if (!job)
+            throw jobNotFound(id);
+        return job;
+    }
+    log(job, stream, text) {
+        job.logs.append({ atMs: this.now(), stream, text });
+    }
+    view(job) {
+        const pending = this.deps.approvalQueue.pendingFor(job.id);
+        return {
+            id: job.id,
+            status: job.status,
+            label: job.label,
+            ...(job.error ? { error: job.error } : {}),
+            iterations: job.iterations,
+            usage: job.usage,
+            ...(pending ? { pendingApproval: pending.summary } : {}),
+        };
+    }
+}
+/** One-line task excerpt for a job label. */
+function taskLabel(task) {
+    const flat = task.replace(/\s+/g, " ").trim();
+    return flat.length > LABEL_MAX ? flat.slice(0, LABEL_MAX - 1) + "…" : flat;
+}
+/** The final assistant text of a run — the job's summary. */
+function lastAssistantText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg.role !== "assistant")
+            continue;
+        if (typeof msg.content === "string") {
+            if (msg.content.trim())
+                return msg.content.trim();
+            continue;
+        }
+        const text = msg.content
+            .filter((block) => block.type === "text")
+            .map((block) => block.text)
+            .join("\n")
+            .trim();
+        if (text)
+            return text;
+    }
+    return "";
+}

package/dist/jobs/types.d.ts

@@ -0,0 +1,81 @@
+import type { Usage } from "@cruxy/sdk";
+import type { LogLine } from "./log-buffer.js";
+/**
+ * Types for session-scoped background jobs (C.28): non-interactive orchestration
+ * the main agent dispatches with `run_in_background`. A job runs the SAME agent
+ * loop as a subagent, but CONCURRENTLY with (and outliving the turn of) the
+ * foreground session — bound to the session's lifetime, nothing survives exit
+ * (NOT a daemon). Its gated actions enqueue approval requests into the one
+ * foreground queue; a paused job releases its execution slot.
+ */
+/**
+ * A job's lifecycle state. Every state is HONEST — a job is `done` only when its
+ * run actually completed, never a fabricated success. Terminal states are `done`,
+ * `failed`, `cancelled`; the rest are live.
+ * - `queued` — dispatched, waiting for an execution slot (the shared cap is full).
+ * - `running` — holding a slot, executing its agent loop.
+ * - `paused-needs-approval` — hit a gated action; its approval is enqueued for a
+ *   foreground human and it has RELEASED its slot until the human decides (JC-D).
+ * - `done` — the run completed.
+ * - `failed` — the run errored, exceeded budget, or hit a no-foreground approval
+ *   wall (`CRUXY_E_APPROVAL_REQUIRED`); `error` carries the coded reason.
+ * - `cancelled` — `cruxy cancel <id>` or session exit stopped it; its process tree
+ *   was kill-tree'd and any checkpoint it took survives for review/rollback.
+ */
+export type JobStatus = "queued" | "running" | "paused-needs-approval" | "done" | "failed" | "cancelled";
+/** The terminal states — a job in one of these will never run again. */
+export declare const TERMINAL_JOB_STATUSES: readonly JobStatus[];
+/** Whether a status is terminal (no further execution). */
+export declare function isTerminal(status: JobStatus): boolean;
+/**
+ * What a background job should do — mirrors the self-contained subtask shape of a
+ * subagent spawn (C.14/C.33). A job starts with NO context beyond `task`.
+ */
+export interface JobSpec {
+    /** The complete, self-contained task the job should perform. */
+    task: string;
+    /**
+     * Tool names to grant, resolved against the parent registry — a job can only
+     * scope DOWN. Omitted → the default read-only set. A job granted write/shell
+     * tools takes real, gated actions in the background.
+     */
+    tools?: readonly string[];
+    /**
+     * The workspace root (by exact name, C.26) this job is confined to. Omitted →
+     * the full session workspace (read-only, or a single-root session).
+     */
+    root?: string;
+    /** Budget overrides, clamped to `subagent.defaultBudget` (never raised). */
+    budget?: {
+        maxIterations?: number;
+        maxTokens?: number;
+    };
+}
+/**
+ * A read-only view of one job for `cruxy jobs` / the dispatch tool's result /
+ * tests. Never exposes the live control handles (abort controller, checkpoint
+ * gate) — those stay inside the manager.
+ */
+export interface JobView {
+    /** Stable, session-unique id (also the checkpoint run id for `cruxy rollback`). */
+    id: string;
+    status: JobStatus;
+    /** One-line task excerpt (for listings). */
+    label: string;
+    /** Present on `failed`: the coded, actionable reason. */
+    error?: string;
+    /** Model turns consumed so far. */
+    iterations: number;
+    /** Token usage accumulated so far. */
+    usage: Usage;
+    /** A one-line summary of what's pending, when `paused-needs-approval`. */
+    pendingApproval?: string;
+}
+/** The full log of one job, for `cruxy logs <id>`. */
+export interface JobLog {
+    id: string;
+    status: JobStatus;
+    lines: LogLine[];
+    /** How many earlier lines rolled off the ring buffer (0 when none). */
+    dropped: number;
+}

package/dist/jobs/types.js

@@ -0,0 +1,10 @@
+/** The terminal states — a job in one of these will never run again. */
+export const TERMINAL_JOB_STATUSES = [
+    "done",
+    "failed",
+    "cancelled",
+];
+/** Whether a status is terminal (no further execution). */
+export function isTerminal(status) {
+    return TERMINAL_JOB_STATUSES.includes(status);
+}

package/dist/subagent/orchestrator.d.ts

@@ -6,6 +6,7 @@ import type { Router } from "../routing/index.js";
 import type { ApproveAction, ToolContext, ToolRegistry } from "../tools/index.js";
 import type { SandboxService } from "../sandbox/index.js";
 import { Workspace } from "../workspace/index.js";
+import { Semaphore } from "./semaphore.js";
 import type { SubagentResult, SubagentSpec } from "./types.js";
 /**
  * Everything a spawn needs from the surrounding session, injected by the
@@ -60,6 +61,14 @@ export interface SubagentOrchestratorDeps {
      * same shared checkpoint gate, those writes join the run's one set (⚖︎JC-δ).
      */
     checkpointsActive?: boolean;
+    /**
+     * The ONE shared execution semaphore (C.28). When set, parallel fan-out draws
+     * permits from THIS instance — the same one background jobs use — so the
+     * `subagent.maxConcurrency` cap bounds subagents AND jobs COMBINED, never one
+     * cap each. Omitted → the orchestrator constructs its own (C.33 behaviour,
+     * used by tests that exercise the orchestrator in isolation).
+     */
+    executionSemaphore?: Semaphore;
 }
 /**
  * Spawns subagents (C.14): the existing agent loop re-driven over isolated

package/dist/subagent/orchestrator.js

@@ -32,7 +32,12 @@ export class SubagentOrchestrator {
     sem;
     constructor(deps) {
         this.deps = deps;
-        this.sem = new Semaphore(deps.config.subagent.maxConcurrency);
+        // Share the session's ONE execution semaphore when injected (C.28) so
+        // subagents and background jobs contend for the same permits; fall back to a
+        // private one at the same cap when running the orchestrator in isolation.
+        this.sem =
+            deps.executionSemaphore ??
+                new Semaphore(deps.config.subagent.maxConcurrency);
     }
     /** Live/queued fan-out slots (inspection/tests): proves the global cap holds. */
     get concurrency() {

package/dist/subagent/semaphore.d.ts

@@ -1,27 +1,56 @@
 /**
- * A counting semaphore (C.33): bounds how many subagent runs execute at once.
+ * A counting semaphore (C.33): bounds how many agent runs execute at once.
  * FIFO — waiters are served in arrival order, so a fan-out's results stay
  * dispatch-order-fair — and the permit is handed directly from a releaser to
  * the next waiter, so the live count never transiently exceeds the cap.
  *
- * Used as the ONE shared bound on parallel fan-out. Parallel dispatch happens at
- * depth 0 only (the `spawn_subagents` tool is never granted to a child), and a
- * permit is held for a child's whole lifetime — including any *sequential*
- * nested spawn beneath it, which is deliberately un-permitted. Because no permit
- * holder ever blocks trying to acquire a second permit, the semaphore cannot be
- * part of a wait cycle: it is deadlock-free by construction (see the C.33 design
- * doc's deadlock argument).
+ * Used as the ONE shared bound on all concurrent execution: parallel subagent
+ * fan-out (C.33) AND background jobs (C.28) draw permits from the SAME instance,
+ * so `subagent.maxConcurrency` caps their COMBINED live count — never one cap
+ * per subsystem. Parallel dispatch happens at depth 0 only (the `spawn_subagents`
+ * tool is never granted to a child), and a permit is held for a child's whole
+ * lifetime — including any *sequential* nested spawn beneath it, which is
+ * deliberately un-permitted. Because no permit holder ever blocks trying to
+ * acquire a second permit, the semaphore cannot be part of a wait cycle: it is
+ * deadlock-free by construction (see the C.33 design doc's deadlock argument).
+ *
+ * C.28 adds a PRIORITY lane to {@link acquire}. A background job that pauses to
+ * await a human approval RELEASES its permit (JC-D: a job blocked on a human is
+ * not using compute, and holding the slot would deadlock the cap if N jobs all
+ * paused). When the human approves, the job re-acquires with `priority: true` so
+ * it jumps ahead of newly-dispatched work — a resumed job never starves behind a
+ * fresh fan-out that filled the queue while it waited. Normal (non-priority)
+ * waiters keep strict FIFO among themselves, so C.33's dispatch-order fairness is
+ * unchanged for everything that does not pause.
  */
+export interface AcquireOptions {
+    /**
+     * Serve this waiter ahead of all non-priority waiters (still FIFO among
+     * priority waiters). Used by a resumed background job re-acquiring its slot
+     * after an approval, so it is not starved by work dispatched while it paused.
+     */
+    priority?: boolean;
+}
 export declare class Semaphore {
     private permits;
-    private readonly queue;
+    /** Waiters that take the next permit ahead of {@link normal} (FIFO within). */
+    private readonly priority;
+    /** Ordinary waiters, served strictly FIFO after any priority waiters. */
+    private readonly normal;
     constructor(permits: number);
     /** Run `fn` while holding one permit; the permit is released even if it throws. */
     run<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Take one permit, waiting if none is free. Resolves immediately when a permit
+     * is available; otherwise enqueues onto the priority or normal lane and resolves
+     * when {@link release} hands it a permit. Callers that acquire directly (a
+     * paused/resumed job) MUST call {@link release} exactly once per acquire.
+     */
+    acquire(opts?: AcquireOptions): Promise<void>;
+    /** Return one permit — handed straight to the next waiter (priority first). */
+    release(): void;
     /** Permits currently available (inspection/tests). */
     get available(): number;
     /** Callers currently blocked waiting for a permit (inspection/tests). */
     get waiting(): number;
-    private acquire;
-    private release;
 }

package/dist/subagent/semaphore.js

@@ -1,20 +1,9 @@
-/**
- * A counting semaphore (C.33): bounds how many subagent runs execute at once.
- * FIFO — waiters are served in arrival order, so a fan-out's results stay
- * dispatch-order-fair — and the permit is handed directly from a releaser to
- * the next waiter, so the live count never transiently exceeds the cap.
- *
- * Used as the ONE shared bound on parallel fan-out. Parallel dispatch happens at
- * depth 0 only (the `spawn_subagents` tool is never granted to a child), and a
- * permit is held for a child's whole lifetime — including any *sequential*
- * nested spawn beneath it, which is deliberately un-permitted. Because no permit
- * holder ever blocks trying to acquire a second permit, the semaphore cannot be
- * part of a wait cycle: it is deadlock-free by construction (see the C.33 design
- * doc's deadlock argument).
- */
 export class Semaphore {
     permits;
-    queue = [];
+    /** Waiters that take the next permit ahead of {@link normal} (FIFO within). */
+    priority = [];
+    /** Ordinary waiters, served strictly FIFO after any priority waiters. */
+    normal = [];
     constructor(permits) {
         // A non-positive cap would wedge every run; clamp to at least 1.
         this.permits = Math.max(1, Math.floor(permits));
@@ -29,23 +18,23 @@ export class Semaphore {
             this.release();
         }
     }
-    /** Permits currently available (inspection/tests). */
-    get available() {
-        return this.permits;
-    }
-    /** Callers currently blocked waiting for a permit (inspection/tests). */
-    get waiting() {
-        return this.queue.length;
-    }
-    acquire() {
+    /**
+     * Take one permit, waiting if none is free. Resolves immediately when a permit
+     * is available; otherwise enqueues onto the priority or normal lane and resolves
+     * when {@link release} hands it a permit. Callers that acquire directly (a
+     * paused/resumed job) MUST call {@link release} exactly once per acquire.
+     */
+    acquire(opts = {}) {
         if (this.permits > 0) {
             this.permits--;
             return Promise.resolve();
         }
-        return new Promise((resolve) => this.queue.push(resolve));
+        const lane = opts.priority ? this.priority : this.normal;
+        return new Promise((resolve) => lane.push(resolve));
     }
+    /** Return one permit — handed straight to the next waiter (priority first). */
     release() {
-        const next = this.queue.shift();
+        const next = this.priority.shift() ?? this.normal.shift();
         // Hand the permit straight to the next waiter (never bump the count above
         // the cap); only when nobody waits does the count grow back.
         if (next)
@@ -53,4 +42,12 @@ export class Semaphore {
         else
             this.permits++;
     }
+    /** Permits currently available (inspection/tests). */
+    get available() {
+        return this.permits;
+    }
+    /** Callers currently blocked waiting for a permit (inspection/tests). */
+    get waiting() {
+        return this.priority.length + this.normal.length;
+    }
 }