@molecule/api-ai-tools 1.13.0 → 1.14.0

package/dist/suite-overlap.js

@@ -29,7 +29,7 @@
  * @module
  */
 import { posix } from 'node:path';
-import { commandSegments, locatedCommandSegments } from './command-position.js';
+import { commandSegments, locatedCommandSegments, statementBoundary, } from './command-position.js';
 import { commandRunsNoTests } from './no-test-run.js';
 import { matchingExcludedTitles, shellQuote, suiteRunStatements } from './utilities.js';
 /**
@@ -127,8 +127,278 @@ const FILE_REDIRECT = /(^|\s)(&>>?|1?>>?)(\s*)(?:'([^']+)'|"([^"]+)"|([^\s;&|]+)
 /** A target that is not a log anyone could lose: rewriting it would CREATE a file. */
 const DEVICE_TARGET = /^\/dev\//;
 /**
- * The command with every file redirect pointed at a fresh file beside its original target
- * (`/tmp/pw-full.log` → `/tmp/pw-full.rerun.log`), and nothing else changed.
+ * The command's words, quotes kept whole and with the offsets they were written at — the reading
+ * {@link dropSupersededSelections} tokenizes the runner's arguments with AND the one a redirect
+ * reader may not look inside: a quoted `--grep 'a > b'` is one word, and its `>` is the filter's
+ * text, not a redirect.
+ */
+const ARGUMENT_WORD = /"(?:\\.|[^"\\])*"|'[^']*'|\S+/g;
+/**
+ * The command's words as spans, in the order they were written.
+ *
+ * @param command - The shell command.
+ * @returns Each word's span in the command.
+ */
+function wordSpans(command) {
+    return [...command.matchAll(ARGUMENT_WORD)].map((match) => ({
+        start: match.index ?? 0,
+        end: (match.index ?? 0) + match[0].length,
+    }));
+}
+/**
+ * Whether an offset sits strictly INSIDE one of the command's words rather than between them —
+ * the quoted data a redirect reader must leave alone.
+ *
+ * @param at - The offset being read.
+ * @param words - The command's word spans.
+ * @returns True when the offset is inside a word.
+ */
+function insideWord(at, words) {
+    return words.some((word) => at > word.start && at < word.end);
+}
+/**
+ * The command with the edits applied — right to left, so every edit's offsets are still the ones
+ * its reader reported.
+ *
+ * @param command - The command the edits were read from.
+ * @param edits - The replacements, as offsets in that command.
+ * @returns The command with each span replaced.
+ */
+function applyTextEdits(command, edits) {
+    let out = command;
+    for (const edit of [...edits].sort((a, b) => b.start - a.start))
+        out = out.slice(0, edit.start) + edit.text + out.slice(edit.end);
+    return out;
+}
+/**
+ * The output redirects of ONE statement's text that name a file, as edits that point them at a
+ * fresh sibling of the file they wrote (`/tmp/pw-full.log` → `/tmp/pw-full.rerun.log`).
+ *
+ * A redirect whose operator sits inside a quoted word is that word's text, not a redirect of the
+ * statement: `npx playwright test --grep 'a > b' > /tmp/full.log` carries exactly one redirect.
+ *
+ * @param statement - The statement's text.
+ * @param offset - The statement's offset in the command.
+ * @param words - The command's word spans.
+ * @param fresh - The exact old file → fresh file mapping the edits make, filled in here.
+ * @returns The edits, in statement order.
+ */
+function freshRedirectEdits(statement, offset, words, fresh) {
+    const edits = [];
+    for (const match of statement.matchAll(FILE_REDIRECT)) {
+        const before = match[1] ?? '';
+        const op = match[2] ?? '';
+        const space = match[3] ?? '';
+        const single = match[4];
+        const double = match[5];
+        const target = single ?? double ?? match[6] ?? '';
+        // A `>` written inside a quoted value is that value's own text.
+        if (insideWord(offset + (match.index ?? 0) + before.length, words))
+            continue;
+        // `/dev/null` and friends are not a report to preserve; leaving them keeps the re-run silent
+        // the way the run was, where rewriting them would create a file nobody asked for.
+        if (!target || DEVICE_TARGET.test(target))
+            continue;
+        // A descriptor (`>&2`) or a process substitution (`> >(tee …)`) is no file either.
+        if (target.startsWith('&') || target.startsWith('(') || /^\d+$/.test(target))
+            continue;
+        const quote = single !== undefined || double !== undefined ? 1 : 0;
+        const start = offset + (match.index ?? 0) + before.length + op.length + space.length + quote;
+        const rewritten = `${target}.rerun.log`;
+        fresh.set(target, rewritten);
+        edits.push({ start, end: start + target.length, text: rewritten });
+    }
+    return edits;
+}
+/**
+ * The file arguments of a `tee` stage, as edits that point them at a fresh sibling.
+ *
+ * A pipeline the suite feeds (`… 2>&1 | tee /tmp/full.log`) writes the run's own stream to the
+ * files `tee` names, so a re-run through the same pipeline would overwrite the walk's report
+ * exactly the way its own `> <file>` redirect would ({@link freshRedirectEdits}). A stage that
+ * names no file, reads a device or carries flags keeps those words as written.
+ *
+ * @param statement - The stage's text.
+ * @param offset - The stage's offset in the command.
+ * @param fresh - The exact old file → fresh file mapping the edits make, filled in here.
+ * @returns The edits, in stage order.
+ */
+function freshTeeEdits(statement, offset, fresh) {
+    const words = [...statement.matchAll(ARGUMENT_WORD)].map((match) => ({
+        text: match[0],
+        start: offset + (match.index ?? 0),
+    }));
+    const program = words.findIndex((word) => unquoted(word.text).replace(/\/+$/, '').split('/').at(-1) === 'tee');
+    if (program < 0)
+        return [];
+    const edits = [];
+    for (const word of words.slice(program + 1)) {
+        const bare = unquoted(word.text);
+        if (!bare || bare.startsWith('-') || DEVICE_TARGET.test(bare))
+            continue;
+        const quote = /^['"]/.test(word.text) ? 1 : 0;
+        const rewritten = `${bare}.rerun.log`;
+        fresh.set(bare, rewritten);
+        edits.push({
+            start: word.start + quote,
+            end: word.start + word.text.length - quote,
+            text: rewritten,
+        });
+    }
+    return edits;
+}
+/**
+ * The statements that carry the suite run's OWN output: the Playwright statement, and every stage
+ * of the pipeline it feeds (`| tee /tmp/full.log | tail -5`).
+ *
+ * The parse's own spans answer this, so the setup and the tail around the run are never read as
+ * its output: `printf … > app/public/_redirects` writes a file BEFORE any suite starts, and
+ * `; echo done > /tmp/done` runs after it, whatever their redirects look like. Only a `|` joins a
+ * stage to the run's stream; a `;`, `&&` or newline starts a statement of its own whose output is
+ * not the run's ({@link redirectRunnerOutputsToFreshFiles}).
+ *
+ * @param command - The composed command.
+ * @returns The statements, or null when the command starts no Playwright run that can be placed.
+ */
+function runnerOutputStatements(command) {
+    const located = locatedCommandSegments(command);
+    const at = located.findIndex((entry) => entry.segment !== null && PLAYWRIGHT_RUN.test(entry.segment.text));
+    if (at < 0)
+        return null;
+    const place = (entry, tee) => {
+        if (entry.start === null || entry.end === null)
+            return null;
+        // A statement can end on an enclosing group's closer (`( … 2>&1)`); the closer is the
+        // shell's, not the statement's, so it is not part of what a redirect reader may rewrite.
+        const end = statementBoundary(command, entry.start, entry.end)?.textEnd ?? entry.end;
+        return { start: entry.start, end, tee };
+    };
+    const runner = located[at];
+    const first = runner === undefined ? null : place(runner, false);
+    if (first === null)
+        return null;
+    const statements = [first];
+    for (let i = at + 1; i < located.length; i += 1) {
+        const entry = located[i];
+        // Only a stage of the SAME pipeline carries the run's output; anything else is the tail.
+        if (entry === undefined || entry.separator !== '|')
+            break;
+        const stage = place(entry, entry.segment?.program === 'tee');
+        if (stage !== null)
+            statements.push(stage);
+    }
+    return statements;
+}
+/**
+ * Readers whose non-flag operands are ALL files: a display of the run's own report. Every one of
+ * them is read-only, so moving its operand with the file it reads cannot change what it does.
+ */
+const FILE_READERS = new Set(['cat', 'head', 'tail']);
+/**
+ * grep-family readers: their first non-flag operand is the pattern, and the words after it are the
+ * files they display — unless a `-e`/`-f` flag named the pattern already.
+ */
+const GREP_READERS = new Set(['egrep', 'fgrep', 'grep']);
+/** grep's pattern flags: the word after one is a pattern (or a pattern file), never a file. */
+const GREP_PATTERN_FLAGS = new Set(['-e', '--regexp', '-f', '--file']);
+/**
+ * The postlude statements that DISPLAY the run's own report, with the exact file that run wrote
+ * pointed at the fresh sibling the re-run writes instead.
+ *
+ * xr-molecule-flash-o03 (2026-10-22; the stale-READ arm m248 filed at +25:55): the recipe the
+ * platform handed the executor ended `> /tmp/e2e-local.log.rerun.log 2>&1; echo EXIT=$?; tail -80
+ * /tmp/e2e-local.log`. The writer moved to the fresh sibling and the trailing tail did not, so the
+ * narrowed re-run displayed the walk it was narrowed FROM — the builder followed that recipe at
+ * +19:16 and read the previous walk's failures as the result of the run it had just done.
+ *
+ * Only the EXACT file a runner statement (or its `tee`) wrote moves, and only in a statement AFTER
+ * the run: the setup in front of it keeps every byte (m429), and a read of any other file is left
+ * alone. The value is compared whole — `/tmp/full.log` never matches `/tmp/full.log.bak` — and
+ * inside shell quotes the operand's own quoting survives (`"/tmp/my walk.log"` stays quoted).
+ *
+ * The bound is deliberate: a display this reader set does not recognise (a `wc`, a path held in a
+ * variable, a path the command builds) is left exactly as written rather than guessed at. Those
+ * shapes are not the ones the platform emits, and rewriting a word by resemblance is how m429's
+ * setup redirect was corrupted.
+ *
+ * @param command - The composed command.
+ * @param statements - The statements carrying the run's own output.
+ * @param fresh - The exact old file → fresh file mapping the redirect edits made.
+ * @returns The edits, in statement order.
+ */
+function freshReportReadEdits(command, statements, fresh) {
+    if (fresh.size === 0)
+        return [];
+    const after = Math.max(...statements.map((statement) => statement.end));
+    const edits = [];
+    for (const entry of locatedCommandSegments(command)) {
+        const segment = entry.segment;
+        const start = entry.start;
+        const end = entry.end;
+        const programOffset = entry.programOffset;
+        // Only a statement the parse placed and that runs AFTER the walk can display its report.
+        if (segment === null || start === null || end === null)
+            continue;
+        if (start < after || programOffset === null)
+            continue;
+        const allFiles = FILE_READERS.has(segment.program);
+        const grep = GREP_READERS.has(segment.program);
+        if (!allFiles && !grep)
+            continue;
+        const text = command.slice(start, end);
+        const words = [...text.matchAll(ARGUMENT_WORD)].map((match) => ({
+            text: match[0],
+            start: start + (match.index ?? 0),
+        }));
+        // The program word's own span, so the walk starts exactly where the parse says it does.
+        const program = words.findIndex((word) => word.start === programOffset);
+        if (program < 0)
+            continue;
+        /** grep still owes its pattern: the first bare operand is that pattern, not a file. */
+        let patternPending = grep;
+        for (let i = program + 1; i < words.length; i += 1) {
+            const word = words[i];
+            if (word === undefined)
+                break;
+            if (ARGUMENT_REDIRECT_OPERATOR.test(word.text)) {
+                // The operator's target is where the display WRITES, not a file it reads.
+                i += 1;
+                continue;
+            }
+            if (ARGUMENT_REDIRECT.test(word.text))
+                continue;
+            const flag = unquoted(word.text);
+            if (flag.startsWith('-') && flag !== '-') {
+                if (grep) {
+                    if (GREP_PATTERN_FLAGS.has(flag)) {
+                        patternPending = false;
+                        i += 1;
+                    }
+                    else if (/^(?:--(?:regexp|file)=|-[ef].)/.test(flag))
+                        patternPending = false;
+                }
+                continue;
+            }
+            if (patternPending) {
+                patternPending = false;
+                continue;
+            }
+            const to = fresh.get(unquoted(word.text));
+            if (to === undefined)
+                continue;
+            const quote = /^['"]/.test(word.text) ? 1 : 0;
+            edits.push({
+                start: word.start + quote,
+                end: word.start + word.text.length - quote,
+                text: to,
+            });
+        }
+    }
+    return edits;
+}
+/**
+ * The command with the SUITE RUN's own log files pointed at fresh siblings, and nothing else
+ * changed.
  *
  * A re-run composed from a run's own command keeps the run's redirect by construction, and the
  * run wrote the walk's only report to that file: xr-molecule-flash-m173 handed over *"Send this
@@ -137,29 +407,52 @@ const DEVICE_TARGET = /^\/dev\//;
  * full walk's log, destroying the other 11 failures' error reports. Following the platform's own
  * advice must never destroy the evidence it was based on.
  *
- * @param command - A shell command.
- * @returns The command whose file redirects write to a fresh target.
+ * Only the run's OWN stream moves. What surrounds it is SETUP and POSTLUDE, and those writes are
+ * the command's meaning, not a report: xr-molecule-flash-m429 (2026-10-22) composed
+ * `printf '/index.html 200' > app/public/_redirects && npx playwright test specs/auth.spec.ts
+ * > /tmp/full.log 2>&1` with its SPA fallback written to `_redirects.rerun.log`, so the re-run
+ * measured an app with no fallback at all. A heredoc config, a `.env` the command writes and a
+ * source asset it lays down are the same shape: their targets stay byte-for-byte, and so does
+ * every statement chained after the run (`; echo EXIT $? > /tmp/done`).
+ *
+ * Every statement chained after the run (`; echo EXIT $? > /tmp/done`) is postlude and keeps its
+ * own writes, but the DISPLAY of the run's report is part of the same run: a `tail`, `head`, `cat`
+ * or `grep` after the run that reads the exact file it wrote is pointed at the fresh sibling too
+ * ({@link freshReportReadEdits}), so a re-run shows its own output instead of the walk's
+ * (xr-molecule-flash-o03).
+ *
+ * @param command - The composed command.
+ * @returns The command whose suite-run redirects write to a fresh target.
  */
-function redirectToFreshFile(command) {
-    return command.replace(FILE_REDIRECT, (whole, before, op, space, single, double, bare) => {
-        const target = single ?? double ?? bare ?? '';
-        // `/dev/null` and friends are not a report to preserve; leaving them keeps the re-run silent
-        // the way the run was, where rewriting them would create a file nobody asked for.
-        if (!target || DEVICE_TARGET.test(target))
-            return whole;
-        const quote = single !== undefined ? "'" : double !== undefined ? '"' : '';
-        return `${before}${op}${space}${quote}${target}.rerun.log${quote}`;
-    });
+function redirectRunnerOutputsToFreshFiles(command) {
+    const statements = runnerOutputStatements(command);
+    if (statements === null)
+        return command;
+    const words = wordSpans(command);
+    const edits = [];
+    const fresh = new Map();
+    for (const statement of statements) {
+        const text = command.slice(statement.start, statement.end);
+        edits.push(...freshRedirectEdits(text, statement.start, words, fresh));
+        if (statement.tee)
+            edits.push(...freshTeeEdits(text, statement.start, fresh));
+    }
+    edits.push(...freshReportReadEdits(command, statements, fresh));
+    return applyTextEdits(command, edits);
 }
 /**
  * The whole-suite command made scoped to the tests it should re-run instead: the same
- * invocation — same directory, same settings — with the named `file:line`s in place of the whole
- * suite, `--last-failed` dropped (it re-runs the tests that never ran too, X1 flash-m60) and
+ * invocation — same launcher, same settings — with the named `file:line`s in place of every
+ * positional selection the run carried (a spec file, a suite directory or a regex filter),
+ * `--last-failed` dropped (it re-runs the tests that never ran too, X1 flash-m60) and
  * `--retries=0` set (a re-run of a known failure does not need to pay for retries).
  *
  * The re-run keeps the run's `> <file>` redirect only in the sense of keeping its OUTPUT there:
- * the target is rewritten to a fresh sibling ({@link redirectToFreshFile}), so a re-run never
- * overwrites the log the run itself is the evidence for (xr-molecule-flash-m173).
+ * the target is rewritten to a fresh sibling ({@link redirectRunnerOutputsToFreshFiles}), so a
+ * re-run never overwrites the log the run itself is the evidence for (xr-molecule-flash-m173) —
+ * and the setup around the run keeps its own file writes untouched (xr-molecule-flash-m429). A
+ * `tail`/`head`/`cat`/`grep` chained after the run that reads that exact log is shown the fresh
+ * sibling instead, so the re-run displays the run it performed (xr-molecule-flash-o03).
  *
  * `config` is the config the run was measured under ({@link withSuiteConfig}): the narrowed re-run
  * carries it whenever the command itself does not, so a run that dropped `--config` cannot be
@@ -215,8 +508,10 @@ export function scopedRerunCommand(command, locations, excluded = [], config, cw
     // nothing — "No tests found" — so every location is rendered in a form Playwright can match
     // ({@link playwrightLocations}).
     const narrowed = playwrightLocations(locations, command, cwd);
-    const dropped = dropSupersededSpecFiles(args, narrowed)
-        .replace(/\s*--last-failed\b/g, '')
+    const dropped = dropSupersededSelections(args, narrowed)
+        // `--last-failed` re-runs the tests that never ran too (flash-m60); its `--last-failed-file`
+        // sibling only moves the file it reads and is a real option of the re-run.
+        .replace(/\s*--last-failed(?!-)/g, '')
         .replace(/\s*--retries(?:[= ]\d+)?/g, '');
     const scoped = command.slice(0, run.afterRunner) +
         ` ${narrowed.join(' ')} --retries=0${carry}${invert}` +
@@ -226,7 +521,7 @@ export function scopedRerunCommand(command, locations, excluded = [], config, cw
     // X1 xr-molecule-flash-m157 (+14:02) was handed a re-run that still carried the chain's second
     // whole walk — 4.5 minutes measuring code it had not changed.
     const rerunTail = suiteRunStatements(tail).length > 0 ? '' : tail;
-    return withRunEnv(`${redirectToFreshFile(scoped)}${redirectToFreshFile(rerunTail)}`, env);
+    return withRunEnv(redirectRunnerOutputsToFreshFiles(`${scoped}${rerunTail}`), env);
 }
 /** A `NAME=value` word in command position, optionally behind `export`/`env`. */
 const ENV_WORD = /(^|[\s;&|(])(?:export[ \t]+|env[ \t]+)?([A-Za-z_][A-Za-z0-9_]*)=('[^']*'|"[^"]*"|[^\s;&|]+)/g;
@@ -366,33 +661,145 @@ function playwrightLocations(locations, command, cwd) {
         return `${resolved}${suffix}`;
     });
 }
-/** A spec-file argument Playwright accepts as its positional filter — never a flag. */
-const SPEC_FILE_ARGUMENT = /^(?!-)[^\s]*\.(?:spec|test)\.[cm]?[jt]sx?(?::\d+(?::\d+)?)?$/;
 /**
- * The runner's own arguments with every bare spec-file argument taken out once the re-run names
+ * Every Playwright `test` option that takes its value from the NEXT word, read from the runner's
+ * own option table (`playwright test --help`, Playwright 1.63 as the sandbox image ships it).
+ *
+ * A value here is never a positional selection however much it looks like a path:
+ * `--config playwright.config.ts` names the config the run was measured under, and dropping it
+ * because it ends in `.ts` would re-create m113 exactly (a re-run with no base URL).
+ */
+const SUITE_VALUE_FLAGS = new Set([
+    '--add-reporter',
+    '--browser',
+    '-c',
+    '--config',
+    '--global-timeout',
+    '-g',
+    '--grep',
+    '-G',
+    '--grep-invert',
+    '--last-failed-file',
+    '--max-failures',
+    '--output',
+    '--repeat-each',
+    '--reporter',
+    '--retries',
+    '--run-agents',
+    '--shard',
+    '--test-list',
+    '--test-list-invert',
+    '--timeout',
+    '--trace',
+    '--tsconfig',
+    '--ui-host',
+    '--ui-port',
+    '--update-source-method',
+    '-j',
+    '--workers',
+]);
+/**
+ * Options whose value is optional (`--debug [mode]`, `--only-changed [ref]`): the next word is
+ * theirs unless it is another flag — the reading the runner's own command line takes.
+ */
+const SUITE_OPTIONAL_VALUE_FLAGS = new Set([
+    '--debug',
+    '--only-changed',
+    '-u',
+    '--update-snapshots',
+]);
+/**
+ * `--project <project-name...>` takes every word up to the next flag, as the runner's own command
+ * line does; a project name is a selection of projects, never a positional test filter.
+ */
+const SUITE_VARIADIC_VALUE_FLAGS = new Set(['--project']);
+/** A redirect written as one word (`2>&1`, `>/tmp/out.log`): not a selection. */
+const ARGUMENT_REDIRECT = /^(?:\d*|&)(?:<<<|<<-?|>>?\|?|<>|>&|<&)(?:&?\d+|-|[^\s;&|()<>]*)?$/;
+/** A redirect operator whose target is the word after it (`> /tmp/out.log`). */
+const ARGUMENT_REDIRECT_OPERATOR = /^(?:\d*|&)(?:<<<|<<-?|>>?\|?|<>|>&|<&)$/;
+/**
+ * The runner's own arguments with every positional selection taken out once the re-run names
  * failure locations.
  *
- * The re-run is "just these": Playwright matches each positional argument against every collected
- * file's path, so a bare file left beside the `file:line`s re-admits ALL of that file's tests.
- * xr-molecule-flash-m118 (+45:24) kept the one file its 14 failures were in ("~297s" for a file and
- * fourteen duplicates); xr-molecule-flash-m134 (+20:0x) kept all four files of a run whose 8
- * failures sat in two of them — 32 tests, ~3 min, instead of the 8 failures' ~30 s. A file with no
- * failure in it has nothing to re-run, so it goes too.
+ * The re-run is "just these", and Playwright OR-s every positional argument into one selection:
+ * ANY leftover positional re-admits tests the re-run is supposed to skip. A bare spec file
+ * re-admits all of that file's tests (xr-molecule-flash-m118 (+45:24) ~297 s for one file and
+ * fourteen duplicates; xr-molecule-flash-m134 (+20:0x) 32 tests instead of 8). A suite DIRECTORY
+ * is the same argument and re-admits the WHOLE walk even beside fourteen exact `file:line`s —
+ * xr-molecule-flash-m428's suggested "Re-run just these" kept
+ * `/workspace/fixtures/realworld/specs/e2e` after `--config playwright.config.ts`, so the command
+ * said 14 locations and selected every spec again. A regex positional filter selects files the
+ * same way and goes too.
+ *
+ * What is NOT a selection survives byte-for-byte: every option and its value — whatever it looks
+ * like (`--config playwright.config.ts`, `--output test-results`, `--grep 'a|b'`, a `--project`
+ * list) — and every redirect. Quoting and spacing survive because the result is a span splice on
+ * the raw text, never a rebuild from words.
  *
- * The launcher's words are not arguments and are not here: the caller passes what follows
- * `playwright test` ({@link playwrightStatement}'s `afterRunner`), so `node <path>/playwright
- * test` and `npx playwright test` lose the same spec files.
+ * An empty `locations` list keeps the original selection untouched:
+ * {@link scopedRerunCommand} is not narrowing anything then.
  *
  * @param args - The run's own arguments, after `playwright test`.
  * @param locations - The failing `file:line`s the re-run names.
- * @returns The arguments without their bare spec-file arguments.
+ * @returns The arguments without their positional selections.
  */
-function dropSupersededSpecFiles(args, locations) {
+function dropSupersededSelections(args, locations) {
     if (locations.length === 0)
         return args;
-    return args.replace(/(^|\s+)([^\s]+)(?=\s|$)/g, (whole, _space, token) => {
-        return SPEC_FILE_ARGUMENT.test(token) ? '' : whole;
-    });
+    const words = [];
+    for (const match of args.matchAll(ARGUMENT_WORD))
+        words.push({ text: match[0], start: match.index ?? 0 });
+    const dropped = new Array(words.length).fill(false);
+    let at = 0;
+    while (at < words.length) {
+        const word = words[at]?.text ?? '';
+        if (ARGUMENT_REDIRECT_OPERATOR.test(word)) {
+            // The operator and the target after it are one redirect, not two words to judge.
+            at += 2;
+            continue;
+        }
+        if (ARGUMENT_REDIRECT.test(word)) {
+            at += 1;
+            continue;
+        }
+        if (word.startsWith('-') && word !== '-') {
+            // `--flag=value` carries its value inside the same word; only the flag's own name is read.
+            if (word.includes('=')) {
+                at += 1;
+                continue;
+            }
+            if (SUITE_OPTIONAL_VALUE_FLAGS.has(word)) {
+                const next = words[at + 1]?.text;
+                at += next !== undefined && !next.startsWith('-') ? 2 : 1;
+                continue;
+            }
+            if (SUITE_VARIADIC_VALUE_FLAGS.has(word)) {
+                at += 1;
+                while (at < words.length && !(words[at]?.text ?? '').startsWith('-'))
+                    at += 1;
+                continue;
+            }
+            at += SUITE_VALUE_FLAGS.has(word) ? 2 : 1;
+            continue;
+        }
+        // A bare word — a spec file, a directory or a regex filter — is a positional selection.
+        dropped[at] = true;
+        at += 1;
+    }
+    let out = '';
+    let cursor = 0;
+    for (let i = 0; i < words.length; i += 1) {
+        const word = words[i];
+        if (word === undefined || !dropped[i])
+            continue;
+        // The whitespace in front of the word goes with it, so the result is not left double-spaced.
+        let start = word.start;
+        while (start > cursor && /\s/.test(args[start - 1] ?? ''))
+            start -= 1;
+        out += args.slice(cursor, start);
+        cursor = word.start + word.text.length;
+    }
+    return out + args.slice(cursor);
 }
 /**
  * The run in flight that makes a second run a hazard, or null when nothing is in the way.

package/dist/tools.d.ts

@@ -59,6 +59,21 @@ export declare const SUITE_OVER_BUDGET_ADVICE: string;
  * @returns The note, or null when the path is not inside a package's `dist`.
  */
 export declare function moleculeDistReadNote(path: string): string | null;
+/**
+ * The command that reads a REGISTERED background task's own log as one bounded contiguous window
+ * ({@link runningLogReadCommand}), with the file its launch redirects to when the launch recorded
+ * one.
+ *
+ * The task id is the ownership: it is the handle `wait_for_task` returned, `/tmp/${taskId}.log` is
+ * the log this platform's launcher writes for it, and the redirect target is the file this
+ * process's own launch registered for that id — never a path parsed out of a command by the
+ * caller. A diagnosis that reads a running walk must not build a `/tmp` path of its own
+ * (xr-molecule-flash-l07: the wait's DISPLAY was diagnosed as if it were the log).
+ *
+ * @param taskId - The `mol-bg-…` handle the wait returned.
+ * @returns The read command, or null when the handle is not a task id this platform minted.
+ */
+export declare function registeredTaskLogCommand(taskId: string): string | null;
 /**
  * What the filesystem says about a write target under `node_modules` — the half
  * of the decision a path's spelling cannot make.

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAgS9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAudD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAgInE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AA2DlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAoBpF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,GACxE,qBAAqB,CAkBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AA2GD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAq/FxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAgS9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAudD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAiInE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AA2DlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGtE;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;AAoBpF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC,GACxE,qBAAqB,CAkBvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,qBAAqB,GAC5B,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCxB;AA2GD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAq/FxF"}

package/dist/tools.js

@@ -703,7 +703,7 @@ async function backgroundTaskState(backend, command, seconds, ceilingMs) {
 }
 import { suiteCommandTarget } from './suite-overlap.js';
 import { diagnosisTraceCommand } from './trace-artifacts.js';
-import { addedRedactionMask, BRACE_GLOB_HINT, checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, earlyReturnCause, emptyCallError, expandBraceGlob, failureCausesNote, findPathArgs, findPatternArgs, fusedLine, htmlOutline, isCommandTimeout, isEnvFilePath, isOutsideRoot, isPlaywrightRunCommand, isReadOnlyInspection, isSuiteRunCommand, linesWithinSerialized, literalDirPrefix, logShowsInlineFailureBodies, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_HTML_INLINE_CHARS, MAX_OUTPUT_SIZE, MAX_READ_CALL_CHARS, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, READ_RESULT_ENVELOPE_CHARS, redactSecrets, redactSecretsInCode, repeatedSuiteRunError, repeatingFailure, repeatingFailureNote, resolvePath, RUNNING_FAILURE_LINES, runningCauseCommand, runningOutputSliceCommand, searchTimeoutError, serializedChars, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, suiteRunBudgetCommand, suiteRunConfigCommand, suiteRunPipelinePlacement, suiteRunPriorityLaunch, TOOL_RESULT_CHARS, truncateMiddle, universalCause, whitespaceTolerantReplace, withoutSuiteTimeout, withPlaywrightRunReport, } from './utilities.js';
+import { addedRedactionMask, BRACE_GLOB_HINT, checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, earlyReturnCause, emptyCallError, expandBraceGlob, failureCausesNote, findPathArgs, findPatternArgs, fusedLine, htmlOutline, isCommandTimeout, isEnvFilePath, isOutsideRoot, isPlaywrightRunCommand, isReadOnlyInspection, isSuiteRunCommand, linesWithinSerialized, literalDirPrefix, logShowsInlineFailureBodies, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_HTML_INLINE_CHARS, MAX_OUTPUT_SIZE, MAX_READ_CALL_CHARS, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, READ_RESULT_ENVELOPE_CHARS, redactSecrets, redactSecretsInCode, repeatedSuiteRunError, repeatingFailure, repeatingFailureNote, resolvePath, RUNNING_FAILURE_LINES, runningCauseCommand, runningLogReadCommand, runningOutputSliceCommand, searchTimeoutError, serializedChars, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, suiteRunBudgetCommand, suiteRunConfigCommand, suiteRunPipelinePlacement, suiteRunPriorityLaunch, TOOL_RESULT_CHARS, truncateMiddle, universalCause, whitespaceTolerantReplace, withoutSuiteTimeout, withPlaywrightRunReport, } from './utilities.js';
 /**
  * How long exec_command waits for a command it backgrounded only because the
  * command asked for more than the tool's ceiling, before handing back a task id.
@@ -840,6 +840,25 @@ export function moleculeDistReadNote(path) {
             ? ' The declarations above are generated from it.'
             : ' For one signature, read the matching .d.ts file.'));
 }
+/**
+ * The command that reads a REGISTERED background task's own log as one bounded contiguous window
+ * ({@link runningLogReadCommand}), with the file its launch redirects to when the launch recorded
+ * one.
+ *
+ * The task id is the ownership: it is the handle `wait_for_task` returned, `/tmp/${taskId}.log` is
+ * the log this platform's launcher writes for it, and the redirect target is the file this
+ * process's own launch registered for that id — never a path parsed out of a command by the
+ * caller. A diagnosis that reads a running walk must not build a `/tmp` path of its own
+ * (xr-molecule-flash-l07: the wait's DISPLAY was diagnosed as if it were the log).
+ *
+ * @param taskId - The `mol-bg-…` handle the wait returned.
+ * @returns The read command, or null when the handle is not a task id this platform minted.
+ */
+export function registeredTaskLogCommand(taskId) {
+    if (!TASK_ID.test(taskId))
+        return null;
+    return runningLogReadCommand(`/tmp/${taskId}.log`, outputFileByTask.get(taskId));
+}
 /**
  * The `node_modules` entry a path goes through, and the package name after it
  * (`null` when the path IS the entry).