mixdog 0.7.1

package/src/agent/orchestrator/tools/builtin/cwd-utils.mjs

@@ -0,0 +1,37 @@
+import { statSync } from 'fs';
+import { isAbsolute, resolve } from 'path';
+import {
+    normalizeInputPath,
+    normalizeOutputPath,
+    resolveAgainstCwd,
+} from './path-utils.mjs';
+
+export function literalPathHint(rawPath) {
+    const s = String(rawPath || '');
+    if (/\$env:[A-Za-z_][A-Za-z0-9_]*|\$[A-Za-z_][A-Za-z0-9_]*|%[^%]+%/.test(s)) {
+        return ' Path fields do not expand shell environment variables; pass the resolved absolute path.';
+    }
+    if (process.platform === 'win32' && /^[A-Za-z]:[^\\/]/.test(s)) {
+        return ' Windows drive-relative paths like C:Project are ambiguous; use C:/Project or C:\\Project.';
+    }
+    return '';
+}
+
+export function resolveOptionalCwd(rawCwd, baseCwd) {
+    if (typeof rawCwd !== 'string' || rawCwd.trim() === '') {
+        return { cwd: baseCwd };
+    }
+    const normalized = normalizeInputPath(rawCwd.trim());
+    const resolved = isAbsolute(normalized) ? resolve(normalized) : resolveAgainstCwd(normalized, baseCwd);
+    try {
+        const st = statSync(resolved);
+        if (!st.isDirectory()) {
+            return { error: `Error: cwd is not a directory: ${normalizeOutputPath(resolved)}.${literalPathHint(rawCwd)}` };
+        }
+        return { cwd: resolved };
+    } catch (err) {
+        return {
+            error: `Error: cwd does not exist: ${normalizeOutputPath(resolved)} (${err?.code || 'ENOENT'}).${literalPathHint(rawCwd)} Pass an absolute repo path or omit cwd to use ${normalizeOutputPath(baseCwd)}.`,
+        };
+    }
+}

package/src/agent/orchestrator/tools/builtin/device-paths.mjs

@@ -0,0 +1,154 @@
+// G6: device path block list (Claude Code parity). Reading these paths
+// would either hang (waiting for stdin / tty) or produce infinite output
+// (/dev/zero, /dev/random). The device block list catches pseudo-files on
+// POSIX hosts that a user-allowed path can still hit.
+const BLOCKED_DEVICE_PATHS = new Set([
+    '/dev/zero', '/dev/random', '/dev/urandom', '/dev/full',
+    '/dev/stdin', '/dev/tty', '/dev/console',
+    '/dev/stdout', '/dev/stderr',
+    '/dev/fd/0', '/dev/fd/1', '/dev/fd/2',
+]);
+
+export function isBlockedDevicePath(p) {
+    if (BLOCKED_DEVICE_PATHS.has(p)) return true;
+    // /proc/self/fd/0-2 and /proc/<pid>/fd/0-2 are Linux aliases for stdio.
+    if (typeof p === 'string' && p.startsWith('/proc/')
+        && (p.endsWith('/fd/0') || p.endsWith('/fd/1') || p.endsWith('/fd/2'))) return true;
+    return false;
+}
+
+// R1: UNC / SMB share paths (\\server\share or //server/share). Reading these
+// causes Windows to auto-authenticate to the remote host, leaking the NTLM
+// hash of the current user to any attacker-controlled SMB target. CC parity:
+// FileReadTool.ts:461 rejects the same prefix before stat. Accepts both
+// backslash and forward-slash leaders so a normalize that picked either form
+// is caught.
+export function isUncPath(p) {
+    if (typeof p !== 'string' || p.length < 2) return false;
+    return (p[0] === '\\' && p[1] === '\\') || (p[0] === '/' && p[1] === '/');
+}
+
+// R2: Windows reserved device basenames (CON, NUL, PRN, AUX, COM0-9, LPT0-9)
+// and raw-device namespace prefixes (\\.\ DosDevices, \\?\ NT namespace).
+// CON/NUL etc. are kernel-level aliases that never resolve to real files
+// when used as bare names; \\.\PhysicalDrive0 / \\.\CON allow raw device
+// access. Basenames with a real extension (nul.bin) are ordinary files.
+const WIN_RESERVED_BASENAMES = new Set([
+    'CON', 'NUL', 'PRN', 'AUX',
+    // CONIN$ / CONOUT$ are the console input/output device aliases; the
+    // trailing '$' is part of the name and survives stem extraction
+    // (cut happens at the first '.'/':' only).
+    'CONIN$', 'CONOUT$',
+    'COM0', 'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
+    'LPT0', 'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',
+    // Win32 normalizes the Latin-1 superscript digits ¹ (U+00B9), ²
+    // (U+00B2), ³ (U+00B3) to 1/2/3 when resolving device names, so
+    // COM¹/COM²/COM³ and LPT¹/LPT²/LPT³ open the real COM1-3/LPT1-3
+    // devices. toUpperCase() leaves these codepoints unchanged, so they
+    // must be listed literally.
+    'COM\u00B9', 'COM\u00B2', 'COM\u00B3',
+    'LPT\u00B9', 'LPT\u00B2', 'LPT\u00B3',
+]);
+export function isWindowsDevicePath(p) {
+    if (typeof p !== 'string' || p.length === 0) return false;
+    // \\.\ and \\?\ raw-device / DOS-device namespace (both slash forms).
+    if (p.startsWith('\\\\.\\') || p.startsWith('\\\\?\\')) return true;
+    if (p.startsWith('//./') || p.startsWith('//?/')) return true;
+    // Reserved basenames (CON/NUL/PRN/AUX/COM*/LPT*) are device aliases ONLY on
+    // Windows; on POSIX a file literally named `con.txt` is a normal regular
+    // file. Gate the basename check to win32 so non-Windows reads of such names
+    // aren't false-rejected (the \\.\ / \\?\ namespace checks above stay
+    // unconditional). reviewer-flagged false positive.
+    if (process.platform !== 'win32') return false;
+    // Basename match, case-insensitive, extension-stripped. R12: splitting
+    // on '.' alone missed NTFS ADS suffixes (NUL:stream, CON:stream) and
+    // trailing Win32-ignored dots/spaces ("CON. ", "NUL. ") that the
+    // kernel still resolves to the reserved device. Compute the stem by
+    // cutting at the FIRST '.' or ':' in the basename, then stripping
+    // any trailing dots/spaces that Win32 silently drops.
+    const lastSep = Math.max(p.lastIndexOf('\\'), p.lastIndexOf('/'));
+    const base = lastSep >= 0 ? p.slice(lastSep + 1) : p;
+    let cut = base.length;
+    for (let i = 0; i < base.length; i += 1) {
+        const ch = base.charCodeAt(i);
+        if (ch === 0x2E /* . */ || ch === 0x3A /* : */) { cut = i; break; }
+    }
+    let stem = base.slice(0, cut);
+    // R14: strip Unicode invisibles (BOM, zero-width joiners, bidi controls)
+    // BEFORE the trailing-dot / reserved-name checks. Win32 GetFinalPathName
+    // and a number of file APIs collapse / ignore these characters when
+    // opening, so "CON\u200B" or "\uFEFFCON" can resolve to the CON device
+    // even though byte-comparison says "not reserved". Drop them defensively.
+    stem = stem.replace(/[\uFEFF\u200B-\u200F\u202A-\u202E\u2066-\u2069]/g, '');
+    // Strip trailing dots / spaces — Win32 ignores them when opening a
+    // file, so "CON. " and "CON " resolve to CON. Loop instead of regex
+    // to keep allocation-free hot path.
+    let end = stem.length;
+    while (end > 0) {
+        const ch = stem.charCodeAt(end - 1);
+        if (ch === 0x2E /* . */ || ch === 0x20 /* SP */) { end -= 1; continue; }
+        break;
+    }
+    stem = stem.slice(0, end).toUpperCase();
+    if (!WIN_RESERVED_BASENAMES.has(stem)) return false;
+    // Bare device alias only (NUL, CON, …). A dotted extension means a normal
+    // file even when the stem matches a reserved name (dir/nul.bin).
+    return cut >= base.length;
+}
+
+// R12: Win32 path-component guard. Rejects any path component that
+// (a) ends in '.' or ' ' — Win32 silently strips trailing dots/spaces
+// when opening, so the kernel resolves a DIFFERENT path than the one
+// the guard sees, bypassing string-based device/UNC checks; or
+// (b) contains ':' after the optional `<drive>:` prefix — colon inside
+// a component names an NTFS Alternate Data Stream (e.g. `file.txt:hidden`),
+// which is a hidden writable channel attached to another file.
+// Legitimate Windows filenames never have trailing dot/space or embedded
+// ':' in any component, so unconditional rejection is safe.
+export function hasUnsafeWin32Component(p) {
+    if (process.platform !== 'win32') return false;
+    if (typeof p !== 'string' || p.length === 0) return false;
+    // Strip optional drive prefix (`C:` / `c:`) so the drive colon is not
+    // mistaken for an ADS marker. \\.\ / \\?\ raw-device prefixes are
+    // already rejected by isWindowsDevicePath; treat their bytes as
+    // ordinary components here so a `\\?\C:\foo:stream` still trips.
+    let rest = p;
+    if (rest.length >= 2 && rest.charCodeAt(1) === 0x3A /* : */
+        && ((rest.charCodeAt(0) >= 0x41 && rest.charCodeAt(0) <= 0x5A)
+            || (rest.charCodeAt(0) >= 0x61 && rest.charCodeAt(0) <= 0x7A))) {
+        rest = rest.slice(2);
+    }
+    // Split on both Win32 separators.
+    const parts = rest.split(/[\\/]+/);
+    for (const rawPart of parts) {
+        if (!rawPart) continue;
+        // R14: strip Unicode invisibles (BOM, zero-width joiners, bidi controls)
+        // BEFORE the trailing-dot / ADS-colon checks. Win32 ignores these
+        // characters in many path-open codepaths, so "foo \u200B" (trailing
+        // space + ZWSP) or "name\uFEFF:stream" must still trip the guard.
+        const part = rawPart.replace(/[\uFEFF\u200B-\u200F\u202A-\u202E\u2066-\u2069]/g, '');
+        if (!part) continue;
+        // `.` and `..` are the standard current/parent-dir components — they end
+        // in '.' but are NOT a trailing-dot bypass, so exempt them (without this
+        // a default relative path like "." or "src/.." is rejected on Windows).
+        // Any other trailing dot/space is still unsafe.
+        if (part === '.' || part === '..') continue;
+        const last = part.charCodeAt(part.length - 1);
+        if (last === 0x2E /* . */ || last === 0x20 /* SP */) return true;
+        if (part.indexOf(':') >= 0) return true;
+    }
+    return false;
+}
+
+// R2: Stat-based special-file reject. FIFOs, character devices, block devices,
+// and sockets pass a normal statSync but reading them either hangs (FIFO with
+// no writer, socket) or produces unbounded output (/dev/zero, /dev/random).
+// Must be called AFTER statSync (or fstatSync) — the string-based device
+// guard catches well-known paths, this catches arbitrary user paths that
+// happen to point at a special inode (custom mknod, symlink targets, etc.).
+export function isSpecialFileStat(st) {
+    if (!st || typeof st !== 'object') return false;
+    try {
+        return st.isFIFO() || st.isCharacterDevice() || st.isBlockDevice() || st.isSocket();
+    } catch { return false; }
+}

package/src/agent/orchestrator/tools/builtin/diagnostics-tool.mjs

@@ -0,0 +1,292 @@
+// Server-less diagnostics tool.
+//
+// Mixdog has no resident LSP server. Instead this tool detects the project
+// marker(s) under the target path, runs the matching project CLI ONCE via the
+// same exec path bash-tool uses (execShellCommand + resolveShell), then PARSES
+// the checker's stdout/stderr into structured findings. No watch, no daemon.
+//
+// Graceful contract: a missing marker or a missing checker binary returns a
+// clear "no checker available for X" message — it never throws.
+import { existsSync, readFileSync, statSync } from 'fs';
+import { dirname, isAbsolute, resolve as pathResolve } from 'path';
+import { execShellCommand, stripAnsi } from '../shell-command.mjs';
+import { resolveShell } from './shell-runtime.mjs';
+
+const DIAGNOSTICS_TIMEOUT_MS = 120_000;
+
+// Probe whether a CLI binary is resolvable on PATH without running real work.
+// Uses the platform command-resolver so an absent checker degrades gracefully
+// into a "no checker available" message instead of a spawn error.
+async function _commandExists(bin, cwd, env) {
+    const { shell, shellArg, shellArgs, shellType } = resolveShell();
+    const probe = shellType === 'powershell'
+        ? `Get-Command ${bin} -ErrorAction SilentlyContinue | Select-Object -First 1`
+        : `command -v ${bin}`;
+    try {
+        const r = await execShellCommand({
+            shell, shellArg, shellArgs, command: probe,
+            env, cwd, timeoutMs: 10_000, abortSignal: null,
+        });
+        const out = `${r.stdout || ''}`.trim();
+        if (shellType === 'powershell') return out.length > 0;
+        return r.exitCode === 0 && out.length > 0;
+    } catch {
+        return false;
+    }
+}
+
+async function _runChecker(command, cwd, env) {
+    const { shell, shellArg, shellArgs } = resolveShell();
+    const r = await execShellCommand({
+        shell, shellArg, shellArgs, command,
+        env, cwd, timeoutMs: DIAGNOSTICS_TIMEOUT_MS, abortSignal: null,
+    });
+    return {
+        stdout: stripAnsi(r.stdout || ''),
+        stderr: stripAnsi(r.stderr || ''),
+        exitCode: r.timedOut ? null : r.exitCode,
+        timedOut: !!r.timedOut,
+    };
+}
+
+// ---- per-checker output parsers -> [{file,line,col,severity,code,message}] ----
+
+function _parseTsc(text) {
+    const findings = [];
+    const re = /^(.+?)\((\d+),(\d+)\):\s+(error|warning)\s+(TS\d+):\s+(.*)$/;
+    for (const line of text.split(/\r?\n/)) {
+        const m = re.exec(line.trim());
+        if (m) findings.push({ file: m[1], line: +m[2], col: +m[3], severity: m[4], code: m[5], message: m[6] });
+    }
+    return findings;
+}
+
+function _parseRuff(text) {
+    const findings = [];
+    // ruff default text: path:line:col: CODE message
+    const re = /^(.+?):(\d+):(\d+):\s+([A-Z]+\d+)\s+(.*)$/;
+    for (const line of text.split(/\r?\n/)) {
+        const m = re.exec(line.trim());
+        if (!m) continue;
+        const code = m[4];
+        const severity = (/^(E9|F)/.test(code)) ? 'error' : 'warning';
+        findings.push({ file: m[1], line: +m[2], col: +m[3], severity, code, message: m[5] });
+    }
+    return findings;
+}
+
+function _parsePyflakes(text) {
+    const findings = [];
+    // pyflakes: path:line: message  (no column)
+    const re = /^(.+?):(\d+):\s*(.*)$/;
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        const m = re.exec(trimmed);
+        if (m) findings.push({ file: m[1], line: +m[2], col: null, severity: 'warning', code: null, message: m[3] });
+    }
+    return findings;
+}
+
+function _parseGoVet(text) {
+    const findings = [];
+    // go vet: path:line:col: message   OR   path:line: message
+    const re = /^(.+?\.go):(\d+):(?:(\d+):)?\s+(.*)$/;
+    for (const line of text.split(/\r?\n/)) {
+        const m = re.exec(line.trim());
+        if (m) findings.push({ file: m[1], line: +m[2], col: m[3] ? +m[3] : null, severity: 'error', code: 'vet', message: m[4] });
+    }
+    return findings;
+}
+
+function _parseCargo(text) {
+    const findings = [];
+    // cargo check --message-format=short: path:line:col: severity[CODE]: message
+    const re = /^(.+?):(\d+):(\d+):\s+(warning|error)(?:\[([A-Za-z0-9]+)\])?:\s+(.*)$/;
+    for (const line of text.split(/\r?\n/)) {
+        const m = re.exec(line.trim());
+        if (m) findings.push({ file: m[1], line: +m[2], col: +m[3], severity: m[4], code: m[5] || null, message: m[6] });
+    }
+    return findings;
+}
+
+// node --check failure shape: "<abs file>:<line>" on its own line, followed
+// by the offending source + caret, then "SyntaxError: <message>".
+function _parseNodeCheck(text) {
+    const findings = [];
+    const head = /^(.+?):(\d+)\s*$/m.exec(text);
+    const err = /^([A-Za-z]*Error):\s+(.*)$/m.exec(text);
+    if (head && err) {
+        findings.push({ file: head[1], line: +head[2], col: null, severity: 'error', code: err[1], message: err[2] });
+    }
+    return findings;
+}
+
+function _parseEslintCompact(text) {
+    const findings = [];
+    // eslint --format compact: path: line N, col M, Severity - message (rule)
+    const re = /^(.+?):\s+line\s+(\d+),\s+col\s+(\d+),\s+(Error|Warning)\s+-\s+(.*?)(?:\s+\(([^)]+)\))?$/;
+    for (const line of text.split(/\r?\n/)) {
+        const m = re.exec(line.trim());
+        if (m) findings.push({ file: m[1], line: +m[2], col: +m[3], severity: m[4].toLowerCase(), code: m[6] || null, message: m[5] });
+    }
+    return findings;
+}
+
+// Detect the project marker under projectDir and return the checker plan.
+// Order is deterministic; the first matching marker wins.
+function _detectChecker(projectDir) {
+    const has = (f) => existsSync(pathResolve(projectDir, f));
+    if (has('tsconfig.json')) {
+        return { kind: 'tsc', bin: 'tsc', command: 'tsc --noEmit', parse: _parseTsc, marker: 'tsconfig.json' };
+    }
+    if (has('pyproject.toml') || has('setup.py')) {
+        return { kind: 'python', marker: has('pyproject.toml') ? 'pyproject.toml' : 'setup.py' };
+    }
+    if (has('go.mod')) {
+        return { kind: 'go', bin: 'go', command: 'go vet ./...', parse: _parseGoVet, marker: 'go.mod' };
+    }
+    if (has('Cargo.toml')) {
+        return { kind: 'cargo', bin: 'cargo', command: 'cargo check --message-format=short', parse: _parseCargo, marker: 'Cargo.toml' };
+    }
+    if (has('package.json')) {
+        let usesEslint = false;
+        try {
+            const pkg = JSON.parse(readFileSync(pathResolve(projectDir, 'package.json'), 'utf8'));
+            const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+            usesEslint = Object.prototype.hasOwnProperty.call(deps, 'eslint');
+        } catch { /* unreadable/invalid package.json */ }
+        const hasEslintConfig = ['.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json', '.eslintrc.yml', '.eslintrc.yaml', 'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs']
+            .some((f) => has(f));
+        if (usesEslint || hasEslintConfig) {
+            return { kind: 'eslint', bin: 'eslint', command: 'eslint . --format compact', parse: _parseEslintCompact, marker: 'package.json (eslint)' };
+        }
+        return { kind: 'none', reason: 'package.json present but no eslint dependency/config detected' };
+    }
+    return { kind: 'none', reason: 'no recognized project marker (tsconfig.json / pyproject.toml / setup.py / go.mod / Cargo.toml / package.json)' };
+}
+
+function _formatResult({ marker, checker, findings, raw, note }) {
+    return JSON.stringify({
+        ok: true,
+        marker: marker || null,
+        checker: checker || null,
+        note: note || null,
+        count: findings.length,
+        findings,
+        raw: raw ? raw.slice(0, 4000) : undefined,
+    }, null, 2);
+}
+
+export async function executeDiagnosticsTool(args, workDir, options = {}) {
+    const result = await _executeDiagnosticsImpl(args, workDir);
+    // ② completion progress (claude "Found N" parity). Best-effort, no-op
+    // when onProgress is absent (no progressToken). Never throws — the tool
+    // result is returned regardless.
+    if (typeof options?.onProgress === 'function') {
+        try {
+            let _n = null;
+            try { _n = JSON.parse(result)?.count; } catch { /* non-JSON envelope */ }
+            if (Number.isFinite(_n)) {
+                options.onProgress(_n === 0 ? 'no issues' : `${_n} issue${_n === 1 ? '' : 's'}`);
+            }
+        } catch { /* best-effort */ }
+    }
+    return result;
+}
+
+async function _executeDiagnosticsImpl(args, workDir) {
+    try {
+        // Resolve the target path (file or dir). Default: cwd.
+        const rawPath = (args && typeof args.path === 'string' && args.path.trim()) ? args.path.trim() : '';
+        const absTarget = rawPath
+            ? (isAbsolute(rawPath) ? rawPath : pathResolve(workDir, rawPath))
+            : workDir;
+        if (rawPath && !existsSync(absTarget)) {
+            return _formatResult({ note: `path not found: ${rawPath}`, findings: [] });
+        }
+        let projectDir = absTarget;
+        try {
+            if (statSync(absTarget).isFile()) projectDir = dirname(absTarget);
+        } catch { /* fall through with absTarget */ }
+
+        let plan = _detectChecker(projectDir);
+        // A file deep in the tree (src/search/lib/foo.mjs) has its project
+        // marker at the repo ROOT — walk parent directories until a marker is
+        // found instead of reporting "no recognized project marker" from the
+        // file's immediate dirname. Stops at the first directory that yields
+        // any non-"no marker" answer (including "package.json present but no
+        // eslint"), or at the filesystem root.
+        {
+            const _noMarker = (p) => p.kind === 'none' && String(p.reason || '').startsWith('no recognized project marker');
+            let walk = projectDir;
+            while (_noMarker(plan)) {
+                const parent = dirname(walk);
+                if (!parent || parent === walk) break;
+                walk = parent;
+                plan = _detectChecker(walk);
+            }
+            if (!_noMarker(plan)) projectDir = walk;
+        }
+        if (plan.kind === 'none') {
+            // Syntax-check fallback: a JS file target can still be validated
+            // with `node --check` even when the project has no lint setup —
+            // catch the dominant failure class (parse errors) instead of
+            // going dark with "no checker".
+            let isJsFile = false;
+            try { isJsFile = /\.(mjs|cjs|js)$/i.test(absTarget) && statSync(absTarget).isFile(); } catch { /* keep false */ }
+            if (isJsFile) {
+                const env = { ...process.env, LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' };
+                if (await _commandExists('node', projectDir, env)) {
+                    const r = await _runChecker(`node --check "${absTarget}"`, projectDir, env);
+                    const combined = `${r.stdout}\n${r.stderr}`;
+                    const findings = _parseNodeCheck(combined);
+                    return _formatResult({ checker: 'node --check (no-lint fallback)', findings, raw: combined, note: `${plan.reason} — fell back to syntax check only` });
+                }
+            }
+            return _formatResult({ note: `no checker available for this path — ${plan.reason}`, findings: [] });
+        }
+
+        const env = { ...process.env, LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8' };
+
+        // Python is special: prefer ruff, fall back to pyflakes.
+        if (plan.kind === 'python') {
+            if (await _commandExists('ruff', projectDir, env)) {
+                const r = await _runChecker('ruff check .', projectDir, env);
+                const findings = _parseRuff(`${r.stdout}\n${r.stderr}`);
+                return _formatResult({ marker: plan.marker, checker: 'ruff check', findings, raw: `${r.stdout}\n${r.stderr}` });
+            }
+            if (await _commandExists('python', projectDir, env)) {
+                const r = await _runChecker('python -m pyflakes .', projectDir, env);
+                const out = `${r.stdout}\n${r.stderr}`;
+                if (/No module named pyflakes/i.test(out)) {
+                    return _formatResult({ marker: plan.marker, note: 'no checker available for Python — ruff absent and pyflakes module not installed', findings: [] });
+                }
+                const findings = _parsePyflakes(out);
+                return _formatResult({ marker: plan.marker, checker: 'python -m pyflakes (ruff fallback)', findings, raw: out });
+            }
+            return _formatResult({ marker: plan.marker, note: 'no checker available for Python — neither ruff nor python found on PATH', findings: [] });
+        }
+
+        if (!(await _commandExists(plan.bin, projectDir, env))) {
+            return _formatResult({ marker: plan.marker, note: `no checker available for ${plan.kind} — "${plan.bin}" not found on PATH`, findings: [] });
+        }
+        const r = await _runChecker(plan.command, projectDir, env);
+        const combined = `${r.stdout}\n${r.stderr}`;
+        const findings = plan.parse(combined);
+        const note = r.timedOut ? `checker timed out after ${DIAGNOSTICS_TIMEOUT_MS}ms` : null;
+        return _formatResult({ marker: plan.marker, checker: plan.command, findings, raw: combined, note });
+    } catch (err) {
+        // Never throw — surface a graceful diagnostic envelope.
+        return JSON.stringify({ ok: false, error: `diagnostics failed: ${err && err.message ? err.message : String(err)}`, findings: [] }, null, 2);
+    }
+}
+
+function _isDir(p, workDir) {
+    try {
+        const abs = isAbsolute(p) ? p : pathResolve(workDir, p);
+        return statSync(abs).isDirectory();
+    } catch { return false; }
+}
+
+export default executeDiagnosticsTool;

package/src/agent/orchestrator/tools/builtin/diff-utils.mjs

@@ -0,0 +1,109 @@
+// Self-contained unified diff so the plugin does not need to take on an
+// external `diff` npm dep. LCS dynamic-programming table is O(n*m) memory
+// and time for normal tool-sized inputs; very large inputs fall back to a
+// compact "files differ" summary.
+export function computeUnifiedDiff(a, b, ctx, fromLabel, toLabel) {
+    const n = a.length;
+    const m = b.length;
+    if (n > 10000 || m > 10000 || n * m > 4_000_000) {
+        if (n === m) {
+            let same = true;
+            for (let k = 0; k < n; k++) {
+                if (a[k] !== b[k]) { same = false; break; }
+            }
+            if (same) return '';
+        }
+        return `--- ${fromLabel}\n+++ ${toLabel}\n(files too large for inline diff — ${n} vs ${m} lines)`;
+    }
+
+    const dp = Array.from({ length: n + 1 }, () => new Int32Array(m + 1));
+    for (let i = n - 1; i >= 0; i--) {
+        const aI = a[i];
+        const rowI = dp[i];
+        const rowI1 = dp[i + 1];
+        for (let j = m - 1; j >= 0; j--) {
+            if (aI === b[j]) rowI[j] = rowI1[j + 1] + 1;
+            else rowI[j] = rowI1[j] >= rowI[j + 1] ? rowI1[j] : rowI[j + 1];
+        }
+    }
+
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) { ops.push(['=', a[i]]); i++; j++; }
+        else if (dp[i + 1][j] >= dp[i][j + 1]) { ops.push(['-', a[i]]); i++; }
+        else { ops.push(['+', b[j]]); j++; }
+    }
+    while (i < n) ops.push(['-', a[i++]]);
+    while (j < m) ops.push(['+', b[j++]]);
+
+    if (!ops.some((op) => op[0] !== '=')) return '';
+
+    const hunks = [];
+    let aLine = 1;
+    let bLine = 1;
+    let current = null;
+    let eqRun = 0;
+    const openHunk = (aStart, bStart) => ({ aStart, bStart, aCount: 0, bCount: 0, lines: [] });
+
+    for (let k = 0; k < ops.length; k++) {
+        const [op, line] = ops[k];
+        if (op === '=') {
+            if (current) {
+                let nextChangeWithin = false;
+                for (let la = 1; la <= ctx && k + la < ops.length; la++) {
+                    if (ops[k + la][0] !== '=') { nextChangeWithin = true; break; }
+                }
+                if (nextChangeWithin || eqRun < ctx) {
+                    current.lines.push([' ', line]);
+                    current.aCount++;
+                    current.bCount++;
+                    eqRun++;
+                } else {
+                    hunks.push(current);
+                    current = null;
+                    eqRun = 0;
+                }
+            }
+            aLine++;
+            bLine++;
+        } else {
+            if (!current) {
+                const leading = [];
+                let leadA = 0;
+                let leadB = 0;
+                for (let back = k - 1; back >= 0 && leading.length < ctx; back--) {
+                    if (ops[back][0] !== '=') break;
+                    leading.unshift([' ', ops[back][1]]);
+                    leadA++;
+                    leadB++;
+                }
+                current = openHunk(aLine - leadA, bLine - leadB);
+                current.lines.push(...leading);
+                current.aCount += leadA;
+                current.bCount += leadB;
+            }
+            if (op === '-') {
+                current.lines.push(['-', line]);
+                current.aCount++;
+                aLine++;
+            } else {
+                current.lines.push(['+', line]);
+                current.bCount++;
+                bLine++;
+            }
+            eqRun = 0;
+        }
+    }
+    if (current) hunks.push(current);
+
+    const out = [`--- ${fromLabel}`, `+++ ${toLabel}`];
+    for (const h of hunks) {
+        const aHdr = h.aCount === 0 ? `${h.aStart - 1},0` : (h.aCount === 1 ? `${h.aStart}` : `${h.aStart},${h.aCount}`);
+        const bHdr = h.bCount === 0 ? `${h.bStart - 1},0` : (h.bCount === 1 ? `${h.bStart}` : `${h.bStart},${h.bCount}`);
+        out.push(`@@ -${aHdr} +${bHdr} @@`);
+        for (const [sign, line] of h.lines) out.push(`${sign}${line}`);
+    }
+    return out.join('\n');
+}

package/src/agent/orchestrator/tools/builtin/edit-base-guard.mjs

@@ -0,0 +1,58 @@
+import { readFileSync, statSync } from 'fs';
+import { hashText } from './hash-utils.mjs';
+import { statMatchesSnapshot } from './snapshot-helpers.mjs';
+import { normalizeErrorMessage } from './path-diagnostics.mjs';
+import { getPathMutationGeneration } from './cache-layers.mjs';
+
+// Change detection: a full stat match (size + mtime±1 + ctime±1) is
+// proof the file is untouched since the preflight snapshot — accept
+// without re-reading the body (fast-path). Only when stat drifts do we
+// fall back to the authoritative content-hash compare. Tradeoff
+// (accepted policy, parity with write's isSnapshotStale): a size-
+// preserving write that ALSO restores mtime AND ctime is not caught —
+// vanishingly rare, since ctime is not userland-settable on the usual
+// platforms.
+export function validatePreparedEditBase(prepared) {
+    if (!prepared || !prepared.fullPath) return 'Error [code 7]: edit prewrite check failed — missing prepared file path';
+    // In-process CAS, checked before the stat fast-path below. Every committed
+    // write bumps the target's mutation generation (bumpPathMutationGeneration,
+    // reached via invalidateBuiltinResultCache after each atomic/byte write).
+    // If the generation captured at preflight no longer matches, a concurrent
+    // in-process edit committed between this edit's snapshot and now. This
+    // signal is deterministic and independent of mtime/size granularity — it
+    // closes the window where the stat fast-path (size + mtime±1 + ctime±1)
+    // false-negatives on a same-size write that lands within the mtime
+    // tolerance (e.g. two concurrent cross-file batches racing the same
+    // targets), which would otherwise wave drift through. Only enforced when a
+    // generation was captured (Number.isFinite) so callers that omit it keep
+    // their prior behavior; sequential edits capture and commit without an
+    // intervening write, so the generation is stable and never false-positives.
+    if (Number.isFinite(prepared.baseMutationGeneration)
+        && getPathMutationGeneration(prepared.fullPath) !== prepared.baseMutationGeneration) {
+        return `Error [code 7]: file modified between edit preflight and write — read it again before editing: ${prepared.filePath}`;
+    }
+    let currentStat;
+    try { currentStat = statSync(prepared.fullPath); }
+    catch (err) {
+        return `Error [code 7]: file changed before edit write — read it again before editing: ${prepared.filePath} (${normalizeErrorMessage(err instanceof Error ? err.message : String(err))})`;
+    }
+    // Fast-path: clean stat match ⇒ untouched, accept without reading.
+    // statMatchesSnapshot returns false when baseStatSnapshot is missing
+    // or incomplete, so an incomplete snapshot falls through to the
+    // fail-closed / content-hash path below (no fail-open).
+    if (statMatchesSnapshot(currentStat, prepared.baseStatSnapshot)) return null;
+    // Stat drifted (or no stat material) → content hash is authoritative.
+    // Without baseContentHash we cannot prove identity, so fail closed.
+    if (!prepared.baseContentHash) {
+        return `Error [code 7]: file modified between edit preflight and write — read it again before editing: ${prepared.filePath}`;
+    }
+    let current;
+    try { current = readFileSync(prepared.fullPath); }
+    catch (err) {
+        return `Error [code 7]: file changed before edit write — read it again before editing: ${prepared.filePath} (${normalizeErrorMessage(err instanceof Error ? err.message : String(err))})`;
+    }
+    if (hashText(current) !== prepared.baseContentHash) {
+        return `Error [code 7]: file modified between edit preflight and write — read it again before editing: ${prepared.filePath}`;
+    }
+    return null;
+}