mixdog 1.3.0 → 1.3.2

package/src/runtime/agent/orchestrator/tools/builtin/read-single-media.mjs

@@ -11,11 +11,40 @@
  * stringify it to "[object Object]"; scalar reads leave it unset and get the
  * rich block shapes.
  */
+import { open } from 'node:fs/promises';
 import { extname } from 'node:path';
 import { extractOoxmlText } from '../../../../attachments/office-extract.mjs';
+import { readImageAsContent } from './read-image.mjs';
 
 const OOXML_EXTENSIONS = new Set(['.docx', '.pptx', '.xlsx', '.xlsm']);
 
+// File signatures of the media an extension-less path may hold: the stored
+// attachments a reference points at keep no extension.
+const SNIFFED_IMAGE_TYPES = [
+  { mimeType: 'image/png', matches: (head) => head.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex')) },
+  { mimeType: 'image/jpeg', matches: (head) => head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff },
+  { mimeType: 'image/gif', matches: (head) => head.subarray(0, 4).toString('latin1') === 'GIF8' },
+  {
+    mimeType: 'image/webp',
+    matches: (head) =>
+      head.subarray(0, 4).toString('latin1') === 'RIFF' && head.subarray(8, 12).toString('latin1') === 'WEBP',
+  },
+];
+
+async function sniffedMediaType(fullPath, st) {
+  if (!st?.isFile?.() || st.size < 5) return null;
+  const handle = await open(fullPath, 'r');
+  try {
+    const head = Buffer.alloc(12);
+    const { bytesRead } = await handle.read(head, 0, head.length, 0);
+    const bytes = head.subarray(0, bytesRead);
+    if (bytes.subarray(0, 5).toString('latin1') === '%PDF-') return 'application/pdf';
+    return SNIFFED_IMAGE_TYPES.find((type) => type.matches(bytes))?.mimeType || null;
+  } finally {
+    await handle.close();
+  }
+}
+
 /**
  * @returns {Promise<{ result: unknown } | null>} null when the path is not a
  *   media file.
@@ -24,8 +53,24 @@ export async function readMediaFile({ fullPath, st, args, readStateScope, option
   const { extractPdfText, extractIpynbText, READ_MAX_OUTPUT_BYTES, _recordReadSnapshot } = helpers;
   const textOnly = options?.mediaTextOnly === true;
   const ext = extname(fullPath).toLowerCase();
-  if (ext === '.pdf') {
-    return { result: await extractPdfText(fullPath, args.pages, { maxOutputBytes: READ_MAX_OUTPUT_BYTES, textOnly }) };
+  const sniffed = ext === '' ? await sniffedMediaType(fullPath, st) : null;
+  if (ext === '.pdf' || sniffed === 'application/pdf') {
+    return {
+      result: await extractPdfText(fullPath, args.pages, {
+        maxOutputBytes: READ_MAX_OUTPUT_BYTES,
+        textOnly,
+        // The caller's model decides how a scanned page arrives: as a page
+        // image for one that reads images, as OCR text for a text-only one;
+        // a whole document block only for one that reads PDFs natively.
+        pageMode: options?.pdfPageMode === 'ocr' ? 'ocr' : 'image',
+        nativeDocument: options?.pdfNativeDocument !== false,
+        signal: options?.signal || null,
+      }),
+    };
+  }
+  if (sniffed && !textOnly) {
+    const image = await readImageAsContent(fullPath, args.path || fullPath, st, sniffed);
+    if (image) return { result: image };
   }
   if (OOXML_EXTENSIONS.has(ext)) {
     // OOXML text extraction — always a flat string, so it is batch-safe

package/src/runtime/agent/orchestrator/tools/builtin/read-special-files.mjs

@@ -1,18 +1,25 @@
 import { readFile, stat } from 'node:fs/promises';
-import { MAX_PDF_BYTES, MAX_PDF_PAGES, isPdfBuffer } from '../../../../attachments/limits.mjs';
+import { MAX_PDF_BYTES, isPdfBuffer } from '../../../../attachments/limits.mjs';
+import { READ_PDF_MAX_PAGES_PER_CALL } from '../../../../attachments/attachment-reference.mjs';
 import { READ_MAX_SIZE_BYTES } from './read-constants.mjs';
 import { capMarker } from './tool-output-limit.mjs';
 import { imageBlocksFromBuffer } from './read-image-resize.mjs';
-import { inspectPdfBuffer } from '../../../../attachments/pdf-extract.mjs';
+import { boundedUtf8, inspectPdfBuffer, pageHasTextLayer } from '../../../../attachments/pdf-extract.mjs';
 
 const DEFAULT_READ_MAX_OUTPUT_BYTES = 100 * 1024;
 
-// PDFs at or under this size are emitted as the runtime's canonical base64
-// document block (providers convert it to their native file shape): 20MB raw → ~27MB
-// base64, which stays under the 32MB request cap.
-// Larger PDFs fall back to bounded PDF.js text extraction.
-// (MAX_PDF_BYTES / MAX_PDF_PAGES come from the shared attachment limits.)
-const PDF_TEXT_FALLBACK_PAGES = 20;
+// A whole-PDF read (no pages) returns a PDF of up to this many pages whole —
+// as the canonical base64 document block for a model that reads PDFs natively
+// (providers convert it to their native file shape; MAX_PDF_BYTES keeps it
+// under the request cap). A longer PDF returns its outline and first pages:
+// the model then reads the pages it needs.
+const PDF_WHOLE_READ_MAX_PAGES = 10;
+const PDF_PREVIEW_PAGES = 5;
+// Scanned pages render at this width: past the point where text in a page
+// image stays legible, below the vision ceiling that would downscale it again.
+const PDF_PAGE_IMAGE_WIDTH = 1200;
+// The renderer takes at most 12 explicit pages per call.
+const PDF_RENDER_BATCH = 12;
 
 // Per-output text ceiling inside a notebook. A single cell output larger than
 // this is replaced with a jq hint (large-notebook guidance) so a
@@ -40,15 +47,16 @@ function parsePagesArg(pagesArg) {
   if (to < from) {
     return { error: `Error: pages "${trimmed}" inverted — end (${to}) precedes start (${from})` };
   }
-  if (to - from + 1 > 20) {
-    return { error: `Error: pages "${trimmed}" spans ${to - from + 1} pages; max 20 per request — narrow the range` };
+  if (to - from + 1 > READ_PDF_MAX_PAGES_PER_CALL) {
+    return {
+      error: `Error: pages "${trimmed}" spans ${to - from + 1} pages; max ${READ_PDF_MAX_PAGES_PER_CALL} per request — narrow the range`,
+    };
   }
   return { filter: { from, to } };
 }
 
-// PDF.js text extraction. Fallback path for PDFs over the document-block
-// size cap, and the always-path when a page range is requested (a base64
-// document block can't be page-filtered, so a narrowed read keeps using text).
+// PDF.js text extraction for a file without the %PDF- signature: pdf.js
+// surfaces the parse error as text instead of a document block.
 async function extractPdfTextBody(fullPath, pageFilter, maxOutputBytes) {
   const buf = await readFile(fullPath);
   const result = await inspectPdfBuffer(buf, {
@@ -60,79 +68,240 @@ async function extractPdfTextBody(fullPath, pageFilter, maxOutputBytes) {
   return result.text || '(no text content extracted from PDF)';
 }
 
+// Bounded UTF-8 cut for the text a paged read returns.
+function capPdfText(text, maxOutputBytes) {
+  const bounded = boundedUtf8(text, maxOutputBytes);
+  if (!bounded.truncated) return text;
+  return `${bounded.text}\n\n${capMarker({ limit: maxOutputBytes, shown: 'PDF text cut', narrow: 'read a narrower pages range' })}`;
+}
+
+async function renderPdfPageImages(fullPath, pages, signal) {
+  const { renderPdfPages } = await import('../../../../office/pdf/pdf-render.mjs');
+  const out = [];
+  for (let offset = 0; offset < pages.length; offset += PDF_RENDER_BATCH) {
+    const rendered = await renderPdfPages(fullPath, {
+      pages: pages.slice(offset, offset + PDF_RENDER_BATCH),
+      maxWidth: PDF_PAGE_IMAGE_WIDTH,
+      signal,
+      writeImages: false,
+    });
+    out.push(...rendered.images);
+  }
+  return out;
+}
+
+async function recognizePdfPages(fullPath, pages, signal) {
+  const [{ recognizePdfPageTexts }, { defaultOfficeDataDir }] = await Promise.all([
+    import('../../../../office/pdf/pdf-ocr.mjs'),
+    import('../../../../office/core/journal.mjs'),
+  ]);
+  return recognizePdfPageTexts(fullPath, pages, { dataDir: defaultOfficeDataDir(), signal });
+}
+
+function pageList(pages) {
+  return pages.length > 6 ? `${pages.slice(0, 6).join(', ')}, …` : pages.join(', ');
+}
+
+function errorText(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function pdfFileLabel(fullPath) {
+  return fullPath.split(/[\\/]/).pop();
+}
+
+// The scanned pages of one paged read, as page images or OCR text. A page the
+// renderer or the OCR engine cannot produce says so instead of failing the
+// whole read: the text pages are still returned.
+async function scannedPageBodies(fullPath, scanned, { pageMode, signal, renderPages, recognizePages }) {
+  const bodies = new Map();
+  if (!scanned.length) return bodies;
+  if (pageMode === 'text') {
+    for (const page of scanned) {
+      bodies.set(page, {
+        text: `(no text layer: a scanned page. Read this PDF on its own with pages="${page}" to see it as an image or OCR text.)`,
+      });
+    }
+    return bodies;
+  }
+  if (pageMode === 'image') {
+    try {
+      for (const image of await renderPages(fullPath, scanned, signal)) {
+        bodies.set(image.page, { image });
+      }
+    } catch (error) {
+      for (const page of scanned) {
+        bodies.set(page, { text: `(no text layer, and the page image could not be rendered: ${errorText(error)})` });
+      }
+    }
+    return bodies;
+  }
+  try {
+    for (const { page, text } of await recognizePages(fullPath, scanned, signal)) {
+      bodies.set(page, { ocr: text || '(OCR found no text on this page)' });
+    }
+  } catch (error) {
+    const note =
+      `(no text layer, and OCR is unavailable here: ${errorText(error)}. OCR language data downloads on first ` +
+      'use, so this needs a network connection once; after that it works offline. A model that accepts images ' +
+      'can read these pages as page images instead.)';
+    for (const page of scanned) bodies.set(page, { text: note });
+  }
+  return bodies;
+}
+
+// One page range: text pages as their text, scanned pages (no text layer) as
+// page images for a model that reads images, OCR text for a text-only model,
+// or a note in a flat-text context. Order follows the pages.
+async function readPdfPageRange(fullPath, buf, pageCount, range, options) {
+  const { maxOutputBytes, note = '' } = options;
+  const extracted = await inspectPdfBuffer(buf, {
+    extractText: true,
+    maxPages: Infinity,
+    maxOutputBytes,
+    pageRange: range,
+  });
+  const scanned = extracted.pages.filter((entry) => !pageHasTextLayer(entry.text)).map((entry) => entry.page);
+  const bodies = await scannedPageBodies(fullPath, scanned, options);
+  const label = pdfFileLabel(fullPath);
+  const textPages = extracted.pages.length - scanned.length;
+  const header =
+    `[PDF ${label}: pages ${range.from}-${range.to} of ${pageCount}; ` +
+    `${textPages === extracted.pages.length ? 'every page has a text layer' : `scanned (no text layer): ${pageList(scanned)}`}` +
+    `${note ? `. ${note}` : ''}]`;
+  const blocks = [];
+  let text = header;
+  let textBytes = 0;
+  const flush = () => {
+    if (!text) return;
+    blocks.push({ type: 'text', text: capPdfText(text, Math.max(1, maxOutputBytes - textBytes)) });
+    textBytes += Buffer.byteLength(text, 'utf8');
+    text = '';
+  };
+  for (const entry of extracted.pages) {
+    const body = bodies.get(entry.page);
+    if (body?.image) {
+      text += `${text ? '\n\n' : ''}--- Page ${entry.page} (scanned; page image follows) ---`;
+      flush();
+      const { data, mimeType, width, height } = body.image;
+      blocks.push({ type: 'image', data, mimeType, width, height });
+      continue;
+    }
+    let pageText = entry.text;
+    let title = `--- Page ${entry.page} ---`;
+    if (body?.ocr) {
+      title = `--- Page ${entry.page} (OCR of a scanned page) ---`;
+      pageText = body.ocr;
+    } else if (body?.text) {
+      pageText = body.text;
+    }
+    text += `${text ? '\n\n' : ''}${title}\n${pageText}`;
+  }
+  flush();
+  if (blocks.every((block) => block.type === 'text')) return blocks.map((block) => block.text).join('\n\n');
+  return { content: blocks };
+}
+
+function pdfInspectError(fullPath, error) {
+  const label = pdfFileLabel(fullPath);
+  const protectedPdf = error?.name === 'PasswordException' || /password/i.test(String(error?.message || ''));
+  return protectedPdf
+    ? `Error: this PDF is password-protected and cannot be read (${label}).`
+    : `Error: ${label} is not a valid PDF (${errorText(error)}).`;
+}
+
+/**
+ * Reads a PDF: whole for a short one, by page range otherwise.
+ *
+ * pages "N" / "N-M" (≤20) reads that range: text first; pages without a text
+ * layer come back as page images (`pageMode: 'image'`, a model that sees
+ * images), OCR text (`pageMode: 'ocr'`, a text-only model) or a note
+ * (`textOnly`, a batch that must stay flat text). Without pages a PDF of up to
+ * 10 pages is returned whole (a document block when `nativeDocument`, the
+ * model reading PDFs natively, else every page through the range path), a
+ * longer one as the outline and its first 5 pages. offset/limit do not apply.
+ */
 export async function extractPdfText(
   fullPath,
   pagesArg,
-  { maxOutputBytes = DEFAULT_READ_MAX_OUTPUT_BYTES, textOnly = false } = {}
+  {
+    maxOutputBytes = DEFAULT_READ_MAX_OUTPUT_BYTES,
+    textOnly = false,
+    pageMode = 'image',
+    nativeDocument = true,
+    signal = null,
+    renderPages = renderPdfPageImages,
+    recognizePages = recognizePdfPages,
+  } = {}
 ) {
   try {
     let pdfStat;
     try {
       pdfStat = await stat(fullPath);
     } catch (e) {
-      return `Error: pdf stat failed — ${e instanceof Error ? e.message : String(e)}`;
+      return `Error: pdf stat failed — ${errorText(e)}`;
     }
 
     const pages = parsePagesArg(pagesArg);
     if (pages.error) return pages.error;
 
-    // Document-block path: whole-PDF read, no page range, within the size
-    // cap, and confirmed %PDF- magic. Emits the canonical document block
-    // that provider adapters convert to native media (figures, layout,
-    // tables) instead of lossy pdf-parse text. The magic-byte guard prevents
-    // a non-PDF (mislabelled extension) from poisoning history.
-    // textOnly (batch context) skips the block and always emits text.
-    if (!textOnly && !pages.filter && pdfStat.size <= MAX_PDF_BYTES) {
-      const buf = await readFile(fullPath);
-      if (isPdfBuffer(buf)) {
-        // A password-protected or invalid PDF is rejected by every provider
-        // and would wedge the session if it entered history as a block.
-        let pageCount;
-        try {
-          ({ pageCount } = await inspectPdfBuffer(buf, { maxPages: Infinity }));
-        } catch (inspectErr) {
-          const label = fullPath.split(/[\\/]/).pop();
-          const protectedPdf =
-            inspectErr?.name === 'PasswordException' || /password/i.test(String(inspectErr?.message || ''));
-          return protectedPdf
-            ? `Error: this PDF is password-protected and cannot be read (${label}).`
-            : `Error: ${label} is not a valid PDF (${inspectErr instanceof Error ? inspectErr.message : String(inspectErr)}).`;
-        }
-        if (pageCount > MAX_PDF_PAGES) {
-          const head = await inspectPdfBuffer(buf, {
-            extractText: true,
-            maxPages: Infinity,
-            maxOutputBytes,
-            pageRange: { from: 1, to: PDF_TEXT_FALLBACK_PAGES },
-          });
-          return (
-            `[PDF has ${pageCount} pages, too many to attach natively (max ${MAX_PDF_PAGES});` +
-            `showing extracted text of pages 1-${PDF_TEXT_FALLBACK_PAGES}. Pass \`pages\` (e.g. "21-40", max 20 per request) to read others.]\n` +
-            (head.text || '(no text content extracted from PDF)')
-          );
+    const buf = await readFile(fullPath);
+    // Not a real PDF (mislabelled extension) — pdf.js surfaces a clean parse
+    // error rather than a bad document block entering history.
+    if (!isPdfBuffer(buf)) return await extractPdfTextBody(fullPath, pages.filter, maxOutputBytes);
+    // A password-protected or invalid PDF is rejected by every provider and
+    // would wedge the session if it entered history as a block.
+    let pageCount;
+    try {
+      ({ pageCount } = await inspectPdfBuffer(buf, { maxPages: Infinity }));
+    } catch (inspectErr) {
+      return pdfInspectError(fullPath, inspectErr);
+    }
+    const mode = textOnly ? 'text' : pageMode;
+    const rangeOptions = { maxOutputBytes, pageMode: mode, signal, renderPages, recognizePages };
+    if (pages.filter) {
+      if (pages.filter.from > pageCount) {
+        return `Error: pages "${pagesArg}" out of range — this PDF has ${pageCount} page${pageCount === 1 ? '' : 's'}`;
+      }
+      const range = { from: pages.filter.from, to: Math.min(pages.filter.to, pageCount) };
+      return await readPdfPageRange(fullPath, buf, pageCount, range, rangeOptions);
+    }
+    if (pageCount > PDF_WHOLE_READ_MAX_PAGES) {
+      return await readPdfPageRange(
+        fullPath,
+        buf,
+        pageCount,
+        { from: 1, to: PDF_PREVIEW_PAGES },
+        {
+          ...rangeOptions,
+          note: `Showing the first ${PDF_PREVIEW_PAGES} pages; pass pages (e.g. "${PDF_PREVIEW_PAGES + 1}-${Math.min(pageCount, PDF_PREVIEW_PAGES + 10)}", up to ${READ_PDF_MAX_PAGES_PER_CALL} per call) to read the pages the request needs`,
         }
-        return {
-          content: [
-            {
-              type: 'document',
-              source: {
-                type: 'base64',
-                media_type: 'application/pdf',
-                data: buf.toString('base64'),
-              },
-              pageCount,
+      );
+    }
+    // A short PDF whole: a model that reads PDFs natively gets the canonical
+    // document block (figures, layout, tables) with its page and text-layer
+    // counts for the estimate; others get every page through the range path.
+    if (mode === 'image' && nativeDocument && pdfStat.size <= MAX_PDF_BYTES) {
+      const { textPages, textChars } = await inspectPdfBuffer(buf, { maxPages: Infinity, measureText: true });
+      return {
+        content: [
+          {
+            type: 'document',
+            source: {
+              type: 'base64',
+              media_type: 'application/pdf',
+              data: buf.toString('base64'),
             },
-          ],
-        };
-      }
-      // Not a real PDF — fall through to pdf-parse, which surfaces a
-      // clean parse error rather than emitting a bad document block.
+            pageCount,
+            textPages,
+            textChars,
+          },
+        ],
+      };
     }
-
-    // TEXT fallback: >20MB PDFs, page-filtered reads, or non-magic files.
-    return await extractPdfTextBody(fullPath, pages.filter, maxOutputBytes);
+    return await readPdfPageRange(fullPath, buf, pageCount, { from: 1, to: Math.max(1, pageCount) }, rangeOptions);
   } catch (err) {
-    return `Error: PDF extraction failed — ${err instanceof Error ? err.message : String(err)}`;
+    return `Error: PDF extraction failed — ${errorText(err)}`;
   }
 }
 
@@ -197,6 +366,30 @@ function capNotebookText(blocks, maxOutputBytes) {
   return capped;
 }
 
+// The image blocks (each after its resize note, when it has one) for one
+// cell's image outputs. An image the resize helper cannot take (sharp
+// unavailable) stays the text placeholder already in the cell's text.
+async function notebookImageBlocks(pendingImages, fullPath, cellIndex) {
+  const blocks = [];
+  for (const img of pendingImages) {
+    let buf;
+    try {
+      buf = Buffer.from(img.b64, 'base64');
+    } catch {
+      buf = null;
+    }
+    if (!buf || buf.length === 0) continue;
+    const built = await imageBlocksFromBuffer(buf, img.mimeType, {
+      sourcePath: `${fullPath} [cell ${cellIndex}]`,
+    });
+    if (built) {
+      if (built.textBlock) blocks.push(built.textBlock);
+      blocks.push(built.imageBlock);
+    }
+  }
+  return blocks;
+}
+
 export async function extractIpynbText(
   fullPath,
   { maxOutputBytes = DEFAULT_READ_MAX_OUTPUT_BYTES, hasRangeArgs = false, textOnly = false } = {}
@@ -214,7 +407,7 @@ export async function extractIpynbText(
     try {
       nbStat = await stat(fullPath);
     } catch (e) {
-      return `Error: ipynb stat failed — ${e instanceof Error ? e.message : String(e)}`;
+      return `Error: ipynb stat failed — ${errorText(e)}`;
     }
     if (nbStat.size > READ_MAX_SIZE_BYTES) {
       return `Error: notebook too large (size: ${nbStat.size}B, cap: ${READ_MAX_SIZE_BYTES}B) — use a cell range to narrow`;
@@ -253,23 +446,7 @@ export async function extractIpynbText(
         // placeholder in `block` is the only representation.
         if (!textOnly && pendingImages.length > 0) {
           flushText();
-          for (const img of pendingImages) {
-            let buf;
-            try {
-              buf = Buffer.from(img.b64, 'base64');
-            } catch {
-              buf = null;
-            }
-            if (!buf || buf.length === 0) continue;
-            const built = await imageBlocksFromBuffer(buf, img.mimeType, {
-              sourcePath: `${fullPath} [cell ${cellIndex}]`,
-            });
-            if (built) {
-              if (built.textBlock) blocks.push(built.textBlock);
-              blocks.push(built.imageBlock);
-            }
-            // built === null → sharp unavailable; placeholder text already emitted.
-          }
+          blocks.push(...(await notebookImageBlocks(pendingImages, fullPath, cellIndex)));
         }
       }
     }
@@ -293,6 +470,6 @@ export async function extractIpynbText(
     }
     return { content: blocks };
   } catch (err) {
-    return `Error: ipynb parse failed — ${err instanceof Error ? err.message : String(err)}`;
+    return `Error: ipynb parse failed — ${errorText(err)}`;
   }
 }

package/src/runtime/agent/orchestrator/tools/builtin/shell-analysis.mjs

@@ -1255,9 +1255,9 @@ export function buildPowerShellFilterTeePlan(command) {
 }
 
 // Read the tail of a tee spill file (BOM-sniffed: Windows PowerShell 5.1
-// writes UTF-16LE, pwsh 7 writes UTF-8) and ALWAYS delete the file. Returns
-// null when the file is missing/empty/unreadable.
-export function consumeFilterTeeCapture(teePath, { maxBytes = 16384 } = {}) {
+// writes UTF-16LE, pwsh 7 writes UTF-8). Returns null when the file is
+// missing/empty/unreadable.
+export function readFilterTeeCapture(teePath, { maxBytes = 16384 } = {}) {
   let out = null;
   try {
     const st = statSync(teePath);
@@ -1281,10 +1281,16 @@ export function consumeFilterTeeCapture(teePath, { maxBytes = 16384 } = {}) {
   } catch {
     out = null;
   }
+  return out?.trim() ? out : null;
+}
+
+// The tail of a tee spill file, which is then ALWAYS deleted.
+export function consumeFilterTeeCapture(teePath, options) {
+  const out = readFilterTeeCapture(teePath, options);
   try {
     unlinkSync(teePath);
   } catch {
     /* best-effort cleanup */
   }
-  return out?.trim() ? out : null;
+  return out;
 }

package/src/runtime/agent/orchestrator/tools/builtin/shell-jobs.mjs

@@ -28,10 +28,8 @@ import {
   adoptShellWorkspaceAdmission,
   clearTerminationHold,
   completeShellJobRecord,
-  isShellOwnerSessionClosed,
   listShellJobRecords,
   markShellJobTerminationUnconfirmed,
-  noteShellJobSurvivors,
   publishShellJobRecord,
   registerTerminationHold,
   retireShellJobRecord,
@@ -196,8 +194,6 @@ function trackShellJobRecord(task, options) {
       sweep: killed,
       onTerminated: finish,
       releaseRequested: () => takeReleaseRequest(jobId),
-      ownerClosed: () => isShellOwnerSessionClosed(options?.ownerSessionId),
-      onSurvivors: (pids) => void noteShellJobSurvivors(jobId, pids),
       onUnconfirmed: () => {
         void markShellJobTerminationUnconfirmed(jobId);
         registerTerminationHold(jobId, {
@@ -343,41 +339,58 @@ export function peekShellJob(jobId) {
   return attachJobInsights(normalizeShellJobDetail(getNativeTask(jobId)));
 }
 
-/** True while the job's process is still alive in this daemon. Owners of
+/** Run `onTreeSettled` once a job whose native task is terminal is over as a
+ *  whole: at once for an untracked job, else once every process of its tree is
+ *  confirmed gone (or the user released it) — a root's exit is not the end of
+ *  what it started. */
+function afterTreeSettled(jobId, onTreeSettled) {
+  const entry = backgroundTrackers.get(jobId);
+  if (entry) void entry.terminated.then(onTreeSettled);
+  else onTreeSettled();
+}
+
+/** True while a process of the job is still alive in this daemon. Owners of
  *  in-use artifacts consult it before a fallback cleanup fires. */
 export function isShellJobRunning(jobId) {
-  return getNativeTask(String(jobId || ''))?.status === 'running';
+  const key = String(jobId || '');
+  return getNativeTask(key)?.status === 'running' || backgroundTrackers.has(key);
 }
 
-/** Run `onSettled` once the job leaves 'running' (immediately when it already
- *  has). Owners of per-command artifacts (hoisted script files, tee captures,
- *  cache invalidation) use this instead of a fixed timer, which either fired
- *  under a still-running command or never at all. Returns an unsubscribe, or
- *  null when the job is unknown here — the caller then keeps its own fallback. */
+/** Run `onSettled` once the job leaves 'running' and its tree has settled
+ *  (immediately when both already have). Owners of per-command artifacts
+ *  (hoisted script files, tee captures, cache invalidation) use this instead of
+ *  a fixed timer, which either fired under a still-running command or never at
+ *  all. Returns an unsubscribe, or null when the job is unknown here — the
+ *  caller then keeps its own fallback. */
 export function subscribeShellJobSettled(jobId, onSettled) {
   const key = String(jobId || '').trim();
   if (!key || typeof onSettled !== 'function') return null;
   const current = getNativeTask(key);
   if (!current) return null;
-  if (current.status !== 'running') {
-    queueMicrotask(() => {
+  let done = false;
+  const deliver = (task) =>
+    afterTreeSettled(key, () => {
+      if (done) return;
+      done = true;
       try {
-        onSettled(current);
+        onSettled(task);
       } catch {}
     });
-    return () => {};
+  if (current.status !== 'running') {
+    queueMicrotask(() => deliver(current));
+    return () => {
+      done = true;
+    };
   }
-  let done = false;
+  let seen = false;
   let unsubscribe = () => {};
   const fire = (task) => {
-    if (done || !task || task.status === 'running') return;
-    done = true;
+    if (seen || done || !task || task.status === 'running') return;
+    seen = true;
     try {
       unsubscribe();
     } catch {}
-    try {
-      onSettled(task);
-    } catch {}
+    deliver(task);
   };
   unsubscribe = subscribeNativeTask(key, fire);
   return () => {

package/src/runtime/agent/orchestrator/tools/code-graph/constants.mjs

@@ -38,12 +38,16 @@ export const CODE_GRAPH_DISK_MEMORY_MAX_BYTES = Math.max(
 // Younger .tmp files may belong to an in-flight persist still holding the sibling .lock;
 // DEFAULT_LOCK_TIMEOUT_MS is 8s — 120s is a safe margin for large graph JSON writes.
 export const ORPHAN_TMP_MIN_AGE_MS = 120_000;
-export const RE_CACHE_TMP = /^\.[0-9a-f]{16}\.json\.[0-9a-f]{24}\.tmp$/i;
-export const RE_MANIFEST_TMP = /^\.manifest\.json\.[0-9a-f]{24}\.tmp$/i;
+// Atomic writer temp name: `<basename>.mixdog-tmp-<16hex>`; the dot-prefixed
+// `.<basename>.<24hex>.tmp` is what older builds left behind.
+export const RE_CACHE_TMP =
+  /^(?:\.[0-9a-f]{16}\.json\.[0-9a-f]{24}\.tmp|[0-9a-f]{16}\.json\.mixdog-tmp-[0-9a-f]{16,24})$/i;
+export const RE_MANIFEST_TMP = /^(?:\.manifest\.json\.[0-9a-f]{24}\.tmp|manifest\.json\.mixdog-tmp-[0-9a-f]{16,24})$/i;
 export const RE_CACHE_LOCK = /^[0-9a-f]{16}\.json\.lock$/i;
 // Same debris, for the `<hash>.calls.json` call-site sidecar written beside
-// each entry (atomic writer temp name: `.<basename>.<24hex>.tmp`).
-export const RE_CALLS_CACHE_TMP = /^\.[0-9a-f]{16}\.calls\.json\.[0-9a-f]{24}\.tmp$/i;
+// each entry.
+export const RE_CALLS_CACHE_TMP =
+  /^(?:\.[0-9a-f]{16}\.calls\.json\.[0-9a-f]{24}\.tmp|[0-9a-f]{16}\.calls\.json\.mixdog-tmp-[0-9a-f]{16,24})$/i;
 export const RE_CALLS_CACHE_LOCK = /^[0-9a-f]{16}\.calls\.json\.lock$/i;
 export const CODE_GRAPH_MEMORY_MAX_ENTRIES = Math.max(
   1,