@molecule/api-ai-tools 1.8.1 → 1.8.3

package/dist/tools.d.ts

@@ -60,8 +60,47 @@ export declare const SUITE_OVER_BUDGET_ADVICE: string;
  */
 export declare function moleculeDistReadNote(path: string): string | null;
 /**
- * The refusal for a write whose target is inside an installed package, or null
- * when the path is not under a `node_modules` directory.
+ * What the filesystem says about a write target under `node_modules` — the half
+ * of the decision a path's spelling cannot make.
+ *
+ * @remarks
+ * A path that reads `node_modules` is not necessarily an install: a run links
+ * `node_modules` beside its e2e copy to borrow the hoisted tree, and that link
+ * is its own. X0 xr-molecule-flash-m106 (+07:58) made exactly that link, found
+ * it dangling (everything was hoisted to `/workspace/node_modules`), and was
+ * refused three times for trying to remove it — 40 s and a "3rd time this turn
+ * … ask the user" escalation, in an unattended run, over a broken symlink in
+ * the run's own scratch directory. So the guard asks what is there.
+ */
+export interface InstalledPackageFacts {
+    /** Whether the `node_modules` entry the path goes through is a symbolic link. */
+    readonly symlink: boolean;
+    /** Whether a package is really installed there: a `package.json` resolves under the entry. */
+    readonly installed: boolean;
+}
+/**
+ * Looks at the filesystem for {@link InstalledPackageFacts}.
+ *
+ * The guard cannot `stat` the path itself: the tools act through a backend (a
+ * sandbox over the network for the fleet), so the caller — which holds that
+ * backend — supplies the look. {@link shellInstalledPackageProbe} builds one
+ * from any shell runner.
+ */
+export type InstalledPackageProbe = (path: string) => Promise<InstalledPackageFacts>;
+/**
+ * Build an {@link InstalledPackageProbe} from a shell runner (a backend's
+ * `run`, or a sandbox's `exec`): one command reports whether the entry is a
+ * link and whether a `package.json` resolves under it.
+ *
+ * @param run - Runs a command where the path lives.
+ * @returns The probe.
+ */
+export declare function shellInstalledPackageProbe(run: (command: string) => Promise<{
+    stdout?: string;
+} | null | undefined>): InstalledPackageProbe;
+/**
+ * The refusal for a write whose target is inside an INSTALLED package, or null
+ * when the path is not under `node_modules` or nothing is installed there.
  *
  * `node_modules` is not the project's code: nothing written there survives the
  * next install, no deploy carries it, and a sandbox whose dependency tree is
@@ -74,6 +113,19 @@ export declare function moleculeDistReadNote(path: string): string | null;
  * putting the file back. Reading these files stays allowed (that is how the
  * declarations above are read at all).
  *
+ * What is protected is the INSTALL, not the spelling: the decision comes from
+ * {@link InstalledPackageFacts}, never from the path alone (m106 above). Three
+ * things are the run's own to remove or replace —
+ *
+ * - a `node_modules` that is a SYMLINK: `rm`/`unlink` removes the link, never the
+ *   tree it points at, so a link the run made cannot clobber anything;
+ * - anything under the run's own `.mol-scratch/` directory;
+ * - a `node_modules` with no `package.json` under it (nothing was ever installed).
+ *
+ * A path INSIDE the link is still decided by what resolves there: a link into a
+ * real tree is refused, because removing or writing through it reaches the
+ * install.
+ *
  * The restore route is named because the model that has ALREADY clobbered a file
  * (this refusal is too late for it) is the one who needs it, and because the
  * obvious repair — `npm install <pkg>` — is itself refused in the pre-installed
@@ -81,9 +133,10 @@ export declare function moleculeDistReadNote(path: string): string | null;
  * m91 used, and what both guards leave alone.
  *
  * @param path - An absolute path a tool is about to write.
+ * @param probe - Looks at the filesystem where the path lives.
  * @returns The one-line refusal naming the package, or null when nothing is installed there.
  */
-export declare function installedPackageWriteRefusal(path: string): string | null;
+export declare function installedPackageWriteRefusal(path: string, probe?: InstalledPackageProbe): Promise<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;AA0G9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAyHD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAkEnE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AAmBlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAsBxE;AAgDD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAyzExF"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAgJ9C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAahG;AAiOD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAmEnE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,QAEA,CAAA;AAE9B;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,wBAAwB,QAI6C,CAAA;AAmBlF;;;;;;;;;;;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;AAgDD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,EAAE,CAu2ExF"}

package/dist/tools.js

@@ -10,6 +10,7 @@ import { commandCutRun, CUT_AT_BUDGET, cutRunSentence, suiteRunExitCode } from '
 import { addChangeSpan, changedSpan, countLines, renderEditExcerpt, renderSmallFile, } from './edit-excerpt.js';
 import { guardToolExecute, missingParamError, ToolInputError } from './input-normalizer.js';
 import { TOOL_SCHEMAS } from './schemas.js';
+import { leadingSleepPeek } from './sleep-peek.js';
 /**
  * Total waiting, per background task, after which wait_for_task reports it
  * stuck instead of waiting again. Env-tunable so a test can exercise it.
@@ -44,6 +45,36 @@ const runByTask = new Map();
 const FILTERED_EXIT_NOTE = 'No exit code is reported for this run: a stage after the test runner produced the pipeline’s ' +
     'code (or the code says 0 beside a failure in the tally), so read the pass/fail tally in the ' +
     'log instead.';
+/**
+ * What a finished run says when its suite sits inside a `sh -c '<command>'` string: the stages are
+ * positions in THAT string, so the platform cannot point at one in the command's own text. Said
+ * instead of {@link FILTERED_EXIT_NOTE} — that note names a stage after the runner, and this run
+ * cannot be read as having one; a command with nothing piped after the runner keeps its code.
+ */
+const UNPLACED_KEPT_NOTE = 'The suite sits inside a `sh -c` string, so its stages cannot be placed in the command’s own ' +
+    'text; nothing follows the runner there, so the exit code above is the run’s own — read the ' +
+    'pass/fail tally in the log for the verdict.';
+/** {@link UNPLACED_KEPT_NOTE} when between them a stage after the runner produced the code. */
+const UNPLACED_PIPED_NOTE = 'The suite sits inside a `sh -c` string, so its stages cannot be placed in the command’s own ' +
+    'text, and a stage after the runner may have produced the pipeline’s code: none is reported, ' +
+    'so read the pass/fail tally in the log instead.';
+/**
+ * The sentence a finished suite run's result carries about its exit code, or null when the code it
+ * reports is the run's own and needs no explanation.
+ *
+ * {@link FILTERED_EXIT_NOTE} names a stage after the runner, so it is said only when the parse
+ * found one; a run whose stages cannot be placed says THAT instead, and keeps the command's own
+ * code when nothing follows the runner.
+ *
+ * @param placement - Where the code came from ({@link suiteRunPipelinePlacement}).
+ * @param reported - The code the result reports, or null when it reports none.
+ * @returns The note, or null.
+ */
+function suiteExitCodeNote(placement, reported) {
+    if (placement.unplaced)
+        return reported === null ? UNPLACED_PIPED_NOTE : UNPLACED_KEPT_NOTE;
+    return reported === null ? FILTERED_EXIT_NOTE : null;
+}
 /**
  * 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
@@ -229,8 +260,106 @@ function runningNote(clauses) {
     const joined = clauses.join('; ');
     return `${joined[0].toUpperCase()}${joined.slice(1)}.`;
 }
+/**
+ * The background task a leading `sleep` was about to peek at, and its state now — or null when the
+ * command has no task of this process's to report, in which case the sleep runs as written (the
+ * tool's own budget bounds it, as before).
+ *
+ * X1 xr-molecule-flash-m105 (+08:49 → +10:53, 2026-10-17) hand-polled with `sleep N; tail …`
+ * three times. The state the executor wanted was always one the platform already held: two tasks
+ * had ended 0.1 s in (exit 127, and `Error: No tests found`) and the third was live at 72 of 139
+ * with failures the log already carried. So a command that opens with a long sleep is answered
+ * from the same reads `wait_for_task` makes — the exit file, and the failure-lines-plus-tail slice
+ * of the log — and the sleep is dropped.
+ *
+ * The command names WHAT it is peeking at (`/tmp/<id>.log`, or the file the task redirects its own
+ * output to), and that task is the answer whether it has ended or not: the two dead peeks are
+ * exactly this shape. With no name to follow, the newest LIVE task is the answer — the point of
+ * the rule is that a sleep never outlives a run it could have been waiting on — and with no live
+ * task there is nothing to report.
+ *
+ * @param backend - The execution backend the task runs on.
+ * @param command - The command whose leading sleep is being replaced.
+ * @param seconds - The seconds that leading sleep asked for.
+ * @param ceilingMs - The wait ceiling a `wait_for_task` would have, so the ETA it states is the
+ *   one an actual wait would act on.
+ * @returns One sentence naming the task's state and how to get its result, plus the log slice the
+ *   caller attaches as `outputSoFar`; null when no task answers this command.
+ */
+async function backgroundTaskState(backend, command, seconds, ceilingMs) {
+    const ids = [...runByTask.keys()];
+    if (!ids.length)
+        return null;
+    const exitCodeOf = async (id) => {
+        try {
+            const raw = await backend.readFile(`/tmp/${id}.exit`);
+            const code = Number.parseInt(raw.trim(), 10);
+            return Number.isFinite(code) ? code : 0;
+        }
+        catch (_error) {
+            // No exit file yet: the task is still running. Not an error.
+            return null;
+        }
+    };
+    const names = (id) => {
+        if (command.includes(`/tmp/${id}.log`))
+            return true;
+        const own = outputFileByTask.get(id);
+        return own !== undefined && command.includes(own);
+    };
+    const newestFirst = [...ids].reverse();
+    const namedId = newestFirst.find(names);
+    let target = namedId
+        ? { id: namedId, exitCode: await exitCodeOf(namedId) }
+        : null;
+    if (!target) {
+        // Bounded: a long session can leave many finished tasks behind, and each look costs a read.
+        for (const id of newestFirst.slice(0, 8)) {
+            const exitCode = await exitCodeOf(id);
+            if (exitCode === null) {
+                target = { id, exitCode };
+                break;
+            }
+        }
+    }
+    if (!target)
+        return null;
+    let slice = '';
+    try {
+        const r = await backend.run(runningOutputSliceCommand(`/tmp/${target.id}.log`, outputFileByTask.get(target.id)), { timeout: 5_000 });
+        slice = r.stdout ?? '';
+    }
+    catch (_error) {
+        // No slice: the note still says the task's state and how to get its result.
+    }
+    const secondsText = `Did not sleep ${Math.round(seconds)} s: background task \`${target.id}\``;
+    if (target.exitCode === null) {
+        const facts = waitProgressClauses({
+            taskId: target.id,
+            slice,
+            stillWriting: false,
+            bytes: null,
+            ceilingMs,
+            waitedMs: 0,
+        });
+        const failures = slice.trim() ? '; the failures already in its log are in outputSoFar' : '';
+        return {
+            note: `${secondsText} is live (${facts.join('; ')})${failures} — ` +
+                `\`wait_for_task ${target.id}\` returns its result the moment it ends.`,
+            slice,
+        };
+    }
+    const counter = logProgress(slice);
+    const progress = counter ? `, at ${counter.done} of ${counter.total} in its log` : '';
+    const failures = slice.trim() ? '; the failures in its log are in outputSoFar' : '';
+    return {
+        note: `${secondsText} had already ended (exit code ${target.exitCode})${progress}${failures} — ` +
+            `\`wait_for_task ${target.id}\` returns its result now.`,
+        slice,
+    };
+}
 import { diagnosisTraceCommand } from './trace-artifacts.js';
-import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, earlyReturnCause, emptyCallError, failureCausesNote, findPathArgs, findPatternArgs, fusedLine, htmlOutline, isCommandTimeout, isEnvFilePath, isOutsideRoot, isPlaywrightRunCommand, isSuiteRunCommand, isValidGlob, linesWithinSerialized, literalDirPrefix, 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, printsOnlySource, READ_RESULT_ENVELOPE_CHARS, redactSecrets, redactSecretsInCode, repeatingFailure, repeatingFailureNote, resolvePath, RUNNING_FAILURE_LINES, runningCauseCommand, runningOutputSliceCommand, searchTimeoutError, serializedChars, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, suiteRunPipedAfterRunner, suiteRunPriorityLaunch, truncateMiddle, universalCause, whitespaceTolerantReplace, } from './utilities.js';
+import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, earlyReturnCause, emptyCallError, failureCausesNote, findPathArgs, findPatternArgs, fusedLine, htmlOutline, isCommandTimeout, isEnvFilePath, isOutsideRoot, isPlaywrightRunCommand, isSuiteRunCommand, isValidGlob, linesWithinSerialized, literalDirPrefix, 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, printsOnlySource, READ_RESULT_ENVELOPE_CHARS, redactSecrets, redactSecretsInCode, repeatingFailure, repeatingFailureNote, resolvePath, RUNNING_FAILURE_LINES, runningCauseCommand, runningOutputSliceCommand, searchTimeoutError, serializedChars, shellQuote, sliceLines, SMALL_FILE_WHOLE_CHARS, streamingBackgroundCommand, stripControlChars, suiteRunPipelinePlacement, suiteRunPriorityLaunch, truncateMiddle, universalCause, 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.
@@ -298,8 +427,51 @@ export function moleculeDistReadNote(path) {
             : ' For one signature, read the matching .d.ts file.'));
 }
 /**
- * The refusal for a write whose target is inside an installed package, or null
- * when the path is not under a `node_modules` directory.
+ * The `node_modules` entry a path goes through, and the package name after it
+ * (`null` when the path IS the entry).
+ *
+ * @param path - An absolute path.
+ * @returns The entry and the name, or null when no `node_modules` component is in the path.
+ */
+function nodeModulesParts(path) {
+    // A path may sit in a NESTED node_modules (`app/node_modules/...`) as well as the
+    // hoisted root one: both can be installed trees.
+    const at = /(?:^|\/)node_modules(?:\/|$)/.exec(path);
+    if (!at)
+        return null;
+    const head = path.slice(0, at.index);
+    const entry = `${head}${head === '' || head.endsWith('/') ? '' : '/'}node_modules`;
+    const named = /node_modules\/((?:@[^/]+\/)?[^/]+)(?:\/|$)/.exec(path.slice(at.index));
+    return { entry, name: named?.[1] ?? null };
+}
+/**
+ * Build an {@link InstalledPackageProbe} from a shell runner (a backend's
+ * `run`, or a sandbox's `exec`): one command reports whether the entry is a
+ * link and whether a `package.json` resolves under it.
+ *
+ * @param run - Runs a command where the path lives.
+ * @returns The probe.
+ */
+export function shellInstalledPackageProbe(run) {
+    return async (path) => {
+        const parts = nodeModulesParts(path);
+        if (!parts)
+            return { symlink: false, installed: false };
+        const { entry, name } = parts;
+        // A bare `@scope` is not a package, but removing it takes every package under
+        // it: treat the scope directory like the entry itself and look beneath it.
+        const scopeOnly = name !== null && /^@[^/]+$/.test(name);
+        const install = name !== null && !scopeOnly
+            ? `if [ -e ${shellQuote(`${entry}/${name}/package.json`)} ]; then echo installed; fi`
+            : `if find ${shellQuote(name === null ? entry : `${entry}/${name}`)} -maxdepth 3 -name package.json -print -quit 2>/dev/null | grep -q .; then echo installed; fi`;
+        const out = String((await run(`if [ -L ${shellQuote(entry)} ]; then echo symlink; fi; ${install}`))?.stdout ??
+            '');
+        return { symlink: out.includes('symlink'), installed: out.includes('installed') };
+    };
+}
+/**
+ * The refusal for a write whose target is inside an INSTALLED package, or null
+ * when the path is not under `node_modules` or nothing is installed there.
  *
  * `node_modules` is not the project's code: nothing written there survives the
  * next install, no deploy carries it, and a sandbox whose dependency tree is
@@ -312,6 +484,19 @@ export function moleculeDistReadNote(path) {
  * putting the file back. Reading these files stays allowed (that is how the
  * declarations above are read at all).
  *
+ * What is protected is the INSTALL, not the spelling: the decision comes from
+ * {@link InstalledPackageFacts}, never from the path alone (m106 above). Three
+ * things are the run's own to remove or replace —
+ *
+ * - a `node_modules` that is a SYMLINK: `rm`/`unlink` removes the link, never the
+ *   tree it points at, so a link the run made cannot clobber anything;
+ * - anything under the run's own `.mol-scratch/` directory;
+ * - a `node_modules` with no `package.json` under it (nothing was ever installed).
+ *
+ * A path INSIDE the link is still decided by what resolves there: a link into a
+ * real tree is refused, because removing or writing through it reaches the
+ * install.
+ *
  * The restore route is named because the model that has ALREADY clobbered a file
  * (this refusal is too late for it) is the one who needs it, and because the
  * obvious repair — `npm install <pkg>` — is itself refused in the pre-installed
@@ -319,19 +504,34 @@ export function moleculeDistReadNote(path) {
  * m91 used, and what both guards leave alone.
  *
  * @param path - An absolute path a tool is about to write.
+ * @param probe - Looks at the filesystem where the path lives.
  * @returns The one-line refusal naming the package, or null when nothing is installed there.
  */
-export function installedPackageWriteRefusal(path) {
-    // A path may sit in a NESTED node_modules (`app/node_modules/...`) as well as the
-    // hoisted root one: both are installed packages.
-    const at = /(?:^|\/)node_modules(?:\/|$)/.exec(path);
-    if (!at)
+export async function installedPackageWriteRefusal(path, probe) {
+    const parts = nodeModulesParts(path);
+    if (!parts)
         return null;
-    const named = /(?:^|\/)node_modules\/((?:@[^/]+\/)?[^/]+)(?:\/|$)/.exec(path);
-    const name = named?.[1] ?? null;
-    const scoped = at[0].startsWith('/') ? path.slice(0, at.index) : '';
-    const dir = name ? `${scoped}/node_modules/${name}` : null;
-    const what = name ? `the installed package ${name}` : 'an installed package';
+    const { entry, name } = parts;
+    // The run's own scratch directory is the run's to clean: the platform tells it
+    // to put throwaway work there (system prompt, "Throwaway probes go in
+    // `.mol-scratch/`"), so nothing in it is the pre-installed tree.
+    if (/(?:^|\/)\.mol-scratch(?:\/|$)/.test(path))
+        return null;
+    // No probe, or a probe that could not answer: keep the old, conservative
+    // reading (everything under node_modules is an install).
+    const facts = probe ? await probe(path).catch(() => null) : null;
+    const symlink = facts?.symlink ?? false;
+    const installed = facts?.installed ?? true;
+    // The entry itself — the link (or a tree with nothing in it) the run may take
+    // away. Removing a symlink deletes the LINK only; its target is untouched.
+    if (name === null && (symlink || !installed))
+        return null;
+    // A path under the entry: `installed` resolved through any link, so it is true
+    // exactly when a write here would land in a real installation.
+    if (name !== null && !installed)
+        return null;
+    const dir = name ? `${entry}/${name}` : null;
+    const what = name ? `the installed package ${name}` : 'an installed node_modules tree';
     const change = 'Installed packages are read-only: the next install replaces that file and a deploy never ' +
         'carries it. Change its behaviour from your app instead (its options, your own handler, a ' +
         'bond), and where the package itself is wrong, report it rather than patching it here. ' +
@@ -488,9 +688,11 @@ export function buildTools(backend, config) {
      * @param path - Relative or absolute path requested by the tool input.
      * @returns The normalized path, when writing it is allowed.
      */
-    function resolveWrite(path) {
+    async function resolveWrite(path) {
         const resolved = resolve(path);
-        const refusal = installedPackageWriteRefusal(resolved);
+        // The guard decides from what is installed where the path lives, so the
+        // backend is asked (one command, only for a path that names node_modules).
+        const refusal = await installedPackageWriteRefusal(resolved, shellInstalledPackageProbe((command) => backend.run(command, { timeout: 8000 })));
         if (refusal)
             throw new ToolInputError(refusal);
         return resolved;
@@ -1046,7 +1248,7 @@ export function buildTools(backend, config) {
             const argErr = pathArgError(input.path, 'write_file');
             if (argErr)
                 return { error: argErr };
-            const path = resolveWrite(input.path);
+            const path = await resolveWrite(input.path);
             const content = input.content;
             if (content.length > MAX_WRITE_SIZE)
                 return {
@@ -1095,7 +1297,7 @@ export function buildTools(backend, config) {
             const argErr = pathArgError(input.path, 'edit_file');
             if (argErr)
                 return { error: argErr };
-            const path = resolveWrite(input.path);
+            const path = await resolveWrite(input.path);
             // Support both formats: { replacements: [...] } (batch) and { old_string, new_string } (single, backwards-compatible)
             let replacements = input.replacements;
             // Accept the single format when BOTH are strings — `typeof` (not truthy) so
@@ -1729,7 +1931,7 @@ export function buildTools(backend, config) {
             }
         },
         async create_directory(input) {
-            const path = resolveWrite(input.path);
+            const path = await resolveWrite(input.path);
             const parentPath = path.substring(0, path.lastIndexOf('/')) || root;
             const symlinkErr = await checkSymlink(parentPath);
             if (symlinkErr)
@@ -1747,8 +1949,8 @@ export function buildTools(backend, config) {
         async rename_file(input) {
             // Both ends: moving a package's file OUT is as much a change to the installed
             // package as moving one in.
-            const oldPath = resolveWrite(input.old_path);
-            const newPath = resolveWrite(input.new_path);
+            const oldPath = await resolveWrite(input.old_path);
+            const newPath = await resolveWrite(input.new_path);
             const oldSymlinkErr = await checkSymlink(oldPath);
             if (oldSymlinkErr)
                 return { error: oldSymlinkErr };
@@ -1770,7 +1972,7 @@ export function buildTools(backend, config) {
             }
         },
         async delete_file(input) {
-            const path = resolveWrite(input.path);
+            const path = await resolveWrite(input.path);
             const symlinkErr = await checkSymlink(path);
             if (symlinkErr)
                 return { error: symlinkErr };
@@ -1820,7 +2022,28 @@ export function buildTools(backend, config) {
                 cwd,
                 readFile: (path) => backend.readFile(path),
             });
-            const command = traced.command;
+            let command = traced.command;
+            // A leading `sleep N; <read of a background task's log>` is a hand-rolled poll, and the
+            // platform knows the task's state better than the log's tail does (see
+            // {@link backgroundTaskState}): X1 xr-molecule-flash-m105 slept 225 s this way, two of the
+            // three on tasks that had already ended. The sleep is dropped and the rest of the command
+            // runs at once; with no background task behind it, the sleep is left exactly as sent — the
+            // tool's own budget is the existing bound.
+            const sleepPeek = leadingSleepPeek(command);
+            const peekedTask = sleepPeek
+                ? await backgroundTaskState(backend, command, sleepPeek.seconds, Math.max(5_000, (commandBudgetMs ?? 290_000) - 10_000))
+                : null;
+            const sleepNote = peekedTask?.note ?? null;
+            if (sleepPeek && peekedTask) {
+                command = sleepPeek.rest;
+                if (!command) {
+                    return {
+                        status: 'task_state',
+                        note: peekedTask.note,
+                        ...(peekedTask.slice.trim() ? { outputSoFar: sanitizeOutput(peekedTask.slice) } : {}),
+                    };
+                }
+            }
             // Detached: start it, hand back a handle, let the turn continue. A
             // command that outlives the tool's ceiling is otherwise simply lost —
             // measured across six agent runs, ten of them were killed at the
@@ -1937,18 +2160,22 @@ export function buildTools(backend, config) {
                                         ...(output.length > MAX_OUTPUT_SIZE
                                             ? { truncated: true, fullOutput: log }
                                             : {}),
-                                        error: `${cutRunSentence(cut)} ` +
+                                        error: (sleepNote ? `${sleepNote} ` : '') +
+                                            `${cutRunSentence(cut)} ` +
                                             (isSuiteRunCommand(command) ? SUITE_OVER_BUDGET_ADVICE : SPLIT_WORK_ADVICE),
                                     };
                                 }
                                 // The exit file holds the PIPELINE's code: when a stage this rewrite could not
                                 // prove is output-only still follows the suite runner (`| tee run.log`), that code
-                                // is the filter's — report none and let the log's tally decide (m101 +25:54).
-                                const piped = suiteRunPipedAfterRunner(streaming.command);
-                                const reported = suiteRunExitCode(code, output, piped);
+                                // is the filter's — report none and let the log's tally decide (m101 +25:54). The
+                                // note says this only when the parse found such a stage (m105 +08:12).
+                                const placement = suiteRunPipelinePlacement(streaming.command);
+                                const reported = suiteRunExitCode(code, output, placement.piped);
+                                const exitNote = suiteExitCodeNote(placement, reported);
                                 const notes = [
+                                    ...(sleepNote ? [sleepNote] : []),
                                     ...streaming.changes,
-                                    ...(reported === null ? [FILTERED_EXIT_NOTE] : []),
+                                    ...(exitNote === null ? [] : [exitNote]),
                                 ];
                                 return {
                                     stdout,
@@ -1965,22 +2192,25 @@ export function buildTools(backend, config) {
                         taskId: id,
                         log,
                         exitFile,
-                        note: (overCeiling
-                            ? declaredSeconds > ceilingSeconds
-                                ? `This command asks for ${declaredSeconds}s, more than this tool's ${ceilingSeconds}s, and its ` +
-                                    'output only appears when it ends — so it was started in the background instead. '
-                                : `A Playwright run can take longer than this tool's ${ceilingSeconds}s, and behind a pipe its ` +
-                                    'output only appears when it ends — so it was started in the background instead. '
-                            : '') +
+                        ...(peekedTask?.slice.trim() ? { outputSoFar: sanitizeOutput(peekedTask.slice) } : {}),
+                        note: (sleepNote ? `${sleepNote} ` : '') +
+                            (overCeiling
+                                ? declaredSeconds > ceilingSeconds
+                                    ? `This command asks for ${declaredSeconds}s, more than this tool's ${ceilingSeconds}s, and its ` +
+                                        'output only appears when it ends — so it was started in the background instead. '
+                                    : `A Playwright run can take longer than this tool's ${ceilingSeconds}s, and behind a pipe its ` +
+                                        'output only appears when it ends — so it was started in the background instead. '
+                                : '') +
                             `Started in the background. Its output is written to ${log} and comes back as the ` +
-                            `stdout of wait_for_task when the command finishes (read_file cannot reach /tmp — ` +
-                            `to peek mid-run, exec_command: tail ${log}). If you have other work, do it and ` +
-                            `check back. If you need this result before you can continue, call wait_for_task ` +
-                            `with this taskId — never sleep and read the log by hand.` +
+                            `stdout of wait_for_task when the command finishes (read_file cannot reach /tmp). If ` +
+                            `you have other work, do it and check back. If you need this result before you can ` +
+                            `continue, call wait_for_task with this taskId: it returns the moment the command ` +
+                            `ends, returns early when a failure cause repeats, and reports progress and the ` +
+                            `failures so far — never sleep and read the log by hand.` +
                             (streaming.changes.length ? ` ${streaming.changes.join(' ')}` : '') +
                             (prioritized.note ? ` ${prioritized.note}` : '') +
                             (ownFile
-                                ? ` This command writes its own output to ${ownFile}, so the task log stays empty: peek with exec_command: tail ${ownFile}.`
+                                ? ` This command writes its own output to ${ownFile}, so the task log stays empty: wait_for_task reads that file when the command ends and reports its progress while it runs — never sleep and tail it by hand.`
                                 : ''),
                     };
                 }
@@ -2063,7 +2293,8 @@ export function buildTools(backend, config) {
                         // The facts, so a reader that can also see the suite itself (its own `.hurl` file
                         // count) says the same sentence with the total the output alone cannot give.
                         cutRun: cut,
-                        error: `${cutLead} ` +
+                        error: (sleepNote ? `${sleepNote} ` : '') +
+                            `${cutLead} ` +
                             // The tool's own budget stopping a run that printed nothing: keep the sentence that
                             // says why the output is empty, since nothing else in the result can say it.
                             (cut.stoppedBy === 'tool-budget'
@@ -2078,8 +2309,11 @@ export function buildTools(backend, config) {
                     stdout,
                     stderr,
                     exitCode: result.exitCode,
-                    ...(ceilingNote || traced.change
-                        ? { note: [ceilingNote, traced.change].filter(Boolean).join(' ') }
+                    ...(peekedTask?.slice.trim() ? { outputSoFar: sanitizeOutput(peekedTask.slice) } : {}),
+                    ...(sleepNote || ceilingNote || traced.change
+                        ? {
+                            note: [sleepNote, ceilingNote, traced.change].filter(Boolean).join(' '),
+                        }
                         : {}),
                 };
             }
@@ -2383,8 +2617,8 @@ export function buildTools(backend, config) {
                         status: 'running',
                         waitedMs,
                         ...sliceField,
-                        note: `${progress} Call wait_for_task again to keep waiting; peek with exec_command: ` +
-                            `tail ${log}.${midRun}`,
+                        note: `${progress} Call wait_for_task again to keep waiting — it returns the moment the ` +
+                            `command ends and reports the failures as they appear.${midRun}`,
                     };
                 }
                 if (waitedBefore + waitedMs >= stuckAfterMs()) {
@@ -2484,10 +2718,13 @@ export function buildTools(backend, config) {
             // Same shaping as a foreground exec result, so the executor reads both
             // the same way. The exit file holds the PIPELINE's code: when a stage this rewrite could not
             // prove is output-only still follows the suite runner (`| tee run.log`), that code is the
-            // filter's — report none and let the log's tally decide (m101 +25:54).
-            const piped = run ? suiteRunPipedAfterRunner(run.command) : false;
-            const reported = suiteRunExitCode(exitCode, output, piped);
-            const noCodeNote = reported === null ? FILTERED_EXIT_NOTE : null;
+            // filter's — report none and let the log's tally decide (m101 +25:54). The note says this
+            // only when the parse found such a stage (m105 +08:12).
+            const placement = run
+                ? suiteRunPipelinePlacement(run.command)
+                : { piped: false, unplaced: false };
+            const reported = suiteRunExitCode(exitCode, output, placement.piped);
+            const noCodeNote = suiteExitCodeNote(placement, reported);
             return {
                 taskId,
                 exitCode: reported,

package/dist/trace-artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace-artifacts.d.ts","sourceRoot":"","sources":["../src/trace-artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAA;IACZ,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAA;CACf;AAED,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,0FAA0F;IAC1F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAA;IACZ,6FAA6F;IAC7F,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAErC,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,uDAAuD;AACvD,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAErC,iDAAiD;AACjD,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,gEAAgE;AAChE,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB,QAAO,MA+LvC,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAyBnE;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA4B/F;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,8BAA8B,CAAA;AAuG/D,oGAAoG;AACpG,MAAM,WAAW,qBAAqB;IACpC,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,4EAA4E;IAC5E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5C,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAyBjC"}
+{"version":3,"file":"trace-artifacts.d.ts","sourceRoot":"","sources":["../src/trace-artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,iGAAiG;IACjG,IAAI,EAAE,MAAM,CAAA;IACZ,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAA;CACf;AAED,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,0FAA0F;IAC1F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAA;IACZ,6FAA6F;IAC7F,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAErC,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAEpC,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,uDAAuD;AACvD,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAErC,iDAAiD;AACjD,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC,gEAAgE;AAChE,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB,QAAO,MA+LvC,CAAA;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAyBnE;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA4B/F;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,8BAA8B,CAAA;AA2G/D,oGAAoG;AACpG,MAAM,WAAW,qBAAqB;IACpC,0BAA0B;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,4EAA4E;IAC5E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5C,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAyBjC"}