@cruxy/cli 0.24.0 → 0.26.0

package/dist/jobs/log-renderer.js

@@ -0,0 +1,70 @@
+import { themeForColor } from "../theme/index.js";
+/** Non-terminal capabilities: a background job renders to NOTHING on screen. */
+const OFFSCREEN_CAPS = {
+    tty: false,
+    color: false,
+    cursor: false,
+    spinner: false,
+    reducedMotion: true,
+    screenReader: false,
+    unicode: true,
+    width: 80,
+};
+/**
+ * A {@link StreamRenderer} for a background job (C.28) that captures activity into
+ * the job's log buffer and writes NOTHING to any terminal — a job runs
+ * non-interactively, off screen, and its foreground session owns the terminal.
+ * `cruxy logs <id>` (a REPL `/logs`) reads back what was captured here.
+ *
+ * Assistant text is accumulated and flushed a line at a time on `endSegment`;
+ * committed chrome notes and tool-call completions are captured verbatim. The
+ * live-region methods (status, phase, progress, prompt-resolved) are dropped —
+ * transient decor has no meaning in an append-only log.
+ */
+export class JobLogRenderer {
+    sink;
+    caps = OFFSCREEN_CAPS;
+    theme = themeForColor(false);
+    pending = "";
+    constructor(sink) {
+        this.sink = sink;
+    }
+    beginTurn() {
+        this.pending = "";
+    }
+    write(delta) {
+        this.pending += delta;
+        // Flush any complete lines immediately; keep the trailing partial line.
+        const nl = this.pending.lastIndexOf("\n");
+        if (nl === -1)
+            return;
+        const complete = this.pending.slice(0, nl);
+        this.pending = this.pending.slice(nl + 1);
+        for (const line of complete.split("\n"))
+            this.sink("out", line);
+    }
+    endSegment() {
+        if (this.pending.trim())
+            this.sink("out", this.pending.trimEnd());
+        this.pending = "";
+    }
+    note(text) {
+        this.sink("out", text);
+    }
+    toolLifecycle(event) {
+        if (event.event !== "end")
+            return; // only the committed outcome is log-worthy
+        const mark = event.ok ? "ok" : "fail";
+        this.sink(event.ok ? "out" : "err", `[${mark}] ${event.label}`);
+    }
+    endTurn() {
+        this.endSegment();
+    }
+    // Transient decor / previews have no place in an append-only job log.
+    preview() { }
+    status() { }
+    setPhase() { }
+    progress() { }
+    promptResolved() { }
+    close() { }
+}

package/dist/jobs/manager.d.ts

@@ -0,0 +1,139 @@
+import type { Provider } from "@cruxy/sdk";
+import { runAgent } from "../agent/loop.js";
+import { type ApprovalMutex, type PromptIO } from "../approval/index.js";
+import type { CruxyConfig } from "../config/index.js";
+import type { Router } from "../routing/index.js";
+import type { SandboxService } from "../sandbox/index.js";
+import { Semaphore } from "../subagent/index.js";
+import type { ToolRegistry } from "../tools/index.js";
+import type { logger as Logger } from "../utils/logger.js";
+import { Workspace } from "../workspace/index.js";
+import { ApprovalQueue } from "./approval-queue.js";
+import type { JobLog, JobSpec, JobView } from "./types.js";
+/**
+ * Everything the manager needs from the surrounding session, injected by the
+ * session factory. The SHARED members are the crux of C.28's "one system, not
+ * two": `semaphore`, `approvalQueue`, and `approvalMutex` are the SAME instances
+ * the foreground loop and subagents use, so a job contends for the one execution
+ * cap and serializes its prompts/checkpoints on the one mutex — never a parallel
+ * universe with its own limits.
+ */
+export interface JobManagerDeps {
+    config: CruxyConfig;
+    provider: Provider;
+    router?: Router;
+    /** The parent's registry — the ceiling every job's tool scope derives from. */
+    parentRegistry: ToolRegistry;
+    cwd: string;
+    workspace: Workspace;
+    logger: typeof Logger;
+    git?: {
+        branch: string;
+        dirty: boolean;
+    } | null;
+    projectInstructions?: string | null;
+    sandbox?: SandboxService;
+    /** The ONE execution semaphore, shared with subagents (JC-D, the shared cap). */
+    semaphore: Semaphore;
+    /** The ONE foreground pending-approval queue jobs produce onto. */
+    approvalQueue: ApprovalQueue;
+    /** The ONE approval mutex — job prompts/checkpoints serialize on it. */
+    approvalMutex: ApprovalMutex;
+    /**
+     * Whether an interactive foreground exists to service the queue. FALSE (a
+     * one-shot / piped run) means a job's gated action fails loud with
+     * `CRUXY_E_APPROVAL_REQUIRED` — it never auto-approves and never hangs on a
+     * human who will never come.
+     */
+    foregroundInteractive: boolean;
+    /** The shared prompt I/O used when the foreground services a job's request. */
+    promptIO: PromptIO;
+    /** Test seam: the loop driver. Defaults to the real {@link runAgent}. */
+    runAgentFn?: typeof runAgent;
+    /** Test seam: deterministic job ids. Defaults to `job-<seq>-<rand>`. */
+    idFactory?: () => string;
+    /** Test seam: log-line clock (ms). Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * 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 declare class JobManager {
+    private readonly deps;
+    private readonly jobs;
+    /** In-flight executions, awaited on {@link cancelAll} so teardown completes. */
+    private readonly running;
+    private readonly idFactory;
+    private readonly now;
+    private readonly runAgentFn;
+    private seq;
+    constructor(deps: JobManagerDeps);
+    /**
+     * 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: JobSpec): JobView;
+    /** Live view of every job this session, dispatch order. */
+    list(): JobView[];
+    /** One job's view, or undefined if the id is unknown. */
+    get(id: string): JobView | undefined;
+    /** One job's full log (for `/logs <id>`). Fails loud on an unknown id. */
+    logs(id: string): JobLog;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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.
+     */
+    cancelAll(reason: string): Promise<number>;
+    /** Jobs that are not yet terminal (queued + running + paused). */
+    liveCount(): number;
+    /** Whether any job is paused awaiting a foreground approval (drive the drain). */
+    hasPendingApprovals(): boolean;
+    /** Service every pending job approval on the foreground (called between turns). */
+    serviceApprovals(): Promise<number>;
+    /** Abort a job's run and unblock it if paused (shared by cancel/cancelAll). */
+    private abort;
+    /** Drive one job to completion, mapping every outcome onto its status. */
+    private execute;
+    /** Build the {@link runAgent} args for a job: scoped registry, budget, ctx. */
+    private runArgs;
+    /**
+     * 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.
+     */
+    private makeJobApproval;
+    /** Resolve a job's scope from an optional root name (fail-loud on unknown). */
+    private jobScope;
+    private statusFor;
+    private errorFor;
+    private requireJob;
+    private log;
+    private view;
+}

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;
+}