@cruxy/cli 0.27.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/file/apply-patch.js

@@ -2,7 +2,7 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { resolveToolPath } from "./paths.js";
-import { countOccurrences } from "./edit-file.js";
+import { applyEol, detectEol, findMatch, tierLabel } from "./match.js";
 /** How many leading lines of a created file the approval preview shows. */
 const PREVIEW_LINES = 20;
 const HunkSchema = z.object({
@@ -143,25 +143,29 @@ async function planOp(i, op, abs, ctx) {
         }
         return { ok: false, error: opError(i, op, err.message) };
     }
+    // Detect the file's line ending once, from the original bytes, so every hunk
+    // re-encodes newStr to the same convention as content mutates across hunks.
+    const fileEol = detectEol(content);
     for (let h = 0; h < op.hunks.length; h++) {
         const { oldStr, newStr } = op.hunks[h];
-        const matches = countOccurrences(content, oldStr);
-        if (matches === 0) {
+        const match = findMatch(content, oldStr);
+        if (match.kind === "none") {
             return {
                 ok: false,
                 error: opError(i, op, `hunk ${h + 1}: oldStr not found`),
             };
         }
-        if (matches > 1) {
+        if (match.kind === "ambiguous") {
             return {
                 ok: false,
-                error: opError(i, op, `hunk ${h + 1}: oldStr not unique (${matches} matches)`),
+                error: opError(i, op, `hunk ${h + 1}: oldStr not unique (${match.count} matches${tierLabel(match.tier)})`),
             };
         }
-        // Replace by index so `$` patterns in newStr aren't interpreted.
-        const idx = content.indexOf(oldStr);
+        // Splice by offset so `$` patterns in newStr aren't interpreted.
         content =
-            content.slice(0, idx) + newStr + content.slice(idx + oldStr.length);
+            content.slice(0, match.start) +
+                applyEol(newStr, fileEol) +
+                content.slice(match.end);
     }
     return {
         ok: true,

package/dist/tools/file/edit-file.d.ts

@@ -1,7 +1,5 @@
 import { z } from "zod";
 import type { Tool } from "../types.js";
-/** Count non-overlapping exact occurrences of `needle` in `haystack`. */
-export declare function countOccurrences(haystack: string, needle: string): number;
 /**
  * Replace one exact, unique occurrence of `old_str` with `new_str` in a file.
  * The uniqueness requirement is checked before approval so the model can fix an

package/dist/tools/file/edit-file.js

@@ -1,16 +1,7 @@
 import { promises as fs } from "node:fs";
 import { z } from "zod";
 import { resolveToolPath } from "./paths.js";
-/** Count non-overlapping exact occurrences of `needle` in `haystack`. */
-export function countOccurrences(haystack, needle) {
-    let count = 0;
-    let i = haystack.indexOf(needle);
-    while (i !== -1) {
-        count++;
-        i = haystack.indexOf(needle, i + needle.length);
-    }
-    return count;
-}
+import { applyEol, detectEol, findMatch, tierLabel } from "./match.js";
 /**
  * Replace one exact, unique occurrence of `old_str` with `new_str` in a file.
  * The uniqueness requirement is checked before approval so the model can fix an
@@ -47,14 +38,14 @@ export const editFileTool = {
             }
             return { ok: false, error: err.message };
         }
-        const matches = countOccurrences(content, input.old_str);
-        if (matches === 0) {
+        const match = findMatch(content, input.old_str);
+        if (match.kind === "none") {
             return { ok: false, error: `old_str not found in ${input.path}` };
         }
-        if (matches > 1) {
+        if (match.kind === "ambiguous") {
             return {
                 ok: false,
-                error: `old_str not unique (${matches} matches); add surrounding context to disambiguate`,
+                error: `old_str not unique (${match.count} matches${tierLabel(match.tier)}); add surrounding context to disambiguate`,
             };
         }
         const decision = await ctx.requestApproval({
@@ -68,11 +59,11 @@ export const editFileTool = {
                 error: decision.feedback ?? `edit to ${input.path} denied`,
             };
         }
-        // Replace the single occurrence by index to avoid `$`-pattern interpretation.
-        const idx = content.indexOf(input.old_str);
-        const updated = content.slice(0, idx) +
-            input.new_str +
-            content.slice(idx + input.old_str.length);
+        // Splice the matched span by offset (avoids `$`-pattern interpretation) and
+        // re-encode new_str to the file's line ending so a CRLF file stays CRLF.
+        const updated = content.slice(0, match.start) +
+            applyEol(input.new_str, detectEol(content)) +
+            content.slice(match.end);
         try {
             await fs.writeFile(abs, updated, "utf8");
             return { ok: true, output: `edited ${input.path}` };

package/dist/tools/file/match.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Locating `old_str` inside a file for edit_file / apply_patch.
+ *
+ * Models emit `\n` line endings, but a file on disk may be `\r\n` (Windows
+ * checkouts/editors) — a byte-exact `indexOf` then never matches and the model
+ * can't replace existing code. We match in ordered tiers, tightest first, and
+ * stop at the first tier that finds anything:
+ *
+ *   0. exact        — raw bytes; every currently-working edit takes this path
+ *   1. eol          — CRLF and lone CR treated as LF (comparison only)
+ *   2. eol+trailws  — tier 1, plus trailing whitespace ignored per line
+ *
+ * Looser tiers compare against a normalized copy but return offsets into the
+ * ORIGINAL string, so the splice preserves every unmatched byte verbatim (the
+ * file is never wholesale re-encoded). Ambiguity is never resolved by guessing:
+ * more than one match at a tier is a hard error, and we do not fall through to a
+ * looser tier (looser can only be more ambiguous, never less).
+ */
+export type Tier = "exact" | "eol" | "eol+trailws";
+export type MatchResult = {
+    kind: "found";
+    start: number;
+    end: number;
+} | {
+    kind: "ambiguous";
+    count: number;
+    tier: Tier;
+} | {
+    kind: "none";
+};
+/**
+ * Find the single occurrence of `oldStr` in `content`, tolerating line-ending
+ * and trailing-whitespace differences. Returns original-string byte offsets on
+ * a unique match, `ambiguous` if the tightest matching tier had >1 hit, or
+ * `none` if no tier matched.
+ */
+export declare function findMatch(content: string, oldStr: string): MatchResult;
+/** The file's line ending: CRLF if the first newline is `\r\n`, else LF. */
+export declare function detectEol(content: string): "\r\n" | "\n";
+/** Re-encode `text`'s line endings to `eol` so an edit matches the file. */
+export declare function applyEol(text: string, eol: "\r\n" | "\n"): string;
+/** Human phrase for the tier named in an ambiguity error. */
+export declare function tierLabel(tier: Tier): string;

package/dist/tools/file/match.js

@@ -0,0 +1,127 @@
+/**
+ * Locating `old_str` inside a file for edit_file / apply_patch.
+ *
+ * Models emit `\n` line endings, but a file on disk may be `\r\n` (Windows
+ * checkouts/editors) — a byte-exact `indexOf` then never matches and the model
+ * can't replace existing code. We match in ordered tiers, tightest first, and
+ * stop at the first tier that finds anything:
+ *
+ *   0. exact        — raw bytes; every currently-working edit takes this path
+ *   1. eol          — CRLF and lone CR treated as LF (comparison only)
+ *   2. eol+trailws  — tier 1, plus trailing whitespace ignored per line
+ *
+ * Looser tiers compare against a normalized copy but return offsets into the
+ * ORIGINAL string, so the splice preserves every unmatched byte verbatim (the
+ * file is never wholesale re-encoded). Ambiguity is never resolved by guessing:
+ * more than one match at a tier is a hard error, and we do not fall through to a
+ * looser tier (looser can only be more ambiguous, never less).
+ */
+const TIERS = ["exact", "eol", "eol+trailws"];
+/**
+ * Find the single occurrence of `oldStr` in `content`, tolerating line-ending
+ * and trailing-whitespace differences. Returns original-string byte offsets on
+ * a unique match, `ambiguous` if the tightest matching tier had >1 hit, or
+ * `none` if no tier matched.
+ */
+export function findMatch(content, oldStr) {
+    for (const tier of TIERS) {
+        const occ = occurrences(content, oldStr, tier);
+        if (occ.length === 1) {
+            return { kind: "found", start: occ[0].start, end: occ[0].end };
+        }
+        if (occ.length > 1) {
+            return { kind: "ambiguous", count: occ.length, tier };
+        }
+        // 0 matches → try the next, looser tier.
+    }
+    return { kind: "none" };
+}
+/** Non-overlapping occurrences of `oldStr` under `tier`, as original offsets. */
+function occurrences(content, oldStr, tier) {
+    const out = [];
+    if (tier === "exact") {
+        let i = content.indexOf(oldStr);
+        while (i !== -1) {
+            out.push({ start: i, end: i + oldStr.length });
+            i = content.indexOf(oldStr, i + oldStr.length);
+        }
+        return out;
+    }
+    const { norm, map } = normalize(content, tier);
+    const { norm: needle } = normalize(oldStr, tier);
+    // An all-whitespace old_str can normalize to empty under eol+trailws; refuse
+    // to "match everywhere" rather than delete at an arbitrary point.
+    if (needle.length === 0)
+        return out;
+    let i = norm.indexOf(needle);
+    while (i !== -1) {
+        out.push({ start: map[i], end: map[i + needle.length] });
+        i = norm.indexOf(needle, i + needle.length);
+    }
+    return out;
+}
+/**
+ * Build a normalized view of `s` plus `map`, where `map[k]` is the original
+ * offset of the k-th normalized char and `map[norm.length]` is a sentinel
+ * (`s.length`). This lets a match found in normalized space splice back into
+ * the original bytes exactly.
+ */
+function normalize(s, tier) {
+    const stripTrail = tier === "eol+trailws";
+    let norm = "";
+    const map = [];
+    // Whitespace whose trailing-vs-not status isn't known yet: flushed when real
+    // content follows on the line, dropped when a newline / EOF follows.
+    const pending = [];
+    const emit = (ch, off) => {
+        norm += ch;
+        map.push(off);
+    };
+    const flushPending = () => {
+        for (const p of pending)
+            emit(p.ch, p.off);
+        pending.length = 0;
+    };
+    let i = 0;
+    while (i < s.length) {
+        const c = s[i];
+        if (c === "\r" || c === "\n") {
+            pending.length = 0; // any pending whitespace was trailing → drop it
+            emit("\n", i);
+            i += c === "\r" && s[i + 1] === "\n" ? 2 : 1;
+            continue;
+        }
+        if (stripTrail && (c === " " || c === "\t")) {
+            pending.push({ ch: c, off: i });
+            i += 1;
+            continue;
+        }
+        flushPending();
+        emit(c, i);
+        i += 1;
+    }
+    // Trailing whitespace at end-of-string (in `pending`) is intentionally dropped.
+    map.push(s.length);
+    return { norm, map };
+}
+/** The file's line ending: CRLF if the first newline is `\r\n`, else LF. */
+export function detectEol(content) {
+    const i = content.indexOf("\n");
+    return i > 0 && content[i - 1] === "\r" ? "\r\n" : "\n";
+}
+/** Re-encode `text`'s line endings to `eol` so an edit matches the file. */
+export function applyEol(text, eol) {
+    const lf = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    return eol === "\r\n" ? lf.replace(/\n/g, "\r\n") : lf;
+}
+/** Human phrase for the tier named in an ambiguity error. */
+export function tierLabel(tier) {
+    switch (tier) {
+        case "exact":
+            return "";
+        case "eol":
+            return " after end-of-line normalization";
+        case "eol+trailws":
+            return " after end-of-line + trailing-whitespace normalization";
+    }
+}

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.27.0",
+  "version": "0.28.1",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {