@molecule/api-ai-tools 1.6.4 → 1.6.6

package/README.md

@@ -3,7 +3,7 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-16T16:49:27.760Z
+Generated: 2026-10-16T21:18:13.332Z
 -->
 
 # @molecule/api-ai-tools
@@ -73,6 +73,37 @@ interface CommandSegment {
   args: readonly string[]
   /** The program and its arguments as one line — what a runner pattern is matched against. */
   text: string
+  /**
+   * The seconds the segment's own `timeout` wrapper allows the command it runs
+   * (`timeout 280 hurl --test …` → 280), or null when it carries none.
+   */
+  timeoutSeconds: number | null
+}
+```
+
+#### `CutRun`
+
+A run a budget stopped, as its result reports it.
+
+```typescript
+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
 }
 ```
 
@@ -132,6 +163,29 @@ interface ToolSchema {
 }
 ```
 
+#### `SuiteRunInFlight`
+
+One suite run, as the rule that decides whether a second may start beside it reads it.
+
+Both callers describe the runs in flight the same way and ask the same question of them; what
+differs is only which runs each one knows about — the hold reads its ledger of background runs,
+the note reads the one run it is waiting on.
+
+```typescript
+interface SuiteRunInFlight {
+  /** Whether the run invokes a suite at all: a `vitest`/`jest` run is not one, and cannot be. */
+  runsSuite: boolean
+  /** The app and database the run measures, as {@link suiteCommandTarget} keys it. */
+  target: string
+  /**
+   * Whether the command being judged STOPS this run before starting its own — a kill comes first,
+   * so a run the command itself stops is not in the way (xr-molecule-flash-m87's
+   * `kill 19408 … ; npx playwright test …`).
+   */
+  stoppedByCommand?: boolean
+}
+```
+
 #### `ExecutionBackend`
 
 Abstraction over the execution environment.
@@ -420,6 +474,22 @@ interface FailureCause {
 
 ### Types
 
+#### `CommandRunState`
+
+What a command's result records: a run that ended, or one a budget stopped.
+
+```typescript
+type CommandRunState = 'ran' | typeof CUT_AT_BUDGET
+```
+
+#### `CutBy`
+
+What stopped a run.
+
+```typescript
+type CutBy = 'tool-budget' | 'command-timeout'
+```
+
 #### `DiscoveredSkill` _(deprecated)_
 
 Re-export SkillEntry as DiscoveredSkill for backwards compatibility.
@@ -468,6 +538,18 @@ function createSandboxBackend(sandbox: SandboxLike, projectRoot?: string): Execu
 
 **Returns:** A backend that proxies all filesystem calls into the sandbox.
 
+#### `durationSeconds(word)`
+
+The seconds a duration word stands for.
+
+```typescript
+function durationSeconds(word: string): number | null
+```
+
+- `word` — A duration (`280`, `20s`, `1m`).
+
+**Returns:** The seconds, or null when the word is not a duration.
+
 #### `commandSegments(command)`
 
 The segments of a command, each with its program and arguments — the answer every classifier
@@ -481,6 +563,25 @@ function commandSegments(command: string): CommandSegment[]
 
 **Returns:** One entry per statement or pipeline stage that runs something, in order.
 
+#### `commandTimeoutSeconds(command)`
+
+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}).
+
+```typescript
+function commandTimeoutSeconds(command: string): number | null
+```
+
+- `command` — The shell command.
+
+**Returns:** The seconds the command allows itself, or null.
+
 #### `runsInCommandPosition(command, pattern)`
 
 Whether any segment of the command runs a program whose command-position text matches
@@ -499,6 +600,102 @@ function runsInCommandPosition(command: string, pattern: RegExp): boolean
 
 **Returns:** True when a segment in command position matches.
 
+#### `commandRunState(result)`
+
+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.
+
+```typescript
+function commandRunState(result: unknown): CommandRunState
+```
+
+- `result` — The exec_command / wait_for_task result.
+
+**Returns:** The state the result records.
+
+#### `suiteTally(text)`
+
+Whether text carries a runner's closing summary ({@link SUITE_TALLY}).
+
+```typescript
+function suiteTally(text: string): boolean
+```
+
+- `text` — The run's stdout and stderr.
+
+**Returns:** True when the runner's own end-of-run summary is there.
+
+#### `commandCutRun(command, result, elapsedMs, budgetSeconds)`
+
+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.
+
+```typescript
+function commandCutRun(
+  command: string,
+  result: unknown,
+  elapsedMs: number,
+  budgetSeconds?: number,
+): CutRun | null
+```
+
+- `command` — The command the executor sent.
+- `result` — Its result.
+- `elapsedMs` — How long the command ran, in ms.
+- `budgetSeconds` — This tool's foreground budget, in seconds (0 when it has none).
+
+**Returns:** The stopped run, or null.
+
+#### `cutRunFacts(result)`
+
+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}).
+
+```typescript
+function cutRunFacts(result: unknown): CutRun | null
+```
+
+- `result` — The exec_command / wait_for_task result.
+
+**Returns:** The facts the result carries, or null when it records no stopped run.
+
+#### `cutRunSentence(run)`
+
+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.
+
+```typescript
+function cutRunSentence(run: CutRun): string
+```
+
+- `run` — The stopped run.
+
+**Returns:** The sentence.
+
 #### `normalizeToolInput(schema, raw)`
 
 Move known aliases onto the declared parameter names and report what is still
@@ -606,6 +803,108 @@ function commandRunsNoTests(command: string): boolean
 
 **Returns:** True when the command invokes a runner only to print.
 
+#### `withoutHeredocs(command)`
+
+A command with its heredoc bodies removed: the runs, kills and hosts it names in a file it
+WRITES are not what the command itself does.
+
+The header is kept (`cat > run.sh <<'EOF' …EOF` leaves `cat > run.sh`), which is what the
+readers here want: everything before the body is still readable as the command's own words.
+
+```typescript
+function withoutHeredocs(command: string): string
+```
+
+- `command` — The shell command.
+
+**Returns:** The command without its heredoc bodies.
+
+#### `suiteCommandTarget(command)`
+
+The server a suite command points at, as a comparable key: the host it names (`HOST=`,
+`BASE_URL=`, `PLAYWRIGHT_BASE_URL=`, `--variable host=`, or a bare URL), or `local` for a run
+that names none — a suite run in the sandbox goes to the sandbox's own app unless the command
+says otherwise. Every localhost spelling collapses to `local` (one sandbox, one app, one
+database).
+
+```typescript
+function suiteCommandTarget(command: string): string
+```
+
+- `command` — The suite command.
+
+**Returns:** The target key.
+
+#### `scopedRerunCommand(command, locations)`
+
+The whole-suite command made scoped to the tests it should re-run instead: the same
+invocation — same directory, same settings — with the named `file:line`s in place of the whole
+suite, `--last-failed` dropped (it re-runs the tests that never ran too, X1 flash-m60) and
+`--retries=0` set (a re-run of a known failure does not need to pay for retries).
+
+```typescript
+function scopedRerunCommand(command: string, locations: readonly string[]): string
+```
+
+- `command` — The whole-suite run's command.
+- `locations` — The failing `file:line`s to re-run, as the run's own log printed them — or, for a run that started outside the suite, the absolute form Playwright matches each file argument against.
+
+**Returns:** The scoped command, or the command unchanged when it runs no Playwright suite.
+
+#### `suiteRunInTheWay(candidate, inFlight)`
+
+The run in flight that makes a second run a hazard, or null when nothing is in the way.
+
+This is the ONE rule the mid-run note and the suite-overlap hold both answer with: a suite run
+may start only when this returns null, because two suites against one app and database share its
+rows — the failures one causes the other cannot be told from real ones. A run that invokes no
+suite is never in the way, and neither is one the candidate command stops first.
+
+```typescript
+function suiteRunInTheWay(candidate: { target: string }, inFlight: readonly T[]): T | null
+```
+
+- `candidate` — The run about to start, by the app and database it would measure ({@link suiteCommandTarget}).
+- `inFlight` — The suite runs already going, in the order the caller found them.
+
+**Returns:** The first run in the way, or null.
+
+#### `isDiagnosisRun(command)`
+
+Whether a command walks a PART of a suite instead of all of it: a cap that stops it at a failure
+count, the failures the last run printed (`--last-failed`, `--only-changed`), a title filter, or
+named files/lines.
+
+THE one reading of that question, in one place. Two sites act on the answer and must never
+disagree:
+
+- the command rewriter that adds `--retries=0` to a background Playwright run
+  ({@link ./utilities.js} `streamingBackgroundCommand`) — a diagnosis walks each failure once,
+  while the run the suite is judged by keeps the suite's own retries; and
+- the platform's own notes (molecule-dev's `suite-cli-override.ts`), which must not tell the
+  executor to drop the `--retries=0` the platform itself has just added — the contradiction X1
+  flash-m74 and m75 filed, and m76 filed a third time.
+
+Until xr-molecule-flash-m89 they were a regex and a predicate that only LOOKED alike, and the
+gap was exactly the run the platform had asked for: its `testRunNote` says "run the whole suite
+once with `--max-failures=0`", and the rewriter read that cap flag as a capped diagnosis and
+stripped the suite's retries from the uncapped proof run that follows a deploy — the one run the
+graded run is compared against (+25:03, +31:39, +36:40 and +49:57, the last two against the
+deployed URL, where a network blip is likeliest and the retries it dropped are the ones that
+absorb it).
+
+`--max-failures=0` is Playwright's own "no cap" ({@link boundsFailures}), so it is not a
+
+_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/suite-overlap.d.ts`.)_
+
+```typescript
+function isDiagnosisRun(command: string): boolean
+```
+
+- `command` — The command as the executor sent it.
+
+**Returns:** True when the run is a diagnosis or a re-run, not the whole suite.
+
 #### `discoverSkills(backend)`
 
 Discover skills from a project directory.
@@ -683,6 +982,36 @@ function moleculeDistReadNote(path: string): string | null
 
 **Returns:** The note, or null when the path is not inside a package's `dist`.
 
+#### `installedPackageWriteRefusal(path)`
+
+The refusal for a write whose target is inside an installed package, or null
+when the path is not under a `node_modules` directory.
+
+`node_modules` is not the project's code: nothing written there survives the
+next install, no deploy carries it, and a sandbox whose dependency tree is
+shared (the pre-installed superset) breaks every other run through it. X0
+xr-molecule-flash-m91 (+04:43) called `write_file` on
+`node_modules/@molecule/api-resource-comment/dist/numbers.d.ts` while reading
+the package's declarations and clobbered its runtime module a call later
+(`module.exports = {}` over the ESM handler its own code imports) — the write
+answered `ok: true`, and 18 s went to noticing, `npm pack`-ing the package and
+putting the file back. Reading these files stays allowed (that is how the
+declarations above are read at all).
+
+The restore route is named because the model that has ALREADY clobbered a file
+(this refusal is too late for it) is the one who needs it, and because the
+obvious repair — `npm install <pkg>` — is itself refused in the pre-installed
+sandbox. `npm pack` + a `tar` extraction over the package directory is what
+m91 used, and what both guards leave alone.
+
+```typescript
+function installedPackageWriteRefusal(path: string): string | null
+```
+
+- `path` — An absolute path a tool is about to write.
+
+**Returns:** The one-line refusal naming the package, or null when nothing is installed there.
+
 #### `buildTools(backend, config)`
 
 Build a complete set of AI agent tools bound to an execution backend.
@@ -1044,6 +1373,105 @@ function findPatternArgs(pattern: string): string
 
 **Returns:** A `find` predicate: `-name '…'` for a bare name, else one or more `-path '…'` alternatives, ORed inside parens when there is more than one.
 
+#### `findPathArgs(pattern)`
+
+The `-path` alternatives of {@link findPatternArgs}, for a pattern whose
+directory the caller has already rooted the search at.
+
+`find_files` narrows the search root itself when the pattern spells its own
+directory out (see {@link literalDirPrefix}) — `node_modules` plus
+`@molecule/api-resource-user/dist/*.d.ts` searched that one directory. The
+remainder (`*.d.ts`) must then keep the `-path` form rather than collapsing to
+`-name`: `*` crosses `/` in an fnmatch glob, so the `-path` form still finds a
+declaration file in a `dist/utilities/` subdirectory, which `-name '*.d.ts'`
+would drop (a silent partial answer, which is worse than the timeout it
+replaced).
+
+```typescript
+function findPathArgs(pattern: string): string
+```
+
+- `pattern` — The pattern's remainder, with a `/` in it or not.
+
+**Returns:** One or more `-path '…'` alternatives, ORed inside parens when there is more than one.
+
+#### `literalDirPrefix(pattern)`
+
+The directory a GLOB pattern spells out, when it spells one out: everything
+before the pattern's first glob character, trimmed back to the last `/`.
+
+A pattern is matched against the whole path with a leading "any parent"
+anchor ({@link findPatternArgs}), so `find` visits every entry below the
+search root. Handed `/workspace/node_modules` and
+`@molecule/api-resource-user/dist/*.d.ts` — a directory named outright —
+`find` walked the sandbox's entire dependency tree and hit the tool's 10 s
+deadline without printing a result (xr-molecule-flash-m94: the one directory
+the model meant answered a `list_files` in 0 s). The literal prefix is that
+directory, and rooting the search at it is what keeps the call instant.
+
+A BARE first segment (`helpers/*`, `bonds/*`, `e2e/*.spec.ts`) is NOT one:
+`helpers/*` means "a `helpers/` directory anywhere below the root", which the
+tool documents and a live run relied on (xr-molecule-flash-m77 — a path
+pattern is not anchored to one depth). Rooting those at
+`<root>/helpers` would answer with a SUBSET, silently: the nested
+`api/src/helpers/` matches would disappear, and a missing file reads as
+"no such file". So a prefix is returned only when it names a path of two or
+more segments (`@molecule/api-resource-user/dist`), which is the shape that
+is a directory rather than a directory name.
+
+```typescript
+function literalDirPrefix(pattern: string): string | null
+```
+
+- `pattern` — A pattern already accepted by {@link isValidGlob}.
+
+**Returns:** The literal directory prefix, without a trailing slash, or null when the pattern has no glob character, no `/`, or only a bare name before one.
+
+#### `isCommandTimeout(error)`
+
+Whether a backend error is the sandbox's own command deadline.
+
+The E2B SDK answers a timed-out `exec` with its generic text —
+`[deadline_exceeded] the operation timed out: … It can be modified by passing
+'timeoutMs' when making the request. Use '0' to disable the timeout.` — which
+names an option the executor cannot set and says nothing about the search
+that died. Handing that sentence to the model is what xr-molecule-flash-m94
+read after `find_files` spent 10 s walking `node_modules`; the tool answers
+the deadline in its own words instead (see {@link searchTimeoutError}).
+
+```typescript
+function isCommandTimeout(error: unknown): boolean
+```
+
+- `error` — The error the backend threw.
+
+**Returns:** True when the error reads as a timeout or a deadline.
+
+#### `searchTimeoutError(tool, searched, pattern, seconds, hint)`
+
+The answer a search tool gives when the backend's deadline fires: what was
+searched, for what, how long the tool allowed, and the two ways to get an
+answer — a narrower `path`, or a listing. Never the vendor's `timeoutMs`
+sentence (see {@link isCommandTimeout}).
+
+```typescript
+function searchTimeoutError(
+  tool: string,
+  searched: string,
+  pattern: string,
+  seconds: number,
+  hint: string,
+): string
+```
+
+- `tool` — The tool that timed out (`find_files`, `search_files`).
+- `searched` — The directory the search actually covered.
+- `pattern` — The pattern it was searching for.
+- `seconds` — The tool's own limit, in seconds.
+- `hint` — What to do differently — the narrower target or the listing tool.
+
+**Returns:** The message's text.
+
 #### `pathArgError(path, tool)`
 
 Validate a file tool's `path` argument is a non-empty string. A weak model
@@ -1364,6 +1792,31 @@ function failureCausesNote(log: string): string | null
 
 **Returns:** The note, or null.
 
+#### `rerunOfRunningSuite(run, locations)`
+
+The command that re-runs the tests at `locations` the way the run IN FLIGHT ran them: the same
+invocation, in the same directory, narrowed to those tests — or null when the running command
+is not a Playwright run this can narrow.
+
+The `locations` are the paths the run's own log printed, which are relative to the directory
+that run started in, so a re-run has to resolve them there: the command names that directory
+unless it already changes into one of its own, because the executor's next command starts
+wherever it starts. The returned command is for AFTER the run ends — it is a second run against
+the same app and database, and that is exactly what is refused while the run walks
+({@link suiteRunInTheWay}).
+
+```typescript
+function rerunOfRunningSuite(
+  run: { command: string; cwd?: string },
+  locations: readonly string[],
+): string | null
+```
+
+- `run` — The run in flight: the command it was started with, as it was run, and the directory that command ran in.
+- `locations` — The failing `file:line`s to re-run, as the run's log printed them.
+
+**Returns:** The re-run command, or null when there is no suite to narrow.
+
 #### `repeatingFailureNote(found, o)`
 
 The sentence that names a cause repeating among a running suite's failures, mid-run.
@@ -1379,15 +1832,30 @@ cause was certain at the third, 47 s in, and the note answers exactly that; X1 f
 stopped eight runs at their first repeating cause in 14.5 minutes and never finished one, so
 the note must not say to stop when the run still has other causes to name.
 
+The run is STILL WALKING while this note is written — both callers produce it mid-run — so a
+re-run of one of its tests is a second run against the same app and database, and the platform
+refuses that ({@link suiteRunInTheWay}, the same rule its overlap hold answers with):
+xr-molecule-flash-m89 (2026-10-16) read _"Start on them now, while the run keeps walking.
+`null-fields.spec.ts:53` alone reproduces the first one."_ and sent exactly that re-run 23 s
+later, where the hold answered *"A playwright suite is already running against this app and
+
+_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/utilities.d.ts`.)_
+
 ```typescript
 function repeatingFailureNote(
   found: RepeatingFailure,
-  o: { taskId: string; log: string; stop: string; universal?: UniversalCause | null },
+  o: {
+    taskId: string
+    log: string
+    stop: string
+    universal?: UniversalCause | null
+    run?: { command: string; cwd?: string }
+  },
 ): string
 ```
 
 - `found` — What {@link repeatingFailure} found.
-- `o` — The run's facts: its `taskId`, its `log` path, `stop` — the shell command that stops it, printed only for a {@link UniversalCause} — and `universal`, what {@link universalCause} found (absent means the run is not failing whole).
+- `o` — The run's facts: its `taskId`, its `log` path, `stop` — the shell command that stops it, printed only for a {@link UniversalCause} — `universal`, what {@link universalCause} found (absent means the run is not failing whole), and `run`, how the run was started ({@link rerunOfRunningSuite}) when the caller knows it.
 
 **Returns:** The note.
 
@@ -1469,6 +1937,15 @@ function fusedLine(content: string, newString: string): { line: number; text: st
 
 ### Constants
 
+#### `CUT_AT_BUDGET`
+
+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.
+
+```typescript
+const CUT_AT_BUDGET: 'cut_at_budget'
+```
+
 #### `TOOL_SCHEMAS`
 
 Canonical tool schemas shared by the agent runtime and documentation.
@@ -1477,6 +1954,34 @@ Canonical tool schemas shared by the agent runtime and documentation.
 const TOOL_SCHEMAS: Record<string, ToolSchema>
 ```
 
+#### `SPLIT_WORK_ADVICE`
+
+The closing advice on an over-budget message for a command that is not a test
+suite: the work it was chaining is what to split.
+
+```typescript
+const SPLIT_WORK_ADVICE: string
+```
+
+#### `SUITE_OVER_BUDGET_ADVICE`
+
+The closing advice on an over-budget message for a command that IS a suite run
+(Playwright, Vitest, a `hurl` run — {@link isSuiteRunCommand}): its files are not
+a bigger unit to break up.
+
+X1 flash-m36 asked for this half and the message kept saying "run a smaller unit"
+for two months. It is the wrong direction for a suite, and measurably: a run
+stopped here reports NO tally, so nothing in the result says which test or request
+hung — the run has to be sent again in the background (off this budget, its output
+written to a log that can be read mid-run) or, when a consumer knows the runner's
+per-request limit, with each request bounded. xr-molecule-flash-m93 (+06:22,
+2026-10-16) lost 4.8 minutes to a Hurl run whose ONE unanswered request had hurl's
+300 s default per request holding the file, ten seconds past this tool's budget.
+
+```typescript
+const SUITE_OVER_BUDGET_ADVICE: string
+```
+
 #### `MAX_READ_SIZE`
 
 Max file size for read_file (5MB).
@@ -1800,6 +2305,18 @@ Peer dependencies:
   `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

package/dist/command-position.d.ts

@@ -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
  */
@@ -37,7 +37,19 @@ export interface CommandSegment {
     args: readonly string[];
     /** The program and its arguments as one line — what a runner pattern is matched against. */
     text: string;
+    /**
+     * The seconds the segment's own `timeout` wrapper allows the command it runs
+     * (`timeout 280 hurl --test …` → 280), or null when it carries none.
+     */
+    timeoutSeconds: number | null;
 }
+/**
+ * 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 declare function durationSeconds(word: string): number | null;
 /**
  * The segments of a command, each with its program and arguments — the answer every classifier
  * that reads a command as "this runs the suite" is asking for.
@@ -46,6 +58,20 @@ export interface CommandSegment {
  * @returns One entry per statement or pipeline stage that runs something, in order.
  */
 export declare function commandSegments(command: string): CommandSegment[];
+/**
+ * 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 declare function commandTimeoutSeconds(command: string): number | null;
 /**
  * Whether any segment of the command runs a program whose command-position text matches
  * `pattern` — the one question a runner-kind table asks.

package/dist/command-position.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;CACb;AAqRD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAEjE;AA+BD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}
+{"version":3,"file":"command-position.d.ts","sourceRoot":"","sources":["../src/command-position.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAmFD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAyPD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAEjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAoCD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}