@molecule/api-ai-tools 1.8.2 → 1.8.3

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-17T02:50:55.123Z
+Generated: 2026-10-17T05:02:46.912Z
 -->
 
 # @molecule/api-ai-tools
@@ -115,6 +115,24 @@ interface LocatedCommandSegment {
    * inside a nested `sh -c` string, for the same reason as {@link start}.
    */
   assignmentOffset: number | null
+  /**
+   * The offset in the command one past the statement's last word — where an option of this
+   * statement's program belongs, before whatever closes it. Null inside a nested `sh -c` string.
+   */
+  end: number | null
+  /**
+   * The offset in the command of the word in command position — the program, once every wrapper
+   * in front of it is taken away (`npx --prefix /app <here>playwright test`). Null inside a
+   * nested `sh -c` string, and for a statement that only sets variables.
+   */
+  programOffset: number | null
+  /**
+   * The separator the shell split at immediately before this statement — `|`, `||`, `&&`, `;`,
+   * a newline or `&` — or '' when it is the first statement of the command. It is the parse's own
+   * answer, so it is known even where the offsets are not, and a caller deciding whether two
+   * statements are one pipeline (`|`, never `;`) asks it instead of reading the text between them.
+   */
+  separator: string
 }
 ```
 
@@ -235,6 +253,19 @@ interface ToolSchema {
 }
 ```
 
+#### `LeadingSleep`
+
+The leading `sleep` a command opens with, and the command that follows it.
+
+```typescript
+interface LeadingSleep {
+  /** How many seconds the statement would have slept (GNU sleep sums its operands). */
+  seconds: number
+  /** What follows the leading statement, trimmed — '' when the sleep was the whole command. */
+  rest: string
+}
+```
+
 #### `SuiteRunInFlight`
 
 One suite run, as the rule that decides whether a second may start beside it reads it.
@@ -258,6 +289,20 @@ interface SuiteRunInFlight {
 }
 ```
 
+#### `InstalledPackageFacts`
+
+What the filesystem says about a write target under `node_modules` — the half
+of the decision a path's spelling cannot make.
+
+```typescript
+interface InstalledPackageFacts {
+  /** Whether the `node_modules` entry the path goes through is a symbolic link. */
+  readonly symlink: boolean
+  /** Whether a package is really installed there: a `package.json` resolves under the entry. */
+  readonly installed: boolean
+}
+```
+
 #### `TraceRequest`
 
 One request a traced page made, as `*.network` records it.
@@ -553,6 +598,27 @@ interface SuiteFilterStrip {
 }
 ```
 
+#### `SuiteRunPipelinePlacement`
+
+Whether a finished run's exit code belongs to a stage after the suite runner.
+
+```typescript
+interface SuiteRunPipelinePlacement {
+  /**
+   * True when a pipe this tool must not drop still follows the suite runner: the code in the
+   * result is that stage's, not the run's.
+   */
+  piped: boolean
+  /**
+   * True when the suite (or a stage of its pipeline) sits inside a nested `sh -c '<command>'`
+   * string, so the parse cannot place it in the command's own text. The caller then says so
+   * plainly instead of implying a stage it can point at — and keeps the command's own code when
+   * no pipe follows the runner, because on that command the pipeline's last stage IS the run.
+   */
+  unplaced: boolean
+}
+```
+
 #### `FailedTest`
 
 One failed test, as a running suite's log names it.
@@ -658,6 +724,19 @@ Re-export SkillEntry as DiscoveredSkill for backwards compatibility.
 type DiscoveredSkill = SkillEntry
 ```
 
+#### `InstalledPackageProbe`
+
+Looks at the filesystem for {@link InstalledPackageFacts}.
+
+The guard cannot `stat` the path itself: the tools act through a backend (a
+sandbox over the network for the fleet), so the caller — which holds that
+backend — supplies the look. {@link shellInstalledPackageProbe} builds one
+from any shell runner.
+
+```typescript
+type InstalledPackageProbe = (path: string) => Promise<InstalledPackageFacts>
+```
+
 ### Classes
 
 #### `ToolInputError`
@@ -1029,6 +1108,26 @@ function commandRunsNoTests(command: string): boolean
 
 **Returns:** True when the command invokes a runner only to print.
 
+#### `leadingSleepPeek(command)`
+
+The leading `sleep` of a command, when the first statement is one and it asks for at least
+{@link MIN_PEEK_SLEEP_SECONDS}.
+
+The statement is read by {@link locatedCommandSegments} — the same parse every other command
+classifier uses — so only a `sleep` in command position of the FIRST statement counts. The end
+of that statement is then found by walking forward from its own start: the statement is
+`sleep <duration>`, whose words carry no quotes and open no substitution, so the first unquoted
+`;`, newline or `&` ends it. A `|` is refused: dropping the left side of a pipeline would hand
+the right side its stdin instead, and a `||` fallback would run on a success that never did.
+
+```typescript
+function leadingSleepPeek(command: string): LeadingSleep | null
+```
+
+- `command` — The shell command the executor sent.
+
+**Returns:** The seconds and the remaining command, or null when the command does not open with a long `sleep`.
+
 #### `withoutHeredocs(command)`
 
 A command with its heredoc bodies removed: the runs, kills and hosts it names in a file it
@@ -1213,10 +1312,26 @@ function moleculeDistReadNote(path: string): string | null
 
 **Returns:** The note, or null when the path is not inside a package's `dist`.
 
-#### `installedPackageWriteRefusal(path)`
+#### `shellInstalledPackageProbe(run)`
 
-The refusal for a write whose target is inside an installed package, or null
-when the path is not under a `node_modules` directory.
+Build an {@link InstalledPackageProbe} from a shell runner (a backend's
+`run`, or a sandbox's `exec`): one command reports whether the entry is a
+link and whether a `package.json` resolves under it.
+
+```typescript
+function shellInstalledPackageProbe(
+  run: (command: string) => Promise<{ stdout?: string } | null | undefined>,
+): InstalledPackageProbe
+```
+
+- `run` — Runs a command where the path lives.
+
+**Returns:** The probe.
+
+#### `installedPackageWriteRefusal(path, probe)`
+
+The refusal for a write whose target is inside an INSTALLED package, or null
+when the path is not under `node_modules` or nothing is installed there.
 
 `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
@@ -1229,17 +1344,29 @@ 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.
+What is protected is the INSTALL, not the spelling: the decision comes from
+{@link InstalledPackageFacts}, never from the path alone (m106 above). Three
+things are the run's own to remove or replace —
+
+- a `node_modules` that is a SYMLINK: `rm`/`unlink` removes the link, never the
+  tree it points at, so a link the run made cannot clobber anything;
+- anything under the run's own `.mol-scratch/` directory;
+- a `node_modules` with no `package.json` under it (nothing was ever installed).
+
+A path INSIDE the link is still decided by what resolves there: a link into a
+real tree is refused, because removing or writing through it reaches the
+
+_(description truncated — read the full text in `node_modules/@molecule/api-ai-tools/dist/tools.d.ts`.)_
 
 ```typescript
-function installedPackageWriteRefusal(path: string): string | null
+function installedPackageWriteRefusal(
+  path: string,
+  probe?: InstalledPackageProbe,
+): Promise<string | null>
 ```
 
 - `path` — An absolute path a tool is about to write.
+- `probe` — Looks at the filesystem where the path lives.
 
 **Returns:** The one-line refusal naming the package, or null when nothing is installed there.
 
@@ -1602,23 +1729,40 @@ function stripTrailingSuiteFilters(command: string): SuiteFilterStrip
 
 **Returns:** The rewritten command and the stages dropped.
 
+#### `suiteRunPipelinePlacement(command)`
+
+Where the suite runner's exit code comes from: the runner itself, or a stage piped after it.
+
+{@link suiteRunPipedAfterRunner}'s one question, with the honest third answer kept apart. The
+code a finished run reports is its LAST pipeline stage's, so a stage after the runner makes the
+code the stage's — but only when such a stage EXISTS. The platform used to report "piped" for
+any run whose statements it could not place in the text, which one heredoc body was enough to
+cause: on X1 xr-molecule-flash-m105 (+08:12) a config written in the same `exec_command` made
+the run come back with no exit code at all, and the note under it claimed a stage after the
+runner that was not there. The parse now places every statement (`locatedCommandSegments`), so
+"unplaced" is the rare, named case rather than a guess dressed as an answer.
+
+```typescript
+function suiteRunPipelinePlacement(command: string): SuiteRunPipelinePlacement
+```
+
+- `command` — The shell command, after the streaming rewrite when one was applied.
+
+**Returns:** Whether a stage follows the runner, and whether the run could be placed at all.
+
 #### `suiteRunPipedAfterRunner(command)`
 
 Whether the command's last step runs a suite whose output still passes through a stage after
 the runner — one {@link stripTrailingSuiteFilters} could not prove is output-only (`| tee log`,
 `| xargs …`). The pipeline's exit status is that stage's, not the run's.
 
-A command whose stages cannot be placed in the text (irregular whitespace inside the run) is
-reported as piped too: whether a pipe follows the runner is then UNKNOWN, and an unknown exit
-code that gets trusted is a failing run read as a pass — the failure this rule exists to stop.
-
 ```typescript
 function suiteRunPipedAfterRunner(command: string): boolean
 ```
 
 - `command` — The shell command, after the streaming rewrite when one was applied.
 
-**Returns:** True when a pipe this tool must not drop still follows the suite runner, or when the command runs a suite the parse cannot place.
+**Returns:** True when a pipe this tool must not drop still follows the suite runner.
 
 #### `suiteRunPriorityLaunch(command, launch)`
 
@@ -2231,9 +2375,12 @@ executor reads, so one round of fixes covers all of them rather than the one cau
 stopped early happened to reach.
 
 A test the request excludes is not one of the causes — it is dropped and named once, at the
-end, so a result never asks to fix a test it also says to ignore. Where the caller knows how
-the run was started, the note also hands over the narrowed re-run of exactly those tests
-({@link rerunOfRunningSuite}) instead of leaving the executor to re-run the whole suite.
+end, so a result never asks to fix a test it also says to ignore. A test the runner itself
+declared `flaky` (it failed once and passed on its config retry) is not a cause either: it is
+named apart from them, once, as what the tally called it ({@link flakyTestsDeclared}). Where
+the caller knows how the run was started, the note also hands over the narrowed re-run of
+exactly those tests ({@link rerunOfRunningSuite}) instead of leaving the executor to re-run the
+whole suite.
 
 ```typescript
 function failureCausesNote(
@@ -2414,6 +2561,15 @@ Canonical tool schemas shared by the agent runtime and documentation.
 const TOOL_SCHEMAS: Record<string, ToolSchema>
 ```
 
+#### `MIN_PEEK_SLEEP_SECONDS`
+
+The shortest leading sleep the platform drops: below it the wall clock it costs is noise, and a
+short settle (`sleep 2; curl …`) is a legitimate thing to run.
+
+```typescript
+const MIN_PEEK_SLEEP_SECONDS: 5
+```
+
 #### `SPLIT_WORK_ADVICE`
 
 The closing advice on an over-budget message for a command that is not a test

package/dist/command-position.d.ts

@@ -21,8 +21,14 @@
  * Not command position, and therefore not an invocation: a runner named as an argument
  * (`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 `./suite-overlap.js`).
+ * WRITES is not a command it runs, so the bodies are blanked to spaces before anything is split
+ * ({@link blankHeredocBodies}); offsets stay exact, because the blanking preserves every position.
+ *
+ * The parser also answers WHERE each statement sits ({@link locatedCommandSegments}): `start`,
+ * `end`, `programOffset` and `assignmentOffset` are the offsets a caller splices at. They are
+ * token positions from this walk, never a search for re-joined text — the words are joined back
+ * with single spaces for matching, so `command.indexOf(segment.text)` fails on irregular spacing,
+ * on grouping braces, and on anything a heredoc body shifts (xr-molecule-flash-m105 +08:12).
  *
  * @module
  */
@@ -90,6 +96,24 @@ export interface LocatedCommandSegment {
      * inside a nested `sh -c` string, for the same reason as {@link start}.
      */
     assignmentOffset: number | null;
+    /**
+     * The offset in the command one past the statement's last word — where an option of this
+     * statement's program belongs, before whatever closes it. Null inside a nested `sh -c` string.
+     */
+    end: number | null;
+    /**
+     * The offset in the command of the word in command position — the program, once every wrapper
+     * in front of it is taken away (`npx --prefix /app <here>playwright test`). Null inside a
+     * nested `sh -c` string, and for a statement that only sets variables.
+     */
+    programOffset: number | null;
+    /**
+     * The separator the shell split at immediately before this statement — `|`, `||`, `&&`, `;`,
+     * a newline or `&` — or '' when it is the first statement of the command. It is the parse's own
+     * answer, so it is known even where the offsets are not, and a caller deciding whether two
+     * statements are one pipeline (`|`, never `;`) asks it instead of reading the text between them.
+     */
+    separator: string;
 }
 /**
  * Every statement of a command, with its own assignments and where it sits — assignment-only

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;IACZ;;;OAGG;IACH,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AA2MD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AAkVD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAIjE;AAED;;;;;;;;;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;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AAqDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;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;;;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;AA2MD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM3D;AA+cD;;;;;;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;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAE/E;AA4ED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK/E"}

package/dist/command-position.js

@@ -21,8 +21,14 @@
  * Not command position, and therefore not an invocation: a runner named as an argument
  * (`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 `./suite-overlap.js`).
+ * WRITES is not a command it runs, so the bodies are blanked to spaces before anything is split
+ * ({@link blankHeredocBodies}); offsets stay exact, because the blanking preserves every position.
+ *
+ * The parser also answers WHERE each statement sits ({@link locatedCommandSegments}): `start`,
+ * `end`, `programOffset` and `assignmentOffset` are the offsets a caller splices at. They are
+ * token positions from this walk, never a search for re-joined text — the words are joined back
+ * with single spaces for matching, so `command.indexOf(segment.text)` fails on irregular spacing,
+ * on grouping braces, and on anything a heredoc body shifts (xr-molecule-flash-m105 +08:12).
  *
  * @module
  */
@@ -380,6 +386,123 @@ function commandStart(words) {
     }
     return { at, nested: null, timeoutSeconds };
 }
+/**
+ * A command with every heredoc BODY blanked to spaces, so its length and every offset in it are
+ * unchanged.
+ *
+ * A heredoc body is data the command writes, not a command it runs: `cat > playwright.config.ts
+ * <<'EOF' … import { defineConfig, devices } from '@playwright/test' … EOF` writes a file and runs
+ * `cat`. Read as shell, though, every line of the body is a statement — and the words joined back
+ * for matching are not the words written, so a caller that placed a statement by searching for
+ * them found nothing, in a command whose real statements sat all along. On X1
+ * xr-molecule-flash-m105 (+08:12) the body's `import { defineConfig, devices } …` alone made
+ * `suiteRunPipedAfterRunner` answer "piped" for a run with no pipe left, and the run's exit code
+ * was dropped for the rest of the session.
+ *
+ * The body runs from the line after the operator to the line whose whole content is the delimiter
+ * (leading TABS stripped for `<<-`, as `man bash` defines it); the terminator line is blanked too,
+ * and its newline kept, so the statements around it still split at the same places. Newlines
+ * inside the body are kept for the same reason. `<<<` is a herestring, not a heredoc, and a `<<`
+ * inside quotes or a comment opens nothing.
+ *
+ * @param command - The shell command.
+ * @returns The command with the bodies blanked to spaces, the same length as the input.
+ */
+function blankHeredocBodies(command) {
+    if (!command.includes('<<'))
+        return command;
+    const chars = command.split('');
+    /** Overwrite a range with spaces, keeping its newlines so statements still split there. */
+    const blank = (from, to) => {
+        for (let i = from; i < to; i++)
+            if (chars[i] !== '\n')
+                chars[i] = ' ';
+    };
+    let lineStart = 0;
+    while (lineStart < command.length) {
+        const lineEndRaw = command.indexOf('\n', lineStart);
+        const lineEnd = lineEndRaw < 0 ? command.length : lineEndRaw;
+        const openers = [];
+        let quote = null;
+        for (let i = lineStart; i < lineEnd; i++) {
+            const char = command[i] ?? '';
+            if (quote !== null) {
+                if (char === quote)
+                    quote = null;
+                continue;
+            }
+            if (char === '"' || char === "'") {
+                quote = char;
+                continue;
+            }
+            // A `#` that starts a word opens a comment: the rest of the line is not shell words.
+            if (char === '#' && (i === lineStart || /\s/.test(command[i - 1] ?? '')))
+                break;
+            if (char !== '<' || command[i + 1] !== '<')
+                continue;
+            // `<<<` is a herestring: it opens no body.
+            if (command[i + 2] === '<') {
+                i += 2;
+                continue;
+            }
+            let at = i + 2;
+            const stripTabs = command[at] === '-';
+            if (stripTabs)
+                at += 1;
+            while (command[at] === ' ' || command[at] === '\t')
+                at += 1;
+            let delimiter;
+            const opener = command[at];
+            if (opener === '"' || opener === "'") {
+                const close = command.indexOf(opener, at + 1);
+                const wordEnd = close < 0 || close > lineEnd ? lineEnd : close;
+                delimiter = command.slice(at + 1, wordEnd);
+                at = wordEnd + 1;
+            }
+            else {
+                let wordEnd = at;
+                while (wordEnd < lineEnd && !/\s/.test(command[wordEnd] ?? ''))
+                    wordEnd += 1;
+                delimiter = command.slice(at, wordEnd);
+                at = wordEnd;
+            }
+            if (delimiter !== '')
+                openers.push({ delimiter, stripTabs });
+            i = at - 1;
+        }
+        if (openers.length === 0) {
+            if (lineEndRaw < 0)
+                break;
+            lineStart = lineEnd + 1;
+            continue;
+        }
+        // The bodies follow the line that opened them, in the order the operators were written.
+        let cursor = lineEndRaw < 0 ? command.length : lineEnd + 1;
+        for (const heredoc of openers) {
+            let bodyEnd = command.length;
+            let after = command.length;
+            let from = cursor;
+            while (from < command.length) {
+                const nl = command.indexOf('\n', from);
+                const line = command.slice(from, nl < 0 ? command.length : nl);
+                const compared = heredoc.stripTabs ? line.replace(/^\t+/, '') : line;
+                if (compared === heredoc.delimiter) {
+                    bodyEnd = from;
+                    after = nl < 0 ? command.length : nl + 1;
+                    break;
+                }
+                if (nl < 0)
+                    break;
+                from = nl + 1;
+            }
+            blank(cursor, bodyEnd);
+            blank(bodyEnd, after);
+            cursor = after;
+        }
+        lineStart = cursor;
+    }
+    return chars.join('');
+}
 /**
  * A command's statements and pipeline stages, split where the shell splits them — inside quotes
  * and inside a command substitution, a `|`, `;` or `&&` belongs to that command, not to this one.
@@ -400,19 +523,21 @@ function commandStart(words) {
  * no runner, and every run of it reads as nothing).
  *
  * @param command - The shell command.
- * @returns Each segment's text and the offset in the command its first character sits at, in
- *   order, with empty ones dropped.
+ * @returns Each statement's text, the offset its first character sits at, and the separator that
+ *   ended it (`|`, `&&`, `;`, a newline, … — '' after the last one), in order, with empty ones
+ *   dropped.
  */
 function splitSegments(command) {
+    const source = blankHeredocBodies(command);
     const parts = [];
     let buffer = '';
     /** The offset in the command of the current buffer's first character. */
     let bufferStart = 0;
     /** The nestings this position sits inside, outermost first. */
     const stack = [];
-    for (let i = 0; i < command.length; i++) {
-        const char = command[i] ?? '';
-        const next = command[i + 1];
+    for (let i = 0; i < source.length; i++) {
+        const char = source[i] ?? '';
+        const next = source[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.
@@ -469,33 +594,46 @@ function splitSegments(command) {
             continue;
         }
         if ((char === '&' && next === '&') || (char === '|' && next === '|')) {
-            parts.push({ text: buffer, start: bufferStart });
+            parts.push({ text: buffer, start: bufferStart, after: char + next });
             buffer = '';
             i += 1;
             bufferStart = i + 1;
             continue;
         }
         if (char === ';' || char === '|' || char === '\n') {
-            parts.push({ text: buffer, start: bufferStart });
+            parts.push({ text: buffer, start: bufferStart, after: char });
             buffer = '';
             bufferStart = i + 1;
             continue;
         }
-        if (char === '&' && command[i - 1] !== '>' && next !== '>') {
-            parts.push({ text: buffer, start: bufferStart });
+        if (char === '&' && source[i - 1] !== '>' && next !== '>') {
+            parts.push({ text: buffer, start: bufferStart, after: '&' });
             buffer = '';
             bufferStart = i + 1;
             continue;
         }
         buffer += char;
     }
-    parts.push({ text: buffer, start: bufferStart });
-    return parts
-        .map((part) => ({
-        text: part.text.trim(),
-        start: part.start + (part.text.length - part.text.trimStart().length),
-    }))
-        .filter((part) => part.text !== '');
+    parts.push({ text: buffer, start: bufferStart, after: '' });
+    const out = [];
+    // The separator of the last part, kept across the empty ones so a statement's own separator
+    // survives the blank lines around it (`a &&\n b` and a heredoc's blanked body alike).
+    let lastAfter = null;
+    for (const part of parts) {
+        const text = part.text.trim();
+        if (text === '') {
+            lastAfter = part.after;
+            continue;
+        }
+        out.push({
+            text,
+            start: part.start + (part.text.length - part.text.trimStart().length),
+            after: part.after,
+            before: lastAfter ?? '',
+        });
+        lastAfter = part.after;
+    }
+    return out;
 }
 /**
  * One segment's words: quotes kept whole, grouping parentheses dropped, and a `(` written
@@ -559,6 +697,42 @@ function leadingAssignments(text) {
 export function commandSegments(command) {
     return locatedSegmentsOf(command, 0).flatMap((located) => located.segment === null ? [] : [located.segment]);
 }
+/**
+ * Where a statement's word sits in its own raw text, as {@link segmentWords} counts the words.
+ *
+ * The words are matched for READING (quotes whole, grouping braces dropped, a leading `(` taken
+ * off the first word); a caller that writes into the statement needs the offset it was written
+ * at. Both come from this one walk, so the two can never disagree about which word is which.
+ *
+ * @param text - One statement's text.
+ * @param index - The word's index in {@link segmentWords}'s list.
+ * @returns The word's offset in `text`, or null when there is no such word.
+ */
+function wordOffset(text, index) {
+    const placement = new RegExp(WORD.source, 'g');
+    let kept = 0;
+    let first = true;
+    for (let match = placement.exec(text); match !== null; match = placement.exec(text)) {
+        if (GROUPING.has(match[0]))
+            continue;
+        if (first) {
+            first = false;
+            const bare = match[0].replace(/^[({]+/, '');
+            // `segmentWords` shifts a first word that was nothing but grouping away, so the NEXT word
+            // is not stripped and is counted from zero.
+            if (bare === '')
+                continue;
+            if (kept === index)
+                return match.index + (match[0].length - bare.length);
+            kept += 1;
+            continue;
+        }
+        if (kept === index)
+            return match.index;
+        kept += 1;
+    }
+    return null;
+}
 /**
  * Every statement of a command, with its own assignments and where it sits — assignment-only
  * statements included, because the variables those persist are exactly what a later statement of
@@ -587,9 +761,31 @@ function locatedSegmentsOf(command, depth) {
         const words = segmentWords(part.text);
         const start = commandStart(words);
         const leading = leadingAssignments(part.text);
+        /** 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,
+            programOffset: words[start.at] === undefined ? null : part.start + (wordOffset(part.text, start.at) ?? 0),
+        };
         if (start.nested !== null) {
-            for (const inner of locatedSegmentsOf(start.nested, depth + 1))
-                out.push({ ...inner, start: null, assignmentOffset: null });
+            const inner = locatedSegmentsOf(start.nested, depth + 1);
+            for (let i = 0; i < inner.length; i += 1) {
+                const entry = inner[i];
+                if (!entry)
+                    continue;
+                out.push({
+                    ...entry,
+                    // 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.
+                    start: null,
+                    end: null,
+                    assignmentOffset: null,
+                    programOffset: null,
+                    separator: i === 0 ? part.before : entry.separator,
+                });
+            }
             continue;
         }
         const word = words[start.at];
@@ -600,8 +796,9 @@ function locatedSegmentsOf(command, depth) {
                 out.push({
                     segment: null,
                     assignments: leading.words,
-                    start: part.start,
-                    assignmentOffset: part.start + leading.end,
+                    ...placed,
+                    programOffset: null,
+                    separator: part.before,
                 });
             continue;
         }
@@ -615,8 +812,8 @@ function locatedSegmentsOf(command, depth) {
                 timeoutSeconds: start.timeoutSeconds,
             },
             assignments: leading.words,
-            start: part.start,
-            assignmentOffset: part.start + leading.end,
+            ...placed,
+            separator: part.before,
         });
     }
     return out;

package/dist/index.d.ts

@@ -137,6 +137,7 @@ export * from './cut-run.js';
 export * from './input-normalizer.js';
 export * from './no-test-run.js';
 export * from './schemas.js';
+export * from './sleep-peek.js';
 export * from './suite-overlap.js';
 export * from './system-prompt.js';
 export * from './tools.js';