@molecule/api-ai-tools 1.0.9 → 1.2.0

package/dist/tools.js

@@ -6,8 +6,16 @@
  *
  * @module
  */
+import { guardToolExecute, missingParamError } from './input-normalizer.js';
 import { TOOL_SCHEMAS } from './schemas.js';
-import { checkBlockedCommand, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, isEnvFilePath, isValidGlob, MAX_FIND_RESULTS, MAX_OUTPUT_SIZE, MAX_READ_SIZE, MAX_SEARCH_RESULTS, MAX_WRITE_SIZE, pathArgError, redactSecrets, redactSecretsInCode, resolvePath, shellQuote, stripControlChars, truncateMiddle, whitespaceTolerantReplace, } from './utilities.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.
+ */
+const stuckAfterMs = () => Number(process.env.MOL_AI_BG_STUCK_AFTER_MS) || 5 * 60 * 1000;
+/** Cumulative wait_for_task time per task id, this process. */
+const waitedByTask = new Map();
+import { checkBlockedCommand, declaredBudgetSeconds, DEFAULT_SEARCH_EXCLUDED_DIRS, directoryReadHint, isEnvFilePath, 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, parseCheckCommand, parseCheckProblem, pathArgError, redactSecrets, redactSecretsInCode, resolvePath, shellQuote, sliceLines, stripControlChars, truncateMiddle, whitespaceTolerantReplace, } from './utilities.js';
 /**
  * Build a complete set of AI agent tools bound to an execution backend.
  *
@@ -43,6 +51,29 @@ export function buildTools(backend, config) {
     const grepExcludeArgs = excludedDirs.map((d) => `--exclude-dir=${shellQuote(d)}`).join(' ');
     const findExcludeArgs = excludedDirs.map((d) => `-not -path ${shellQuote(`*/${d}/*`)}`).join(' ');
     // ── Path helpers ───────────────────────────────────────────────
+    /**
+     * After a write or edit, parse the file and hand the error back IN THE SAME
+     * RESULT. An edit that leaves a file unparsable used to surface only at the
+     * next build or type-check, minutes and many calls later — x13 (2026-09-22)
+     * mangled a template literal in `scripts/prerender.mjs`, the site stopped
+     * building, and the fix round spent 500 calls on the fallout. `node --check`
+     * is ~50 ms; the executor sees the exact line while the edit is still in
+     * front of it.
+     */
+    async function syntaxErrorAfterWrite(path) {
+        const command = parseCheckCommand(path);
+        if (!command)
+            return {};
+        const result = await backend
+            .run(command, { cwd: path.slice(0, path.lastIndexOf('/')) || '/', timeout: 15_000 })
+            .catch(() => null);
+        const problem = result ? parseCheckProblem(result) : null;
+        return problem
+            ? {
+                syntaxError: `The file no longer parses after this change — fix it before anything else, every build and test fails until it does:\n${problem}`,
+            }
+            : {};
+    }
     /**
      * Resolve a workspace-relative path using optional path guards.
      *
@@ -221,6 +252,155 @@ export function buildTools(backend, config) {
         };
     }
     // ── Tool implementations ───────────────────────────────────────
+    /**
+     * Read ONE file with every DWIM behavior read_file offers (directory
+     * listing, ENOENT parent listing, empty-read classification). Shared by the
+     * single-path and batched forms of the tool.
+     *
+     * @param rawPath - The path as the model sent it.
+     * @returns The same result shape read_file returns for one file.
+     */
+    /**
+     * How many leading lines of a file fit in a char budget.
+     *
+     * @param content - The file text.
+     * @param chars - The budget in chars.
+     * @returns The line count, at least one.
+     */
+    function linesWithin(content, chars) {
+        let used = 0;
+        let lines = 0;
+        for (const line of content.split('\n')) {
+            used += line.length + 1;
+            if (used > chars && lines > 0)
+                break;
+            lines++;
+        }
+        return Math.max(1, lines);
+    }
+    /**
+     * Read one file for the model: symlink-checked, size-bounded, optionally
+     * windowed by line, and never more than MAX_READ_RETURN_CHARS at once.
+     *
+     * @param rawPath - The path as the model sent it.
+     * @param window - Optional `offset`/`limit` in lines.
+     * @returns The file content (or a window of it) or a model-readable error.
+     */
+    async function readOneFile(rawPath, window) {
+        const argErr = pathArgError(rawPath, 'read_file');
+        if (argErr)
+            return { error: argErr };
+        const path = resolve(rawPath);
+        const symlinkErr = await checkSymlink(path);
+        if (symlinkErr)
+            return { error: symlinkErr };
+        try {
+            const content = await backend.readFile(path);
+            // A read that produced no usable text is verified against the file's real
+            // size before it can be reported as content (see classifyEmptyRead). The
+            // non-string arm covers a backend whose transport handed back an empty
+            // body as `undefined`; `content.length` below would otherwise raise an
+            // unactionable "Cannot read properties of undefined".
+            if (typeof content !== 'string' || content === '') {
+                const verdict = await classifyEmptyRead(path, 'read_file');
+                if ('error' in verdict)
+                    return verdict;
+                return {
+                    path,
+                    content: sanitizeFileContent(verdict.content, path),
+                    ...(verdict.content === '' ? { empty: true } : {}),
+                    ...(verdict.note ? { note: verdict.note } : {}),
+                };
+            }
+            if (content.length > MAX_READ_SIZE)
+                return {
+                    error: `File too large (${Math.round(content.length / 1024)}KB). Maximum is ${MAX_READ_SIZE / 1024 / 1024}MB.`,
+                };
+            // No window asked for and the file is bigger than one call should hand
+            // back: return its first window, sized to the ceiling, and say so. The
+            // model can read on with offset/limit; it cannot un-send 300k tokens.
+            const effectiveWindow = !sliceLines(content, window) && content.length > MAX_READ_RETURN_CHARS
+                ? { offset: 1, limit: linesWithin(content, MAX_READ_RETURN_CHARS) }
+                : window;
+            const windowed = sliceLines(content, effectiveWindow);
+            if (windowed) {
+                return {
+                    path,
+                    content: sanitizeFileContent(windowed.text, path),
+                    offset: windowed.offset,
+                    lines: windowed.lines,
+                    totalLines: windowed.totalLines,
+                    // The note decides the executor's next call. Observed (X0 run x7): a
+                    // 44 KB README read as seven 300-line windows, one round trip each,
+                    // because the note only ever said "read another window" — when the
+                    // whole file fits in one call, say that; when it does not, name the
+                    // 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}.`,
+                        }
+                        : {}),
+                };
+            }
+            return { path, content: sanitizeFileContent(content, path) };
+        }
+        catch (e) {
+            // Backends (e.g. the docker provider's `cat`) already prefix "Failed to read <path>: ";
+            // strip it so the wrap below doesn't stutter ("Failed to read X: Failed to read X: …").
+            const rawMessage = e.message;
+            const prefix = `Failed to read ${path}: `;
+            const message = rawMessage.startsWith(prefix) ? rawMessage.slice(prefix.length) : rawMessage;
+            // A weak model often read_file's a directory (handlers/, migrations/). Rather than
+            // erroring and costing it a retry loop (observed: 3 such misses + follow-up
+            // list_files in one custom build), DWIM: return the directory's listing — what it
+            // almost certainly wanted — with a note so it read_file's a specific entry next.
+            if (directoryReadHint(message, path)) {
+                try {
+                    const entries = await backend.readDir(path);
+                    return {
+                        path,
+                        isDirectory: true,
+                        note: `${path} is a directory, not a file — returning its contents. read_file a specific entry inside it to see that file's content.`,
+                        entries: entries.map((entry) => ({ name: entry.name, type: entry.type })),
+                    };
+                }
+                catch (_dirErr) {
+                    // readDir also failed — fall through to the steer-to-list_files hint below.
+                }
+            }
+            // ENOENT DWIM: a weak model GUESSES paths from framework priors (observed: 65 of 89
+            // reads in one imported-app build were misses on files that never existed). Return
+            // ground truth in the SAME result — what the parent directory actually contains — so
+            // the next read uses a real name instead of another guess.
+            if (/No such file or directory/i.test(message)) {
+                const parent = path.replace(/\/[^/]*$/, '') || '/';
+                let listing;
+                try {
+                    const entries = await backend.readDir(parent);
+                    const names = entries
+                        .slice(0, 40)
+                        .map((entry) => entry.name + (entry.type === 'directory' ? '/' : ''));
+                    listing = names.length
+                        ? `The directory ${parent} exists and contains: ${names.join(', ')}${entries.length > 40 ? ', …' : ''}.`
+                        : `The directory ${parent} exists but is EMPTY.`;
+                }
+                catch (_parentErr) {
+                    // Parent listing failed too — most usefully because it doesn't exist either.
+                    listing = `The directory ${parent} does not exist either.`;
+                }
+                return {
+                    error: `No such file: ${path}. ${listing} Read one of the real entries (or use find_files) — do not guess paths.`,
+                };
+            }
+            return { error: directoryReadHint(message, path) ?? `Failed to read ${path}: ${message}` };
+        }
+    }
     const toolImpls = {
         async list_files(input) {
             const path = resolve(input.path || '');
@@ -236,87 +416,46 @@ export function buildTools(backend, config) {
             }
         },
         async read_file(input) {
-            const argErr = pathArgError(input.path, 'read_file');
-            if (argErr)
-                return { error: argErr };
-            const path = resolve(input.path);
-            const symlinkErr = await checkSymlink(path);
-            if (symlinkErr)
-                return { error: symlinkErr };
-            try {
-                const content = await backend.readFile(path);
-                // A read that produced no usable text is verified against the file's real
-                // size before it can be reported as content (see classifyEmptyRead). The
-                // non-string arm covers a backend whose transport handed back an empty
-                // body as `undefined`; `content.length` below would otherwise raise an
-                // unactionable "Cannot read properties of undefined".
-                if (typeof content !== 'string' || content === '') {
-                    const verdict = await classifyEmptyRead(path, 'read_file');
-                    if ('error' in verdict)
-                        return verdict;
+            // Several paths in ONE call. The executor issues one tool call per model
+            // round-trip 89% of the time (X0: 464 assistant messages, 515 tool calls,
+            // a ~10s mean gap), so a turn's wall clock IS its round-trip count — and
+            // the largest single block measured was a systematic scaffold survey:
+            // 121 sequential read_file calls, 108 of them in the first ten minutes,
+            // across 93 distinct files. The same reads batched cost the same tokens
+            // and a tenth of the latency.
+            if (Array.isArray(input.paths)) {
+                const requested = input.paths.map((p) => String(p ?? '')).filter(Boolean);
+                if (requested.length === 0) {
                     return {
-                        path,
-                        content: sanitizeFileContent(verdict.content, path),
-                        ...(verdict.content === '' ? { empty: true } : {}),
-                        ...(verdict.note ? { note: verdict.note } : {}),
+                        error: 'read_file got an empty "paths" array. Pass "path" for one file, or "paths" with at ' +
+                            'least one path for several.',
                     };
                 }
-                if (content.length > MAX_READ_SIZE)
-                    return {
-                        error: `File too large (${Math.round(content.length / 1024)}KB). Maximum is ${MAX_READ_SIZE / 1024 / 1024}MB.`,
-                    };
-                return { path, content: sanitizeFileContent(content, path) };
-            }
-            catch (e) {
-                // Backends (e.g. the docker provider's `cat`) already prefix "Failed to read <path>: ";
-                // strip it so the wrap below doesn't stutter ("Failed to read X: Failed to read X: …").
-                const rawMessage = e.message;
-                const prefix = `Failed to read ${path}: `;
-                const message = rawMessage.startsWith(prefix) ? rawMessage.slice(prefix.length) : rawMessage;
-                // A weak model often read_file's a directory (handlers/, migrations/). Rather than
-                // erroring and costing it a retry loop (observed: 3 such misses + follow-up
-                // list_files in one custom build), DWIM: return the directory's listing — what it
-                // almost certainly wanted — with a note so it read_file's a specific entry next.
-                if (directoryReadHint(message, path)) {
-                    try {
-                        const entries = await backend.readDir(path);
-                        return {
-                            path,
-                            isDirectory: true,
-                            note: `${path} is a directory, not a file — returning its contents. read_file a specific entry inside it to see that file's content.`,
-                            entries: entries.map((entry) => ({ name: entry.name, type: entry.type })),
-                        };
+                const files = [];
+                let budget = MAX_BATCH_READ_BYTES;
+                let stoppedAt = null;
+                for (const [index, requestedPath] of requested.entries()) {
+                    if (index >= MAX_BATCH_READ_FILES || budget <= 0) {
+                        stoppedAt = requestedPath;
+                        break;
                     }
-                    catch (_dirErr) {
-                        // readDir also failed — fall through to the steer-to-list_files hint below.
-                    }
-                }
-                // ENOENT DWIM: a weak model GUESSES paths from framework priors (observed: 65 of 89
-                // reads in one imported-app build were misses on files that never existed). Return
-                // ground truth in the SAME result — what the parent directory actually contains — so
-                // the next read uses a real name instead of another guess.
-                if (/No such file or directory/i.test(message)) {
-                    const parent = path.replace(/\/[^/]*$/, '') || '/';
-                    let listing;
-                    try {
-                        const entries = await backend.readDir(parent);
-                        const names = entries
-                            .slice(0, 40)
-                            .map((entry) => entry.name + (entry.type === 'directory' ? '/' : ''));
-                        listing = names.length
-                            ? `The directory ${parent} exists and contains: ${names.join(', ')}${entries.length > 40 ? ', …' : ''}.`
-                            : `The directory ${parent} exists but is EMPTY.`;
-                    }
-                    catch (_parentErr) {
-                        // Parent listing failed too — most usefully because it doesn't exist either.
-                        listing = `The directory ${parent} does not exist either.`;
-                    }
-                    return {
-                        error: `No such file: ${path}. ${listing} Read one of the real entries (or use find_files) — do not guess paths.`,
-                    };
+                    const one = (await readOneFile(requestedPath, input));
+                    files.push(one);
+                    if (typeof one.content === 'string')
+                        budget -= one.content.length;
                 }
-                return { error: directoryReadHint(message, path) ?? `Failed to read ${path}: ${message}` };
+                return {
+                    files,
+                    ...(stoppedAt
+                        ? {
+                            note: `Stopped after ${files.length} of ${requested.length} files (limit: ${MAX_BATCH_READ_FILES} ` +
+                                `files or ${Math.round(MAX_BATCH_READ_BYTES / 1024)}KB per call). Call read_file again ` +
+                                `starting at ${stoppedAt}.`,
+                        }
+                        : {}),
+                };
             }
+            return readOneFile(input.path, input);
         },
         async write_file(input) {
             const argErr = pathArgError(input.path, 'write_file');
@@ -348,7 +487,7 @@ export function buildTools(backend, config) {
                 const diff = computeDiff(oldContent, finalContent);
                 if (onFileChange)
                     onFileChange({ type: oldContent === null ? 'created' : 'modified', path });
-                return { path, ok: true, diff };
+                return { path, ok: true, diff, ...(await syntaxErrorAfterWrite(path)) };
             }
             catch (e) {
                 return { error: `Failed to write ${path}: ${e.message}` };
@@ -473,8 +612,27 @@ export function buildTools(backend, config) {
                             if (idx >= 0)
                                 return showSnippet(idx);
                         }
+                        // Nothing anchored. Say WHICH of the two situations this is — they
+                        // call for different next moves, and the old message implied the
+                        // first while being returned for both. Measured across six agent
+                        // runs, `old_string not found` was the largest remaining tool-error
+                        // class (15 of 64) and every one of these fell through to a bare
+                        // "re-read and copy the exact text", which is wrong advice when the
+                        // text is not in the file at all.
+                        const anchorsPresent = distinctiveLines.some((anchor) => fileLines.some((l) => l.includes(anchor)));
+                        if (!anchorsPresent) {
+                            return {
+                                error: `old_string not found in ${path} — and NONE of its lines appear anywhere in ` +
+                                    `that file, so this is not a whitespace problem. Either the edit was already ` +
+                                    `applied, or this is the wrong file. read_file it and look before trying ` +
+                                    `again; do not retry the same old_string.`,
+                            };
+                        }
                         return {
-                            error: `old_string not found in ${path}. Re-read the file with read_file and copy the exact current text — do not construct old_string from memory or the plan.`,
+                            error: `old_string not found in ${path}. Parts of it ARE in the file but no single ` +
+                                `line is distinctive enough to locate the target. read_file the region you ` +
+                                `mean and copy old_string verbatim from what it returns — including ` +
+                                `indentation — or include more surrounding context to make it unique.`,
                         };
                     }
                     if (count > 1)
@@ -497,7 +655,12 @@ export function buildTools(backend, config) {
                     await onAfterWrite(path).catch(() => { });
                 if (onFileChange)
                     onFileChange({ type: 'modified', path });
-                return { path, ok: true, replacementsApplied: replacements.length };
+                return {
+                    path,
+                    ok: true,
+                    replacementsApplied: replacements.length,
+                    ...(await syntaxErrorAfterWrite(path)),
+                };
             }
             catch (e) {
                 return { error: `Failed to edit ${path}: ${e.message}` };
@@ -507,16 +670,27 @@ export function buildTools(backend, config) {
             const pattern = input.pattern;
             const path = resolve(input.path || '');
             const include = input.include;
+            // Lines of surrounding context per match. The executor reaches for
+            // `grep -A 20` through the shell because this tool could not express it;
+            // bounded so a broad pattern cannot pull the whole tree into the reply.
+            const rawContext = Number(input.contextLines ?? input.context);
+            const contextLines = Number.isFinite(rawContext)
+                ? Math.min(Math.max(Math.trunc(rawContext), 0), MAX_SEARCH_CONTEXT_LINES)
+                : 0;
             if (include && !isValidGlob(include))
                 return {
-                    error: 'Invalid include glob pattern. Allowed: alphanumeric and * ? . _ - / [ ] ( ).',
+                    error: 'Invalid include glob pattern. Allowed: alphanumeric and @ * ? . _ - / [ ] ( ).',
                 };
             const symlinkErr = await checkSymlink(path);
             if (symlinkErr)
                 return { error: symlinkErr };
             try {
                 const globArg = include ? `--include=${shellQuote(include)}` : '';
-                const result = await backend.run(`grep -rn ${globArg} ${grepExcludeArgs} --max-count=${MAX_SEARCH_RESULTS} -- ${shellQuote(pattern)} ${shellQuote(path)} 2>/dev/null || true`, { timeout: 10000 });
+                // With context, grep emits `file-line-content` for context lines and
+                // `file:line:content` for matches, plus `--` group separators. Both
+                // shapes are parsed below; without context the output is unchanged.
+                const contextArg = contextLines > 0 ? `-C ${contextLines}` : '';
+                const result = await backend.run(`grep -rn ${globArg} ${contextArg} ${grepExcludeArgs} --max-count=${MAX_SEARCH_RESULTS} -- ${shellQuote(pattern)} ${shellQuote(path)} 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
                 // the line-anchored env pattern, and knowing each match's own path is what
@@ -524,14 +698,31 @@ export function buildTools(backend, config) {
                 const output = stripControlChars(result.stdout.trim());
                 if (!output)
                     return { pattern, path, matches: [] };
+                const cap = contextLines > 0 ? MAX_SEARCH_RESULTS * (contextLines * 2 + 2) : MAX_SEARCH_RESULTS;
                 const matches = output
                     .split('\n')
-                    .slice(0, MAX_SEARCH_RESULTS)
+                    .slice(0, cap)
+                    .filter((line) => line !== '--')
                     .map((line) => {
-                    const m = line.match(/^(.+?):(\d+):(.*)$/);
-                    return m
-                        ? { file: m[1], line: parseInt(m[2]), content: sanitizeFileContent(m[3], m[1]) }
-                        : { file: '', line: 0, content: sanitizeFileContent(line, '') };
+                    const hit = line.match(/^(.+?):(\d+):(.*)$/);
+                    if (hit) {
+                        return {
+                            file: hit[1],
+                            line: parseInt(hit[2]),
+                            content: sanitizeFileContent(hit[3], hit[1]),
+                            ...(contextLines > 0 ? { match: true } : {}),
+                        };
+                    }
+                    const ctx = contextLines > 0 ? line.match(/^(.+?)-(\d+)-(.*)$/) : null;
+                    if (ctx) {
+                        return {
+                            file: ctx[1],
+                            line: parseInt(ctx[2]),
+                            content: sanitizeFileContent(ctx[3], ctx[1]),
+                            match: false,
+                        };
+                    }
+                    return { file: '', line: 0, content: sanitizeFileContent(line, '') };
                 });
                 return { pattern, path, matches };
             }
@@ -551,7 +742,7 @@ export function buildTools(backend, config) {
                 };
             if (!isValidGlob(pattern))
                 return {
-                    error: 'Invalid pattern. Allowed: alphanumeric and * ? . _ - / [ ] ( ) ' +
+                    error: 'Invalid pattern. Allowed: alphanumeric and @ * ? . _ - / [ ] ( ) ' +
                         '(brackets/parens support Next.js route dirs like [id] or (group)).',
                 };
             const symlinkErr = await checkSymlink(path);
@@ -623,6 +814,17 @@ export function buildTools(backend, config) {
         async exec_command(input) {
             const command = input.command;
             const cwd = input.cwd ? resolve(input.cwd) : root;
+            // A model that sent the command under another name (`cmd`, `script`, …)
+            // has already been normalized by guardToolExecute; reaching here with
+            // nothing means there is genuinely no command. Say so in the terms that
+            // let the model fix it. It used to fall through to
+            // checkBlockedCommand(undefined) and die with "Cannot read properties of
+            // undefined (reading 'match')" — the executor read that as a broken shell,
+            // stopped verifying, and ended the turn claiming all checks passed while
+            // seven acceptance checks failed (X0 rehearsal 83, 2026-09-16).
+            if (typeof command !== 'string' || command.trim() === '') {
+                return { error: missingParamError(TOOL_SCHEMAS.exec_command, input, ['command']) };
+            }
             if (blockDangerousCommands) {
                 const blocked = checkBlockedCommand(command);
                 if (blocked)
@@ -635,6 +837,70 @@ export function buildTools(backend, config) {
                 if (blocked)
                     return { error: blocked };
             }
+            // 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
+            // ceiling for 49 minutes, 11% of all wall clock, every one returning
+            // nothing because it was piped through tail/grep. A full test suite or a
+            // slow production build could not be run at all, so the executor ran
+            // smaller and smaller pieces, or reported a result it never saw.
+            //
+            // Output goes to a file the executor reads with read_file (which takes
+            // offset/limit, so a long log is cheap to follow), and an `.exit` file
+            // appears when it finishes — so "is it done?" is a read, not a poll that
+            // blocks a turn.
+            if (input.run_in_background === true) {
+                const id = `mol-bg-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+                const log = `/tmp/${id}.log`;
+                const exitFile = `/tmp/${id}.exit`;
+                const script = `/tmp/${id}.sh`;
+                try {
+                    // The command goes to a FILE rather than through nested quoting:
+                    // an executor's commands routinely carry quotes, heredocs and
+                    // newlines, and re-quoting them into a detached `sh -c` is how a
+                    // background runner corrupts the very thing it is running.
+                    await backend.writeFile(script, `${command}\n`);
+                    await backend.run(`nohup sh -c ${shellQuote(`sh ${script} > ${log} 2>&1; echo $? > ${exitFile}`)} ` +
+                        `> /dev/null 2>&1 & echo $! > /tmp/${id}.pid`, { cwd, timeout: 15_000 });
+                    return {
+                        taskId: id,
+                        log,
+                        exitFile,
+                        note: `Started in the background. Its output is being written to ${log} — read it with ` +
+                            `read_file (use offset/limit to follow a long one). When it finishes, ${exitFile} ` +
+                            `appears and holds the exit code. 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.`,
+                    };
+                }
+                catch (e) {
+                    return {
+                        error: `Could not start the background command: ${e.message}`,
+                    };
+                }
+            }
+            // A command that declares its OWN budget larger than this tool's ceiling,
+            // and whose output is withheld until the pipeline ends, cannot produce
+            // anything: it will be stopped at the ceiling having printed nothing.
+            // Measured across six agent runs, that combination was ten commands and
+            // 49 minutes — 11% of all wall clock — each returning a few hundred bytes.
+            // Refusing in five seconds, naming both ways out, is strictly better than
+            // spending the ceiling to say the same thing afterwards. A command that
+            // declares nothing still RUNS: partial output survives an overrun, so
+            // there is something to learn either way.
+            if (commandBudgetMs) {
+                const ceiling = Math.max(1, Math.round(commandBudgetMs / 1000));
+                const declared = declaredBudgetSeconds(command, input.timeout);
+                if (declared > ceiling && outputIsWithheldUntilExit(command)) {
+                    return {
+                        error: `This command asks for ${declared}s and this tool stops at ${ceiling}s — and its output ` +
+                            'is piped into tail/head/grep, which print nothing until the pipeline ends, so it ' +
+                            'would spend the whole budget and hand you back nothing. Either run a smaller unit ' +
+                            '(one spec file, one build step) that finishes inside the limit, or drop the pipe ' +
+                            'and use a streaming reporter so the output survives being stopped. Nothing was run.',
+                    };
+                }
+            }
             try {
                 // exec_command runs installs/builds/tests — the old 30s hardcap killed
                 // those spuriously; use the (generous, caller-configurable) budget.
@@ -644,10 +910,26 @@ export function buildTools(backend, config) {
                 // printed until then comes back with exit code 124 — instead of an outer
                 // timeout discarding the run and its output together.
                 const budgetSeconds = commandBudgetMs ? Math.max(1, Math.round(commandBudgetMs / 1000)) : 0;
+                // A requested budget is honored DOWNWARD only. The model used to send
+                // `timeout: 900000` for a test suite, the field was not declared so it
+                // was silently dropped, and the command was killed at the ceiling with
+                // no hint that a ceiling existed — costing a full budget per attempt
+                // before the overrun message could teach anything (X0 R83/R84). Now the
+                // ceiling is reported the FIRST time a larger one is asked for.
+                const requestedMs = Number(input.timeout);
+                const wantsMore = Number.isFinite(requestedMs) && requestedMs > 0 && requestedMs > (commandBudgetMs ?? 0);
+                const effectiveBudgetMs = Number.isFinite(requestedMs) && requestedMs > 0 && commandBudgetMs
+                    ? Math.min(requestedMs, commandBudgetMs)
+                    : commandBudgetMs;
+                const ceilingNote = wantsMore && budgetSeconds
+                    ? `You asked for ${Math.round(requestedMs / 1000)}s; this tool's ceiling is ${budgetSeconds}s. ` +
+                        'Split the work into smaller commands (one test file, one build step) rather than ' +
+                        're-running the same long one.'
+                    : null;
                 const result = await backend.run(command, {
                     cwd,
                     timeout: execTimeoutMs,
-                    ...(commandBudgetMs ? { budgetMs: commandBudgetMs } : {}),
+                    ...(effectiveBudgetMs ? { budgetMs: effectiveBudgetMs } : {}),
                 });
                 // truncateMiddle (not truncate): a failing build/test/migration puts its
                 // error at the TAIL, so keep the head AND the tail — head-only truncation
@@ -668,7 +950,12 @@ export function buildTools(backend, config) {
                             'a build and a whole suite.',
                     };
                 }
-                return { stdout, stderr, exitCode: result.exitCode };
+                return {
+                    stdout,
+                    stderr,
+                    exitCode: result.exitCode,
+                    ...(ceilingNote ? { note: ceilingNote } : {}),
+                };
             }
             catch (e) {
                 return { error: `Command failed: ${e.message}` };
@@ -720,6 +1007,103 @@ export function buildTools(backend, config) {
                 error: `Skill '${name}' not found. Searched .agents/skills/${name}/SKILL.md and .claude/skills/${name}/SKILL.md`,
             };
         },
+        // The other half of run_in_background. A handle is only useful if the
+        // executor has other work to do while the command runs; when it needs the
+        // result to continue — a build before the tests, tests before "done" — it
+        // has nothing to do but wait, and without this it waited by calling
+        // `sleep 75; cat <log>` in exec_command, one round trip per poll, each at
+        // the full context. Observed on X0 run x1 (2026-09-22): the first two
+        // background builds were each followed by a sleep-and-cat call. Waiting
+        // server-side costs no round trip and no context.
+        async wait_for_task(input) {
+            const taskId = typeof input.taskId === 'string' ? input.taskId.trim() : '';
+            // 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
+            // attached). Say so once, name the pid, and refuse to wait on it again.
+            const waitedBefore = waitedByTask.get(taskId) ?? 0;
+            if (taskId && waitedBefore >= stuckAfterMs()) {
+                return {
+                    taskId,
+                    status: 'stuck',
+                    waitedMs: waitedBefore,
+                    note: `You have already waited ${Math.round(waitedBefore / 1000)}s on this command and it ` +
+                        `has not exited — it is stuck, not slow. Kill it (exec_command: kill $(cat /tmp/${taskId}.pid) ` +
+                        `2>/dev/null; pkill -f ${taskId}.sh) and move on; do not wait on it again.`,
+                };
+            }
+            // The id names files under /tmp; only an id this tool minted may be used
+            // to read them, so a crafted id cannot turn this into a file reader.
+            if (!/^mol-bg-[a-z0-9]+-[a-z0-9]+$/.test(taskId)) {
+                return {
+                    error: 'taskId must be the id a run_in_background command returned (it looks like ' +
+                        '`mol-bg-…`).',
+                };
+            }
+            const log = `/tmp/${taskId}.log`;
+            const exitFile = `/tmp/${taskId}.exit`;
+            // Leave the outer tool ceiling a margin so this returns a result rather
+            // than being killed by it.
+            const ceiling = Math.max(5_000, (commandBudgetMs ?? 290_000) - 10_000);
+            const requested = Number(input.timeout);
+            const budgetMs = Number.isFinite(requested) && requested > 0 ? Math.min(requested, ceiling) : ceiling;
+            const startedAt = Date.now();
+            const readExit = async () => {
+                try {
+                    const raw = await backend.readFile(exitFile);
+                    const code = Number.parseInt(raw.trim(), 10);
+                    return Number.isFinite(code) ? code : 0;
+                }
+                catch (_error) {
+                    // No exit file yet — the command is still running. Not an error.
+                    return null;
+                }
+            };
+            let exitCode = await readExit();
+            while (exitCode === null && Date.now() - startedAt < budgetMs) {
+                await new Promise((r) => setTimeout(r, Math.min(2_000, budgetMs - (Date.now() - startedAt))));
+                exitCode = await readExit();
+            }
+            const waitedMs = Date.now() - startedAt;
+            waitedByTask.set(taskId, waitedBefore + waitedMs);
+            if (exitCode === null) {
+                if (waitedBefore + waitedMs >= stuckAfterMs()) {
+                    return {
+                        taskId,
+                        status: 'stuck',
+                        waitedMs: waitedBefore + waitedMs,
+                        note: `${Math.round((waitedBefore + waitedMs) / 1000)}s of waiting and it has not exited — it is ` +
+                            `stuck, not slow. Read /tmp/${taskId}.log for what it printed, kill it (exec_command: ` +
+                            `kill $(cat /tmp/${taskId}.pid) 2>/dev/null; pkill -f ${taskId}.sh) and move on; do not wait on it again.`,
+                    };
+                }
+                return {
+                    taskId,
+                    status: 'running',
+                    waitedMs,
+                    note: `Still running after ${Math.round(waitedMs / 1000)}s. Call wait_for_task again to ` +
+                        `keep waiting, or read ${log} for its output so far.`,
+                };
+            }
+            let output;
+            try {
+                output = await backend.readFile(log);
+            }
+            catch (_error) {
+                // The command finished but wrote nothing (or the log was removed);
+                // an empty output with a real exit code is still a result.
+                output = '';
+            }
+            // Same shaping as a foreground exec result, so the executor reads both
+            // the same way.
+            return {
+                taskId,
+                exitCode,
+                waitedMs,
+                stdout: sanitizeOutput(truncateMiddle(output, MAX_OUTPUT_SIZE)),
+                ...(output.length > MAX_OUTPUT_SIZE ? { truncated: true, fullOutput: log } : {}),
+            };
+        },
         async save_plan(input) {
             const name = input.name;
             // The schema field is `content`, but a weak executor frequently sends the plan under
@@ -794,7 +1178,13 @@ export function buildTools(backend, config) {
             name: schema.name,
             description: schema.description,
             parameters: schema.parameters,
-            execute: impl,
+            // Every tool goes through the same guard: parameter aliases are moved onto
+            // the declared names, a missing required one returns a model-actionable
+            // error instead of reaching a handler as `undefined`, and a handler that
+            // throws returns an error rather than a bare internal message. See
+            // input-normalizer.ts for why (X0 R83: `{ cmd }` instead of
+            // `{ command }` crashed exec_command and the executor stopped verifying).
+            execute: guardToolExecute(schema, impl),
         });
     }
     return allTools;