@cruxy/cli 0.24.0 → 0.26.0

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

package/dist/jobs/approval-queue.js

@@ -0,0 +1,96 @@
+export class ApprovalQueue {
+    queue = [];
+    seq = 0;
+    /**
+     * 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) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({
+                id: `pa-${++this.seq}`,
+                jobId: sub.jobId,
+                summary: sub.summary,
+                tier: sub.tier,
+                finalize: sub.finalize,
+                resolve,
+                reject,
+                settled: false,
+            });
+        });
+    }
+    /** Whether any request is waiting to be serviced. */
+    hasPending() {
+        return this.queue.length > 0;
+    }
+    /** Count of requests waiting. */
+    get size() {
+        return this.queue.length;
+    }
+    /** Read-only snapshot of every pending request, FIFO order. */
+    pending() {
+        return this.queue.map((e) => ({
+            id: e.id,
+            jobId: e.jobId,
+            summary: e.summary,
+            tier: e.tier,
+        }));
+    }
+    /** The pending request for one job (a job has at most one at a time), if any. */
+    pendingFor(jobId) {
+        return this.pending().find((p) => p.jobId === jobId);
+    }
+    /**
+     * 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.
+     */
+    async serviceAll() {
+        let serviced = 0;
+        for (;;) {
+            const entry = this.queue.shift();
+            if (!entry)
+                break;
+            if (entry.settled)
+                continue; // withdrawn between snapshot and here
+            try {
+                const decision = await entry.finalize();
+                this.settle(entry, () => entry.resolve(decision));
+            }
+            catch (err) {
+                this.settle(entry, () => entry.reject(err));
+            }
+            serviced++;
+        }
+        return serviced;
+    }
+    /**
+     * 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, decision) {
+        const entry = this.queue.find((e) => e.jobId === jobId && !e.settled);
+        if (!entry)
+            return false;
+        const i = this.queue.indexOf(entry);
+        if (i !== -1)
+            this.queue.splice(i, 1);
+        this.settle(entry, () => entry.resolve(decision));
+        return true;
+    }
+    /** Settle an entry exactly once (double-settle is a defensive no-op). */
+    settle(entry, run) {
+        if (entry.settled)
+            return;
+        entry.settled = true;
+        run();
+    }
+}

package/dist/jobs/dispatch-tool.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import type { Tool } from "../tools/index.js";
+import type { JobManager } from "./manager.js";
+/**
+ * The `run_in_background` tool (C.28): the agent-facing seam for dispatching a
+ * background job. Unlike `spawn_subagent`, it does NOT block — it returns a job
+ * id immediately and the job runs CONCURRENTLY with the rest of the turn and the
+ * session. The agent uses it for long-running, self-contained work it does not
+ * want to wait on inline; the human watches it with `/jobs` and `/logs`, and any
+ * side effect the job takes still requires a foreground approval.
+ */
+export declare const RUN_IN_BACKGROUND_TOOL_NAME = "run_in_background";
+declare const parameters: z.ZodObject<{
+    task: z.ZodString;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString, "atleastone">>;
+    root: z.ZodOptional<z.ZodString>;
+    maxIterations: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    task: string;
+    root?: string | undefined;
+    maxTokens?: number | undefined;
+    maxIterations?: number | undefined;
+    tools?: [string, ...string[]] | undefined;
+}, {
+    task: string;
+    root?: string | undefined;
+    maxTokens?: number | undefined;
+    maxIterations?: number | undefined;
+    tools?: [string, ...string[]] | undefined;
+}>;
+/** Build the `run_in_background` tool bound to the session's job manager. */
+export declare function makeRunInBackgroundTool(manager: JobManager): Tool<typeof parameters>;
+export {};

package/dist/jobs/dispatch-tool.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { CruxyError } from "../errors/index.js";
+/**
+ * The `run_in_background` tool (C.28): the agent-facing seam for dispatching a
+ * background job. Unlike `spawn_subagent`, it does NOT block — it returns a job
+ * id immediately and the job runs CONCURRENTLY with the rest of the turn and the
+ * session. The agent uses it for long-running, self-contained work it does not
+ * want to wait on inline; the human watches it with `/jobs` and `/logs`, and any
+ * side effect the job takes still requires a foreground approval.
+ */
+export const RUN_IN_BACKGROUND_TOOL_NAME = "run_in_background";
+const parameters = z.object({
+    task: z
+        .string()
+        .min(1)
+        .describe("The complete, self-contained task for the background job. It starts with " +
+        "NO context beyond this text — include every path, constraint, and expected " +
+        "output. The job runs concurrently; you get a job id back immediately."),
+    tools: z
+        .array(z.string().min(1))
+        .nonempty()
+        .optional()
+        .describe("Tool names to grant the job — a subset of your own. Omit for the default " +
+        "read-only set. Grant write/shell tools only when the job needs them; every " +
+        "side effect still pauses for a foreground human approval."),
+    root: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Workspace root name (from your Environment) to confine the job's writes to. " +
+        "Omit for a read-only job or a single-root workspace."),
+    maxIterations: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Cap on the job's model turns (clamped to the configured ceiling)."),
+    maxTokens: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Cap on the job's total tokens (clamped to the configured ceiling)."),
+});
+/** Build the `run_in_background` tool bound to the session's job manager. */
+export function makeRunInBackgroundTool(manager) {
+    return {
+        name: RUN_IN_BACKGROUND_TOOL_NAME,
+        description: "Dispatch a self-contained task to run as a BACKGROUND JOB, concurrently with " +
+            "the rest of this session. Returns a job id immediately (non-blocking) — the " +
+            "job runs on its own while you continue. Use it for long or independent work " +
+            "you don't need to wait on inline (e.g. \"run the full test suite and fix any " +
+            "failures\"). The job's output goes to a log (the user reads it with /logs); any " +
+            "file/shell action it takes pauses for the user's approval. For a subtask whose " +
+            "RESULT you need before continuing, use spawn_subagent (which blocks) instead.",
+        parameters,
+        async execute(input) {
+            const spec = {
+                task: input.task,
+                ...(input.tools ? { tools: input.tools } : {}),
+                ...(input.root !== undefined ? { root: input.root } : {}),
+                budget: {
+                    ...(input.maxIterations !== undefined
+                        ? { maxIterations: input.maxIterations }
+                        : {}),
+                    ...(input.maxTokens !== undefined
+                        ? { maxTokens: input.maxTokens }
+                        : {}),
+                },
+            };
+            let view;
+            try {
+                view = manager.dispatch(spec);
+            }
+            catch (err) {
+                // Disabled / job-limit / unknown-root are the model's to correct — feed
+                // the coded, actionable message back as a tool error, never a stack.
+                if (CruxyError.is(err)) {
+                    return {
+                        ok: false,
+                        error: `${err.code}: ${err.title}${err.cause ? ` — ${err.cause}` : ""}`,
+                    };
+                }
+                throw err;
+            }
+            return {
+                ok: true,
+                output: JSON.stringify({
+                    jobId: view.id,
+                    status: view.status,
+                    note: "dispatched — runs in the background; check with /jobs and /logs",
+                }),
+            };
+        },
+    };
+}

package/dist/jobs/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./log-buffer.js";
+export * from "./log-renderer.js";
+export * from "./approval-queue.js";
+export * from "./manager.js";
+export * from "./dispatch-tool.js";

package/dist/jobs/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./log-buffer.js";
+export * from "./log-renderer.js";
+export * from "./approval-queue.js";
+export * from "./manager.js";
+export * from "./dispatch-tool.js";

package/dist/jobs/log-buffer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A bounded ring buffer of a background job's log lines (C.28). A job runs
+ * non-interactively, so its progress isn't on screen — `cruxy logs <id>` reads
+ * it back here. Bounded so a chatty job cannot grow memory without limit: once
+ * `capacity` lines are held, the oldest roll off. When anything is dropped the
+ * buffer records how many, so a reader is never misled into thinking a truncated
+ * tail is the whole story (`cruxy logs` prints an honest "… N earlier lines").
+ */
+export interface LogLine {
+    /** Milliseconds since the job started (monotonic, injected — never wall clock
+     * inside the buffer, so it stays deterministic and testable). */
+    atMs: number;
+    /** `out` for normal progress, `err` for diagnostics/failures. */
+    stream: "out" | "err";
+    /** The line text (no trailing newline). */
+    text: string;
+}
+export declare class LogBuffer {
+    private readonly capacity;
+    private readonly lines;
+    private droppedCount;
+    constructor(capacity: number);
+    /** Append a line, rolling the oldest off (and counting it) when at capacity. */
+    append(line: LogLine): void;
+    /** The retained lines, oldest-first (a copy — callers never mutate the buffer). */
+    snapshot(): LogLine[];
+    /** How many lines rolled off the front (0 when nothing was dropped). */
+    get dropped(): number;
+    /** Lines currently retained. */
+    get size(): number;
+}

package/dist/jobs/log-buffer.js

@@ -0,0 +1,30 @@
+export class LogBuffer {
+    capacity;
+    lines = [];
+    droppedCount = 0;
+    constructor(capacity) {
+        // A non-positive capacity would drop everything; clamp to at least 1 so a
+        // misconfigured buffer still shows the most recent line.
+        this.capacity = Math.max(1, Math.floor(capacity));
+    }
+    /** Append a line, rolling the oldest off (and counting it) when at capacity. */
+    append(line) {
+        this.lines.push(line);
+        while (this.lines.length > this.capacity) {
+            this.lines.shift();
+            this.droppedCount++;
+        }
+    }
+    /** The retained lines, oldest-first (a copy — callers never mutate the buffer). */
+    snapshot() {
+        return [...this.lines];
+    }
+    /** How many lines rolled off the front (0 when nothing was dropped). */
+    get dropped() {
+        return this.droppedCount;
+    }
+    /** Lines currently retained. */
+    get size() {
+        return this.lines.length;
+    }
+}

package/dist/jobs/log-renderer.d.ts

@@ -0,0 +1,32 @@
+import { type Theme } from "../theme/index.js";
+import type { RenderCapabilities, StreamRenderer, ToolLifecycleEvent } from "../render/index.js";
+/**
+ * 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 declare class JobLogRenderer implements StreamRenderer {
+    private readonly sink;
+    readonly caps: RenderCapabilities;
+    readonly theme: Theme;
+    private pending;
+    constructor(sink: (stream: "out" | "err", text: string) => void);
+    beginTurn(): void;
+    write(delta: string): void;
+    endSegment(): void;
+    note(text: string): void;
+    toolLifecycle(event: ToolLifecycleEvent): void;
+    endTurn(): void;
+    preview(): void;
+    status(): void;
+    setPhase(): void;
+    progress(): void;
+    promptResolved(): void;
+    close(): void;
+}