mixdog 0.9.149 → 0.9.151

package/src/runtime/agent/orchestrator/session/store/serialize.test.mjs

@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import {
+    _sessionForDisk,
+    _storedSessionFromFile,
+} from './serialize.mjs';
+
+test('provider prefix guard remains runtime-local across media-safe persistence', () => {
+    const guard = {
+        messageHashes: ['live-image-hash'],
+        requestPrefixHash: 'live-tools-hash',
+    };
+    const session = {
+        id: 'sess_prefix_guard',
+        messages: [{
+            role: 'tool',
+            content: [{
+                type: 'image_url',
+                image_url: { url: 'data:image/png;base64,AAAA' },
+            }],
+        }],
+        _providerPrefixGuardState: guard,
+    };
+
+    const stored = _sessionForDisk(session);
+
+    assert.equal(Object.hasOwn(stored, '_providerPrefixGuardState'), false);
+    assert.equal(session._providerPrefixGuardState, guard);
+    assert.match(JSON.stringify(stored.messages), /Image omitted from stored history: image\/png/);
+});
+
+test('legacy stored provider prefix guards are discarded on load', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'mixdog-prefix-guard-store-'));
+    const id = 'sess_legacy_prefix_guard';
+    try {
+        await writeFile(join(dir, `${id}.json`), JSON.stringify({
+            id,
+            generation: 0,
+            closed: false,
+            messages: [{ role: 'user', content: 'kept' }],
+            tools: [],
+            _providerPrefixGuardState: {
+                messageHashes: ['stale'],
+                requestPrefixHash: 'stale',
+            },
+        }), 'utf8');
+
+        const loaded = _storedSessionFromFile(dir, `${id}.json`);
+
+        assert.ok(loaded);
+        assert.equal(Object.hasOwn(loaded, '_providerPrefixGuardState'), false);
+        assert.equal(loaded.messages[0].content, 'kept');
+    } finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});

package/src/runtime/agent/orchestrator/session/task-wait-control.mjs

@@ -0,0 +1,78 @@
+// Per-session wake control for `task wait`.
+//
+// This is intentionally separate from the turn AbortController: new user input
+// should release only the passive wait, let the tool return a running snapshot,
+// and then flow through the normal post-tool steering boundary. The background
+// task itself keeps running.
+const waitersBySession = new Map();
+
+function sessionKey(sessionId) {
+  return String(sessionId || '').trim();
+}
+
+export function beginInterruptibleTaskWait(sessionId, parentSignal = null) {
+  const key = sessionKey(sessionId);
+  if (!key) {
+    return {
+      signal: parentSignal || null,
+      interruptedByUser: false,
+      dispose() {},
+    };
+  }
+
+  const controller = new AbortController();
+  const waiter = {
+    controller,
+    interruptedByUser: false,
+  };
+  let waiters = waitersBySession.get(key);
+  if (!waiters) {
+    waiters = new Set();
+    waitersBySession.set(key, waiters);
+  }
+  waiters.add(waiter);
+
+  let disposed = false;
+  const onParentAbort = () => {
+    if (!controller.signal.aborted) controller.abort(parentSignal?.reason);
+  };
+  if (parentSignal) {
+    if (parentSignal.aborted) onParentAbort();
+    else {
+      try { parentSignal.addEventListener('abort', onParentAbort, { once: true }); } catch {}
+    }
+  }
+
+  return {
+    signal: controller.signal,
+    get interruptedByUser() {
+      return waiter.interruptedByUser;
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      if (parentSignal) {
+        try { parentSignal.removeEventListener('abort', onParentAbort); } catch {}
+      }
+      waiters.delete(waiter);
+      if (waiters.size === 0) waitersBySession.delete(key);
+    },
+  };
+}
+
+export function interruptTaskWaitForSession(sessionId, reason = 'user-message') {
+  const waiters = waitersBySession.get(sessionKey(sessionId));
+  if (!waiters?.size) return 0;
+  let interrupted = 0;
+  for (const waiter of [...waiters]) {
+    if (waiter.controller.signal.aborted) continue;
+    waiter.interruptedByUser = true;
+    interrupted += 1;
+    try { waiter.controller.abort(reason); } catch {}
+  }
+  return interrupted;
+}
+
+export function activeTaskWaitCountForSession(sessionId) {
+  return waitersBySession.get(sessionKey(sessionId))?.size || 0;
+}

package/src/runtime/agent/orchestrator/session/task-wait-control.test.mjs

@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  activeTaskWaitCountForSession,
+  beginInterruptibleTaskWait,
+  interruptTaskWaitForSession,
+} from './task-wait-control.mjs';
+import {
+  cancelBackgroundTask,
+  getBackgroundTask,
+  registerBackgroundTask,
+} from '../../../shared/background-tasks.mjs';
+import { executeTaskTool } from '../tools/builtin/task-tool.mjs';
+
+test('user input interrupts only task waits in its session', () => {
+  const first = beginInterruptibleTaskWait('sess_wait_1');
+  const second = beginInterruptibleTaskWait('sess_wait_1');
+  const other = beginInterruptibleTaskWait('sess_wait_2');
+
+  assert.equal(activeTaskWaitCountForSession('sess_wait_1'), 2);
+  assert.equal(interruptTaskWaitForSession('sess_wait_1'), 2);
+  assert.equal(first.signal.aborted, true);
+  assert.equal(second.signal.aborted, true);
+  assert.equal(first.interruptedByUser, true);
+  assert.equal(second.interruptedByUser, true);
+  assert.equal(other.signal.aborted, false);
+
+  first.dispose();
+  second.dispose();
+  other.dispose();
+  assert.equal(activeTaskWaitCountForSession('sess_wait_1'), 0);
+});
+
+test('turn cancellation propagates without masquerading as user input', () => {
+  const parent = new AbortController();
+  const wait = beginInterruptibleTaskWait('sess_parent_abort', parent.signal);
+
+  parent.abort('turn-cancelled');
+  assert.equal(wait.signal.aborted, true);
+  assert.equal(wait.interruptedByUser, false);
+
+  wait.dispose();
+});
+
+test('task wait returns on user input without cancelling the background task', async () => {
+  const sessionId = 'sess_task_wait_integration';
+  const taskId = 'task_shell_wait_integration';
+  const task = registerBackgroundTask({
+    taskId,
+    surface: 'shell',
+    operation: 'run',
+    context: {
+      callerSessionId: sessionId,
+      routingSessionId: sessionId,
+    },
+  });
+  task.promise = new Promise(() => {});
+
+  const interruptTimer = setTimeout(
+    () => interruptTaskWaitForSession(sessionId),
+    20,
+  );
+  const startedAt = Date.now();
+  try {
+    const result = await executeTaskTool(
+      { action: 'wait', task_id: taskId, timeout_ms: 10_000 },
+      { sessionId, callerSessionId: sessionId, routingSessionId: sessionId },
+    );
+
+    assert.ok(Date.now() - startedAt < 1_000, 'wait should return before its ceiling');
+    assert.match(result, /Wait interrupted by new user input/);
+    assert.equal(getBackgroundTask(taskId)?.status, 'running');
+  } finally {
+    clearTimeout(interruptTimer);
+    cancelBackgroundTask(taskId, 'test cleanup');
+  }
+});

package/src/runtime/agent/orchestrator/tools/builtin/absence-absorption.test.mjs

@@ -0,0 +1,43 @@
+// Absence absorption: a conclusive "no such path" (read/list) and git's
+// exit-128 state verdict are ANSWERS, not tool failures. The full diagnostic
+// body is preserved — only the error envelope is dropped, so the caller acts
+// on the evidence instead of entering error recovery.
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import { executeBuiltinTool } from '../builtin.mjs';
+import { executeGitTool } from './git-command-tool.mjs';
+
+test('read of a conclusively missing path answers [path absent], not Error', async (t) => {
+    const root = mkdtempSync(join(tmpdir(), 'mixdog-absent-read-'));
+    t.after(() => rmSync(root, { recursive: true, force: true }));
+    const out = String(await executeBuiltinTool('read', { path: join(root, 'no-such-file.txt') }, root));
+    assert.match(out, /^\[path absent\]/);
+    assert.match(out, /ENOENT/);
+    assert.doesNotMatch(out, /^Error:/);
+});
+
+test('list of a conclusively missing directory answers [path absent], not Error', async (t) => {
+    const root = mkdtempSync(join(tmpdir(), 'mixdog-absent-list-'));
+    t.after(() => rmSync(root, { recursive: true, force: true }));
+    const out = String(await executeBuiltinTool('list', { path: join(root, 'no-such-dir') }, root));
+    assert.match(out, /^\[path absent\]/);
+    assert.doesNotMatch(out, /^Error:/);
+});
+
+test('git exit 128 returns the state verdict as a non-error envelope', async (t) => {
+    const root = mkdtempSync(join(tmpdir(), 'mixdog-absent-git128-'));
+    t.after(() => rmSync(root, { recursive: true, force: true }));
+    const repo = join(root, 'repo');
+    await executeGitTool({ command: `git init "${repo}"` }, root);
+    // Unborn branch: `git log` exits 128 with git's own explanation.
+    const out = String(await executeGitTool({ command: `git -C "${repo}" log` }, repo));
+    assert.doesNotMatch(out, /^Error:/);
+    const parsed = JSON.parse(out);
+    assert.equal(parsed.ok, false);
+    assert.equal(parsed.exit, 128);
+    assert.ok(String(parsed.stderr || parsed.reason || '').length > 0);
+});

package/src/runtime/agent/orchestrator/tools/builtin/absolute-glob-expand.test.mjs

@@ -0,0 +1,63 @@
+// An absolute glob is expanded straight off the filesystem when the inventory
+// walker cannot see its targets (symlink farms such as /sys and /proc). The
+// pattern bounds the walk; anything unbounded or unsupported declines.
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import { expandAbsoluteGlob, expandAbsoluteGlobs } from './lib/absolute-glob-expand.mjs';
+
+async function withBlockTree(run) {
+    const root = await mkdtemp(join(tmpdir(), 'mixdog-abs-glob-'));
+    try {
+        for (const disk of ['sda', 'sdb', 'nvme0n1']) {
+            await mkdir(join(root, 'block', disk, 'device'), { recursive: true });
+            await writeFile(join(root, 'block', disk, 'size'), '2048\n');
+            await writeFile(join(root, 'block', disk, 'device', 'model'), `${disk}-model\n`);
+        }
+        return await run(root);
+    } finally {
+        await rm(root, { recursive: true, force: true });
+    }
+}
+
+test('a magic middle segment expands to every matching path', async () => {
+    await withBlockTree(async (root) => {
+        const sizes = await expandAbsoluteGlob(join(root, 'block', 'sd*', 'size'));
+        assert.equal(sizes.length, 2);
+        assert.ok(sizes.every((p) => p.endsWith('/size')));
+        assert.ok(sizes.some((p) => p.includes('/sda/')));
+        assert.ok(sizes.some((p) => p.includes('/sdb/')));
+
+        const models = await expandAbsoluteGlob(join(root, 'block', '*', 'device', 'model'));
+        assert.equal(models.length, 3);
+    });
+});
+
+test('a pattern with no matches answers empty, not null', async () => {
+    await withBlockTree(async (root) => {
+        assert.deepEqual(await expandAbsoluteGlob(join(root, 'block', 'hd*', 'size')), []);
+    });
+});
+
+test('unbounded or non-absolute patterns decline so the caller keeps its answer', async () => {
+    await withBlockTree(async (root) => {
+        assert.equal(await expandAbsoluteGlob(join(root, '**', 'size')), null);
+        assert.equal(await expandAbsoluteGlob('block/sd*/size'), null);
+        assert.equal(await expandAbsoluteGlob(join(root, 'block', 'sda', 'size')), null);
+    });
+});
+
+test('the batch form dedupes and honours its limit', async () => {
+    await withBlockTree(async (root) => {
+        const found = await expandAbsoluteGlobs([
+            join(root, 'block', 'sd*', 'size'),
+            join(root, 'block', 's*a', 'size'),
+        ], { limit: 5 });
+        assert.equal(found.length, 2);
+        const limited = await expandAbsoluteGlobs([join(root, 'block', '*', 'size')], { limit: 1 });
+        assert.equal(limited.length, 1);
+    });
+});

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

@@ -555,6 +555,14 @@ function maybeCapUnboundedRead(a) {
         if (/:\d+(?:-\d+)?\s*$/.test(p)) return;
     }
     a.limit = READ_GUARD_DEFAULT_LIMIT;
+    // Marker for the read tool's glob fan-out: this limit is the injected
+    // default, not a caller choice, so a multi-file survey may tighten it.
+    // Non-enumerable so it never leaks into arg spreads, cache keys, or output.
+    try {
+        Object.defineProperty(a, '_readLimitDefaulted', {
+            value: true, enumerable: false, configurable: true, writable: true,
+        });
+    } catch { /* best-effort */ }
 }
 
 function guardRead(a) {

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

@@ -1,4 +1,4 @@
-import { statSync, createWriteStream } from 'fs';
+import { statSync, lstatSync, realpathSync, createWriteStream } from 'fs';
 import * as fsPromises from 'fs/promises';
 import { basename, dirname, join } from 'path';
 import { performance } from 'perf_hooks';
@@ -73,6 +73,21 @@ async function cleanupEmptyWxTarget(targetPath) {
     } catch { /* already gone or unreadable — leave it */ }
 }
 
+// The real file a write aimed at `targetPath` must land on when the leaf is a
+// symlink, or null when it is not a link (or is dangling, so there is nothing
+// to resolve). Writers rename a temp file into place, which would replace the
+// LINK itself with a regular file and silently detach layouts like nginx's
+// sites-enabled/default from sites-available/default. Engines that write a
+// path themselves use this as "do not hand this target to the engine".
+export function symlinkWriteTarget(targetPath) {
+    try {
+        if (!lstatSync(targetPath).isSymbolicLink()) return null;
+        return realpathSync(targetPath);
+    } catch {
+        return null;
+    }
+}
+
 export async function atomicWrite(targetPath, content, {
     mode,
     signal,
@@ -95,12 +110,16 @@ export async function atomicWrite(targetPath, content, {
     };
     if (resolvedSignal?.aborted) throw abortReason();
 
-    const dir = dirname(targetPath);
+    // Write THROUGH a leaf symlink: resolve it first so the rename replaces the
+    // file the link points at, not the link. Resolving also keeps the temp file
+    // beside the real target, so the rename stays on one filesystem.
+    const writeTarget = symlinkWriteTarget(targetPath) ?? targetPath;
+    const dir = dirname(writeTarget);
     const rnd = randomBytes(4).toString('hex');
-    const tmp = join(dir, `.${basename(targetPath)}.mixdog-tmp-${rnd}`);
+    const tmp = join(dir, `.${basename(writeTarget)}.mixdog-tmp-${rnd}`);
     let effectiveMode = mode;
     let existingStat = null;
-    try { existingStat = statSync(targetPath); } catch { /* target doesn't exist */ }
+    try { existingStat = statSync(writeTarget); } catch { /* target doesn't exist */ }
     if (effectiveMode === undefined && existingStat) {
         effectiveMode = existingStat.mode & 0o777;
     }
@@ -165,7 +184,7 @@ export async function atomicWrite(targetPath, content, {
     if (flags === 'wx') {
         let excl = null;
         try {
-            excl = await fsPromises.open(targetPath, 'wx');
+            excl = await fsPromises.open(writeTarget, 'wx');
             await excl.close();
         } catch (exclErr) {
             if (excl) try { await excl.close(); } catch { /* already closed */ }
@@ -179,7 +198,7 @@ export async function atomicWrite(targetPath, content, {
 
     if (resolvedSignal?.aborted) {
         try { await fsPromises.unlink(tmp); } catch { /* already gone */ }
-        if (flags === 'wx') await cleanupEmptyWxTarget(targetPath);
+        if (flags === 'wx') await cleanupEmptyWxTarget(writeTarget);
         throw abortReason();
     }
 
@@ -188,16 +207,16 @@ export async function atomicWrite(targetPath, content, {
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
         if (expectedTargetSnapshot) {
             let currentStat = null;
-            try { currentStat = statSync(targetPath); } catch { currentStat = null; }
+            try { currentStat = statSync(writeTarget); } catch { currentStat = null; }
             if (expectedTargetSnapshotChanged(currentStat, expectedTargetSnapshot)) {
                 try { await fsPromises.unlink(tmp); } catch { /* already gone */ }
-                const err = new Error(`target changed between preflight and rename (TOCTOU): ${targetPath}`);
+                const err = new Error(`target changed between preflight and rename (TOCTOU): ${writeTarget}`);
                 err.code = 'ESTALE_TARGET';
                 throw err;
             }
         }
         try {
-            await fsPromises.rename(tmp, targetPath);
+            await fsPromises.rename(tmp, writeTarget);
             // When fsync is requested, also fsync the parent directory so
             // the rename itself is durable across power-loss. Directory
             // fsync is a no-op / unsupported on Windows; swallow EPERM /
@@ -231,6 +250,6 @@ export async function atomicWrite(targetPath, content, {
         }
     }
     try { await fsPromises.unlink(tmp); } catch { /* already gone */ }
-    if (flags === 'wx') await cleanupEmptyWxTarget(targetPath);
+    if (flags === 'wx') await cleanupEmptyWxTarget(writeTarget);
     throw lastErr;
 }

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

@@ -44,12 +44,12 @@ export const BUILTIN_TOOLS = [
         name: 'read',
         title: 'Read',
         annotations: { title: 'Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
-        description: 'Read-only; safe to batch in parallel. Known-file contents or line ranges, bounded to the narrowest range that answers the question. Images render for viewing; not directories. Replaces cat/head/tail.',
+        description: 'Read-only; safe to batch in parallel. Known-file contents or line ranges, bounded to the narrowest range that answers the question — when the answer depends on content not yet seen, read the wider range once instead of deciding from a partial view. Images render for viewing; not directories. Replaces cat/head/tail.',
         inputSchema: {
             type: 'object',
             properties: {
                 file_path: {
-                    type: 'string',                    description: 'Known file path as plain text. A glob (e.g. "logs/*.log") fans out to per-file results (cap 10, newest first); literal-named files win over expansion.',
+                    type: 'string',                    description: 'Known file path as plain text. A glob (e.g. "logs/*.log") fans out to per-file results (cap 10 files, newest first; limit applies per file and is capped at 25 lines; all files share a 10 KB output budget); literal-named files win over expansion.',
                 },
                 offset: {
                     type: 'integer',
@@ -59,7 +59,7 @@ export const BUILTIN_TOOLS = [
                 limit: {
                     type: 'integer',
                     minimum: 1,
-                    description: 'Maximum line count as a bare integer; default 500.',
+                    description: 'Maximum line count as a bare integer; default 500 for one exact file, capped at 25 per file for glob expansion.',
                 },
             },
             required: ['file_path'],
@@ -107,7 +107,7 @@ export const BUILTIN_TOOLS = [
                 timeout_ms: {
                     type: 'number',
                     minimum: 0,
-                    description: 'Optional hard total deadline in ms; kills the command even after background promotion. Omit or 0 = no deadline.',
+                    description: 'Hard process-kill deadline in ms; unrelated to the automatic 10s foreground window and still applies after background promotion. Omit for normal builds/tests; use only when forced termination is intended. Omit or 0 = no deadline.',
                 },
             },
             required: ['command'],
@@ -160,7 +160,7 @@ export const BUILTIN_TOOLS = [
         name: 'grep',
         title: 'Grep',
         annotations: { title: 'Grep', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Read-only; safe to batch in parallel. Search file contents for literal or regex matches and return contextual path:line blocks that are directly usable; read only the lines they omit. A wide reconnaissance pattern goes to mode:files first; context:0 when only the location is needed. Ripgrep-dialect regex (e.g. "log.*Error"; escape literal braces; patterns match within one line). Replaces grep/rg.',
+        description: 'Read-only; safe to batch in parallel. Search file contents for literal or regex matches and return contextual path:line blocks that are directly usable; read only the lines they omit. All rendered output is capped at 10 KB. A wide reconnaissance pattern goes to mode:files first; context:0 when only the location is needed. Ripgrep-dialect regex (e.g. "log.*Error"; escape literal braces; patterns match within one line). Replaces grep/rg.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -175,7 +175,7 @@ export const BUILTIN_TOOLS = [
                     type: 'string',                    description: 'One plain existing file or directory scope; if unsure, omit to search the project root.',
                 },
                 glob: {
-                    type: 'string',                    description: 'Optional file-path glob filter, not search text.',
+                    type: 'string',                    description: 'Relative file-path glob filter evaluated inside path (e.g. "*.cs", "src/**/*.ts"). Never pass an absolute or exact file path here; use path instead.',
                 },
                 mode: { type: 'string', enum: ['content', 'files', 'count'], description: 'content default; files lists matching paths; count totals all patterns together per file.' },
                 limit: { type: 'integer', minimum: 0, description: 'Max results; default 250; 0 unlimited.' },
@@ -244,7 +244,7 @@ export const BUILTIN_TOOLS = [
                 },
                 hidden: { type: 'boolean', description: 'Include dotfiles.' },
                 meta: { type: 'boolean', description: 'Per-entry size bytes, UTC mtime, octal mode.' },
-                limit: { type: 'integer', minimum: 0, description: 'Max entries; default 100; 0 unlimited.' },
+                limit: { type: 'integer', minimum: 0, maximum: 100, description: 'Max entries; default 100; 0 = no page cap (absolute cap still applies).' },
                 offset: { type: 'integer', minimum: 0, description: 'Entry offset.' },
             },
             required: [],

package/src/runtime/agent/orchestrator/tools/builtin/enoent-outside-project.test.mjs

@@ -0,0 +1,56 @@
+// A missing ABSOLUTE path outside the project is recovered from its OWN
+// filesystem, never from a project-wide scan: no file inside the project can
+// be the correction for /sys/block/sd*/size, and the scan is what turned three
+// such reads into 17.5s each.
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import { executeBuiltinTool } from '../builtin.mjs';
+
+async function withDirs(run) {
+    const project = await mkdtemp(join(tmpdir(), 'mixdog-enoent-project-'));
+    const outside = await mkdtemp(join(tmpdir(), 'mixdog-enoent-outside-'));
+    try {
+        return await run({ project, outside });
+    } finally {
+        await rm(project, { recursive: true, force: true });
+        await rm(outside, { recursive: true, force: true });
+    }
+}
+
+test('an outside absolute miss names its own nearest directory, not the project', async () => {
+    await withDirs(async ({ project, outside }) => {
+        await mkdir(join(project, 'src'), { recursive: true });
+        await writeFile(join(project, 'src', 'size'), 'decoy\n');
+        await mkdir(join(outside, 'block'), { recursive: true });
+        await writeFile(join(outside, 'block', 'sda'), 'disk\n');
+
+        const out = String(await executeBuiltinTool('read', {
+            file_path: join(outside, 'block', 'sd*', 'size'),
+        }, project));
+
+        assert.match(out, /\[path absent\]/);
+        assert.match(out, /nearest existing directory/);
+        assert.match(out, /"sda"/);
+        // The decoy inside the project must never be offered for an outside path.
+        assert.doesNotMatch(out, /same filename exists at/);
+        assert.doesNotMatch(out, /project scan/);
+    });
+});
+
+test('a miss INSIDE the project keeps its same-name recovery', async () => {
+    await withDirs(async ({ project }) => {
+        await mkdir(join(project, 'src', 'tools'), { recursive: true });
+        await writeFile(join(project, 'src', 'tools', 'widget.mjs'), 'export const widget = 1;\n');
+
+        const out = String(await executeBuiltinTool('read', {
+            file_path: join(project, 'lib', 'widget.mjs'),
+        }, project));
+
+        assert.match(out, /widget\.mjs/);
+        assert.doesNotMatch(out, /nearest existing directory/);
+    });
+});

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

@@ -13,7 +13,7 @@
 // the existing EXTERNAL_TOOL_REDIRECTS guidance message in that case.
 import { readFileSync, mkdirSync, existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { atomicWrite } from './atomic-write.mjs';
+import { atomicWrite, symlinkWriteTarget } from './atomic-write.mjs';
 import { assertPathsReachable } from './fs-reachability.mjs';
 import { normalizeInputPath, resolveAgainstCwd, normalizeOutputPath } from './path-utils.mjs';
 import { isUncPath, isWindowsDevicePath, hasUnsafeWin32Component, isBlockedDevicePath, isSpecialFileStat } from './device-paths.mjs';
@@ -587,7 +587,11 @@ async function adaptStrReplace(args, workDir, options) {
     // An unverified native edit session never receives work: the in-process
     // apply below is the fallback, so a stale/spoofed engine cannot touch bytes.
     const nativeEditVerified = await nativeEditSessionSatisfiesContract();
-    if (!nativeEditVerified || fileEnc.encoding !== 'utf8' || editPlan.rebased || !editPlan.uniform) {
+    // A symlinked target never reaches the native engine either: it writes the
+    // path it is handed, which would replace the link with a regular file. The
+    // in-process apply goes through atomicWrite, which writes through the link.
+    const symlinkedTarget = symlinkWriteTarget(fullPath) !== null;
+    if (!nativeEditVerified || symlinkedTarget || fileEnc.encoding !== 'utf8' || editPlan.rebased || !editPlan.uniform) {
         const occurrences = editPlan.positions.length;
         if (occurrences === 0) {
             const message = 'old_string not found';