@cruxy/cli 0.28.0 → 0.28.1

package/dist/agent/session.js

@@ -99,6 +99,12 @@ export class Session {
      * history is unaffected.
      */
     async send(userPrompt, renderer) {
+        // Per-turn tool lifecycle (C.13): re-arm any per-episode tool state (e.g. the
+        // run_tests consecutive-failure breaker) at the top of the turn, so a fresh
+        // user instruction starts clean. The breaker still latches across the many
+        // model iterations WITHIN this turn — it just never leaks into the next one.
+        for (const tool of this.args.registry.list())
+            tool.onTurnStart?.();
         this.messages.push({ role: "user", content: userPrompt });
         // Usage telemetry (C.22): one collector per run. `onReq` is threaded into
         // every real model request this turn drives — the main loop, compaction, and

package/dist/cli/commands/run.js

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import { logger } from "../../utils/logger.js";
 import { loadConfig, resolveApiKey } from "../../config/index.js";
-import { authMissingKey, shouldUseColor, usageError, } from "../../errors/index.js";
+import { agentIncomplete, authMissingKey, shouldUseColor, usageError, } from "../../errors/index.js";
 import { createRenderer } from "../../render/index.js";
 import { themeForColor } from "../../theme/index.js";
 import { summarizeRuns, renderSummary, } from "../../usage/index.js";
@@ -217,8 +217,9 @@ export function runCommand() {
         // Provider/network/auth failures propagate to the top-level boundary,
         // which classifies them (e.g. CRUXY_E_GATEWAY_UNREACHABLE) and exits with
         // the matching code — a one-shot run must fail non-zero on error.
+        let result;
         try {
-            const result = await session.send(prompt, renderer);
+            result = await session.send(prompt, renderer);
             logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
                 `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
         }
@@ -235,12 +236,26 @@ export function runCommand() {
             await resetMcpServices();
         }
         // End-of-run usage summary (C.22): honest tokens + per-tier breakdown +
-        // cost (only when priced). Printed after the live region is torn down.
-        // Reaches here only on success — a thrown run propagates past it — and
-        // never affects the run's outcome.
+        // cost (only when priced). Printed after the live region is torn down, for
+        // BOTH a completed run and one that gave up below — the tokens burned are
+        // useful either way. A thrown run (provider error) propagates past it.
         if (config.usage.enabled && session.lastRun) {
             printRunUsage(session.lastRun, config);
         }
+        // Fail loud on a non-completed stop (#3/#5): a one-shot run that hit the
+        // iteration cap or a token budget (or was cancelled) MUST exit non-zero —
+        // otherwise CI reads a gave-up run as success. The partial history already
+        // streamed to stdout stands; the boundary prints the coded reason to stderr
+        // and exits with CRUXY_E_AGENT_INCOMPLETE's code. `result` is always set
+        // here — a thrown send would have propagated past this point.
+        if (result && result.stop !== "completed") {
+            throw agentIncomplete({
+                stop: result.stop,
+                iterations: result.iterations,
+                reason: result.stopReason,
+                maxIterations: config.agent.maxIterations,
+            });
+        }
     });
 }
 /** Render the just-finished run's usage as a single themed line (C.22). */

package/dist/config/schema.d.ts

@@ -266,20 +266,20 @@ export declare const SubagentConfigSchema: z.ZodObject<{
         /** Optional wall-clock cap; unset means no time limit. */
         timeoutMs: z.ZodOptional<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
-        maxTokens: number;
         maxIterations: number;
+        maxTokens: number;
         timeoutMs?: number | undefined;
     }, {
         timeoutMs?: number | undefined;
-        maxTokens?: number | undefined;
         maxIterations?: number | undefined;
+        maxTokens?: number | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
     maxDepth: number;
     maxConcurrency: number;
     defaultBudget: {
-        maxTokens: number;
         maxIterations: number;
+        maxTokens: number;
         timeoutMs?: number | undefined;
     };
 }, {
@@ -287,8 +287,8 @@ export declare const SubagentConfigSchema: z.ZodObject<{
     maxConcurrency?: number | undefined;
     defaultBudget?: {
         timeoutMs?: number | undefined;
-        maxTokens?: number | undefined;
         maxIterations?: number | undefined;
+        maxTokens?: number | undefined;
     } | undefined;
 }>;
 /**
@@ -1217,20 +1217,20 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             /** Optional wall-clock cap; unset means no time limit. */
             timeoutMs: z.ZodOptional<z.ZodNumber>;
         }, "strict", z.ZodTypeAny, {
-            maxTokens: number;
             maxIterations: number;
+            maxTokens: number;
             timeoutMs?: number | undefined;
         }, {
             timeoutMs?: number | undefined;
-            maxTokens?: number | undefined;
             maxIterations?: number | undefined;
+            maxTokens?: number | undefined;
         }>>;
     }, "strict", z.ZodTypeAny, {
         maxDepth: number;
         maxConcurrency: number;
         defaultBudget: {
-            maxTokens: number;
             maxIterations: number;
+            maxTokens: number;
             timeoutMs?: number | undefined;
         };
     }, {
@@ -1238,8 +1238,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         maxConcurrency?: number | undefined;
         defaultBudget?: {
             timeoutMs?: number | undefined;
-            maxTokens?: number | undefined;
             maxIterations?: number | undefined;
+            maxTokens?: number | undefined;
         } | undefined;
     }>>;
     jobs: z.ZodDefault<z.ZodObject<{
@@ -1720,8 +1720,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         maxDepth: number;
         maxConcurrency: number;
         defaultBudget: {
-            maxTokens: number;
             maxIterations: number;
+            maxTokens: number;
             timeoutMs?: number | undefined;
         };
     };
@@ -1873,8 +1873,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         maxConcurrency?: number | undefined;
         defaultBudget?: {
             timeoutMs?: number | undefined;
-            maxTokens?: number | undefined;
             maxIterations?: number | undefined;
+            maxTokens?: number | undefined;
         } | undefined;
     } | undefined;
     model?: {

package/dist/errors/constructors.d.ts

@@ -362,6 +362,22 @@ export declare function webFetchFailed(url: string, underlying?: unknown): Cruxy
  */
 export declare function webBlockedHost(url: string, reason: string): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
+/**
+ * A one-shot `cruxy run` ended without completing: the agent loop hit a hard stop
+ * — the iteration cap (`max_iterations`) or a token budget (`budget`) — or was
+ * cancelled (`aborted`). We fail loud with a non-zero exit so CI never reads a
+ * gave-up run as success; the partial work already streamed to stdout is preserved
+ * and the specific reason is named. `stop` is taken as a plain string so this
+ * (low-level) module needn't depend on the agent's result type.
+ */
+export declare function agentIncomplete(info: {
+    stop: string;
+    iterations: number;
+    /** The loop's stopReason (the concrete budget message), when `stop === "budget"`. */
+    reason?: string;
+    /** The turn ceiling in force, surfaced for `max_iterations`. */
+    maxIterations?: number;
+}): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed
  * {@link CruxyError}, or `null` if it isn't one. Order matters: specific

package/dist/errors/constructors.js

@@ -1193,6 +1193,53 @@ export function internal(underlying) {
         underlying,
     });
 }
+// ── one-shot run outcome (exit 20) ───────────────────────────────────────────
+/**
+ * A one-shot `cruxy run` ended without completing: the agent loop hit a hard stop
+ * — the iteration cap (`max_iterations`) or a token budget (`budget`) — or was
+ * cancelled (`aborted`). We fail loud with a non-zero exit so CI never reads a
+ * gave-up run as success; the partial work already streamed to stdout is preserved
+ * and the specific reason is named. `stop` is taken as a plain string so this
+ * (low-level) module needn't depend on the agent's result type.
+ */
+export function agentIncomplete(info) {
+    const { stop, iterations, reason, maxIterations } = info;
+    const turns = `${iterations} turn${iterations === 1 ? "" : "s"}`;
+    const meta = { stop, iterations };
+    if (stop === "budget") {
+        return new CruxyError({
+            code: ErrorCode.AgentIncomplete,
+            title: "cruxy stopped: token budget reached before the task finished",
+            cause: `${reason ?? "the token budget was exhausted"} (after ${turns}). The work so far is shown above.`,
+            nextSteps: [
+                "review the partial output above, then re-run with a narrower prompt",
+                "raise or unset `agent.maxTokensPerTurn` if the task legitimately needs more",
+            ],
+            meta,
+        });
+    }
+    if (stop === "aborted") {
+        return new CruxyError({
+            code: ErrorCode.AgentIncomplete,
+            title: "cruxy stopped: the run was cancelled before the task finished",
+            cause: `cancelled after ${turns}. The work so far is shown above.`,
+            nextSteps: ["re-run to continue in a fresh session"],
+            meta,
+        });
+    }
+    // max_iterations (and any other non-completed stop, defensively).
+    const cap = maxIterations !== undefined ? ` (${maxIterations})` : "";
+    return new CruxyError({
+        code: ErrorCode.AgentIncomplete,
+        title: "cruxy stopped: iteration cap reached before the task finished",
+        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",
+        ],
+        meta,
+    });
+}
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed
  * {@link CruxyError}, or `null` if it isn't one. Order matters: specific

package/dist/errors/types.d.ts

@@ -201,6 +201,11 @@ export declare const ErrorCode: {
      * `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";
+    /** A one-shot `cruxy run` ended WITHOUT completing the task: the agent loop hit
+     * a hard stop (the iteration cap or a token budget) or was cancelled, rather
+     * than finishing on its own. Fail loud with a non-zero exit so CI never reads a
+     * gave-up run as success — the partial work already streamed to stdout stands. */
+    readonly AgentIncomplete: "CRUXY_E_AGENT_INCOMPLETE";
 };
 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

@@ -222,6 +222,12 @@ export const ErrorCode = {
      * `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",
+    // one-shot run outcome (exit 20)
+    /** A one-shot `cruxy run` ended WITHOUT completing the task: the agent loop hit
+     * a hard stop (the iteration cap or a token budget) or was cancelled, rather
+     * than finishing on its own. Fail loud with a non-zero exit so CI never reads a
+     * gave-up run as success — the partial work already streamed to stdout stands. */
+    AgentIncomplete: "CRUXY_E_AGENT_INCOMPLETE",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -343,6 +349,10 @@ const EXIT_CODES = {
     [ErrorCode.JobLimit]: 2,
     [ErrorCode.JobNotFound]: 19,
     [ErrorCode.JobsDisabled]: 19,
+    // One-shot run outcome. A run that hit the iteration cap / token budget (or was
+    // cancelled) without completing gets its own greppable exit code, so CI can tell
+    // "the agent gave up" apart from a provider/auth/config failure.
+    [ErrorCode.AgentIncomplete]: 20,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

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

@@ -19,14 +19,14 @@ declare const parameters: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     task: string;
     root?: string | undefined;
-    maxTokens?: number | undefined;
     maxIterations?: number | undefined;
+    maxTokens?: number | undefined;
     tools?: [string, ...string[]] | undefined;
 }, {
     task: string;
     root?: string | undefined;
-    maxTokens?: number | undefined;
     maxIterations?: number | undefined;
+    maxTokens?: number | undefined;
     tools?: [string, ...string[]] | undefined;
 }>;
 /** Build the `run_in_background` tool bound to the session's job manager. */

package/dist/subagent/spawn-tool.d.ts

@@ -15,13 +15,13 @@ declare const parameters: z.ZodObject<{
     maxTokens: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     task: string;
-    maxTokens?: number | undefined;
     maxIterations?: number | undefined;
+    maxTokens?: number | undefined;
     tools?: [string, ...string[]] | undefined;
 }, {
     task: string;
-    maxTokens?: number | undefined;
     maxIterations?: number | undefined;
+    maxTokens?: number | undefined;
     tools?: [string, ...string[]] | undefined;
 }>;
 /** Build a `spawn_subagent` tool bound to `orchestrator` at `depth`. */
@@ -36,42 +36,42 @@ declare const batchParameters: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         task: string;
         root?: string | undefined;
-        maxTokens?: number | undefined;
         maxIterations?: number | undefined;
+        maxTokens?: number | undefined;
         tools?: [string, ...string[]] | undefined;
     }, {
         task: string;
         root?: string | undefined;
-        maxTokens?: number | undefined;
         maxIterations?: number | undefined;
+        maxTokens?: number | undefined;
         tools?: [string, ...string[]] | undefined;
     }>, "atleastone">;
 }, "strip", z.ZodTypeAny, {
     tasks: [{
         task: string;
         root?: string | undefined;
-        maxTokens?: number | undefined;
         maxIterations?: number | undefined;
+        maxTokens?: number | undefined;
         tools?: [string, ...string[]] | undefined;
     }, ...{
         task: string;
         root?: string | undefined;
-        maxTokens?: number | undefined;
         maxIterations?: number | undefined;
+        maxTokens?: number | undefined;
         tools?: [string, ...string[]] | undefined;
     }[]];
 }, {
     tasks: [{
         task: string;
         root?: string | undefined;
-        maxTokens?: number | undefined;
         maxIterations?: number | undefined;
+        maxTokens?: number | undefined;
         tools?: [string, ...string[]] | undefined;
     }, ...{
         task: string;
         root?: string | undefined;
-        maxTokens?: number | undefined;
         maxIterations?: number | undefined;
+        maxTokens?: number | undefined;
         tools?: [string, ...string[]] | undefined;
     }[]];
 }>;

package/dist/testing/run-tests-tool.d.ts

@@ -10,19 +10,37 @@ import type { TestCommand, TestRunner } from "./types.js";
  */
 /**
  * Counts consecutive FAILING test executions; a green run resets it. When the
- * count reaches the cap, the next attempt is refused with the coded
- * CRUXY_E_TEST_ITERATION_LIMIT result (nothing executes), and the counter
- * resets — so the episode ends loudly, but a deliberate later attempt (a new
- * user instruction) starts fresh rather than finding a permanently dead tool.
+ * count reaches the cap, `trip` LATCHES: every further attempt is refused with
+ * the coded CRUXY_E_TEST_ITERATION_LIMIT result (nothing executes) for the rest
+ * of the episode. Because a refused attempt never runs, {@link record} is never
+ * reached and the counter stays pinned at the cap — the breaker cannot re-arm
+ * itself mid-episode. (This replaces a bug where `trip` zeroed the counter as it
+ * tripped, so the very next call ran again and the "cap" was a speed bump, not a
+ * stop: the model could burn the whole turn re-running a failing suite.)
+ *
+ * The latch is cleared by {@link reset}, called at the top of each user turn
+ * (see `Session.send`) — so a fresh instruction starts with the full budget,
+ * but the model cannot bypass the cap by simply calling the tool again within
+ * one episode. A green run mid-streak still re-arms the budget via {@link record}.
  * Per-turn work stays bounded regardless via `agent.maxIterations`.
  */
 export declare class TestIterationBudget {
     private failedRuns;
     /** Runs already spent in the current failing streak. */
     get spent(): number;
-    /** True when the next run must be refused; resets the streak as it trips. */
+    /**
+     * True when the next run must be refused. Latches at the cap: once the streak
+     * reaches `maxIterations` this keeps returning true (the refused call never
+     * executes, so {@link record} never runs and the counter stays pinned) until
+     * {@link reset} clears it at the next user turn.
+     */
     trip(maxIterations: number): boolean;
     record(passed: boolean): void;
+    /**
+     * Clear the failing streak, re-arming the breaker. Called at the start of each
+     * user turn so a new instruction starts fresh; within one turn the latch holds.
+     */
+    reset(): void;
 }
 declare const parameters: z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;

package/dist/testing/run-tests-tool.js

@@ -12,10 +12,18 @@ import { SandboxTestRunner } from "./sandbox-runner.js";
  */
 /**
  * Counts consecutive FAILING test executions; a green run resets it. When the
- * count reaches the cap, the next attempt is refused with the coded
- * CRUXY_E_TEST_ITERATION_LIMIT result (nothing executes), and the counter
- * resets — so the episode ends loudly, but a deliberate later attempt (a new
- * user instruction) starts fresh rather than finding a permanently dead tool.
+ * count reaches the cap, `trip` LATCHES: every further attempt is refused with
+ * the coded CRUXY_E_TEST_ITERATION_LIMIT result (nothing executes) for the rest
+ * of the episode. Because a refused attempt never runs, {@link record} is never
+ * reached and the counter stays pinned at the cap — the breaker cannot re-arm
+ * itself mid-episode. (This replaces a bug where `trip` zeroed the counter as it
+ * tripped, so the very next call ran again and the "cap" was a speed bump, not a
+ * stop: the model could burn the whole turn re-running a failing suite.)
+ *
+ * The latch is cleared by {@link reset}, called at the top of each user turn
+ * (see `Session.send`) — so a fresh instruction starts with the full budget,
+ * but the model cannot bypass the cap by simply calling the tool again within
+ * one episode. A green run mid-streak still re-arms the budget via {@link record}.
  * Per-turn work stays bounded regardless via `agent.maxIterations`.
  */
 export class TestIterationBudget {
@@ -24,16 +32,25 @@ export class TestIterationBudget {
     get spent() {
         return this.failedRuns;
     }
-    /** True when the next run must be refused; resets the streak as it trips. */
+    /**
+     * True when the next run must be refused. Latches at the cap: once the streak
+     * reaches `maxIterations` this keeps returning true (the refused call never
+     * executes, so {@link record} never runs and the counter stays pinned) until
+     * {@link reset} clears it at the next user turn.
+     */
     trip(maxIterations) {
-        if (this.failedRuns < maxIterations)
-            return false;
-        this.failedRuns = 0;
-        return true;
+        return this.failedRuns >= maxIterations;
     }
     record(passed) {
         this.failedRuns = passed ? 0 : this.failedRuns + 1;
     }
+    /**
+     * Clear the failing streak, re-arming the breaker. Called at the start of each
+     * user turn so a new instruction starts fresh; within one turn the latch holds.
+     */
+    reset() {
+        this.failedRuns = 0;
+    }
 }
 const parameters = z.object({
     command: z
@@ -69,6 +86,12 @@ export function makeRunTestsTool(deps = {}) {
             "Use it to verify changes: run, read the failures, fix, re-run. The edit→re-run loop is " +
             "capped — when the iteration limit trips, stop, summarize the remaining failures, and ask the user.",
         parameters,
+        // Per-turn lifecycle (C.13): a new user instruction re-arms the failing-run
+        // breaker. Within one turn the latch holds (the model can't bypass the cap by
+        // re-calling); across turns a deliberate retry starts fresh.
+        onTurnStart() {
+            budget.reset();
+        },
         async execute(input, ctx) {
             // Resolve the command first: detection failure needs no approval and
             // must be a coded, actionable error — never an invented command.

package/dist/tools/types.d.ts

@@ -241,6 +241,16 @@ export interface Tool<Schema extends ZodTypeAny = ZodTypeAny> {
      * leave it unset and are advertised from their zod schema as before.
      */
     rawInputSchema?: Record<string, unknown>;
+    /**
+     * Optional per-turn lifecycle hook (C.13). {@link Session.send} calls it on
+     * every tool in the session registry at the start of each user turn, before the
+     * model runs. A tool that carries per-episode state — e.g. `run_tests`' consecutive-
+     * failure breaker — resets it here so a fresh instruction starts clean, while that
+     * state still latches across the many model iterations *within* one turn. Tools
+     * with no per-turn state omit it (a subagent/one-shot run is a single episode, so
+     * a missing hook simply means the state lives for that whole run).
+     */
+    onTurnStart?(): void;
     /** Run the tool against validated `input` and the ambient `ctx`. */
     execute(input: z.infer<Schema>, ctx: ToolContext): Promise<ToolResult>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {