@sema-agent/core 1.279.0 → 1.280.0

package/dist/tools/fs/index.js

@@ -4,15 +4,21 @@ import { defineTool } from "../../core/tools.js";
 import { createTaskOutputTool, createTaskStopTool, defaultTaskRegistry } from "../../core/task-registry.js";
 import { hasBackgroundShell } from "../../core/background-shell.js";
 import { delimitUntrusted } from "../../core/untrusted-text.js";
-import { sha256, resolveKey, violationText, requireRead, checkStale, checkEditMatch, checkNoChange, hasBinaryExtension, isBinaryContent, fileArgPath, imageMimeForRead, imageMagicMatches, similarNameSuggestion, resolveQuoteMatch, adaptNewStringQuotes, deletionOldString, countOccurrences, } from "./safety.js";
+import { sha256, resolveKey, violationText, requireRead, checkStale, checkEditMatch, checkNoChange, hasBinaryExtension, isBinaryContent, fileArgPath, imageMimeForRead, imageMagicMatches, similarNameSuggestion, resolveQuoteMatch, adaptNewStringQuotes, deletionOldString, countOccurrences, OVERSIZE_READ_ESCAPE_HINT, } from "./safety.js";
 import { decodeTextBytes, encodeTextForFile, normalizeEditText } from "./encoding.js";
-import { runGrep, runGlobDetailed, splitAbsoluteGlobPattern } from "./search.js";
+import { runGrepDetailed, runGlobDetailed, splitAbsoluteGlobPattern } from "./search.js";
 import { makeRepoMapTool } from "./repo-map.js";
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { MCP_IMAGE_MAX_BASE64, IMAGE_TARGET_RAW_SIZE, sharpImageDownsampler } from "../../core/mcp.js";
 import { PDF_FALLBACK_RENDER_PAGES, PDF_INLINE_PAGE_THRESHOLD, PDF_MAX_EXTRACT_SIZE, PDF_MAX_PAGES_PER_READ, PDF_TARGET_RAW_SIZE, extractPdfPagesAsImages, extractPdfTextLayer, getPdfPageCount, parsePdfPageRange, pdfMagicMatches, } from "./pdf.js";
 export { pdfModelCapabilitiesOf } from "./pdf.js";
 const MAX_READ_BYTES = 256 * 1024;
+export const SLICED_READ_MAX_BYTES = 64 * 1024 * 1024;
+async function notReadRefusalText(env, toolName, key, v, signal) {
+    const base = `Error (${toolName}): ${v.message}`;
+    const info = await env.fileInfo(key, signal);
+    return info.ok && info.value.kind !== "directory" && info.value.size > MAX_READ_BYTES ? `${base} ${OVERSIZE_READ_ESCAPE_HINT}` : base;
+}
 const MAX_IMAGE_READ_BYTES = 5 * 1024 * 1024;
 const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES = 64 * 1024 * 1024;
 let autoDownsampler;
@@ -162,17 +168,20 @@ async function readPdfFile(env, path, key, pages, signal, downsamplerOpt, cwd, p
             const t = await extractPdfTextLayer(env, key, { first: range.first, last }, signal);
             if (t.ok) {
                 const { body, truncated } = boundPdfExtractedText(t.text);
+                const timeoutNote = t.timedOutAfterSec !== undefined
+                    ? `; PARTIAL — pdftotext timed out after ${t.timedOutAfterSec}s, so the text below covers only what was extracted before the timeout; use a narrower pages range for the rest`
+                    : "";
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""} extracted as text via pdftotext (the serving model does not support native PDF input)]` +
+                            text: `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""} extracted as text via pdftotext (the serving model does not support native PDF input)${timeoutNote}]` +
                                 `\n${delimitUntrusted("PDF text layer", body)}${truncated ? `\n[extracted text truncated at ${MAX_READ_BYTES} bytes; narrow the pages range]` : ""}`,
                         },
                     ],
                     details: {
                         type: "document",
-                        file: { type: "application/pdf", originalSize: size, ...(pageCount !== undefined ? { pageCount } : {}), pages: `${range.first}-${last}` },
+                        file: { type: "application/pdf", originalSize: size, ...(pageCount !== undefined ? { pageCount } : {}), pages: `${range.first}-${last}`, ...(t.timedOutAfterSec !== undefined ? { timedOut: true } : {}) },
                         fallback: { level: 1, reason: "model lacks document input; text layer extracted via pdftotext" },
                     },
                 };
@@ -204,18 +213,29 @@ async function readPdfFile(env, path, key, pages, signal, downsamplerOpt, cwd, p
         const blocks = await pdfPagesToImageBlocks(extract.pages, path, downsamplerOpt);
         if (typeof blocks === "string")
             return blocks;
+        const requestedPages = last - range.first + 1;
+        const renderedAll = extract.pages.length >= requestedPages;
+        const header = extract.timedOutAfterSec !== undefined
+            ? renderedAll
+                ? `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""}: pdftoppm timed out after ${extract.timedOutAfterSec}s, but all ${requestedPages} requested page${requestedPages === 1 ? "" : "s"} were rendered before the timeout hit at teardown (100 dpi); nothing is missing.]`
+                : `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""}: pdftoppm timed out after ${extract.timedOutAfterSec}s; rendered ${extract.pages.length} of ${requestedPages} requested page${requestedPages === 1 ? "" : "s"} before the timeout (100 dpi). Read the remaining pages with a narrower range (e.g. pages: "${range.first + extract.pages.length}-${last}").]`
+            : `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""} rendered as ${extract.pages.length} image${extract.pages.length === 1 ? "" : "s"} (100 dpi)]`;
         const content = [
-            {
-                type: "text",
-                text: `[PDF: ${path} — pages ${range.first}-${last}${pageCount !== undefined ? ` of ${pageCount}` : ""} rendered as ${extract.pages.length} image${extract.pages.length === 1 ? "" : "s"} (100 dpi)]`,
-            },
+            { type: "text", text: header },
             ...blocks,
         ];
         return {
             content,
             details: {
                 type: "document",
-                file: { type: "application/pdf", originalSize: size, ...(pageCount !== undefined ? { pageCount } : {}), pages: `${range.first}-${last}`, renderedPages: extract.pages.length },
+                file: {
+                    type: "application/pdf",
+                    originalSize: size,
+                    ...(pageCount !== undefined ? { pageCount } : {}),
+                    pages: `${range.first}-${last}`,
+                    renderedPages: extract.pages.length,
+                    ...(extract.timedOutAfterSec !== undefined ? { requestedPages, timedOut: true } : {}),
+                },
             },
         };
     }
@@ -231,15 +251,22 @@ async function readPdfFile(env, path, key, pages, signal, downsamplerOpt, cwd, p
         const t = await extractPdfTextLayer(env, key, undefined, signal);
         if (t.ok) {
             const { body, truncated } = boundPdfExtractedText(t.text);
+            const timeoutNote = t.timedOutAfterSec !== undefined
+                ? `; PARTIAL — pdftotext timed out after ${t.timedOutAfterSec}s, so the text below covers only what was extracted before the timeout; use the pages parameter for the rest`
+                : "";
             return {
                 content: [
                     {
                         type: "text",
-                        text: `[PDF: ${path} — extracted text layer via pdftotext${pageCount !== undefined ? `; ${pageCount} page${pageCount === 1 ? "" : "s"}` : ""} (the serving model does not support native PDF input)]` +
+                        text: `[PDF: ${path} — extracted text layer via pdftotext${pageCount !== undefined ? `; ${pageCount} page${pageCount === 1 ? "" : "s"}` : ""} (the serving model does not support native PDF input)${timeoutNote}]` +
                             `\n${delimitUntrusted("PDF text layer", body)}${truncated ? `\n[extracted text truncated at ${MAX_READ_BYTES} bytes; use the pages parameter to read specific ranges]` : ""}`,
                     },
                 ],
-                details: { type: "document", file: fileCard, fallback: { level: 1, reason: "model lacks document input; text layer extracted via pdftotext" } },
+                details: {
+                    type: "document",
+                    file: { ...fileCard, ...(t.timedOutAfterSec !== undefined ? { timedOut: true } : {}) },
+                    fallback: { level: 1, reason: "model lacks document input; text layer extracted via pdftotext" },
+                },
             };
         }
         const textWhy = t.toolMissing ? "`pdftotext` is not available in this environment" : `pdftotext failed: ${t.error}`;
@@ -250,18 +277,19 @@ async function readPdfFile(env, path, key, pages, signal, downsamplerOpt, cwd, p
             if (extract.ok) {
                 const blocks = await pdfPagesToImageBlocks(extract.pages, path, downsamplerOpt);
                 if (typeof blocks !== "string") {
+                    const renderTimeoutNote = extract.timedOutAfterSec !== undefined ? ` pdftoppm timed out after ${extract.timedOutAfterSec}s — only the pages that finished rendering are included.` : "";
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: `[PDF: ${path} — first ${extract.pages.length}${pageCount !== undefined ? ` of ${pageCount}` : ""} page${extract.pages.length === 1 ? "" : "s"} rendered as image${extract.pages.length === 1 ? "" : "s"} (100 dpi; ${textWhy}). ` +
-                                    `Use the pages parameter (e.g., pages: "${n + 1}-${n + PDF_FALLBACK_RENDER_PAGES}") to read more pages.]`,
+                                text: `[PDF: ${path} — first ${extract.pages.length}${pageCount !== undefined ? ` of ${pageCount}` : ""} page${extract.pages.length === 1 ? "" : "s"} rendered as image${extract.pages.length === 1 ? "" : "s"} (100 dpi; ${textWhy}).${renderTimeoutNote} ` +
+                                    `Use the pages parameter (e.g., pages: "${extract.pages.length + 1}-${extract.pages.length + PDF_FALLBACK_RENDER_PAGES}") to read more pages.]`,
                             },
                             ...blocks,
                         ],
                         details: {
                             type: "document",
-                            file: { ...fileCard, pages: `1-${extract.pages.length}`, renderedPages: extract.pages.length },
+                            file: { ...fileCard, pages: `1-${extract.pages.length}`, renderedPages: extract.pages.length, ...(extract.timedOutAfterSec !== undefined ? { timedOut: true } : {}) },
                             fallback: { level: 2, reason: `model lacks document input; ${textWhy}; rendered first ${extract.pages.length} page(s) via pdftoppm` },
                         },
                     };
@@ -309,7 +337,7 @@ export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRo
             "- This tool can only read files, not directories. To read a directory, use Glob/Grep or an ls command via the Bash tool.\n" +
             "- You must read a file before editing it.\n" +
             "- Reads PDFs (.pdf): the document is provided to the model directly (text layer included). Use the `pages` parameter (e.g., \"1-5\") to read a page range; PDFs over 10 pages REQUIRE `pages`. Maximum 20 pages per request.\n" +
-            "- Other binaries (archives, executables) and text files over 256 KB are refused; Grep a large file instead.\n" +
+            "- Other binaries (archives, executables) are refused. A whole-file read of a text file over 256 KB is refused — read it in slices with explicit offset/limit, or Grep it instead.\n" +
             "- If you read a file that exists but has empty contents you will receive a warning in place of file contents.\n" +
             "- Do NOT re-read a file you just edited to verify — Edit/Write would have errored if the change failed, and the harness tracks file state for you.",
         parameters: Type.Object({
@@ -399,8 +427,13 @@ export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRo
                 if (info.value.kind === "directory") {
                     return `Error (Read): "${path}" is a directory, not a file; use glob/grep or list it with the shell.`;
                 }
-                if (info.value.size > MAX_READ_BYTES) {
-                    return `Error (Read): "${path}" is too large to read (${info.value.size} bytes > ${MAX_READ_BYTES}-byte cap); use grep to search it instead.`;
+                if (info.value.size > SLICED_READ_MAX_BYTES) {
+                    return (`Error (Read): "${path}" is too large to read with this tool even as an offset/limit slice ` +
+                        `(${info.value.size} bytes > ${SLICED_READ_MAX_BYTES}-byte cap — the reader loads the whole file into memory before slicing). ` +
+                        `Stream a portion with bash instead, e.g. \`sed -n '1,200p' <file>\` for a line range or \`head -c 65536 <file>\` for the leading bytes, or use grep to search it.`);
+                }
+                if (info.value.size > MAX_READ_BYTES && offset === undefined && limit === undefined) {
+                    return `Error (Read): "${path}" is too large to read in full (${info.value.size} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`;
                 }
             }
             else {
@@ -411,6 +444,15 @@ export function makeReadFileTool(env, state, rootCanonical, cwdRef, additionalRo
             const readBin = await env.readBinaryFile(r.key, ctx.signal);
             if (!readBin.ok)
                 return `Error (Read): cannot read "${path}": ${readBin.error.message}`;
+            const readSize = readBin.value.byteLength;
+            if (readSize > SLICED_READ_MAX_BYTES) {
+                return (`Error (Read): "${path}" is too large to read with this tool even as an offset/limit slice ` +
+                    `(${readSize} bytes > ${SLICED_READ_MAX_BYTES}-byte cap — the reader loads the whole file into memory before slicing). ` +
+                    `Stream a portion with bash instead, e.g. \`sed -n '1,200p' <file>\` for a line range or \`head -c 65536 <file>\` for the leading bytes, or use grep to search it.`);
+            }
+            if (readSize > MAX_READ_BYTES && offset === undefined && limit === undefined) {
+                return `Error (Read): "${path}" is too large to read in full (${readSize} bytes > ${MAX_READ_BYTES}-byte cap); pass an explicit offset/limit to read a slice, or use grep to search it instead.`;
+            }
             if (pdfMagicMatches(readBin.value)) {
                 return await readPdfFile(env, path, r.key, pages, ctx.signal, imageDownsampler, cwdRef?.current ?? rootCanonical, readBin.value, pdfCapabilities);
             }
@@ -617,7 +659,7 @@ export function makeEditFileTool(env, state, rootCanonical, cwdRef, additionalRo
             }
             const notRead = requireRead(state, r.key);
             if (notRead)
-                return violationText("Edit", notRead);
+                return await notReadRefusalText(env, "Edit", r.key, notRead, ctx.signal);
             const readBin = await env.readBinaryFile(r.key, ctx.signal);
             if (!readBin.ok)
                 return `Error (Edit): cannot read "${path}": ${readBin.error.message}`;
@@ -795,7 +837,7 @@ export function makeNotebookEditTool(env, state, rootCanonical, cwdRef, addition
                 return violationText("NotebookEdit", r.violation);
             const notRead = requireRead(state, r.key);
             if (notRead)
-                return violationText("NotebookEdit", notRead);
+                return await notReadRefusalText(env, "NotebookEdit", r.key, notRead, ctx.signal);
             const readBin = await env.readBinaryFile(r.key, ctx.signal);
             if (!readBin.ok)
                 return `Error (NotebookEdit): cannot read "${notebook_path}": ${readBin.error.message}`;
@@ -936,7 +978,7 @@ export function makeGrepTool(env, rootCanonical, additionalRoots) {
                     return violationText("Grep", r.violation);
                 scoped = r.key;
             }
-            const text = await runGrep(env, rootCanonical, {
+            const grepRun = await runGrepDetailed(env, rootCanonical, {
                 ...a,
                 path: scoped,
                 head_limit: a.head_limit ?? a.max_results,
@@ -946,6 +988,7 @@ export function makeGrepTool(env, rootCanonical, additionalRoots) {
                 ignore_case: a.ignore_case ?? a["-i"],
                 only_matching: a.only_matching ?? a["-o"],
             }, ctx.signal);
+            const text = grepRun.text;
             const mode = a.output_mode ?? "content";
             const rows = text.startsWith("No matches.")
                 ? []
@@ -984,7 +1027,7 @@ export function makeGrepTool(env, rootCanonical, additionalRoots) {
             }
             return {
                 content: text,
-                details: { type: "grep", mode, ...detailFields },
+                details: { type: "grep", mode, ...detailFields, ...(grepRun.degraded ?? {}) },
             };
         },
     });
@@ -1206,7 +1249,7 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
         if (res.error.code === "transport_lost") {
             return `Error (${toolName}): connection to the execution environment was lost — the command's outcome is unknown and it may still be running. Verify its effects before retrying; retry only if the command is idempotent. (${res.error.message})`;
         }
-        if (res.error.code === "timeout" || res.error.code === "aborted") {
+        if (res.error.code === "timeout" || res.error.code === "aborted" || res.error.code === "callback_error") {
             const clip = clipShellOutput;
             const pStdout = clip(res.error.partialStdout ?? "");
             const pStderr = clip(res.error.partialStderr ?? "");
@@ -1216,7 +1259,9 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
                         ? `Command was cut off after ${timeout}s — NOT its requested ${requestedSec}s timeout: the task's wall-clock deadline has already been reached, so the command only got a ${timeout}s grace window. The process was killed; output produced before the cutoff is shown below. Do NOT retry this foreground command — there is no time left. Use run_in_background (exempt from this clamp) if the work must continue, or write out your results now.`
                         : `Command was cut off after ${timeout}s — NOT its requested ${requestedSec}s timeout: the task is near its wall-clock deadline, so the foreground time budget was clamped to the ${timeout}s remaining. The process was killed; output produced before the cutoff is shown below. Do NOT retry this foreground command — the next attempt gets even less time. Use run_in_background (exempt from this clamp) if the work must continue, or write out your results now.`
                     : `Command timed out after ${timeout}s (timeout limit: ${timeout}s). The process was killed; output produced before the cutoff is shown below. Re-running the same command will likely time out again — consider run_in_background for long commands, a narrower command, or resuming from the partial progress below.`
-                : `Command was interrupted (aborted) before completion. Output produced before the interrupt is shown below.`;
+                : res.error.code === "aborted"
+                    ? `Command was interrupted (aborted) before completion. Output produced before the interrupt is shown below.`
+                    : `Command started but its completion could not be observed — a host-side output-stream callback failed mid-run and the process was terminated (${res.error.message}). Output captured before the cut is shown below; its effects up to that point may have landed. Verify before assuming it needs a full re-run.`;
             const body = (pStdout ? `\n--- partial stdout ---\n${pStdout}` : "") +
                 (pStderr ? `\n--- partial stderr ---\n${pStderr}` : "") +
                 (!pStdout && !pStderr ? `\n(no output was produced before the cutoff)` : "");
@@ -1233,14 +1278,16 @@ async function runShell(env, cwd, toolName, command, timeoutSec, signal, cwdRef,
                             timeoutSec: timeout,
                             ...(clampedByDeadline ? { requestedTimeoutSec: requestedSec, clampedByDeadline: true } : {}),
                         }
-                        : { aborted: true }),
+                        : res.error.code === "aborted"
+                            ? { aborted: true }
+                            : { callbackError: true }),
                 },
             };
         }
-        return `Error (${toolName}): command did not run (${res.error.code}): ${res.error.message}`;
+        return `Error (${toolName}): command execution failed (${res.error.code}): ${res.error.message}. Whether the command started or completed could not be determined — verify its effects before retrying.`;
     }
     if (res.value.detached && detach) {
-        return detach.onDetached(res.value.detached.shellId, res.value.stdout, res.value.stderr);
+        return await detach.onDetached(res.value.detached.shellId, res.value.stdout, res.value.stderr);
     }
     let { stderr } = res.value;
     const { stdout, exitCode } = res.value;
@@ -1349,12 +1396,18 @@ export function makeBashTool(env, rootCanonical, coAuthor = DEFAULT_COMMIT_COAUT
                     if (diagnosis !== undefined)
                         throw new Error(diagnosis);
                 }
+                const requestedTimeoutSec = timeout !== undefined ? Math.max(1, Math.round(timeout / 1000)) : undefined;
                 const r = await env.spawnBackground(command, {
                     cwd: cwdRef.current,
-                    ...(timeout !== undefined ? { timeout: Math.max(1, Math.round(timeout / 1000)) } : {}),
+                    ...(requestedTimeoutSec !== undefined ? { timeout: requestedTimeoutSec } : {}),
                 });
                 if (!r.ok)
                     return `Error (Bash): ${r.error.message}`;
+                const bgCaps = env.backgroundCapabilities;
+                const appliedTimeoutSec = typeof bgCaps.defaultBgTimeoutSec === "number" && typeof bgCaps.maxBgTimeoutSec === "number"
+                    ? Math.min(requestedTimeoutSec ?? bgCaps.defaultBgTimeoutSec, bgCaps.maxBgTimeoutSec)
+                    : undefined;
+                const budgetNote = appliedTimeoutSec !== undefined ? ` Time budget: auto-terminates if still running after ${appliedTimeoutSec}s (hard cap ${bgCaps.maxBgTimeoutSec}s).` : "";
                 if (taskOpts.taskRegistry) {
                     const sessionScoped = taskOpts.sessionId !== undefined;
                     const owner = sessionScoped ? taskOpts.sessionId : (ctx.taskId ?? taskOpts.taskOwner);
@@ -1374,24 +1427,43 @@ export function makeBashTool(env, rootCanonical, coAuthor = DEFAULT_COMMIT_COAUT
                         });
                     }
                     catch (e) {
-                        await env.killBackground(r.value.shellId).catch(() => undefined);
-                        return `Error (Bash): background process was started but could not be registered (${e instanceof Error ? e.message : String(e)}); it has been terminated.`;
+                        const reason = e instanceof Error ? e.message : String(e);
+                        let kill;
+                        try {
+                            kill = await env.killBackground(r.value.shellId);
+                        }
+                        catch {
+                            kill = undefined;
+                        }
+                        if (kill !== undefined && (kill.ok || kill.error.code === "not_found")) {
+                            return `Error (Bash): background process was started but could not be registered (${reason}); it has been terminated.`;
+                        }
+                        const killMsg = kill !== undefined && !kill.ok ? kill.error.message : "killBackground threw";
+                        return {
+                            content: `Error (Bash): background process was started but could not be registered (${reason}), and the cleanup kill failed (${killMsg}). ` +
+                                `The process could NOT be terminated — it may still be running, but it has no task_id, so TaskOutput/TaskStop cannot reach it. ` +
+                                `If it must be stopped, kill it manually (e.g. \`pkill -f\` on its command line).`,
+                            details: { type: "bash", registerFailed: true, killFailed: true },
+                        };
                     }
                     return onNotify !== undefined
                         ? `Command running in background; task_id=${taskId}. You will be notified when it completes — do not poll; ` +
-                            `end your turn if nothing else is pending. Use TaskOutput("${taskId}") to check interim output; TaskStop("${taskId}") to stop.`
+                            `end your turn if nothing else is pending. Use TaskOutput("${taskId}") to check interim output; TaskStop("${taskId}") to stop.` +
+                            budgetNote
                         : `Started in background; task_id=${taskId}. ` +
                             `Use TaskOutput("${taskId}") to read output (poll until status is no longer "running"); ` +
-                            `TaskStop("${taskId}") to stop. No '&' needed.`;
+                            `TaskStop("${taskId}") to stop. No '&' needed.` +
+                            budgetNote;
                 }
                 return (`Started in background; task_id=${r.value.shellId}. Legacy bash_id=${r.value.shellId}. ` +
                     `Use TaskOutput("${r.value.shellId}") to read output (poll until status is no longer "running"); ` +
-                    `TaskStop("${r.value.shellId}") to stop. No '&' needed.`);
+                    `TaskStop("${r.value.shellId}") to stop. No '&' needed.` +
+                    budgetNote);
             }
             const detachChain = taskOpts.detachHub && taskOpts.taskRegistry && hasBackgroundShell(env) && env.backgroundCapabilities.supportsDetach === true
                 ? {
                     signal: taskOpts.detachHub.signalFor(ctx.toolCallId),
-                    onDetached: (shellId, stdoutSoFar, _stderrSoFar) => {
+                    onDetached: async (shellId, stdoutSoFar, stderrSoFar) => {
                         const sessionScoped = taskOpts.sessionId !== undefined;
                         const owner = sessionScoped ? taskOpts.sessionId : (ctx.taskId ?? taskOpts.taskOwner);
                         const scope = ctx.principal ?? taskOpts.taskScope;
@@ -1410,18 +1482,48 @@ export function makeBashTool(env, rootCanonical, coAuthor = DEFAULT_COMMIT_COAUT
                             });
                         }
                         catch (e) {
+                            const reason = e instanceof Error ? e.message : String(e);
+                            let kill;
+                            try {
+                                kill = await env.killBackground(shellId);
+                            }
+                            catch {
+                                kill = undefined;
+                            }
+                            const killed = kill !== undefined && (kill.ok || kill.error.code === "not_found");
+                            const outTail = stdoutSoFar.slice(-1_000);
+                            const errTail = stderrSoFar.slice(-1_000);
+                            const tails = (outTail ? `\n--- output so far (tail) ---\n${outTail}` : "") +
+                                (errTail ? `\n--- stderr so far (tail) ---\n${errTail}` : "");
+                            if (killed) {
+                                return {
+                                    content: `Error (Bash): command was detached to the background but could not be registered (${reason}); ` +
+                                        `it has been terminated (an unregistered background process would have no task_id and could not be read or stopped).` +
+                                        tails,
+                                    details: { type: "bash", detached: true, registerFailed: true },
+                                };
+                            }
+                            const killMsg = kill !== undefined && !kill.ok ? kill.error.message : "killBackground threw";
                             return {
-                                content: `Command moved to background but could not be registered (${e instanceof Error ? e.message : String(e)}); it keeps running under the env's background limits.`,
-                                details: { type: "bash", detached: true },
+                                content: `Error (Bash): command was detached to the background but could not be registered (${reason}), and the cleanup kill failed (${killMsg}). ` +
+                                    `The process could NOT be terminated — it may still be running, but it has no task_id, so TaskOutput/TaskStop cannot reach it. ` +
+                                    `If it must be stopped, kill it manually (e.g. \`pkill -f\` on its command line).` +
+                                    tails,
+                                details: { type: "bash", detached: true, registerFailed: true, killFailed: true },
                             };
                         }
                         const tail = stdoutSoFar.slice(-1_000);
+                        const adoptCaps = env.backgroundCapabilities;
+                        const adoptBudgetNote = typeof adoptCaps.defaultBgTimeoutSec === "number" && typeof adoptCaps.maxBgTimeoutSec === "number"
+                            ? ` Time budget: auto-terminates if still running after ${Math.min(adoptCaps.defaultBgTimeoutSec, adoptCaps.maxBgTimeoutSec)}s (hard cap ${adoptCaps.maxBgTimeoutSec}s).`
+                            : "";
                         return {
                             content: `Command moved to background; task_id=${taskId}. ` +
                                 `Use TaskOutput("${taskId}") to read its output; TaskStop("${taskId}") to stop it. ` +
                                 (onNotify !== undefined
                                     ? `You will be notified when it completes — do not poll.`
                                     : `Poll TaskOutput until its status is no longer "running".`) +
+                                adoptBudgetNote +
                                 (tail ? `\n--- output so far (tail) ---\n${tail}` : ""),
                             details: { type: "bash", detached: true, task_id: taskId, ...(description !== undefined ? { description } : {}) },
                         };