pum-agent 0.2.34-beta.2 → 0.2.35-beta.1

package/src/file-checkpoints.ts

@@ -0,0 +1,337 @@
+import {
+  createEditToolDefinition, createReadToolDefinition, createWriteToolDefinition, withFileMutationQueue,
+  type AgentSession, type InlineExtension,
+} from "@earendil-works/pi-coding-agent";
+import { createHash, randomUUID } from "node:crypto";
+import { constants, type Stats } from "node:fs";
+import { access, lstat, mkdir, open, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { AGENT_DIR } from "./config";
+import { getCheckModeConfig } from "./check-mode";
+import { pathSensitivity } from "./check-mutation";
+import { validateSandboxPath } from "./filesystem-sandbox";
+import { canonicalPathIdentityAllowMissing, isPathInsideOrSame } from "./platform";
+import { FileMutationGuard, type MutationAdmission } from "./file-mutation-guard";
+
+export const CHECKPOINT_MAX_FILE_BYTES = 1024 * 1024;
+export const CHECKPOINT_MAX_BYTES = 8 * 1024 * 1024;
+export const CHECKPOINT_MAX_RECORDS = 32;
+
+type Snapshot = { bytes: Buffer; fingerprint: string };
+export type FileCheckpointInfo = {
+  id: string; path: string; toolName: "write" | "edit"; createdAt: number;
+  bytes: number; priorAbsent: boolean;
+};
+type Record = FileCheckpointInfo & { before: Buffer | null; after: string };
+type Pending = { path: string; before: Buffer | null; after: string };
+const controllers = new Map<string, FileCheckpointController>();
+type CheckpointBinding = { controller?: FileCheckpointController; readAutoResize?: () => boolean };
+const bindings = new Map<string, CheckpointBinding>();
+/** AgentSession.dispose does NOT emit session_shutdown (notably worker closure). */
+export function bindFileCheckpointSession(session: Pick<AgentSession, "sessionId" | "dispose">
+  & { settingsManager?: Pick<AgentSession["settingsManager"], "getImageAutoResize"> }): void {
+  const id = session.sessionId;
+  const settings = session.settingsManager;
+  const binding: CheckpointBinding = {
+    controller: controllers.get(id),
+    readAutoResize: settings ? () => settings.getImageAutoResize() : undefined,
+  };
+  bindings.set(id, binding);
+  const dispose = session.dispose.bind(session);
+  session.dispose = () => {
+    try { dispose(); }
+    finally {
+      binding.controller?.dispose();
+      if (controllers.get(id) === binding.controller) controllers.delete(id);
+      if (bindings.get(id) === binding) bindings.delete(id);
+    }
+  };
+}
+export function checkpointControllerForSession(sessionId: string): FileCheckpointController | undefined {
+  return controllers.get(sessionId);
+}
+function metadata(stat: Stats): string {
+  return [stat.dev, stat.ino, stat.mode, stat.nlink, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+}
+function digest(bytes: Buffer): string { return createHash("sha256").update(bytes).digest("hex"); }
+function missing(error: unknown): boolean { return (error as NodeJS.ErrnoException)?.code === "ENOENT"; }
+class CheckpointConflictError extends Error {}
+class RecoveryError extends Error {}
+/** Only our finite recovery errors may reach the UI; raw IO failures stay private. */
+export function checkpointRecoveryFailureText(error: unknown): string {
+  return error instanceof RecoveryError ? error.message
+    : "Checkpoint recovery failed; no in-place restore was attempted. List checkpoints to check availability.";
+}
+
+/** Runtime-private bytes. No persistence, model restore tool, or original-file restore. */
+export class FileCheckpointController {
+  private records: Record[] = [];
+  private retainedBytes = 0;
+  private skipped = 0;
+  private evicted = 0;
+  private disposed = false;
+  private generation = 0;
+  readonly mutationGuard: FileMutationGuard;
+  constructor(
+    private readonly cwd: string,
+    private readonly allowedPaths: () => readonly string[] = () => getCheckModeConfig().additionalPaths ?? [],
+    private readonly agentDir = AGENT_DIR,
+    private readonly checkpoints = true,
+  ) { this.mutationGuard = new FileMutationGuard(cwd, allowedPaths); }
+
+  private async validate(path: string): Promise<string> {
+    const target = await validateSandboxPath(this.cwd, path, this.allowedPaths(), "write");
+    const identity = await canonicalPathIdentityAllowMissing(target.absolute);
+    const config = await canonicalPathIdentityAllowMissing(this.agentDir);
+    if (isPathInsideOrSame(config, identity) || pathSensitivity(identity).credential) {
+      throw new Error("Checkpoint path is private or credential-sensitive.");
+    }
+    return target.absolute;
+  }
+
+  private async snapshot(path: string): Promise<Snapshot | null> {
+    await this.validate(path);
+    let stat: Stats;
+    try { stat = await lstat(path); } catch (error) { if (missing(error)) return null; throw error; }
+    if (!stat.isFile() || stat.nlink !== 1 || stat.size > CHECKPOINT_MAX_FILE_BYTES) {
+      throw new Error("Checkpoint requires a singly linked regular file of at most 1 MiB.");
+    }
+    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+      const initial = await handle.stat();
+      if (metadata(initial) !== metadata(stat)) throw new CheckpointConflictError("Checkpoint file changed while opening; mutation refused.");
+      // Never use readFile: a concurrently growing file must not allocate unbounded memory.
+      const bytes = Buffer.alloc(stat.size + 1);
+      let offset = 0;
+      while (offset < bytes.length) {
+        const result = await handle.read(bytes, offset, bytes.length - offset, offset);
+        if (!result.bytesRead) break;
+        offset += result.bytesRead;
+      }
+      const final = await handle.stat();
+      await this.validate(path);
+      const named = await lstat(path);
+      if (offset !== stat.size || metadata(final) !== metadata(stat) || metadata(named) !== metadata(stat)) {
+        throw new CheckpointConflictError("Checkpoint file changed while reading; mutation refused.");
+      }
+      const content = Buffer.from(bytes.subarray(0, offset));
+      return { bytes: content, fingerprint: `${metadata(stat)}:${digest(content)}` };
+    } finally { await handle.close(); }
+  }
+
+  list(): FileCheckpointInfo[] {
+    return this.records.map(({ before: _before, after: _after, ...info }) => ({ ...info }));
+  }
+  summary(): string {
+    return `Runtime-only file-tool recovery copies: ${this.records.length}/32 checkpoints, ${this.retainedBytes}/8388608 bytes; ${this.skipped} skipped, ${this.evicted} evicted. Maximum file 1 MiB; oldest evicted first. No Bash coverage. Lost on clear, runtime replacement, worker closure or exit. Originals are never restored in place.`;
+  }
+  clear(): void {
+    this.generation++;
+    this.records = [];
+    this.retainedBytes = 0;
+    this.skipped = 0;
+    this.evicted = 0;
+  }
+  dispose(): void { this.disposed = true; this.clear(); this.mutationGuard.dispose(); }
+
+  /** Execute through pi's native queue and exact write/edit argument and diff contracts. */
+  async execute(
+    toolName: "write" | "edit", toolCallId: string, input: any,
+    signal?: AbortSignal, onUpdate?: any, requirePrepared = false,
+  ): Promise<any> {
+    if (this.disposed) throw new Error("Checkpoint runtime is disposed.");
+    const generation = this.generation;
+    return this.mutationGuard.run(toolName, toolCallId, input, signal,
+      (admission) => this.executeAdmitted(toolName, toolCallId, input, admission, generation, signal, onUpdate), requirePrepared);
+  }
+
+  private async executeAdmitted(
+    toolName: "write" | "edit", toolCallId: string, input: any, admission: MutationAdmission,
+    generation: number, signal?: AbortSignal, onUpdate?: any,
+  ): Promise<any> {
+    let writtenContent: string | undefined;
+    let pending: Pending | undefined;
+    let readState: Snapshot | undefined;
+    let skip = false;
+    const captureWrite = async (path: string, content: string) => {
+      // This runs inside the SDK mutation queue, immediately at its write boundary.
+      await validateSandboxPath(this.cwd, path, this.allowedPaths(), "write");
+      let before: Snapshot | null | undefined;
+      try {
+        // Stable-read protection also applies in headless mode. Disabling
+        // recovery retention must not turn a supported edit into a failure.
+        before = await this.snapshot(path);
+        if (readState && before?.fingerprint !== readState.fingerprint) {
+          throw new CheckpointConflictError("Checkpoint conflict: file changed since edit read; mutation refused.");
+        }
+      } catch (error) {
+        if (readState || error instanceof CheckpointConflictError) throw error;
+        skip = true;
+      }
+      // A skipped capture must never bypass a boundary that changed during IO.
+      await validateSandboxPath(this.cwd, path, this.allowedPaths(), "write");
+      await this.mutationGuard.assertUnchanged(admission);
+      if (signal?.aborted || this.disposed) throw new Error("Operation aborted");
+      await writeFile(path, content, "utf8");
+      writtenContent = content;
+      if (!this.checkpoints) return;
+      if (skip || before === undefined || Buffer.byteLength(content) > CHECKPOINT_MAX_FILE_BYTES) { skip = true; return; }
+      try {
+        const after = await this.snapshot(path);
+        if (!after || !after.bytes.equals(Buffer.from(content, "utf8"))) { skip = true; return; }
+        pending = { path, before: before?.bytes ?? null, after: after.fingerprint };
+      } catch { skip = true; }
+    };
+    const write = createWriteToolDefinition(this.cwd, { operations: {
+      mkdir: async (path) => {
+        await validateSandboxPath(this.cwd, path, this.allowedPaths(), "write");
+        if (signal?.aborted || this.disposed) throw new Error("Operation aborted");
+        await mkdir(path, { recursive: true });
+      }, writeFile: captureWrite,
+    } });
+    const edit = createEditToolDefinition(this.cwd, { operations: {
+      access: async (path) => { await access(path, constants.R_OK | constants.W_OK); },
+      readFile: async (path) => {
+        // Oversized edits retain native functionality, without checkpoint coverage.
+        await validateSandboxPath(this.cwd, path, this.allowedPaths(), "write");
+        try { readState = (await this.snapshot(path)) ?? undefined; }
+        catch (error) {
+          if (error instanceof CheckpointConflictError) throw error;
+          skip = true;
+        }
+        if (readState) return Buffer.from(readState.bytes);
+        const { readFile } = await import("node:fs/promises");
+        return readFile(path);
+      }, writeFile: captureWrite,
+    } });
+    const tool = toolName === "write" ? write : edit;
+    let result = await tool.execute(toolCallId, input, signal, onUpdate, { cwd: this.cwd } as any);
+    if (signal?.aborted || this.disposed) return result;
+    if (writtenContent !== undefined) {
+      try { await this.mutationGuard.didWrite(admission, writtenContent); }
+      catch { admission.notice = "File changed or became unavailable after writing; read it again before further mutations."; }
+    }
+    if (admission.notice) result = { ...result, content: [...result.content, { type: "text", text: admission.notice }] };
+    if (!this.checkpoints || generation !== this.generation) return result;
+    let note: string;
+    if (!skip && pending) {
+      const record: Record = {
+        id: randomUUID(), path: pending.path, toolName, createdAt: Date.now(),
+        bytes: pending.before?.length ?? 0, priorAbsent: pending.before === null,
+        before: pending.before, after: pending.after,
+      };
+      while (this.records.length >= CHECKPOINT_MAX_RECORDS || this.retainedBytes + record.bytes > CHECKPOINT_MAX_BYTES) {
+        this.retainedBytes -= this.records.shift()!.bytes;
+        this.evicted++;
+      }
+      this.records.push(record);
+      this.retainedBytes += record.bytes;
+      note = record.priorAbsent
+        ? "Checkpoint records prior absence; no preimage to recover and no automatic deletion."
+        : "Runtime-only file checkpoint retained; user may export a recovery copy with /checkpoint. No in-place rewind.";
+    } else {
+      this.skipped++;
+      note = "No file checkpoint retained (unsupported, oversized, unavailable or concurrently changed file).";
+    }
+    return { ...result, content: [...result.content, { type: "text", text: note }] };
+  }
+
+  /** User-only export. Never write, rename over, chmod or unlink the original. */
+  async recover(id: string): Promise<string> {
+    const record = this.records.find((item) => item.id === id);
+    if (!record || this.disposed) throw new RecoveryError("Checkpoint unavailable or expired.");
+    if (record.before === null) throw new RecoveryError("File was newly created: no prior bytes to recover. Original was not deleted.");
+    const generation = this.generation;
+    const preimage = record.before;
+    return withFileMutationQueue(record.path, async () => {
+      const current = await this.snapshot(record.path);
+      if (current?.fingerprint !== record.after) throw new RecoveryError("Checkpoint conflict: original changed; no recovery file created.");
+      if (generation !== this.generation || this.disposed) throw new RecoveryError("Checkpoint expired during recovery.");
+      // Random flat sibling, independent of a potentially special source basename.
+      const destination = join(dirname(record.path), `pum-recovery-${randomUUID()}.txt`);
+      await this.validate(destination);
+      let handle;
+      try { handle = await open(destination, "wx", 0o600); }
+      catch { throw new RecoveryError("Recovery file could not be exclusively created. Original is unchanged."); }
+      try {
+        // Validate the opened name again BEFORE releasing any private preimage bytes.
+        await this.validate(destination);
+        const opened = await handle.stat();
+        const linked = await lstat(destination);
+        if (!opened.isFile() || opened.nlink !== 1 || opened.size !== 0
+          || metadata(opened) !== metadata(linked)
+          || generation !== this.generation || this.disposed) {
+          throw new Error("Recovery destination changed before write");
+        }
+        await handle.writeFile(preimage);
+        await handle.sync();
+        await this.validate(destination);
+        const exported = await this.snapshot(destination);
+        const own = await handle.stat();
+        const named = await lstat(destination);
+        const final = await this.snapshot(record.path);
+        if (metadata(own) !== metadata(named) || !exported?.bytes.equals(preimage)
+          || final?.fingerprint !== record.after || generation !== this.generation || this.disposed) {
+          throw new Error("Recovery validation conflict");
+        }
+      } catch {
+        // Never unlink by name: another writer may have replaced/edited the artifact.
+        throw new RecoveryError(`Recovery failed or conflicted; possible partial recovery file: ${JSON.stringify(destination)}. Original was not changed by recovery.`);
+      } finally {
+        try { await handle.close(); }
+        catch { throw new RecoveryError(`Recovery close failed; inspect possible recovery file: ${JSON.stringify(destination)}. Original was not changed by recovery.`); }
+      }
+      return destination;
+    });
+  }
+}
+
+/** A fresh extension instance per runtime; no state survives session replacement. */
+export function createFileCheckpointExtension(options: { readonly?: boolean; checkpoints?: boolean } = {}): InlineExtension {
+  return {
+    name: "pum-file-checkpoints",
+    factory(pi) {
+      if (options.readonly) return;
+      let controller: FileCheckpointController | undefined;
+      let sessionId: string | undefined;
+      let retired = false;
+      const obtain = (ctx: { cwd: string; sessionManager: { getSessionId(): string } }) => {
+        const id = ctx.sessionManager.getSessionId();
+        if (retired || (sessionId !== undefined && sessionId !== id)) throw new Error("Checkpoint runtime is unavailable.");
+        if (!controller) {
+          controller = new FileCheckpointController(ctx.cwd, undefined, undefined, options.checkpoints !== false);
+          sessionId = id;
+          controllers.set(id, controller);
+          const binding = bindings.get(id);
+          if (binding) binding.controller = controller;
+        }
+        return controller;
+      };
+      pi.on("session_start", (_event, ctx) => { obtain(ctx); });
+      pi.on("session_shutdown", () => {
+        retired = true;
+        controller?.dispose();
+        if (sessionId && controllers.get(sessionId) === controller) controllers.delete(sessionId);
+        controller = undefined;
+      });
+      pi.on("before_agent_start", (event) => ({
+        systemPrompt: `${event.systemPrompt}\n\n## Shared file mutation guard\n\nRead existing files before write/edit. Changed read/proposal baselines reject stale writes and overlapping edits; exact unique unchanged edit targets can preserve other changes. On conflict, reread and reconcile, coordinate ownership or use spawn_subagent with worktree: true. This is process-local conflict detection, not filesystem isolation: Bash, user shells and external editors are not locked or checkpointed.`,
+      }));
+      pi.on("tool_call", async (event, ctx) => {
+        if (event.toolName !== "write" && event.toolName !== "edit") return;
+        try { await obtain(ctx).mutationGuard.prepare(event.toolName, event.toolCallId, event.input); }
+        catch (error) { return { block: true, reason: error instanceof Error ? error.message : "File mutation proposal unavailable." }; }
+      });
+      pi.on("tool_result", (event) => { controller?.mutationGuard.forgetProposal(event.input); });
+      pi.on("agent_end", () => { controller?.mutationGuard.clearProposals(); });
+      const read = createReadToolDefinition(process.cwd());
+      pi.registerTool({ ...read, execute: (id, args, signal, onUpdate, ctx) => obtain(ctx).mutationGuard.read(
+        id, args, signal, onUpdate, ctx, bindings.get(ctx.sessionManager.getSessionId())?.readAutoResize?.(),
+      ) });
+      const write = createWriteToolDefinition(process.cwd());
+      const edit = createEditToolDefinition(process.cwd());
+      pi.registerTool({ ...write, execute: (id, args, signal, onUpdate, ctx) => obtain(ctx).execute("write", id, args, signal, onUpdate, true) });
+      pi.registerTool({ ...edit, execute: (id, args, signal, onUpdate, ctx) => obtain(ctx).execute("edit", id, args, signal, onUpdate, true) });
+    },
+  };
+}

package/src/file-mutation-guard.ts

@@ -0,0 +1,224 @@
+import { createReadToolDefinition, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createHash } from "node:crypto";
+import { constants, type Stats } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { getCheckModeConfig } from "./check-mode";
+import { validateSandboxPath } from "./filesystem-sandbox";
+import { canonicalPathIdentityAllowMissing } from "./platform";
+
+export const MUTATION_BASELINE_MAX_FILE_BYTES = 1024 * 1024;
+export const MUTATION_BASELINE_MAX_BYTES = 8 * 1024 * 1024;
+export const MUTATION_BASELINE_MAX_FILES = 128;
+const guidance = "Read the file again, reconcile the changes, and retry. Coordinate overlapping work or use spawn_subagent with worktree: true. Bash and external editors are not locked by this guard.";
+export class FileMutationConflictError extends Error {
+  constructor(reason: string) { super(`File mutation conflict: ${reason}. ${guidance}`); }
+}
+type Snapshot = { fingerprint: string; bytes?: Buffer; absent: boolean };
+type Proposal = {
+  path: string; key: string; inputKey: string; id: string; tool: "write" | "edit";
+  baseline: Snapshot; observed: boolean;
+};
+export type MutationAdmission = { path: string; current: Snapshot; rebased: boolean; notice?: string };
+const queues = new Map<string, Promise<void>>();
+
+function metadata(stat: Stats): string {
+  return [stat.dev, stat.ino, stat.mode, stat.nlink, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
+}
+function digest(bytes: Buffer): string { return createHash("sha256").update(bytes).digest("hex"); }
+function missing(error: unknown): boolean { return (error as NodeJS.ErrnoException)?.code === "ENOENT"; }
+function normalized(bytes: Buffer): string { return bytes.toString("utf8").replace(/^\uFEFF/, "").replace(/\r\n/g, "\n"); }
+function uniqueLines(text: string, needle: string): string | undefined {
+  const at = text.indexOf(needle);
+  if (!needle.length || at < 0 || text.indexOf(needle, at + 1) >= 0) return undefined;
+  // Include the whole touched lines, not just the substring: "value = 1" still
+  // matches "value = 10", but overwriting that prefix would clobber a newer edit.
+  const start = at === 0 ? 0 : text.lastIndexOf("\n", at - 1) + 1;
+  const end = text.indexOf("\n", at + needle.length - 1);
+  return text.slice(start, end < 0 ? text.length : end + 1);
+}
+/** Deliberately stricter than pi's fuzzy matcher when rebasing a stale proposal. */
+function unchangedEditTargets(before: Snapshot, now: Snapshot, input: any): boolean {
+  if (!before.bytes || !now.bytes || !Array.isArray(input.edits) || !input.edits.length) return false;
+  // Invalid UTF-8 / binary bytes cannot safely be reasoned about as text.
+  if (!Buffer.from(before.bytes.toString("utf8")).equals(before.bytes)
+    || !Buffer.from(now.bytes.toString("utf8")).equals(now.bytes)
+    || before.bytes.includes(0) || now.bytes.includes(0)) return false;
+  const currentText = now.bytes.toString("utf8");
+  // pi normalizes every line ending before editing and restores one style for
+  // the whole file. A stale rebase must not erase another writer's untouched
+  // mixed/bare-CR endings while claiming to preserve their changes. Uniform LF
+  // and CRLF round-trip; fresh (non-rebased) edits retain native behavior.
+  if (currentText.replace(/\r\n/g, "").includes("\r")
+    || (currentText.includes("\r\n") && /(?<!\r)\n/.test(currentText))) return false;
+  const a = normalized(before.bytes), b = normalized(now.bytes);
+  return input.edits.every((edit: any) => {
+    if (typeof edit?.oldText !== "string") return false;
+    const needle = normalized(Buffer.from(edit.oldText));
+    const original = uniqueLines(a, needle);
+    return original !== undefined && original === uniqueLines(b, needle);
+  });
+}
+
+/** Separate from pi's queue: canonical Windows/missing-path identities must also serialize. */
+async function inQueue<T>(key: string, run: () => Promise<T>): Promise<T> {
+  const previous = queues.get(key) ?? Promise.resolve();
+  let release!: () => void;
+  const current = new Promise<void>((resolve) => { release = resolve; });
+  const tail = previous.then(() => current);
+  queues.set(key, tail);
+  await previous;
+  try { return await run(); }
+  finally { release(); if (queues.get(key) === tail) queues.delete(key); }
+}
+
+/** Runtime-owned observations, never persisted, never populated from replay/model input. */
+export class FileMutationGuard {
+  private baselines = new Map<string, Snapshot>();
+  private retainedBytes = 0;
+  private proposals = new Map<object, Proposal>();
+  private proposalBytes = 0;
+  private disposed = false;
+  constructor(
+    private readonly cwd: string,
+    private readonly allowedPaths: () => readonly string[] = () => getCheckModeConfig().additionalPaths ?? [],
+  ) {}
+  dispose(): void {
+    this.disposed = true;
+    this.baselines.clear(); this.clearProposals(); this.retainedBytes = 0;
+  }
+  clearProposals(): void { this.proposals.clear(); this.proposalBytes = 0; }
+  forgetProposal(input: object): void {
+    this.proposalBytes -= this.proposals.get(input)?.baseline.bytes?.length ?? 0;
+    this.proposals.delete(input);
+  }
+  private live(): void { if (this.disposed) throw new Error("File mutation guard runtime is disposed."); }
+  private remember(key: string, value: Snapshot): void {
+    this.live();
+    const prior = this.baselines.get(key);
+    this.retainedBytes -= prior?.bytes?.length ?? 0;
+    this.baselines.delete(key);
+    while (this.baselines.size >= MUTATION_BASELINE_MAX_FILES
+      || this.retainedBytes + (value.bytes?.length ?? 0) > MUTATION_BASELINE_MAX_BYTES) {
+      const first = this.baselines.keys().next().value!;
+      this.retainedBytes -= this.baselines.get(first)?.bytes?.length ?? 0;
+      this.baselines.delete(first);
+    }
+    this.baselines.set(key, value);
+    this.retainedBytes += value.bytes?.length ?? 0;
+  }
+  private async target(path: string, operation: "read" | "write") {
+    this.live();
+    const { absolute } = await validateSandboxPath(this.cwd, path, this.allowedPaths(), operation);
+    return { path: absolute, key: await canonicalPathIdentityAllowMissing(absolute) };
+  }
+  private async snapshot(path: string, operation: "read" | "write"): Promise<Snapshot> {
+    await this.target(path, operation);
+    let stat: Stats;
+    try { stat = await lstat(path); }
+    catch (error) { if (missing(error)) return { fingerprint: "absent", absent: true }; throw error; }
+    if (!stat.isFile()) throw new FileMutationConflictError("target is not a regular file");
+    // Large files keep metadata-only observations, never allocate unbounded retained bytes.
+    if (stat.size > MUTATION_BASELINE_MAX_FILE_BYTES) return { fingerprint: metadata(stat), absent: false };
+    const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+      if (metadata(await handle.stat()) !== metadata(stat)) throw new FileMutationConflictError("file changed while opening");
+      const bytes = Buffer.alloc(stat.size + 1);
+      let size = 0;
+      while (size < bytes.length) {
+        const read = await handle.read(bytes, size, bytes.length - size, size);
+        if (!read.bytesRead) break;
+        size += read.bytesRead;
+      }
+      await this.target(path, operation);
+      if (size !== stat.size || metadata(await handle.stat()) !== metadata(stat)
+        || metadata(await lstat(path)) !== metadata(stat)) throw new FileMutationConflictError("file changed while reading");
+      const content = Buffer.from(bytes.subarray(0, size));
+      return { fingerprint: `${metadata(stat)}:${digest(content)}`, bytes: content, absent: false };
+    } finally { await handle.close(); }
+  }
+
+  /** Preserve native image handling and filename retries; observe only a stable successful read. */
+  async read(id: string, input: any, signal?: AbortSignal, onUpdate?: any, ctx?: ExtensionContext, autoResizeImages?: boolean): Promise<any> {
+    const target = await this.target(input.path, "read");
+    const before = await this.snapshot(target.path, "read");
+    const result = await createReadToolDefinition(this.cwd, { autoResizeImages }).execute(
+      id, input, signal, onUpdate, ctx ?? { cwd: this.cwd } as ExtensionContext,
+    );
+    const after = await this.snapshot(target.path, "read");
+    if (!signal?.aborted && !this.disposed && before.fingerprint === after.fingerprint) this.remember(target.key, before);
+    else if (!this.disposed) {
+      return { ...result, content: [...result.content, { type: "text", text: "File changed during read; no fresh mutation baseline recorded. Read it again before editing." }] };
+    }
+    return result;
+  }
+
+  /** Called at tool_call, before asynchronous Check review and before any parallel execution. */
+  async prepare(tool: "write" | "edit", id: string, input: any): Promise<void> {
+    const target = await this.target(input.path, "write");
+    const current = await this.snapshot(target.path, "write");
+    this.live();
+    const observed = this.baselines.get(target.key);
+    if (this.proposals.has(input)) throw new FileMutationConflictError("proposal object was reused");
+    const baseline = observed ?? current;
+    if (this.proposals.size >= MUTATION_BASELINE_MAX_FILES
+      || this.proposalBytes + (baseline.bytes?.length ?? 0) > MUTATION_BASELINE_MAX_BYTES) {
+      throw new FileMutationConflictError("too many pending file proposals or baseline bytes");
+    }
+    this.proposals.set(input, {
+      ...target, tool, id, inputKey: JSON.stringify(input), baseline, observed: !!observed,
+    });
+    this.proposalBytes += baseline.bytes?.length ?? 0;
+  }
+
+  /** Proposals are consumed exactly once; every queued execution rechecks its immutable baseline. */
+  async run<T>(tool: "write" | "edit", id: string, input: any, signal: AbortSignal | undefined,
+    execute: (admission: MutationAdmission) => Promise<T>, requirePrepared = false): Promise<T> {
+    if (!this.proposals.has(input)) {
+      if (requirePrepared) throw new FileMutationConflictError("prepared proposal is missing or expired");
+      await this.prepare(tool, id, input);
+    }
+    const proposal = this.proposals.get(input)!;
+    this.forgetProposal(input);
+    if (proposal.id !== id || proposal.tool !== tool || proposal.inputKey !== JSON.stringify(input)) throw new FileMutationConflictError("proposal arguments changed");
+    return inQueue(proposal.key, async () => {
+      this.live();
+      if (signal?.aborted) throw new Error("Operation aborted");
+      const target = await this.target(input.path, "write");
+      if (target.key !== proposal.key) throw new FileMutationConflictError("target identity changed");
+      const current = await this.snapshot(target.path, "write");
+      const changed = proposal.baseline.fingerprint !== current.fingerprint;
+      if (changed && !(tool === "edit" && unchangedEditTargets(proposal.baseline, current, input))) {
+        throw new FileMutationConflictError("baseline changed since this runtime's read or mutation proposal");
+      }
+      const admission: MutationAdmission = {
+        path: target.path, current, rebased: changed,
+        notice: changed
+          ? "File baseline changed outside the exact, unique edit targets and their lines; preserved those other changes. Read again before further mutations."
+          : !proposal.observed && !current.absent
+            ? "No prior read baseline was available; only changes since this proposal were checked. Read existing files before mutating them; use worktrees for overlapping work."
+            : undefined,
+      };
+      if (!current.absent && !current.bytes) admission.notice = (admission.notice ? `${admission.notice} ` : "")
+        + "Large-file conflict detection uses metadata only (over 1 MiB); no stale edit rebasing.";
+      // Waiting for another runtime and filesystem validation are asynchronous;
+      // the exact prepared object must still carry the originally pinned args.
+      if (proposal.inputKey !== JSON.stringify(input)) throw new FileMutationConflictError("proposal arguments changed");
+      return execute(admission);
+    });
+  }
+
+  /** Invoke immediately before the actual write, inside both mutation queues. Not filesystem CAS. */
+  async assertUnchanged(admission: MutationAdmission): Promise<void> {
+    this.live();
+    const current = await this.snapshot(admission.path, "write");
+    if (current.fingerprint !== admission.current.fingerprint) throw new FileMutationConflictError("file changed during mutation execution");
+  }
+  async didWrite(admission: MutationAdmission, content: string): Promise<void> {
+    if (this.disposed || admission.rebased) return; // Do not bless unseen changes from a safe rebase.
+    const after = await this.snapshot(admission.path, "write");
+    if (after.bytes?.equals(Buffer.from(content)) || (!after.absent && !after.bytes)) {
+      const { key } = await this.target(admission.path, "write");
+      if (!this.disposed) this.remember(key, after);
+    } else throw new FileMutationConflictError("postimage changed after writing");
+  }
+}

package/src/filesystem-sandbox.ts

@@ -219,12 +219,15 @@ function toolPath(input: Record<string, unknown>): string | undefined {
 /** Enforce the process-local filesystem sandbox before built-in tool execution. */
 export type FilesystemSandboxExtensionOptions = {
   readonly?: boolean;
+  /** Names the restricted role in refusals: a readonly child, or plan mode (#51). */
+  roleLabel?: string;
 };
 
 export function createFilesystemSandboxExtension(
   options: FilesystemSandboxExtensionOptions = {},
 ): InlineExtension {
   const readonly = options.readonly === true;
+  const role = options.roleLabel ?? "readonly child";
   return {
     name: readonly ? "pum-readonly-filesystem-sandbox" : "pum-filesystem-sandbox",
     factory(pi) {
@@ -232,7 +235,7 @@ export function createFilesystemSandboxExtension(
       pi.on("before_agent_start", (event) => ({
         systemPrompt: `${event.systemPrompt}\n\n## Filesystem sandbox\n\n`
           + "- The read, write, and edit tools are limited to the project and configured allowed roots.\n"
-          + (readonly ? "- This readonly child cannot use write or edit.\n" : "")
+          + (readonly ? `- This ${role} cannot use write or edit.\n` : "")
           + "- The read tool may also read the temporary files PUM stages for you, such as pasted text and full bash output.\n"
           + "- Do not access credential-sensitive paths or paths through symbolic links or junctions.\n"
           + "- Do not attempt to bypass the filesystem sandbox with alternate path spellings.",
@@ -243,7 +246,7 @@ export function createFilesystemSandboxExtension(
         const toolName = event.toolName as FilesystemSandboxToolName;
         try {
           if (readonly && toolName !== "read") {
-            throw new Error(`readonly child cannot use ${toolName}`);
+            throw new Error(`${role} cannot use ${toolName}`);
           }
           const allowedPaths = getCheckModeConfig().additionalPaths;
           const path = toolPath(event.input);