@molecule/api-ai-tools 1.5.15 → 1.5.17

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-16T05:16:44.196Z
+Generated: 2026-10-16T09:30:45.054Z
 -->
 
 # @molecule/api-ai-tools
@@ -488,6 +488,24 @@ function buildAgentPrompt(ctx: PromptContext): string
 
 **Returns:** Fully assembled system prompt text for the coding agent.
 
+#### `moleculeDistReadNote(path)`
+
+The steer attached to a SUCCESSFUL read of a package's built output. The ENOENT
+redirect below fires only when the read FAILS, so a model that knows the hoisted
+layout reads `node_modules/@molecule/<pkg>/dist/*.js` happily and never learns the
+documented API is one call away (X0 flash-m70: 24 such reads in 57 s, no note on
+any of them). Carried as `distNote` rather than merged into `note` so a host that
+has read_molecule_doc (molecule-dev's cadence note, which also names the functions)
+can supersede it without string-matching.
+
+```typescript
+function moleculeDistReadNote(path: string): string | null
+```
+
+- `path` — The resolved path that was read.
+
+**Returns:** The note, or null when the path is not inside a package's `dist`.
+
 #### `buildTools(backend, config)`
 
 Build a complete set of AI agent tools bound to an execution backend.
@@ -572,6 +590,22 @@ function redactSecretsInCode(s: string): string
 
 **Returns:** A redacted copy that preserves ordinary code verbatim.
 
+#### `printsOnlySource(command)`
+
+Whether a shell command only PRINTS source files (`cat a.tsx`, `sed -n '1,40p' x.ts`,
+`head -50 b.hurl`): its output is file content and gets the code-safe redaction, like
+read_file. Through the env-dump grade a printed `type AuthState = 'authenticated' | …`
+came back as `'[REDACTED]'`, and the executor wrote the mask into a new file (X1
+flash-m58). Any segment that is not such a print, or any env file named, keeps the full grade.
+
+```typescript
+function printsOnlySource(command: string): boolean
+```
+
+- `command` — The shell command.
+
+**Returns:** True when every segment prints source files only.
+
 #### `isEnvFilePath(path)`
 
 Whether a path is an env file, for which {@link redactSecrets}' full env-dump
@@ -646,9 +680,16 @@ killed (X1 run flash-m15 lost 20 of its 60 minutes this way, 2026-10-15):
 - a trailing `| tail -N`, which holds everything back until the command ends.
   It is dropped: `wait_for_task` already returns the end of the log.
 - `playwright test` with no `--reporter`, which runs the config's reporter —
-  often `html`, which prints nothing per test. `--reporter=line` is added
+  often `html`, which prints nothing per test. `--reporter=list` is added
   when the playwright run is the command's last step and nothing is piped or
-  redirected from it ( aside); the results are the same, printed as they happen.
+  redirected from it: it writes each result as it finishes, and it is the
+  shape the platform reads a background suite back in (`suite-fail-fast.ts`'s
+  fail-fast note and the Tests bar both parse `list` lines). A run that names
+  `--reporter=line` is switched to `list` for the same reason — `line` writes
+  `[n/N] <title>` with no ✓/✘ mark and no duration, so on X1 flash-m62 an
+  8.3-minute walk of one suite could never trip the fail-fast note.
+
+Only the command's last step is touched, and only its reporter.
 
 ```typescript
 function streamingBackgroundCommand(command: string): { command: string; changes: string[] }
@@ -827,6 +868,25 @@ function failureBlocks(s: string): string[]
 
 **Returns:** Each block, in order (empty when there are none).
 
+#### `runningOutputSliceCommand(log, own)`
+
+The shell command whose stdout is the interesting part of a log that is still being written:
+the failure lines so far (capped at {@link RUNNING_FAILURE_LINES}), then the end of the log.
+
+A Playwright `list` run prints one line per test as it finishes and its error blocks only at
+the end, so the LAST bytes of a running log are its least informative part — in X1 flash-m61
+the last 3 000 bytes of a 139-test walk were the skip list, and all 61 failures were above
+them, which cost the run the grep it had to make anyway.
+
+```typescript
+function runningOutputSliceCommand(log: string, own?: string): string
+```
+
+- `log` — The task log path.
+- `own` — A file the command redirects its own output to, if any.
+
+**Returns:** The shell command, safe to hand to the execution backend as-is.
+
 #### `whitespaceTolerantReplace(content, oldString, newString)`
 
 Attempt a whitespace-tolerant replacement when an exact `old_string` match
@@ -985,7 +1045,9 @@ const MAX_READ_RETURN_CHARS: number
 
 #### `SMALL_FILE_WHOLE_CHARS`
 
-A file this small is returned whole even when a window is asked for (paging it costs a call each).
+A file this small is returned whole on a second window of it (paging it costs a call each).
+The same bound as {@link MAX_READ_RETURN_CHARS}: the windowed-read note promises that a
+file under it "fits in ONE call", and a smaller bound here broke that promise (X1 flash-m67).
 
 ```typescript
 const SMALL_FILE_WHOLE_CHARS: number
@@ -1031,6 +1093,31 @@ const DEFAULT_SEARCH_EXCLUDED_DIRS: readonly [
 ]
 ```
 
+#### `RUNNING_FAILURE_LINES`
+
+Failure lines shown from a log that is still being written.
+
+```typescript
+const RUNNING_FAILURE_LINES: 40
+```
+
+#### `RUNNING_TAIL_BYTES`
+
+Bytes of a running log's end appended after its failure lines.
+
+```typescript
+const RUNNING_TAIL_BYTES: 1000
+```
+
+#### `RUNNING_FAILURE_LINE_RE`
+
+The lines worth showing from a log that is still being written: a failed test's mark or
+numbered block header, and a runner's own error lines. Matched with `grep -E`.
+
+```typescript
+const RUNNING_FAILURE_LINE_RE: '^[[:space:]]*(✘|✗|×|✖|✕|[0-9]+\\)|[0-9]+ (passed|failed|flaky|skipped|did not run)|FAIL|FAILED|ERROR|Error:|error:|Traceback|AssertionError)'
+```
+
 #### `PARSE_CHECKABLE`
 
 Files a parse check can vouch for cheaply right after a write.

package/dist/tools.d.ts

@@ -8,6 +8,19 @@
  */
 import type { AITool } from '@molecule/api-ai';
 import type { ExecutionBackend, ToolBuildConfig } from './types.js';
+/**
+ * The steer attached to a SUCCESSFUL read of a package's built output. The ENOENT
+ * redirect below fires only when the read FAILS, so a model that knows the hoisted
+ * layout reads `node_modules/@molecule/<pkg>/dist/*.js` happily and never learns the
+ * documented API is one call away (X0 flash-m70: 24 such reads in 57 s, no note on
+ * any of them). Carried as `distNote` rather than merged into `note` so a host that
+ * has read_molecule_doc (molecule-dev's cadence note, which also names the functions)
+ * can supersede it without string-matching.
+ *
+ * @param path - The resolved path that was read.
+ * @returns The note, or null when the path is not inside a package's `dist`.
+ */
+export declare function moleculeDistReadNote(path: string): string | null;
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AA8B9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA0CnE;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAooDxF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AA0H9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA6CnE;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAutDxF"}

package/dist/tools.js

@@ -25,12 +25,118 @@ const waitedByTask = new Map();
 const logBytesByTask = new Map();
 /** The file a background command writes its own output to, when it redirects it. */
 const outputFileByTask = new Map();
-import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, fusedLine, isEnvFilePath, isOutsideRoot, isValidGlob, MAX_BATCH_READ_BYTES, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_OUTPUT_SIZE, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, redactSecrets, redactSecretsInCode, resolvePath, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, truncateMiddle, whitespaceTolerantReplace, } from './utilities.js';
+/**
+ * Task ids whose own-output file has already been looked for this process.
+ * {@link outputFileByTask} is empty for every task after a restart — it is
+ * process memory and the task is not — so without this the recovery below
+ * would re-read the task's script on every single wait.
+ */
+const outputFileProbed = new Set();
+/** A millisecond span the way a model reads it: seconds under 90, else minutes. */
+function durationText(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    const mins = Math.floor(s / 60);
+    return s < 90 ? `${s} s` : s % 60 ? `${mins} min ${s % 60} s` : `${mins} min`;
+}
+/**
+ * When a background command started, read from its own id: the handle is minted
+ * as `mol-bg-${Date.now().toString(36)}-…`, so the start stamp is in the id and
+ * no new state has to be kept to have it.
+ *
+ * @param taskId - The handle a run_in_background command returned.
+ * @returns Epoch ms, or null when the id carries no usable stamp (a hand-written
+ * or synthetic id) — a wrong number in a note is worse than none.
+ */
+function taskStartedAt(taskId) {
+    const stamp = Number.parseInt(taskId.split('-')[2] ?? '', 36);
+    const now = Date.now();
+    return Number.isFinite(stamp) && stamp > now - 24 * 3600_000 && stamp < now + 60_000
+        ? stamp
+        : null;
+}
+/**
+ * The progress a run reports in its own log: the last `[done/total]` counter a
+ * Playwright reporter writes (`[86/139] [chromium] › e2e/settings.spec.ts:…`).
+ *
+ * @param log - The log slice this wait read.
+ * @returns The counter, or null when the log carries none.
+ */
+function logProgress(log) {
+    const last = [...log.matchAll(/\[(\d+)\/(\d+)\]/g)].at(-1);
+    const done = Number(last?.[1]);
+    const total = Number(last?.[2]);
+    return last && total > 0 && done >= 0 && done <= total ? { done, total } : null;
+}
+/**
+ * What a wait knows about the command BESIDES "it has not exited": how long it
+ * has been running, whether its output is still growing, how far its own log
+ * says it has got, and how much longer that implies.
+ *
+ * X1 flash-m62 (2026-10-16) spent three 290 s waits on one 8.3-minute suite and
+ * every answer read only "Still running after 280s": the run could not tell a
+ * suite with 30 s left from one with 6 minutes left, so the wait cadence — not
+ * the suite — set the pace, and the run learned nothing for its 14 minutes of
+ * waiting. The elapsed time comes from the task id, the progress from the log
+ * this wait already read, and the time left is the rate so far, said as such.
+ *
+ * @param o - The wait's facts: `taskId`, the `slice` of the log it read,
+ *   `stillWriting` (the log grew during this wait), `bytes` (the log's size, null
+ *   when unreadable), and `ceilingMs` (this call's ceiling, for "one more wait").
+ * @returns A sentence to append to a running note, or '' when nothing is known.
+ */
+function waitProgressNote(o) {
+    const startedAt = taskStartedAt(o.taskId);
+    const elapsedMs = startedAt === null ? null : Math.max(0, Date.now() - startedAt);
+    const parts = [];
+    if (elapsedMs !== null)
+        parts.push(`it has been running ${durationText(elapsedMs)}`);
+    if (o.stillWriting)
+        parts.push(`its output is still growing (${o.bytes} bytes) — slow, not stuck`);
+    else if (o.bytes !== null)
+        parts.push(`its log has not grown during this wait (${o.bytes} bytes)`);
+    const counter = logProgress(o.slice);
+    if (counter) {
+        parts.push(`its log is at ${counter.done} of ${counter.total}`);
+        if (elapsedMs !== null && counter.done > 0 && counter.done < counter.total) {
+            const leftMs = Math.round((elapsedMs * (counter.total - counter.done)) / counter.done);
+            parts.push(leftMs <= o.ceilingMs
+                ? `about ${durationText(leftMs)} left at that rate — one more wait covers it`
+                : `about ${durationText(leftMs)} left at that rate (${Math.ceil(leftMs / o.ceilingMs)} more waits)`);
+        }
+    }
+    if (!parts.length)
+        return '';
+    const sentence = parts.join('; ');
+    return ` ${sentence[0].toUpperCase()}${sentence.slice(1)}.`;
+}
+import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, fusedLine, isEnvFilePath, isOutsideRoot, isValidGlob, MAX_BATCH_READ_BYTES, MAX_BATCH_READ_FILES, MAX_FIND_RESULTS, MAX_OUTPUT_SIZE, MAX_READ_RETURN_CHARS, MAX_READ_SIZE, MAX_SEARCH_CONTEXT_LINES, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, outputIsWithheldUntilExit, outputRedirectTarget, parseCheckCommand, parseCheckProblem, pathArgError, printsOnlySource, redactSecrets, redactSecretsInCode, resolvePath, RUNNING_FAILURE_LINES, runningOutputSliceCommand, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, truncateMiddle, whitespaceTolerantReplace, } 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.
  */
 const OVER_CEILING_GRACE_MS = 45_000;
+/**
+ * The steer attached to a SUCCESSFUL read of a package's built output. The ENOENT
+ * redirect below fires only when the read FAILS, so a model that knows the hoisted
+ * layout reads `node_modules/@molecule/<pkg>/dist/*.js` happily and never learns the
+ * documented API is one call away (X0 flash-m70: 24 such reads in 57 s, no note on
+ * any of them). Carried as `distNote` rather than merged into `note` so a host that
+ * has read_molecule_doc (molecule-dev's cadence note, which also names the functions)
+ * can supersede it without string-matching.
+ *
+ * @param path - The resolved path that was read.
+ * @returns The note, or null when the path is not inside a package's `dist`.
+ */
+export function moleculeDistReadNote(path) {
+    const pkg = /node_modules\/@molecule\/([a-z0-9-]+)\/dist\//.exec(path)?.[1];
+    if (!pkg)
+        return null;
+    return (`This is @molecule/${pkg}'s compiled dist, not its API: read_molecule_doc("@molecule/${pkg}") ` +
+        'returns its README.md — the functions, options and bond wiring — in one call.' +
+        (/\.d\.ts$/.test(path)
+            ? ' The declarations above are generated from it.'
+            : ' For one signature, read the matching .d.ts file.'));
+}
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *
@@ -135,6 +241,8 @@ export function buildTools(backend, config) {
     }
     /** Paths read with a window in this tool set, to tell paging from one targeted read. */
     const windowedReads = new Set();
+    /** The text each path was last handed back WHOLE as, so that correction fires once per version. */
+    const wholeReturned = new Map();
     /**
      * Verify that `path` does not symlink outside the project root when guards are enabled.
      *
@@ -365,6 +473,10 @@ export function buildTools(backend, config) {
         const symlinkErr = await checkSymlink(path);
         if (symlinkErr)
             return { error: symlinkErr };
+        // Carried on every successful read of a package's built output, so no dist read
+        // goes out unsteered (see moleculeDistReadNote).
+        const distNote = moleculeDistReadNote(path);
+        const noted = (r) => distNote ? { ...r, distNote } : r;
         try {
             const content = await backend.readFile(path);
             // A read that produced no usable text is verified against the file's real
@@ -376,12 +488,12 @@ export function buildTools(backend, config) {
                 const verdict = await classifyEmptyRead(path, 'read_file');
                 if ('error' in verdict)
                     return verdict;
-                return {
+                return noted({
                     path,
                     content: sanitizeFileContent(verdict.content, path),
                     ...(verdict.content === '' ? { empty: true } : {}),
                     ...(verdict.note ? { note: verdict.note } : {}),
-                };
+                });
             }
             if (content.length > MAX_READ_SIZE)
                 return {
@@ -395,21 +507,32 @@ export function buildTools(backend, config) {
                 : window;
             // A SECOND window of the same small file: hand back all of it (one window is a targeted read). X1 flash-m50 paged files that fit in one
             // call 13 times in a row, each window answered with "read it again with no offset/limit".
+            // The bound is the one that note states (SMALL_FILE_WHOLE_CHARS = MAX_READ_RETURN_CHARS): 24 KB left
+            // RealWorld's 24,935-byte openapi.yml paged nine times under "fits in ONE call" (flash-m67).
             const small = sliceLines(content, window);
             const pagedBefore = small?.truncated ? windowedReads.has(path) : false;
             if (small?.truncated)
                 windowedReads.add(path);
-            if (small?.truncated && pagedBefore && content.length <= SMALL_FILE_WHOLE_CHARS) {
-                return {
+            // Once per version of the file: after the whole text went back, a later window is a
+            // targeted read and gets its window (X1 flash-m67: 25 firings, 8 byte-identical repeats).
+            const sentWhole = wholeReturned.get(path) === content;
+            if (small?.truncated &&
+                pagedBefore &&
+                !sentWhole &&
+                content.length <= SMALL_FILE_WHOLE_CHARS) {
+                wholeReturned.set(path, content);
+                return noted({
                     path,
                     content: sanitizeFileContent(content, path),
+                    offset: 1,
+                    lines: small.totalLines,
                     totalLines: small.totalLines,
                     note: `The whole file is returned (${Math.round(content.length / 1024)} KB, ${small.totalLines} lines): a file this small fits in one call, so it is not paged.`,
-                };
+                });
             }
             const windowed = sliceLines(content, effectiveWindow);
             if (windowed) {
-                return {
+                return noted({
                     path,
                     content: sanitizeFileContent(windowed.text, path),
                     offset: windowed.offset,
@@ -422,18 +545,21 @@ export function buildTools(backend, config) {
                     // exact next window so the executor does not have to compute it.
                     ...(windowed.truncated
                         ? {
-                            note: content.length <= MAX_READ_RETURN_CHARS
-                                ? `Lines ${windowed.offset}-${windowed.offset + windowed.lines - 1} of ` +
-                                    `${windowed.totalLines}. The whole file is ${Math.round(content.length / 1024)} KB ` +
-                                    `and fits in ONE call — read it again with no offset/limit instead of paging.`
-                                : `Lines ${windowed.offset}-${windowed.offset + windowed.lines - 1} of ` +
-                                    `${windowed.totalLines}. Next window: offset ${windowed.offset + windowed.lines}, ` +
-                                    `limit ${windowed.lines}.`,
+                            note: sentWhole
+                                ? `Lines ${windowed.offset}-${windowed.offset + windowed.lines - 1} of ${windowed.totalLines}; ` +
+                                    'the whole file, unchanged, was returned earlier in this conversation.'
+                                : content.length <= MAX_READ_RETURN_CHARS
+                                    ? `Lines ${windowed.offset}-${windowed.offset + windowed.lines - 1} of ` +
+                                        `${windowed.totalLines}. The whole file is ${Math.round(content.length / 1024)} KB ` +
+                                        `and fits in ONE call — read it again with no offset/limit instead of paging.`
+                                    : `Lines ${windowed.offset}-${windowed.offset + windowed.lines - 1} of ` +
+                                        `${windowed.totalLines}. Next window: offset ${windowed.offset + windowed.lines}, ` +
+                                        `limit ${windowed.lines}.`,
                         }
                         : {}),
-                };
+                });
             }
-            return { path, content: sanitizeFileContent(content, path) };
+            return noted({ path, content: sanitizeFileContent(content, path) });
         }
         catch (e) {
             // Backends (e.g. the docker provider's `cat`) already prefix "Failed to read <path>: ";
@@ -921,7 +1047,15 @@ export function buildTools(backend, config) {
                     ...(fusedNote
                         ? { syntaxError: fusedNote }
                         : {
-                            ...(dropped.length > 0
+                            // The evidence for this note is `located`, not `dropped`: a drop joins
+                            // two lines only when something other than a newline (or EOF) follows
+                            // the replaced text. A weaker model writes one line's change as two
+                            // replacements — the line including its trailing newline, then the
+                            // line's own text — and the newline it consumed ended that line with a
+                            // BLANK line after it, so nothing joined while the model was told it
+                            // had: it spent a new round trip putting the blank line back
+                            // (flash-m62). Say nothing when nothing was joined.
+                            ...(dropped.length > 0 && located.length > 0
                                 ? {
                                     newlineNote: `${dropped.length === 1 ? 'A replacement' : `${dropped.length} replacements`} removed the line break after the replaced text (old_string ended with a newline, new_string does not), so the next line now continues on the same line. Check the excerpt; add the newline back if that was not intended.`,
                                 }
@@ -966,7 +1100,9 @@ export function buildTools(backend, config) {
                 // search found nothing (X1 run sol-m07). A pattern that is not a valid
                 // extended regex (`foo(` — an unbalanced paren) makes grep exit 2; it is
                 // then searched as the plain text it was meant as.
-                const grepArgs = `-rn ${globArg} ${contextArg} ${grepExcludeArgs(path)} --max-count=${MAX_SEARCH_RESULTS} -- ${shellQuote(pattern)} ${shellQuote(path)}`;
+                // -H: a search scoped to one file printed `line:content` with no file, and every match
+                // came back `{file: "", line: 0}` (X1 flash-m62).
+                const grepArgs = `-rnH ${globArg} ${contextArg} ${grepExcludeArgs(path)} --max-count=${MAX_SEARCH_RESULTS} -- ${shellQuote(pattern)} ${shellQuote(path)}`;
                 const result = await backend.run(`{ grep -E ${grepArgs}; s=$?; if [ "$s" -eq 2 ]; then grep -F ${grepArgs}; fi; } 2>/dev/null || true`, { timeout: 10000 });
                 // grep emits `<file>:<line>:<content>`, so redaction runs PER MATCH on the
                 // content alone: the file prefix would otherwise hide an env assignment from
@@ -1268,7 +1404,12 @@ export function buildTools(backend, config) {
                 // truncateMiddle (not truncate): a failing build/test/migration puts its
                 // error at the TAIL, so keep the head AND the tail — head-only truncation
                 // strands the executor with passing progress and no failure reason.
-                const stdout = sanitizeOutput(truncateMiddle(result.stdout, MAX_OUTPUT_SIZE));
+                // A command that only prints source files returns file content: the code-safe grade,
+                // as read_file uses (utilities.ts printsOnlySource).
+                const grade = printsOnlySource(command)
+                    ? (s) => sanitizeFileContent(s, 'printed.ts')
+                    : sanitizeOutput;
+                const stdout = grade(truncateMiddle(result.stdout, MAX_OUTPUT_SIZE));
                 const stderr = sanitizeOutput(truncateMiddle(result.stderr, MAX_OUTPUT_SIZE));
                 if (budgetSeconds && result.exitCode === 124) {
                     return {
@@ -1351,6 +1492,33 @@ export function buildTools(backend, config) {
         // server-side costs no round trip and no context.
         async wait_for_task(input) {
             const taskId = typeof input.taskId === 'string' ? input.taskId.trim() : '';
+            // Where a task writes its own output is process memory; the task is not.
+            // An API process swapped mid-run (a release, a patch, a crash) leaves the
+            // command running in the sandbox with nothing left that remembers the file
+            // it redirects to — and then `wait_for_task` returns the task's near-empty
+            // log as the command's whole result, which is the X1 flash-m48 loss all
+            // over again (X1 flash-m63's +43:20 restart: the public walk's handle
+            // outlived the process, its redirect target did not). The script the task
+            // was started from is still on disk and carries the command, so read the
+            // target back from there. The id is format-checked before any /tmp path is
+            // built from it, exactly as the reads below are.
+            if (!outputFileByTask.has(taskId) &&
+                !outputFileProbed.has(taskId) &&
+                /^mol-bg-[a-z0-9]+-[a-z0-9]+$/.test(taskId)) {
+                outputFileProbed.add(taskId);
+                try {
+                    const target = outputRedirectTarget(await backend.readFile(`/tmp/${taskId}.sh`));
+                    // A relative target was written against the command's own cwd, which
+                    // the handle does not carry; the project root is where a background
+                    // command runs unless the caller passed one.
+                    if (target)
+                        outputFileByTask.set(taskId, target.startsWith('/') ? target : `${root}/${target}`);
+                }
+                catch (_error) {
+                    // No script under that id: this process did not start the task, so
+                    // there is nothing to recover. The log stays the whole result.
+                }
+            }
             // A command that has been waited on for stuckAfterMs() in total without
             // exiting is not going to: on one run the executor waited five times,
             // 120 s each, on an e2e suite that could never start (no browser page
@@ -1432,16 +1600,44 @@ export function buildTools(backend, config) {
                 const lastSize = logBytesByTask.get(taskId);
                 if (grownTo !== null)
                     logBytesByTask.set(taskId, grownTo);
+                // Evidence of liveness, read the same way by every answer below: a log
+                // that grew during THIS wait means the command is working. On the first
+                // wait any output at all counts (there is no earlier size to compare).
                 const stillWriting = grownTo !== null && (lastSize === undefined ? grownTo > 0 : grownTo > lastSize);
+                // The log's own slice, read ONCE for whichever answer follows: it is what
+                // the progress sentence is built from, and a wait that showed nothing was
+                // waited blind (X1 flash-m50: 4m42s across two waits on an 11-minute run).
+                // The slice leads with the failure lines, not the last bytes — a suite's
+                // tail is its progress lines (X1 flash-m61: the last 3 000 bytes of a
+                // 139-test walk were the skip list).
+                const own = outputFileByTask.get(taskId);
+                let soFar = '';
+                try {
+                    const r = await backend.run(runningOutputSliceCommand(log, own), { timeout: 5_000 });
+                    soFar = r.stdout ?? '';
+                }
+                catch (_error) {
+                    // No slice: the notes still say how to peek, and the task id still
+                    // carries how long the command has been running.
+                }
+                const progress = waitProgressNote({
+                    taskId,
+                    slice: soFar,
+                    stillWriting,
+                    bytes: grownTo,
+                    ceilingMs: ceiling,
+                });
+                const sliceField = soFar.trim() ? { outputSoFar: sanitizeOutput(soFar) } : {};
                 if (stillWriting && waitedBefore + waitedMs >= stuckAfterMs()) {
                     waitedByTask.set(taskId, 0);
                     return {
                         taskId,
                         status: 'running',
                         waitedMs,
+                        ...sliceField,
                         note: `Still running after ${Math.round((waitedBefore + waitedMs) / 1000)}s of waiting, and its ` +
-                            `output is still growing (${grownTo} bytes) — slow, not stuck. Call wait_for_task again to ` +
-                            `keep waiting; peek with exec_command: tail ${log}.`,
+                            `output is still growing (${grownTo} bytes) — slow, not stuck.${progress} Call wait_for_task ` +
+                            `again to keep waiting; peek with exec_command: tail ${log}.`,
                     };
                 }
                 if (waitedBefore + waitedMs >= stuckAfterMs()) {
@@ -1455,26 +1651,19 @@ export function buildTools(backend, config) {
                             `kill $(cat /tmp/${taskId}.pid) 2>/dev/null; pkill -f ${taskId}.sh) and move on; do not wait on it again.`,
                     };
                 }
-                // The output so far rides the result: a wait that shows nothing was waited blind
-                // (X1 flash-m50: 4m42s across two waits on an 11-minute run).
-                const own = outputFileByTask.get(taskId);
-                let soFar;
-                try {
-                    const r = await backend.run(`cat ${log}${own ? ` ${shellQuote(own)}` : ''} 2>/dev/null | tail -c 3000`, { timeout: 5_000 });
-                    soFar = r.stdout ?? '';
-                }
-                catch (_error) {
-                    // No tail: the note still says how to peek.
-                    soFar = '';
-                }
                 return {
                     taskId,
                     status: 'running',
                     waitedMs,
-                    ...(soFar.trim() ? { outputSoFar: sanitizeOutput(soFar) } : {}),
-                    note: `Still running after ${Math.round(waitedMs / 1000)}s. Call wait_for_task again to ` +
-                        `keep waiting — its result carries the log output${soFar.trim() ? '; outputSoFar is the end of the log as it stands, so there is no need to tail it' : ''}. ` +
-                        `Do other work in the meantime (another suite, a fix you have already found) rather than waiting.`,
+                    ...sliceField,
+                    note: `Still running after ${Math.round(waitedMs / 1000)}s.${progress} Call wait_for_task again to ` +
+                        `keep waiting — its result carries the log output. ` +
+                        (soFar.trim()
+                            ? `outputSoFar is the failure lines so far (up to ${RUNNING_FAILURE_LINES}) and then the end of ` +
+                                `the log, not the whole run — \`grep -n '✘' ${log} | head -40\` lists every failure, ` +
+                                `\`grep -n -A 20 '<test name>' ${log}\` reads one failure's error. `
+                            : `Nothing has been printed yet — \`grep -n '✘' ${log} | head -40\` lists failures as they appear. `) +
+                        `Meanwhile do work that leaves the code under test alone (read the failures so far, plan the fixes): editing app/src or api/src now changes the code the run is testing, and its result no longer counts.`,
                 };
             }
             let output;

package/dist/utilities.d.ts

@@ -55,6 +55,17 @@ export declare function redactSecrets(s: string): string;
  * @returns A redacted copy that preserves ordinary code verbatim.
  */
 export declare function redactSecretsInCode(s: string): string;
+/**
+ * Whether a shell command only PRINTS source files (`cat a.tsx`, `sed -n '1,40p' x.ts`,
+ * `head -50 b.hurl`): its output is file content and gets the code-safe redaction, like
+ * read_file. Through the env-dump grade a printed `type AuthState = 'authenticated' | …`
+ * came back as `'[REDACTED]'`, and the executor wrote the mask into a new file (X1
+ * flash-m58). Any segment that is not such a print, or any env file named, keeps the full grade.
+ *
+ * @param command - The shell command.
+ * @returns True when every segment prints source files only.
+ */
+export declare function printsOnlySource(command: string): boolean;
 /**
  * Whether a path is an env file, for which {@link redactSecrets}' full env-dump
  * treatment is appropriate rather than {@link redactSecretsInCode}. Matches
@@ -108,9 +119,16 @@ export declare function outputRedirectTarget(command: string): string | null;
  * - a trailing `| tail -N`, which holds everything back until the command ends.
  *   It is dropped: `wait_for_task` already returns the end of the log.
  * - `playwright test` with no `--reporter`, which runs the config's reporter —
- *   often `html`, which prints nothing per test. `--reporter=line` is added
+ *   often `html`, which prints nothing per test. `--reporter=list` is added
  *   when the playwright run is the command's last step and nothing is piped or
- *   redirected from it ( aside); the results are the same, printed as they happen.
+ *   redirected from it: it writes each result as it finishes, and it is the
+ *   shape the platform reads a background suite back in (`suite-fail-fast.ts`'s
+ *   fail-fast note and the Tests bar both parse `list` lines). A run that names
+ *   `--reporter=line` is switched to `list` for the same reason — `line` writes
+ *   `[n/N] <title>` with no ✓/✘ mark and no duration, so on X1 flash-m62 an
+ *   8.3-minute walk of one suite could never trip the fail-fast note.
+ *
+ * Only the command's last step is touched, and only its reporter.
  *
  * @param command - The command as the executor sent it.
  * @returns The command to run and one sentence per change made (empty when none).
@@ -249,7 +267,11 @@ export declare const MAX_BATCH_READ_BYTES: number;
  * needs.
  */
 export declare const MAX_READ_RETURN_CHARS: number;
-/** A file this small is returned whole even when a window is asked for (paging it costs a call each). */
+/**
+ * A file this small is returned whole on a second window of it (paging it costs a call each).
+ * The same bound as {@link MAX_READ_RETURN_CHARS}: the windowed-read note promises that a
+ * file under it "fits in ONE call", and a smaller bound here broke that promise (X1 flash-m67).
+ */
 export declare const SMALL_FILE_WHOLE_CHARS: number;
 /** Max search results. */
 export declare const MAX_SEARCH_RESULTS = 50;
@@ -296,6 +318,29 @@ export declare function truncateMiddle(s: string, maxLength: number): string;
  * @returns Each block, in order (empty when there are none).
  */
 export declare function failureBlocks(s: string): string[];
+/** Failure lines shown from a log that is still being written. */
+export declare const RUNNING_FAILURE_LINES = 40;
+/** Bytes of a running log's end appended after its failure lines. */
+export declare const RUNNING_TAIL_BYTES = 1000;
+/**
+ * The lines worth showing from a log that is still being written: a failed test's mark or
+ * numbered block header, and a runner's own error lines. Matched with `grep -E`.
+ */
+export declare const RUNNING_FAILURE_LINE_RE = "^[[:space:]]*(\u2718|\u2717|\u00D7|\u2716|\u2715|[0-9]+\\)|[0-9]+ (passed|failed|flaky|skipped|did not run)|FAIL|FAILED|ERROR|Error:|error:|Traceback|AssertionError)";
+/**
+ * The shell command whose stdout is the interesting part of a log that is still being written:
+ * the failure lines so far (capped at {@link RUNNING_FAILURE_LINES}), then the end of the log.
+ *
+ * A Playwright `list` run prints one line per test as it finishes and its error blocks only at
+ * the end, so the LAST bytes of a running log are its least informative part — in X1 flash-m61
+ * the last 3 000 bytes of a 139-test walk were the skip list, and all 61 failures were above
+ * them, which cost the run the grep it had to make anyway.
+ *
+ * @param log - The task log path.
+ * @param own - A file the command redirects its own output to, if any.
+ * @returns The shell command, safe to hand to the execution backend as-is.
+ */
+export declare function runningOutputSliceCommand(log: string, own?: string): string;
 /**
  * Attempt a whitespace-tolerant replacement when an exact `old_string` match
  * failed. Finds a contiguous run of lines in `content` whose per-line

package/dist/utilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utilities.d.ts","sourceRoot":"","sources":["../src/utilities.ts"],"names":[],"mappings":"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"}

package/dist/utilities.js

@@ -98,9 +98,15 @@ const NON_SECRET_VALUES = new Set([
  * @param quote - The quote character the value uses (`"` or `'`).
  * @returns A String.replace replacer preserving allowlisted values.
  */
-const jsonValueReplacer = (quote) => (match, prefix) => {
+const jsonValueReplacer = (quote) => (match, prefix, offset, whole) => {
     const value = match.slice(prefix.length);
     const inner = value.slice(1, -1);
+    // A TypeScript type literal is never a credential: `type AuthState = 'authenticated' | …`
+    // (X1 flash-m58). A union member is followed by `|`; a declaration starts `type`.
+    if (/^\s*\|/.test(whole.slice(offset + match.length)))
+        return match;
+    if (/\btype\s+$/.test(whole.slice(Math.max(0, offset - 16), offset)))
+        return match;
     // An empty value hides nothing, and a suite fixture's `"password": ""` is the fact a
     // failing assertion turns on (X1 flash-m52).
     // A version (`"jsonwebtoken": "9.0.2"`, a package name that holds a keyword) is not a
@@ -153,6 +159,61 @@ export function redactSecrets(s) {
 export function redactSecretsInCode(s) {
     return s.replace(SECRET_ENV_ASSIGNMENT, '$1=[REDACTED]');
 }
+/** Source-file extensions a printing command's output is read as code for. */
+const SOURCE_FILE_RE = /\.(?:[cm]?[jt]sx?|css|scss|html|vue|svelte|md|sql|hurl)$/;
+/**
+ * Whether a shell command only PRINTS source files (`cat a.tsx`, `sed -n '1,40p' x.ts`,
+ * `head -50 b.hurl`): its output is file content and gets the code-safe redaction, like
+ * read_file. Through the env-dump grade a printed `type AuthState = 'authenticated' | …`
+ * came back as `'[REDACTED]'`, and the executor wrote the mask into a new file (X1
+ * flash-m58). Any segment that is not such a print, or any env file named, keeps the full grade.
+ *
+ * @param command - The shell command.
+ * @returns True when every segment prints source files only.
+ */
+export function printsOnlySource(command) {
+    if (/\.env\b/.test(command))
+        return false;
+    const segments = command
+        .split(/\s*(?:&&|;|\n)\s*/)
+        .map((s) => s.trim())
+        .filter((s) => s && !/^cd\s/.test(s));
+    if (segments.length === 0)
+        return false;
+    return segments.every((seg) => {
+        // Words, quotes kept whole: a grep pattern like "sign\\|verify" is one word, not a pipe.
+        const words = seg.match(/"(?:\\.|[^"\\])*"|'[^']*'|\S+/g) ?? [];
+        const stages = [[]];
+        for (const w of words) {
+            if (w === '|')
+                stages.push([]);
+            else if (!/^\d?>&\d$|^2>\/dev\/null$/.test(w))
+                stages[stages.length - 1].push(w);
+        }
+        const [first, ...rest] = stages;
+        const head = first[0];
+        // A print of named source files: cat/head/tail/nl/sed -n, or a non-recursive grep/rg
+        // (X1 flash-m61 read a fixture's password masked through `grep -n … auth.hurl`).
+        let args = first.slice(1);
+        if (head === 'sed' && args[0] !== '-n')
+            return false;
+        if (head === 'grep' || head === 'rg') {
+            if (args.some((a) => /^-[a-zA-Z]*[rR]/.test(a) || a === '--recursive'))
+                return false;
+            const flags = args.filter((a) => a.startsWith('-'));
+            const rest2 = args.filter((a) => !a.startsWith('-'));
+            args = flags.includes('-e') ? rest2 : rest2.slice(1);
+        }
+        else if (!/^(?:cat|head|tail|nl|sed)$/.test(head ?? ''))
+            return false;
+        const files = args.filter((t) => !t.startsWith('-') && !/^'[^']*'$|^"[^"]*"$|^\d+$|^\d+,\d+p$/.test(t));
+        if (files.length === 0 || !files.every((f) => SOURCE_FILE_RE.test(f)))
+            return false;
+        // After it, only text filters that read no file of their own.
+        return rest.every((stage) => /^(?:head|tail|sort|uniq|wc|cut|nl|grep)$/.test(stage[0] ?? '') &&
+            !stage.slice(1).some((a) => !a.startsWith('-') && /\.[a-z]+$/i.test(a) && !/^['"]/.test(a)));
+    });
+}
 /**
  * Whether a path is an env file, for which {@link redactSecrets}' full env-dump
  * treatment is appropriate rather than {@link redactSecretsInCode}. Matches
@@ -226,6 +287,8 @@ export function outputRedirectTarget(command) {
 }
 /** A trailing `| tail -N` / `| tail -n N` (stderr redirects before it stay). */
 const TRAILING_TAIL = /\s*\|\s*tail(?:\s+-n)?\s+[-+]?\d+\s*$/;
+/** `--reporter=line` / `--reporter line`, the one reporter the platform cannot read back. */
+const LINE_REPORTER_FLAG = /--reporter([= ])line\b/;
 /**
  * Rewrite a command about to run in the background so its log grows while it
  * runs. Two shapes left the log empty until exit, and an empty log is what
@@ -235,9 +298,16 @@ const TRAILING_TAIL = /\s*\|\s*tail(?:\s+-n)?\s+[-+]?\d+\s*$/;
  * - a trailing `| tail -N`, which holds everything back until the command ends.
  *   It is dropped: `wait_for_task` already returns the end of the log.
  * - `playwright test` with no `--reporter`, which runs the config's reporter —
- *   often `html`, which prints nothing per test. `--reporter=line` is added
+ *   often `html`, which prints nothing per test. `--reporter=list` is added
  *   when the playwright run is the command's last step and nothing is piped or
- *   redirected from it ( aside); the results are the same, printed as they happen.
+ *   redirected from it: it writes each result as it finishes, and it is the
+ *   shape the platform reads a background suite back in (`suite-fail-fast.ts`'s
+ *   fail-fast note and the Tests bar both parse `list` lines). A run that names
+ *   `--reporter=line` is switched to `list` for the same reason — `line` writes
+ *   `[n/N] <title>` with no ✓/✘ mark and no duration, so on X1 flash-m62 an
+ *   8.3-minute walk of one suite could never trip the fail-fast note.
+ *
+ * Only the command's last step is touched, and only its reporter.
  *
  * @param command - The command as the executor sent it.
  * @returns The command to run and one sentence per change made (empty when none).
@@ -259,12 +329,20 @@ export function streamingBackgroundCommand(command) {
         changes.push(`Dropped the trailing \`${head[0].trim()}\`: Playwright prints its pass/fail count last, and it would be cut.`);
     }
     const lastStep = out.split(/&&|\|\||;/).at(-1) ?? '';
-    if (/\bplaywright\s+test\b/.test(lastStep) &&
-        !/--reporter\b/.test(lastStep) &&
+    const finalPlaywrightRun = /\bplaywright\s+test\b/.test(lastStep) &&
         // `2>&1` only joins stderr to the log; any other pipe or redirect sends the output elsewhere.
-        !/[|>]/.test(lastStep.replace(/\d?>&\d/g, ''))) {
-        out = `${out.trimEnd()} --reporter=line`;
-        changes.push('Added `--reporter=line` so each test result is written to the log as it finishes ' +
+        !/[|>]/.test(lastStep.replace(/\d?>&\d/g, ''));
+    if (finalPlaywrightRun && LINE_REPORTER_FLAG.test(lastStep)) {
+        // Only the last step is rewritten, and `lastStep` is a suffix of `out`.
+        out =
+            out.slice(0, out.length - lastStep.length) +
+                lastStep.replace(LINE_REPORTER_FLAG, '--reporter$1list');
+        changes.push('Switched `--reporter=line` to `--reporter=list`: it also writes each test result as it ' +
+            'finishes, and it is the shape the platform reads back from a background run.');
+    }
+    else if (finalPlaywrightRun && !/--reporter\b/.test(lastStep)) {
+        out = `${out.trimEnd()} --reporter=list`;
+        changes.push('Added `--reporter=list` so each test result is written to the log as it finishes ' +
             '(the config reporter may print nothing until the end).');
     }
     return { command: out, changes };
@@ -283,7 +361,8 @@ export function streamingBackgroundCommand(command) {
  * a keyless build still succeeds, and blocking those sent it looking for
  * workarounds (X0 rehearsal 14).
  */
-const BLOCKED_COMMANDS = /(?:^|[;&|`]\s*|(?:sh|bash|zsh|dash)\s+-c\s+['"]?\s*)(?:\/usr\/bin\/)?(?:\benv(?:\s+(?:-0|--null|--))?\s*(?:$|[;&|>)`'"])|\bprintenv\b|\bexport\s*$|\bset\s*$|\bdeclare\s+-x|cat\s+\/etc\/environment|cat\s+\/root\/\.bashrc|cat\s+\/proc\/\d+\/environ|cat\s+\/proc\/self\/environ|strings\s+\/proc|xargs[^;&|\n]*\/proc\/[^;&|\n]*environ|less\s+\/proc|head\s+\/proc|tail\s+\/proc|xxd\s+\/proc|od\s+\/proc|base64\s+\/proc|dd\s[^\n]*\/proc|sed\s[^\n]*\/proc\/[^\n]*environ|awk\s[^\n]*\/proc\/[^\n]*environ|cp\s[^\n]*\/proc\/[^\n]*environ|(?:cat|less|head|tail|xxd|od|base64|strings|dd|cp|sed|awk)\s[^\n;&|]*\/etc\/mol(?:\/|\b))/i;
+// `(?<!\\)`: a backslash-escaped `\|` is a literal in the shell (grep "a\|env"), not a pipe (X1 flash-m58).
+const BLOCKED_COMMANDS = /(?<!\\)(?:^|[;&|`]\s*|(?:sh|bash|zsh|dash)\s+-c\s+['"]?\s*)(?:\/usr\/bin\/)?(?:\benv(?:\s+(?:-0|--null|--))?\s*(?:$|[;&|>)`'"])|\bprintenv\b|\bexport\s*$|\bset\s*$|\bdeclare\s+-x|cat\s+\/etc\/environment|cat\s+\/root\/\.bashrc|cat\s+\/proc\/\d+\/environ|cat\s+\/proc\/self\/environ|strings\s+\/proc|xargs[^;&|\n]*\/proc\/[^;&|\n]*environ|less\s+\/proc|head\s+\/proc|tail\s+\/proc|xxd\s+\/proc|od\s+\/proc|base64\s+\/proc|dd\s[^\n]*\/proc|sed\s[^\n]*\/proc\/[^\n]*environ|awk\s[^\n]*\/proc\/[^\n]*environ|cp\s[^\n]*\/proc\/[^\n]*environ|(?:cat|less|head|tail|xxd|od|base64|strings|dd|cp|sed|awk)\s[^\n;&|]*\/etc\/mol(?:\/|\b))/i;
 /** Block shell redirects from /proc environ. */
 const BLOCKED_PROC_REDIRECT = /(?:<\s*\/proc\/(?:\d+|self)\/environ)/i;
 /** Block shell redirects from the molecule platform secrets dir (`/etc/mol`). */
@@ -498,8 +577,12 @@ export const MAX_BATCH_READ_BYTES = 200 * 1024;
  * needs.
  */
 export const MAX_READ_RETURN_CHARS = 80 * 1024;
-/** A file this small is returned whole even when a window is asked for (paging it costs a call each). */
-export const SMALL_FILE_WHOLE_CHARS = 24 * 1024;
+/**
+ * A file this small is returned whole on a second window of it (paging it costs a call each).
+ * The same bound as {@link MAX_READ_RETURN_CHARS}: the windowed-read note promises that a
+ * file under it "fits in ONE call", and a smaller bound here broke that promise (X1 flash-m67).
+ */
+export const SMALL_FILE_WHOLE_CHARS = MAX_READ_RETURN_CHARS;
 /** Max search results. */
 export const MAX_SEARCH_RESULTS = 50;
 /** Max find results. */
@@ -554,6 +637,33 @@ export function truncate(s, maxLength) {
 export function truncateMiddle(s, maxLength) {
     if (s.length <= maxLength)
         return s;
+    // Room for the tally line it may append, so the result stays near the cap.
+    return withRunTally(s, truncateMiddleBody(s, Math.max(Math.floor(maxLength / 2), maxLength - 200)));
+}
+/**
+ * A test run's tally lines (`  3 failed`, `  71 passed (4.6m)`) the cut text lost, put back at
+ * its end: Playwright lists every failed test after its "N failed" line, so a long list pushed
+ * the line itself into the cut middle and the run read as having no failures (X1 flash-m60).
+ *
+ * @param original - The whole output.
+ * @param cut - The truncated output.
+ * @returns The cut output, with any lost tally lines appended.
+ */
+function withRunTally(original, cut) {
+    const tally = [
+        ...original.matchAll(/^\s*\d+ (?:failed|passed|flaky|skipped|did not run|interrupted)\b[^\n]{0,40}$/gm),
+    ].map((m) => m[0].trim());
+    const lost = tally.filter((line) => !cut.includes(line));
+    return lost.length ? `${cut}\n[run tally] ${lost.join(' · ')}` : cut;
+}
+/**
+ * {@link truncateMiddle} without the tally guard.
+ *
+ * @param s - The text.
+ * @param maxLength - The budget.
+ * @returns The cut text.
+ */
+function truncateMiddleBody(s, maxLength) {
     // Reserve room for the elision notice so head + notice + tail stays WITHIN
     // maxLength — the cap is a real token budget the caller relies on (a head-only
     // truncate that overshoots by its suffix length breaks that contract). 140 =
@@ -624,6 +734,33 @@ export function failureBlocks(s) {
         blocks.push(current.join('\n').trimEnd());
     return blocks;
 }
+/** Failure lines shown from a log that is still being written. */
+export const RUNNING_FAILURE_LINES = 40;
+/** Bytes of a running log's end appended after its failure lines. */
+export const RUNNING_TAIL_BYTES = 1000;
+/**
+ * The lines worth showing from a log that is still being written: a failed test's mark or
+ * numbered block header, and a runner's own error lines. Matched with `grep -E`.
+ */
+export const RUNNING_FAILURE_LINE_RE = '^[[:space:]]*(✘|✗|×|✖|✕|[0-9]+\\)|[0-9]+ (passed|failed|flaky|skipped|did not run)|FAIL|FAILED|ERROR|Error:|error:|Traceback|AssertionError)';
+/**
+ * The shell command whose stdout is the interesting part of a log that is still being written:
+ * the failure lines so far (capped at {@link RUNNING_FAILURE_LINES}), then the end of the log.
+ *
+ * A Playwright `list` run prints one line per test as it finishes and its error blocks only at
+ * the end, so the LAST bytes of a running log are its least informative part — in X1 flash-m61
+ * the last 3 000 bytes of a 139-test walk were the skip list, and all 61 failures were above
+ * them, which cost the run the grep it had to make anyway.
+ *
+ * @param log - The task log path.
+ * @param own - A file the command redirects its own output to, if any.
+ * @returns The shell command, safe to hand to the execution backend as-is.
+ */
+export function runningOutputSliceCommand(log, own) {
+    const read = `cat ${log}${own ? ` ${shellQuote(own)}` : ''} 2>/dev/null`;
+    return (`{ ${read} | grep -aE ${shellQuote(RUNNING_FAILURE_LINE_RE)} | head -${RUNNING_FAILURE_LINES} | cut -c1-300; ` +
+        `echo; ${read} | tail -c ${RUNNING_TAIL_BYTES}; }`);
+}
 /**
  * Attempt a whitespace-tolerant replacement when an exact `old_string` match
  * failed. Finds a contiguous run of lines in `content` whose per-line

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-ai-tools",
-  "version": "1.5.15",
+  "version": "1.5.17",
   "description": "Shared AI agent tools with backend abstraction for sandbox and local execution",
   "type": "module",
   "main": "dist/index.js",