@cruxy/cli 1.9.0 → 1.11.0

package/dist/jobs/manager.js

@@ -1,15 +1,47 @@
 import { runAgent } from "../agent/loop.js";
-import { ApprovalService, classify, serializeGate, } from "../approval/index.js";
+import { ApprovalService, classify, InteractivePolicy, serializeGate, SessionAllowlist, } from "../approval/index.js";
 import { CheckpointGate, withCheckpointGate } from "../checkpoint/index.js";
-import { CruxyError, ErrorCode, approvalRequired, jobLimitExceeded, jobNotFound, jobsDisabled, messageOf, } from "../errors/index.js";
+import { compactTokens } from "../render/units.js";
+import { CruxyError, ErrorCode, approvalRequired, jobLimitExceeded, jobNotFound, jobsDisabled, messageOf, poolDenial, sessionBudgetExhausted, } from "../errors/index.js";
+import { resolveTaskModel } from "../routing/index.js";
+import { UNRESOLVED_TIER } from "../budget/index.js";
+import { UsageCollector } from "../usage/index.js";
 import { Budget, resolveBudget } from "../agent/budget.js";
 import { scopeRegistry } from "../subagent/index.js";
 import { Workspace } from "../workspace/index.js";
 import { LogBuffer } from "./log-buffer.js";
+import { JobLogWriter } from "./log-store.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;
+/**
+ * THE ADMISSION FLOOR, in whole requests' worth of fixed payload (cli#245).
+ *
+ * `Budget.exceeded` is checked BEFORE each model turn against the run's
+ * cumulative tokens, so a job's first request always goes out whatever its
+ * ceiling is: at iteration 0 the usage is zero and no cap can trip. A ceiling
+ * the pool narrowed down to a few hundred tokens therefore buys exactly one
+ * request — the system prompt and the whole tool catalogue re-sent, real
+ * weighted tokens drawn from a window that is already refusing — and then stops
+ * the run at the next boundary with `token cap reached`, which `statusFor` maps
+ * to `failed`. The job dispatches, the model is told it started, and it dies a
+ * second later having produced nothing and spent something.
+ *
+ * TWO, not one, and `context.reserveTokens` (4500 by default) is the unit
+ * because it is the figure this repo already keeps for exactly this quantity:
+ * "the built system prompt plus the default tool catalogue". One request's worth
+ * buys a job a single model turn it cannot act on — it can call a tool and never
+ * see the result. Two is the smallest ceiling under which a job can complete one
+ * act-and-report cycle, which is the least a background job can do and still be
+ * worth the tokens. It is a FLOOR and not a promise: input is re-sent every
+ * turn, so two turns cost more than twice the fixed payload.
+ *
+ * Derived from config rather than a literal, so it tracks the prompt: a build
+ * whose catalogue grows raises the floor with it. A config that sets
+ * `reserveTokens` to 0 states that there is no fixed payload, and floors nothing.
+ */
+const MIN_JOB_REQUESTS = 2;
 /**
  * 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
@@ -32,6 +64,8 @@ export class JobManager {
     idFactory;
     now;
     runAgentFn;
+    /** The last pool denial a job died on, until the foreground takes it. */
+    poolDenied;
     seq = 0;
     constructor(deps) {
         this.deps = deps;
@@ -43,9 +77,21 @@ export class JobManager {
     }
     /**
      * 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.
+     * feature is disabled, when the live-job ceiling is reached, when a named
+     * root is unknown, or when the session's weighted budget will not cover the
+     * job — all BEFORE the job is registered, so a refused dispatch leaves no
+     * ghost. Returns a view immediately; the job runs asynchronously.
+     *
+     * ADMISSION HAPPENS HERE, NOT IN `execute` (cli#245). A queued job can sit
+     * behind the shared semaphore for a long time, so "does it fit now" and "does
+     * it fit when it runs" are genuinely different questions when the pool is
+     * moving — and this is the only one of the two the model can be told the
+     * answer to. `dispatch` is synchronous and already throws three coded
+     * refusals that `dispatch-tool.ts` converts into a tool error; a budget
+     * refusal is that same shape, needing no new mechanism. `execute` has no
+     * error channel back to the model at all — only `job.status`, read by a human
+     * later — and by then the turn that dispatched has long returned, having
+     * already been told the job started.
      */
     dispatch(spec) {
         const { config } = this.deps;
@@ -58,7 +104,13 @@ export class JobManager {
         // 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.
+        //
+        // Before the budget check, deliberately, and for the reason the fan-out
+        // seam orders its two checks the same way: a job naming a root that does
+        // not exist is MALFORMED, and answering it with "your budget is used up"
+        // would report a ceiling instead of the typo.
         const scope = this.jobScope(spec.root);
+        const limits = this.admit(spec);
         const id = this.idFactory();
         const checkpoints = config.checkpoint.enabled
             ? new CheckpointGate({
@@ -75,9 +127,11 @@ export class JobManager {
             usage: { input_tokens: 0, output_tokens: 0 },
             summary: "",
             logs: new LogBuffer(config.jobs.logBufferLines),
+            writer: this.makeWriter(id, taskLabel(spec.task)),
             controller: new AbortController(),
             checkpoints,
             scope,
+            limits,
             holdsSlot: false,
         };
         this.jobs.set(id, job);
@@ -177,6 +231,14 @@ export class JobManager {
     /** Drive one job to completion, mapping every outcome onto its status. */
     async execute(job) {
         const signal = job.controller.signal;
+        // Per-request usage for THIS job, collected exactly as the parent's turn and
+        // a subagent collect their own. Needed rather than `result.usage` for two
+        // reasons: the weighted arithmetic is per-tier, and a run that THREW has no
+        // result at all while still having spent whatever it spent before it died.
+        // Origin `"job"` on every entry (cli#244): this record is published to the
+        // store in its own right, so its entries have to say what they were.
+        const usage = new UsageCollector(undefined, "job");
+        const startedAt = new Date().toISOString();
         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
@@ -192,7 +254,7 @@ export class JobManager {
             // 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));
+            const result = await this.runAgentFn(this.runArgs(job, signal, usage));
             job.iterations = result.iterations;
             job.usage = result.usage;
             job.summary = lastAssistantText(result.messages);
@@ -213,8 +275,31 @@ export class JobManager {
                 job.error = `${err.code}: ${err.title}`;
             }
             else {
+                // THE WEIGHTED POOL REFUSED THIS JOB (429 `budget_exhausted`), and it is
+                // not a per-job outcome (cli#245). Two things used to be lost here, and
+                // they are the same two the fan-out seam recovered in cli#243.
+                //
+                // First the FACTS: `messageOf` flattened the typed error to a string, so
+                // `window`, `resetAt` and `miraAvailable` went with it — the last of
+                // which is the only one that unblocks someone now rather than telling
+                // them when to come back — and a job that died on a 429 read like any
+                // other failure in `/jobs`.
+                //
+                // Second the AUDIENCE. A pool denial is a statement about a denominator
+                // this job shares with the foreground turn, so the foreground is
+                // entitled to it: without the latch the job dies quietly off-screen and
+                // the user walks into their own refusal on the next turn, having been
+                // told nothing. It is the same "N denials for one fact" argument #243
+                // made across siblings, carried across the job/foreground boundary.
+                const denial = poolDenial(err);
                 job.status = "failed";
-                job.error = `${ErrorCode.SubagentFailed}: ${messageOf(err) ?? "unknown error"}`;
+                job.error = denial
+                    ? denialLine(denial)
+                    : `${ErrorCode.SubagentFailed}: ${messageOf(err) ?? "unknown error"}`;
+                if (denial) {
+                    this.poolDenied = denial;
+                    this.abortSiblings(job, denial);
+                }
             }
         }
         finally {
@@ -222,21 +307,99 @@ export class JobManager {
                 this.deps.semaphore.release();
                 job.holdsSlot = false;
             }
+            // JOB SPEND IS SESSION SPEND (cli#245), and in the `finally` because the
+            // tokens are spent on every path out of here — a job that failed, was
+            // cancelled at session exit, or died on a 429 still drew whatever it drew
+            // before it stopped. Without this the admission check above reads a
+            // numerator its own dispatches never move, and a job running across an
+            // idle period stays invisible to `/budget` for the rest of the session.
+            //
+            // AND NOW ALSO WRITTEN TO THE USAGE STORE (cli#244 answered the question
+            // this call site used to defer). One record, handed to both sinks, so
+            // `/budget` and `/usage` can never disagree about what this job drew.
+            //
+            // `job.id` is the run id — stable, already unique, and the thing the user
+            // saw in `/jobs`, so a record in the store can be traced back to the job
+            // that made it rather than to an anonymous UUID.
+            //
+            // The session id is read HERE rather than at construction: see the note on
+            // `sessionId`. Without it the record persists and then hides from every
+            // session-scoped read of the very store it is in.
+            const record = usage.toRecord(job.id, this.deps.sessionId?.(), startedAt);
+            this.deps.budget?.record(record);
+            // Empty records are not published. A job that was cancelled before it
+            // reached the model spent nothing, and a run of no requests is not a run —
+            // it would only pad `runCount` and shorten retention for nothing.
+            if (record.entries.length > 0)
+                this.deps.onRunUsage?.(record);
             this.log(job, "out", `job ${job.status}`);
+            // THE TERMINAL RECORD, and the entire reconciliation rule for a persisted
+            // log (#172 item 1): a job is `interrupted` if and only if its file has
+            // none. This `finally` runs on every path a job can actually terminate
+            // on — completed, failed, cancelled, refused by the pool — so its
+            // presence means "the job ended" and its absence means "the process died
+            // mid-job", with no marker to maintain and nothing to reconcile at
+            // startup. See `readJobLog` for why neither a pid liveness marker nor a
+            // startup sweep can carry that weight instead.
+            job.writer?.end(job.status, job.iterations, job.error);
+        }
+    }
+    /**
+     * The pool denial a job died on, handed over ONCE (cli#245).
+     *
+     * A latch rather than a push: the foreground drains it where it is idle —
+     * between turns, next to the pending-approval drain — so a background failure
+     * never writes into a live region a turn is painting, and never lands
+     * mid-stream in a shell that is reading a line.
+     *
+     * The newest denial wins. Two jobs refused by one exhausted window are one
+     * fact, and printing it twice is the flood #243 aborted a batch to avoid.
+     */
+    takePoolDenial() {
+        const denial = this.poolDenied;
+        this.poolDenied = undefined;
+        return denial;
+    }
+    /**
+     * ONE POOL DENIAL STOPS EVERY OTHER LIVE JOB (cli#245) — the batch abort #243
+     * made across siblings, carried to the job seam, because the argument is
+     * identical and the denominator is literally the same one.
+     *
+     * A 429 is not a fact about the job that received it. It is a fact about a
+     * window every live job draws on, so the other jobs are not in a different
+     * situation — they are in the same one, a few seconds behind. Left running,
+     * each spends its way to its own refusal: three concurrent jobs discovering
+     * one exhausted window produce three failed jobs, three wasted partial runs,
+     * and three denials for a single fact. Aborting makes the FIRST denial the
+     * session's answer, which is what {@link takePoolDenial} then reports once.
+     *
+     * `abort` and not a status write, so a job stops at its next TURN boundary
+     * exactly as `cruxy cancel` stops it: the in-flight request completes,
+     * whatever checkpoint it took survives for rollback, and its slot is released
+     * through the same `finally`. Aborted jobs land on the `signal.aborted` branch
+     * above and end `cancelled` — honest, and distinct from the one job that
+     * actually was refused, which ends `failed` carrying the denial. They do not
+     * re-latch: the one denial stays the one denial.
+     *
+     * Queued jobs are aborted too. A job still waiting for a slot has spent
+     * nothing yet, and dispatching it into a window that just refused its sibling
+     * is the clearest waste of the set.
+     */
+    abortSiblings(source, denial) {
+        for (const job of this.jobs.values()) {
+            if (job === source || isTerminal(job.status))
+                continue;
+            this.log(job, "out", `cancelling: ${denial.code} — job ${source.id} was refused by the weighted pool`);
+            this.abort(job);
         }
     }
     /** Build the {@link runAgent} args for a job: scoped registry, budget, ctx. */
-    runArgs(job, signal) {
+    runArgs(job, signal, usage) {
         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 }
-                : {}),
-        }));
+        // The caps admission settled at dispatch — resolved there, not here, so a
+        // ceiling the budget cut is the ceiling the run actually executes under.
+        const budget = new Budget(job.limits);
         const ctx = {
             cwd: job.scope.cwd,
             workspace: job.scope.workspace,
@@ -262,6 +425,7 @@ export class JobManager {
             router: deps.router,
             taskClass: "subagent",
             signal,
+            onRequestUsage: (req) => usage.record(req),
         };
     }
     /**
@@ -277,10 +441,18 @@ export class JobManager {
     makeJobApproval(job) {
         const { approvalQueue, semaphore, approvalMutex, foregroundInteractive } = this.deps;
         const cwd = job.scope.cwd;
+        // THE session allowlist a job's grants actually accumulate in (cli#251).
+        // A job has no factory-built allowlist to share — a child gets the parent's
+        // MODE but not its grants (P5 track 3) — so "allow for this session" taken
+        // inside a job lands here and is spent by this policy alone, for this job's
+        // lifetime. The service used to build this line for us when no policy was
+        // passed, which meant the single call site where the allowlist is
+        // load-bearing looked identical to the ones where it is inert. Written out
+        // so the ownership is readable here rather than inferred from an absence.
         const interactive = new ApprovalService({
             cwd,
             interactive: foregroundInteractive,
-            io: this.deps.promptIO,
+            policy: new InteractivePolicy(new SessionAllowlist(), 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
@@ -321,6 +493,83 @@ export class JobManager {
             }
         };
     }
+    /**
+     * Ask the session budget whether this job fits, and return the caps it may run
+     * under (P10 track 3 / cli#245).
+     *
+     * THE VERDICT HAS ONLY TWO SHAPES HERE, because a job is dispatched ONE at a
+     * time. `spawnMany` can be told "three of your five fit" and hands the parent
+     * a positional `not-admitted` result for each of the two that did not; a
+     * single dispatch has no such slot and needs none — `admit` with `count: 1`
+     * either allows, or narrows to that one run with its token ceiling cut to
+     * what the allowance covers, or refuses outright — and a narrowed ceiling
+     * below the floor (see {@link MIN_JOB_REQUESTS}) collapses into that last
+     * one, because a job cannot use it.
+     *
+     * The refusal is a THROW, so it lands on `dispatch`'s existing coded-error
+     * path and reaches the model through the tool: the same treatment as
+     * `jobsDisabled` / `jobLimitExceeded` / an unknown root.
+     *
+     * Tier: a job routes on the `subagent` task class, exactly as a child does. An
+     * unresolved tier still draws on the pool, so it is weighed at the worst case
+     * rather than skipped; no router at all means a bring-your-own provider whose
+     * tokens never touch the weighted pool, and nothing here bounds them.
+     */
+    admit(spec) {
+        const { budget, config, logger } = this.deps;
+        const resolved = resolveBudget(config.subagent.defaultBudget, {
+            ...(spec.budget?.maxIterations !== undefined
+                ? { maxIterations: spec.budget.maxIterations }
+                : {}),
+            ...(spec.budget?.maxTokens !== undefined
+                ? { maxTokens: spec.budget.maxTokens }
+                : {}),
+        });
+        if (!budget)
+            return resolved;
+        const verdict = budget.admit({
+            count: 1,
+            perRunTokens: resolved.maxTokens,
+            tier: this.jobTier(),
+        });
+        if (verdict.kind === "refused")
+            throw sessionBudgetExhausted(verdict.reason);
+        if (verdict.kind === "allow" || verdict.maxTokens <= 0)
+            return resolved;
+        // A NARROWED CEILING BELOW THE FLOOR IS A REFUSAL (cli#245). `admit` narrows
+        // rather than refuses so that a user with real headroom is never left unable
+        // to ask anything at all, and for the turn that is exactly right: the user is
+        // present, sees the warning, and can shorten the question or raise
+        // `/budget`. A job has none of that. It runs after the turn returned, with
+        // nobody watching, on a task the model already wrote — so the same narrowing
+        // that keeps a turn useful hands a job a ceiling it cannot start under, and
+        // the honest answer is to say so at the seam where the model can still act
+        // on it rather than to dispatch a run that fails a second later.
+        //
+        // Refused HERE and not in the shared rule on purpose: `admit` is one object
+        // answering three callers, and only this one is unattended.
+        const floor = this.deps.config.context.reserveTokens * MIN_JOB_REQUESTS;
+        if (verdict.maxTokens < floor) {
+            throw sessionBudgetExhausted(`${verdict.reason}; a background job needs at least ` +
+                `${compactTokens(floor)} tokens to complete one act-and-report cycle, ` +
+                `so it was refused rather than dispatched to fail on its first turn`);
+        }
+        // Narrowed: the one run is admitted with a cut ceiling. `Math.min` because
+        // `admit` may only ever narrow — a granted figure above the resolved cap
+        // would raise a ceiling the config and the spec already set.
+        logger.warn(verdict.reason);
+        return {
+            ...resolved,
+            maxTokens: Math.min(resolved.maxTokens, verdict.maxTokens),
+        };
+    }
+    /** The tier a job would route to, or the unresolved/no-pool markers. */
+    jobTier() {
+        const router = this.deps.router;
+        if (!router)
+            return undefined; // not a cruxy request — no weighted pool
+        return resolveTaskModel(router, "subagent").tier ?? UNRESOLVED_TIER;
+    }
     /** Resolve a job's scope from an optional root name (fail-loud on unknown). */
     jobScope(rootName) {
         if (rootName === undefined) {
@@ -354,8 +603,65 @@ export class JobManager {
             throw jobNotFound(id);
         return job;
     }
+    /**
+     * THE ONE SINK every job log line goes through — the in-memory ring buffer
+     * for the live readers (`/logs`, the Tasks view), and the file for afterwards
+     * (#172 item 1).
+     *
+     * Both, on the same call, because the file is written by STREAMING and not by
+     * serialising the buffer on the way out. A flush-at-exit design would live in
+     * `execute`'s `finally`, and that `finally` is exactly what does not run when
+     * the process is felled: `tui/restore.ts` and `utils/child-tree.ts` both
+     * install SIGINT/SIGTERM/SIGHUP handlers that call `process.exit` directly,
+     * so a closed terminal window, a dropped ssh session or a plain `kill`
+     * abandons every pending `finally` in the process. A log that only persists
+     * on the orderly path persists the runs nobody needed persisted and loses
+     * every one they did.
+     *
+     * Streaming also happens to be the only version that delivers what the issue
+     * asked for: writing the BUFFER at exit would persist its truncated tail, so
+     * the drop-on-overflow this was meant to remove would simply move to disk.
+     */
     log(job, stream, text) {
-        job.logs.append({ atMs: this.now(), stream, text });
+        const line = { atMs: this.now(), stream, text };
+        job.logs.append(line);
+        job.writer?.line(line);
+    }
+    /**
+     * Build a job's on-disk log, or decline to.
+     *
+     * DECLINES WHEN `sessions.enabled` IS FALSE, and this is load-bearing rather
+     * than tidy. The sweep that bounds this subtree
+     * ({@link ../session/prune.js sweepOrphanedJobLogs}) is reached only through
+     * `pruneSessions`, which returns early on that same flag — so a writer that
+     * ignored it would produce files nothing ever collects, which is precisely
+     * the second unbounded writer under `~/.cruxy` that #257 was filed to
+     * prevent. "Do not record my conversations to disk" also plainly covers what
+     * the agent said while working in the background.
+     *
+     * DECLINES WITH NO SESSION ID for the same ownership reason: a job log is
+     * content owned by its session, keyed on the session, and one that cannot
+     * name its owner can be neither swept with it nor listed beside it. The id is
+     * read lazily (see {@link JobManagerDeps.sessionId}) and is present by the
+     * time any job is dispatched — a dispatch happens inside a turn, and the
+     * session exists before its first turn. Returning undefined is the honest
+     * answer to the case that should not arise, rather than a fabricated key.
+     */
+    makeWriter(id, label) {
+        const { deps } = this;
+        if (!deps.config.sessions.enabled)
+            return undefined;
+        const sessionId = deps.sessionId?.();
+        if (sessionId === undefined)
+            return undefined;
+        return new JobLogWriter({
+            cwd: deps.cwd,
+            sessionId,
+            jobId: id,
+            label,
+            cap: deps.config.jobs.logFileLines,
+            logger: deps.logger,
+        });
     }
     view(job) {
         const pending = this.deps.approvalQueue.pendingFor(job.id);
@@ -370,6 +676,20 @@ export class JobManager {
         };
     }
 }
+/**
+ * A job's `error` line for a pool denial, with every fact the 429 carried.
+ *
+ * `job.error` is a string and a `JobView` is what `/jobs` and the Tasks view
+ * read, so the typed error cannot be handed over whole here — but its next
+ * steps are exactly where `miraAvailable` and `resetAt` were rendered into
+ * words, and dropping them is what made a denial indistinguishable from a
+ * crash. The typed object itself still survives, on the latch the foreground
+ * drains (see {@link JobManager.takePoolDenial}).
+ */
+function denialLine(denial) {
+    const steps = denial.nextSteps.join("; ");
+    return `${denial.code}: ${denial.title}${steps ? ` — ${steps}` : ""}`;
+}
 /** One-line task excerpt for a job label. */
 function taskLabel(task) {
     const flat = task.replace(/\s+/g, " ").trim();

package/dist/mcp/client.js

@@ -10,6 +10,22 @@ import { APP_NAME, APP_VERSION } from "../constants.js";
  */
 /** The MCP protocol revision cruxy advertises. */
 const PROTOCOL_VERSION = "2025-06-18";
+/**
+ * The three fields cruxy accepts from an advertised tool — and, by omission, the
+ * enforcement point for everything it refuses.
+ *
+ * `annotations` IS DELIBERATELY ABSENT. MCP lets a server describe its own tool
+ * with `readOnlyHint` / `destructiveHint` / `idempotentHint`, and zod strips
+ * unknown keys, so declaring only these three drops the block here at the wire
+ * boundary rather than carrying it inward for someone downstream to be tempted
+ * by. The spec's own rule is that clients "MUST consider tool annotations to be
+ * untrusted unless they come from trusted servers", and cruxy's MCP trust binds
+ * the INVOCATION rather than the code (`mcp/trust.ts`), so it cannot claim that
+ * exemption. Adding a field here would not merely widen a parse — it would put a
+ * server-controlled boolean within reach of the approval gate. The full argument
+ * is at `mcpRequest` in `approval/classify.ts`; `annotations-untrusted.test.ts`
+ * pins the property at both layers.
+ */
 const RawToolSchema = z.object({
     name: z.string().min(1),
     description: z.string().optional(),