mixdog 1.3.1 → 1.3.2

package/src/runtime/agent/orchestrator/tools/builtin/advisory-lock.mjs

@@ -1,16 +1,41 @@
-// Cross-process advisory lock for patch/write operations. Uses a sibling
-// lockfile written exclusively (`wx`) and a process.kill(pid, 0) liveness
-// check to clean up after crashed holders. Pair with the in-process
-// withPathLock for the same target: in-process serialises async callers
-// in this Node, advisory lock serialises across Node processes.
-import { openSync, closeSync, writeSync, readFileSync, unlinkSync, mkdirSync } from 'node:fs';
+// Cross-process advisory lock for patch/write operations. Uses a lockfile
+// written exclusively (`wx`) and a process.kill(pid, 0) liveness check to
+// clean up after crashed holders. Pair with the in-process withPathLock for
+// the same target: in-process serialises async callers in this Node, advisory
+// lock serialises across Node processes.
+import { openSync, closeSync, writeSync, readFileSync, unlinkSync, mkdirSync, realpathSync } from 'node:fs';
 import { compareCodePoints } from '../../../../shared/code-point-order.mjs';
+import { resolvePluginData } from '../../../../shared/plugin-paths.mjs';
 import { sleep } from '../../../../shared/sleep.mjs';
-import { dirname, basename, join } from 'node:path';
-import { randomBytes } from 'node:crypto';
+import { dirname, basename, join, resolve } from 'node:path';
+import { createHash, randomBytes } from 'node:crypto';
 
+// The deepest existing component (the target itself when present, so a leaf
+// symlink shares its referent's lock like atomicWrite writes through it) is
+// resolved; components not created yet are appended as given.
+function canonicalLockTarget(targetPath) {
+  const resolved = resolve(targetPath);
+  const tail = [];
+  let dir = resolved;
+  for (;;) {
+    try {
+      return join(realpathSync.native(dir), ...tail.reverse());
+    } catch {
+      if (dirname(dir) === dir) return resolved;
+      tail.push(basename(dir));
+      dir = dirname(dir);
+    }
+  }
+}
+
+// Lockfiles live in the local data dir, keyed by the target's canonical path,
+// never beside the target: sync-drive folders (e.g. Naver MYBOX) refuse
+// dot-prefixed sibling files, and the pid liveness check only spans this host.
 function lockFileFor(targetPath) {
-  return join(dirname(targetPath), `.${basename(targetPath)}.mixdog-lock`);
+  const canonical = canonicalLockTarget(targetPath);
+  const key = process.platform === 'win32' ? canonical.toLowerCase() : canonical;
+  const hash = createHash('sha256').update(key).digest('hex');
+  return join(resolvePluginData(), 'locks', `${hash}.mixdog-lock`);
 }
 
 function isPidAlive(pid) {
@@ -87,15 +112,12 @@ function tryCreateLock(lockFile, token) {
 
 async function acquireAdvisoryLock(targetPath, { timeoutMs = 5000, pollMs = 25 } = {}) {
   const lockFile = lockFileFor(targetPath);
-  // Ensure parent directory exists before openSync('wx'); the lockfile lives
-  // next to the target, so writes to new files in missing parent dirs would
-  // otherwise fail with ENOENT here.
   mkdirSync(dirname(lockFile), { recursive: true });
   const token = `${process.pid}.${randomBytes(8).toString('hex')}`;
   const deadline = Date.now() + timeoutMs;
   let stalePostDeadlineRetryUsed = false;
   const timeoutError = (holderPid) => {
-    const err = new Error(`advisory lock timeout: ${lockFile} held by pid ${holderPid}`);
+    const err = new Error(`advisory lock timeout: ${targetPath} (${lockFile}) held by pid ${holderPid}`);
     err.code = 'EAGAIN';
     return err;
   };

package/src/runtime/agent/orchestrator/tools/builtin/atomic-write.mjs

@@ -24,9 +24,24 @@ function expectedTargetSnapshotChanged(currentStat, expected) {
   return !sameFileVersion(currentStat, expected);
 }
 
+// Files the agent writes into a user's project are durable by default: without
+// the flush a crash can publish the renamed file with every byte NUL.
+// MIXDOG_ATOMIC_FSYNC=0|false|no|off opts out.
 function atomicWriteShouldFsync(value) {
   if (value === true || value === false) return value;
-  return /^(1|true|yes|on|sync)$/i.test(String(process.env.MIXDOG_ATOMIC_FSYNC || ''));
+  return !/^(0|false|no|off)$/i.test(String(process.env.MIXDOG_ATOMIC_FSYNC || ''));
+}
+
+// Filesystems that refuse fsync answer with one of these; durability is
+// best-effort there and must not fail the write.
+const FSYNC_TOLERATED = new Set(['EPERM', 'ENOTSUP', 'EINVAL']);
+
+async function syncHandle(fh) {
+  try {
+    await fh.sync();
+  } catch (error) {
+    if (!FSYNC_TOLERATED.has(error?.code)) throw error;
+  }
 }
 
 // 'wx' preflight creates an empty placeholder at targetPath; if the write is
@@ -104,7 +119,10 @@ async function writeTempFile(tmp, content, { mode, fsync }) {
     if (payloadByteLength(content) > STREAMING_THRESHOLD_BYTES) {
       // Streaming path: avoid buffering the entire payload through
       // fh.writeFile (which copies into a single Buffer).
-      const ws = createWriteStream(tmp, { flags: 'wx', mode });
+      // Owner-writable while we flush: the fsync reopens the file for writing,
+      // which a read-only mode would refuse; the final mode is applied after.
+      const streamMode = fsync ? mode | 0o200 : mode;
+      const ws = createWriteStream(tmp, { flags: 'wx', mode: streamMode });
       // Stream construction precedes open; only the open event proves ownership.
       ws.once('open', () => {
         ownsTemp = true;
@@ -115,15 +133,16 @@ async function writeTempFile(tmp, content, { mode, fsync }) {
       await pipeline(source, ws);
       if (fsync) {
         fh = await fsPromises.open(tmp, 'r+');
-        await fh.sync();
+        await syncHandle(fh);
         await fh.close();
         fh = null;
+        if (streamMode !== mode) await fsPromises.chmod(tmp, mode);
       }
     } else {
       fh = await fsPromises.open(tmp, 'wx', mode);
       ownsTemp = true;
       await fh.writeFile(content);
-      if (fsync) await fh.sync();
+      if (fsync) await syncHandle(fh);
       await fh.close();
       fh = null;
     }
@@ -260,7 +279,8 @@ export async function atomicWrite(
   // beside the real target, so the rename stays on one filesystem.
   const writeTarget = symlinkWriteTarget(targetPath) ?? targetPath;
   const dir = dirname(writeTarget);
-  const tmp = join(dir, `.${basename(writeTarget)}.mixdog-tmp-${randomBytes(4).toString('hex')}`);
+  // No leading dot: sync-drive folders (e.g. Naver MYBOX) refuse dot-prefixed names.
+  const tmp = join(dir, `${basename(writeTarget)}.mixdog-tmp-${randomBytes(4).toString('hex')}`);
   const existingStat = statOrNull(writeTarget);
   let effectiveMode = mode;
   if (effectiveMode === undefined && existingStat) effectiveMode = existingStat.mode & 0o777;

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool/backgrounded-result.mjs

@@ -3,7 +3,7 @@ import { killShellJob, watchBackgroundShellJob } from '../shell-jobs.mjs';
 import { renderBackgroundPartialOutput } from '../shell-output.mjs';
 import { readShellTaskOutput } from '../lib/shell-task-output.mjs';
 import { normalizeOutputPath } from '../path-utils.mjs';
-import { cleanupArtifactOnTaskSettled, consumeTeeArtifact } from './transport-artifacts.mjs';
+import { cleanupArtifactAfter, cleanupArtifactOnTaskSettled, consumeTeeArtifact } from './transport-artifacts.mjs';
 import { _backgroundResultLines, _prependDestructiveWarning } from './result-format.mjs';
 
 const DEFAULT_BACKGROUND_MESSAGE =
@@ -68,8 +68,9 @@ export function renderBackgroundedResult({ result, command, cwd, options, starte
   }
   // The promoted producer is still writing into the tee file, so it cannot be
   // consumed here — but it must not survive the command either. Consume (and
-  // delete) it when the task settles.
-  if (teePlan) cleanupArtifactOnTaskSettled(teePlan.teePath, result.jobId, consumeTeeArtifact);
+  // delete) it when the task settles — for a queued command, its run.
+  if (teePlan && result.jobId) cleanupArtifactOnTaskSettled(teePlan.teePath, result.jobId, consumeTeeArtifact);
+  else if (teePlan) cleanupArtifactAfter(teePlan.teePath, result.settled, consumeTeeArtifact);
   let taskBlock = null;
   if (task) taskBlock = renderBackgroundTask(task, { ownerTool: true });
   else if (result.jobId) taskBlock = `[task_id: ${result.jobId}]`;

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool/completed-result.mjs

@@ -1,9 +1,9 @@
 import { renderBackgroundTask, startBackgroundTask } from '../../../../../shared/background-tasks.mjs';
 import { killShellDescendants, waitForShellDescendants } from '../../lib/shell-descendants.mjs';
 import { releaseShellJobWorkspace } from '../lib/shell-job-records.mjs';
-import { consumeFilterTeeCapture } from '../shell-analysis.mjs';
+import { readFilterTeeCapture } from '../shell-analysis.mjs';
 import { compactShellOutputLosslessly, renderShellOutputBody } from '../shell-lossless-compact.mjs';
-import { removeTransportFileNow } from './transport-artifacts.mjs';
+import { cleanupArtifactAfter, removeTransportFileNow } from './transport-artifacts.mjs';
 import { DELIVERY_FULL_CHARS, EMPTY_PIECE, fitPieces, shellTextPiece } from '../lib/shell-delivery.mjs';
 import { shellLogPiece } from '../lib/shell-task-output.mjs';
 import { shellTaskIdentity } from './backgrounded-result.mjs';
@@ -74,17 +74,16 @@ function survivingDescendantsWarning(result, taskContext) {
   return [heading, renderBackgroundTask(task, { ownerTool: true })].join('\n');
 }
 
-// Filter-swallow rescue: the tee file is ALWAYS consumed (deleted) here; its
-// tail is attached only when the run failed with an empty visible capture —
-// the exact `(no output)` shape that previously cost the model extra
-// diagnostic turns.
-function filterRescueNote(teePlan, { failed, stdout, stderr }) {
-  const rescueTail = consumeFilterTeeCapture(teePlan.teePath);
-  // consumeFilterTeeCapture unlinks best-effort and swallows the failure; on
-  // Windows a process that survived an unconfirmed kill still holds the file.
-  // Route it through the same retry + exit-hook path the settlement branch
-  // uses instead of abandoning it.
-  removeTransportFileNow(teePlan.teePath);
+// Filter-swallow rescue: the tee file is ALWAYS consumed (deleted) — once the
+// run's tree has settled when its result says it may still run; its tail is
+// attached only when the run failed with an empty visible capture — the exact
+// `(no output)` shape that previously cost the model extra diagnostic turns.
+function filterRescueNote(teePlan, { failed, stdout, stderr }, settled) {
+  const rescueTail = readFilterTeeCapture(teePlan.teePath);
+  // Removal goes through the retry + exit-hook path: on Windows a process
+  // that survived an unconfirmed kill still holds the file.
+  if (settled) cleanupArtifactAfter(teePlan.teePath, settled);
+  else removeTransportFileNow(teePlan.teePath);
   if (!failed || !rescueTail || stdout.trim() || stderr.trim()) return '';
   return `\n\n[filter-swallowed output rescue] the command failed but its trailing filter(s) matched nothing, so the visible output was empty. Unfiltered pipeline output (tail):\n${rescueTail}`;
 }
@@ -148,7 +147,7 @@ export function renderCompletedResult({
   const { signal, exitCode, completedExit, benignExit, isReallyErrored } = outcome;
   const commandExitedNonzero = completedExit && exitCode !== 0 && !benignExit;
   const rescueNote = teePlan
-    ? filterRescueNote(teePlan, { failed: isReallyErrored || commandExitedNonzero, stdout, stderr })
+    ? filterRescueNote(teePlan, { failed: isReallyErrored || commandExitedNonzero, stdout, stderr }, result.settled)
     : '';
   const descendantWarning = survivingDescendantsWarning(result, { command, cwd, options, startedAtMs });
   // rewriteNote states that the text which RAN is not the text the caller

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool/transport-artifacts.mjs

@@ -79,6 +79,15 @@ export function removeTransportFileNow(file) {
   finishTransportArtifact(file, removeTransportFile);
 }
 
+/** Remove `file` once a run's own lifetime promise settles: a queued command
+ *  has no job to subscribe to until it runs. */
+export function cleanupArtifactAfter(file, settled, remove = removeTransportFile) {
+  if (!file) return;
+  registerTransportArtifact(file);
+  const done = () => finishTransportArtifact(file, remove);
+  Promise.resolve(settled).then(done, done);
+}
+
 export function cleanupArtifactOnTaskSettled(file, jobId, remove = removeTransportFile) {
   if (!file) return;
   registerTransportArtifact(file);

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool.mjs

@@ -12,7 +12,11 @@ import { recordShellCaptureTelemetry } from './shell-output.mjs';
 import { normalizeErrorMessage } from './path-diagnostics.mjs';
 import { invalidateBuiltinResultCache } from './cache-layers.mjs';
 import { formatShellToolFailure } from './bash-tool/result-format.mjs';
-import { cleanupArtifactOnTaskSettled, removeTransportFileNow } from './bash-tool/transport-artifacts.mjs';
+import {
+  cleanupArtifactAfter,
+  cleanupArtifactOnTaskSettled,
+  removeTransportFileNow,
+} from './bash-tool/transport-artifacts.mjs';
 import { combineAbortSignals, sessionAbortSignal } from './bash-tool/abort-signals.mjs';
 import { beginInterruptibleTaskWait } from '../../session/task-wait-control.mjs';
 import { prepareShellCommand } from './bash-tool/command-preflight.mjs';
@@ -39,9 +43,10 @@ export { buildShellSpawnEnv } from './bash-tool/spawn-env.mjs';
 export { executeTaskTool } from './task-tool.mjs';
 
 // Reads cached after a mutating command must not serve pre-command state. A
-// promoted command has barely started when the tool returns and a queued one
-// has not started at all, so the invalidation repeats when it settles.
-function settleMutationCaches(shellEffects, backgroundJobId, queuedSettled = null) {
+// promoted command has barely started when the tool returns, a queued one has
+// not started at all and a killed tree may still run, so the invalidation
+// repeats when it settles.
+function settleMutationCaches(shellEffects, backgroundJobId, runSettled = null) {
   const invalidate = () => {
     if (shellEffects.mutationMode === 'paths') {
       invalidateBuiltinResultCache(shellEffects.paths);
@@ -55,7 +60,7 @@ function settleMutationCaches(shellEffects, backgroundJobId, queuedSettled = nul
   if (backgroundJobId && shellEffects.mutationMode !== 'none') {
     subscribeShellJobSettled(backgroundJobId, invalidate);
   }
-  if (queuedSettled && shellEffects.mutationMode !== 'none') queuedSettled.then(invalidate).catch(() => {});
+  if (runSettled && shellEffects.mutationMode !== 'none') runSettled.then(invalidate).catch(() => {});
 }
 
 export async function executeBashTool(args, workDir, options = {}) {
@@ -89,7 +94,8 @@ export async function executeBashTool(args, workDir, options = {}) {
   const inputWake = backgroundOnTimeout ? beginInterruptibleTaskWait(options?.sessionId) : null;
   let backgrounded = false;
   let backgroundJobId = null;
-  let queuedSettled = null;
+  // A queued run, or a foreground tree that may outlive its result, settles later.
+  let runSettled = null;
   try {
     const invocation = await planShellInvocation({ command, resolvedSpec, cwd: bashWorkDir });
     if (invocation.failure) return invocation.failure;
@@ -127,7 +133,7 @@ export async function executeBashTool(args, workDir, options = {}) {
     });
     backgrounded = result.backgrounded === true;
     backgroundJobId = backgrounded ? result.jobId || null : null;
-    queuedSettled = backgrounded ? result.settled || null : null;
+    runSettled = result.settled || null;
     const stdout = stripAnsi(result.stdout || '');
     const stderr = stripAnsi(result.stderr || '');
     recordShellCaptureTelemetry(options?.resultTelemetry, result, stdout, stderr);
@@ -152,14 +158,13 @@ export async function executeBashTool(args, workDir, options = {}) {
     inputWake?.dispose();
     combinedAbort?.cleanup?.();
     if (hoisted.hoistPath) {
-      // A promoted or queued command still runs from the hoisted file; a
-      // foreground one is done with it now (an unconfirmed kill may keep it
-      // locked — retried).
-      if (queuedSettled) {
-        queuedSettled.then(() => removeTransportFileNow(hoisted.hoistPath)).catch(() => {});
-      } else if (backgrounded) cleanupArtifactOnTaskSettled(hoisted.hoistPath, backgroundJobId);
+      // A promoted or queued command still runs from the hoisted file, and so
+      // may a killed tree until it settles; a finished foreground one is done
+      // with it now (an unconfirmed kill may keep it locked — retried).
+      if (runSettled) cleanupArtifactAfter(hoisted.hoistPath, runSettled);
+      else if (backgrounded) cleanupArtifactOnTaskSettled(hoisted.hoistPath, backgroundJobId);
       else removeTransportFileNow(hoisted.hoistPath);
     }
-    settleMutationCaches(shellEffects, backgroundJobId, queuedSettled);
+    settleMutationCaches(shellEffects, backgroundJobId, runSettled);
   }
 }

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

@@ -87,7 +87,13 @@ export const BUILTIN_TOOLS = [
           type: 'integer',
           minimum: 1,
           maximum: PUBLIC_READ_WINDOW_MAX,
-          description: 'Maximum line count; default 500 per exact file, 25 per glob-expanded file; batch default.',
+          description:
+            'Maximum line count; default 500 per exact file, 25 per glob-expanded file; batch default. Lines only: PDFs use pages.',
+        },
+        pages: {
+          type: 'string',
+          description:
+            'PDF page range "N" or "N-M", 1-based, ≤20 pages per call. Text pages return text; scanned pages (no text layer) return page images, or OCR text on a text-only model. Without pages, a PDF over 10 pages returns its first 5 pages and page count.',
         },
       },
       required: ['file_path'],

package/src/runtime/agent/orchestrator/tools/builtin/lib/shell-job-records.mjs

@@ -24,7 +24,7 @@ import { access, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/p
 import { unlinkSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { writeJsonAtomicAsync } from '../../../../../shared/atomic-file.mjs';
+import { holdsNoData, writeJsonAtomicAsync } from '../../../../../shared/atomic-file.mjs';
 import { isPidAlive } from '../../../../../shared/pid-liveness.mjs';
 import { displayShellCommand } from '../../../../../shared/shell-display.mjs';
 import { tryAdmitWorkspaceActivity } from '../../../../../shared/worktrees/activity-gate.mjs';
@@ -339,23 +339,11 @@ export function releaseShellJobWorkspace(jobId) {
   if (workspaceLeases.get(key) === leave) workspaceLeases.delete(key);
 }
 
-/** True once `sessionId` closed in this runtime. */
-export function isShellOwnerSessionClosed(sessionId) {
-  return closedOwnerSessions.has(String(sessionId || '').trim());
-}
-
 /** Flag a still-open job record as "termination unconfirmed" for the readouts. */
 export function markShellJobTerminationUnconfirmed(jobId) {
   return patchRunningShellJobRecord(jobId, { terminationUnconfirmed: true });
 }
 
-/** Record the pids a held job's termination watch last found alive, so a
- *  reader in another process can tell a live hold from a stale one. */
-export function noteShellJobSurvivors(jobId, pids) {
-  const survivorPids = (pids || []).map(Number).filter((pid) => Number.isInteger(pid) && pid > 0);
-  return patchRunningShellJobRecord(jobId, { survivorPids });
-}
-
 function patchRunningShellJobRecord(jobId, patch) {
   const key = validJobId(jobId);
   if (!key) return Promise.resolve(false);
@@ -431,7 +419,11 @@ export async function readShellJobRecord(jobId, { strict = false } = {}) {
   const dir = jobsDir();
   const jsonPath = join(dir, `${key}.json`);
   try {
-    const record = JSON.parse(await readFile(jsonPath, 'utf8'));
+    const text = await readFile(jsonPath, 'utf8');
+    // A crash left no data (fsync is off for these records): nothing to inspect,
+    // the same as no record, even for a strict reader.
+    if (holdsNoData(text)) return null;
+    const record = JSON.parse(text);
     if (
       strict &&
       (!record ||

package/src/runtime/agent/orchestrator/tools/builtin/pdf-test-fixtures.mjs

@@ -1,11 +1,14 @@
 // Deterministic PDF fixtures shared by the read and MCP media tests.
-export function makePdf(pageCount) {
+// `pageText(index)` is the text of page index+1; null draws a filled box and
+// no text, like a scanned page without a text layer.
+export function makePdf(pageCount, { pageText = (i) => `Page ${i + 1}` } = {}) {
   const objs = ['<< /Type /Catalog /Pages 2 0 R >>'];
   const kids = Array.from({ length: pageCount }, (_, i) => `${4 + i * 2} 0 R`);
   objs.push(`<< /Type /Pages /Kids [${kids.join(' ')}] /Count ${pageCount} >>`);
   objs.push('<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>');
   for (let i = 0; i < pageCount; i += 1) {
-    const stream = `BT /F1 12 Tf 10 10 Td (Page ${i + 1}) Tj ET`;
+    const text = pageText(i);
+    const stream = text === null ? '0.2 g 20 20 160 160 re f' : `BT /F1 12 Tf 10 10 Td (${text}) Tj ET`;
     objs.push(
       `<< /Type /Page /Parent 2 0 R /MediaBox [0 0 200 200] /Contents ${5 + i * 2} 0 R /Resources << /Font << /F1 3 0 R >> >> >>`
     );
@@ -44,4 +47,3 @@ export function makeEncryptedPdf() {
   out += `trailer\n<< /Size 5 /Root 1 0 R /Encrypt 4 0 R /ID [<${'cd'.repeat(16)}> <${'cd'.repeat(16)}>] >>\nstartxref\n${xref}\n%%EOF\n`;
   return Buffer.from(out, 'latin1');
 }
-

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

@@ -37,8 +37,10 @@ export function imageMimeForPath(p) {
 // behaviour (refuse over-cap originals with an isError text result, else emit
 // the raw base64 image block). Decoder rejection is an explicit tool error;
 // corrupt bytes must never enter model history.
-export async function readImageAsContent(fullPath, displayPath, preflightStat = null) {
-  const mimeType = imageMimeForPath(fullPath);
+// `knownMimeType` names the image type of a path whose extension does not
+// (a stored attachment, recognized by its signature).
+export async function readImageAsContent(fullPath, displayPath, preflightStat = null, knownMimeType = null) {
+  const mimeType = knownMimeType || imageMimeForPath(fullPath);
   if (!mimeType) return null;
   let st;
   try {

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