mixdog 1.2.2 → 1.2.4

package/src/runtime/office/core/office-write-ledger.mjs

@@ -0,0 +1,94 @@
+/**
+ * office-write-ledger.mjs — the workspace files one Office Use call wrote,
+ * with their exact before/after state, so the session's turn review counts
+ * them as its own changes and Undo can restore them.
+ *
+ * Ownership is never inferred from the folder: every route that writes a
+ * workspace file — the session's working copy, a created or converted
+ * document, a render's preview and page images, a split/extract/query output,
+ * an authored document and its sidecars, a secured PDF — hands the path to
+ * noteOfficeWrite BEFORE it writes, which captures the file's prior state.
+ * After the call, only noted files whose bytes changed are recorded. Scratch
+ * files outside the workspace (the system temp folder, the Office data
+ * folder) are never noted.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { PATCH_EDIT_BUDGET_BYTES, createSnapshotBudget, reviewFileContent } from '../../shared/bounded-file-read.mjs';
+
+const ledgers = new AsyncLocalStorage();
+
+const pathKey = (path) => (process.platform === 'win32' ? path.toLowerCase() : path);
+
+function inside(parent, child) {
+  if (!parent) return false;
+  const rel = relative(resolve(parent), child);
+  return !rel || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+function fileStamp(path) {
+  try {
+    const info = statSync(path);
+    return info.isFile() ? { size: info.size, mtimeMs: info.mtimeMs } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Run one Office call with a ledger its write routes report into. */
+export function runWithOfficeWriteLedger({ cwd, dataDir }, task) {
+  const ledger = {
+    cwd: resolve(cwd || process.cwd()),
+    dataDir: dataDir ? resolve(dataDir) : '',
+    budget: createSnapshotBudget(PATCH_EDIT_BUDGET_BYTES),
+    before: new Map(),
+  };
+  return { ledger, run: ledgers.run(ledger, task) };
+}
+
+/** A write receipt: the call is about to write `path`. The first receipt of a
+ *  path captures its state before the write; a call without a ledger (no
+ *  session to credit) and scratch paths are ignored. */
+export function noteOfficeWrite(path) {
+  const ledger = ledgers.getStore();
+  const text = typeof path === 'string' ? path.trim() : '';
+  if (!ledger || !text) return;
+  const fullPath = resolve(ledger.cwd, text);
+  const key = pathKey(fullPath);
+  if (ledger.before.has(key)) return;
+  if (inside(ledger.dataDir, fullPath)) return;
+  if (inside(tmpdir(), fullPath) && !inside(ledger.cwd, fullPath)) return;
+  let content;
+  try {
+    content = reviewFileContent(fullPath, { budget: ledger.budget });
+  } catch {
+    return; // not a regular file: never recorded
+  }
+  ledger.before.set(key, { fullPath, content, stamp: fileStamp(fullPath) });
+}
+
+const sameBytes = (left, right) => Buffer.isBuffer(left) && Buffer.isBuffer(right) && left.equals(right);
+
+/** Every noted file the call created, changed or removed, as
+ *  `{ fullPath, before, after }` (null = absent). */
+export function officeWriteChanges(ledger) {
+  const changes = [];
+  for (const { fullPath, content: before, stamp: priorStamp } of ledger.before.values()) {
+    const stamp = fileStamp(fullPath);
+    if (!priorStamp && !stamp) continue;
+    // Uncaptured bytes compare by their stamp; captured ones byte for byte.
+    const untouched = priorStamp && stamp && priorStamp.size === stamp.size && priorStamp.mtimeMs === stamp.mtimeMs;
+    if (untouched && !Buffer.isBuffer(before)) continue;
+    let after = null;
+    try {
+      after = stamp ? reviewFileContent(fullPath) : null;
+    } catch {
+      continue;
+    }
+    if (sameBytes(before, after)) continue;
+    changes.push({ fullPath, before, after });
+  }
+  return changes;
+}

package/src/runtime/office/index.mjs

@@ -14,6 +14,7 @@ import {
   toolResult,
 } from './core/office-core.mjs';
 import { resolveSession } from './core/office-sessions.mjs';
+import { officeWriteChanges, runWithOfficeWriteLedger } from './core/office-write-ledger.mjs';
 
 // Office work is minutes of real application time, and guessing which action carries it is how
 // tuning goes wrong. MIXDOG_OFFICE_TRACE writes one line per call so a slow run maps itself; it
@@ -27,6 +28,34 @@ const OFFICE_TRACE = process.env.MIXDOG_OFFICE_TRACE || '';
 const READ_ONLY_ACTIONS = new Set(['snapshot', 'get', 'query', 'issues', 'validate', 'describe', 'render', 'qa']);
 
 export async function executeOfficeTool(args = {}, context = {}) {
+  const sessionId = String(context.sessionId || '');
+  if (!sessionId) return await tracedOfficeTool(args, context);
+  const cwd = context.cwd || process.cwd();
+  const { ledger, run } = runWithOfficeWriteLedger({ cwd, dataDir: context.dataDir || defaultOfficeDataDir() }, () =>
+    tracedOfficeTool(args, context)
+  );
+  try {
+    return await run;
+  } finally {
+    await recordOfficeWrites(ledger, sessionId, cwd);
+  }
+}
+
+// The files this call's write routes reported join the session's turn review
+// as its own changes (counted, and undoable where their bytes were captured).
+// The recorder is loaded on first use; recording never affects the result.
+async function recordOfficeWrites(ledger, sessionId, cwd) {
+  try {
+    const changes = officeWriteChanges(ledger);
+    if (changes.length === 0) return;
+    const { recordToolFileChanges } = await import('../agent/orchestrator/tools/patch/ui-diff.mjs');
+    recordToolFileChanges({ sessionId, basePath: cwd, changes });
+  } catch {
+    /* best-effort review channel */
+  }
+}
+
+async function tracedOfficeTool(args, context) {
   if (!OFFICE_TRACE) return await runOfficeTool(args, context);
   const startedAt = performance.now();
   try {

package/src/runtime/office/pdf/pdf-analysis.mjs

@@ -261,74 +261,6 @@ export async function extractPdfTextLayout(
 // so the adapter, the tool surface, and tests keep one import.
 export { findPdfText } from './pdf-search.mjs';
 
-// The text run at `index`, joined with the next run on the same line when only
-// the joined text names a category (a label the PDF drew as two runs).
-function categoryLabelAt(items, index, expected) {
-  const item = items[index];
-  const text = String(item?.text || '').trim();
-  if (!text || expected.includes(text)) return text;
-  let nextIndex = index + 1;
-  while (nextIndex < items.length && !String(items[nextIndex]?.text || '').trim()) nextIndex += 1;
-  const next = items[nextIndex];
-  if (!next || Math.abs(Number(next.top) - Number(item.top)) > 1) return text;
-  const joined = `${text}${String(next.text || '').trim()}`;
-  return expected.includes(joined) ? joined : text;
-}
-
-// Every line that carries category labels, keyed by page and baseline.
-function categoryLabelRows(layout, expected) {
-  const rows = [];
-  for (const page of layout?.pages || []) {
-    const items = Array.isArray(page.items) ? page.items : [];
-    for (let index = 0; index < items.length; index += 1) {
-      const item = items[index];
-      const text = categoryLabelAt(items, index, expected);
-      if (!text || !expected.includes(text)) continue;
-      let row = rows.find((entry) => entry.page === page.page && Math.abs(entry.top - Number(item.top)) <= 1);
-      if (!row) {
-        row = { page: page.page, width: Number(page.width) || 0, top: Number(item.top), labels: [] };
-        rows.push(row);
-      }
-      if (!row.labels.some((entry) => entry.text === text)) {
-        row.labels.push({ text, x: Number(item.x) || 0 });
-      }
-    }
-  }
-  return rows;
-}
-
-function categoryRowSpacing(row, expected) {
-  const labels = expected
-    .map((text) => row.labels.find((entry) => entry.text === text))
-    .sort((left, right) => left.x - right.x);
-  const gaps = labels.slice(1).map((entry, index) => entry.x - labels[index].x);
-  return {
-    ...row,
-    labels,
-    span: labels.length > 1 ? labels.at(-1).x - labels[0].x : 0,
-    minimumGap: gaps.length ? Math.min(...gaps) : 0,
-  };
-}
-
-export function evaluatePowerPointCategorySpacing(layout, categories = []) {
-  const expected = [...new Set(categories.map((entry) => String(entry || '').trim()).filter(Boolean))];
-  const complete = categoryLabelRows(layout, expected)
-    .filter((row) => expected.every((text) => row.labels.some((entry) => entry.text === text)))
-    .map((row) => categoryRowSpacing(row, expected))
-    .sort((left, right) => right.span - left.span);
-  const best = complete[0] || null;
-  const requiredGap = best ? best.width * 0.1 : 0;
-  return {
-    ok: expected.length <= 1 || Boolean(best && best.minimumGap >= requiredGap),
-    categories: expected,
-    page: best?.page || 0,
-    labels: best?.labels || [],
-    span: Number((best?.span || 0).toFixed(2)),
-    minimumGap: Number((best?.minimumGap || 0).toFixed(2)),
-    requiredGap: Number(requiredGap.toFixed(2)),
-  };
-}
-
 // A PDF reports the runs it drew, not cells: a cell whose words were drawn as
 // separate runs would count as several columns and break its row against the
 // rows around it. Runs closer than half a line height are the same cell — the

package/src/runtime/office/pdf/pdf-edit-document.mjs

@@ -5,6 +5,7 @@
  */
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
+import { noteOfficeWrite } from '../core/office-write-ledger.mjs';
 import {
   PDFDocument,
   PDFArray,
@@ -130,6 +131,7 @@ export async function writeSibling(path, target, bytes) {
   if (output.toLowerCase() === resolve(path).toLowerCase())
     throw new Error('output must differ from the document being edited');
   await mkdir(dirname(output), { recursive: true });
+  noteOfficeWrite(output);
   await writeFile(output, bytes);
   return output;
 }

package/src/runtime/office/pdf/pdf-render.mjs

@@ -5,6 +5,7 @@ import { createCanvas, loadImage } from '@napi-rs/canvas';
 import { pdfjsStandardFontDataUrl, resolvedPdfJs } from '../../attachments/pdfjs-runtime.mjs';
 import { installPdfGlobals } from './pdf-document.mjs';
 import { workerExecArgv } from '../../shared/worker-exec-argv.mjs';
+import { noteOfficeWrite } from '../core/office-write-ledger.mjs';
 
 const PAGE_NUMBER_PATTERN = /^\s*(?:(?:page\s*)?\d+\s*(?:of|\/)\s*\d+|페이지\s*\d+|\d+\s*페이지)\s*$/i;
 
@@ -144,8 +145,8 @@ async function runPdfRenderWorker(data, signal = null) {
 }
 
 // Many pages are reviewed as contact sheets: one labelled grid image per group
-// of pages, written next to the PDF.
-async function writeContactSheet(group, width, imagePath, renderPage) {
+// of pages, for a file next to the PDF.
+async function contactSheet(group, width, imagePath, renderPage) {
   const columns = group.length <= 2 ? 1 : Math.max(2, Math.ceil(Math.sqrt(group.length * 0.75)));
   const rows = Math.ceil(group.length / columns);
   const gap = 12;
@@ -182,7 +183,6 @@ async function writeContactSheet(group, width, imagePath, renderPage) {
     context.strokeRect(x, y + labelHeight, image.width, image.height);
   }
   const data = sheet.toBuffer('image/png');
-  await writeFile(imagePath, data);
   return {
     page: group[0],
     pages: group,
@@ -204,7 +204,18 @@ async function writeContactSheet(group, width, imagePath, renderPage) {
   };
 }
 
-async function renderPdfPagesDirect(path, { pages = null, maxWidth = 1400, maximumScale = 2, signal = null } = {}) {
+// The page images land beside the PDF, each reported as an Office write first.
+async function writePageImages(images) {
+  for (const image of images) {
+    noteOfficeWrite(image.path);
+    await writeFile(image.path, Buffer.from(image.data, 'base64'));
+  }
+}
+
+async function renderPdfPagesDirect(
+  path,
+  { pages = null, maxWidth = 1400, maximumScale = 2, signal = null, writeImages = true } = {}
+) {
   if (signal?.aborted) throw new Error('PDF rendering was cancelled');
   installPdfGlobals();
   const { getDocument, VerbosityLevel } = await resolvedPdfJs();
@@ -248,7 +259,6 @@ async function renderPdfPagesDirect(path, { pages = null, maxWidth = 1400, maxim
       for (const pageNumber of selected) {
         const { canvas, data } = await renderPage(pageNumber, maxWidth);
         const imagePath = join(dirname(path), `${stem}-page-${pageNumber}.png`);
-        await writeFile(imagePath, data);
         output.push({
           page: pageNumber,
           path: imagePath,
@@ -264,9 +274,10 @@ async function renderPdfPagesDirect(path, { pages = null, maxWidth = 1400, maxim
       for (let offset = 0; offset < selected.length; offset += pagesPerSheet) {
         const group = selected.slice(offset, offset + pagesPerSheet);
         const imagePath = join(dirname(path), `${stem}-pages-${group[0]}-${group.at(-1)}.png`);
-        output.push(await writeContactSheet(group, width, imagePath, renderPage));
+        output.push(await contactSheet(group, width, imagePath, renderPage));
       }
     }
+    if (writeImages) await writePageImages(output);
     const reviewedPages = output.flatMap((image) => image.pages || [image.page]);
     const reviewedPageSet = new Set(reviewedPages);
     return {
@@ -293,7 +304,9 @@ export async function renderPdfPages(path, options = {}) {
   const signal = options.signal || null;
   if (signal?.aborted) throw new Error('PDF rendering was cancelled');
   if (!isMainThread) return await renderPdfPagesDirect(path, options);
-  return await runPdfRenderWorker(
+  // The worker rasterizes; this thread writes the images, where the call's
+  // write ledger can see each one before it lands.
+  const rendered = await runPdfRenderWorker(
     {
       kind: PDF_RENDER_WORKER_KIND,
       path,
@@ -301,10 +314,13 @@ export async function renderPdfPages(path, options = {}) {
         pages: options.pages ?? null,
         maxWidth: options.maxWidth ?? 1400,
         maximumScale: options.maximumScale ?? 2,
+        writeImages: false,
       },
     },
     signal
   );
+  await writePageImages(rendered.images);
+  return rendered;
 }
 
 if (!isMainThread && [PDF_RENDER_WORKER_KIND, PDF_RENDER_PAGE_WORKER_KIND].includes(workerData?.kind)) {

package/src/runtime/office/pdf/pdf-security.mjs

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { writeFile, rm, rename } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { noteOfficeWrite } from '../core/office-write-ledger.mjs';
 
 // qpdf on PATH, or wherever MIXDOG_QPDF_PATH points (the Windows installer
 // does not add itself to PATH).
@@ -89,6 +90,7 @@ export async function securePdf({ input, output, mode, password = '', ownerPassw
       ? ['--encrypt', password, ownerPassword || password, '256', '--', input, target]
       : [`--password=${password}`, '--decrypt', input, target];
   await writeFile(responsePath, `${args.join('\n')}\n`, { encoding: 'utf8', mode: 0o600 });
+  noteOfficeWrite(output);
   try {
     await run(QPDF, [`@${responsePath}`]);
     if (samePath) await rename(target, output);

package/src/runtime/office/portable/portable-opc.mjs

@@ -1,6 +1,7 @@
 import { posix } from 'node:path';
 import { createHash } from 'node:crypto';
 import { readFile, writeFile } from 'node:fs/promises';
+import { noteOfficeWrite } from '../core/office-write-ledger.mjs';
 import { koreanParticleReplacements } from '../shared/korean-particles.mjs';
 import { presetLabels } from '../shared/labels.mjs';
 import {
@@ -137,7 +138,9 @@ export async function packageBuffer(zip) {
 }
 
 export async function savePackage(zip, path) {
-  await writeFile(path, await packageBuffer(zip));
+  const bytes = await packageBuffer(zip);
+  noteOfficeWrite(path);
+  await writeFile(path, bytes);
 }
 
 export function relationshipMap(xml) {

package/src/runtime/office/quality/visual-diff.mjs

@@ -1,6 +1,7 @@
 import { writeFile } from 'node:fs/promises';
 import { dirname, extname, basename, join } from 'node:path';
 import { createCanvas, loadImage } from '@napi-rs/canvas';
+import { noteOfficeWrite } from '../core/office-write-ledger.mjs';
 
 function imageByPage(images) {
   return new Map((images || []).map((image) => [Number(image.page), image]));
@@ -61,6 +62,7 @@ export async function compareRenderedPages(beforeImages, afterImages, outputPdf)
     diffContext.putImageData(diff, 0, 0);
     const data = diffCanvas.toBuffer('image/png');
     const path = join(dirname(outputPdf), `${stem}-visual-diff-page-${page}.png`);
+    noteOfficeWrite(path);
     await writeFile(path, data);
     const total = width * height;
     metrics.push({

package/src/runtime/session-search/session-search-ingest.mjs

@@ -58,7 +58,7 @@ export async function forgetSessionSearch(sessionId) {
 
 async function loadStoreDeps() {
   const [{ getStoreDir }, { _storedSessionFromFile, STORED_SESSION_UNREADABLE }] = await Promise.all([
-    import('../agent/orchestrator/session/store/paths-heartbeat.mjs'),
+    import('../agent/orchestrator/session/store/session-paths.mjs'),
     import('../agent/orchestrator/session/store/serialize.mjs'),
   ]);
   return {

package/src/runtime/shared/agent-reap-state.mjs

@@ -3,6 +3,19 @@ import { positiveInt } from './numbers.mjs';
 
 export const TAG_TOMBSTONE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 
+// How long a finished agent (completed, failed or cancelled child, or a Lead
+// row) stays listed in the Agents pane, measured from its finish stamp. This is
+// pane visibility only: session reuse and cache reaping keep their own windows
+// (resolveAgentTerminalReapMs).
+export const AGENT_PANE_VISIBLE_MS = 60 * 60 * 1000;
+
+/** Whether a row finished at `finishedAtMs` is still inside the pane window.
+ *  Index rows are always stamped; a row with no usable stamp has no provable
+ *  age and stays listed rather than vanishing on a guess. */
+export function agentPaneVisible(finishedAtMs, now) {
+  return !(finishedAtMs > 0) || now - finishedAtMs < AGENT_PANE_VISIBLE_MS;
+}
+
 export function stampMs(value) {
   if (typeof value === 'number') return Number.isFinite(value) && value > 0 ? value : 0;
   const text = clean(value);

package/src/runtime/shared/atomic-file.d.mts

@@ -23,5 +23,5 @@ export function writeJsonAtomicAsync(
 export function withFileLock<T>(
   lockPath: string,
   task: () => T | Promise<T>,
-  options?: { timeoutMs?: number; staleMs?: number; secret?: boolean }
+  options?: { timeoutMs?: number; staleMs?: number; secret?: boolean; strictOwner?: boolean }
 ): Promise<T>;

package/src/runtime/shared/background-tasks.mjs

@@ -330,13 +330,18 @@ export function settleCancelledBackgroundTask(taskId, { result } = {}) {
 export function cancelBackgroundTasks(options = {}) {
   const reason = clean(options.reason) || 'cancelled';
   const wanted = clean(options.surface);
+  const executionSessionId = clean(options.executionSessionId);
   let cancelled = 0;
   for (const task of [...tasks.values()]) {
     if (wanted && task.surface !== wanted) continue;
     // Scoped teardown must be exact. Legacy tasks without ownership stay
     // visible/recoverable, but may not be claimed by whichever session happens
     // to close first.
-    if (!taskMatchesScope(task, options, { includeUnattributed: false })) continue;
+    if (executionSessionId) {
+      // Delegated work executes in its bound session; before binding it still
+      // belongs to the registering session. Notification ownership is separate.
+      if ((clean(task.meta?.sessionId) || task.ownerSessionId) !== executionSessionId) continue;
+    } else if (!taskMatchesScope(task, options, { includeUnattributed: false })) continue;
     if (TERMINAL_STATUSES.has(task.status)) {
       if (options.notify === false) silenceCancelledNotification(task);
       continue;

package/src/runtime/shared/bounded-file-read.mjs

@@ -156,6 +156,19 @@ export function readBoundedFile(
   }
 }
 
+/**
+ * A file's state for the turn review of a tool write: null when absent, its
+ * bytes (binary included) up to PATCH_EDIT_MAX_BYTES and within `budget`,
+ * otherwise an omitted marker — counted as changed, never diffed or restored.
+ * Throws ENOTREGULAR for anything but a regular file.
+ */
+export function reviewFileContent(path, { budget = null } = {}) {
+  const read = readBoundedFile(path, { maxBytes: PATCH_EDIT_MAX_BYTES, budget, detectBinary: false });
+  if (read.state === 'absent') return null;
+  if (read.state === 'omitted') return { omitted: true, size: read.size, reason: read.reason };
+  return read.content;
+}
+
 /** Human phrase for an omitted read: "binary (N bytes)", "larger than 8 MiB (N bytes)". */
 export function describeOmittedFile({ reason, size, limit } = {}) {
   const bytes = `${Number(size) || 0} bytes`;

package/src/runtime/shared/bounded-line-diff.mjs

@@ -0,0 +1,191 @@
+// In-process line diffs for the turn-change paths, bounded the way codex
+// bounds its own: every file gets a short timeout, every operation (one tool
+// call, one review or seal pass) a total budget. A file over the size limits,
+// past its timeout or past the spent budget gets one replacement hunk between
+// its common line prefix and suffix instead — still an exact patch that
+// applies, only not a minimal one. Results are cached by content, so the same
+// pair is not diffed again across calls and reviews.
+import { createHash } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { formatPatch, structuredPatch } from 'diff';
+
+/** Longest a single file's Myers diff may run (codex's per-file value). */
+export const LINE_DIFF_FILE_TIMEOUT_MS = 100;
+/** Total Myers diff time one operation may spend across its files. */
+// Kept well under the lag target: an operation also renders, hashes and
+// bounds its patches outside the diff itself.
+export const LINE_DIFF_OPERATION_BUDGET_MS = 150;
+// A side over either limit is never Myers-diffed.
+const LINE_DIFF_MAX_CHARS = 1024 * 1024;
+const LINE_DIFF_MAX_LINES = 20_000;
+const CONTEXT_LINES = 3;
+const CACHE_MAX_ENTRIES = 512;
+// Cached hunks reference their texts: bound the cache by their length.
+const CACHE_MAX_CHARS = 32 * 1024 * 1024;
+
+/** One operation's diff budget; pass it to every lineDiffHunks call of it. */
+export function createLineDiffBudget(totalMs = LINE_DIFF_OPERATION_BUDGET_MS) {
+  return { remainingMs: totalMs };
+}
+
+const _cache = new Map();
+let _cachedChars = 0;
+const _hashByBytes = new WeakMap();
+
+const sha1 = (value) => createHash('sha1').update(value).digest('hex');
+
+/** Content hash of one side: a byte array is hashed once per object. A text
+ *  hashes to the same id as its UTF-8 bytes; one that has no exact UTF-8 form
+ *  (a lone surrogate) gets no id. */
+function sideHash(source, text) {
+  if (source && typeof source === 'object') {
+    let hash = _hashByBytes.get(source);
+    if (!hash) {
+      hash = sha1(source);
+      _hashByBytes.set(source, hash);
+    }
+    return hash;
+  }
+  return text.isWellFormed() ? sha1(text) : null;
+}
+
+function cacheKey(sources, oldText, newText) {
+  const before = sideHash(sources[0], oldText);
+  const after = before && sideHash(sources[1], newText);
+  return after ? `${before}:${after}` : null;
+}
+
+function cacheGet(key) {
+  const entry = _cache.get(key);
+  if (!entry) return null;
+  _cache.delete(key);
+  _cache.set(key, entry);
+  return entry.result;
+}
+
+function cacheSet(key, result, chars) {
+  if (chars > CACHE_MAX_CHARS) return;
+  _cachedChars -= _cache.get(key)?.chars || 0;
+  _cache.delete(key);
+  _cache.set(key, { result, chars });
+  _cachedChars += chars;
+  while (_cache.size > CACHE_MAX_ENTRIES || _cachedChars > CACHE_MAX_CHARS) {
+    const [oldest, entry] = _cache.entries().next().value;
+    _cache.delete(oldest);
+    _cachedChars -= entry.chars;
+  }
+}
+
+function overLimits(text) {
+  if (text.length > LINE_DIFF_MAX_CHARS) return true;
+  let lines = 0;
+  for (let index = text.indexOf('\n'); index >= 0; index = text.indexOf('\n', index + 1)) {
+    lines += 1;
+    if (lines > LINE_DIFF_MAX_LINES) return true;
+  }
+  return false;
+}
+
+/** Lines with their `\n` (the last one may lack it), as jsdiff tokenizes. */
+function lineTokens(text) {
+  if (!text) return [];
+  const lines = text.split('\n');
+  const tokens = lines.map((line, index) => (index < lines.length - 1 ? `${line}\n` : line));
+  if (tokens.at(-1) === '') tokens.pop();
+  return tokens;
+}
+
+/** The one hunk replacing everything between the texts' common line prefix
+ *  and suffix, with up to three context lines each side, in jsdiff's hunk
+ *  shape (`` included). */
+function replacementHunks(oldText, newText) {
+  const before = lineTokens(oldText);
+  const after = lineTokens(newText);
+  const shortest = Math.min(before.length, after.length);
+  let start = 0;
+  while (start < shortest && before[start] === after[start]) start += 1;
+  let end = 0;
+  while (end < shortest - start && before[before.length - 1 - end] === after[after.length - 1 - end]) end += 1;
+  const lead = Math.min(CONTEXT_LINES, start);
+  const trail = Math.min(CONTEXT_LINES, end);
+  const lines = [];
+  const push = (mark, tokens) => {
+    for (const token of tokens) {
+      if (token.endsWith('\n')) lines.push(mark + token.slice(0, -1));
+      else lines.push(mark + token, '\');
+    }
+  };
+  push(' ', before.slice(start - lead, start));
+  push('-', before.slice(start, before.length - end));
+  push('+', after.slice(start, after.length - end));
+  push(' ', before.slice(before.length - end, before.length - end + trail));
+  const first = start - lead;
+  return [
+    {
+      oldStart: first + 1,
+      oldLines: before.length - end + trail - first,
+      newStart: first + 1,
+      newLines: after.length - end + trail - first,
+      lines,
+    },
+  ];
+}
+
+/**
+ * Hunks (context 3, jsdiff's structuredPatch shape) turning `oldText` into
+ * `newText`: jsdiff's own when its diff finishes within the file timeout and
+ * what is left of `budget` (`exact`), else the replacement hunk. `sources`
+ * are the raw sides the texts came from (bytes or the texts), used only as
+ * the cache key. The returned value is shared: never mutate it.
+ */
+export function lineDiffHunks(oldText, newText, budget, sources = [oldText, newText]) {
+  if (oldText === newText) return { hunks: [], exact: true };
+  const key = cacheKey(sources, oldText, newText);
+  const cached = key ? cacheGet(key) || budget.fallbacks?.get(key) : null;
+  if (cached) return cached;
+  let result = null;
+  // A fallback forced by the operation's spent budget is not this pair's own
+  // outcome: it is not cached, so a later operation can still diff it.
+  let repeatable = true;
+  if (!overLimits(oldText) && !overLimits(newText)) {
+    if (budget.remainingMs > 0) {
+      const timeout = Math.min(LINE_DIFF_FILE_TIMEOUT_MS, budget.remainingMs);
+      const startedAt = performance.now();
+      const patch = structuredPatch('', '', oldText, newText, '', '', { context: CONTEXT_LINES, timeout });
+      budget.remainingMs -= performance.now() - startedAt;
+      if (patch) result = { hunks: patch.hunks, exact: true };
+      else repeatable = timeout >= LINE_DIFF_FILE_TIMEOUT_MS;
+    } else {
+      repeatable = false;
+    }
+  }
+  result ||= { hunks: replacementHunks(oldText, newText), exact: false };
+  if (key && repeatable) cacheSet(key, result, oldText.length + newText.length);
+  // Within its own operation it is final: the budget never grows back.
+  else if (key) {
+    budget.fallbacks ||= new Map();
+    budget.fallbacks.set(key, result);
+  }
+  return result;
+}
+
+/** The `--- `/`+++ ` headers and hunks of `hunks`, as jsdiff formats them,
+ *  ending in exactly one newline. */
+export function unifiedHunksBody(oldHeader, newHeader, hunks) {
+  const generated = formatPatch({
+    oldFileName: oldHeader,
+    newFileName: newHeader,
+    oldHeader: '',
+    newHeader: '',
+    hunks,
+  });
+  let end = generated.length;
+  // Linear trim: a /\n*$/ regex rescans from every position of a large patch.
+  while (end > 0 && generated.charCodeAt(end - 1) === 10) end -= 1;
+  return `${generated.slice(generated.search(/^--- /m), end)}\n`;
+}
+
+export function _resetLineDiffCacheForTest() {
+  _cache.clear();
+  _cachedChars = 0;
+}

package/src/runtime/shared/browser-launch.mjs

@@ -88,3 +88,18 @@ export function buildPuppeteerLaunchArgs(extra = []) {
   if (puppeteerNoSandboxEnabled()) args.push('--no-sandbox');
   return args;
 }
+
+// A healthy headless launch answers in a few seconds; the observed CI failures
+// are launches that never print the DevTools endpoint and hit puppeteer's 30 s
+// TimeoutError (Windows runner, Linux runner). Puppeteer closes that child
+// itself, so one fresh attempt is the remedy; a longer wait would only delay
+// the same hang. Any other launch error (missing executable, bad args), or a
+// timeout after `signal` aborted, is not retried.
+export async function launchPuppeteerBrowser(puppeteer, options, { signal = null } = {}) {
+  try {
+    return await puppeteer.launch(options);
+  } catch (error) {
+    if (error?.name !== 'TimeoutError' || signal?.aborted) throw error;
+    return puppeteer.launch(options);
+  }
+}