@molecule/api-ai-tools 1.10.2 → 1.10.4

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-19T01:32:03.421Z
+Generated: 2026-10-19T06:38:37.559Z
 -->
 
 # @molecule/api-ai-tools
@@ -216,6 +216,12 @@ interface CutRun {
   noun: 'files' | 'tests'
   /** The last thing the run printed — the line a reader looks at first. */
   doing: string | null
+  /**
+   * The interpreter of an inline program that only touches local files (`python3`, `node`, …), or
+   * null. Such a program is stopped by its short budget because it is stuck, never because the work
+   * is slow, so the sentence must not send it to the background (xr-molecule-flash-m200 +03:45).
+   */
+  inlineScript?: string | null
 }
 ```
 
@@ -626,6 +632,43 @@ interface TraceReadContradiction {
 }
 ```
 
+#### `TraceHiddenBox`
+
+A visibility failure whose locator RESOLVED: Playwright calls an element with a zero-size box
+"hidden" even when it is painted, so the useful fact is why the box is empty. The trace's own
+failure snapshot carries the element's children — read here, never guessed.
+
+```typescript
+interface TraceHiddenBox {
+  /** The locator the assertion printed (`locator('a.navbar-brand')`), or the element it names. */
+  locator: string
+  /** The element's tag, lowercased (`a`). */
+  tag: string
+  /** The element's own inline style, when the snapshot carries one. */
+  style?: string
+  /**
+   * The `<img>` the element wraps when that image is its only element child and the element has
+   * no text of its own: the size the box would collapse to.
+   */
+  image?: {
+    /** The image's `src`, bounded. */
+    src?: string
+    /** Its `width` attribute. */
+    width?: string
+    /** Its `height` attribute. */
+    height?: string
+    /** Its inline `style`. */
+    style?: string
+    /** Its `class`. */
+    className?: string
+    /** Its `alt` text. */
+    alt?: string
+  }
+  /** True when the element has no text and no element children at all. */
+  empty?: true
+}
+```
+
 #### `TraceArtifact`
 
 What one trace says: the test it belongs to, the requests it made, and its console lines.
@@ -715,6 +758,13 @@ interface TraceArtifact {
    * and on traces read before this field existed.
    */
   readContradiction?: TraceReadContradiction
+  /**
+   * A visibility failure whose locator RESOLVED into an empty box — Playwright's "hidden" — with
+   * the element's children read from the failure snapshot ({@link TraceHiddenBox}). The note uses
+   * it to name why the box is empty (an `<img>` with no CSS size, a textless element) instead of
+   * leaving the run to probe computed styles (xr-molecule-flash-m197).
+   */
+  hiddenBox?: TraceHiddenBox
 }
 ```
 
@@ -1026,6 +1076,17 @@ interface ToolBuildConfig {
    */
   suiteBudget?: (command: string, cwd: string) => Promise<SuiteBudgetPin | null | undefined>
 
+  /**
+   * A whole walk's duration in ms, as the consumer measured it. A suite run the executor detached
+   * whose own `timeout` is shorter than this is lifted (m200); unset lifts only a bound no longer
+   * than this tool's ceiling.
+   *
+   * @param command - The suite command.
+   * @param cwd - The run's working directory.
+   * @returns The duration in ms, or null.
+   */
+  suiteRunMs?: (command: string, cwd: string) => Promise<number | null | undefined>
+
   /** Post-write hook (e.g. auto-format via Prettier/ESLint). Called after every write_file/edit_file. */
   onAfterWrite?: (path: string) => Promise<void>
 
@@ -1659,7 +1720,9 @@ Written to be quotable by the model in one sentence and to leave no room for "ne
 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 "of N" it can then state. The sentence
 says how many tests the stop left unrun — a number a reader cannot round up to "the suite
-passed" — and hands over the one move that survives a long run: run it in the background.
+passed" — and hands over the one move that survives a long run: run it in the background. An
+inline program that only touches local files is the exception ({@link CutRun.inlineScript}): it
+is not slow, it is stuck, and the background is the one place it must not be sent.
 
 ```typescript
 function cutRunSentence(run: CutRun): string
@@ -1699,6 +1762,37 @@ function allConnectionFailures(failures: readonly (RunFailureClass | null)[]): b
 
 **Returns:** True when there is at least one and none of them is the app's.
 
+#### `inlineLocalScriptCommand(command)`
+
+The interpreter of an INLINE program that only reads and writes local files — the shape that gets
+{@link INLINE_SCRIPT_BUDGET_MS} instead of the tool's command budget.
+
+An inline program with any external effect keeps the full budget: no network, install, test
+runner, build or server verb may appear anywhere in the command ({@link EXTERNAL_EFFECT}), and
+the command must not be a suite run or a foreground server (the platform's own classifiers).
+
+```typescript
+function inlineLocalScriptCommand(command: string): string | null
+```
+
+- `command` — The command as the executor sent it.
+
+**Returns:** The interpreter's name (`python3`, `node`, …), or null when this is not the shape.
+
+#### `inlineScriptRunawaySentence(interpreter, seconds)`
+
+What a cut inline program's result says instead of the background advice: the work never was
+slow, it is stuck, and re-running it — here or in the background — cannot help.
+
+```typescript
+function inlineScriptRunawaySentence(interpreter: string, seconds: number): string
+```
+
+- `interpreter` — The interpreter the program ran under (`python3`, `node`, …).
+- `seconds` — The short budget it was stopped at, in seconds.
+
+**Returns:** The sentence the result carries.
+
 #### `normalizeToolInput(schema, raw)`
 
 Move known aliases onto the declared parameter names and report what is still
@@ -1818,7 +1912,9 @@ the runner invocation each caller read as a run is one.
 
 A command that also runs tests is false however it is spelled: `npx playwright install &&
 npx playwright test` installs and runs, so a caller that sees `playwright test` in it is
-reading a real run.
+reading a real run. So is a command carrying a segment this reader cannot place (a script it
+does not know, which may start a suite): only the runners and the {@link NO_TEST_PROGRAMS}
+table can be accounted for, and "only prints" is a claim about the WHOLE command.
 
 ```typescript
 function commandRunsNoTests(command: string): boolean
@@ -2409,6 +2505,26 @@ function isCredentialExchangePath(path: string, authEndpoints?: readonly string[
 
 **Returns:** True when the path names a credential exchange.
 
+#### `hiddenBoxNote(items)`
+
+The sentence a "hidden" visibility failure earns when the trace proved WHY the box is empty.
+
+Playwright calls an element with a zero-size box hidden even when it is painted, so the answer
+is in the element's children. `a.navbar-brand` on xr-molecule-flash-m197 was 0×4 px because its
+only child was `<img src="/conduit-logo.svg" height="26">`: an SVG with a `viewBox` and no
+width/height has no intrinsic size, and the `height` attribute loses to Tailwind's preflight
+(`img { max-width: 100%; height: auto }`), which the scaffold's own `index.css` imports. The
+note said only "the cause is in the page", and the run spent over four minutes rasterising an
+SVG to PNG. Only what the snapshot shows is claimed ({@link TraceHiddenBox}).
+
+```typescript
+function hiddenBoxNote(items: readonly TraceArtifact[]): string | null
+```
+
+- `items` — The traces {@link parseTraceArtifacts} read.
+
+**Returns:** The sentence, or null when no failure carries a hidden-box reading.
+
 #### `failureTraceNote(items, target, earlierFailures, apiPrefixes, report)`
 
 The note a failed suite run's result carries: what each failing test's page actually sent, and
@@ -3020,6 +3136,32 @@ function isValidGlob(pattern: string): boolean
 
 **Returns:** `true` when the pattern contains only allowed characters.
 
+#### `expandBraceGlob(pattern)`
+
+Expand ONE level of brace alternatives in a glob pattern, validating every
+expanded pattern.
+
+Neither search tool expands braces itself: `grep --include` and `find` take
+the pattern as a single shell-quoted argument, so no shell ever sees it.
+`find_files {pattern:"*.{ts,tsx}"}` and `search_files {include:"*.{ts,tsx}"}`
+were both refused outright (xr-molecule-flash-m199 and m189), costing a round
+trip and pushing the agent to a narrower search. The group is expanded here
+instead — `search_files` passes one `--include` per alternative and
+`find_files` ORs one `-name`/`-path` predicate per alternative.
+
+Bounded on purpose: one level of braces, alternatives split on `,`, at most
+{@link MAX_BRACE_GLOB_ALTERNATIVES}, none empty, and each EXPANDED pattern
+must still pass {@link isValidGlob} — so a shell metacharacter in any
+alternative (`*.{ts,$(rm)}`) is refused exactly as a bare one is.
+
+```typescript
+function expandBraceGlob(pattern: string): string[] | null
+```
+
+- `pattern` — The user-supplied glob.
+
+**Returns:** Every pattern the value expands to, or null when it is not accepted (the caller reports its tool's glob error).
+
 #### `findPatternArgs(pattern)`
 
 The `find` predicate for a `find_files` pattern.
@@ -3827,6 +3969,18 @@ run that passed, and no reader may treat it as one.
 const CUT_AT_BUDGET: 'cut_at_budget'
 ```
 
+#### `INLINE_SCRIPT_BUDGET_MS`
+
+How long an inline interpreter program that only reads and writes local files may run.
+
+Such work finishes in milliseconds; if it has not finished in twenty seconds it never will
+(a backtracking regex on a large file, a loop waiting on something that is not coming), so this
+is a runaway detector, not a performance budget.
+
+```typescript
+const INLINE_SCRIPT_BUDGET_MS: 20000
+```
+
 #### `TOOL_SCHEMAS`
 
 Canonical tool schemas shared by the agent runtime and documentation.
@@ -4019,6 +4173,26 @@ edited `app/src` while the run was still walking — which voids the run.
 const PLAYWRIGHT_FAILURES_INLINE_ENV: 'PLAYWRIGHT_LIST_PRINT_FAILURES_INLINE'
 ```
 
+#### `MAX_BRACE_GLOB_ALTERNATIVES`
+
+The most alternatives one brace group may expand to. The point is to accept
+the ordinary multi-extension form a model writes from habit
+(`*.{ts,tsx,yml,json,md}`), not to grow a glob engine: a group is bounded so
+a pattern cannot turn one search into hundreds.
+
+```typescript
+const MAX_BRACE_GLOB_ALTERNATIVES: 16
+```
+
+#### `BRACE_GLOB_HINT`
+
+The accepted brace form, named in every refusal so a refusal teaches the
+syntax rather than only reporting that the value was wrong.
+
+```typescript
+const BRACE_GLOB_HINT: string
+```
+
 #### `MAX_READ_SIZE`
 
 Max file size for read_file (5MB).

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;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;AA8RD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAwkBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAmCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,MAAM,GAAG,IAAI,CAyDf;AA2FD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAC1C;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAoD7C;AAED;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;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;AAgSD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAmoBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAmCD;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;IAC9B,0FAA0F;IAC1F,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAmDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,GAAG,EAAE,MAAM,GAAG,IAAI,GACjB,MAAM,GAAG,IAAI,CAyDf;AA4GD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,GAC1C;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAoD7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}

package/dist/command-position.js

@@ -62,6 +62,7 @@ const LAUNCHERS = new Set([
     'nice',
     'nohup',
     'setsid',
+    'stdbuf',
     'sudo',
     'time',
     'timeout',
@@ -268,6 +269,7 @@ const WRAPPER_VALUE_FLAGS = {
     env: ['-S', '--split-string', '-u', '--unset', '-C', '--chdir'],
     ionice: ['-c', '--class', '-n', '--classdata', '-p', '--pid', '-P', '--pgid', '-u', '--uid'],
     nice: ['-n', '--adjustment'],
+    stdbuf: ['-e', '-i', '-o'],
     sudo: [
         '-C',
         '--chdir',
@@ -408,22 +410,40 @@ function nestedCommand(words, from) {
     return null;
 }
 /**
- * Where the program starts in one segment's words, and the bound the segment puts on itself.
+ * Where the program starts in one segment's words, the bound the segment puts on itself, and the
+ * environment it binds for the program it runs.
+ *
+ * `bound` is every `NAME=value` word the walk steps over between the segment's start and its
+ * program: the leading words, and the ones behind an `env` wrapper (`env -i PATH=$PATH
+ * BASE_URL=https://… npx playwright test`). A shell passes those to the program in exactly the
+ * same way — `env` is the POSIX form of the leading-word form — so a reader that only saw the
+ * leading ones called a deployed walk local (X0 xr-molecule-flash-m204 +38:15: two green deployed
+ * walks were refused, 5.2 min).
  *
  * @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), 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.
+ *   nothing), the command string of a `sh -c '<command>'` this segment turns out to be, the
+ *   seconds its own `timeout` wrapper allows that command (`timeout 280 hurl …` → 280) or null,
+ *   every `NAME=value` word bound for the program in the order the shell binds them, and the word
+ *   index an assignment for the program belongs at when an `env` wrapper sits in front of it
+ *   (`env -i … <here>npx`; a value written before `env -i` is cleared, so it must go after).
  *   `program` names what runs when that is not the word itself's name — `node <path>/playwright`
  *   is a `playwright` invocation, not a `node` one ({@link nodeScriptRunner}).
  */
 function commandStart(words) {
     let at = 0;
     let timeoutSeconds = null;
+    const bound = [];
+    let envInsert = null;
+    let envReset = false;
     for (let guard = 0; guard < MAX_WRAPPERS && at < words.length; guard++) {
         const word = words[at] ?? '';
         if (ENV_ASSIGNMENT.test(word)) {
+            bound.push(word);
             at += 1;
+            // Still the env wrapper's own region: an assignment for the program goes after it.
+            if (envInsert !== null)
+                envInsert = at;
             continue;
         }
         const name = programName(word);
@@ -435,14 +455,22 @@ function commandStart(words) {
         if (SHELLS.has(name)) {
             const nested = nestedCommand(words, at + 1);
             if (nested !== null)
-                return { at, nested, timeoutSeconds, program: null };
+                return { at, nested, timeoutSeconds, program: null, bound, envInsert, envReset };
             at += 1 + flagWords(words, at + 1, name);
             continue;
         }
         if (PACKAGE_RUNNERS.has(name)) {
             const runner = packageRunnerOptions(words, at + 1, name);
             if (runner.nested !== null)
-                return { at, nested: runner.nested, timeoutSeconds, program: null };
+                return {
+                    at,
+                    nested: runner.nested,
+                    timeoutSeconds,
+                    program: null,
+                    bound,
+                    envInsert,
+                    envReset,
+                };
             at += 1 + runner.count;
             continue;
         }
@@ -451,7 +479,15 @@ function commandStart(words) {
             const subcommand = unquoted(words[at + 1] ?? '');
             const runner = packageRunnerOptions(words, at + 2, `${name} ${subcommand}`);
             if (runner.nested !== null)
-                return { at, nested: runner.nested, timeoutSeconds, program: null };
+                return {
+                    at,
+                    nested: runner.nested,
+                    timeoutSeconds,
+                    program: null,
+                    bound,
+                    envInsert,
+                    envReset,
+                };
             at += 2 + runner.count;
             continue;
         }
@@ -468,18 +504,38 @@ function commandStart(words) {
             const script = nodeScriptIndex(words, at + 1);
             const runner = script === null ? null : nodeScriptRunner(words[script] ?? '');
             return runner === null
-                ? { at, nested: null, timeoutSeconds, program: null }
-                : { at: script ?? at, nested: null, timeoutSeconds, program: runner };
+                ? { at, nested: null, timeoutSeconds, program: null, bound, envInsert, envReset }
+                : {
+                    at: script ?? at,
+                    nested: null,
+                    timeoutSeconds,
+                    program: runner,
+                    bound,
+                    envInsert,
+                    envReset,
+                };
         }
         if (!LAUNCHERS.has(name))
-            return { at, nested: null, timeoutSeconds, program: null };
+            return { at, nested: null, timeoutSeconds, program: null, bound, envInsert, envReset };
+        const from = at;
         at += 1 + flagWords(words, at + 1, name);
+        // Past `env` and its own options: an assignment for the program written here survives
+        // `env -i`, which clears everything before it.
+        if (name === 'env') {
+            envInsert = at;
+            // `env -i` clears the environment it inherited: the words bound before it are NOT the
+            // environment the program runs in, so a reader must not attribute them to the run.
+            if (words.slice(from + 1, at).some((flag) => flag === '-i' || flag === '--ignore-environment'))
+                envReset = true;
+        }
+        if (envReset)
+            bound.length = 0;
         if (name === 'timeout' && DURATION.test(words[at] ?? '')) {
             timeoutSeconds = durationSeconds(words[at] ?? '');
             at += 1;
         }
     }
-    return { at, nested: null, timeoutSeconds, program: null };
+    return { at, nested: null, timeoutSeconds, program: null, bound, envInsert, envReset };
 }
 /**
  * A command with every heredoc BODY blanked to spaces, so its length and every offset in it are
@@ -1073,11 +1129,24 @@ function locatedSegmentsOf(command, depth) {
         const words = segmentWords(part.text);
         const start = commandStart(words);
         const leading = leadingAssignments(part.text);
+        // Every `NAME=value` bound for the program the statement runs: its leading words AND the ones
+        // an `env` wrapper carries (`env -i PATH=$PATH BASE_URL=… npx playwright test`). A shell binds
+        // both to the program the same way, so one list holds both — a reader that saw only the
+        // leading ones read a deployed walk as local (X0 xr-molecule-flash-m204 +38:15). `env -i`
+        // clears what it inherited, so after it the wrapper's own words are the whole environment.
+        const assignments = [
+            ...new Set(start.envReset ? start.bound : [...leading.words, ...start.bound]),
+        ];
         /** Every offset in this statement is an offset in the command it was written in. */
         const placed = {
             start: part.start,
             end: part.start + part.text.length,
-            assignmentOffset: part.start + leading.end,
+            // After the statement's own leading `NAME=value` words — or, when an `env` wrapper stands
+            // there, after that wrapper and its own options/assignments, because `env -i` clears what
+            // comes before it (`env -i … <here>npx playwright test`).
+            assignmentOffset: start.envInsert === null
+                ? part.start + leading.end
+                : part.start + (wordOffset(part.text, start.envInsert) ?? leading.end),
             programOffset: words[start.at] === undefined ? null : part.start + (wordOffset(part.text, start.at) ?? 0),
         };
         // The runner the word RUNS names, when that is not the word's own name (`node <path>/playwright`
@@ -1093,6 +1162,9 @@ function locatedSegmentsOf(command, depth) {
                     continue;
                 out.push({
                     ...entry,
+                    // The variables this statement bound before the shell reached it are the nested
+                    // command's too: `env BASE_URL=… sh -c '… npx playwright test …'` passes them down.
+                    assignments: [...new Set([...assignments, ...entry.assignments])],
                     // A nested statement's positions are positions in the nested string, not in this
                     // command. The FIRST one keeps this statement's own separator: the shell reads the
                     // nested string where this statement stands.
@@ -1115,10 +1187,10 @@ function locatedSegmentsOf(command, depth) {
         if (word === undefined) {
             // Only wrappers and assignments: nothing this statement runs, but the variables it sets
             // persist in the shell the rest of the command runs in.
-            if (leading.words.length > 0)
+            if (assignments.length > 0)
                 out.push({
                     segment: null,
-                    assignments: leading.words,
+                    assignments,
                     ...placed,
                     programOffset: null,
                     separator: part.before,
@@ -1134,7 +1206,7 @@ function locatedSegmentsOf(command, depth) {
                 text: [program, ...args].join(' '),
                 timeoutSeconds: start.timeoutSeconds,
             },
-            assignments: leading.words,
+            assignments,
             ...placed,
             separator: part.before,
             terminator: part.after,

package/dist/cut-run.d.ts

@@ -161,6 +161,12 @@ export interface CutRun {
     noun: 'files' | 'tests';
     /** The last thing the run printed — the line a reader looks at first. */
     doing: string | null;
+    /**
+     * The interpreter of an inline program that only touches local files (`python3`, `node`, …), or
+     * null. Such a program is stopped by its short budget because it is stuck, never because the work
+     * is slow, so the sentence must not send it to the background (xr-molecule-flash-m200 +03:45).
+     */
+    inlineScript?: string | null;
 }
 /**
  * The run a command's result records as stopped by a budget, or null when the result is a run that
@@ -213,7 +219,9 @@ export declare function cutRunFacts(result: unknown): CutRun | null;
  * 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 "of N" it can then state. The sentence
  * says how many tests the stop left unrun — a number a reader cannot round up to "the suite
- * passed" — and hands over the one move that survives a long run: run it in the background.
+ * passed" — and hands over the one move that survives a long run: run it in the background. An
+ * inline program that only touches local files is the exception ({@link CutRun.inlineScript}): it
+ * is not slow, it is stuck, and the background is the one place it must not be sent.
  *
  * @param run - The stopped run.
  * @returns The sentence.

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

@@ -1 +1 @@
-{"version":3,"file":"cut-run.d.ts","sourceRoot":"","sources":["../src/cut-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;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;AAiBD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAkDD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA4B9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,MAAM,GAAG,IAAI,CAIf;AAED,0BAA0B;AAC1B,MAAM,MAAM,KAAK;AACf,sEAAsE;AACpE,aAAa;AACf,oDAAoD;GAClD,iBAAiB;AACnB;;;;GAIG;GACD,cAAc,CAAA;AAElB,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,SAAS,EAAE,KAAK,CAAA;IAChB;;;;;;OAMG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;OAGG;IACH,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;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,SAAI,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAuFf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAiB1D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAiClD"}
+{"version":3,"file":"cut-run.d.ts","sourceRoot":"","sources":["../src/cut-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH;;;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;AAiBD;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAkDD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CA4B9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,GACb,MAAM,GAAG,IAAI,CAIf;AAED,0BAA0B;AAC1B,MAAM,MAAM,KAAK;AACf,sEAAsE;AACpE,aAAa;AACf,oDAAoD;GAClD,iBAAiB;AACnB;;;;GAIG;GACD,cAAc,CAAA;AAElB,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,kFAAkF;IAClF,SAAS,EAAE,KAAK,CAAA;IAChB;;;;;;OAMG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;;OAGG;IACH,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,qCAAqC;IACrC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;IACvB,yEAAyE;IACzE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,aAAa,SAAI,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CA4Ff;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAkB1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAqClD"}

package/dist/cut-run.js

@@ -33,6 +33,7 @@
  * @module
  */
 import { commandTimeoutSeconds } from './command-position.js';
+import { inlineLocalScriptCommand } from './inline-script.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
@@ -287,6 +288,7 @@ export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0, raw
     if (summary?.finished)
         return null;
     const suite = isSuiteRunCommand(command);
+    const inlineScript = inlineLocalScriptCommand(command);
     const withheld = /\|\s*(?:tail|head|grep|egrep|fgrep|sort|uniq|wc|jq)\b/.test(command);
     const progress = runProgress(detected, suite, summary);
     const doing = lastPrinted(text);
@@ -315,6 +317,7 @@ export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0, raw
             exitCode,
             ...progress,
             doing,
+            inlineScript,
         };
     }
     if (declared !== null && ownBoundStops && elapsedMs >= atBoundMs(declared)) {
@@ -326,6 +329,7 @@ export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0, raw
             exitCode: withheld || exitCode === 0 ? null : exitCode,
             ...progress,
             doing,
+            inlineScript,
         };
     }
     // The tool's budget with its code masked: the run used the whole budget and the pipeline left
@@ -338,6 +342,7 @@ export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0, raw
             exitCode: exitCode === 0 ? null : exitCode,
             ...progress,
             doing,
+            inlineScript,
         };
     }
     // The runner printed a summary that does not account for the total it announced, and neither
@@ -354,6 +359,7 @@ export function commandCutRun(command, result, elapsedMs, budgetSeconds = 0, raw
             exitCode: withheld || exitCode === 0 ? null : exitCode,
             ...progress,
             doing,
+            inlineScript,
         };
     }
     return null;
@@ -390,6 +396,7 @@ export function cutRunFacts(result) {
         total: typeof c.total === 'number' ? c.total : null,
         noun: c.noun === 'tests' ? 'tests' : 'files',
         doing: typeof c.doing === 'string' && c.doing ? c.doing : null,
+        inlineScript: typeof c.inlineScript === 'string' && c.inlineScript ? c.inlineScript : null,
     };
 }
 /**
@@ -400,7 +407,9 @@ export function cutRunFacts(result) {
  * 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 "of N" it can then state. The sentence
  * says how many tests the stop left unrun — a number a reader cannot round up to "the suite
- * passed" — and hands over the one move that survives a long run: run it in the background.
+ * passed" — and hands over the one move that survives a long run: run it in the background. An
+ * inline program that only touches local files is the exception ({@link CutRun.inlineScript}): it
+ * is not slow, it is stuck, and the background is the one place it must not be sent.
  *
  * @param run - The stopped run.
  * @returns The sentence.
@@ -417,11 +426,15 @@ export function cutRunSentence(run) {
     // from being sent to the background again — when its own `timeout` is what stopped it, that
     // prefix is the thing to drop (X1 xr-molecule-flash-m143 +24:45: three cut sentences in one run
     // told a background walk to "run it in the background", which is where it already was).
-    const background = run.background
-        ? run.stoppedBy === 'command-timeout'
-            ? `drop the \`timeout\` prefix and send it again — in the background a run is bounded by \`wait_for_task\` and the turn's deadline, not by this tool's ceiling, so the bound you wrote is what killed it`
-            : 'send it again when you are ready'
-        : 'run it in the background (run_in_background + wait_for_task)';
+    const background = run.inlineScript
+        ? // An inline local-file program finished in milliseconds or is stuck; backgrounding it only
+            // moves the hang (xr-molecule-flash-m200 +03:45). The full rewrite advice rides the error.
+            'do not run it in the background — the transform is stuck, not slow'
+        : run.background
+            ? run.stoppedBy === 'command-timeout'
+                ? `drop the \`timeout\` prefix and send it again — in the background a run is bounded by \`wait_for_task\` and the turn's deadline, not by this tool's ceiling, so the bound you wrote is what killed it`
+                : 'send it again when you are ready'
+            : 'run it in the background (run_in_background + wait_for_task)';
     const missing = run.ran !== null && run.total !== null ? run.total - run.ran : null;
     const lead = missing !== null
         ? `Ran ${run.ran} of ${run.total} ${run.noun} in ${run.seconds} s and was stopped by ${by} — the ${missing} it never reached ${missing === 1 ? 'has' : 'have'} not run; ${background}`

package/dist/index.d.ts

@@ -135,6 +135,7 @@ export * from './browser-guard.js';
 export * from './command-position.js';
 export * from './cut-run.js';
 export * from './failure-kind.js';
+export * from './inline-script.js';
 export * from './input-normalizer.js';
 export * from './line-diff.js';
 export * from './no-test-run.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"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,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,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,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,yBAAyB,CAAA;AACvC,cAAc,cAAc,CAAA;AAC5B,cAAc,qBAAqB,CAAA;AACnC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA;AACpC,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -135,6 +135,7 @@ export * from './browser-guard.js';
 export * from './command-position.js';
 export * from './cut-run.js';
 export * from './failure-kind.js';
+export * from './inline-script.js';
 export * from './input-normalizer.js';
 export * from './line-diff.js';
 export * from './no-test-run.js';