mixdog 0.9.2 → 0.9.3

package/src/runtime/agent/orchestrator/stall-policy.mjs

@@ -181,9 +181,9 @@ export const PROVIDER_WS_ACQUIRE_TIMEOUT_MS = resolveTimeoutMs(
     { minMs: 5_000, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
 );
 
-// Single inter-chunk idle timer, matching codex's DEFAULT_STREAM_IDLE_TIMEOUT_MS
-// (300s). codex resets one idle timer on every received WS frame; mixdog does
-// the same (openai-oauth-ws messageHandler resets on every parsed event). There
+// Single inter-chunk idle timer (300s), matching the upstream WS provider's
+// default stream idle timeout. Mixdog resets one idle timer on every received
+// WS frame (openai-oauth-ws messageHandler resets on every parsed event). There
 // is deliberately no separate "first-meaningful" watchdog — a live stream
 // (including server-side reasoning ACKed via response.created) keeps this timer
 // fresh, and only true socket silence trips it. Env-tunable.

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

@@ -17,7 +17,7 @@ export const BUILTIN_TOOLS = [
         name: 'read',
         title: 'Mixdog Read',
         annotations: { title: 'Mixdog Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
-        description: 'Read known file path(s). Prefer grep content_with_context or code_graph anchors first. Window with numeric offset+limit only. Batch paths/regions as real arrays. Dirs use list.',
+        description: 'Read known file path(s). Prefer grep content_with_context or code_graph anchors first. Window with numeric offset+limit only. Batch paths/regions as real arrays; adjacent spans in one file = one window, not repeated calls. Dirs use list.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -42,7 +42,7 @@ export const BUILTIN_TOOLS = [
                             minItems: 1,
                         },
                     ],
-                    description: 'File path, path[], or {path,offset,limit}[] region objects. Pass arrays directly; JSON strings are legacy recovery only. Dirs use list.',
+                    description: 'File path, path[], or {path,offset,limit}[] region objects. Pass arrays directly; JSON strings are legacy recovery only.',
                 },
                 offset: { type: 'number', minimum: 0, description: 'Numeric lines to skip before reading; 0 starts at line 1. Continue with offset:N.' },
                 limit: { type: 'number', minimum: 1, description: 'Numeric max lines to return after offset.' },

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

@@ -0,0 +1,241 @@
+// Native adapters for well-known tool names from OTHER agent CLIs whose
+// argument shapes differ from any mixdog builtin (StrReplace/Write/bash
+// variants). Executed directly against the filesystem via atomicWrite / the
+// existing shell runner — NOT by synthesizing an apply_patch V4A string
+// (that approach was tried and abandoned: building a correct V4A envelope
+// from arbitrary old_string/new_string/contents blew up in edge-case
+// complexity for no benefit over a direct fs edit).
+//
+// Contract: tryExecuteExternalToolAdapter(name, args, workDir, options)
+// returns a result STRING when the call was handled (success or a concrete
+// tool-level error), or `null` when the args shape didn't match what the
+// adapter expects — the caller (builtin.mjs default: case) falls back to
+// the existing EXTERNAL_TOOL_REDIRECTS guidance message in that case.
+import { readFileSync, mkdirSync, existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
+import { dirname, sep } from 'node:path';
+import { atomicWrite } 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';
+import { executeBashTool } from './bash-tool.mjs';
+import { invalidateBuiltinResultCache } from './cache-layers.mjs';
+import { markCodeGraphDirtyPaths } from '../code-graph-state.mjs';
+
+const STR_REPLACE_NAMES = new Set(['strreplace', 'str_replace', 'str_replace_editor', 'search_replace']);
+const WRITE_NAMES = new Set(['write', 'create_file', 'createfile']);
+// 'bash'/'Bash' explicitly request the posix/git-bash shell kind; the
+// run/runcommand/terminal/run_terminal_cmd family leaves `shell` unset so
+// executeBashTool's own default-shell resolution applies (mirrors how the
+// native `shell` tool behaves when the caller omits `shell`).
+const BASH_SHELL_KIND_NAMES = new Set(['bash']);
+const BASH_DEFAULT_NAMES = new Set(['run', 'runcommand', 'terminal', 'run_terminal_cmd']);
+
+/**
+ * True when `name` is a foreign-CLI tool this module can adapt natively.
+ * Used by the session loop's dispatch so these names route INTO
+ * executeBuiltinTool (whose default: case invokes the adapter) instead of
+ * short-circuiting to the unknown-tool redirect message.
+ */
+export function isExternalAdapterTool(name) {
+    if (typeof name !== 'string' || !name) return false;
+    const key = name.toLowerCase();
+    return STR_REPLACE_NAMES.has(key) || WRITE_NAMES.has(key)
+        || BASH_SHELL_KIND_NAMES.has(key) || BASH_DEFAULT_NAMES.has(key);
+}
+
+// Same write-target guards the read/list surfaces enforce (UNC → NTLM hash
+// leak, device namespace → raw device access / hang, trailing-dot / ADS →
+// device-guard bypass). Writes are strictly more dangerous than reads, so
+// every adapter write path must run these on both the normalized input and
+// the fully resolved path. Returns an Error string or null.
+function guardWritePath(p) {
+    if (isUncPath(p))
+        return `Error: cannot write UNC / SMB path (network credential leak risk): ${normalizeOutputPath(p)}`;
+    if (isWindowsDevicePath(p))
+        return `Error: cannot write Windows device path (reserved name or raw-device namespace): ${normalizeOutputPath(p)}`;
+    if (hasUnsafeWin32Component(p))
+        return `Error: cannot write Windows path with trailing dot/space or NTFS ADS suffix (bypasses device guard): ${normalizeOutputPath(p)}`;
+    if (isBlockedDevicePath(p))
+        return `Error: cannot write device file (would block or corrupt a device): ${normalizeOutputPath(p)}`;
+    return null;
+}
+
+// Realpath to the nearest existing ancestor (create-mode leaves don't exist
+// yet). Returns { probe, real } or null when nothing on the path exists /
+// realpath itself fails.
+function realpathNearestExisting(fullPath) {
+    let probe = fullPath;
+    while (probe && !existsSync(probe)) {
+        const parent = dirname(probe);
+        if (!parent || parent === probe) return null;
+        probe = parent;
+    }
+    if (!probe || !existsSync(probe)) return null;
+    try { return { probe, real: realpathSync(probe) }; } catch { return null; }
+}
+
+// Realpath-based guard: a symlink/junction in the target (or its nearest
+// existing ancestor, for create-mode paths) can point at a UNC share or a
+// device namespace that the lexical checks above never see. Mirrors the
+// realpath verification apply_patch runs on every header. Returns an Error
+// string or null; never throws.
+function guardRealTarget(fullPath) {
+    const nearest = realpathNearestExisting(fullPath);
+    if (nearest && nearest.real !== nearest.probe) {
+        const guardErr = guardWritePath(nearest.real);
+        if (guardErr) return `${guardErr} (symlink target of ${normalizeOutputPath(nearest.probe)})`;
+    }
+    try {
+        const lst = lstatSync(fullPath);
+        if (lst.isSymbolicLink()) {
+            const realTarget = realpathSync(fullPath);
+            const linkGuardErr = guardWritePath(realTarget);
+            if (linkGuardErr) return `${linkGuardErr} (symlink target of ${normalizeOutputPath(fullPath)})`;
+        }
+        // statSync FOLLOWS a leaf symlink, so a link pointing at a custom
+        // FIFO/socket/char/block inode trips here too (lstat alone only saw
+        // the link inode itself).
+        const st = statSync(fullPath);
+        if (isSpecialFileStat(st))
+            return `Error: cannot write special file (FIFO / character / block device / socket): ${normalizeOutputPath(fullPath)}`;
+    } catch { /* ENOENT (create mode) — nothing to check */ }
+    return null;
+}
+
+// Write containment — mirrors apply_patch's realBase check: the REAL resolved
+// target (symlinks flattened, create-mode suffix re-attached lexically) must
+// stay inside the REAL workDir. A lexically-inside path whose ancestor
+// symlink/junction lands outside the project must not be writable through
+// this adapter surface (apply_patch refuses the same shape).
+function guardBaseContainment(fullPath, workDir) {
+    let realBase;
+    try { realBase = realpathSync(workDir); } catch { return null; }
+    const nearest = realpathNearestExisting(fullPath);
+    if (!nearest) return null;
+    const realResolved = nearest.real + fullPath.slice(nearest.probe.length);
+    const fold = process.platform === 'win32' ? (s) => s.toLowerCase() : (s) => s;
+    const baseWithSep = realBase.endsWith(sep) ? realBase : realBase + sep;
+    if (fold(realResolved) !== fold(realBase) && !fold(realResolved).startsWith(fold(baseWithSep))) {
+        return `Error: cannot write outside the working directory: ${normalizeOutputPath(realResolved)} escapes ${normalizeOutputPath(realBase)}`;
+    }
+    return null;
+}
+
+async function resolveTargetPath(args, workDir) {
+    const raw = args?.path ?? args?.file_path;
+    if (typeof raw !== 'string' || raw.length === 0) return null;
+    const norm = normalizeInputPath(raw);
+    const guardErr = guardWritePath(norm);
+    if (guardErr) return { error: guardErr };
+    const full = resolveAgainstCwd(norm, workDir);
+    const fullGuardErr = guardWritePath(full);
+    if (fullGuardErr) return { error: fullGuardErr };
+    // Reachability preflight BEFORE any sync fs (existsSync/realpathSync/
+    // lstatSync in the guards below): a dead mount would wedge the event loop
+    // on the first sync stat, defeating every downstream timeout. Same
+    // deadline-raced probe the read path runs (_readReachPreflight).
+    try { await assertPathsReachable([full]); }
+    catch (e) { return { error: `Error: ${e?.message || e}` }; }
+    const realGuardErr = guardRealTarget(full);
+    if (realGuardErr) return { error: realGuardErr };
+    const containErr = guardBaseContainment(full, workDir);
+    if (containErr) return { error: containErr };
+    return { full };
+}
+
+function invalidateAfterWrite(fullPath) {
+    try { invalidateBuiltinResultCache([fullPath]); } catch { /* best-effort */ }
+    try { markCodeGraphDirtyPaths([fullPath]); } catch { /* best-effort */ }
+}
+
+function countOccurrences(haystack, needle) {
+    let count = 0;
+    let idx = -1;
+    while ((idx = haystack.indexOf(needle, idx + 1)) !== -1) count += 1;
+    return count;
+}
+
+async function adaptStrReplace(args, workDir, options) {
+    const oldStr = args?.old_string;
+    const newStr = args?.new_string;
+    if (typeof oldStr !== 'string' || typeof newStr !== 'string') return null;
+    // Empty old_string would loop forever in countOccurrences (indexOf('', i)
+    // never returns -1) and has no meaningful replace semantics anyway.
+    if (oldStr.length === 0) return 'Error: old_string must be a non-empty string';
+    const target = await resolveTargetPath(args, workDir);
+    if (!target) return null;
+    if (target.error) return target.error;
+    const fullPath = target.full;
+    let content;
+    let statBefore = null;
+    try {
+        try { statBefore = statSync(fullPath); } catch { /* readFileSync below surfaces the real error */ }
+        content = readFileSync(fullPath, 'utf8');
+    } catch (err) {
+        return `Error: cannot read ${fullPath} (${err?.message || err})`;
+    }
+    const matchCount = countOccurrences(content, oldStr);
+    if (matchCount === 0) return `Error: old_string not found in ${fullPath}`;
+    if (matchCount > 1) return `Error: old_string is ambiguous: ${matchCount} matches in ${fullPath}`;
+    const first = content.indexOf(oldStr);
+    const updated = content.slice(0, first) + newStr + content.slice(first + oldStr.length);
+    // Lost-update guard: hand the pre-read stat to atomicWrite as an expected
+    // target snapshot — it re-stats immediately before EACH rename attempt and
+    // aborts with ESTALE_TARGET when another writer (parallel tool call,
+    // interleaved apply_patch) changed the file after our read. This closes
+    // the check-then-write race a pre-write mtime comparison here would leave.
+    try {
+        await atomicWrite(fullPath, updated, {
+            sessionId: options?.readStateScope || options?.sessionId,
+            expectedTargetSnapshot: statBefore ? {
+                exists: true,
+                size: statBefore.size,
+                mtimeMs: statBefore.mtimeMs,
+                ctimeMs: statBefore.ctimeMs,
+                ino: statBefore.ino,
+            } : undefined,
+        });
+    } catch (err) {
+        if (err?.code === 'ESTALE_TARGET') {
+            return `Error: ${fullPath} changed on disk during the replace; re-read and retry`;
+        }
+        throw err;
+    }
+    invalidateAfterWrite(fullPath);
+    return `Updated ${fullPath} (1 replacement)`;
+}
+
+async function adaptWrite(args, workDir, options) {
+    const contents = args?.contents ?? args?.content ?? args?.file_text;
+    if (typeof contents !== 'string') return null;
+    const target = await resolveTargetPath(args, workDir);
+    if (!target) return null;
+    if (target.error) return target.error;
+    const fullPath = target.full;
+    const existed = existsSync(fullPath);
+    try { mkdirSync(dirname(fullPath), { recursive: true }); } catch { /* best-effort: parent may already exist */ }
+    await atomicWrite(fullPath, contents, { sessionId: options?.readStateScope || options?.sessionId });
+    invalidateAfterWrite(fullPath);
+    return `${existed ? 'Updated' : 'Created'} ${fullPath} (${Buffer.byteLength(contents, 'utf8')} bytes)`;
+}
+
+async function adaptBash(key, args, workDir, options) {
+    if (typeof args?.command !== 'string' || args.command.length === 0) return null;
+    const shellArgs = { ...args };
+    if (BASH_SHELL_KIND_NAMES.has(key) && shellArgs.shell === undefined) shellArgs.shell = 'bash';
+    return executeBashTool(shellArgs, workDir, options);
+}
+
+export async function tryExecuteExternalToolAdapter(name, args, workDir, options) {
+    if (typeof name !== 'string' || !name) return null;
+    if (!args || typeof args !== 'object' || Array.isArray(args)) return null;
+    const key = name.toLowerCase();
+    try {
+        if (STR_REPLACE_NAMES.has(key)) return await adaptStrReplace(args, workDir, options);
+        if (WRITE_NAMES.has(key)) return await adaptWrite(args, workDir, options);
+        if (BASH_SHELL_KIND_NAMES.has(key) || BASH_DEFAULT_NAMES.has(key)) return await adaptBash(key, args, workDir, options);
+    } catch (err) {
+        return `Error: ${name} failed (${err?.message || String(err)})`;
+    }
+    return null;
+}

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

@@ -0,0 +1,162 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { tryExecuteExternalToolAdapter, isExternalAdapterTool } from './external-tool-adapters.mjs';
+
+function makeDir() {
+    return mkdtempSync(join(tmpdir(), 'ext-adapter-test-'));
+}
+
+test('isExternalAdapterTool recognizes adapted names only', () => {
+    assert.equal(isExternalAdapterTool('StrReplace'), true);
+    assert.equal(isExternalAdapterTool('str_replace'), true);
+    assert.equal(isExternalAdapterTool('str_replace_editor'), true);
+    assert.equal(isExternalAdapterTool('search_replace'), true);
+    assert.equal(isExternalAdapterTool('Write'), true);
+    assert.equal(isExternalAdapterTool('create_file'), true);
+    assert.equal(isExternalAdapterTool('Bash'), true);
+    assert.equal(isExternalAdapterTool('run_terminal_cmd'), true);
+    // Destructive / different-shape names stay on the redirect path.
+    assert.equal(isExternalAdapterTool('Delete'), false);
+    assert.equal(isExternalAdapterTool('delete_file'), false);
+    assert.equal(isExternalAdapterTool('edit'), false);
+    assert.equal(isExternalAdapterTool('multiedit'), false);
+    assert.equal(isExternalAdapterTool(''), false);
+    assert.equal(isExternalAdapterTool(null), false);
+});
+
+test('StrReplace: unique match replaces content', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'a.txt');
+    writeFileSync(file, 'alpha\nbeta\ngamma\n');
+    const out = await tryExecuteExternalToolAdapter('StrReplace', {
+        path: file, old_string: 'beta', new_string: 'BETA',
+    }, dir, {});
+    assert.match(out, /^Updated .*\(1 replacement\)$/);
+    assert.equal(readFileSync(file, 'utf8'), 'alpha\nBETA\ngamma\n');
+});
+
+test('StrReplace: zero matches errors without writing', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'a.txt');
+    writeFileSync(file, 'alpha\n');
+    const out = await tryExecuteExternalToolAdapter('str_replace', {
+        path: file, old_string: 'missing', new_string: 'x',
+    }, dir, {});
+    assert.match(out, /old_string not found/);
+    assert.equal(readFileSync(file, 'utf8'), 'alpha\n');
+});
+
+test('StrReplace: ambiguous matches error with count', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'a.txt');
+    writeFileSync(file, 'dup\ndup\n');
+    const out = await tryExecuteExternalToolAdapter('search_replace', {
+        path: file, old_string: 'dup', new_string: 'x',
+    }, dir, {});
+    assert.match(out, /ambiguous: 2 matches/);
+    assert.equal(readFileSync(file, 'utf8'), 'dup\ndup\n');
+});
+
+test('StrReplace: missing old_string falls back (null)', async () => {
+    const dir = makeDir();
+    const out = await tryExecuteExternalToolAdapter('StrReplace', {
+        path: join(dir, 'a.txt'), new_string: 'x',
+    }, dir, {});
+    assert.equal(out, null);
+});
+
+test('StrReplace: unreadable target is a concrete error', async () => {
+    const dir = makeDir();
+    const out = await tryExecuteExternalToolAdapter('StrReplace', {
+        path: join(dir, 'nope.txt'), old_string: 'a', new_string: 'b',
+    }, dir, {});
+    assert.match(out, /^Error: cannot read /);
+});
+
+test('Write: creates a new file with contents', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'new', 'nested.txt');
+    const out = await tryExecuteExternalToolAdapter('Write', {
+        path: file, contents: 'created body',
+    }, dir, {});
+    assert.match(out, /^Created .*nested\.txt \(12 bytes\)$/);
+    assert.equal(readFileSync(file, 'utf8'), 'created body');
+});
+
+test('Write: overwrites an existing file and says Updated', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'exists.txt');
+    writeFileSync(file, 'old');
+    const out = await tryExecuteExternalToolAdapter('write', {
+        file_path: file, content: 'new body',
+    }, dir, {});
+    assert.match(out, /^Updated /);
+    assert.equal(readFileSync(file, 'utf8'), 'new body');
+});
+
+test('Write: missing contents falls back to redirect (null)', async () => {
+    const dir = makeDir();
+    const out = await tryExecuteExternalToolAdapter('Write', {
+        path: join(dir, 'x.txt'),
+    }, dir, {});
+    assert.equal(out, null);
+    assert.equal(existsSync(join(dir, 'x.txt')), false);
+});
+
+test('StrReplace: missing old_string/new_string falls back (null)', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'a.txt');
+    writeFileSync(file, 'body');
+    const out = await tryExecuteExternalToolAdapter('StrReplace', {
+        path: file, old_string: 'body',
+    }, dir, {});
+    assert.equal(out, null);
+});
+
+test('StrReplace: empty old_string is a concrete error (no hang)', async () => {
+    const dir = makeDir();
+    const file = join(dir, 'a.txt');
+    writeFileSync(file, 'body');
+    const out = await tryExecuteExternalToolAdapter('StrReplace', {
+        path: file, old_string: '', new_string: 'x',
+    }, dir, {});
+    assert.match(out, /old_string must be a non-empty string/);
+    assert.equal(readFileSync(file, 'utf8'), 'body');
+});
+
+test('bash family: missing command falls back (null)', async () => {
+    const dir = makeDir();
+    const out = await tryExecuteExternalToolAdapter('Bash', {}, dir, {});
+    assert.equal(out, null);
+});
+
+test('Write: target outside workDir is refused (base containment)', async () => {
+    const workDir = makeDir();
+    const outsideDir = makeDir();
+    const outside = join(outsideDir, 'escape.txt');
+    const out = await tryExecuteExternalToolAdapter('Write', {
+        path: outside, contents: 'should not land',
+    }, workDir, {});
+    assert.match(out, /cannot write outside the working directory/);
+    assert.equal(existsSync(outside), false);
+});
+
+test('non-adapted names return null without touching fs', async () => {
+    const dir = makeDir();
+    const out = await tryExecuteExternalToolAdapter('Delete', {
+        path: join(dir, 'x.txt'),
+    }, dir, {});
+    assert.equal(out, null);
+});
+
+test('bash family: executes a command via the shell runner', async () => {
+    const dir = makeDir();
+    const out = await tryExecuteExternalToolAdapter('run_terminal_cmd', {
+        command: 'node -e "console.log(\'adapter-ok\')"',
+    }, dir, {});
+    assert.equal(typeof out, 'string');
+    assert.match(out, /adapter-ok/);
+});

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

@@ -1,5 +1,5 @@
 // fuzzy-match.mjs — lightweight subsequence fuzzy scorer for filename / path
-// search (codex file-search / nucleo style, in JS). Returns a score where a
+// search. Returns a score where a
 // higher value is a better match, or null when the query is not a subsequence
 // of the candidate.
 //

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

@@ -1,5 +1,5 @@
-import { readdirSync } from 'fs';
-import { basename, dirname, extname, isAbsolute, join, relative } from 'path';
+import { readdirSync, statSync } from 'fs';
+import { basename, dirname, extname, isAbsolute, join, relative, sep } from 'path';
 import { homedir } from 'os';
 import { resolvePluginData, mixdogRoot } from '../../../../shared/plugin-paths.mjs';
 
@@ -80,6 +80,46 @@ export function findFileByBasename(searchRoot, fullPath, { limit = 3, maxDirs =
     } catch { return []; }
 }
 
+// Recover a hallucinated absolute-path PREFIX: models frequently request
+// paths like /Users/foo/Local/Project/ink/src/tui/input-editing.mjs where the
+// TAIL (src/tui/input-editing.mjs) is the real repo-relative path but the
+// leading segments are an invented (or wrong-machine) prefix. findFileByBasename
+// only matches the final basename and walks the whole tree (skipping vendor/
+// noise dirs for performance); this instead peels leading segments off the
+// requested path one at a time and stats the remaining tail directly against
+// searchRoot — no directory walk, no skip-dir filtering, so it finds files
+// under vendor/ or any other normally-skipped directory. Min tail length is 2
+// segments so a bare basename (which would match almost anything) never
+// counts as a hit. Capped iterations; pure best-effort, never throws.
+export function findBySuffixStrip(searchRoot, fullPath, { maxIterations = 12 } = {}) {
+    try {
+        if (typeof searchRoot !== 'string' || !searchRoot) return null;
+        if (typeof fullPath !== 'string' || !fullPath) return null;
+        // Containment guard: drop `.`/`..` and drive/UNC-ish segments outright.
+        // Tails are joined under searchRoot; a `..` segment could stat (and
+        // hint) outside the repo, so no relative-traversal token may survive.
+        const segments = fullPath.replace(/\\/g, '/').split('/')
+            .filter((s) => s && s !== '.' && s !== '..' && !/^[A-Za-z]:$/.test(s));
+        // Peel 0..N leading segments; each peel costs one stat. maxIterations
+        // bounds the number of stats (strict <), and tails shorter than 2
+        // segments never count as a hit.
+        const iterations = Math.min(Math.max(segments.length - 1, 0), Math.max(maxIterations, 0));
+        for (let i = 0; i < iterations; i++) {
+            const tail = segments.slice(i);
+            if (tail.length < 2) break;
+            const candidate = join(searchRoot, ...tail);
+            const rel = relative(searchRoot, candidate);
+            if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) continue;
+            try {
+                if (statSync(candidate).isFile()) {
+                    return rel.replace(/\\/g, '/');
+                }
+            } catch { /* miss this tail length, keep peeling */ }
+        }
+        return null;
+    } catch { return null; }
+}
+
 // Node's native fs errors embed the failing path wrapped in single quotes
 // using OS-native separators ('C:\\Users\\foo\\bar.mjs' on Windows). Without
 // this pass, read error bodies surface backslash paths that

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

@@ -20,7 +20,7 @@ export const SMART_READ_TAIL_LINES = _readEnvInt('MIXDOG_READ_TAIL_LINES', 400);
 // file actually hurts.
 export const READ_CONTEXT_ADVISORY_BYTES = 40 * 1024;
 export const READ_MAX_RENDERED_LINE_CHARS = 2_000;
-// Claude-Code parity: the read line-prefix separator is `→` (the `→`
+// The read line-prefix separator is `→` (the `→`
 // arrow), matching default cat -n format `<n>→<content>`. It
 // MUST be a NON-WHITESPACE glyph: a tab/space separator collides with the
 // content's own leading indentation, so a model hand-reconstructing an edit

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

@@ -3,7 +3,7 @@ import * as fsPromises from 'fs/promises';
 import { readFile } from 'fs/promises';
 import { extname } from 'path';
 import { normalizeInputPath } from './path-utils.mjs';
-import { findFileByBasename } from './path-diagnostics.mjs';
+import { findFileByBasename, findBySuffixStrip } from './path-diagnostics.mjs';
 import { getReadSnapshot } from './read-snapshot-runtime.mjs';
 import { snapshotCoversFullFile, statMatchesSnapshot } from './snapshot-helpers.mjs';
 import { formatBinaryReadPreview } from './binary-file.mjs';
@@ -209,9 +209,16 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
         // path(s) directly — the route a model would otherwise reconstruct with
         // a grep/glob storm.
         if (!similar) {
-            const elsewhere = findFileByBasename(workDir, fullPath);
-            if (elsewhere.length) {
-                hint = ` Not found at this path; the same filename exists at: ${elsewhere.map((p) => `"${normalizeOutputPath(p)}"`).join(', ')}. Read that path directly.`;
+            // Hallucinated absolute-prefix recovery first: no directory walk,
+            // stats directly (finds vendor/ paths the basename BFS skips).
+            const suffixHit = findBySuffixStrip(workDir, fullPath);
+            if (suffixHit) {
+                hint = ` Not found at this path; the same filename exists at: "${normalizeOutputPath(suffixHit)}". Read that path directly.`;
+            } else {
+                const elsewhere = findFileByBasename(workDir, fullPath);
+                if (elsewhere.length) {
+                    hint = ` Not found at this path; the same filename exists at: ${elsewhere.map((p) => `"${normalizeOutputPath(p)}"`).join(', ')}. Read that path directly.`;
+                }
             }
         }
         const _rawMsg = err instanceof Error ? err.message : String(err);

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

@@ -1,6 +1,7 @@
 import { statSync } from 'fs';
 import { isAbsolute, resolve } from 'path';
 import { trueCasePath } from './path-utils.mjs';
+import { findBySuffixStrip } from './path-diagnostics.mjs';
 import {
     canonicalizeGlobSlashes,
     coerceShapeFlex,
@@ -478,6 +479,10 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
     try { grepStat = statSync(grepResolvedPath); }
     catch (err) {
         const msg = `Error: path does not exist: ${normalizeOutputPath(grepResolvedPath)} (${err?.code || 'ENOENT'})`;
+        const suffixHit = findBySuffixStrip(workDir, grepResolvedPath);
+        if (suffixHit) {
+            return msg + ` Not found at this path; the same filename exists at: "${normalizeOutputPath(suffixHit)}". Search that path directly.`;
+        }
         return msg + await _suggestIndexedPaths(grepResolvedPath, executeChildBuiltinTool, workDir);
     }
     const filenameOmitted = grepStat.isFile();