mixdog 1.3.1 → 1.3.2

package/src/runtime/attachments/pdf-extract.mjs

@@ -5,19 +5,18 @@
  * OpenAI-compatible providers without a document contract receive page-ordered
  * text extracted here, so they never see an unsupported inline Base64 block.
  */
+import { stripTrailingReplacementChars } from '../shared/utf8-cut.mjs';
 import { MAX_PDF_PAGES } from './limits.mjs';
 import { resolvedPdfJs } from './pdfjs-runtime.mjs';
 
 const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
 
-function boundedUtf8(value, maxBytes) {
+/** `value` cut to at most `maxBytes` of UTF-8, never inside a multi-byte sequence. */
+export function boundedUtf8(value, maxBytes) {
   const buffer = Buffer.from(String(value || ''), 'utf8');
   if (buffer.length <= maxBytes) return { text: buffer.toString('utf8'), bytes: buffer.length, truncated: false };
   if (maxBytes <= 0) return { text: '', bytes: 0, truncated: true };
-  const text = buffer
-    .subarray(0, maxBytes)
-    .toString('utf8')
-    .replace(/\uFFFD+$/g, '');
+  const text = stripTrailingReplacementChars(buffer.subarray(0, maxBytes).toString('utf8'));
   return { text, bytes: Buffer.byteLength(text, 'utf8'), truncated: true };
 }
 
@@ -74,38 +73,90 @@ function pageBodyText(content) {
     .trim();
 }
 
-export async function inspectPdfBuffer(
+/** The deadline prompt intake passes: it runs inside a room's post queue, which
+ *  a document that never loads would otherwise hold forever. */
+export const PDF_INTAKE_TIMEOUT_MS = 60_000;
+
+// A page counts as carrying a text layer when its extracted text holds at
+// least this many non-whitespace characters. A scan often keeps a stamped page
+// number or a few stray glyphs; those alone do not make its content readable
+// as text, so such a page still needs its image (or OCR).
+export const PDF_TEXT_LAYER_MIN_CHARS = 16;
+
+/** Whether one page's extracted text is a real text layer (see above). */
+export function pageHasTextLayer(text) {
+  return String(text || '').replace(/\s+/g, '').length >= PDF_TEXT_LAYER_MIN_CHARS;
+}
+
+function timeoutError(timeoutMs) {
+  return Object.assign(new Error(`PDF inspection timed out after ${timeoutMs} ms`), {
+    code: 'PDF_INSPECTION_TIMEOUT',
+  });
+}
+
+/** Inspect a PDF. With `timeoutMs`, a document that has not finished by then
+ *  is destroyed and the call rejects (`code: 'PDF_INSPECTION_TIMEOUT'`);
+ *  without it there is no deadline. */
+export async function inspectPdfBuffer(buffer, { timeoutMs = null, ...options } = {}) {
+  if (!Buffer.isBuffer(buffer) || buffer.length === 0) throw new TypeError('PDF payload is empty');
+  const hold = { pdf: null, expired: false };
+  if (!(timeoutMs > 0)) return inspectLoaded(buffer, options, hold);
+  let timer;
+  const deadline = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      hold.expired = true;
+      // A document still loading is destroyed as soon as it arrives (below).
+      Promise.resolve(hold.pdf?.destroy?.()).catch(() => {});
+      reject(timeoutError(timeoutMs));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([inspectLoaded(buffer, options, hold), deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function inspectLoaded(
   buffer,
   {
     extractText = false,
+    measureText = false,
     maxPages = MAX_PDF_PAGES,
     maxOutputBytes = DEFAULT_MAX_OUTPUT_BYTES,
     pageRange = null,
     password = '',
-  } = {}
+  },
+  hold
 ) {
-  if (!Buffer.isBuffer(buffer) || buffer.length === 0) throw new TypeError('PDF payload is empty');
   await resolvedPdfJs();
   const { getDocumentProxy } = await import('unpdf');
   const pdf = await getDocumentProxy(new Uint8Array(buffer), password ? { password: String(password) } : {});
+  hold.pdf = pdf;
   try {
+    if (hold.expired) throw timeoutError(0);
     const pageCount = Math.max(0, Number(pdf?.numPages) || 0);
     const pageLimit = Number.isFinite(Number(maxPages)) ? Math.max(1, Math.floor(Number(maxPages))) : Infinity;
     if (pageCount > pageLimit) {
       throw new RangeError(`PDF has ${pageCount} pages; maximum supported attachment is ${pageLimit} pages`);
     }
+    if (measureText) return { pageCount, ...(await measureTextLayer(pdf, pageCount, hold)) };
     if (!extractText) return { pageCount, text: '', truncated: false };
 
     const from = Math.max(1, Number(pageRange?.from) || 1);
     const to = Math.min(pageCount, Math.max(from, Number(pageRange?.to) || pageCount));
     const byteLimit = Math.max(1, Number(maxOutputBytes) || DEFAULT_MAX_OUTPUT_BYTES);
     const chunks = [];
+    // Each page's own text (before the output budget cuts it), so a caller can
+    // tell text pages from scanned ones.
+    const pages = [];
     let bytes = 0;
     let truncated = false;
     for (let pageNumber = from; pageNumber <= to; pageNumber += 1) {
       const page = await pdf.getPage(pageNumber);
       try {
         const body = pageBodyText(await page.getTextContent());
+        pages.push({ page: pageNumber, text: body });
         const block = `--- Page ${pageNumber} ---\n${body || '(no extractable text on this page)'}`;
         const separatorBytes = chunks.length ? 2 : 0;
         const remaining = byteLimit - bytes - separatorBytes;
@@ -134,12 +185,35 @@ export async function inspectPdfBuffer(
       const suffix = '\n\n... [PDF text truncated to the prompt input budget]';
       const room = Math.max(0, byteLimit - Buffer.byteLength(suffix, 'utf8'));
       const bounded = boundedUtf8(chunks.join(''), room);
-      return { pageCount, text: `${bounded.text}${suffix}`, truncated: true };
+      return { pageCount, text: `${bounded.text}${suffix}`, truncated: true, pages };
     }
-    return { pageCount, text: chunks.join(''), truncated: false };
+    return { pageCount, text: chunks.join(''), truncated: false, pages };
   } finally {
     try {
       await pdf.destroy?.();
     } catch {}
   }
 }
+
+// How much of the document reads as text: the pages that carry a text layer
+// and the characters they hold. Nothing is kept but the counts.
+async function measureTextLayer(pdf, pageCount, hold) {
+  let textPages = 0;
+  let textChars = 0;
+  for (let pageNumber = 1; pageNumber <= pageCount; pageNumber += 1) {
+    if (hold.expired) throw timeoutError(0);
+    const page = await pdf.getPage(pageNumber);
+    try {
+      const body = pageBodyText(await page.getTextContent());
+      if (pageHasTextLayer(body)) {
+        textPages += 1;
+        textChars += body.length;
+      }
+    } finally {
+      try {
+        page.cleanup?.();
+      } catch {}
+    }
+  }
+  return { textPages, textChars };
+}

package/src/runtime/attachments/store.mjs

@@ -6,7 +6,7 @@
  * snapshots carry only a sha256 reference plus byte-free metadata.
  * Provider lowering resolves the reference at the last possible boundary.
  */
-import { createHash, randomBytes } from 'node:crypto';
+import { createHash } from 'node:crypto';
 import {
   closeSync,
   existsSync,
@@ -15,18 +15,18 @@ import {
   openSync,
   readFileSync,
   readSync,
-  renameSync,
   statSync,
   unlinkSync,
   utimesSync,
   writeFileSync,
 } from 'node:fs';
-import { mkdir, readdir, readFile as readFileAsync, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { readdir, readFile as readFileAsync, stat, unlink } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
+import { writeFileAtomicSync, writeJsonAtomicAsync } from '../shared/atomic-file.mjs';
 import { resolvePluginData } from '../shared/plugin-paths.mjs';
 import { MAX_ATTACHMENT_BLOB_BYTES, MAX_PDF_BYTES, MAX_PDF_PAGES, isPdfBuffer } from './limits.mjs';
-import { inspectPdfBuffer } from './pdf-extract.mjs';
+import { inspectPdfBuffer, PDF_INTAKE_TIMEOUT_MS } from './pdf-extract.mjs';
 
 const ATTACHMENT_REF_RE = /^[a-f0-9]{64}$/;
 const TEXT_TOKEN_RE = /\[(?:Pasted text|File) #(\d+)[^\]\r\n]*\]/g;
@@ -140,17 +140,13 @@ function saveBuffer(buffer) {
   }
   if (!existingValid) {
     mkdirSync(join(attachmentsDir(), attachmentRef.slice(0, 2)), { recursive: true, mode: 0o700 });
-    const temp = `${target}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
     try {
-      writeFileSync(temp, buffer, { mode: 0o600 });
-      renameSync(temp, target);
+      // Durable, so a crash cannot leave this content address holding NUL
+      // bytes (a read would then fail its digest check).
+      writeFileAtomicSync(target, buffer, { mode: 0o600 });
     } catch (error) {
       // A concurrent writer may have published the same content first.
       if (!storedMatches()) throw error;
-    } finally {
-      try {
-        unlinkSync(temp);
-      } catch {}
     }
   } else {
     // Reusing old content creates a fresh reference before its queue/session
@@ -172,10 +168,23 @@ export function storeAttachmentBuffer(buffer) {
   return saveBuffer(buffer);
 }
 
+/** Where the store keeps the bytes of `ref` on this machine (no extension:
+ *  the read tool recognizes PDFs and images there by their content). */
+export function attachmentFilePath(ref) {
+  return attachmentPath(ref);
+}
+
 export function isAttachmentReference(value) {
   return Boolean(value && typeof value === 'object' && ATTACHMENT_REF_RE.test(String(value.attachmentRef || '')));
 }
 
+// The bytes of a base64 string, or null when they are empty or would not
+// re-encode to the same string (a stored reference could not replay it exactly).
+function canonicalBase64Buffer(data) {
+  const buffer = Buffer.from(data, 'base64');
+  return buffer.length === 0 || buffer.toString('base64') !== data ? null : buffer;
+}
+
 /**
  * Stored-history form of an inline base64 image part (`{ type:'image', data }`
  * or `{ type:'image', source:{ type:'base64' } }`): the same part as a
@@ -200,8 +209,8 @@ export function storeInlineImagePart(part) {
   } else {
     return null;
   }
-  const buffer = Buffer.from(data, 'base64');
-  if (buffer.length === 0 || buffer.toString('base64') !== data) return null;
+  const buffer = canonicalBase64Buffer(data);
+  if (!buffer) return null;
   return { ...metadata, ...saveBuffer(buffer) };
 }
 
@@ -235,8 +244,8 @@ export function storeInlineDocumentPart(part) {
   } else {
     return null;
   }
-  const buffer = Buffer.from(data, 'base64');
-  if (buffer.length === 0 || buffer.toString('base64') !== data) return null;
+  const buffer = canonicalBase64Buffer(data);
+  if (!buffer) return null;
   // The magic header decides the kind before the label does (inlineFileKind),
   // so a mislabelled PDF is stored under its real type: the reloaded part then
   // estimates and lowers exactly like the live one.
@@ -645,11 +654,21 @@ export async function preparePromptSubmissionForProvider(intake, provider) {
     if (bytes > MAX_PDF_BYTES) {
       throw new RangeError(`PDF exceeds the ${MAX_PDF_BYTES / 1024 / 1024} MiB input limit`);
     }
+    // The text-layer counts price the PDF (a scanned page costs its page image,
+    // a text page its text as well) and tell the model, when the PDF is sent
+    // as a reference, which pages read as text.
     const inspected = await inspectPdfBuffer(readAttachmentBuffer(part), {
       maxPages: nativePdf ? MAX_PDF_PAGES : Infinity,
+      measureText: true,
+      timeoutMs: PDF_INTAKE_TIMEOUT_MS,
     });
     changed = true;
-    prepared.push({ ...part, pageCount: inspected.pageCount });
+    prepared.push({
+      ...part,
+      pageCount: inspected.pageCount,
+      textPages: inspected.textPages,
+      textChars: inspected.textChars,
+    });
   }
   if (!changed) return intake;
   return { ...intake, prompt: prepared };
@@ -739,8 +758,8 @@ function dropCachedAttachment(path) {
 async function persistedAttachmentReferencePaths() {
   const root = resolvePluginData();
   const paths = [];
-  for (const dirname of ['sessions', 'turn-checkpoints', 'session-pending']) {
-    const dir = join(root, dirname);
+  for (const subdir of ['sessions', 'turn-checkpoints', 'session-pending']) {
+    const dir = join(root, subdir);
     let entries;
     try {
       entries = await readdir(dir, { withFileTypes: true });
@@ -752,7 +771,7 @@ async function persistedAttachmentReferencePaths() {
       if (!entry.isFile()) continue;
       // The turn-checkpoint journal appends `<session>.jsonl` records that
       // carry attachment refs of in-flight turns.
-      if (entry.name.endsWith('.json') || (dirname === 'turn-checkpoints' && entry.name.endsWith('.jsonl'))) {
+      if (entry.name.endsWith('.json') || (subdir === 'turn-checkpoints' && entry.name.endsWith('.jsonl'))) {
         paths.push(join(dir, entry.name));
       }
     }
@@ -819,16 +838,14 @@ async function loadReferenceCache(root) {
 async function saveReferenceCache(root, files) {
   referenceCache = { root, files };
   const target = attachmentReferenceCachePath();
-  const temp = `${target}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
   try {
-    await mkdir(dirname(target), { recursive: true });
-    await writeFile(temp, JSON.stringify({ version: 1, files: Object.fromEntries(files) }));
-    await rename(temp, target);
-  } catch {
-    try {
-      await unlink(temp);
-    } catch {}
-  }
+    // An unusable cache only costs a full re-read (loadReferenceCache), so no fsync.
+    await writeJsonAtomicAsync(
+      target,
+      { version: 1, files: Object.fromEntries(files) },
+      { compact: true, fsync: false }
+    );
+  } catch {}
 }
 
 export async function collectPromptAttachments({ now = Date.now(), minAgeMs = ATTACHMENT_GC_MIN_AGE_MS } = {}) {
@@ -885,8 +902,10 @@ export async function collectPromptAttachments({ now = Date.now(), minAgeMs = AT
       continue;
     }
     for (const entry of entries) {
-      // A writer that died between create and rename leaves `<ref>.<pid>.<rand>.tmp`.
-      if (entry.isFile() && /^[a-f0-9]{64}\..+\.tmp$/.test(entry.name)) {
+      // A writer that died between create and rename leaves
+      // `<ref>.mixdog-tmp-<rand>` (atomic writer), or the older
+      // `.<ref>.<rand>.tmp` / `<ref>.<pid>.<rand>.tmp`.
+      if (entry.isFile() && /^(?:\.?[a-f0-9]{64}\..+\.tmp|[a-f0-9]{64}\.mixdog-tmp-[0-9a-f]+)$/.test(entry.name)) {
         const tempPath = join(dir, entry.name);
         try {
           if ((await stat(tempPath)).mtimeMs <= cutoff) await unlink(tempPath);

package/src/runtime/browser-bridge/client.mjs

@@ -14,8 +14,12 @@ import { base64ByteLength, inlineFileKind } from '../shared/inline-file-kind.mjs
 import { MAX_IMAGE_BYTES, SUPPORTED_IMAGE_MIME_TYPES } from '../attachments/limits.mjs';
 
 const DISCOVERY_FILE = 'browser-bridge.json';
-/** Ceiling above the bridge's own per-action timeouts (navigation settle,
- *  surface auto-open), so the bridge's specific error wins over a bare abort. */
+/** How long a request may go without a single byte from the bridge. Above the
+ *  bridge's own per-action timeouts (navigation settle, surface auto-open), so
+ *  the bridge's specific error wins over a bare abort. It is a silence limit,
+ *  not a total: a command that waits on the person (an approval card, which has
+ *  no limit) is kept alive by the bridge with a space every few seconds
+ *  (apps/desktop/src/main/browser/bridge-server.ts), and each byte restarts it. */
 const REQUEST_TIMEOUT_MS = 45_000;
 const MAX_REQUEST_BYTES = 256 * 1024;
 const MAX_RESPONSE_BYTES = 150 * 1024 * 1024;
@@ -33,7 +37,7 @@ export async function finishBrowserTurn(sessionId, turnId, { aborted = false } =
   if (!discovery) return;
   turns.delete(turnId);
   if (!turns.size) browserTurns.delete(sessionId);
-  const result = await requestBridge(
+  const result = await requestBridgeWithin(
     discovery,
     JSON.stringify({
       action: 'finish_turn',
@@ -43,7 +47,7 @@ export async function finishBrowserTurn(sessionId, turnId, { aborted = false } =
       // so its pages stay; only an aborted run reclaims them.
       aborted: aborted === true,
     }),
-    AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    undefined,
     { sessionId, turnId, action: 'finish_turn' }
   );
   if (result.status !== 200 || result.body?.ok === false || result.body?.error) {
@@ -61,12 +65,10 @@ export async function browserSecretInput(sessionId, requestId, { signal } = {})
   const discovery = readBridgeDiscovery(DISCOVERY_FILE);
   if (!discovery || !sessionId || !requestId) return 'skipped';
   try {
-    const result = await requestBridge(
+    const result = await requestBridgeWithin(
       discovery,
       JSON.stringify({ action: 'secret_input', session_id: String(sessionId), request_id: String(requestId) }),
-      signal
-        ? AbortSignal.any([AbortSignal.timeout(REQUEST_TIMEOUT_MS), signal])
-        : AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      signal,
       { sessionId, action: 'secret_input' }
     );
     return result.status === 200 && result.body?.ok !== false && result.body?.value?.text === 'provided'
@@ -155,8 +157,9 @@ function unavailableMessage() {
 class BrowserBridgeResponseError extends Error {}
 
 // Read the body incrementally so a chunked response (no content-length) still
-// honours MAX_RESPONSE_BYTES.
-export async function readCappedJson(response, maximum = MAX_RESPONSE_BYTES) {
+// honours MAX_RESPONSE_BYTES. `onChunk` hears every chunk read (the bridge's
+// keep-alive spaces included).
+export async function readCappedJson(response, maximum = MAX_RESPONSE_BYTES, onChunk = undefined) {
   if (!response.body) throw new Error('empty response');
   const reader = response.body.getReader();
   const chunks = [];
@@ -165,6 +168,7 @@ export async function readCappedJson(response, maximum = MAX_RESPONSE_BYTES) {
     for (;;) {
       const result = await reader.read();
       if (result.done) break;
+      onChunk?.();
       bytes += result.value.byteLength;
       if (bytes > maximum) {
         await reader.cancel().catch(() => {});
@@ -178,7 +182,50 @@ export async function readCappedJson(response, maximum = MAX_RESPONSE_BYTES) {
   return JSON.parse(Buffer.concat(chunks, bytes).toString('utf8'));
 }
 
-async function requestBridge(discovery, encodedPayload, signal, timingContext) {
+/** One bridge request's clock: it times out after `timeoutMs` without a byte
+ *  from the bridge (`touch` restarts it), with the same TimeoutError an
+ *  AbortSignal.timeout gives, and ends with `callerSignal` (the caller's own
+ *  reason). `stop` leaves no timer behind. */
+export function bridgeDeadline(callerSignal, timeoutMs = REQUEST_TIMEOUT_MS) {
+  const controller = new AbortController();
+  let timer = null;
+  const stop = () => {
+    if (timer) clearTimeout(timer);
+    timer = null;
+  };
+  const touch = () => {
+    stop();
+    timer = setTimeout(
+      () => controller.abort(new DOMException('The operation was aborted due to timeout', 'TimeoutError')),
+      timeoutMs
+    );
+    timer.unref?.();
+  };
+  touch();
+  return {
+    signal: callerSignal ? AbortSignal.any([controller.signal, callerSignal]) : controller.signal,
+    touch,
+    stop,
+  };
+}
+
+/** `requestBridge` under the silence limit of `bridgeDeadline`. */
+export async function requestBridgeWithin(
+  discovery,
+  encodedPayload,
+  callerSignal,
+  timingContext,
+  timeoutMs = REQUEST_TIMEOUT_MS
+) {
+  const deadline = bridgeDeadline(callerSignal, timeoutMs);
+  try {
+    return await requestBridge(discovery, encodedPayload, deadline.signal, timingContext, deadline.touch);
+  } finally {
+    deadline.stop();
+  }
+}
+
+async function requestBridge(discovery, encodedPayload, signal, timingContext, onActivity = undefined) {
   const started = performance.now();
   let body;
   let status;
@@ -192,6 +239,7 @@ async function requestBridge(discovery, encodedPayload, signal, timingContext) {
       body: encodedPayload,
       signal,
     });
+    onActivity?.();
     status = response.status;
     const contentLength = Number(response.headers.get('content-length'));
     if (Number.isFinite(contentLength) && contentLength > MAX_RESPONSE_BYTES) {
@@ -199,10 +247,12 @@ async function requestBridge(discovery, encodedPayload, signal, timingContext) {
       throw new BrowserBridgeResponseError(`browser bridge response exceeds ${MAX_RESPONSE_BYTES} bytes`);
     }
     try {
-      body = await readCappedJson(response);
+      body = await readCappedJson(response, MAX_RESPONSE_BYTES, onActivity);
       return { body, status: response.status };
     } catch (error) {
       if (error instanceof BrowserBridgeResponseError) throw error;
+      // Silence past the clock, or the caller stopping, is not a bad response.
+      if (signal?.aborted) throw signal.reason ?? error;
       throw new BrowserBridgeResponseError(`browser bridge returned an invalid response (HTTP ${response.status})`);
     }
   } finally {
@@ -225,6 +275,12 @@ export async function executeBrowserTool(args, options = {}) {
     action: validated.action,
     ...validated.input,
     session_id: sessionId,
+    // Set by the runtime from the session, never from the model's arguments: a
+    // schedule/webhook run (or work it started) whose saved routine is the
+    // user's grant for submits, posts and uploads (human-gate/run-policy.mjs).
+    ...(options.unattendedRun === true
+      ? { unattended_run: true, unattended_agent: String(options.unattendedAgent || '') }
+      : {}),
     ...(Number.isFinite(Number(options.turnId)) && Number(options.turnId) > 0
       ? { turn_id: Math.trunc(Number(options.turnId)) }
       : {}),
@@ -243,14 +299,11 @@ export async function executeBrowserTool(args, options = {}) {
   let bridgeResult;
   for (let attempt = 0; attempt < 2; attempt += 1) {
     try {
-      bridgeResult = await requestBridge(
-        discovery,
-        encodedPayload,
-        options.signal
-          ? AbortSignal.any([AbortSignal.timeout(REQUEST_TIMEOUT_MS), options.signal])
-          : AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-        { sessionId, turnId: payload.turn_id, action: validated.action }
-      );
+      bridgeResult = await requestBridgeWithin(discovery, encodedPayload, options.signal, {
+        sessionId,
+        turnId: payload.turn_id,
+        action: validated.action,
+      });
       break;
     } catch (error) {
       if (error?.name === 'TimeoutError') {

package/src/runtime/channels/lib/runtime-paths.mjs

@@ -329,7 +329,7 @@ function cleanupStaleRuntimeFiles(now = Date.now()) {
       // tighter TTLs keep dead-process residue from accumulating.
       let ttl = RUNTIME_STALE_TTL;
       if (/^status-.*\.json$/.test(file)) ttl = STATUS_FILE_TTL;
-      else if (/\.tmp$/.test(file)) ttl = TMP_FILE_TTL;
+      else if (/\.tmp$|\.mixdog-tmp-[0-9a-f]+$/.test(file)) ttl = TMP_FILE_TTL;
       if (age > ttl) removeFileIfExists(fullPath);
     } catch {}
   });

package/src/runtime/channels/lib/scheduler.mjs

@@ -26,6 +26,19 @@ const SCHEDULE_LOG = join(DATA_DIR, 'schedule.log');
 // here. The channels worker owns shutdown sequencing (drain queues, persist
 // baselines, release the scheduler lock, etc.) and a library-level exit(0)
 // preempts that drain. The buffered appender drains pending log lines on exit.
+function skipReasonText(outcome) {
+  switch (outcome.reason) {
+    case 'backoff':
+      return 'backing off after failures';
+    case 'paused':
+      return 'switched off';
+    case 'owner':
+      return `paused: ${outcome.message}`;
+    default:
+      return 'previous run still in progress';
+  }
+}
+
 function logSchedule(msg) {
   msg = msg.replace(/\n$/, '');
   process.stderr.write(`mixdog scheduler: ${msg}\n`);
@@ -686,13 +699,7 @@ ${prompt}`;
         // already persisted the skip.
         if (outcome?.skipped) {
           schedule.lastSkippedAt = new Date().toISOString();
-          const why =
-            outcome.reason === 'backoff'
-              ? 'backing off after failures'
-              : outcome.reason === 'owner'
-                ? `paused: ${outcome.message}`
-                : 'previous run still in progress';
-          logSchedule(`${schedule.name}: skipped — ${why}\n`);
+          logSchedule(`${schedule.name}: skipped — ${skipReasonText(outcome)}\n`);
           return false;
         }
         logSchedule(`${schedule.name} done\n`);

package/src/runtime/channels/lib/state-file.mjs

@@ -1,5 +1,5 @@
 import { mkdirSync, readFileSync, unlinkSync } from 'node:fs';
-import { writeJsonAtomicSync } from '../../shared/atomic-file.mjs';
+import { readJsonStateSync, updateJsonAtomicSync, writeJsonAtomicSync } from '../../shared/atomic-file.mjs';
 function ensureDir(dirPath) {
   mkdirSync(dirPath, { recursive: true });
 }
@@ -19,10 +19,6 @@ function readJsonFile(filePath, fallback) {
     return fallback;
   }
 }
-function readJsonFileStrict(filePath) {
-  const raw = readFileSync(filePath, 'utf8');
-  return JSON.parse(raw);
-}
 function writeJsonFile(filePath, value) {
   writeJsonAtomicSync(filePath, value, { compact: true, lock: true, fsync: false, fsyncDir: false });
 }
@@ -38,19 +34,23 @@ class JsonStateFile {
     writeJsonFile(this.filePath, value);
     return value;
   }
+  // A damaged file (empty, NUL-filled after a crash) is kept aside as
+  // <file>.corrupt-<ts> and the file restarts from the fallback; it is never
+  // overwritten in place and never blocks an update. That recovery is why the
+  // writes below can skip fsync.
   ensure() {
-    writeJsonFile(this.filePath, this.read());
+    writeJsonFile(this.filePath, readJsonStateSync(this.filePath, { fallback: this.fallback }));
   }
   update(mutator) {
-    let draft;
-    try {
-      draft = readJsonFileStrict(this.filePath);
-    } catch (err) {
-      process.stderr.write(`[state-file] REFUSING update: parse error for ${this.filePath}: ${err.message}\n`);
-      throw err;
-    }
-    mutator(draft);
-    return this.write(draft);
+    return updateJsonAtomicSync(
+      this.filePath,
+      (current) => {
+        const draft = current ?? structuredClone(this.fallback);
+        mutator(draft);
+        return draft;
+      },
+      { compact: true, fsync: false, fsyncDir: false }
+    );
   }
 }
 export { JsonStateFile, ensureDir, readJsonFile, removeFileIfExists, writeJsonFile };