mixdog 0.7.17 → 0.8.0

package/src/runtime/agent/orchestrator/tools/builtin/native-edit-runner.mjs

@@ -0,0 +1,110 @@
+import { existsSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { performance } from 'perf_hooks';
+import { fileURLToPath } from 'url';
+import { snapshotCoversFullFile } from './snapshot-helpers.mjs';
+import { getPluginData } from '../../config.mjs';
+import { findCachedPatchBinary } from '../patch-binary-fetcher.mjs';
+import { runServerEdit } from '../patch.mjs';
+
+const PLUGIN_ROOT = process.env.MIXDOG_ROOT
+    || resolve(dirname(fileURLToPath(import.meta.url)), '../../../../..');
+const NATIVE_EDIT_DEFAULT_BIN = join(
+    PLUGIN_ROOT,
+    'native/mixdog-patch/target/release',
+    process.platform === 'win32' ? 'mixdog-patch.exe' : 'mixdog-patch',
+);
+
+export function nativeEditMode() {
+    return String(process.env.MIXDOG_EDIT_NATIVE || 'auto').toLowerCase();
+}
+
+function nativeEditBinCandidate() {
+    const override = process.env.MIXDOG_EDIT_NATIVE_BIN || process.env.MIXDOG_PATCH_NATIVE_BIN;
+    if (override) return { path: override, kind: 'override' };
+    if (existsSync(NATIVE_EDIT_DEFAULT_BIN)) return { path: NATIVE_EDIT_DEFAULT_BIN, kind: 'local' };
+    const cached = findCachedPatchBinary(getPluginData());
+    if (cached) return { path: cached, kind: 'cached' };
+    return { path: NATIVE_EDIT_DEFAULT_BIN, kind: 'missing' };
+}
+
+export function nativeEditBinPath() {
+    return nativeEditBinCandidate().path;
+}
+
+export function nativeEditShouldAttempt({ editSnapshot, oldStr, newStr, preloadedContent, preloadedRawBuf }) {
+    const mode = nativeEditMode();
+    if (/^(0|false|no|off|js|legacy)$/i.test(mode)) return false;
+    const forcedNative = /^(1|true|yes|on|native)$/i.test(mode);
+    const candidate = nativeEditBinCandidate();
+    if (!existsSync(candidate.path)) return false;
+    // Cached release prebuilds are guaranteed valid for apply_patch, but older
+    // manifests (currently v0.6.5 in clean CI) predate the EDIT server protocol.
+    // In auto mode, native edit is only an acceleration, so require either a
+    // local cargo build or an explicit override. If a user forces native mode,
+    // still try the cached binary and surface any protocol failure.
+    if (candidate.kind === 'cached' && !forcedNative) return false;
+    if (!snapshotCoversFullFile(editSnapshot)) return false;
+    if (preloadedContent !== null || preloadedRawBuf !== null) return false;
+    if (typeof oldStr !== 'string' || oldStr.length === 0 || typeof newStr !== 'string') return false;
+    if (forcedNative) return true;
+    // auto: the persistent server removed per-call spawn cost, so route edits to
+    // native edit2 by default (B3). Same-size edits keep the JS in-place partial
+    // write, which rewrites bytes in place instead of the whole file.
+    const oldBytes = Buffer.byteLength(oldStr, 'utf-8');
+    const newBytes = Buffer.byteLength(newStr, 'utf-8');
+    if (oldBytes === newBytes) return false;
+    return true;
+}
+
+export async function runNativeExactEdit({ fullPath, oldStr, newStr, replaceAll, signal = null }) {
+    const forcedNative = /^(1|true|yes|on|native)$/i.test(nativeEditMode());
+    if (signal?.aborted) {
+        return { ok: false, fallback: false, error: signal.reason?.message || signal.reason || 'native edit aborted' };
+    }
+    const oldBuf = Buffer.from(oldStr, 'utf-8');
+    const newBuf = Buffer.from(newStr, 'utf-8');
+    const started = performance.now();
+    try {
+        // PARITY GUARD: the native engine MATCHES via the curly-quote fold
+        // tier but applies new_string verbatim, silently downgrading the
+        // file's typographic quotes (JS slow path preserves them via
+        // preserveQuoteTypography). When old_string carries quote-family
+        // chars — the only inputs that can land on the curly tier — probe
+        // with a dry run (persistent server, ~ms) and defer curly-tier
+        // matches to the JS editor.
+        if (/["'‘’“”]/.test(oldStr)) {
+            const probe = await runServerEdit({ fullPath, oldBuf, newBuf, replaceAll, dryRun: true, signal });
+            if (probe?.tier === 'curly') {
+                return { ok: false, fallback: true, error: 'curly-quote fold match — deferred to JS editor for typography preservation' };
+            }
+        }
+        const res = await runServerEdit({ fullPath, oldBuf, newBuf, replaceAll, signal });
+        return {
+            ok: true,
+            replacements: res.replacements,
+            readMs: res.readMs,
+            applyMs: res.applyMs,
+            writeMs: res.writeMs,
+            totalMs: res.totalMs,
+            roundtripMs: res.roundtripMs ?? (performance.now() - started),
+            stage: res.tier,
+            contentHash: res.contentHash,
+        };
+    } catch (err) {
+        if (err?.name === 'AbortError') {
+            return { ok: false, fallback: false, error: err.message };
+        }
+        const msg = String(err?.message || err);
+        // Tier misses and not-found map to a JS fallback; transport/spawn errors
+        // also fall back so a server hiccup never blocks an edit. Older cached
+        // mixdog-patch binaries (for example the v0.6.5 release prebuilds used
+        // by clean CI before a local cargo build exists) support APPLY but not
+        // the EDIT server protocol, and answer EDIT with the APPLY parser's
+        // "bad header" error. In auto mode that means "native edit unavailable",
+        // not "the edit is invalid", so fall through to the JS editor. When the
+        // user explicitly forces native mode, keep surfacing the native failure.
+        const fallback = !forcedNative && /old_string (?:not found|found \d+ times)|not valid UTF-8|no exact match|not found|server|bad header|bad edit header/i.test(msg);
+        return { ok: false, fallback, error: msg };
+    }
+}

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

@@ -0,0 +1,153 @@
+import { readdirSync } from 'fs';
+import { basename, dirname, extname, isAbsolute, join, relative } from 'path';
+import { homedir } from 'os';
+import { resolvePluginData, mixdogRoot } from '../../../../shared/plugin-paths.mjs';
+
+// Suggest a sibling file the caller may have meant when the requested
+// path is missing: same stem with a different extension, or a same-name
+// sibling differing only in case. Pure best-effort; any fs error returns
+// null so the caller falls back to the bare "not found" message.
+export function findSimilarFile(fullPath) {
+    try {
+        const dir = dirname(fullPath);
+        const base = basename(fullPath);
+        const stem = basename(fullPath, extname(fullPath));
+        const entries = readdirSync(dir);
+        const sameStem = entries.find((e) => e !== base && basename(e, extname(e)) === stem);
+        if (sameStem) return join(dir, sameStem);
+        const caseMatch = entries.find((e) => e !== base && e.toLowerCase() === base.toLowerCase());
+        if (caseMatch) return join(dir, caseMatch);
+        return null;
+    } catch { return null; }
+}
+
+// Sibling listing for ENOENT diagnostics. Pure information extension —
+// callers always receive the directory's existing entries (capped) inline
+// in the error hint, removing the recovery cost of a follow-up list/glob
+// call. Measurement showed ENOENT recovery consistently runs read→glob/
+// list→read (4-call); siblings inline collapses that to read→read.
+export function listSiblings(dir, limit = 12) {
+    try {
+        return readdirSync(dir).filter((n) => !n.startsWith('.')).slice(0, limit);
+    } catch { return []; }
+}
+
+// Locate a missing file's basename ELSEWHERE under the search root. The most
+// common ENOENT cause is a right-name / wrong-directory path (e.g. asking for
+// `webhook.mjs` when the file lives at `src/channels/lib/webhook.mjs`).
+// findSimilarFile only inspects the same directory, so a wrong-directory miss
+// gets no hint and the caller reconstructs the real path with a grep/glob
+// storm. This walks the root (BFS — shallow hits first), skipping noise dirs
+// and hard-capped on directories scanned, and returns up to `limit` real
+// locations so the error can name them directly. Pure best-effort; any error
+// returns [].
+const BASENAME_SCAN_SKIP_DIRS = new Set([
+    'node_modules', '.git', '.hg', '.svn', 'dist', 'build', 'out',
+    'coverage', '.next', '.nuxt', '.turbo', '.cache', 'vendor',
+    'target', '.venv', 'venv', '__pycache__', '.idea', '.vscode',
+]);
+export function findFileByBasename(searchRoot, fullPath, { limit = 3, maxDirs = 6000 } = {}) {
+    try {
+        if (typeof searchRoot !== 'string' || !searchRoot) return [];
+        const target = basename(fullPath).toLowerCase();
+        if (!target) return [];
+        const matches = [];
+        const queue = [searchRoot];
+        let scanned = 0;
+        while (queue.length && matches.length < limit && scanned < maxDirs) {
+            const dir = queue.shift();
+            scanned++;
+            let entries;
+            try { entries = readdirSync(dir, { withFileTypes: true }); }
+            catch { continue; }
+            for (const ent of entries) {
+                const name = ent.name;
+                if (ent.isDirectory()) {
+                    if (name.startsWith('.') || BASENAME_SCAN_SKIP_DIRS.has(name)) continue;
+                    queue.push(join(dir, name));
+                } else if (ent.isFile() && name.toLowerCase() === target) {
+                    const hit = join(dir, name);
+                    if (hit !== fullPath) {
+                        // Return search-root-relative so the hint stays leak-safe
+                        // (no home / cache absolute) and is directly read-usable.
+                        matches.push(relative(searchRoot, hit));
+                        if (matches.length >= limit) break;
+                    }
+                }
+            }
+        }
+        return matches;
+    } catch { return []; }
+}
+
+// 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
+// break the forward-slash convention the rest of the tool output keeps.
+// Accepts an optional workDir to produce cwd-relative paths. This pass also
+// closes the R14 tool-result info-leak boundary: home dir / Mixdog root /
+// Mixdog data / runtime dir absolutes are rewritten into stable tokens so
+// model-facing error bodies never carry environment-specific filesystem
+// segments. Full detail is retained in local logs upstream of this call.
+//
+// Replacement priority for any absolute path encountered:
+//   1. cwd-relative      (workDir set and path is inside workDir)
+//   2. <runtime>/...     (MIXDOG_RUNTIME_ROOT prefix)
+//   3. <mixdog-data>/... (Mixdog data dir)
+//   4. <mixdog-root>/...
+//   5. ~/...             (OS home directory prefix)
+//   6. forward-slash normalised absolute (Windows backslash → slash, no leak)
+//
+// Two surface forms are scrubbed:
+//   * quoted drive-letter / POSIX absolute paths inside the message body
+//   * bare `file:///C:/...` or `file:///abs/...` stack-frame URIs (no quotes)
+// More-specific prefixes are checked first so plugin-data wins over the
+// containing home directory.
+export function normalizeErrorMessage(msg, workDir) {
+    if (typeof msg !== 'string') return msg;
+    const home = homedir().replace(/\\/g, '/');
+    const pluginRoot = mixdogRoot().replace(/\\/g, '/');
+    const pluginData = resolvePluginData().replace(/\\/g, '/');
+    const runtimeDir = (process.env.MIXDOG_RUNTIME_ROOT || '').replace(/\\/g, '/');
+    const cwd = typeof workDir === 'string' && workDir ? workDir.replace(/\\/g, '/') : '';
+
+    const redact = (raw) => {
+        const fwd = raw.replace(/\\/g, '/');
+        if (cwd) {
+            try {
+                const rel = relative(cwd, fwd);
+                if (rel && !rel.startsWith('..') && !isAbsolute(rel)) {
+                    return rel.replace(/\\/g, '/');
+                }
+            } catch { /* fall through */ }
+        }
+        if (runtimeDir && (fwd === runtimeDir || fwd.startsWith(runtimeDir + '/'))) {
+            return `<runtime>${fwd.slice(runtimeDir.length)}`;
+        }
+        if (pluginData && (fwd === pluginData || fwd.startsWith(pluginData + '/'))) {
+            return `<mixdog-data>${fwd.slice(pluginData.length)}`;
+        }
+        if (pluginRoot && (fwd === pluginRoot || fwd.startsWith(pluginRoot + '/'))) {
+            return `<mixdog-root>${fwd.slice(pluginRoot.length)}`;
+        }
+        if (home && (fwd === home || fwd.startsWith(home + '/'))) {
+            return `~${fwd.slice(home.length)}`;
+        }
+        return fwd;
+    };
+
+    // 1. Strip bare `file:///...` stack-frame URIs first so the inner path
+    //    survives the quoted-path pass that follows (URIs aren't quoted).
+    let out = msg.replace(
+        /file:\/\/\/([A-Za-z]:\/[^\s'"<>)\]]+|\/[^\s'"<>)\]]+)/g,
+        (_m, p) => redact(p),
+    );
+
+    // 2. Redact quoted drive-letter (Windows) and POSIX absolute paths.
+    out = out.replace(
+        /(['"])([A-Za-z]:[\\\/][^'"]+|\/[^'"]+)\1/g,
+        (_m, q, p) => `${q}${redact(p)}${q}`,
+    );
+
+    return out;
+}

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

@@ -0,0 +1,118 @@
+import { mergeReadRanges } from './read-ranges.mjs';
+
+export const SMART_READ_MAX_BYTES = 30 * 1024;
+export const SMART_READ_MAX_LINES = 600;
+export const SMART_READ_HEAD_LINES = 200;
+export const SMART_READ_TAIL_LINES = 100;
+// Only the genuinely large full reads warrant the anti-re-read advisory; below
+// this the smart-truncate path (30 KB) already caps normal reads, so a 16 KB
+// floor mostly fired on full:true mid-size reads where the advisory was pure
+// tail bloat. Raised to 40 KB to keep the guidance only where re-reading a big
+// 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 `→`
+// arrow), matching Claude Code's 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
+// old_string cannot tell the separator from the indent and produces
+// byte-mismatched anchors (grep finds the substring, edit cannot). All
+// read/edit parsers accept `[\t│→]`, so any in-flight tab/pipe-rendered
+// output stays backward-compatible.
+export const LINE_NO_SEP = '→';
+
+export function buildSmartReadTruncationMarker(totalLines, fileBytes, _filePath = '') {
+    const kb = Math.max(1, Math.round((Number(fileBytes) || 0) / 1024));
+    return `... [TRUNCATED - ${totalLines} lines / ${kb} KB] ...`;
+}
+
+function rangeFromRenderedReadRows(rows, fallbackStartLine = 1) {
+    if (!Array.isArray(rows) || rows.length === 0) return null;
+    const nums = [];
+    for (const row of rows) {
+        const m = /^(\d+)[\t│→]/.exec(String(row));
+        if (m) nums.push(Number(m[1]));
+    }
+    if (nums.length > 0) {
+        return { startLine: Math.min(...nums), endLine: Math.max(...nums) };
+    }
+    return {
+        startLine: Math.max(1, Number(fallbackStartLine) || 1),
+        endLine: Math.max(1, (Number(fallbackStartLine) || 1) + rows.length - 1),
+    };
+}
+
+// Optional `budget` { maxLines, headLines, tailLines } lets a caller request a
+// TIGHTER head+tail elision than the 600-line / 200+100 default (e.g. read
+// budget:'compact' or max_lines:N) to bound lead-context cost. Omitted -> the
+// standard caps, so existing 4-arg callers are byte-for-byte unchanged.
+export function smartReadTruncate(renderedWithLineNos, totalLines, fileBytes, filePath = '', budget = null) {
+    const maxLines = budget?.maxLines ?? SMART_READ_MAX_LINES;
+    const headLines = budget?.headLines ?? SMART_READ_HEAD_LINES;
+    const tailLines = budget?.tailLines ?? SMART_READ_TAIL_LINES;
+    const overByBytes = fileBytes > SMART_READ_MAX_BYTES;
+    const overByLines = totalLines > maxLines;
+    if (!overByBytes && !overByLines) {
+        return { text: renderedWithLineNos, truncated: false, totalLines, ranges: null };
+    }
+    const rows = renderedWithLineNos.split('\n');
+    const headCount = Math.min(headLines, rows.length);
+    const tailStart = Math.max(headCount, rows.length - tailLines);
+    const elidedRows = tailStart - headCount;
+    if (elidedRows <= 0) {
+        return { text: renderedWithLineNos, truncated: false, totalLines, ranges: null };
+    }
+    const headRows = rows.slice(0, headCount);
+    const tailRows = rows.slice(tailStart);
+    const head = headRows.join('\n');
+    const tail = tailRows.join('\n');
+    const marker = buildSmartReadTruncationMarker(totalLines, fileBytes, filePath);
+    return {
+        text: `${head}\n${marker}\n${tail}`,
+        truncated: true,
+        totalLines,
+        ranges: mergeReadRanges([
+            rangeFromRenderedReadRows(headRows, 1),
+            rangeFromRenderedReadRows(tailRows, tailStart + 1),
+        ].filter(Boolean)),
+    };
+}
+
+export function appendReadContextAdvisory(out, { filePath: _filePath, lineCount: _lineCount, bytes: _bytes }) {
+    return out;
+}
+
+export function formatPaginationHint(remaining, nextOffset) {
+    const n = Number(remaining);
+    const label = Number.isFinite(n) && n > 0 ? `${n} more entries` : 'more entries';
+    return `... [${label}; next offset: ${nextOffset}]`;
+}
+
+export function parseOffsetArg(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.trunc(n) : 0;
+}
+
+export function parseLineLimitArg(value, defaultValue) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return defaultValue;
+    if (n === 0) return Infinity;
+    return Math.max(1, Math.trunc(n));
+}
+
+export function truncateReadLineText(line, { truncateLongLine = true } = {}) {
+    let text = String(line ?? '');
+    const originalLength = text.length;
+    if (truncateLongLine && text.length > READ_MAX_RENDERED_LINE_CHARS) {
+        const cps = [...text];
+        const head = cps.slice(0, 1_500).join('');
+        const tail = cps.slice(-300).join('');
+        text = `${head} ... [line truncated: ${originalLength} chars total] ... ${tail}`;
+    }
+    return text;
+}
+
+export function renderReadLine(lineNo, line, { truncateLongLine = true } = {}) {
+    const text = truncateReadLineText(line, { truncateLongLine });
+    return `${lineNo}${LINE_NO_SEP}${text}`;
+}

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

@@ -0,0 +1,189 @@
+import { closeSync, lstatSync, openSync, readSync, realpathSync, statSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { dirname } from 'path';
+import {
+    normalizeOutputPath,
+    resolveAgainstCwd,
+} from './path-utils.mjs';
+import {
+    findSimilarFile,
+    listSiblings,
+    normalizeErrorMessage,
+} from './path-diagnostics.mjs';
+import { isBinaryFile } from './binary-file.mjs';
+import { READ_MAX_SIZE_BYTES } from './read-constants.mjs';
+import { normalizePathAndStripLineCoordinate } from './read-args.mjs';
+import {
+    isBlockedDevicePath,
+    isSpecialFileStat,
+    isUncPath,
+    isWindowsDevicePath,
+    hasUnsafeWin32Component,
+} from './device-paths.mjs';
+
+function detectReadEncodingFromBuffer(head) {
+    const n = head.length;
+    if (n >= 2 && head[0] === 0xff && head[1] === 0xfe) {
+        return { encoding: 'utf16le', bomLen: 2 };
+    }
+    if (n >= 2 && head[0] === 0xfe && head[1] === 0xff) {
+        return { encoding: 'utf16be', bomLen: 2 };
+    }
+    if (n >= 3 && head[0] === 0xef && head[1] === 0xbb && head[2] === 0xbf) {
+        return { encoding: 'utf8', bomLen: 3 };
+    }
+    return { encoding: 'utf8', bomLen: 0 };
+}
+
+export function detectReadEncoding(fullPath) {
+    let fd;
+    try {
+        fd = openSync(fullPath, 'r');
+        const head = Buffer.alloc(3);
+        const n = readSync(fd, head, 0, 3, 0);
+        return detectReadEncodingFromBuffer(head.subarray(0, n));
+    } catch {
+        return { encoding: 'utf8', bomLen: 0 };
+    } finally {
+        if (fd !== undefined) { try { closeSync(fd); } catch {} }
+    }
+}
+
+function decodeReadBuffer(buf, enc) {
+    if (enc.encoding === 'utf16le') {
+        return buf.subarray(enc.bomLen).toString('utf16le');
+    }
+    if (enc.encoding === 'utf16be') {
+        // Node has no 'utf16be' string encoding; swap byte pairs to LE in a
+        // copy, then decode as utf16le. swap16 needs an even length, so drop a
+        // trailing odd byte before swapping.
+        const body = buf.subarray(enc.bomLen);
+        const even = body.length & ~1;
+        return Buffer.from(body.subarray(0, even)).swap16().toString('utf16le');
+    }
+    const slice = enc.bomLen ? buf.subarray(enc.bomLen) : buf;
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(slice);
+    } catch (err) {
+        const e = new Error(`invalid UTF-8 in text file: ${err instanceof Error ? err.message : String(err)}`);
+        e.code = 'EUTF8';
+        throw e;
+    }
+}
+
+/** String-phase guards shared by full read and mode reads. Returns error message or null. */
+export function readPathStringGuardError(filePath, workDir) {
+    if (typeof filePath !== 'string' || !filePath) {
+        return 'path is required';
+    }
+    const guardedPath = normalizePathAndStripLineCoordinate(filePath, workDir);
+    if (isUncPath(guardedPath)) {
+        return `cannot read UNC / SMB path (network credential leak risk): ${normalizeOutputPath(guardedPath)}`;
+    }
+    if (isWindowsDevicePath(guardedPath)) {
+        return `cannot read Windows device path (reserved name or raw-device namespace): ${normalizeOutputPath(guardedPath)}`;
+    }
+    if (hasUnsafeWin32Component(guardedPath)) {
+        return `cannot read Windows path with trailing dot/space or NTFS ADS suffix (bypasses device guard): ${normalizeOutputPath(guardedPath)}`;
+    }
+    if (isBlockedDevicePath(guardedPath)) {
+        return `cannot read device file (would block or produce infinite output): ${normalizeOutputPath(guardedPath)}`;
+    }
+    const fullPath = resolveAgainstCwd(guardedPath, workDir);
+    if (isUncPath(fullPath)) {
+        return `cannot read UNC / SMB path (network credential leak risk): ${normalizeOutputPath(fullPath)}`;
+    }
+    if (isWindowsDevicePath(fullPath)) {
+        return `cannot read Windows device path (reserved name or raw-device namespace): ${normalizeOutputPath(fullPath)}`;
+    }
+    if (hasUnsafeWin32Component(fullPath)) {
+        return `cannot read Windows path with trailing dot/space or NTFS ADS suffix (bypasses device guard): ${normalizeOutputPath(fullPath)}`;
+    }
+    if (isBlockedDevicePath(fullPath)) {
+        return `cannot read device file (would block or produce infinite output): ${normalizeOutputPath(fullPath)}`;
+    }
+    return null;
+}
+
+/** Post-stat / symlink guards. Returns error message or null. */
+export function readPathStatGuardError(userPath, fullPath, st) {
+    if (isSpecialFileStat(st)) {
+        return `cannot read special file (FIFO / character / block device / socket): ${normalizeOutputPath(userPath)}`;
+    }
+    try {
+        const lst = lstatSync(fullPath);
+        if (lst?.isSymbolicLink?.()) {
+            let realTarget = null;
+            try { realTarget = realpathSync(fullPath); } catch { realTarget = null; }
+            if (realTarget && realTarget !== fullPath) {
+                if (isBlockedDevicePath(realTarget)) {
+                    return `cannot read device file via symlink (would block or produce infinite output): ${normalizeOutputPath(userPath)} → ${normalizeOutputPath(realTarget)}`;
+                }
+                if (isUncPath(realTarget)) {
+                    return `cannot read UNC / SMB path via symlink (network credential leak risk): ${normalizeOutputPath(userPath)} → ${normalizeOutputPath(realTarget)}`;
+                }
+                if (isWindowsDevicePath(realTarget)) {
+                    return `cannot read Windows device path via symlink (reserved name or raw-device namespace): ${normalizeOutputPath(userPath)} → ${normalizeOutputPath(realTarget)}`;
+                }
+                try {
+                    const rst = statSync(realTarget);
+                    if (isSpecialFileStat(rst)) {
+                        return `cannot read special file via symlink (FIFO / character / block device / socket): ${normalizeOutputPath(userPath)} → ${normalizeOutputPath(realTarget)}`;
+                    }
+                } catch { /* ENOENT surfaces later */ }
+            }
+        }
+    } catch { /* best-effort */ }
+    return null;
+}
+
+// Shared file-open prologue for read-flavoured tools (tail / wc / diff / modes).
+export function openTextPathForReadMeta(filePath, workDir, opts = {}) {
+    const guardErr = readPathStringGuardError(filePath, workDir);
+    if (guardErr) {
+        throw Object.assign(new Error(guardErr), { code: 'EARG' });
+    }
+    const norm = normalizePathAndStripLineCoordinate(filePath, workDir);
+    const fullPath = resolveAgainstCwd(norm, workDir);
+    let st;
+    try { st = statSync(fullPath); }
+    catch (err) {
+        const similar = findSimilarFile(fullPath);
+        const siblings = listSiblings(dirname(fullPath));
+        const hint = (similar ? ` Did you mean "${normalizeOutputPath(similar)}"?` : '')
+                   + ` Siblings: [${siblings.join(', ')}].`;
+        const msg = normalizeErrorMessage(err instanceof Error ? err.message : String(err)) + hint;
+        throw Object.assign(new Error(msg), { code: 'ENOENT' });
+    }
+    const statGuard = readPathStatGuardError(filePath, fullPath, st);
+    if (statGuard) {
+        throw Object.assign(new Error(statGuard), { code: 'ESPECIAL' });
+    }
+    if (opts.enforceSizeCap !== false && st.size > READ_MAX_SIZE_BYTES) {
+        throw Object.assign(
+            new Error(`file size ${st.size} bytes exceeds ${READ_MAX_SIZE_BYTES}-byte cap`),
+            { code: 'ETOOBIG', size: st.size, fullPath, st });
+    }
+    if (opts.skipBinary !== true && isBinaryFile(fullPath, st.size)) {
+        throw Object.assign(
+            new Error(`file appears to be binary (contains null bytes): ${normalizeOutputPath(norm)}`),
+            { code: 'EBINARY' });
+    }
+    return { fullPath, displayPath: normalizeOutputPath(norm), st, size: st.size };
+}
+
+export async function openForRead(filePath, workDir, opts = {}) {
+    const meta = openTextPathForReadMeta(filePath, workDir, opts);
+    const rawBuf = await readFile(meta.fullPath);
+    const enc = detectReadEncodingFromBuffer(rawBuf.subarray(0, Math.min(rawBuf.length, 3)));
+    let content;
+    try {
+        content = decodeReadBuffer(rawBuf, enc);
+    } catch (err) {
+        if (err?.code === 'EUTF8' && opts.routeInvalidUtf8ToHex === true) {
+            throw Object.assign(new Error(err.message), { code: 'EUTF8', fullPath: meta.fullPath, st: meta.st });
+        }
+        throw err;
+    }
+    return { ...meta, content, readEncoding: enc };
+}