mixdog 1.3.0 → 1.3.2

package/src/runtime/agent/orchestrator/session/transcript-restore/user-text.mjs

@@ -11,6 +11,7 @@
  *   moves a long block into the attachment store; it is read back from there.
  */
 import { isAttachmentReference, readAttachmentTextWithin } from '../../../../attachments/store.mjs';
+import { isMediaReferencePart } from '../../../../attachments/attachment-reference.mjs';
 import { toolResultText } from './tool-result-text.mjs';
 
 const IMAGE_METADATA_LINE = /\[Image(?::| source:) [^\]\r\n]+\]\s*$/;
@@ -116,14 +117,85 @@ function referencedFeedbackText(part) {
   }
 }
 
+const PASTED_LINES = /· (\d+) lines?$/;
+const PASTED_TEXT_MAX_BYTES = 1024 * 1024;
+/** Blob bytes one transcript load may read to count the lines of pastes
+ *  whose stored name does not carry the count (pastes stored before it did). */
+export const PASTED_LINE_READ_BUDGET_BYTES = 4 * 1024 * 1024;
+
+/** A stored plain-text prompt part's text within the load's byte budget, else ''. */
+function offloadedPromptText(part, budget) {
+  const allowance = Math.min(PASTED_TEXT_MAX_BYTES, budget.remaining);
+  if (allowance <= 0) return '';
+  try {
+    const text = readAttachmentTextWithin(part, allowance);
+    if (text == null) return '';
+    budget.remaining -= Buffer.byteLength(text, 'utf8');
+    return text;
+  } catch (error) {
+    if (error?.code !== 'ENOENT') budget.remaining -= allowance;
+    return '';
+  }
+}
+
+/** Visible lines of a stored paste (as `pastedTextLineCount` counts them), or
+ *  null when the count would take a read past the load's budget. */
+function storedPasteLines(part, budget) {
+  const named = PASTED_LINES.exec(String(part.filename || ''));
+  if (named) return Number(named[1]);
+  const allowance = Math.min(PASTED_TEXT_MAX_BYTES, budget.remaining);
+  if (allowance <= 0) return null;
+  try {
+    const read = readAttachmentTextWithin(part, allowance);
+    if (read == null) return null;
+    budget.remaining -= Buffer.byteLength(read, 'utf8');
+    const value = read.replace(/\r\n?/g, '\n').replace(/\n+$/, '');
+    return value ? value.split('\n').length : 0;
+  } catch (error) {
+    // A blob that failed its integrity check was read before it failed: the
+    // read counts against the cap (at most the allowance). A missing blob
+    // read nothing.
+    if (error?.code !== 'ENOENT') budget.remaining -= allowance;
+    return null;
+  }
+}
+
+/** The chip token a stored pasted / attached text stood for in the live
+ *  bubble (intake moved its body into the store and dropped the token). A
+ *  paste whose line count is unknown shows as the plain `[Pasted text #n]`. */
+function storedTextToken(part, number, budget) {
+  if (part?.type !== 'text') return '';
+  if (part.textKind === 'paste') {
+    const lines = storedPasteLines(part, budget);
+    return lines == null ? `[Pasted text #${number}]` : `[Pasted text #${number} +${lines} lines]`;
+  }
+  if (part.textKind === 'file') return `[File #${number}: ${part.filename || 'attachment.txt'}]`;
+  return '';
+}
+
 /** The display lines of a stored prompt's parts, and for each image part the
  *  line that draws it: the composer's metadata line right before it, else a
- *  bare line of its own (a bare line never stands for the next image). */
-function restoredUserParts(content) {
+ *  bare line of its own (a bare line never stands for the next image). A
+ *  stored pasted or attached text shows as its chip token. */
+function restoredUserParts(content, budget) {
   const texts = [];
   const images = [];
   let pendingMetadata = '';
+  let storedTexts = 0;
+  // Plain text the intake moved into the store (a long prompt, a bot's message).
+  const offloaded = [];
+  let companionText = false;
   for (const part of content) {
+    // An attachment sent by reference is model-facing text; the bubble shows
+    // the attachment as the chip its message records.
+    if (isMediaReferencePart(part)) continue;
+    const token = isAttachmentReference(part) ? storedTextToken(part, storedTexts + 1, budget) : '';
+    if (token) {
+      storedTexts += 1;
+      texts.push(token);
+      pendingMetadata = '';
+      continue;
+    }
     if (part?.type === 'image' || part?.type === 'input_image') {
       let line = pendingMetadata;
       if (!line) {
@@ -135,27 +207,72 @@ function restoredUserParts(content) {
       continue;
     }
     const text = isAttachmentReference(part) ? referencedFeedbackText(part) : toolResultText([part]);
-    if (text) texts.push(text);
+    if (text) {
+      texts.push(text);
+      if (!IMAGE_METADATA_LINE.test(text)) companionText = true;
+    } else if (isAttachmentReference(part) && part?.type === 'text' && !part.textKind) {
+      // Keeps its place among the parts until it is known whether to read it.
+      texts.push(part);
+      offloaded.push(part);
+    }
     pendingMetadata = IMAGE_METADATA_LINE.test(text) ? text.trimEnd().split(/\r?\n/).pop().trim() : '';
   }
-  return { texts, images };
+  // A prompt whose only real text was moved out restores it in place (bounded,
+  // within the load's read budget); image labels and chips are not companion
+  // text. Beside real text such parts stay out, as before.
+  const resolved = [];
+  for (const entry of texts) {
+    if (typeof entry === 'string') resolved.push(entry);
+    else if (!companionText) {
+      const text = offloadedPromptText(entry, budget);
+      if (text) resolved.push(text);
+    }
+  }
+  return { texts: resolved, images };
+}
+
+/**
+ * The user-bubble projection of one transcript load: each stored prompt's
+ * parts are worked out once (its text and its image refs share them, and a
+ * load that widens its range sees the same messages again), and the blob
+ * reads that count paste lines share one byte budget.
+ */
+export function createUserTextRestore({ readBudgetBytes = PASTED_LINE_READ_BUDGET_BYTES } = {}) {
+  const budget = { remaining: readBudgetBytes };
+  const parts = new WeakMap();
+  const partsOf = (content) => {
+    let found = parts.get(content);
+    if (!found) {
+      found = restoredUserParts(content, budget);
+      parts.set(content, found);
+    }
+    return found;
+  };
+  return {
+    text(content) {
+      if (!Array.isArray(content)) {
+        return withVisualizeFeedbackDisplay(typeof content === 'string' ? content : toolResultText(content));
+      }
+      return withVisualizeFeedbackDisplay(partsOf(content).texts.join('\n'));
+    },
+    /** The stored original of each image the restored bubble draws, by the
+     *  `[Image: …]` line that draws it. Every image keeps its slot (one
+     *  without a stored original has no `ref`) so later images do not shift
+     *  onto it; empty when no image has a stored original. */
+    imageRefs(content) {
+      if (!Array.isArray(content)) return [];
+      const slots = partsOf(content).images.map(({ part, line }) =>
+        isAttachmentReference(part) ? { line, ref: part.attachmentRef } : { line }
+      );
+      return slots.some((slot) => slot.ref) ? slots : [];
+    },
+  };
 }
 
 export function restoredUserText(content) {
-  if (!Array.isArray(content)) {
-    return withVisualizeFeedbackDisplay(typeof content === 'string' ? content : toolResultText(content));
-  }
-  return withVisualizeFeedbackDisplay(restoredUserParts(content).texts.join('\n'));
+  return createUserTextRestore().text(content);
 }
 
-/** The stored original of each image the restored bubble draws, by the
- *  `[Image: …]` line that draws it. Every image keeps its slot (one without a
- *  stored original has no `ref`) so later images do not shift onto it; empty
- *  when no image has a stored original. */
 export function restoredUserImageRefs(content) {
-  if (!Array.isArray(content)) return [];
-  const slots = restoredUserParts(content).images.map(({ part, line }) =>
-    isAttachmentReference(part) ? { line, ref: part.attachmentRef } : { line }
-  );
-  return slots.some((slot) => slot.ref) ? slots : [];
+  return createUserTextRestore().imageRefs(content);
 }

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 {