@cruxy/cli 0.28.2 → 0.29.2

package/dist/agent/budget.d.ts

@@ -0,0 +1,52 @@
+import type { Usage } from "@cruxy/sdk";
+import type { LoopBudget } from "./loop.js";
+/**
+ * The live budget primitive for the agent loop: iteration + token + optional
+ * wall-clock caps, checked by {@link runAgent} before every model turn (see
+ * `LoopBudget`). A tripped cap stops the run with a human-readable reason and
+ * the coherent partial history — the loop never runs unbounded.
+ *
+ * It lives beside the loop it guards: the loop defines the `LoopBudget` seam,
+ * this is its one concrete implementation, and the subagent orchestrator, the
+ * job manager, and {@link Session} (per-turn token guard) all consume it.
+ */
+/**
+ * Hard caps a run executes under. `maxTokens` is always finite; `maxIterations`
+ * is finite for a subagent (bounded by construction) but may be
+ * `Number.POSITIVE_INFINITY` for a token-only guard where iteration count is
+ * bounded elsewhere (a main turn is already capped by `agent.maxIterations` in
+ * the loop). `timeoutMs` is an optional wall-clock backstop on top.
+ */
+export interface BudgetLimits {
+    /** Cap on the run's model turns (may be `Infinity` for a token-only guard). */
+    maxIterations: number;
+    /** Cap on the run's combined input+output tokens. */
+    maxTokens: number;
+    /** Optional wall-clock cap in milliseconds. */
+    timeoutMs?: number;
+}
+/**
+ * Resolve the effective limits for one spawn: start from the configured
+ * ceilings and let overrides only *narrow* them. A request above a ceiling is
+ * clamped down, not honored — "budget overrides within limits" by construction.
+ */
+export declare function resolveBudget(defaults: BudgetLimits, overrides?: Partial<BudgetLimits>): BudgetLimits;
+/**
+ * A live budget for one run. The wall clock starts at construction (spawn /
+ * turn start); the clock source is injectable so tests never sleep.
+ */
+export declare class Budget implements LoopBudget {
+    private readonly limits;
+    private readonly now;
+    private readonly startedAt;
+    constructor(limits: BudgetLimits, now?: () => number);
+    /**
+     * The reason to stop before the next model turn, or `null` to continue.
+     * Checked at iteration boundaries — the in-flight turn always completes, so
+     * overshoot is bounded by one turn.
+     */
+    exceeded(state: {
+        iterations: number;
+        usage: Usage;
+    }): string | null;
+}

package/dist/{subagent → agent}/budget.js

@@ -1,9 +1,3 @@
-/**
- * The subagent budget (C.14): iteration + token + optional wall-clock caps,
- * checked by the agent loop before every model turn (see `LoopBudget`). A
- * tripped cap stops the run with a human-readable reason — the subagent
- * returns a partial result, it never runs unbounded.
- */
 /**
  * Resolve the effective limits for one spawn: start from the configured
  * ceilings and let overrides only *narrow* them. A request above a ceiling is
@@ -23,8 +17,8 @@ export function resolveBudget(defaults, overrides) {
     };
 }
 /**
- * A live budget for one subagent run. The wall clock starts at construction
- * (spawn time); the clock source is injectable so tests never sleep.
+ * A live budget for one run. The wall clock starts at construction (spawn /
+ * turn start); the clock source is injectable so tests never sleep.
  */
 export class Budget {
     limits;

package/dist/agent/loop.d.ts

@@ -103,6 +103,21 @@ export interface RunAgentArgs {
      * is kill-tree'd rather than orphaned.
      */
     signal?: AbortSignal;
+    /**
+     * Mid-loop compaction seam (build item 3). Called at the top of every
+     * iteration with the running history; returns the history to continue from —
+     * unchanged when under threshold, or with its older prefix summarized away
+     * when over. Supplied by {@link Session}, which reuses its own
+     * threshold/cut/summarize machinery, so the loop gains no summarization
+     * knowledge and no logic is duplicated. Omitted → history is never compacted
+     * mid-loop (unchanged behavior; subagents pass nothing).
+     *
+     * This is what keeps a long autonomous turn — where `send` compacts only once
+     * up front and never again — within the context window: without it a run that
+     * drives dozens of tool calls (each result appended, some tens of KB) grows
+     * unbounded until the next `send`, which in one-shot never comes.
+     */
+    compact?: (messages: Message[]) => Promise<Message[]>;
 }
 /**
  * The budget seam for {@link runAgent}: implementations track their own caps

package/dist/agent/loop.js

@@ -40,8 +40,9 @@ async function driveLoop(args, renderer, routed) {
     const { provider, registry, config, ctx } = args;
     const { logger } = ctx;
     // Work on a copy so we never mutate the caller's array as a side effect; the
-    // extended history is returned for the caller to adopt.
-    const messages = [...args.messages];
+    // extended history is returned for the caller to adopt. Reassigned wholesale
+    // when the mid-loop compaction seam folds away an older prefix.
+    let messages = [...args.messages];
     const usage = { input_tokens: 0, output_tokens: 0 };
     const maxIterations = config.agent.maxIterations;
     // The tool catalogue and environment are stable across the loop, so build the
@@ -88,6 +89,14 @@ async function driveLoop(args, renderer, routed) {
                 usage,
             };
         }
+        // Mid-loop compaction (build item 3), after the abort/budget checks so a
+        // cancelled or over-budget run never spends a summary call: fold away the
+        // older prefix when the history has grown past threshold *this* iteration.
+        // The seam preserves tool_use/tool_result integrity (it only cuts at a
+        // completed turn boundary), so adopting its result mid-turn is safe.
+        if (args.compact) {
+            messages = await args.compact(messages);
+        }
         iterations = i + 1;
         const tools = registry.toToolSpecs();
         // ── Consume one model turn ──────────────────────────────────────────────

package/dist/agent/session.d.ts

@@ -145,23 +145,46 @@ export declare class Session {
     /** Drop the conversation history but keep the session (for `/clear`). */
     clear(): void;
     /**
-     * Compact only when the estimated history exceeds
-     * `compactThreshold * maxTokens`. On success logs a one-line notice and
-     * returns the number of older messages folded into the summary; otherwise
-     * returns `null` (under threshold, nothing safe to cut, or summary failed).
+     * Compact `this.messages` only when it has grown past threshold, adopting the
+     * result. On success logs a one-line notice and returns the number of older
+     * messages folded into the summary; otherwise returns `null` (under threshold,
+     * nothing safe to cut, or summary failed).
      */
     maybeCompact(onRequestUsage?: (req: RequestUsage) => void): Promise<number | null>;
+    /**
+     * The mid-loop compaction seam (build item 3) handed to {@link runAgent}: same
+     * threshold/cut/summarize path as {@link maybeCompact}, but over the loop's own
+     * running history rather than `this.messages` (the loop owns and adopts its
+     * copy). Reuses the exact machinery so no summarization logic is duplicated and
+     * the loop stays ignorant of it. Under threshold it returns the history
+     * unchanged — cheap, no model call.
+     */
+    private compactLoopHistory;
     /**
      * Force compaction regardless of the threshold (backs `/compact`). Returns the
      * number of older messages summarized, or `null` if there was nothing safe to
      * cut or the summary call failed.
      */
     compact(): Promise<number | null>;
+    /**
+     * Compact `messages` when its estimated footprint exceeds
+     * `compactThreshold * maxTokens`, else return it untouched. The estimate adds a
+     * fixed `reserveTokens` allowance for the system prompt and tool schemas that
+     * {@link estimateTokens} never sees (~4.5k+ tokens of real request payload), so
+     * the trigger reflects the actual request size rather than only the visible
+     * history — otherwise the loop can sit just under the visible threshold while
+     * the real request has already overrun the window. Logs a one-line notice on a
+     * successful compaction.
+     */
+    private compactIfOverThreshold;
     /**
      * Find a clean cut, summarize the older prefix into a synthetic user/assistant
      * pair, and splice it in front of the kept-recent messages. Best-effort: a
-     * failed summary call leaves the history untouched and returns `null` (fail
-     * open — losing compaction is degraded, not unsafe).
+     * failed summary call leaves the history untouched and reports `compacted:
+     * null` (fail open — losing compaction is degraded, not unsafe). Pure with
+     * respect to `this.messages`: it returns the new array for the caller to adopt
+     * (the loop and the session each own their own history), and only accumulates
+     * the summary's usage into the session total.
      */
     private runCompaction;
     /**
@@ -171,7 +194,9 @@ export declare class Session {
      * matching `tool_result` (the next user message) must never straddle the cut,
      * or the next provider call breaks. A real user *prompt* (`role:"user"` with
      * string content) only occurs at a completed turn boundary, where every prior
-     * tool exchange is already resolved — so the kept region must begin there.
+     * tool exchange is already resolved — so the kept region must begin there. The
+     * synthetic compaction-summary user message is also string content, so a
+     * repeat compaction always finds at least the previous summary as a clean cut.
      *
      * Start from `length - keepRecentMessages` and walk *backwards* to the nearest
      * such prompt: this keeps at least the recent floor and lands clean. Returns

package/dist/agent/session.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { loadProjectInstructions } from "../config/index.js";
 import { resolveTaskModel } from "../routing/index.js";
 import { UsageCollector, } from "../usage/index.js";
+import { Budget } from "./budget.js";
 import { runAgent, } from "./loop.js";
 import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
 /**
@@ -115,6 +116,20 @@ export class Session {
         const onReq = (req) => collector.record(req);
         // Compact *before* the agent call so the turn runs against a bounded history.
         await this.maybeCompact(onReq);
+        // Per-turn runaway guard (build item 4): when `agent.maxTokensPerTurn` is
+        // set, hand the loop a fresh token-only budget for THIS turn. Reusing the
+        // Budget primitive with an infinite iteration cap makes it purely a token
+        // stop — the loop's own `agent.maxIterations` already bounds turn count.
+        // Unset/0 → no budget object at all, so the loop's budget check is a no-op
+        // and behavior is byte-identical to before. Rebuilt each `send`, so the cap
+        // is per-turn, never cumulative across the session (cost is C.22's concern).
+        const maxTokensPerTurn = this.args.config.agent.maxTokensPerTurn;
+        const budget = maxTokensPerTurn > 0
+            ? new Budget({
+                maxIterations: Number.POSITIVE_INFINITY,
+                maxTokens: maxTokensPerTurn,
+            })
+            : undefined;
         // before-run (C.19): a blocking pre-run hook — or an untrusted project's
         // hooks — throws here and aborts the turn before the model is engaged
         // (fail-closed). No-op when hooks are disabled or none are registered.
@@ -133,12 +148,21 @@ export class Session {
             : await runAgent({
                 messages: this.messages,
                 ...this.args, // carries `router` through to the loop
+                // The per-turn token guard (build item 4). After the spread because
+                // SessionArgs has no `budget` field — it is a per-turn construction,
+                // not session state. `undefined` when the cap is off (no-op check).
+                budget,
                 taskClass: "main-turn",
                 // After the spread so a mid-session `/reload` wins over the initial value.
                 projectInstructions: this.projectInstructions,
                 planMode: false, // the plan directive belongs only to the runner's propose phase
                 renderer,
                 onRequestUsage: onReq,
+                // Mid-loop compaction (build item 3): let a long autonomous turn
+                // compact between iterations, not just once up front. Reuses this
+                // session's threshold/cut/summarize path over the loop's own history
+                // and attributes the summary usage to this run's collector.
+                compact: (messages) => this.compactLoopHistory(messages, onReq),
             });
         this.messages = result.messages;
         this.usage.input_tokens += result.usage.input_tokens;
@@ -169,21 +193,27 @@ export class Session {
         this.messages = [];
     }
     /**
-     * Compact only when the estimated history exceeds
-     * `compactThreshold * maxTokens`. On success logs a one-line notice and
-     * returns the number of older messages folded into the summary; otherwise
-     * returns `null` (under threshold, nothing safe to cut, or summary failed).
+     * Compact `this.messages` only when it has grown past threshold, adopting the
+     * result. On success logs a one-line notice and returns the number of older
+     * messages folded into the summary; otherwise returns `null` (under threshold,
+     * nothing safe to cut, or summary failed).
      */
     async maybeCompact(onRequestUsage) {
-        const { maxTokens, compactThreshold } = this.args.config.context;
-        if (estimateTokens(this.messages) <= compactThreshold * maxTokens) {
-            return null;
-        }
-        const n = await this.runCompaction(onRequestUsage);
-        if (n) {
-            this.args.ctx.logger.info(`compacted ${n} older message${n === 1 ? "" : "s"} to stay within context`);
-        }
-        return n;
+        const { messages, compacted } = await this.compactIfOverThreshold(this.messages, onRequestUsage);
+        this.messages = messages;
+        return compacted;
+    }
+    /**
+     * The mid-loop compaction seam (build item 3) handed to {@link runAgent}: same
+     * threshold/cut/summarize path as {@link maybeCompact}, but over the loop's own
+     * running history rather than `this.messages` (the loop owns and adopts its
+     * copy). Reuses the exact machinery so no summarization logic is duplicated and
+     * the loop stays ignorant of it. Under threshold it returns the history
+     * unchanged — cheap, no model call.
+     */
+    async compactLoopHistory(messages, onRequestUsage) {
+        const result = await this.compactIfOverThreshold(messages, onRequestUsage);
+        return result.messages;
     }
     /**
      * Force compaction regardless of the threshold (backs `/compact`). Returns the
@@ -191,20 +221,47 @@ export class Session {
      * cut or the summary call failed.
      */
     async compact() {
-        return this.runCompaction();
+        const { messages, compacted } = await this.runCompaction(this.messages);
+        this.messages = messages;
+        return compacted;
+    }
+    /**
+     * Compact `messages` when its estimated footprint exceeds
+     * `compactThreshold * maxTokens`, else return it untouched. The estimate adds a
+     * fixed `reserveTokens` allowance for the system prompt and tool schemas that
+     * {@link estimateTokens} never sees (~4.5k+ tokens of real request payload), so
+     * the trigger reflects the actual request size rather than only the visible
+     * history — otherwise the loop can sit just under the visible threshold while
+     * the real request has already overrun the window. Logs a one-line notice on a
+     * successful compaction.
+     */
+    async compactIfOverThreshold(messages, onRequestUsage) {
+        const { maxTokens, compactThreshold, reserveTokens } = this.args.config.context;
+        const estimated = estimateTokens(messages) + reserveTokens;
+        if (estimated <= compactThreshold * maxTokens) {
+            return { messages, compacted: null };
+        }
+        const result = await this.runCompaction(messages, onRequestUsage);
+        if (result.compacted) {
+            this.args.ctx.logger.info(`compacted ${result.compacted} older message${result.compacted === 1 ? "" : "s"} to stay within context`);
+        }
+        return result;
     }
     /**
      * Find a clean cut, summarize the older prefix into a synthetic user/assistant
      * pair, and splice it in front of the kept-recent messages. Best-effort: a
-     * failed summary call leaves the history untouched and returns `null` (fail
-     * open — losing compaction is degraded, not unsafe).
+     * failed summary call leaves the history untouched and reports `compacted:
+     * null` (fail open — losing compaction is degraded, not unsafe). Pure with
+     * respect to `this.messages`: it returns the new array for the caller to adopt
+     * (the loop and the session each own their own history), and only accumulates
+     * the summary's usage into the session total.
      */
-    async runCompaction(onRequestUsage) {
-        const cut = this.findCut();
+    async runCompaction(messages, onRequestUsage) {
+        const cut = this.findCut(messages);
         if (cut === null)
-            return null;
-        const prefix = this.messages.slice(0, cut);
-        const kept = this.messages.slice(cut);
+            return { messages, compacted: null };
+        const prefix = messages.slice(0, cut);
+        const kept = messages.slice(cut);
         let synopsis;
         try {
             const summary = await this.summarize(prefix, onRequestUsage);
@@ -214,7 +271,7 @@ export class Session {
         }
         catch (err) {
             this.args.ctx.logger.warn(`compaction skipped: summary failed (${err.message})`);
-            return null;
+            return { messages, compacted: null };
         }
         // A user/assistant pair, not a lone message: the kept region begins with a
         // user prompt, so a single synthetic user message would put two user turns
@@ -229,8 +286,10 @@ export class Session {
                 content: `${COMPACTION_MARKER} Summary of the conversation so far:\n\n${synopsis}`,
             },
         ];
-        this.messages = [...summaryMessages, ...kept];
-        return prefix.length;
+        return {
+            messages: [...summaryMessages, ...kept],
+            compacted: prefix.length,
+        };
     }
     /**
      * Choose the boundary between the summarized prefix and the kept-recent tail.
@@ -239,18 +298,20 @@ export class Session {
      * matching `tool_result` (the next user message) must never straddle the cut,
      * or the next provider call breaks. A real user *prompt* (`role:"user"` with
      * string content) only occurs at a completed turn boundary, where every prior
-     * tool exchange is already resolved — so the kept region must begin there.
+     * tool exchange is already resolved — so the kept region must begin there. The
+     * synthetic compaction-summary user message is also string content, so a
+     * repeat compaction always finds at least the previous summary as a clean cut.
      *
      * Start from `length - keepRecentMessages` and walk *backwards* to the nearest
      * such prompt: this keeps at least the recent floor and lands clean. Returns
      * the cut index, or `null` if no safe boundary leaves a non-empty prefix
      * (e.g. a single long in-progress turn — nothing safe to compact).
      */
-    findCut() {
+    findCut(messages) {
         const { keepRecentMessages } = this.args.config.context;
-        const start = this.messages.length - keepRecentMessages;
+        const start = messages.length - keepRecentMessages;
         for (let i = start; i >= 1; i--) {
-            const msg = this.messages[i];
+            const msg = messages[i];
             if (msg.role === "user" && typeof msg.content === "string")
                 return i;
         }

package/dist/cli/commands/run.js

@@ -187,7 +187,24 @@ export function runCommand() {
                 logger.info(t.muted(`mcp:     server "${d.server}" declared in ${d.root} not loaded (primary-root MCP only this release)`));
             }
         }
-        const session = buildAgentSession(config, apiKey, workspace, Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksRunner, mcp.tools);
+        // One-shot vs REPL turn ceiling. A one-shot run caps at
+        // `agent.maxIterationsOneShot` (default 40): a headless run can't be
+        // resumed by a human, so hitting the cap abandons the whole task — it
+        // needs headroom above the interactive cap to clear legit long work,
+        // while still bounding a runaway (and it now exits non-zero, see below).
+        // The REPL keeps `agent.maxIterations` (a soft checkpoint). Keyed on the
+        // one-shot MODE, never on TTY, so `cruxy run "task"` behaves the same
+        // piped into CI or run in a terminal.
+        const sessionConfig = interactive
+            ? config
+            : {
+                ...config,
+                agent: {
+                    ...config.agent,
+                    maxIterations: config.agent.maxIterationsOneShot,
+                },
+            };
+        const session = buildAgentSession(sessionConfig, apiKey, workspace, Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksRunner, mcp.tools);
         if (interactive) {
             try {
                 await runInteractive(session, undefined, renderer, checkpoints, hookCommands);
@@ -253,7 +270,9 @@ export function runCommand() {
                 stop: result.stop,
                 iterations: result.iterations,
                 reason: result.stopReason,
-                maxIterations: config.agent.maxIterations,
+                // The effective one-shot cap (agent.maxIterationsOneShot), so the
+                // message names the limit the run actually hit.
+                maxIterations: sessionConfig.agent.maxIterations,
             });
         }
     });

package/dist/config/schema.d.ts

@@ -26,18 +26,48 @@ export declare const CruxyBackendConfigSchema: z.ZodObject<{
     gatewayUrl?: string | undefined;
 }>;
 export declare const AgentConfigSchema: z.ZodObject<{
-    /** Hard ceiling on agent loop turns. */
+    /**
+     * Hard ceiling on agent loop turns per user turn — the interactive default.
+     * In the REPL this is a soft checkpoint: hitting it ends the turn and the
+     * human continues (or Ctrl-C's a runaway), so it can be generous.
+     */
     maxIterations: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Turn ceiling for a ONE-SHOT `cruxy run "task"` (non-interactive). Set higher
+     * than {@link maxIterations} because a headless run has no human to resume it:
+     * hitting the cap abandons the whole task (fail-loud, non-zero exit), so it
+     * must clear the legit long tail (real "fix the failing tests" work runs
+     * ~10-25 turns) while still bounding a runaway. Not clamped to
+     * `maxIterations` — a user may deliberately set it lower or higher.
+     */
+    maxIterationsOneShot: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Optional hard cap on combined input+output tokens for a SINGLE user turn
+     * — a last-resort runaway guard, not cost control (cumulative session cost
+     * is C.22's concern). OFF by default (0 = off): today's behavior is
+     * preserved exactly and no turn is ever token-stopped. When set, a turn that
+     * crosses the cap stops at the next turn boundary with a coherent partial
+     * history (`stop: "budget"`); in one-shot that fails loud (exit 20), while
+     * interactively the human simply continues. Compaction is the everyday
+     * pressure valve for context — this only bounds a genuinely runaway turn, so
+     * a hostile hard stop mid-work stays opt-in. Reset each `send`, never
+     * cumulative across turns.
+     */
+    maxTokensPerTurn: z.ZodDefault<z.ZodNumber>;
     /** Skip per-action confirmation prompts. */
     autoApprove: z.ZodDefault<z.ZodBoolean>;
     /** Plan mode: propose a plan for approval before executing (C.31, opt-in). */
     planMode: z.ZodDefault<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     maxIterations: number;
+    maxIterationsOneShot: number;
+    maxTokensPerTurn: number;
     autoApprove: boolean;
     planMode: boolean;
 }, {
     maxIterations?: number | undefined;
+    maxIterationsOneShot?: number | undefined;
+    maxTokensPerTurn?: number | undefined;
     autoApprove?: boolean | undefined;
     planMode?: boolean | undefined;
 }>;
@@ -88,16 +118,26 @@ export declare const ContextConfigSchema: z.ZodObject<{
     maxTokens: z.ZodDefault<z.ZodNumber>;
     /** Compact once the history estimate exceeds this fraction of maxTokens. */
     compactThreshold: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Fixed token allowance for request payload that `estimateTokens` never
+     * sees — the system prompt and every tool's JSON schema — added to the
+     * measured history before the threshold test so the trigger reflects the
+     * real request size, not just the visible messages. Roughly the size of
+     * the built system prompt plus the default tool catalogue today.
+     */
+    reserveTokens: z.ZodDefault<z.ZodNumber>;
     /** Most-recent messages always kept verbatim (a floor; the cut rounds up to
      * a clean turn boundary). */
     keepRecentMessages: z.ZodDefault<z.ZodNumber>;
 }, "strict", z.ZodTypeAny, {
     maxTokens: number;
     compactThreshold: number;
+    reserveTokens: number;
     keepRecentMessages: number;
 }, {
     maxTokens?: number | undefined;
     compactThreshold?: number | undefined;
+    reserveTokens?: number | undefined;
     keepRecentMessages?: number | undefined;
 }>;
 /**
@@ -979,18 +1019,48 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         gatewayUrl?: string | undefined;
     }>>;
     agent: z.ZodDefault<z.ZodObject<{
-        /** Hard ceiling on agent loop turns. */
+        /**
+         * Hard ceiling on agent loop turns per user turn — the interactive default.
+         * In the REPL this is a soft checkpoint: hitting it ends the turn and the
+         * human continues (or Ctrl-C's a runaway), so it can be generous.
+         */
         maxIterations: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Turn ceiling for a ONE-SHOT `cruxy run "task"` (non-interactive). Set higher
+         * than {@link maxIterations} because a headless run has no human to resume it:
+         * hitting the cap abandons the whole task (fail-loud, non-zero exit), so it
+         * must clear the legit long tail (real "fix the failing tests" work runs
+         * ~10-25 turns) while still bounding a runaway. Not clamped to
+         * `maxIterations` — a user may deliberately set it lower or higher.
+         */
+        maxIterationsOneShot: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Optional hard cap on combined input+output tokens for a SINGLE user turn
+         * — a last-resort runaway guard, not cost control (cumulative session cost
+         * is C.22's concern). OFF by default (0 = off): today's behavior is
+         * preserved exactly and no turn is ever token-stopped. When set, a turn that
+         * crosses the cap stops at the next turn boundary with a coherent partial
+         * history (`stop: "budget"`); in one-shot that fails loud (exit 20), while
+         * interactively the human simply continues. Compaction is the everyday
+         * pressure valve for context — this only bounds a genuinely runaway turn, so
+         * a hostile hard stop mid-work stays opt-in. Reset each `send`, never
+         * cumulative across turns.
+         */
+        maxTokensPerTurn: z.ZodDefault<z.ZodNumber>;
         /** Skip per-action confirmation prompts. */
         autoApprove: z.ZodDefault<z.ZodBoolean>;
         /** Plan mode: propose a plan for approval before executing (C.31, opt-in). */
         planMode: z.ZodDefault<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         maxIterations: number;
+        maxIterationsOneShot: number;
+        maxTokensPerTurn: number;
         autoApprove: boolean;
         planMode: boolean;
     }, {
         maxIterations?: number | undefined;
+        maxIterationsOneShot?: number | undefined;
+        maxTokensPerTurn?: number | undefined;
         autoApprove?: boolean | undefined;
         planMode?: boolean | undefined;
     }>>;
@@ -1038,16 +1108,26 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         maxTokens: z.ZodDefault<z.ZodNumber>;
         /** Compact once the history estimate exceeds this fraction of maxTokens. */
         compactThreshold: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Fixed token allowance for request payload that `estimateTokens` never
+         * sees — the system prompt and every tool's JSON schema — added to the
+         * measured history before the threshold test so the trigger reflects the
+         * real request size, not just the visible messages. Roughly the size of
+         * the built system prompt plus the default tool catalogue today.
+         */
+        reserveTokens: z.ZodDefault<z.ZodNumber>;
         /** Most-recent messages always kept verbatim (a floor; the cut rounds up to
          * a clean turn boundary). */
         keepRecentMessages: z.ZodDefault<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
         maxTokens: number;
         compactThreshold: number;
+        reserveTokens: number;
         keepRecentMessages: number;
     }, {
         maxTokens?: number | undefined;
         compactThreshold?: number | undefined;
+        reserveTokens?: number | undefined;
         keepRecentMessages?: number | undefined;
     }>>;
     approval: z.ZodDefault<z.ZodObject<{
@@ -1737,6 +1817,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     };
     agent: {
         maxIterations: number;
+        maxIterationsOneShot: number;
+        maxTokensPerTurn: number;
         autoApprove: boolean;
         planMode: boolean;
     };
@@ -1752,6 +1834,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     context: {
         maxTokens: number;
         compactThreshold: number;
+        reserveTokens: number;
         keepRecentMessages: number;
     };
     index: {
@@ -1889,6 +1972,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     } | undefined;
     agent?: {
         maxIterations?: number | undefined;
+        maxIterationsOneShot?: number | undefined;
+        maxTokensPerTurn?: number | undefined;
         autoApprove?: boolean | undefined;
         planMode?: boolean | undefined;
     } | undefined;
@@ -1904,6 +1989,7 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     context?: {
         maxTokens?: number | undefined;
         compactThreshold?: number | undefined;
+        reserveTokens?: number | undefined;
         keepRecentMessages?: number | undefined;
     } | undefined;
     index?: {

package/dist/config/schema.js

@@ -26,8 +26,34 @@ export const CruxyBackendConfigSchema = z
     .strict();
 export const AgentConfigSchema = z
     .object({
-    /** Hard ceiling on agent loop turns. */
+    /**
+     * Hard ceiling on agent loop turns per user turn — the interactive default.
+     * In the REPL this is a soft checkpoint: hitting it ends the turn and the
+     * human continues (or Ctrl-C's a runaway), so it can be generous.
+     */
     maxIterations: z.number().int().positive().default(25),
+    /**
+     * Turn ceiling for a ONE-SHOT `cruxy run "task"` (non-interactive). Set higher
+     * than {@link maxIterations} because a headless run has no human to resume it:
+     * hitting the cap abandons the whole task (fail-loud, non-zero exit), so it
+     * must clear the legit long tail (real "fix the failing tests" work runs
+     * ~10-25 turns) while still bounding a runaway. Not clamped to
+     * `maxIterations` — a user may deliberately set it lower or higher.
+     */
+    maxIterationsOneShot: z.number().int().positive().default(40),
+    /**
+     * Optional hard cap on combined input+output tokens for a SINGLE user turn
+     * — a last-resort runaway guard, not cost control (cumulative session cost
+     * is C.22's concern). OFF by default (0 = off): today's behavior is
+     * preserved exactly and no turn is ever token-stopped. When set, a turn that
+     * crosses the cap stops at the next turn boundary with a coherent partial
+     * history (`stop: "budget"`); in one-shot that fails loud (exit 20), while
+     * interactively the human simply continues. Compaction is the everyday
+     * pressure valve for context — this only bounds a genuinely runaway turn, so
+     * a hostile hard stop mid-work stays opt-in. Reset each `send`, never
+     * cumulative across turns.
+     */
+    maxTokensPerTurn: z.number().int().nonnegative().default(0),
     /** Skip per-action confirmation prompts. */
     autoApprove: z.boolean().default(false),
     /** Plan mode: propose a plan for approval before executing (C.31, opt-in). */
@@ -68,6 +94,14 @@ export const ContextConfigSchema = z
     maxTokens: z.number().int().positive().default(100000),
     /** Compact once the history estimate exceeds this fraction of maxTokens. */
     compactThreshold: z.number().min(0).max(1).default(0.75),
+    /**
+     * Fixed token allowance for request payload that `estimateTokens` never
+     * sees — the system prompt and every tool's JSON schema — added to the
+     * measured history before the threshold test so the trigger reflects the
+     * real request size, not just the visible messages. Roughly the size of
+     * the built system prompt plus the default tool catalogue today.
+     */
+    reserveTokens: z.number().int().nonnegative().default(4500),
     /** Most-recent messages always kept verbatim (a floor; the cut rounds up to
      * a clean turn boundary). */
     keepRecentMessages: z.number().int().positive().default(6),

package/dist/errors/constructors.js

@@ -1235,7 +1235,7 @@ export function agentIncomplete(info) {
         cause: `reached the turn limit${cap} after ${turns} without completing. The work so far is shown above.`,
         nextSteps: [
             "review the partial output above, then re-run with a narrower prompt",
-            "raise `agent.maxIterations` if the task legitimately needs more turns",
+            "raise `agent.maxIterationsOneShot` (one-shot) or `agent.maxIterations` if the task legitimately needs more turns",
         ],
         meta,
     });

package/dist/jobs/manager.js

@@ -2,7 +2,8 @@ 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 { 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 { JobLogRenderer } from "./log-renderer.js";

package/dist/subagent/index.d.ts

@@ -1,5 +1,4 @@
 export * from "./types.js";
-export * from "./budget.js";
 export * from "./semaphore.js";
 export * from "./registry-scope.js";
 export * from "./orchestrator.js";

package/dist/subagent/index.js

@@ -1,5 +1,4 @@
 export * from "./types.js";
-export * from "./budget.js";
 export * from "./semaphore.js";
 export * from "./registry-scope.js";
 export * from "./orchestrator.js";

package/dist/subagent/orchestrator.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import { runAgent } from "../agent/loop.js";
 import { CruxyError, ErrorCode, messageOf, subagentDepthExceeded, subagentScopeOverlap, } from "../errors/index.js";
 import { Workspace } from "../workspace/index.js";
-import { Budget, resolveBudget } from "./budget.js";
+import { Budget, resolveBudget } from "../agent/budget.js";
 import { scopeRegistry, SUBAGENT_WRITE_TOOLS } from "./registry-scope.js";
 import { Semaphore } from "./semaphore.js";
 import { makeSpawnSubagentTool } from "./spawn-tool.js";

package/dist/subagent/types.d.ts

@@ -1,5 +1,7 @@
 import type { Usage } from "@cruxy/sdk";
 import type { TaskClass } from "../routing/index.js";
+import type { BudgetLimits } from "../agent/budget.js";
+export type { BudgetLimits };
 /**
  * Types for subagent orchestration (C.14): the main agent delegates a bounded
  * subtask to a child agent that runs the SAME loop with its own fresh history,
@@ -14,19 +16,6 @@ import type { TaskClass } from "../routing/index.js";
  * dressed up as `done`.
  */
 export type SubagentStatus = "done" | "budget-exceeded" | "failed" | "cancelled";
-/**
- * Hard caps a subagent runs under. `maxIterations` and `maxTokens` are always
- * finite — a subagent is bounded by construction; `timeoutMs` is an optional
- * wall-clock backstop on top.
- */
-export interface BudgetLimits {
-    /** Cap on the subagent's model turns. */
-    maxIterations: number;
-    /** Cap on the subagent's combined input+output tokens. */
-    maxTokens: number;
-    /** Optional wall-clock cap in milliseconds. */
-    timeoutMs?: number;
-}
 /** A spawn request: the bounded task plus optional scope/budget narrowing. */
 export interface SubagentSpec {
     /** The complete, self-contained subtask the subagent should perform. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.28.2",
+  "version": "0.29.2",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
     "undici": "^6.21.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.5",
-    "@cruxy/sdk": "0.2.0"
+    "@cruxy/sdk": "0.2.1"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",

package/dist/subagent/budget.d.ts

@@ -1,34 +0,0 @@
-import type { Usage } from "@cruxy/sdk";
-import type { LoopBudget } from "../agent/loop.js";
-import type { BudgetLimits } from "./types.js";
-/**
- * The subagent budget (C.14): iteration + token + optional wall-clock caps,
- * checked by the agent loop before every model turn (see `LoopBudget`). A
- * tripped cap stops the run with a human-readable reason — the subagent
- * returns a partial result, it never runs unbounded.
- */
-/**
- * Resolve the effective limits for one spawn: start from the configured
- * ceilings and let overrides only *narrow* them. A request above a ceiling is
- * clamped down, not honored — "budget overrides within limits" by construction.
- */
-export declare function resolveBudget(defaults: BudgetLimits, overrides?: Partial<BudgetLimits>): BudgetLimits;
-/**
- * A live budget for one subagent run. The wall clock starts at construction
- * (spawn time); the clock source is injectable so tests never sleep.
- */
-export declare class Budget implements LoopBudget {
-    private readonly limits;
-    private readonly now;
-    private readonly startedAt;
-    constructor(limits: BudgetLimits, now?: () => number);
-    /**
-     * The reason to stop before the next model turn, or `null` to continue.
-     * Checked at iteration boundaries — the in-flight turn always completes, so
-     * overshoot is bounded by one turn.
-     */
-    exceeded(state: {
-        iterations: number;
-        usage: Usage;
-    }): string | null;
-}