mixdog 1.2.2 → 1.2.4

package/src/runtime/memory/lib/pg/run-child.mjs

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+
+/**
+ * Async child run with spawnSync's result shape ({ status, signal, stdout,
+ * stderr, error }) so the PG runtime's tar / initdb / pg_ctl steps never block
+ * the event loop of the process hosting them (the daemon serves every client
+ * from one loop). `timeoutMs` > 0 kills the child and reports ETIMEDOUT, like
+ * spawnSync's `timeout`. Never rejects.
+ */
+export function runChild(file, args, { timeoutMs = 0, ...options } = {}) {
+  return new Promise((resolve) => {
+    const stdout = [];
+    const stderr = [];
+    let settled = false;
+    let timer = null;
+    let error = null;
+    const finish = (status, signal) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve({ status, signal, stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr), error });
+    };
+    let child;
+    try {
+      child = spawn(file, args, { windowsHide: true, ...options, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (spawnError) {
+      error = spawnError;
+      finish(null, null);
+      return;
+    }
+    child.stdout?.on('data', (chunk) => stdout.push(chunk));
+    child.stderr?.on('data', (chunk) => stderr.push(chunk));
+    child.once('error', (childError) => {
+      error ??= childError;
+      finish(null, null);
+    });
+    // 'close' (not 'exit'): stdio is flushed, so captured output is complete.
+    child.once('close', (status, signal) => finish(status, signal));
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        error = Object.assign(new Error(`${file} timed out after ${timeoutMs}ms`), { code: 'ETIMEDOUT' });
+        try {
+          child.kill();
+        } catch {}
+        finish(null, 'SIGTERM');
+      }, timeoutMs);
+    }
+  });
+}

package/src/runtime/memory/lib/pg/supervisor.mjs

@@ -6,6 +6,9 @@ import { __mixdogMemoryLog } from '../memory-log.mjs';
  * Public API:
  *   ensurePgInstance(dataDir) → Promise<{ host, port, runtimeDir, pgdataDir }>
  *   stopPgForShutdown()       → Promise<void>  — call from server-main.mjs shutdown()
+ *   stopOwnedPgForShutdown()  → Promise<boolean> — a host stopping the cluster it ensured
+ *   installOwnedPgExitStop()  → void            — last-chance sync stop on process exit
+ *   pgClusterExists(dataDir)  → boolean         — initdb already ran for dataDir
  *
  * Uses process.mjs for startPg / stopPg / healthcheckPg (lazy-imported).
  *
@@ -17,7 +20,7 @@ import { __mixdogMemoryLog } from '../memory-log.mjs';
  */
 
 import { createServer } from 'node:net';
-import { unlinkSync, readFileSync, writeFileSync, renameSync, statSync, mkdirSync } from 'node:fs';
+import { existsSync, unlinkSync, readFileSync, writeFileSync, renameSync, statSync, mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import {
   discoveryPath as _pgDiscoveryPath,
@@ -51,6 +54,10 @@ let _live = null;
 let _ensureInFlight = null;
 /** Per-process flag — postgresql.conf reconcile attempted once per supervisor. */
 let _v2ReconcileTried = false;
+/** Set by stopOwnedPgForShutdown: this process is exiting, no further ensure. */
+let _ownedShutdownStarted = false;
+/** installOwnedPgExitStop registers its 'exit' hook once. */
+let _ownedExitStopInstalled = false;
 
 // ── Constants ────────────────────────────────────────────────────────────────
 const PG_PORT_MIN = 55432;
@@ -537,9 +544,20 @@ async function tryReusePgInstance({ pgdata, runtimeDir, healthcheckPg, source =
 
 // ── Internal: full ensure logic (runs exclusively via _ensureInFlight) ────────
 
+function _pgdataDir(dataDir) {
+  return join(dataDir, 'pgdata');
+}
+
+/** True once `dataDir` holds an initialized cluster (initdb ran). Before that
+ *  no store in it can hold rows, so a read may answer empty without starting
+ *  PostgreSQL — the first start downloads/extracts the runtime and runs initdb. */
+export function pgClusterExists(dataDir) {
+  return existsSync(join(_pgdataDir(dataDir), 'PG_VERSION'));
+}
+
 async function _doEnsure(dataDir) {
   const { healthcheckPg } = await _getPgProc();
-  const pgdata = join(dataDir, 'pgdata');
+  const pgdata = _pgdataDir(dataDir);
 
   // Resolve runtimeDir via runtime-fetcher (cache-hits immediately when already downloaded).
   const { ensureRuntime } = await import('../runtime-fetcher.mjs');
@@ -552,7 +570,7 @@ async function _doEnsure(dataDir) {
     _v2ReconcileTried = true;
     try {
       const { reconcileConfV2 } = await _getPgProc();
-      reconcileConfV2(runtimeDir, pgdata);
+      await reconcileConfV2(runtimeDir, pgdata);
     } catch (e) {
       __mixdogMemoryLog(`[supervisor-pg] reconcileConfV2 error (non-fatal): ${e?.message}\n`);
     }
@@ -699,6 +717,12 @@ async function _doEnsure(dataDir) {
  * @returns {Promise<{ host: string, port: number, runtimeDir: string, pgdataDir: string }>}
  */
 export function ensurePgInstance(dataDir) {
+  // Once this process began stopping the cluster it owns, nothing may start
+  // or re-attach one: a late connection-loss recovery would otherwise bring a
+  // postmaster back up right after the stop and leave it running past exit.
+  if (_ownedShutdownStarted) {
+    return Promise.reject(new Error('[supervisor-pg] process is shutting down; PG start refused'));
+  }
   // Every route to a live PG passes here — start, attach, reuse and the
   // in-process fast path — so this is the one place the sweep cannot be
   // skipped. Latched internally, so repeated calls schedule it only once.
@@ -804,5 +828,89 @@ export function stopPgForShutdownSync() {
   } catch {}
   // The postmaster is gone, so drop its advert too (same guarded clear as the
   // async path: never another live owner's); otherwise pg.json outlives the run.
-  patchActiveInstance({ pg_port: null, pg_started_at: null, pg_pgdata: null, pg_runtime_dir: null }, { timeoutMs: 1000 });
+  patchActiveInstance(
+    { pg_port: null, pg_started_at: null, pg_pgdata: null, pg_runtime_dir: null },
+    { timeoutMs: 1000 }
+  );
+}
+
+// ── Owned-cluster shutdown (a host that starts PG through its stores) ────────
+//
+// `pg_ctl start` daemonizes the postmaster outside the starting process tree,
+// so nothing ends it when that process exits: the process that brought a
+// cluster up (or adopted one whose owner died) owns stopping it. Unlike
+// stopPgForShutdown above, these never act on a cluster this process did not
+// ensure, and never on one a different live process owns (pg_owner_pid) —
+// that owner stops it on its own exit.
+
+/** `_live` cluster's advert is held by another live process. */
+function _liveClusterForeignOwned(snap) {
+  let advert = null;
+  try {
+    advert = _readPgAdvert();
+  } catch {}
+  if (!advert?.pg_pgdata || resolve(advert.pg_pgdata) !== resolve(snap.pgdata)) return false;
+  return _pgAdvertIsForeignLive(advert);
+}
+
+/**
+ * Graceful, bounded stop (`pg_ctl stop -m fast`) of the cluster this process
+ * ensured. Latches the process into shutdown first, so no later ensure can
+ * start another one. Resolves true when a cluster was stopped; rejects when
+ * pg_ctl failed (the 'exit' hook then retries synchronously).
+ */
+export async function stopOwnedPgForShutdown({ timeoutMs = 6_000 } = {}) {
+  _ownedShutdownStarted = true;
+  // A start still under way (pg_ctl start already spawned, readiness pending)
+  // publishes its cluster only when it settles; stopping before that would
+  // miss the postmaster it is about to own. Bounded: a cold first start can
+  // be a download.
+  if (_ensureInFlight) {
+    let timer = null;
+    await Promise.race([
+      _ensureInFlight.catch(() => {}),
+      new Promise((resolveWait) => {
+        timer = setTimeout(resolveWait, timeoutMs);
+        timer.unref?.();
+      }),
+    ]);
+    clearTimeout(timer);
+  }
+  const snap = _live;
+  if (!snap) return false;
+  if (_liveClusterForeignOwned(snap)) {
+    __mixdogMemoryLog(`[supervisor-pg] PG on port ${snap.port} is owned by another live process; leaving it running\n`);
+    _live = null;
+    return false;
+  }
+  const { stopPg } = await _getPgProc();
+  await stopPg({ runtimeDir: snap.runtimeDir, pgdataDir: snap.pgdata, timeoutMs });
+  _live = null;
+  __mixdogMemoryLog(`[supervisor-pg] owned PG on port ${snap.port} stopped on shutdown\n`);
+  patchActiveInstance(
+    { pg_port: null, pg_started_at: null, pg_pgdata: null, pg_runtime_dir: null },
+    { timeoutMs: 2000, syncRetries: 1 }
+  );
+  return true;
+}
+
+/** Last-chance synchronous stop for a process 'exit' hook: acts only while the
+ *  cluster this process ensured is still recorded as live (an exit the async
+ *  stop never reached, or one where it failed). */
+export function stopOwnedPgForShutdownSync() {
+  if (!_live) return;
+  stopPgForShutdownSync();
+  _live = null;
+}
+
+/** Register stopOwnedPgForShutdownSync on process 'exit', once. Cheap when this
+ *  process never ensures a cluster: the hook is then a no-op. */
+export function installOwnedPgExitStop() {
+  if (_ownedExitStopInstalled) return;
+  _ownedExitStopInstalled = true;
+  process.on('exit', () => {
+    try {
+      stopOwnedPgForShutdownSync();
+    } catch {}
+  });
 }

package/src/runtime/memory/lib/runtime-fetcher.mjs

@@ -32,7 +32,7 @@ import {
 } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
+import { runChild } from './pg/run-child.mjs';
 import { renameWithRetrySync, writeFileAtomicSync, writeJsonAtomicSync } from '../../shared/atomic-file.mjs';
 import { downloadToFileWithRetry } from '../../shared/bounded-download.mjs';
 import { platformKey, platformKeyCandidates, verifySha256File } from '../../shared/native-asset.mjs';
@@ -250,21 +250,23 @@ export function _validateRuntimeTarEntries(entries, details, stagingBase) {
   }
 }
 
-export function _extractRuntimeTarGz(tarPath, destDir, stagingBase) {
+// Async throughout: the first boot extracts the whole PG runtime here, and a
+// synchronous tar froze the daemon loop for seconds.
+export async function _extractRuntimeTarGz(tarPath, destDir, stagingBase) {
   mkdirSync(destDir, { recursive: true });
   const resolvedTarPath = resolve(tarPath);
-  const tarOptions = { cwd: dirname(resolvedTarPath), stdio: 'pipe', windowsHide: true };
+  const tarOptions = { cwd: dirname(resolvedTarPath) };
   const tarName = basename(resolvedTarPath);
 
   // List entries first and validate — reject traversal, external links, and
   // special files before the extractor can materialize archive content.
   // Keep the archive argument relative to cwd: GNU tar otherwise interprets
   // an absolute Windows path such as C:\runtime.tar.gz as a remote host path.
-  const listResult = spawnSync('tar', ['-tzf', tarName], tarOptions);
+  const listResult = await runChild('tar', ['-tzf', tarName], tarOptions);
   if (listResult.status !== 0) {
     throw new Error(`[runtime-fetcher] tar list failed: ${listResult.stderr?.toString() || 'unknown'}`);
   }
-  const detailResult = spawnSync('tar', ['-tvzf', tarName], tarOptions);
+  const detailResult = await runChild('tar', ['-tvzf', tarName], tarOptions);
   if (detailResult.status !== 0) {
     throw new Error(`[runtime-fetcher] tar detail list failed: ${detailResult.stderr?.toString() || 'unknown'}`);
   }
@@ -274,10 +276,7 @@ export function _extractRuntimeTarGz(tarPath, destDir, stagingBase) {
 
   const resolvedDestDir = resolve(destDir);
   const extractionArchive = relative(resolvedDestDir, resolvedTarPath);
-  const r = spawnSync('tar', ['-xzf', extractionArchive], {
-    ...tarOptions,
-    cwd: resolvedDestDir,
-  });
+  const r = await runChild('tar', ['-xzf', extractionArchive], { cwd: resolvedDestDir });
   if (r.status !== 0) {
     throw new Error(`[runtime-fetcher] tar extraction failed: ${r.stderr?.toString() || 'unknown error'}`);
   }
@@ -438,9 +437,9 @@ const runtimeCache = new Map();
 
 // One-shot tar availability probe; result cached after first call.
 let _tarProbed = false;
-function probeTar() {
+async function probeTar() {
   if (_tarProbed) return;
-  const r = spawnSync('tar', ['--version'], { stdio: 'pipe', windowsHide: true });
+  const r = await runChild('tar', ['--version']);
   if (r.status !== 0 || r.error) {
     throw new Error(
       '[runtime-fetcher] `tar` not found or not executable. ' +
@@ -532,7 +531,7 @@ async function installRuntimeVersion({ runtimeBaseDir, url, sha256, size, versio
   // tar is only required for the download/extract path. Probe here (not at
   // ensureRuntime entry) so a machine without tar can still reuse an
   // already-extracted, sha-matching cached runtime via the fast path.
-  probeTar();
+  await probeTar();
 
   __mixdogMemoryLog(`[runtime-fetcher] downloading runtime ${version} for ${pkey} (~${size} bytes) …\n`);
 
@@ -574,7 +573,7 @@ async function installRuntimeVersion({ runtimeBaseDir, url, sha256, size, versio
         }
       }
       if (!downloadOk && lastDownloadErr) throw lastDownloadErr;
-      _extractRuntimeTarGz(tarPath, stagingDir, stagingDir);
+      await _extractRuntimeTarGz(tarPath, stagingDir, stagingDir);
     } finally {
       try {
         rmSync(tarPath, { force: true });

package/src/runtime/memory/lib/transcript-ingest.mjs

@@ -53,7 +53,21 @@ export function createTranscriptIngest({
     return run;
   }
 
+  /** A deleted session's transcripts: wait out any ingest of each file, then
+   *  drop its persisted read position. Returns the number of entries removed. */
+  async function forgetTranscripts(transcriptPaths) {
+    let removed = 0;
+    for (const transcriptPath of transcriptPaths) {
+      const resolved = path.resolve(transcriptPath);
+      await tails.get(resolved);
+      for (const key of new Set([transcriptPath, resolved])) if (offsets.forget(key)) removed += 1;
+    }
+    if (removed > 0) await offsets.persist();
+    return removed;
+  }
+
   return {
+    forgetTranscripts,
     loadTranscriptOffsets: offsets.load,
     persistTranscriptOffsets: offsets.persist,
     ingestTranscriptFile,

package/src/runtime/office/README.md

@@ -10,7 +10,7 @@ Microsoft Office installed.
 | --- | --- |
 | `(root)` | Public surface only: `index.mjs` (tool executor), `tool-defs.mjs`, `capabilities.mjs`. Test suites and `office-test-support.mjs` also live here. |
 | `authoring/` | The `author` action — the only way a deck is made: `pptx-script-contract.mjs` (what a script may require and how long it may run; the model-facing guide is the built-in `pptx` skill in `src/defaults/skills/pptx`), `pptx-script-runner.mjs` (runs a pptxgenjs script in-process with a scoped `require`, injecting `MEASURE` and `ICON`), `pptx-script-normalize.mjs` (paragraph properties, hanging punctuation, accent-series merge), `pptx-html-runner.mjs` + `pptx-html-measure.mjs` + `pptx-html-build.mjs` (the HTML input: a local Chrome/Edge lays the slides out, the measurement becomes native text boxes, shapes, tables, charts, and pictures, and the browser's pages are kept for the HTML-beside-PPTX comparison), `pptx-author-action.mjs` (writes the deck, opens an `authored` session, renders, returns the composition receipt and contact sheet), `pptx-receipt.mjs`, `pptx-contact-sheet.mjs`, `pptx-icons.mjs` + `pptx-icons.json` (offline Lucide subset built by `npm run office:icons`), `pptx-brief.mjs`. Sits beside the root and imports `core`. |
-| `core/` | Sessions, transactions, journal, snapshot pagination, tabular sessions, and the action pipeline (`office-actions-*.mjs`). |
+| `core/` | Sessions, transactions, journal, snapshot pagination, tabular sessions, the action pipeline (`office-actions-*.mjs`), and the write ledger (`office-write-ledger.mjs`: every route that writes a workspace file reports it with `noteOfficeWrite` before writing; `index.mjs` records the reported files that changed in the session's turn review as its own changes). |
 | `com/` | Windows-native path: `com-adapter.mjs` plus the PowerShell hosts `office-com-host.ps1` and `office-com-session-host.ps1`. |
 | `portable/` | OOXML read/write without Office, package validation, XLSX contracts, the backend-neutral XLSX audits shared by portable `issues`, Excel's `issues` merge, and the quality review (`xlsx-audit-support.mjs` cell reading and the capped issue list, `xlsx-sheet-hygiene.mjs` every-profile hygiene and layout information, `xlsx-formula-audit.mjs` the financial-model discipline and the orchestration), the workbook conventions summary a snapshot carries (`xlsx-conventions.mjs`), LibreOffice recalculation with its error summary (`portable-soffice.mjs` holds one private user profile for the life of the process, runs conversions one at a time behind it, and drops the profile after a failed run; `xlsx-recalculate.mjs` asks LibreOffice first and falls back to `xlsx-formula-engine.mjs`, which evaluates the formulas in this process and refuses — never guesses — the ones it cannot read; `portable-shared-formulas.mjs` gives every cell a shared or array formula covers the formula it actually holds, so a filled-down column is never read as pasted numbers), the sheet content audits (`portable-sheet-audits.mjs`: percent scale, column fit, protected inputs, unreadable ink, a hardcode inside a row of formulas), the leftover scan (`placeholder-scan.mjs`: template wording and tools' citation markers, read on slides, a document's body, headers and footers, and PDF pages), `convertLegacyOffice` in `portable-soffice.mjs` (a `.doc`/`.xls`/`.ppt` saved once as its package beside the original when `open` meets one), text and image metrics. |
 | `pdf/` | `pdf-adapter.mjs` (session surface: snapshot, batch — including the marks `highlight`, `add_link`, `preview_fields` — validate, issues; re-exports `createPdf`), `pdf-writer.mjs` (blocks → pages, tables, page numbers), `pdf-forms.mjs` (field lint, add, describe, fill), `pdf-draw.mjs` (colors, page sizes, wrapping, images), `pdf-fonts.mjs` (system Unicode font fallback shared by create, marks, forms, and OCR), `pdf-analysis.mjs` (text layout with rules, boxes, and links, ruled and aligned tables, images, OCR), `pdf-search.mjs` (text search over a layout: lines from runs, glyph-width placement, whole words), `pdf-safety.mjs` (active-content report: JavaScript, Launch, non-web links), `pdf-render.mjs`, `pdf-security.mjs` (qpdf), `document-preview.mjs`. |

package/src/runtime/office/authoring/docx-html-runner.mjs

@@ -39,7 +39,7 @@ export async function runDocxHtmlAuthoring(html, output, { target, signal = null
   const scratch = await mkdtemp(join(tmpdir(), 'mixdog-docx-captures-'));
   let browser;
   try {
-    browser = await launchHtmlBrowser('docx-html-browser');
+    browser = await launchHtmlBrowser('docx-html-browser', { signal });
   } catch (error) {
     await rm(scratch, { recursive: true, force: true }).catch(() => {});
     return htmlFailure(error, startedAt);

package/src/runtime/office/authoring/html-browser.mjs

@@ -2,17 +2,25 @@
 // deadline and abort wiring around the layout work, the failure result, and the photographs of captured elements.
 import { join } from 'node:path';
 
-import { buildPuppeteerLaunchArgs, resolveBrowserLaunchOptions } from '../../shared/browser-launch.mjs';
+import {
+  buildPuppeteerLaunchArgs,
+  launchPuppeteerBrowser,
+  resolveBrowserLaunchOptions,
+} from '../../shared/browser-launch.mjs';
 import { startChildGuardian } from '../../shared/child-guardian.mjs';
 
 /** Launches the local browser the HTML is laid out in, under a guardian that reaps it with this process. */
-export async function launchHtmlBrowser(label) {
+export async function launchHtmlBrowser(label, { signal = null } = {}) {
   const puppeteer = (await import('puppeteer-core')).default;
-  const browser = await puppeteer.launch({
-    headless: true,
-    ...resolveBrowserLaunchOptions(),
-    args: buildPuppeteerLaunchArgs(['--font-render-hinting=none']),
-  });
+  const browser = await launchPuppeteerBrowser(
+    puppeteer,
+    {
+      headless: true,
+      ...resolveBrowserLaunchOptions(),
+      args: buildPuppeteerLaunchArgs(['--font-render-hinting=none']),
+    },
+    { signal }
+  );
   try {
     startChildGuardian({ childPid: browser.process?.()?.pid, label });
   } catch {}
@@ -22,7 +30,9 @@ export async function launchHtmlBrowser(label) {
 /** Runs `work` against the browser under a deadline and an abort signal, and closes the browser afterwards. */
 export async function runInBrowser(browser, { signal, timeoutMs }, work) {
   const abort = () => browser.close().catch(() => {});
-  signal?.addEventListener('abort', abort, { once: true });
+  // A cancel that landed while the browser was launching closes it at once.
+  if (signal?.aborted) abort();
+  else signal?.addEventListener('abort', abort, { once: true });
   let timer = null;
   const running = work();
   const timeout = new Promise((_, reject) => {

package/src/runtime/office/authoring/html-document-author.mjs

@@ -8,6 +8,7 @@ import { render } from '../core/office-actions.mjs';
 import { documentFormat, officeSessionForDocument } from '../core/office-core.mjs';
 import { createAuthoredSession, exists, fullPath, validatePptxAuthorMode } from '../core/office-sessions.mjs';
 import { inlineOfficeAudit } from '../quality/inline-audit.mjs';
+import { noteOfficeWrite } from '../core/office-write-ledger.mjs';
 import { parseAuthoringBrief } from './pptx-brief.mjs';
 import { htmlBriefScript } from './pptx-html-runner.mjs';
 import {
@@ -68,6 +69,7 @@ async function writeComparisons(target, htmlPages, officePages) {
       (await scaled(officePages.find((image) => image.page === page && (image.pages?.length || 1) === 1))) ||
       (await blank(left.width));
     const path = `${target}.mixdog-compare-page-${page}.png`;
+    noteOfficeWrite(path);
     await sharp({ create: { width: left.width + right.width + gap, height, channels: 3, background: '#808080' } })
       .composite([
         { input: left.data, left: 0, top: 0 },

package/src/runtime/office/authoring/pdf-html-runner.mjs

@@ -262,7 +262,7 @@ export async function printHtmlPdf(
   await rm(output, { force: true });
   let browser;
   try {
-    browser = await launchHtmlBrowser('pdf-html-browser');
+    browser = await launchHtmlBrowser('pdf-html-browser', { signal });
   } catch (error) {
     return htmlFailure(error, startedAt);
   }

package/src/runtime/office/authoring/pptx-contact-sheet.mjs

@@ -7,6 +7,7 @@
 import { writeFile } from 'node:fs/promises';
 import { basename, dirname, extname, join } from 'node:path';
 import { createCanvas, loadImage } from '@napi-rs/canvas';
+import { noteOfficeWrite } from '../core/office-write-ledger.mjs';
 
 function pageImages(images = []) {
   const pages = [];
@@ -51,6 +52,7 @@ export async function writeContactSheet(images, output, { width = 1600 } = {}) {
   const data = sheet.toBuffer('image/png');
   const stem = basename(output, extname(output));
   const path = join(dirname(output), `${stem}.mixdog-contact.png`);
+  noteOfficeWrite(path);
   await writeFile(path, data);
   return {
     path,

package/src/runtime/office/authoring/pptx-html-measure.mjs

@@ -9,6 +9,7 @@ import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
 
 import { launchHtmlBrowser, runInBrowser } from './html-browser.mjs';
+import { noteOfficeWrite } from '../core/office-write-ledger.mjs';
 import { iconGlobal } from './pptx-icons.mjs';
 import { GEOMETRY_TOLERANCE_PX, NEAR_MISS_PX, readGeometry } from './pptx-html-geometry.mjs';
 
@@ -558,7 +559,7 @@ export async function measureHtmlDeck(
   { sourcePath, shotPath, timeoutMs = 90_000, signal = null, prepare = null }
 ) {
   await writeFile(sourcePath, html, 'utf8');
-  const browser = await launchHtmlBrowser('pptx-html-browser');
+  const browser = await launchHtmlBrowser('pptx-html-browser', { signal });
   const work = async () => {
     const page = await browser.newPage();
     await page.setViewport(viewport(HTML_CANVAS, 1));
@@ -598,6 +599,7 @@ export async function measureHtmlDeck(
         );
       }
       const shot = shotPath(index + 1);
+      noteOfficeWrite(shot);
       await element.screenshot({ path: shot });
       shots.push(shot);
       const measured = await page.evaluate(extractSlide, index);

package/src/runtime/office/authoring/pptx-html-runner.mjs

@@ -6,6 +6,7 @@ import { dirname } from 'node:path';
 import { createRequire } from 'node:module';
 
 import { HTML_CANVAS, measureHtmlDeck } from './pptx-html-measure.mjs';
+import { noteOfficeWrite } from '../core/office-write-ledger.mjs';
 import { buildPptxFromMeasure } from './pptx-html-build.mjs';
 import { normalizeAuthoredPptx } from './pptx-script-normalize.mjs';
 
@@ -312,6 +313,7 @@ export async function writeHtmlComparisons(target, htmlShots, renderedImages) {
     const left = await sharp(html).resize(width, height, { fit: 'fill' }).png().toBuffer();
     const right = await sharp(image.path).resize(width, height, { fit: 'fill' }).png().toBuffer();
     const path = artifacts.compare(image.page);
+    noteOfficeWrite(path);
     await sharp({ create: { width: width * 2 + gap, height, channels: 3, background: '#808080' } })
       .composite([
         { input: left, left: 0, top: 0 },

package/src/runtime/office/authoring/xlsx-html-runner.mjs

@@ -6,6 +6,7 @@ import { dirname, join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 import { htmlFailure, launchHtmlBrowser, photographCaptures, runInBrowser } from './html-browser.mjs';
+import { noteOfficeWrite } from '../core/office-write-ledger.mjs';
 import { iconTable, injectIcons } from './pptx-html-measure.mjs';
 import { extractXlsxSheets } from './xlsx-html-measure.mjs';
 import { drawDataCharts } from './pdf-html-charts.mjs';
@@ -65,7 +66,7 @@ export async function runXlsxHtmlAuthoring(html, output, { target, signal = null
   const scratch = await mkdtemp(join(tmpdir(), 'mixdog-xlsx-captures-'));
   let browser;
   try {
-    browser = await launchHtmlBrowser('xlsx-html-browser');
+    browser = await launchHtmlBrowser('xlsx-html-browser', { signal });
   } catch (error) {
     await rm(scratch, { recursive: true, force: true }).catch(() => {});
     return htmlFailure(error, startedAt);
@@ -106,6 +107,7 @@ export async function runXlsxHtmlAuthoring(html, output, { target, signal = null
     const htmlPages = [];
     for (const [index, clip] of extents.entries()) {
       const path = artifacts.shot(index + 1);
+      noteOfficeWrite(path);
       await page.screenshot({ path, clip, captureBeyondViewport: true });
       htmlPages.push({ page: index + 1, path });
     }

package/src/runtime/office/core/office-actions-read.mjs

@@ -2,6 +2,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { extractPdfImages, extractPdfTextLayout, findPdfText, inferPdfTables } from '../pdf/pdf-analysis.mjs';
 import { findByDocumentPath, fullPath, queryObject, snapshot, snapshotSelectionForTarget } from './office-sessions.mjs';
+import { noteOfficeWrite } from './office-write-ledger.mjs';
 
 /** RFC 4180 quoting so a table cell that contains a comma or quote round-trips. */
 export function csvCell(text) {
@@ -94,6 +95,7 @@ async function queryPdfTables(session, args, cwd, signal) {
       const ordinal = (counters.get(table.page) || 0) + 1;
       counters.set(table.page, ordinal);
       const file = join(directory, `page-${table.page}-table-${ordinal}.csv`);
+      noteOfficeWrite(file);
       await writeFile(
         file,
         `${table.rows.map((row) => row.map((cell) => csvCell(String(cell ?? ''))).join(',')).join('\r\n')}\r\n`,
@@ -115,6 +117,7 @@ async function queryPdfImages(session, args, cwd, signal) {
     const written = [];
     for (const image of extracted._images) {
       const file = join(directory, `page-${image.page}-image-${image.index}.png`);
+      noteOfficeWrite(file);
       await writeFile(file, Buffer.from(image.data, 'base64'));
       written.push(file);
     }

package/src/runtime/office/core/office-render-preview.mjs

@@ -8,6 +8,7 @@ import { resolveOfficeRenderOutput } from '../quality/quality-pipeline.mjs';
 import { defaultRenderOutput, exists, fullPath } from './office-sessions.mjs';
 import { completePageCoverage, pptxPageSignatures, reusablePptxPages } from './pptx-page-cache.mjs';
 import { numberDocxTableOfContents } from './docx-toc-pages.mjs';
+import { noteOfficeWrite } from './office-write-ledger.mjs';
 
 function request(session, args, cwd) {
   return {
@@ -136,6 +137,7 @@ export async function renderOfficePreview(
   const exportKey = `${session.target}\0${Number(session.snapshotVersion || 0)}\0${requested.output}`;
   if (!incremental || session.previewExportKey !== exportKey || !(await exists(requested.output))) {
     session.previewExportKey = null;
+    noteOfficeWrite(requested.output);
     await exportPreview(session, requested.output);
     if (incremental) session.previewExportKey = exportKey;
   }

package/src/runtime/office/core/office-session-dispatch.mjs

@@ -9,6 +9,7 @@ import { describeOfficeCapabilities } from '../capabilities.mjs';
 import { applyBatch, closeSession, finalize, issues, qa, render, save, validate } from './office-actions.mjs';
 import { getOfficeElement, queryOfficeDocument } from './office-actions-read.mjs';
 import { snapshot } from './office-sessions.mjs';
+import { noteOfficeWrite } from './office-write-ledger.mjs';
 import { noteBatchAgainstHtml } from '../authoring/html-source-drift.mjs';
 import {
   assertTransactionUnchanged,
@@ -59,7 +60,13 @@ async function batchAction(session, args, cwd, signal) {
   };
 }
 
+// Verbs that never write the session's document.
+const READ_ACTIONS = new Set(['describe', 'begin', 'diff', 'snapshot', 'get', 'query', 'issues', 'validate']);
+
 export async function dispatchOfficeSessionAction({ action, session, args, cwd, signal }) {
+  // Write receipt: every other verb may write the session's document (an
+  // edit, save, rollback, autoFix, or a render that numbers its contents).
+  if (!READ_ACTIONS.has(action)) noteOfficeWrite(session.target);
   if (action === 'describe') {
     return describeOfficeCapabilities({
       format: session.format,

package/src/runtime/office/core/office-sessionless-actions.mjs

@@ -29,6 +29,7 @@ import {
   toolResult,
 } from './office-core.mjs';
 import { fullPath, selectMode } from './office-sessions.mjs';
+import { noteOfficeWrite } from './office-write-ledger.mjs';
 import { pendingOfficeTransactions, recoverOfficeTransaction } from './office-transactions.mjs';
 
 async function detectAction(args, cwd, dataDir) {
@@ -102,6 +103,13 @@ async function authorAction(args, cwd, dataDir, signal, startedAt) {
   const extension = extname(String(args.path || args.output || '')).toLowerCase();
   const author =
     { '.pdf': authorPdf, '.docx': authorHtmlDocument, '.xlsx': authorHtmlDocument }[extension] || authorPptx;
+  // Write receipts: the authored document and the sidecars kept beside it
+  // (its HTML source and print); per-page images report themselves.
+  for (const value of [args.path, args.output]) {
+    if (!String(value || '').trim()) continue;
+    const target = fullPath(String(value).trim(), cwd);
+    for (const path of [target, `${target}.mixdog-source.html`, `${target}.mixdog-html.pdf`]) noteOfficeWrite(path);
+  }
   const authored = await author(args, { cwd, dataDir, signal });
   const images = Array.isArray(authored?._images) ? authored._images : [];
   delete authored._images;

package/src/runtime/office/core/office-sessions.mjs

@@ -4,6 +4,7 @@ import { basename, dirname, extname, isAbsolute, join, resolve } from 'node:path
 import { tmpdir } from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { assertOfficeOperationContracts } from '../capabilities.mjs';
+import { noteOfficeWrite } from './office-write-ledger.mjs';
 import {
   callMicrosoftOffice,
   detectMicrosoftOffice,
@@ -258,6 +259,7 @@ async function packageSource(path, signal) {
       `${path} is a legacy binary file and ${converted} already exists; open ${converted} directly, or move it aside to convert again.`
     );
   }
+  noteOfficeWrite(converted);
   await convertLegacyOffice(path, converted, { signal });
   return { source: converted, convertedFrom: path };
 }
@@ -280,6 +282,7 @@ export async function openSession(args, cwd, dataDir, { readOnly = false } = {})
   if (existing) return existing;
   if (copies) {
     await mkdir(dirname(target), { recursive: true });
+    noteOfficeWrite(target);
     await copyFile(source, target);
   }
   const designContext = await resolveOfficeDesignContext({
@@ -533,6 +536,7 @@ export async function createSession(args, cwd, dataDir) {
   // Whether this call brings the file into being decides what a failed create
   // may clean up afterwards: a file it wrote itself, never one already there.
   const targetExisted = await exists(target);
+  noteOfficeWrite(target);
   const designContext = await resolveOfficeDesignContext({ args, dataDir, target, format, created: true });
   const creation = { target, fileKind, format, dataDir, targetExisted, designContext };
   await releaseOverwrittenSession(target, args.overwrite);
@@ -645,6 +649,7 @@ export async function materializeWorkingCopy(session) {
     throw new Error('portable editing requires an output path different from the source');
   }
   await mkdir(dirname(target), { recursive: true });
+  noteOfficeWrite(target);
   await copyFile(session.source, target);
   if (documentSessions.get(documentSessionKey(session.target)) === session.id) {
     documentSessions.delete(documentSessionKey(session.target));

package/src/runtime/office/core/office-transactions.mjs

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { callMicrosoftOffice, detectMicrosoftOffice, openMicrosoftOfficeSession } from '../com/com-adapter.mjs';
 import { listOfficeJournals, readOfficeJournal, removeOfficeJournal, writeOfficeJournal } from './journal.mjs';
+import { noteOfficeWrite } from './office-write-ledger.mjs';
 import {
   OfficeConflictError,
   documentFingerprint,
@@ -299,6 +300,8 @@ export async function rollbackTransaction(session) {
   transaction.diff = transactionDocumentDiff(transaction, current.document);
   transaction.phase = 'rolling_back';
   await persistOfficeTransaction(session);
+  // A recovered rollback restores the document outside any session verb.
+  noteOfficeWrite(session.target);
   if (isMicrosoftOfficeSession(session)) {
     const result = await callMicrosoftOffice(
       {