mixdog 0.7.1

package/scripts/mutation-io-smoke.mjs

@@ -0,0 +1,1081 @@
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+process.env.CLAUDE_PLUGIN_ROOT ||= ROOT;
+const DATA_DIR = join(tmpdir(), `mixdog-mutation-io-smoke-data-${process.pid}`);
+process.env.CLAUDE_PLUGIN_DATA = DATA_DIR;
+process.env.MIXDOG_HINT_LEVEL ||= 'normal';
+
+const { executeBuiltinTool, recordReadSnapshotForPath } = await import(pathToFileURL(join(ROOT, 'src/agent/orchestrator/tools/builtin.mjs')).href);
+const { executePatchTool } = await import(pathToFileURL(join(ROOT, 'src/agent/orchestrator/tools/patch.mjs')).href);
+
+const LINE_SEP = '→';
+const dir = await mkdtemp(join(tmpdir(), 'mixdog-mutation-io-smoke-'));
+
+function assertOk(label, out) {
+  if (/^Error/.test(String(out))) throw new Error(`${label}: ${out}`);
+}
+
+function assertError(label, out, wanted = 'Error') {
+  if (!String(out).startsWith(wanted)) throw new Error(`${label}: expected ${wanted}, got ${out}`);
+}
+
+function assertHas(label, text, wanted) {
+  if (!String(text).includes(wanted)) throw new Error(`${label}: missing ${JSON.stringify(wanted)} in ${JSON.stringify(String(text).slice(0, 300))}`);
+}
+
+function assertNotHas(label, text, unwanted) {
+  if (String(text).includes(unwanted)) throw new Error(`${label}: unexpected ${JSON.stringify(unwanted)} in ${JSON.stringify(String(text).slice(0, 300))}`);
+}
+
+async function expectFile(path, expected) {
+  const got = await readFile(join(dir, path), 'utf8');
+  if (got !== expected) throw new Error(`${path}: got ${JSON.stringify(got)}, expected ${JSON.stringify(expected)}`);
+}
+
+async function expectBytes(path, expected) {
+  const got = await readFile(join(dir, path));
+  if (!got.equals(expected)) throw new Error(`${path}: got ${got.toString('hex')}, expected ${expected.toString('hex')}`);
+}
+
+function expectNodeCheck(path) {
+  const fullPath = join(dir, path);
+  const out = spawnSync(process.execPath, ['--check', fullPath], { encoding: 'utf8' });
+  if (out.status !== 0) {
+    throw new Error(`${path}: node --check failed\n${out.stdout || ''}${out.stderr || ''}`);
+  }
+}
+
+function hashBytes(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+function patchText(lines) {
+  return `${lines.join('\n')}\n`;
+}
+
+async function patchAndCheck(label, file, patch, expected) {
+  const out = await executePatchTool('apply_patch', { patch, base_path: dir }, dir, { readStateScope: `patch-${label}` });
+  assertOk(`patch ${label}`, out);
+  await expectFile(file, expected);
+}
+
+async function warmRead(path, scope, offset = 0, limit = 20) {
+  assertOk(`read ${path}`, await executeBuiltinTool('read', { path, offset, limit }, dir, { readStateScope: scope }));
+}
+
+async function rmTree(path) {
+  await rm(path, { recursive: true, force: true, maxRetries: 5, retryDelay: 50 });
+}
+
+try {
+  await writeFile(join(dir, 'patch.txt'), 'a\nb\nc\n', 'utf8');
+  await patchAndCheck('replace', 'patch.txt', patchText([
+    '--- a/patch.txt',
+    '+++ b/patch.txt',
+    '@@ -2,1 +2,1 @@',
+    '-b',
+    '+B',
+  ]), 'a\nB\nc\n');
+
+  await writeFile(join(dir, 'delete.txt'), 'a\nb\nc\n', 'utf8');
+  await patchAndCheck('delete', 'delete.txt', patchText([
+    '--- a/delete.txt',
+    '+++ b/delete.txt',
+    '@@ -2,1 +2,0 @@',
+    '-b',
+  ]), 'a\nc\n');
+
+  await writeFile(join(dir, 'crlf.txt'), 'a\r\nb\r\nc\r\n', 'utf8');
+  await patchAndCheck('crlf', 'crlf.txt', patchText([
+    '--- a/crlf.txt',
+    '+++ b/crlf.txt',
+    '@@ -2,1 +2,1 @@',
+    '-b',
+    '+B',
+  ]), 'a\r\nB\r\nc\r\n');
+
+  await writeFile(join(dir, 'crlf-delete.txt'), 'a\r\nb\r\nc\r\n', 'utf8');
+  await patchAndCheck('crlf-delete', 'crlf-delete.txt', patchText([
+    '--- a/crlf-delete.txt',
+    '+++ b/crlf-delete.txt',
+    '@@ -2,1 +2,0 @@',
+    '-b',
+  ]), 'a\r\nc\r\n');
+
+  await writeFile(join(dir, 'binary-ish.txt'), Buffer.from([0xff, 0xfe, 0x0a, 0x61, 0x0a, 0x62, 0x0a]));
+  const binaryPatch = await executePatchTool('apply_patch', { patch: patchText([
+    '--- a/binary-ish.txt',
+    '+++ b/binary-ish.txt',
+    '@@ -2,1 +2,1 @@',
+    '-a',
+    '+A',
+  ]), base_path: dir }, dir, { readStateScope: 'patch-binary-ish' });
+  assertOk('patch binary-ish exact byte splice', binaryPatch);
+  await expectBytes('binary-ish.txt', Buffer.from([0xff, 0xfe, 0x0a, 0x41, 0x0a, 0x62, 0x0a]));
+
+  await writeFile(join(dir, 'delete-eof-no-newline.txt'), 'a\nb', 'utf8');
+  await patchAndCheck('delete eof no newline', 'delete-eof-no-newline.txt', patchText([
+    '--- a/delete-eof-no-newline.txt',
+    '+++ b/delete-eof-no-newline.txt',
+    '@@ -2,1 +2,0 @@',
+    '-b',
+    '\',
+  ]), 'a\n');
+
+  await writeFile(join(dir, 'insert.txt'), 'a\nc\n', 'utf8');
+  await patchAndCheck('insert only', 'insert.txt', patchText([
+    '--- a/insert.txt',
+    '+++ b/insert.txt',
+    '@@ -1,0 +2,1 @@',
+    '+b',
+  ]), 'a\nb\nc\n');
+
+  await writeFile(join(dir, 'crlf-insert.txt'), 'a\r\nc\r\n', 'utf8');
+  await patchAndCheck('crlf insert only', 'crlf-insert.txt', patchText([
+    '--- a/crlf-insert.txt',
+    '+++ b/crlf-insert.txt',
+    '@@ -1,0 +2,1 @@',
+    '+b',
+  ]), 'a\r\nb\r\nc\r\n');
+
+  await writeFile(join(dir, 'v4a-update.txt'), 'class Foo\n  function bar\n    const x = 1;\n    return x;\n', 'utf8');
+  const v4aUpdate = await executePatchTool('apply_patch', { patch: patchText([
+    '*** Begin Patch',
+    '*** Update File: "v4a-update.txt"\t2026-05-21',
+    '@@ class Foo',
+    '@@ function bar',
+    '     const x = 1;',
+    '-    return x;',
+    '+    return x + 1;',
+    '*** End Patch',
+  ]), base_path: dir }, dir, { readStateScope: 'patch-v4a-update' });
+  assertOk('patch v4a update', v4aUpdate);
+  await expectFile('v4a-update.txt', 'class Foo\n  function bar\n    const x = 1;\n    return x + 1;\n');
+
+  // V4A real paths under a top-level `a/` or `b/` directory must not be
+  // diff-prefix-stripped (those prefixes are a unified-diff convention only).
+  // Regression: stripping rewrote `a/foo.txt` -> `foo.txt`, hitting the wrong
+  // file (ENOENT on update, phantom create on add).
+  await mkdir(join(dir, 'a'), { recursive: true });
+  await writeFile(join(dir, 'a', 'v4a-ab.txt'), 'class Foo\n  const x = 1;\n  return x;\n', 'utf8');
+  const v4aTopLevelA = await executePatchTool('apply_patch', { patch: patchText([
+    '*** Begin Patch',
+    '*** Update File: a/v4a-ab.txt',
+    '@@ class Foo',
+    '   const x = 1;',
+    '-  return x;',
+    '+  return x + 1;',
+    '*** End Patch',
+  ]), base_path: dir }, dir, { readStateScope: 'patch-v4a-toplevel-a' });
+  assertOk('patch v4a update under top-level a/', v4aTopLevelA);
+  await expectFile(join('a', 'v4a-ab.txt'), 'class Foo\n  const x = 1;\n  return x + 1;\n');
+  assertNotHas('no phantom strip of top-level a/', v4aTopLevelA, 'unreadable');
+  await mkdir(join(dir, 'b'), { recursive: true });
+  const v4aTopLevelB = await executePatchTool('apply_patch', { patch: patchText([
+    '*** Begin Patch',
+    '*** Add File: b/v4a-new.txt',
+    '+hello',
+    '+world',
+    '*** End Patch',
+  ]), base_path: dir }, dir, { readStateScope: 'patch-v4a-toplevel-b' });
+  assertOk('patch v4a add under top-level b/', v4aTopLevelB);
+  await expectFile(join('b', 'v4a-new.txt'), 'hello\nworld\n');
+
+  await writeFile(join(dir, 'v4a-tolerant-context.txt'), 'function pick\nconst x = 1;\nreturn x;\n', 'utf8');
+  const v4aTolerantContext = await executePatchTool('apply_patch', { patch: patchText([
+    '*** Begin Patch',
+    '*** Update File: v4a-tolerant-context.txt',
+    '@@ function pick @@',
+    'const x = 1;',
+    '-return x;',
+    '+return x + 1;',
+    '*** End Patch',
+  ]), base_path: dir, format: 'v4a' }, dir, { readStateScope: 'patch-v4a-tolerant-context' });
+  assertOk('patch v4a accepts trailing anchor marker and bare context', v4aTolerantContext);
+  await expectFile('v4a-tolerant-context.txt', 'function pick\nconst x = 1;\nreturn x + 1;\n');
+
+  await writeFile(join(dir, 'v4a-js-syntax.mjs'), [
+    'export function pick(ok) {',
+    '  if (ok) {',
+    '    return 1;',
+    '  }',
+    '  return 0;',
+    '}',
+    '',
+  ].join('\n'), 'utf8');
+  const v4aSyntax = await executePatchTool('apply_patch', { patch: patchText([
+    '*** Begin Patch',
+    '*** Update File: v4a-js-syntax.mjs',
+    '@@ function pick',
+    '   if (ok) {',
+    '-    return 1;',
+    '+    return 2;',
+    '   }',
+    '*** End Patch',
+  ]), base_path: dir, format: 'v4a' }, dir, { readStateScope: 'patch-v4a-js-syntax' });
+  assertOk('patch v4a keeps js syntax', v4aSyntax);
+  await expectFile('v4a-js-syntax.mjs', [
+    'export function pick(ok) {',
+    '  if (ok) {',
+    '    return 2;',
+    '  }',
+    '  return 0;',
+    '}',
+    '',
+  ].join('\n'));
+  expectNodeCheck('v4a-js-syntax.mjs');
+
+  await writeFile(join(dir, 'v4a-reject-no-partial.mjs'), 'export function f() {\n  return 1;\n}\n', 'utf8');
+  let v4aReject;
+  try {
+    v4aReject = await executePatchTool('apply_patch', { patch: patchText([
+      '*** Begin Patch',
+      '*** Update File: v4a-reject-no-partial.mjs',
+      '@@ function f',
+      '-  return missing;',
+      '+  return 2;',
+      '*** End Patch',
+    ]), base_path: dir, format: 'v4a' }, dir, { readStateScope: 'patch-v4a-reject-no-partial' });
+  } catch (err) {
+    v4aReject = `Error: ${err?.message || String(err)}`;
+  }
+  assertError('patch v4a rejects missing context', v4aReject);
+  assertHas('patch v4a missing context hint includes expected line', v4aReject, 'expected first old line');
+  assertHas('patch v4a missing context hint includes nearest line', v4aReject, 'nearest line');
+  await expectFile('v4a-reject-no-partial.mjs', 'export function f() {\n  return 1;\n}\n');
+  expectNodeCheck('v4a-reject-no-partial.mjs');
+
+  await writeFile(join(dir, 'v4a-insert.txt'), 'class Foo\n  function bar\n    return x;\n', 'utf8');
+  const v4aInsert = await executePatchTool('apply_patch', { patch: patchText([
+    '*** Begin Patch',
+    '*** Update File: v4a-insert.txt',
+    '@@ function bar',
+    '+    const y = 2;',
+    '*** End Patch',
+  ]), base_path: dir, format: 'v4a' }, dir, { readStateScope: 'patch-v4a-insert' });
+  assertOk('patch v4a insert', v4aInsert);
+  await expectFile('v4a-insert.txt', 'class Foo\n  function bar\n    const y = 2;\n    return x;\n');
+
+  await writeFile(join(dir, 'v4a-missing-anchor-insert.txt'), 'class Foo\n  function bar\n    return x;\n', 'utf8');
+  let v4aMissingAnchorInsert;
+  try {
+    v4aMissingAnchorInsert = await executePatchTool('apply_patch', { patch: patchText([
+      '*** Begin Patch',
+      '*** Update File: v4a-missing-anchor-insert.txt',
+      '@@ function missing',
+      '+    const nope = true;',
+      '*** End Patch',
+    ]), base_path: dir, format: 'v4a' }, dir, { readStateScope: 'patch-v4a-missing-anchor-insert' });
+  } catch (err) {
+    v4aMissingAnchorInsert = `Error: ${err?.message || String(err)}`;
+  }
+  assertError('patch v4a missing anchor insert rejects', v4aMissingAnchorInsert);
+  assertHas('patch v4a missing anchor insert guidance', v4aMissingAnchorInsert, 'anchor not found');
+  assertHas('patch v4a missing anchor nearest guidance', v4aMissingAnchorInsert, 'nearest anchor candidate');
+  assertHas('patch v4a missing anchor nearest line', v4aMissingAnchorInsert, 'function bar');
+  await expectFile('v4a-missing-anchor-insert.txt', 'class Foo\n  function bar\n    return x;\n');
+
+  await writeFile(join(dir, 'bare-unified-anchor.txt'), 'class Foo\n  function bar\n    return x;\n', 'utf8');
+  const bareUnifiedAnchor = await executePatchTool('apply_patch', { patch: patchText([
+    '--- a/bare-unified-anchor.txt',
+    '+++ b/bare-unified-anchor.txt',
+    '@@ function bar',
+    '-    return x;',
+    '+    return x + 2;',
+  ]), base_path: dir }, dir, { readStateScope: 'patch-bare-unified-anchor' });
+  assertOk('patch bare unified anchor', bareUnifiedAnchor);
+  await expectFile('bare-unified-anchor.txt', 'class Foo\n  function bar\n    return x + 2;\n');
+
+  let strictBareUnified;
+  try {
+    strictBareUnified = await executePatchTool('apply_patch', { patch: patchText([
+      '--- a/bare-unified-anchor.txt',
+      '+++ b/bare-unified-anchor.txt',
+      '@@ function bar',
+      '-    return x + 2;',
+      '+    return x + 3;',
+    ]), base_path: dir, format: 'unified' }, dir, { readStateScope: 'patch-strict-bare-unified' });
+  } catch (err) {
+    strictBareUnified = `Error: ${err?.message || String(err)}`;
+  }
+  assertError('patch strict unified bare hunk guidance rejects', strictBareUnified);
+  assertHas('patch strict unified bare hunk counted hint', strictBareUnified, '@@ -A,B +C,D @@');
+  assertNotHas('patch strict unified bare hunk v4a hint removed', strictBareUnified, 'remove format:"unified"');
+  await expectFile('bare-unified-anchor.txt', 'class Foo\n  function bar\n    return x + 2;\n');
+
+  await writeFile(join(dir, 'unified-nearest-hint.txt'), 'alpha\nbeta current\ngamma\n', 'utf8');
+  const unifiedNearestHint = await executePatchTool('apply_patch', { patch: patchText([
+    '--- a/unified-nearest-hint.txt',
+    '+++ b/unified-nearest-hint.txt',
+    '@@ -2,1 +2,1 @@',
+    '-beta stale',
+    '+beta done',
+  ]), base_path: dir, reject_partial: false }, dir, { readStateScope: 'patch-unified-nearest-hint' });
+  assertError('patch unified hunk nearest hint rejects', unifiedNearestHint);
+  assertHas('patch unified hunk nearest expected line', unifiedNearestHint, 'expected first old/context line');
+  assertHas('patch unified hunk nearest current line', unifiedNearestHint, 'nearest line 2');
+  await expectFile('unified-nearest-hint.txt', 'alpha\nbeta current\ngamma\n');
+
+  await writeFile(join(dir, 'dry-run-context-preview.txt'), 'actual\n', 'utf8');
+  const dryRunContextPreview = await executePatchTool('apply_patch', { patch: patchText([
+    '--- a/dry-run-context-preview.txt',
+    '+++ b/dry-run-context-preview.txt',
+    '@@ -1,1 +1,2 @@',
+    ' stale context',
+    '+inserted',
+  ]), base_path: dir, dry_run: true, fuzzy: false, reject_partial: false }, dir, { readStateScope: 'patch-dry-run-context-preview' });
+  assertError('patch dry-run context mismatch reports without writing', dryRunContextPreview);
+  assertHas('patch dry-run context mismatch expected line', dryRunContextPreview, 'expected first old/context line');
+  assertHas('patch dry-run context mismatch context line', dryRunContextPreview, 'stale context');
+  assertHas('patch dry-run context mismatch current line marker', dryRunContextPreview, 'nearest line 1');
+  assertHas('patch dry-run context mismatch current line', dryRunContextPreview, 'actual');
+  assertNotHas('patch dry-run context mismatch retry block removed', dryRunContextPreview, '*** Update File: dry-run-context-preview.txt');
+  assertNotHas('patch dry-run context mismatch retry hint removed', dryRunContextPreview, 'read({path,line,context})');
+  await expectFile('dry-run-context-preview.txt', 'actual\n');
+
+  const bareUnifiedAdd = await executePatchTool('apply_patch', { patch: patchText([
+    '--- /dev/null',
+    '+++ b/bare-unified-add.txt',
+    '@@',
+    '+made',
+  ]), base_path: dir }, dir, { readStateScope: 'patch-bare-unified-add' });
+  assertOk('patch bare unified add', bareUnifiedAdd);
+  await expectFile('bare-unified-add.txt', 'made\n');
+
+  await writeFile(join(dir, 'bare-unified-delete.txt'), 'remove\nme\n', 'utf8');
+  const bareUnifiedDelete = await executePatchTool('apply_patch', { patch: patchText([
+    '--- a/bare-unified-delete.txt',
+    '+++ /dev/null',
+    '@@',
+    '-remove',
+    '-me',
+  ]), base_path: dir }, dir, { readStateScope: 'patch-bare-unified-delete' });
+  assertOk('patch bare unified delete', bareUnifiedDelete);
+  try {
+    await readFile(join(dir, 'bare-unified-delete.txt'), 'utf8');
+    throw new Error('bare unified delete left file on disk');
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err;
+  }
+
+  const v4aAdd = await executePatchTool('apply_patch', { patch: patchText([
+    '*** Begin Patch',
+    '*** Add File: v4a-add.txt',
+    '+hello',
+    '+',
+    '+world',
+    '*** End Patch',
+  ]), base_path: dir, format: 'v4a' }, dir, { readStateScope: 'patch-v4a-add' });
+  assertOk('patch v4a add', v4aAdd);
+  await expectFile('v4a-add.txt', 'hello\n\nworld\n');
+
+  await writeFile(join(dir, 'v4a-empty-delete.txt'), '', 'utf8');
+  const v4aDeleteEmpty = await executePatchTool('apply_patch', { patch: patchText([
+    '*** Begin Patch',
+    '*** Delete File: v4a-empty-delete.txt',
+    '*** End Patch',
+  ]), base_path: dir, format: 'v4a' }, dir, { readStateScope: 'patch-v4a-delete-empty' });
+  assertOk('patch v4a empty delete', v4aDeleteEmpty);
+  try {
+    await readFile(join(dir, 'v4a-empty-delete.txt'), 'utf8');
+    throw new Error('v4a empty delete left file on disk');
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err;
+  }
+
+  await writeFile(join(dir, 'unified-empty-delete.txt'), '', 'utf8');
+  const unifiedEmptyDelete = await executePatchTool('apply_patch', { patch: patchText([
+    '--- a/unified-empty-delete.txt',
+    '+++ /dev/null',
+    '@@ -1,0 +0,0 @@',
+  ]), base_path: dir }, dir, { readStateScope: 'patch-unified-empty-delete' });
+  assertOk('patch unified zero-length empty delete', unifiedEmptyDelete);
+  try {
+    await readFile(join(dir, 'unified-empty-delete.txt'), 'utf8');
+    throw new Error('unified empty delete left file on disk');
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err;
+  }
+
+  await writeFile(join(dir, 'unified-nonempty-zero-delete.txt'), 'still here\n', 'utf8');
+  const unifiedNonemptyZeroDelete = await executePatchTool('apply_patch', { patch: patchText([
+    '--- a/unified-nonempty-zero-delete.txt',
+    '+++ /dev/null',
+    '@@ -1,0 +0,0 @@',
+  ]), base_path: dir }, dir, { readStateScope: 'patch-unified-nonempty-zero-delete' });
+  assertError('patch unified zero-length non-empty delete rejects', unifiedNonemptyZeroDelete);
+  assertHas('patch unified zero-length non-empty delete residual hint', unifiedNonemptyZeroDelete, 'residual byte');
+  await expectFile('unified-nonempty-zero-delete.txt', 'still here\n');
+
+  await writeFile(join(dir, 'mf-a.txt'), 'a\nb\n', 'utf8');
+  await writeFile(join(dir, 'mf-b.txt'), 'x\ny\n', 'utf8');
+  const multifileOut = await executePatchTool('apply_patch', { patch: patchText([
+    '--- a/mf-a.txt',
+    '+++ b/mf-a.txt',
+    '@@ -2,1 +2,1 @@',
+    '-b',
+    '+B',
+    '--- a/mf-b.txt',
+    '+++ b/mf-b.txt',
+    '@@ -2,1 +2,1 @@',
+    '-y',
+    '+Y',
+  ]), base_path: dir }, dir, { readStateScope: 'patch-multifile' });
+  assertOk('patch multifile', multifileOut);
+  await expectFile('mf-a.txt', 'a\nB\n');
+  await expectFile('mf-b.txt', 'x\nY\n');
+
+  await writeFile(join(dir, 'patch-edit-chain.txt'), 'before\nneedle\n', 'utf8');
+  const patchEditScope = 'patch-edit-chain';
+  assertOk('patch edit chain patch', await executePatchTool('apply_patch', {
+    patch: patchText([
+      '--- a/patch-edit-chain.txt',
+      '+++ b/patch-edit-chain.txt',
+      '@@ -1,2 +1,2 @@',
+      '-before',
+      '+after',
+      ' needle',
+    ]),
+    base_path: dir,
+    reject_partial: false,
+  }, dir, { readStateScope: patchEditScope }));
+  assertOk('patch edit chain edit', await executeBuiltinTool('edit', {
+    path: 'patch-edit-chain.txt',
+    old_string: 'needle',
+    new_string: 'done',
+  }, dir, { readStateScope: patchEditScope }));
+  await expectFile('patch-edit-chain.txt', 'after\ndone\n');
+
+  await writeFile(join(dir, 'delete-snapshot.txt'), 'same\n', 'utf8');
+  await warmRead('delete-snapshot.txt', 'patch-delete-snapshot');
+  const deleteSnapshotOut = await executePatchTool('apply_patch', { patch: patchText([
+    '--- a/delete-snapshot.txt',
+    '+++ /dev/null',
+    '@@ -1,1 +0,0 @@',
+    '-same',
+  ]), base_path: dir }, dir, { readStateScope: 'patch-delete-snapshot' });
+  assertOk('patch delete clears snapshot', deleteSnapshotOut);
+  await writeFile(join(dir, 'delete-snapshot.txt'), 'same\n', 'utf8');
+  const staleWrite = await executeBuiltinTool('write', {
+    path: 'delete-snapshot.txt',
+    content: 'clobbered\n',
+  }, dir, { readStateScope: 'patch-delete-snapshot' });
+  assertError('deleted file snapshot cleared before overwrite', staleWrite, 'Error [code 6]');
+  await expectFile('delete-snapshot.txt', 'same\n');
+
+  assertOk('write seeds edit snapshot/cache', await executeBuiltinTool('write', {
+    path: 'write-edit-cache.txt',
+    content: 'alpha\nbeta\ngamma\n',
+  }, dir, { readStateScope: 'write-edit-cache' }));
+  assertOk('edit after write without read', await executeBuiltinTool('edit', {
+    path: 'write-edit-cache.txt',
+    old_string: 'beta',
+    new_string: 'BETA',
+  }, dir, { readStateScope: 'write-edit-cache' }));
+  await expectFile('write-edit-cache.txt', 'alpha\nBETA\ngamma\n');
+
+  await writeFile(join(dir, 'read-edit-invalidate.txt'), 'one\ntwo\nthree\n', 'utf8');
+  const readEditBefore = await executeBuiltinTool('read', {
+    path: 'read-edit-invalidate.txt',
+    offset: 1,
+    limit: 1,
+  }, dir, { readStateScope: 'read-edit-invalidate' });
+  assertHas('read before edit cache seed', readEditBefore, `2${LINE_SEP}two`);
+  assertOk('edit invalidates same read cache key', await executeBuiltinTool('edit', {
+    path: 'read-edit-invalidate.txt',
+    old_string: 'two',
+    new_string: 'TWO',
+  }, dir, { readStateScope: 'read-edit-invalidate' }));
+  const readEditAfter = await executeBuiltinTool('read', {
+    path: 'read-edit-invalidate.txt',
+    offset: 1,
+    limit: 1,
+  }, dir, { readStateScope: 'read-edit-invalidate' });
+  assertHas('read after edit sees fresh content', readEditAfter, `2${LINE_SEP}TWO`);
+  if (String(readEditAfter).includes(`2${LINE_SEP}two`)) {
+    throw new Error(`read cache returned stale pre-edit content:\n${readEditAfter}`);
+  }
+
+  await writeFile(join(dir, 'read-patch-invalidate.txt'), 'one\ntwo\nthree\n', 'utf8');
+  const readPatchBefore = await executeBuiltinTool('read', {
+    path: 'read-patch-invalidate.txt',
+    offset: 1,
+    limit: 1,
+  }, dir, { readStateScope: 'read-patch-invalidate' });
+  assertHas('read before patch cache seed', readPatchBefore, `2${LINE_SEP}two`);
+  assertOk('apply_patch invalidates same read cache key', await executePatchTool('apply_patch', {
+    patch: patchText([
+      '--- a/read-patch-invalidate.txt',
+      '+++ b/read-patch-invalidate.txt',
+      '@@ -2,1 +2,1 @@',
+      '-two',
+      '+TWO',
+    ]),
+    base_path: dir,
+  }, dir, { readStateScope: 'read-patch-invalidate' }));
+  const readPatchAfter = await executeBuiltinTool('read', {
+    path: 'read-patch-invalidate.txt',
+    offset: 1,
+    limit: 1,
+  }, dir, { readStateScope: 'read-patch-invalidate' });
+  assertHas('read after patch sees fresh content', readPatchAfter, `2${LINE_SEP}TWO`);
+  if (String(readPatchAfter).includes(`2${LINE_SEP}two`)) {
+    throw new Error(`read cache returned stale pre-patch content:\n${readPatchAfter}`);
+  }
+
+  assertOk('batch write seeds edit snapshot/cache', await executeBuiltinTool('write', {
+    writes: [
+      { path: 'batch-write-cache-a.txt', content: 'one\ntwo\n' },
+      { path: 'batch-write-cache-b.txt', content: 'red\nblue\n' },
+    ],
+  }, dir, { readStateScope: 'batch-write-cache' }));
+  assertOk('edit after batch write without read', await executeBuiltinTool('edit', {
+    path: 'batch-write-cache-b.txt',
+    old_string: 'blue',
+    new_string: 'BLUE',
+  }, dir, { readStateScope: 'batch-write-cache' }));
+  await expectFile('batch-write-cache-b.txt', 'red\nBLUE\n');
+
+  await writeFile(join(dir, 'io-cache-stress.txt'), 'alpha\nbeta\ngamma\n', 'utf8');
+  const stressScope = 'io-cache-stress';
+  const stressRead = await executeBuiltinTool('read', { path: 'io-cache-stress.txt' }, dir, { readStateScope: stressScope });
+  assertHas('stress read seeds snapshot', stressRead, `2${LINE_SEP}beta`);
+  assertOk('stress edit invalidates cache', await executeBuiltinTool('edit', {
+    path: 'io-cache-stress.txt',
+    old_string: 'beta',
+    new_string: 'BETA',
+  }, dir, { readStateScope: stressScope }));
+  assertOk('stress patch after edit', await executePatchTool('apply_patch', { patch: patchText([
+    '--- a/io-cache-stress.txt',
+    '+++ b/io-cache-stress.txt',
+    '@@ -3,1 +3,1 @@',
+    '-gamma',
+    '+GAMMA',
+  ]), base_path: dir }, dir, { readStateScope: stressScope }));
+  const stressAfterPatch = await executeBuiltinTool('read', {
+    path: 'io-cache-stress.txt',
+    offset: 0,
+    limit: 3,
+  }, dir, { readStateScope: stressScope });
+  assertHas('stress read after patch fresh', stressAfterPatch, `3${LINE_SEP}GAMMA`);
+  assertOk('stress write after patch snapshot', await executeBuiltinTool('write', {
+    path: 'io-cache-stress.txt',
+    content: 'final\n',
+  }, dir, { readStateScope: stressScope }));
+  const stressFinal = await executeBuiltinTool('read', { path: 'io-cache-stress.txt' }, dir, { readStateScope: stressScope });
+  assertHas('stress final read fresh', stressFinal, `1${LINE_SEP}final`);
+
+  await writeFile(join(dir, 'dry-run-keeps-cache.txt'), 'target\n', 'utf8');
+  assertOk('dry-run cache warm read', await executeBuiltinTool('read', { path: 'dry-run-keeps-cache.txt' }, dir, { readStateScope: 'dry-run-keeps-cache' }));
+  assertOk('dry-run does not write', await executePatchTool('apply_patch', { patch: patchText([
+    '--- a/dry-run-keeps-cache.txt',
+    '+++ b/dry-run-keeps-cache.txt',
+    '@@ -1,1 +1,1 @@',
+    '-target',
+    '+DRY-RUN',
+  ]), base_path: dir, dry_run: true }, dir, { readStateScope: 'dry-run-keeps-cache' }));
+  assertOk('edit still works after dry-run', await executeBuiltinTool('edit', {
+    path: 'dry-run-keeps-cache.txt',
+    old_string: 'target',
+    new_string: 'DONE',
+  }, dir, { readStateScope: 'dry-run-keeps-cache' }));
+  await expectFile('dry-run-keeps-cache.txt', 'DONE\n');
+
+  const readMissingPath = await executeBuiltinTool('read', {}, dir, { readStateScope: 'read-missing-path' });
+  assertError('read missing path concise', readMissingPath);
+  assertNotHas('read missing path no call shape', readMissingPath, 'read({path');
+  const editMissingPath = await executeBuiltinTool('edit', {
+    old_string: 'x',
+    new_string: 'y',
+  }, dir, { readStateScope: 'edit-missing-path' });
+  assertError('edit missing path concise', editMissingPath);
+  assertNotHas('edit missing path no call shape', editMissingPath, 'edit({path');
+
+  await writeFile(join(dir, 'glob-async-stat.js'), 'console.log("ok");\n', 'utf8');
+  await writeFile(join(dir, 'glob-async-stat.txt'), 'nope\n', 'utf8');
+  const globOut = await executeBuiltinTool('glob', {
+    pattern: '*.js',
+    path: dir,
+    head_limit: 5,
+  }, dir, { readStateScope: 'glob-async-stat' });
+  assertOk('glob async stat path', globOut);
+  assertHas('glob async stat result', globOut, 'glob-async-stat.js');
+
+  const grepLines = Array.from({ length: 300 }, (_, i) => `needle-${i + 1}`).join('\n') + '\n';
+  await writeFile(join(dir, 'grep-window.txt'), grepLines, 'utf8');
+  const grepWindow = await executeBuiltinTool('grep', {
+    pattern: 'needle',
+    path: 'grep-window.txt',
+    output_mode: 'content',
+    head_limit: 5,
+  }, dir, { readStateScope: 'grep-window' });
+  assertOk('grep windowed stream', grepWindow);
+  assertHas('grep windowed first result', grepWindow, 'needle-1');
+  assertHas('grep windowed more-matches truncation', grepWindow, 'more matches exist');
+  assertHas('grep windowed count-mode hint', grepWindow, "output_mode:'count'");
+  if (String(grepWindow).includes('needle-200')) {
+    throw new Error('grep windowed stream collected far beyond the requested window');
+  }
+  const grepMissingPattern = await executeBuiltinTool('grep', {
+    path: dir,
+  }, dir, { readStateScope: 'grep-missing-pattern' });
+  assertError('grep missing pattern concise', grepMissingPattern, 'Error: grep requires pattern');
+  assertNotHas('grep missing pattern no example', grepMissingPattern, 'grep({ pattern');
+  const grepMissingPath = await executeBuiltinTool('grep', {
+    pattern: 'needle',
+    path: 'missing-root',
+  }, dir, { readStateScope: 'grep-missing-path' });
+  assertError('grep missing path concise', grepMissingPath, 'Error: path does not exist');
+  assertNotHas('grep missing path no existing-root hint', grepMissingPath, 'existing search root');
+  assertNotHas('grep missing path no next-call example', grepMissingPath, 'grep({pattern:"needle"');
+  await writeFile(join(dir, 'grep-quote-minimal.txt'), 'quoteNeedle\nregexNeedle\n', 'utf8');
+  const grepQuotedPattern = await executeBuiltinTool('grep', {
+    pattern: "'quoteNeedle'",
+    path: 'grep-quote-minimal.txt',
+    output_mode: 'content',
+  }, dir, { readStateScope: 'grep-quoted-pattern' });
+  assertOk('grep quoted pattern no-match minimal', grepQuotedPattern);
+  assertHas('grep quoted pattern no-match marker', grepQuotedPattern, '(no matches)');
+  assertNotHas('grep quoted pattern no hint', grepQuotedPattern, 'without surrounding quotes');
+  const grepRegexLiteralPattern = await executeBuiltinTool('grep', {
+    pattern: '/regexNeedle/',
+    path: 'grep-quote-minimal.txt',
+    output_mode: 'content',
+  }, dir, { readStateScope: 'grep-regex-literal-pattern' });
+  assertOk('grep regex literal no-match minimal', grepRegexLiteralPattern);
+  assertNotHas('grep regex literal no hint', grepRegexLiteralPattern, 'without slashes or flags');
+  const grepUnknownType = await executeBuiltinTool('grep', {
+    pattern: 'quoteNeedle',
+    path: 'grep-quote-minimal.txt',
+    type: 'definitely-not-a-type',
+  }, dir, { readStateScope: 'grep-unknown-type' });
+  assertError('grep unknown type concise', grepUnknownType);
+  assertNotHas('grep unknown type no glob alternative', grepUnknownType, 'glob:"*.mjs"');
+  await mkdir(join(dir, 'scripts'));
+  await writeFile(join(dir, 'scripts', 'one.mjs'), 'needle via path glob\n', 'utf8');
+  const grepGlobPath = await executeBuiltinTool('grep', {
+    pattern: 'needle',
+    path: 'scripts/*.mjs',
+    output_mode: 'content',
+  }, dir, { readStateScope: 'grep-glob-path' });
+  assertOk('grep path glob auto-lift', grepGlobPath);
+  assertHas('grep path glob auto-lift result', grepGlobPath, 'needle via path glob');
+  const grepGlobFallback = await executeBuiltinTool('grep', {
+    path: 'scripts/*.mjs',
+  }, dir, { readStateScope: 'grep-glob-fallback' });
+  assertError('grep path glob without pattern stays strict', grepGlobFallback, 'Error: grep requires pattern');
+  const globPathFallback = await executeBuiltinTool('glob', {
+    path: 'scripts/*.mjs',
+    head_limit: 5,
+  }, dir, { readStateScope: 'glob-path-fallback' });
+  assertOk('glob path fallback', globPathFallback);
+  assertHas('glob path fallback result', globPathFallback, 'scripts/one.mjs');
+  const globQuotedPattern = await executeBuiltinTool('glob', {
+    pattern: "'*.mjs'",
+    path: 'scripts',
+    head_limit: 5,
+  }, dir, { readStateScope: 'glob-quoted-pattern' });
+  assertOk('glob quoted pattern no-files minimal', globQuotedPattern);
+  assertHas('glob quoted pattern marker', globQuotedPattern, '(no files found)');
+  assertNotHas('glob quoted pattern no hint', globQuotedPattern, 'without surrounding quotes');
+  const globCommaPattern = await executeBuiltinTool('glob', {
+    pattern: '*.mjs,*.txt',
+    path: 'scripts',
+    head_limit: 5,
+  }, dir, { readStateScope: 'glob-comma-pattern' });
+  assertOk('glob comma pattern no-files minimal', globCommaPattern);
+  assertNotHas('glob comma pattern no hint', globCommaPattern, 'pattern array or brace glob');
+  const globMissingPath = await executeBuiltinTool('glob', {
+    pattern: '*.mjs',
+    path: 'missing-scripts',
+    head_limit: 5,
+  }, dir, { readStateScope: 'glob-missing-path' });
+  assertError('glob missing path concise', globMissingPath, 'Error: path does not exist');
+  assertNotHas('glob missing path no existing-root hint', globMissingPath, 'existing base directory');
+  assertNotHas('glob missing path no next-call example', globMissingPath, 'glob({pattern:"*.mjs"');
+  const findPathFallback = await executeBuiltinTool('list', {
+    mode: 'find',
+    path: 'scripts/*.mjs',
+    type: 'file',
+    head_limit: 5,
+  }, dir, { readStateScope: 'find-path-fallback' });
+  assertOk('find_files path fallback', findPathFallback);
+  assertHas('find_files path fallback result', findPathFallback, 'scripts/one.mjs');
+  const listPathFallback = await executeBuiltinTool('list', {
+    path: 'scripts/*.mjs',
+    type: 'file',
+    head_limit: 5,
+  }, dir, { readStateScope: 'list-path-fallback' });
+  assertOk('list path glob fallback', listPathFallback);
+  assertHas('list path glob fallback result', listPathFallback, 'scripts/one.mjs');
+  await mkdir(join(dir, 'scripts', 'sub'));
+  await writeFile(join(dir, 'scripts', 'sub', 'two.mjs'), 'nested\n', 'utf8');
+  const listRecursivePathFallback = await executeBuiltinTool('list', {
+    path: 'scripts/**/*.mjs',
+    type: 'file',
+    head_limit: 10,
+  }, dir, { readStateScope: 'list-recursive-path-fallback' });
+  assertOk('list recursive path glob fallback', listRecursivePathFallback);
+  assertHas('list recursive path glob root result', listRecursivePathFallback, 'scripts/one.mjs');
+  assertHas('list recursive path glob nested result', listRecursivePathFallback, 'scripts/sub/two.mjs');
+  await Promise.all(Array.from({ length: 20 }, (_, i) =>
+    writeFile(join(dir, `grep-count-${String(i + 1).padStart(2, '0')}.txt`), 'countneedle\n', 'utf8')));
+  const grepCountWindow = await executeBuiltinTool('grep', {
+    pattern: 'countneedle',
+    path: dir,
+    glob: 'grep-count-*.txt',
+    output_mode: 'count',
+    head_limit: 5,
+  }, dir, { readStateScope: 'grep-count-window' });
+  assertOk('grep count windowed stream', grepCountWindow);
+  assertHas('grep count more-matches truncation', grepCountWindow, 'more matches exist');
+  assertHas('grep count count-mode hint', grepCountWindow, "output_mode:'count'");
+  assertHas('grep count displayed summary', grepCountWindow, 'total 5 matches across 5 files');
+
+  await writeFile(join(dir, 'find-batched-stat-a.txt'), 'a\n', 'utf8');
+  await writeFile(join(dir, 'find-batched-stat-b.txt'), 'b\n', 'utf8');
+  const findBatched = await executeBuiltinTool('list', {
+    mode: 'find',
+    path: dir,
+    name: 'find-batched-stat-*.txt',
+    type: 'file',
+    head_limit: 5,
+  }, dir, { readStateScope: 'find-batched-stat' });
+  assertOk('find_files batched stat path', findBatched);
+  assertHas('find_files batched stat result', findBatched, 'find-batched-stat-a.txt');
+
+  const listStatDir = join(dir, 'list-batched-stat');
+  await mkdir(listStatDir);
+  await writeFile(join(listStatDir, 'small.txt'), 'x\n', 'utf8');
+  await writeFile(join(listStatDir, 'large.txt'), 'x'.repeat(4096), 'utf8');
+  const listBatched = await executeBuiltinTool('list', {
+    path: listStatDir,
+    type: 'file',
+    sort: 'size',
+    head_limit: 1,
+  }, dir, { readStateScope: 'list-batched-stat' });
+  assertOk('list batched stat path', listBatched);
+  assertHas('list batched stat sorted result', listBatched.split('\n')[0], 'large.txt');
+
+  await writeFile(join(dir, 'edit.txt'), 'alpha\nbeta\ngamma\n', 'utf8');
+  await warmRead('edit.txt', 'edit');
+  assertOk('edit byte exact', await executeBuiltinTool('edit', {
+    path: 'edit.txt',
+    old_string: 'beta',
+    new_string: 'BETA',
+  }, dir, { readStateScope: 'edit' }));
+  await expectFile('edit.txt', 'alpha\nBETA\ngamma\n');
+
+  // 0xC3 followed by a non-continuation byte: invalid UTF-8 with NO UTF-16
+  // BOM, so the generic non-UTF-8 branch (not the BOM-aware one) is hit.
+  const editBinaryBytes = Buffer.from([0xc3, 0x28, 0x0a, 0x61, 0x0a, 0x62, 0x0a]);
+  await writeFile(join(dir, 'edit-binary-ish.txt'), editBinaryBytes);
+  recordReadSnapshotForPath(join(dir, 'edit-binary-ish.txt'), 'edit-binary-ish', {
+    source: 'test',
+    contentHash: hashBytes(editBinaryBytes),
+  });
+  assertError('edit binary-ish refuses non-UTF-8', await executeBuiltinTool('edit', {
+    path: 'edit-binary-ish.txt',
+    old_string: 'a',
+    new_string: 'A',
+  }, dir, { readStateScope: 'edit-binary-ish' }), 'Error: file appears to be non-UTF-8');
+  await expectBytes('edit-binary-ish.txt', editBinaryBytes);
+
+  const editUtf16Bytes = Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from('a\nb\n', 'utf16le')]);
+  await writeFile(join(dir, 'edit-utf16.txt'), editUtf16Bytes);
+  recordReadSnapshotForPath(join(dir, 'edit-utf16.txt'), 'edit-utf16', {
+    source: 'test',
+    contentHash: hashBytes(editUtf16Bytes),
+  });
+  assertError('edit utf16 refuses with BOM-aware message', await executeBuiltinTool('edit', {
+    path: 'edit-utf16.txt',
+    old_string: 'a',
+    new_string: 'A',
+  }, dir, { readStateScope: 'edit-utf16' }), 'Error: file is UTF-16LE (BOM FF FE)');
+  await expectBytes('edit-utf16.txt', editUtf16Bytes);
+
+  await writeFile(join(dir, 'edit-replace-all.txt'), 'x\nx\nx\n', 'utf8');
+  await warmRead('edit-replace-all.txt', 'edit-replace-all');
+  assertOk('edit replace_all byte exact', await executeBuiltinTool('edit', {
+    path: 'edit-replace-all.txt',
+    old_string: 'x',
+    new_string: 'X',
+    replace_all: true,
+  }, dir, { readStateScope: 'edit-replace-all' }));
+  await expectFile('edit-replace-all.txt', 'X\nX\nX\n');
+
+  await writeFile(join(dir, 'edit-multi.txt'), 'left\nmiddle\nright\n', 'utf8');
+  await warmRead('edit-multi.txt', 'edit-multi');
+  assertOk('edit multi byte exact', await executeBuiltinTool('edit', {
+    path: 'edit-multi.txt',
+    edits: [
+      { old_string: 'left', new_string: 'LEFT' },
+      { old_string: 'right', new_string: 'RIGHT' },
+    ],
+  }, dir, { readStateScope: 'edit-multi' }));
+  await expectFile('edit-multi.txt', 'LEFT\nmiddle\nRIGHT\n');
+
+  const multiBinaryBytes = Buffer.from([0xc3, 0x28, 0x0a, 0x6c, 0x65, 0x66, 0x74, 0x0a, 0x72, 0x69, 0x67, 0x68, 0x74, 0x0a]);
+  await writeFile(join(dir, 'edit-multi-binary-ish.txt'), multiBinaryBytes);
+  recordReadSnapshotForPath(join(dir, 'edit-multi-binary-ish.txt'), 'edit-multi-binary-ish', {
+    source: 'test',
+    contentHash: hashBytes(multiBinaryBytes),
+  });
+  assertError('edit multi binary-ish refuses non-UTF-8', await executeBuiltinTool('edit', {
+    path: 'edit-multi-binary-ish.txt',
+    edits: [
+      { old_string: 'left', new_string: 'LEFT' },
+      { old_string: 'right', new_string: 'RIGHT' },
+    ],
+  }, dir, { readStateScope: 'edit-multi-binary-ish' }), 'Error: file appears to be non-UTF-8');
+  await expectBytes('edit-multi-binary-ish.txt', multiBinaryBytes);
+
+  const multiBinaryMissBytes = Buffer.from([0xc3, 0x28, 0x0a, 0x61, 0x0a]);
+  await writeFile(join(dir, 'edit-multi-binary-miss.txt'), multiBinaryMissBytes);
+  recordReadSnapshotForPath(join(dir, 'edit-multi-binary-miss.txt'), 'edit-multi-binary-miss', {
+    source: 'test',
+    contentHash: hashBytes(multiBinaryMissBytes),
+  });
+  const multiBinaryMiss = await executeBuiltinTool('edit', {
+    path: 'edit-multi-binary-miss.txt',
+    edits: [
+      { old_string: 'missing', new_string: 'MISSING' },
+    ],
+  }, dir, { readStateScope: 'edit-multi-binary-miss' });
+  assertError('edit multi binary-ish fallback reject', multiBinaryMiss, 'Error: file appears to be non-UTF-8');
+  await expectBytes('edit-multi-binary-miss.txt', multiBinaryMissBytes);
+
+  await writeFile(join(dir, 'edit-crlf-multi.txt'), 'a\r\nb\r\nc\r\n', 'utf8');
+  await warmRead('edit-crlf-multi.txt', 'edit-crlf-multi');
+  assertOk('edit crlf multi byte exact', await executeBuiltinTool('edit', {
+    path: 'edit-crlf-multi.txt',
+    edits: [
+      { old_string: 'a', new_string: 'A' },
+      { old_string: 'c', new_string: 'C' },
+    ],
+  }, dir, { readStateScope: 'edit-crlf-multi' }));
+  await expectFile('edit-crlf-multi.txt', 'A\r\nb\r\nC\r\n');
+
+  await writeFile(join(dir, 'edit-overlap.txt'), 'abcde\n', 'utf8');
+  await warmRead('edit-overlap.txt', 'edit-overlap');
+  const overlap = await executeBuiltinTool('edit', {
+    path: 'edit-overlap.txt',
+    edits: [
+      { old_string: 'abc', new_string: 'XXX' },
+      { old_string: 'bcd', new_string: 'YYY' },
+    ],
+  }, dir, { readStateScope: 'edit-overlap' });
+  assertError('edit overlap reject', overlap, 'Error [code 8]');
+  await expectFile('edit-overlap.txt', 'abcde\n');
+
+  await writeFile(join(dir, 'partial-replace-all.txt'), 'TARGET\nseen\nmiddle\nTARGET\n', 'utf8');
+  await warmRead('partial-replace-all.txt', 'partial-replace-all', 0, 2);
+  const partialReplaceAll = await executeBuiltinTool('edit', {
+    path: 'partial-replace-all.txt',
+    old_string: 'TARGET',
+    new_string: 'DONE',
+    replace_all: true,
+  }, dir, { readStateScope: 'partial-replace-all' });
+  assertOk('partial replace_all now succeeds (read-window gate retired)', partialReplaceAll);
+  await expectFile('partial-replace-all.txt', 'DONE\nseen\nmiddle\nDONE\n');
+
+  await writeFile(join(dir, 'batch-read.txt'), Array.from({ length: 300 }, (_, i) => `line-${i + 1}`).join('\n') + '\n', 'utf8');
+  const batchRead = await executeBuiltinTool('read', {
+    path: [
+      { path: 'batch-read.txt', offset: 10, limit: 3 },
+      { path: 'batch-read.txt', offset: 40, limit: 2 },
+    ],
+  }, dir, { readStateScope: 'batch-read' });
+  assertHas('batch read first slice', batchRead, `11${LINE_SEP}line-11`);
+  assertHas('batch read second slice', batchRead, `42${LINE_SEP}line-42`);
+  assertOk('batch read snapshot edit', await executeBuiltinTool('edit', {
+    path: 'batch-read.txt',
+    old_string: 'line-41',
+    new_string: 'LINE-41',
+  }, dir, { readStateScope: 'batch-read' }));
+  const readLineWindow = await executeBuiltinTool('read', {
+    path: 'batch-read.txt',
+    line: 42,
+    context: 1,
+  }, dir, { readStateScope: 'read-line-window' });
+  assertHas('read line window before', readLineWindow, `41${LINE_SEP}LINE-41`);
+  assertHas('read line window center', readLineWindow, `42${LINE_SEP}line-42`);
+  assertHas('read line window after', readLineWindow, `43${LINE_SEP}line-43`);
+  const readPathLine = await executeBuiltinTool('read', {
+    path: 'batch-read.txt:120',
+  }, dir, { readStateScope: 'read-path-line' });
+  assertHas('read path:line center', readPathLine, `120${LINE_SEP}line-120`);
+  const readGrepCoordinate = await executeBuiltinTool('read', {
+    path: 'batch-read.txt:121:line-121',
+    context: 0,
+  }, dir, { readStateScope: 'read-grep-coordinate' });
+  assertHas('read grep coordinate exact line', readGrepCoordinate, `121${LINE_SEP}line-121`);
+  const batchReadLineSpec = await executeBuiltinTool('read', {
+    path: [
+      { path: 'batch-read.txt:122', context: 0 },
+      { path: 'batch-read.txt', line: 123, context: 0 },
+    ],
+  }, dir, { readStateScope: 'batch-read-line-spec' });
+  assertHas('batch read path:line spec', batchReadLineSpec, `122${LINE_SEP}line-122`);
+  assertHas('batch read line spec', batchReadLineSpec, `123${LINE_SEP}line-123`);
+  const readHashLineRange = await executeBuiltinTool('read', {
+    path: 'batch-read.txt#L124-L126',
+  }, dir, { readStateScope: 'read-hash-line-range' });
+  assertHas('read #L range start', readHashLineRange, `124${LINE_SEP}line-124`);
+  assertHas('read #L range end', readHashLineRange, `126${LINE_SEP}line-126`);
+  if (String(readHashLineRange).includes(`127${LINE_SEP}line-127`)) {
+    throw new Error(`read #L range was not exact:\n${readHashLineRange}`);
+  }
+  const readColonLineRange = await executeBuiltinTool('read', {
+    path: 'batch-read.txt:127-128',
+  }, dir, { readStateScope: 'read-colon-line-range' });
+  assertHas('read colon range start', readColonLineRange, `127${LINE_SEP}line-127`);
+  assertHas('read colon range end', readColonLineRange, `128${LINE_SEP}line-128`);
+
+  await writeFile(join(dir, 'edit-delete.txt'), 'a\nb\nc\n', 'utf8');
+  await warmRead('edit-delete.txt', 'edit-delete');
+  assertOk('edit delete absorb', await executeBuiltinTool('edit', {
+    path: 'edit-delete.txt',
+    old_string: 'b',
+    new_string: '',
+  }, dir, { readStateScope: 'edit-delete' }));
+  await expectFile('edit-delete.txt', 'a\nc\n');
+
+  await writeFile(join(dir, 'edit-coordinate.txt'), 'one\ntwo\nthree\n', 'utf8');
+  await warmRead('edit-coordinate.txt', 'edit-coordinate');
+  assertOk('edit path:line coordinate absorb', await executeBuiltinTool('edit', {
+    path: 'edit-coordinate.txt:2',
+    old_string: 'two',
+    new_string: 'TWO',
+  }, dir, { readStateScope: 'edit-coordinate' }));
+  await expectFile('edit-coordinate.txt', 'one\nTWO\nthree\n');
+
+  await writeFile(join(dir, 'multi-edit-coordinate.txt'), 'alpha\nbeta\ngamma\n', 'utf8');
+  await warmRead('multi-edit-coordinate.txt', 'multi-edit-coordinate');
+  assertOk('multi edit path:line coordinate absorb', await executeBuiltinTool('edit', {
+    edits: [
+      { path: 'multi-edit-coordinate.txt:1', old_string: 'alpha', new_string: 'ALPHA' },
+      { path: 'multi-edit-coordinate.txt:2', old_string: 'beta', new_string: 'BETA' },
+    ],
+  }, dir, { readStateScope: 'multi-edit-coordinate' }));
+  await expectFile('multi-edit-coordinate.txt', 'ALPHA\nBETA\ngamma\n');
+
+  await writeFile(join(dir, 'ambig.txt'), 'x\nx\n', 'utf8');
+  await warmRead('ambig.txt', 'ambig');
+  const ambig = await executeBuiltinTool('edit', {
+    path: 'ambig.txt',
+    old_string: 'x',
+    new_string: 'X',
+  }, dir, { readStateScope: 'ambig' });
+  if (!String(ambig).startsWith('Error [code 9]')) throw new Error(`ambiguous edit did not return code 9: ${ambig}`);
+
+  const lines = Array.from({ length: 12000 }, (_, i) => `line-${i + 1}`).join('\n') + '\n';
+  await writeFile(join(dir, 'large.txt'), lines, 'utf8');
+  const firstTail = await executeBuiltinTool('read', { path: 'large.txt', offset: 8000, limit: 3 }, dir, { readStateScope: 'read-a' });
+  assertHas('read tail first', firstTail, `8001${LINE_SEP}line-8001`);
+  const cachedTail = await executeBuiltinTool('read', { path: 'large.txt', offset: 10000, limit: 2 }, dir, { readStateScope: 'read-b' });
+  assertHas('read tail cached', cachedTail, `10001${LINE_SEP}line-10001`);
+  const compactMediumLines = Array.from({ length: 8000 }, (_, i) => `compact-${i + 1}`).join('\n') + '\n';
+  await writeFile(join(dir, 'compact-medium.txt'), compactMediumLines, 'utf8');
+  const compactMediumDefault = await executeBuiltinTool('read', { path: 'compact-medium.txt' }, dir, { readStateScope: 'read-compact-medium-default' });
+  assertHas('compact medium default marker', compactMediumDefault, 'TRUNCATED');
+  assertHas('compact medium default head', compactMediumDefault, `1${LINE_SEP}compact-1`);
+  assertHas('compact medium default tail', compactMediumDefault, `8000${LINE_SEP}compact-8000`);
+  if (String(compactMediumDefault).includes(`4000${LINE_SEP}compact-4000`)) {
+    throw new Error('compact medium default read included a middle line that should have been elided');
+  }
+  const smartSnapshotRows = Array.from({ length: 700 }, (_, i) => i === 349 ? 'M' : `smart-snapshot-${i + 1}`);
+  await writeFile(join(dir, 'smart-snapshot.txt'), smartSnapshotRows.join('\n') + '\n', 'utf8');
+  const smartSnapshotRead = await executeBuiltinTool('read', { path: 'smart-snapshot.txt' }, dir, { readStateScope: 'read-smart-snapshot' });
+  assertHas('smart snapshot default read marker', smartSnapshotRead, 'TRUNCATED');
+  assertNotHas('smart snapshot default read no narrow hint', smartSnapshotRead, 'read({path,line,context})');
+  const smartHiddenEdit = await executeBuiltinTool('edit', {
+    path: 'smart-snapshot.txt',
+    old_string: 'M',
+    new_string: 'N',
+  }, dir, { readStateScope: 'read-smart-snapshot' });
+  assertOk('smart snapshot hidden middle edit now succeeds (read-window gate retired)', smartHiddenEdit);
+  await expectFile('smart-snapshot.txt', smartSnapshotRows.map((row) => (row === 'M' ? 'N' : row)).join('\n') + '\n');
+  const midRangeLines = Array.from({ length: 20000 }, (_, i) => `midrange-${i + 1}`).join('\n') + '\n';
+  await writeFile(join(dir, 'mid-range.txt'), midRangeLines, 'utf8');
+  const midRange = await executeBuiltinTool('read', { path: 'mid-range.txt', offset: 15000, limit: 2 }, dir, { readStateScope: 'read-mid-range-stream' });
+  assertHas('mid range streamed slice first', midRange, `15001${LINE_SEP}midrange-15001`);
+  assertHas('mid range streamed slice footer', midRange, 'range limit reached; next offset: 15002');
+  const mediumHeadLines = Array.from({ length: 100000 }, (_, i) => `head-${i + 1}`).join('\n') + '\n';
+  await writeFile(join(dir, 'medium-head.txt'), mediumHeadLines, 'utf8');
+  const mediumHead = await executeBuiltinTool('read', { path: 'medium-head.txt', mode: 'head', n: 2 }, dir, { readStateScope: 'read-medium-head' });
+  assertHas('medium head first', mediumHead, `1${LINE_SEP}head-1`);
+  assertHas('medium head second', mediumHead, `2${LINE_SEP}head-2`);
+  const mediumTail = await executeBuiltinTool('read', { path: 'medium-head.txt', mode: 'tail', n: 2 }, dir, { readStateScope: 'read-medium-tail' });
+  assertHas('medium tail first', mediumTail, `99999${LINE_SEP}head-99999`);
+  assertHas('medium tail second', mediumTail, `100000${LINE_SEP}head-100000`);
+  const mediumCount = await executeBuiltinTool('read', { path: 'medium-head.txt', mode: 'count' }, dir, { readStateScope: 'read-medium-count' });
+  assertHas('medium count lines', mediumCount, 'lines\t100000');
+  assertHas('medium count words', mediumCount, 'words\t100000');
+  const mediumDefault = await executeBuiltinTool('read', { path: 'medium-head.txt' }, dir, { readStateScope: 'read-medium-default' });
+  assertHas('medium default first', mediumDefault, `1${LINE_SEP}head-1`);
+  assertHas('medium default marker', mediumDefault, 'TRUNCATED');
+  assertNotHas('medium default no narrow hint', mediumDefault, 'read({path,line,context})');
+  assertHas('medium default tail', mediumDefault, `100000${LINE_SEP}head-100000`);
+  if (String(mediumDefault).includes(`50000${LINE_SEP}head-50000`)) {
+    throw new Error('medium default read streamed a middle line that should have been elided');
+  }
+  assertOk('medium default visible-tail edit', await executeBuiltinTool('edit', {
+    path: 'medium-head.txt',
+    old_string: 'head-99999',
+    new_string: 'HEAD-99999',
+  }, dir, { readStateScope: 'read-medium-default' }));
+  const farBatch = await executeBuiltinTool('read', {
+    path: [
+      { path: 'large.txt', offset: 10, limit: 2 },
+      { path: 'large.txt', offset: 10000, limit: 2 },
+    ],
+  }, dir, { readStateScope: 'read-far-batch' });
+  assertHas('far batch read head slice', farBatch, `11${LINE_SEP}line-11`);
+  assertHas('far batch read tail slice', farBatch, `10001${LINE_SEP}line-10001`);
+  const reverseFarBatch = await executeBuiltinTool('read', {
+    path: [
+      { path: 'large.txt', offset: 10000, limit: 1 },
+      { path: 'large.txt', offset: 10, limit: 1 },
+    ],
+  }, dir, { readStateScope: 'read-far-batch-reverse' });
+  const reverseTailIdx = String(reverseFarBatch).indexOf(`10001${LINE_SEP}line-10001`);
+  const reverseHeadIdx = String(reverseFarBatch).indexOf(`11${LINE_SEP}line-11`);
+  if (reverseTailIdx === -1 || reverseHeadIdx === -1 || reverseTailIdx > reverseHeadIdx) {
+    throw new Error(`far batch output order changed unexpectedly:\n${reverseFarBatch}`);
+  }
+  const byteCapRows = Array.from({ length: 1800 }, (_, i) => `bytecap-${i + 1}-${'x'.repeat(54)}`);
+  byteCapRows[9] = `bytecap-repeat-${'x'.repeat(50)}`;
+  byteCapRows[1699] = `bytecap-repeat-${'x'.repeat(50)}`;
+  const byteCapLines = byteCapRows.join('\n') + '\n';
+  await writeFile(join(dir, 'byte-cap-read.txt'), byteCapLines, 'utf8');
+  const byteCapRead = await executeBuiltinTool('read', { path: 'byte-cap-read.txt', offset: 0, limit: 1800 }, dir, { readStateScope: 'read-byte-cap' });
+  assertHas('byte-cap read truncation marker', byteCapRead, 'output truncated');
+  const byteCapHiddenEdit = await executeBuiltinTool('edit', {
+    path: 'byte-cap-read.txt',
+    old_string: `bytecap-repeat-${'x'.repeat(50)}`,
+    new_string: 'BYTECAP-HIDDEN',
+  }, dir, { readStateScope: 'read-byte-cap' });
+  assertError('byte-cap ambiguous hidden tail edit blocked by ambiguity gate (code 9, not read-window)', byteCapHiddenEdit, 'Error [code 9]');
+  await expectFile('byte-cap-read.txt', byteCapLines);
+
+  await writeFile(join(dir, 'large.txt'), lines.replace('line-10001', 'changed-10001'), 'utf8');
+  const invalidated = await executeBuiltinTool('read', { path: 'large.txt', offset: 10000, limit: 1 }, dir, { readStateScope: 'read-c' });
+  assertHas('read cache invalidation', invalidated, `10001${LINE_SEP}changed-10001`);
+
+  console.log('mutation-io smoke passed');
+} finally {
+  await rmTree(dir);
+  await rmTree(DATA_DIR);
+}
+// Imported builtin/read-dedup/offload modules keep a background flush timer
+// alive, so without an explicit exit the process hangs after all checks pass
+// (same as guard-smoke / builtin-utils-smoke). A thrown assertion above exits
+// non-zero before reaching here.
+process.exit(0);