@molecule/api-ai-tools 1.8.1 → 1.8.3

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,16 +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, 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.
@@ -466,25 +594,46 @@ function splitSegments(command) {
             continue;
         }
         if ((char === '&' && next === '&') || (char === '|' && next === '|')) {
-            parts.push(buffer);
+            parts.push({ text: buffer, start: bufferStart, after: char + next });
             buffer = '';
             i += 1;
+            bufferStart = i + 1;
             continue;
         }
         if (char === ';' || char === '|' || char === '\n') {
-            parts.push(buffer);
+            parts.push({ text: buffer, start: bufferStart, after: char });
             buffer = '';
+            bufferStart = i + 1;
             continue;
         }
-        if (char === '&' && command[i - 1] !== '>' && next !== '>') {
-            parts.push(buffer);
+        if (char === '&' && source[i - 1] !== '>' && next !== '>') {
+            parts.push({ text: buffer, start: bufferStart, after: '&' });
             buffer = '';
+            bufferStart = i + 1;
             continue;
         }
         buffer += char;
     }
-    parts.push(buffer);
-    return parts.map((part) => part.trim()).filter(Boolean);
+    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
@@ -506,6 +655,38 @@ function segmentWords(text) {
     }
     return cleaned;
 }
+/** {@link WORD} anchored at an offset, for walking a statement's raw words. */
+const WORD_AT = new RegExp(WORD.source, 'y');
+/**
+ * A statement's own leading `NAME=value` words, and where they end.
+ *
+ * The shell binds these to the command the statement runs, so they are the environment THAT
+ * program sees — which is why a caller writing a variable for a run has to write it here and not
+ * at the start of the whole command.
+ *
+ * @param text - One statement's text.
+ * @returns The assignments as written, and the offset in `text` just before the word that runs.
+ */
+function leadingAssignments(text) {
+    const words = [];
+    let at = 0;
+    for (let guard = 0; guard < MAX_WRAPPERS; guard++) {
+        while (at < text.length && /\s/.test(text[at] ?? ''))
+            at += 1;
+        // Grouping in front of the statement (`(npx …)`, `{ …`): not a word the shell assigns with.
+        if (text[at] === '(' || text[at] === '{') {
+            at += 1;
+            continue;
+        }
+        WORD_AT.lastIndex = at;
+        const match = WORD_AT.exec(text);
+        if (!match || !ENV_ASSIGNMENT.test(match[0]))
+            return { words, end: at };
+        words.push(match[0]);
+        at += match[0].length;
+    }
+    return { words, end: at };
+}
 /**
  * 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.
@@ -514,66 +695,151 @@ function segmentWords(text) {
  * @returns One entry per statement or pipeline stage that runs something, in order.
  */
 export function commandSegments(command) {
-    return segmentsOf(command, 0);
+    return locatedSegmentsOf(command, 0).flatMap((located) => located.segment === null ? [] : [located.segment]);
 }
 /**
- * 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.
+ * Where a statement's word sits in its own raw text, as {@link segmentWords} counts the words.
  *
- * 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}).
+ * 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 command - The shell command.
- * @returns The seconds the command allows itself, or null.
+ * @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.
  */
-export function commandTimeoutSeconds(command) {
-    let bound = null;
-    for (const segment of segmentsOf(command, 0)) {
-        if (segment.timeoutSeconds === null)
+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;
-        bound = bound === null ? segment.timeoutSeconds : Math.max(bound, segment.timeoutSeconds);
+        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 bound;
+    return null;
 }
 /**
- * {@link commandSegments}'s recursion, so a `sh -c '<command>'` is opened as far as
- * {@link MAX_NESTING} allows.
+ * 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
+ * the same command reads.
+ *
+ * @param command - The shell command.
+ * @returns One entry per statement or pipeline stage, in order.
+ */
+export function locatedCommandSegments(command) {
+    return locatedSegmentsOf(command, 0);
+}
+/**
+ * {@link locatedCommandSegments}'s recursion, so a `sh -c '<command>'` is opened as far as
+ * {@link MAX_NESTING} allows. A nested statement's offsets are cleared: they are positions in
+ * the nested string, not in the command this walk started from.
  *
  * @param command - The shell command.
  * @param depth - How many `sh -c` strings this command already sits inside.
- * @returns The segments.
+ * @returns The located statements.
  */
-function segmentsOf(command, depth) {
+function locatedSegmentsOf(command, depth) {
     if (typeof command !== 'string' || depth > MAX_NESTING)
         return [];
     const out = [];
-    for (const text of splitSegments(command)) {
-        const words = segmentWords(text);
-        if (words.length === 0)
-            continue;
+    for (const part of splitSegments(command)) {
+        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) {
-            out.push(...segmentsOf(start.nested, depth + 1));
+            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];
-        // Only wrappers and assignments: nothing this segment runs.
-        if (word === undefined)
+        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)
+                out.push({
+                    segment: null,
+                    assignments: leading.words,
+                    ...placed,
+                    programOffset: null,
+                    separator: part.before,
+                });
             continue;
+        }
         const program = programName(word);
         const args = words.slice(start.at + 1);
         out.push({
-            program,
-            args,
-            text: [program, ...args].join(' '),
-            timeoutSeconds: start.timeoutSeconds,
+            segment: {
+                program,
+                args,
+                text: [program, ...args].join(' '),
+                timeoutSeconds: start.timeoutSeconds,
+            },
+            assignments: leading.words,
+            ...placed,
+            separator: part.before,
         });
     }
     return out;
 }
+/**
+ * The bound a command puts on its own run: the largest `timeout <N>` any of its segments runs
+ * under (`timeout 280 hurl --test …` → 280), or null when it carries none.
+ *
+ * This is the bound `man timeout` enforces by KILLING the command — so a run that used it did not
+ * finish, whatever the pipeline's own exit status says. It is read here, from the same parse every
+ * other command reader uses, rather than matched as text: `timeout` in an argument
+ * (`grep -n 'timeout 280' notes.md`) bounds nothing, and `-k 5` is the grace before the kill, not
+ * the bound ({@link WRAPPER_VALUE_FLAGS}).
+ *
+ * @param command - The shell command.
+ * @returns The seconds the command allows itself, or null.
+ */
+export function commandTimeoutSeconds(command) {
+    let bound = null;
+    for (const segment of commandSegments(command)) {
+        if (segment.timeoutSeconds === null)
+            continue;
+        bound = bound === null ? segment.timeoutSeconds : Math.max(bound, segment.timeoutSeconds);
+    }
+    return bound;
+}
 /**
  * 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/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';

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,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,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,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,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

@@ -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';

package/dist/sleep-peek.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A leading `sleep` in an executor's command: the seconds it would have waited, and the command
+ * that follows it.
+ *
+ * X1 xr-molecule-flash-m105 (+08:49 → +10:53, 2026-10-17) spent 225 s of its 60-minute clock
+ * inside `exec_command` calls of the shape `sleep N; tail <task log>`. The platform's own launch
+ * note said "peek with exec_command: tail <log>" beside "never sleep", and the only concrete
+ * instruction was the peek, so the executor built the poll by hand. Two of its three sleeps were
+ * provably dead — the task had ended 0.1 s in (`playwright: not found`, exit 127) and another had
+ * already printed `Error: No tests found` — and the third spent 120 s asleep beside a live
+ * 139-test run whose failures were already in the log.
+ *
+ * The platform does not have to answer "what is the task doing" from a sleep: `wait_for_task`
+ * already returns the moment the task ends, early on a proven repeating cause, and with the
+ * progress and failures the log holds. This module answers only the parsing question — is the
+ * command's FIRST statement a `sleep` of {@link MIN_PEEK_SLEEP_SECONDS} seconds or more, and what
+ * follows it — from the package's own shell parse ({@link locatedCommandSegments}), so a `sleep`
+ * named in an argument (`grep -n 'sleep 60' notes.md`) or written after another statement
+ * (`cd x && sleep 60`) is not one.
+ *
+ * @module
+ */
+/**
+ * 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.
+ */
+export declare const MIN_PEEK_SLEEP_SECONDS = 5;
+/** The leading `sleep` a command opens with, and the command that follows it. */
+export 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;
+}
+/**
+ * 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.
+ *
+ * @param 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`.
+ */
+export declare function leadingSleepPeek(command: string): LeadingSleep | null;
+//# sourceMappingURL=sleep-peek.d.ts.map

package/dist/sleep-peek.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep-peek.d.ts","sourceRoot":"","sources":["../src/sleep-peek.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH;;;GAGG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAA;AAEvC,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAA;IACf,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAyBrE"}

package/dist/sleep-peek.js

@@ -0,0 +1,76 @@
+/**
+ * A leading `sleep` in an executor's command: the seconds it would have waited, and the command
+ * that follows it.
+ *
+ * X1 xr-molecule-flash-m105 (+08:49 → +10:53, 2026-10-17) spent 225 s of its 60-minute clock
+ * inside `exec_command` calls of the shape `sleep N; tail <task log>`. The platform's own launch
+ * note said "peek with exec_command: tail <log>" beside "never sleep", and the only concrete
+ * instruction was the peek, so the executor built the poll by hand. Two of its three sleeps were
+ * provably dead — the task had ended 0.1 s in (`playwright: not found`, exit 127) and another had
+ * already printed `Error: No tests found` — and the third spent 120 s asleep beside a live
+ * 139-test run whose failures were already in the log.
+ *
+ * The platform does not have to answer "what is the task doing" from a sleep: `wait_for_task`
+ * already returns the moment the task ends, early on a proven repeating cause, and with the
+ * progress and failures the log holds. This module answers only the parsing question — is the
+ * command's FIRST statement a `sleep` of {@link MIN_PEEK_SLEEP_SECONDS} seconds or more, and what
+ * follows it — from the package's own shell parse ({@link locatedCommandSegments}), so a `sleep`
+ * named in an argument (`grep -n 'sleep 60' notes.md`) or written after another statement
+ * (`cd x && sleep 60`) is not one.
+ *
+ * @module
+ */
+import { durationSeconds, locatedCommandSegments } from './command-position.js';
+/**
+ * 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.
+ */
+export const MIN_PEEK_SLEEP_SECONDS = 5;
+/**
+ * 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.
+ *
+ * @param 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`.
+ */
+export function leadingSleepPeek(command) {
+    if (typeof command !== 'string')
+        return null;
+    const first = locatedCommandSegments(command)[0];
+    if (!first || first.start === null || first.segment === null)
+        return null;
+    if (first.segment.program !== 'sleep')
+        return null;
+    // GNU sleep sums its operands (`sleep 45 15`); every one of them has to be a duration.
+    let seconds = 0;
+    for (const arg of first.segment.args) {
+        const part = durationSeconds(arg);
+        if (part === null)
+            return null;
+        seconds += part;
+    }
+    if (seconds < MIN_PEEK_SLEEP_SECONDS)
+        return null;
+    let end = command.length;
+    for (let i = first.start; i < command.length; i++) {
+        const char = command[i] ?? '';
+        if (char === '|')
+            return null;
+        if (char === ';' || char === '\n' || char === '&') {
+            end = i;
+            break;
+        }
+    }
+    let at = end;
+    while (at < command.length && /[;&\s]/.test(command[at] ?? ''))
+        at += 1;
+    return { seconds, rest: command.slice(at).trim() };
+}