@molecule/api-ai-tools 1.6.4 → 1.6.6

package/dist/command-position.js

@@ -22,7 +22,7 @@
  * (`head -30 run-api-tests-hurl.sh`, `grep -n playwright e2e/README.md`,
  * `git show HEAD:run-api-tests.sh`), and a runner named in a heredoc body — a file a command
  * WRITES is the caller's business, so a command with a heredoc goes through the caller's own
- * stripper first (`withoutHeredocs` in molecule-dev's suite checks).
+ * stripper first (`withoutHeredocs`, in `./suite-overlap.js`).
  *
  * @module
  */
@@ -92,6 +92,22 @@ const WRAPPER_VALUE_FLAGS = {
 const ENV_ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
 /** A wrapper's own duration — `timeout 280 …`, `timeout 1m …` — which is not a flag. */
 const DURATION = /^\d+(?:\.\d+)?[smhd]?$/;
+/** The seconds a `timeout` duration word names (`280`, `1m`, `1.5h`), or null when it is none. */
+const DURATION_UNITS = { s: 1, m: 60, h: 3600, d: 86_400 };
+/**
+ * The seconds a duration word stands for.
+ *
+ * @param word - A duration (`280`, `20s`, `1m`).
+ * @returns The seconds, or null when the word is not a duration.
+ */
+export function durationSeconds(word) {
+    if (!DURATION.test(word))
+        return null;
+    const [, number = '', unit = 's'] = /^(\d+(?:\.\d+)?)([smhd]?)$/.exec(word) ?? [];
+    const scale = DURATION_UNITS[unit] ?? 1;
+    const seconds = Number(number) * scale;
+    return Number.isFinite(seconds) ? seconds : null;
+}
 /**
  * A word without its shell quotes.
  *
@@ -155,14 +171,16 @@ function nestedCommand(words, from) {
     return null;
 }
 /**
- * Where the program starts in one segment's words.
+ * Where the program starts in one segment's words, and the bound the segment puts on itself.
  *
  * @param words - The segment's words, quotes kept.
  * @returns The index of the word in command position (one past the end when the segment runs
- *   nothing), and the command string of a `sh -c '<command>'` this segment turns out to be.
+ *   nothing), the command string of a `sh -c '<command>'` this segment turns out to be, and the
+ *   seconds its own `timeout` wrapper allows that command (`timeout 280 hurl …` → 280) or null.
  */
 function commandStart(words) {
     let at = 0;
+    let timeoutSeconds = null;
     for (let guard = 0; guard < MAX_WRAPPERS && at < words.length; guard++) {
         const word = words[at] ?? '';
         if (ENV_ASSIGNMENT.test(word)) {
@@ -178,7 +196,7 @@ function commandStart(words) {
         if (SHELLS.has(name)) {
             const nested = nestedCommand(words, at + 1);
             if (nested !== null)
-                return { at, nested };
+                return { at, nested, timeoutSeconds };
             at += 1 + flagWords(words, at + 1, name);
             continue;
         }
@@ -192,12 +210,14 @@ function commandStart(words) {
             continue;
         }
         if (!LAUNCHERS.has(name))
-            return { at, nested: null };
+            return { at, nested: null, timeoutSeconds };
         at += 1 + flagWords(words, at + 1, name);
-        if (name === 'timeout' && DURATION.test(words[at] ?? ''))
+        if (name === 'timeout' && DURATION.test(words[at] ?? '')) {
+            timeoutSeconds = durationSeconds(words[at] ?? '');
             at += 1;
+        }
     }
-    return { at, nested: null };
+    return { at, nested: null, timeoutSeconds };
 }
 /**
  * A command's statements and pipeline stages, split where the shell splits them — inside quotes
@@ -206,50 +226,84 @@ function commandStart(words) {
  * A single `&` separates only when it backgrounds a command: the one in a redirect (`2>&1`,
  * `&>log`) is part of the word it sits in.
  *
+ * The nestings are a STACK, not a (quote, depth) pair, because they interleave: a command
+ * substitution opened inside a double quote can itself hold double quotes, and each of those can
+ * hold another substitution. `DIR="$(cd "$(dirname "$0")" && pwd)"` is exactly that shape — it
+ * opens `"`, `$(`, `"`, `$(`, `"` in order — and every runner script of the RealWorld kind has it.
+ * A flat walk read that first inner `"` as the CLOSE of the outer one, so the `)` that ends the
+ * outer substitution landed inside a quote that was never opened, the depth was left standing at
+ * 1, and every newline in the rest of the script was swallowed: the script's own `hurl --test`
+ * never reached command position, and X1 xr-molecule-flash-m89 saw seven passing Hurl runs the
+ * platform could not see (the runner is read from the tree's own script TEXT —
+ * `molecule-dev/api/src/ai/supplied-tree-guard.ts` — so a script that does not classify records
+ * no runner, and every run of it reads as nothing).
+ *
  * @param command - The shell command.
  * @returns Each segment's text, in order, with empty ones dropped.
  */
 function splitSegments(command) {
     const parts = [];
     let buffer = '';
-    let quote = null;
-    let substitutions = 0;
+    /** The nestings this position sits inside, outermost first. */
+    const stack = [];
     for (let i = 0; i < command.length; i++) {
         const char = command[i] ?? '';
-        if (quote !== null) {
+        const next = command[i + 1];
+        const top = stack[stack.length - 1];
+        // A single-quoted string expands nothing at all: no escape, no substitution, and no quote
+        // but its own ends it.
+        if (top === 'single') {
             buffer += char;
-            if (char === '\\' && quote === '"' && i + 1 < command.length) {
-                buffer += command[i + 1] ?? '';
-                i += 1;
-            }
-            else if (char === quote)
-                quote = null;
+            if (char === "'")
+                stack.pop();
             continue;
         }
-        if (char === '"' || char === "'") {
-            quote = char;
+        // A command substitution, wherever a shell opens one — inside double quotes too, and never
+        // inside single quotes (handled above). The `(` is consumed here so the depth is counted once.
+        if (char === '$' && next === '(') {
+            stack.push('sub');
+            buffer += '$(';
+            i += 1;
+            continue;
+        }
+        // Inside double quotes: a `"` closes them, a backslash escapes the next character (so
+        // `"\$("` opens nothing), and everything else is literal — a `'`, a `|`, a newline included.
+        if (top === 'double') {
+            if (char === '"')
+                stack.pop();
+            else if (char === '\\' && next !== undefined) {
+                buffer += char + next;
+                i += 1;
+                continue;
+            }
             buffer += char;
             continue;
         }
-        if (char === '\\' && i + 1 < command.length) {
-            buffer += char + (command[i + 1] ?? '');
-            i += 1;
+        if (char === '"') {
+            stack.push('double');
+            buffer += char;
             continue;
         }
-        if (char === '$' && command[i + 1] === '(') {
-            substitutions += 1;
+        if (char === "'") {
+            stack.push('single');
             buffer += char;
             continue;
         }
-        if (substitutions > 0) {
+        // Inside a substitution or a subshell of one: its own parentheses nest, its `|`/`;`/`&&`
+        // belong to the nested command, and its newlines are that command's too.
+        if (top === 'sub') {
             if (char === '(')
-                substitutions += 1;
+                stack.push('sub');
             else if (char === ')')
-                substitutions -= 1;
+                stack.pop();
             buffer += char;
             continue;
         }
-        const next = command[i + 1];
+        if (char === '\\' && next !== undefined) {
+            buffer += char + next;
+            i += 1;
+            continue;
+        }
         if ((char === '&' && next === '&') || (char === '|' && next === '|')) {
             parts.push(buffer);
             buffer = '';
@@ -301,6 +355,28 @@ function segmentWords(text) {
 export function commandSegments(command) {
     return segmentsOf(command, 0);
 }
+/**
+ * The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
+ * under (`timeout 280 hurl --test …` → 280), or null when it carries none.
+ *
+ * This is the bound `man timeout` enforces by KILLING the command — so a run that used it did not
+ * finish, whatever the pipeline's own exit status says. It is read here, from the same parse every
+ * other command reader uses, rather than matched as text: `timeout` in an argument
+ * (`grep -n 'timeout 280' notes.md`) bounds nothing, and `-k 5` is the grace before the kill, not
+ * the bound ({@link WRAPPER_VALUE_FLAGS}).
+ *
+ * @param command - The shell command.
+ * @returns The seconds the command allows itself, or null.
+ */
+export function commandTimeoutSeconds(command) {
+    let bound = null;
+    for (const segment of segmentsOf(command, 0)) {
+        if (segment.timeoutSeconds === null)
+            continue;
+        bound = bound === null ? segment.timeoutSeconds : Math.max(bound, segment.timeoutSeconds);
+    }
+    return bound;
+}
 /**
  * {@link commandSegments}'s recursion, so a `sh -c '<command>'` is opened as far as
  * {@link MAX_NESTING} allows.
@@ -328,7 +404,12 @@ function segmentsOf(command, depth) {
             continue;
         const program = programName(word);
         const args = words.slice(start.at + 1);
-        out.push({ program, args, text: [program, ...args].join(' ') });
+        out.push({
+            program,
+            args,
+            text: [program, ...args].join(' '),
+            timeoutSeconds: start.timeoutSeconds,
+        });
     }
     return out;
 }

package/dist/cut-run.d.ts

@@ -0,0 +1,124 @@
+/**
+ * A command that a budget stopped before it finished, and the state its result carries so no
+ * reader can mistake it for a run that ended.
+ *
+ * X1 xr-molecule-flash-m93 (2026-10-16, +12:37) sent the supplied RealWorld suite as
+ * `timeout 280 hurl --test --continue-on-error --jobs 1 … hurl/*.hurl 2>&1 | tail -60` and got
+ * back `exitCode: 0`, four finished files' lines and nothing else. Two lies in one result: the
+ * `timeout 280` killed the run at 280 s, and the `| tail` made the pipeline's status the status —
+ * so the executor read a suite that stopped at its fifth file as a suite that ran and nearly
+ * passed, fixed one message, and immediately sent the same 280-second command again (the run's
+ * third, ~14 minutes of a 60-minute cap across three of them).
+ *
+ * So the tool never reports a stopped run as `exitCode: 0`. Such a result carries
+ * `status: 'cut_at_budget'` and an exit code that is `null` whenever the number the pipeline
+ * reported belongs to the filter rather than to the run, and every reader of a run's verdict reads
+ * the state through {@link commandRunState} — a cut run is NOT RUN, never a pass.
+ *
+ * Two things stop a run, and both are read from the command and the result, never inferred:
+ *
+ * 1. **Its own bound** — a `timeout <N>` the command carries ({@link commandTimeoutSeconds}). The
+ *    run used it, so the run was killed at it; with no closing tally in the output, the run did
+ *    not finish. This is m93's shape.
+ * 2. **This tool's budget** — the backend runs the command under `timeout` (see
+ *    `backends/sandbox.ts`), which reports 124 whatever the pipeline did, and returns everything
+ *    printed until then. The budget is the tool's own, so its number belongs to the tool.
+ *
+ * @module
+ */
+/**
+ * The state a result carries when a budget stopped its command: a run that did not finish is not a
+ * run that passed, and no reader may treat it as one.
+ */
+export declare const CUT_AT_BUDGET = "cut_at_budget";
+/** What a command's result records: a run that ended, or one a budget stopped. */
+export type CommandRunState = 'ran' | typeof CUT_AT_BUDGET;
+/**
+ * The state a command's result records — THE reader every verdict about a run goes through.
+ *
+ * A result that carries no state is a run that ended: the state is written where the run is
+ * stopped ({@link commandCutRun}), so a result without it was never stopped by a budget this
+ * platform set or can see. Results produced before this state existed read the same way, which is
+ * what keeps a past turn's tally readable.
+ *
+ * @param result - The exec_command / wait_for_task result.
+ * @returns The state the result records.
+ */
+export declare function commandRunState(result: unknown): CommandRunState;
+/**
+ * Whether text carries a runner's closing summary ({@link SUITE_TALLY}).
+ *
+ * @param text - The run's stdout and stderr.
+ * @returns True when the runner's own end-of-run summary is there.
+ */
+export declare function suiteTally(text: string): boolean;
+/** What stopped a run. */
+export type CutBy = 'tool-budget' | 'command-timeout';
+/** A run a budget stopped, as its result reports it. */
+export interface CutRun {
+    /** The bound the run was allowed, in seconds. */
+    seconds: number;
+    /** Whether this tool's budget stopped it or the `timeout` the command carried. */
+    stoppedBy: CutBy;
+    /**
+     * The exit code the run's own process reported, or null when the code in the result belongs to
+     * the pipeline's filter (`… | tail`) rather than to the run — the case that read as success.
+     */
+    exitCode: number | null;
+    /** How many files or tests the runner's own output shows finishing, or null when it shows none. */
+    ran: number | null;
+    /** How many the run was walking, when the runner printed it (Playwright's `[n/K]`), or null. */
+    total: number | null;
+    /** The noun the runner counts in. */
+    noun: 'files' | 'tests';
+    /** The last thing the run printed — the line a reader looks at first. */
+    doing: string | null;
+}
+/**
+ * The run a command's result records as stopped by a budget, or null when the result is a run that
+ * ended (or says nothing about a run).
+ *
+ * Evidence, in order — never a guess:
+ *
+ * - `timeout`'s own 124 (the code the backend's wrapper returns whenever the TOOL's budget fired,
+ *   whatever the pipeline ended with) — and, when the clock says the command's own smaller bound
+ *   ran out first and less than the budget, that bound instead.
+ * - the command carried its own `timeout <N>`, N is inside this tool's budget (a larger one never
+ *   fires — the tool's does), the run used N, and no runner printed a closing summary: the run was
+ *   killed at its own bound. Its exit code, when the pipeline handed one back, is the filter's.
+ * - the run used this tool's whole budget behind a filter that withheld its output, and printed no
+ *   closing summary: the budget stopped it, and no code in the result is the run's.
+ *
+ * @param command - The command the executor sent.
+ * @param result - Its result.
+ * @param elapsedMs - How long the command ran, in ms.
+ * @param budgetSeconds - This tool's foreground budget, in seconds (0 when it has none).
+ * @returns The stopped run, or null.
+ */
+export declare function commandCutRun(command: string, result: unknown, elapsedMs: number, budgetSeconds?: number): CutRun | null;
+/**
+ * The facts a result records about the run a budget stopped it in — what a reader needs to say
+ * how far the run got WITHOUT re-reading its log or re-deriving the counts.
+ *
+ * The numbers are read from the runner's own output where it printed them (Hurl's per-file lines,
+ * Playwright's `[n/K]`), so a caller that can also see the suite itself — the file count of the
+ * `*.hurl` directory the run walked — fills in the `total` this could not know, and both then say
+ * the same sentence ({@link cutRunSentence}).
+ *
+ * @param result - The exec_command / wait_for_task result.
+ * @returns The facts the result carries, or null when it records no stopped run.
+ */
+export declare function cutRunFacts(result: unknown): CutRun | null;
+/**
+ * The first line of a stopped run's result: how long it was allowed, what stopped it, how far it
+ * got, and the last thing it printed.
+ *
+ * Written to be quotable by the model in one sentence and to leave no room for "nearly passing":
+ * the counts come from the runner's own output ({@link runProgress}), and a `total` the caller
+ * read elsewhere (the suite's own file count) fills in the "M of K" it can then state.
+ *
+ * @param run - The stopped run.
+ * @returns The sentence.
+ */
+export declare function cutRunSentence(run: CutRun): string;
+//# sourceMappingURL=cut-run.d.ts.map

package/dist/cut-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cut-run.d.ts","sourceRoot":"","sources":["../src/cut-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAKH;;;GAGG;AACH,eAAO,MAAM,aAAa,kBAAkB,CAAA;AAE5C,kFAAkF;AAClF,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,OAAO,aAAa,CAAA;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,CAGhE;AA0BD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,0BAA0B;AAC1B,MAAM,MAAM,KAAK,GAAG,aAAa,GAAG,iBAAiB,CAAA;AAErD,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,SAAS,EAAE,KAAK,CAAA;IAChB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,mGAAmG;IACnG,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,gGAAgG;IAChG,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,qCAAqC;IACrC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IACvB,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AA2CD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,SAAI,GAChB,MAAM,GAAG,IAAI,CA2Df;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgB1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAkBlD"}

package/dist/cut-run.js

@@ -0,0 +1,267 @@
+/**
+ * A command that a budget stopped before it finished, and the state its result carries so no
+ * reader can mistake it for a run that ended.
+ *
+ * X1 xr-molecule-flash-m93 (2026-10-16, +12:37) sent the supplied RealWorld suite as
+ * `timeout 280 hurl --test --continue-on-error --jobs 1 … hurl/*.hurl 2>&1 | tail -60` and got
+ * back `exitCode: 0`, four finished files' lines and nothing else. Two lies in one result: the
+ * `timeout 280` killed the run at 280 s, and the `| tail` made the pipeline's status the status —
+ * so the executor read a suite that stopped at its fifth file as a suite that ran and nearly
+ * passed, fixed one message, and immediately sent the same 280-second command again (the run's
+ * third, ~14 minutes of a 60-minute cap across three of them).
+ *
+ * So the tool never reports a stopped run as `exitCode: 0`. Such a result carries
+ * `status: 'cut_at_budget'` and an exit code that is `null` whenever the number the pipeline
+ * reported belongs to the filter rather than to the run, and every reader of a run's verdict reads
+ * the state through {@link commandRunState} — a cut run is NOT RUN, never a pass.
+ *
+ * Two things stop a run, and both are read from the command and the result, never inferred:
+ *
+ * 1. **Its own bound** — a `timeout <N>` the command carries ({@link commandTimeoutSeconds}). The
+ *    run used it, so the run was killed at it; with no closing tally in the output, the run did
+ *    not finish. This is m93's shape.
+ * 2. **This tool's budget** — the backend runs the command under `timeout` (see
+ *    `backends/sandbox.ts`), which reports 124 whatever the pipeline did, and returns everything
+ *    printed until then. The budget is the tool's own, so its number belongs to the tool.
+ *
+ * @module
+ */
+import { commandTimeoutSeconds } from './command-position.js';
+import { isSuiteRunCommand } from './utilities.js';
+/**
+ * The state a result carries when a budget stopped its command: a run that did not finish is not a
+ * run that passed, and no reader may treat it as one.
+ */
+export const CUT_AT_BUDGET = 'cut_at_budget';
+/**
+ * The state a command's result records — THE reader every verdict about a run goes through.
+ *
+ * A result that carries no state is a run that ended: the state is written where the run is
+ * stopped ({@link commandCutRun}), so a result without it was never stopped by a budget this
+ * platform set or can see. Results produced before this state existed read the same way, which is
+ * what keeps a past turn's tally readable.
+ *
+ * @param result - The exec_command / wait_for_task result.
+ * @returns The state the result records.
+ */
+export function commandRunState(result) {
+    if (result === null || typeof result !== 'object')
+        return 'ran';
+    return result.status === CUT_AT_BUDGET ? CUT_AT_BUDGET : 'ran';
+}
+/**
+ * The gap between a bound and the elapsed time a run killed at it reports. Zero, and deliberately
+ * not a tolerance: a command killed at its bound reports AT LEAST the bound (the shell's own
+ * bookkeeping runs after the kill, and this tool's round trip is on top), so any slack would only
+ * make a SHORT bound fire on a run that finished inside it (`timeout 5 curl …` answering in 3 s).
+ * A run that finished near its bound carried its runner's closing summary — {@link suiteTally}.
+ *
+ * @param boundSeconds - The bound the run was allowed.
+ * @returns The elapsed ms a run stopped at that bound reports at least.
+ */
+function atBoundMs(boundSeconds) {
+    return boundSeconds * 1000;
+}
+/**
+ * A runner's closing summary, printed only by a run that walked its whole suite: Hurl's
+ * `Executed files:` block and the `N passed` / `N failed` / `N flaky` line Playwright and Vitest
+ * print when they finish.
+ *
+ * This is what separates "stopped at the bound" from "used the bound and finished": a suite that
+ * printed its summary ran to its end, and is read as the run it was.
+ */
+const SUITE_TALLY = /\bExecuted files:\s*\d+|\b\d+\s+(?:passed|failed|flaky|skipped)\b/;
+/**
+ * Whether text carries a runner's closing summary ({@link SUITE_TALLY}).
+ *
+ * @param text - The run's stdout and stderr.
+ * @returns True when the runner's own end-of-run summary is there.
+ */
+export function suiteTally(text) {
+    return SUITE_TALLY.test(text);
+}
+/** The last thing a run printed: its last non-blank line, as one line and short enough to quote. */
+function lastPrinted(text) {
+    const lines = text.split('\n');
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const line = (lines[i] ?? '').trim();
+        if (line)
+            return line.length > 180 ? `${line.slice(0, 177)}…` : line;
+    }
+    return null;
+}
+/** Hurl's per-file line: `Success hurl/articles.hurl (17 request(s) in 318 ms)`. */
+const HURL_FILE_LINE = /^(?:Success|Failure)\s+(\S+)/gm;
+/** Playwright's progress line — `[5/13] specs/auth.spec.ts:10:5 › signs up`. */
+const PROGRESS_LINE = /^\s*\[(\d+)\/(\d+)\]/gm;
+/**
+ * What the runner's own output says the run got through.
+ *
+ * Hurl prints a line per finished file and no total unless it finished; Playwright's line reporter
+ * prints `[n/K]` with both numbers. Neither is inferred from the command — a run that printed
+ * nothing says nothing, which is what `null` means here.
+ *
+ * @param text - The run's stdout and stderr.
+ * @param suite - Whether the command runs a suite.
+ * @returns How many finished, how many the run was walking, and the noun.
+ */
+function runProgress(text, suite) {
+    const files = new Set();
+    for (const m of text.matchAll(HURL_FILE_LINE))
+        files.add(m[1] ?? '');
+    if (files.size > 0)
+        return { ran: files.size, total: null, noun: 'files' };
+    let ran = null;
+    let total = null;
+    for (const m of text.matchAll(PROGRESS_LINE)) {
+        ran = Number(m[1]);
+        total = Number(m[2]);
+    }
+    if (ran !== null)
+        return { ran, total, noun: 'tests' };
+    return { ran: null, total: null, noun: suite ? 'tests' : 'files' };
+}
+/**
+ * The run a command's result records as stopped by a budget, or null when the result is a run that
+ * ended (or says nothing about a run).
+ *
+ * Evidence, in order — never a guess:
+ *
+ * - `timeout`'s own 124 (the code the backend's wrapper returns whenever the TOOL's budget fired,
+ *   whatever the pipeline ended with) — and, when the clock says the command's own smaller bound
+ *   ran out first and less than the budget, that bound instead.
+ * - the command carried its own `timeout <N>`, N is inside this tool's budget (a larger one never
+ *   fires — the tool's does), the run used N, and no runner printed a closing summary: the run was
+ *   killed at its own bound. Its exit code, when the pipeline handed one back, is the filter's.
+ * - the run used this tool's whole budget behind a filter that withheld its output, and printed no
+ *   closing summary: the budget stopped it, and no code in the result is the run's.
+ *
+ * @param command - The command the executor sent.
+ * @param result - Its result.
+ * @param elapsedMs - How long the command ran, in ms.
+ * @param budgetSeconds - This tool's foreground budget, in seconds (0 when it has none).
+ * @returns The stopped run, or null.
+ */
+export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0) {
+    if (typeof command !== 'string' || !command.trim())
+        return null;
+    if (result === null || typeof result !== 'object')
+        return null;
+    if (!Number.isFinite(elapsedMs))
+        return null;
+    const r = result;
+    const exitCode = typeof r.exitCode === 'number' ? r.exitCode : null;
+    const text = `${String(r.stdout ?? '')}\n${String(r.stderr ?? '')}`;
+    // A suite that printed its summary ran to its end, whatever it was wrapped in.
+    if (suiteTally(text))
+        return null;
+    const suite = isSuiteRunCommand(command);
+    const withheld = /\|\s*(?:tail|head|grep|egrep|fgrep|sort|uniq|wc|jq)\b/.test(command);
+    const progress = runProgress(text, suite);
+    const doing = lastPrinted(text);
+    const declared = commandTimeoutSeconds(command);
+    // A command whose own bound is inside this tool's budget is stopped by ITS bound: a larger one
+    // never gets the chance — the backend's `timeout` fires first (see the module doc). With no
+    // tool budget at all (a reader re-reading a background run) the command's own bound is the only
+    // one there is.
+    const ownBoundStops = budgetSeconds === 0 || (declared !== null && declared < budgetSeconds);
+    // `timeout`'s own 124 — the code the backend's wrapper returns when the TOOL's budget fires,
+    // whatever the pipeline ended with (`backends/sandbox.ts`). Which of the two bounds fired is the
+    // clock's to say: a run killed at the tool's budget reports at least the budget, and one killed
+    // at its own bound reports at least that bound and less than the budget.
+    if (budgetSeconds > 0 && exitCode === 124) {
+        const ownFired = declared !== null &&
+            ownBoundStops &&
+            elapsedMs >= atBoundMs(declared) &&
+            elapsedMs < atBoundMs(budgetSeconds);
+        return {
+            seconds: ownFired ? declared : budgetSeconds,
+            stoppedBy: ownFired ? 'command-timeout' : 'tool-budget',
+            exitCode,
+            ...progress,
+            doing,
+        };
+    }
+    if (declared !== null && ownBoundStops && elapsedMs >= atBoundMs(declared)) {
+        return {
+            seconds: declared,
+            stoppedBy: 'command-timeout',
+            // A code the filter produced is not the run's: `… | tail` handed back 0 forever (m93).
+            exitCode: withheld || exitCode === 0 ? null : exitCode,
+            ...progress,
+            doing,
+        };
+    }
+    // The tool's budget with its code masked: the run used the whole budget and the pipeline left
+    // nothing readable of it — no code of its own, and no runner's closing summary.
+    if (budgetSeconds > 0 && withheld && elapsedMs >= atBoundMs(budgetSeconds)) {
+        return {
+            seconds: budgetSeconds,
+            stoppedBy: 'tool-budget',
+            exitCode: exitCode === 0 ? null : exitCode,
+            ...progress,
+            doing,
+        };
+    }
+    return null;
+}
+/**
+ * The facts a result records about the run a budget stopped it in — what a reader needs to say
+ * how far the run got WITHOUT re-reading its log or re-deriving the counts.
+ *
+ * The numbers are read from the runner's own output where it printed them (Hurl's per-file lines,
+ * Playwright's `[n/K]`), so a caller that can also see the suite itself — the file count of the
+ * `*.hurl` directory the run walked — fills in the `total` this could not know, and both then say
+ * the same sentence ({@link cutRunSentence}).
+ *
+ * @param result - The exec_command / wait_for_task result.
+ * @returns The facts the result carries, or null when it records no stopped run.
+ */
+export function cutRunFacts(result) {
+    if (result === null || typeof result !== 'object')
+        return null;
+    if (commandRunState(result) !== CUT_AT_BUDGET)
+        return null;
+    const cut = result.cutRun;
+    if (cut === null || typeof cut !== 'object')
+        return null;
+    const c = cut;
+    if (typeof c.seconds !== 'number' || typeof c.stoppedBy !== 'string')
+        return null;
+    return {
+        seconds: c.seconds,
+        stoppedBy: c.stoppedBy,
+        exitCode: typeof c.exitCode === 'number' ? c.exitCode : null,
+        ran: typeof c.ran === 'number' ? c.ran : null,
+        total: typeof c.total === 'number' ? c.total : null,
+        noun: c.noun === 'tests' ? 'tests' : 'files',
+        doing: typeof c.doing === 'string' && c.doing ? c.doing : null,
+    };
+}
+/**
+ * The first line of a stopped run's result: how long it was allowed, what stopped it, how far it
+ * got, and the last thing it printed.
+ *
+ * Written to be quotable by the model in one sentence and to leave no room for "nearly passing":
+ * the counts come from the runner's own output ({@link runProgress}), and a `total` the caller
+ * read elsewhere (the suite's own file count) fills in the "M of K" it can then state.
+ *
+ * @param run - The stopped run.
+ * @returns The sentence.
+ */
+export function cutRunSentence(run) {
+    const by = run.stoppedBy === 'tool-budget' ? "this tool's limit" : `its own \`timeout ${run.seconds}\``;
+    const lead = `This run was stopped after ${run.seconds}s (${by})`;
+    const count = run.ran !== null && run.total !== null
+        ? `: ${run.ran} of ${run.total} ${run.noun} ran, the rest did not run`
+        : run.ran !== null
+            ? `: ${run.ran} ${run.noun} ran and the rest did not run`
+            : ' before it finished';
+    const doing = run.doing ? `; the last thing it was doing: ${run.doing}` : '';
+    // Why the result carries no code: without this the model reads the missing field as an
+    // omission, and the number it used to read there was the pipeline's own 0.
+    const code = run.exitCode === null
+        ? ' It has no exit code of its own to report — the one this pipeline produced belongs to the filter, not to the run.'
+        : '';
+    return `${lead}${count}${doing}.${code}`;
+}

package/dist/index.d.ts

@@ -51,6 +51,18 @@
  *   `newlineNote` hint beside an unrelated-looking parse error, which an executor
  *   repairs by rewriting the fused line's text and fuses the next one. The
  *   `newlineNote` alone is still returned when the file parses.
+ * - **A replacement that only changes a line break at its boundary is refused,
+ *   not applied.** When `new_string` is `old_string` with its trailing newline
+ *   added or removed and nothing else, the edit can only move text across lines —
+ *   joining the next line onto the replaced text, or pushing the rest of the line
+ *   down — which is what a weak model does by accident when it repeats a line it
+ *   means to keep (flash-m28, m55, m62, m89, five times in the m89 run alone). The
+ *   replacement is skipped, the rest of the batch is applied, and the result
+ *   carries `skippedNote`: one line naming the replacement, what applying it would
+ *   have done, and how to say it on purpose (include the next line in `old_string`).
+ *   The file's own next character decides: text on the same line is a join or a
+ *   split and is refused; a blank line after it, or the end of the file, means no
+ *   text crosses lines and the edit is applied as written.
  * - **A parameter under another name is not a broken tool.** Every tool's input
  *   is normalized first (`cmd` → `command`, `file` → `path`, camelCase ⇄
  *   snake_case), and a handler that throws returns an error naming the missing
@@ -121,9 +133,11 @@ export * from './backends/local.js';
 export * from './backends/sandbox.js';
 export * from './browser-guard.js';
 export * from './command-position.js';
+export * from './cut-run.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
 export * from './schemas.js';
+export * from './suite-overlap.js';
 export * from './system-prompt.js';
 export * from './tools.js';
 export * from './types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsHG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkIG;AAEH,cAAc,qBAAqB,CAAA;AACnC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}