@visorcraft/idlehands 0.9.1

package/dist/tools.js

@@ -0,0 +1,1114 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn, spawnSync } from 'node:child_process';
+import { checkExecSafety, checkPathSafety, isProtectedDeleteTarget } from './safety.js';
+import { sys_context as sysContextTool } from './sys/context.js';
+import { stateDir, shellEscape, BASH_PATH } from './utils.js';
+const DEFAULT_MAX_BACKUPS_PER_FILE = 5;
+const DEFAULT_MAX_EXEC_BYTES = 16384;
+let ptyUnavailableWarned = false;
+async function loadNodePty() {
+    try {
+        const mod = await import('node-pty');
+        return mod;
+    }
+    catch {
+        if (!ptyUnavailableWarned) {
+            ptyUnavailableWarned = true;
+            console.error('[warn] node-pty not available; interactive sudo is disabled. Install build tools (python3, make, g++) and reinstall to enable it.');
+        }
+        return null;
+    }
+}
+/** Best-effort MIME type guess from magic bytes + extension (§7/§8). */
+function guessMimeType(filePath, buf) {
+    // Magic byte signatures
+    if (buf.length >= 4) {
+        if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47)
+            return 'image/png';
+        if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
+            return 'image/jpeg';
+        if (buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46)
+            return 'image/gif';
+        if (buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 && buf.length >= 12 && buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50)
+            return 'image/webp'; // RIFF+WEBP
+        if (buf[0] === 0x25 && buf[1] === 0x50 && buf[2] === 0x44 && buf[3] === 0x46)
+            return 'application/pdf';
+        if (buf[0] === 0x50 && buf[1] === 0x4b && buf[2] === 0x03 && buf[3] === 0x04)
+            return 'application/zip';
+        if (buf[0] === 0x7f && buf[1] === 0x45 && buf[2] === 0x4c && buf[3] === 0x46)
+            return 'application/x-elf';
+        if (buf[0] === 0x1f && buf[1] === 0x8b)
+            return 'application/gzip';
+    }
+    // Fall back to extension
+    const ext = path.extname(filePath).toLowerCase();
+    const extMap = {
+        '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+        '.webp': 'image/webp', '.svg': 'image/svg+xml', '.pdf': 'application/pdf',
+        '.zip': 'application/zip', '.gz': 'application/gzip', '.tar': 'application/x-tar',
+        '.wasm': 'application/wasm', '.so': 'application/x-sharedlib',
+        '.exe': 'application/x-executable', '.o': 'application/x-object',
+    };
+    return extMap[ext] ?? 'application/octet-stream';
+}
+function defaultBackupDir() {
+    return path.join(stateDir(), 'backups');
+}
+function sha256(s) {
+    return crypto.createHash('sha256').update(s).digest('hex');
+}
+function keyFromPath(absPath) {
+    return sha256(absPath);
+}
+function backupDirForPath(ctx, absPath) {
+    const bdir = ctx.backupDir ?? defaultBackupDir();
+    const key = keyFromPath(absPath);
+    return { bdir, key, keyDir: path.join(bdir, key) };
+}
+function formatBackupTs() {
+    return new Date().toISOString().replace(/[:.]/g, '-');
+}
+async function restoreLatestBackup(absPath, ctx) {
+    const { key, keyDir } = backupDirForPath(ctx, absPath);
+    const legacyDir = ctx.backupDir ?? defaultBackupDir();
+    const latestInDir = async (dir) => {
+        const ents = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        return ents
+            .filter((e) => e.isFile())
+            .map((e) => e.name)
+            .filter((n) => n.endsWith('.bak'))
+            .sort()
+            .reverse()[0];
+    };
+    let bakDir = keyDir;
+    let bakFile = await latestInDir(keyDir);
+    if (!bakFile) {
+        // Compatibility with older flat backup format (without nested key dir).
+        const ents = await fs.readdir(legacyDir, { withFileTypes: true }).catch(() => []);
+        const legacy = ents
+            .filter((e) => e.isFile())
+            .map((e) => e.name)
+            .filter((n) => n.startsWith(`${key}.`) && !n.endsWith('.json'))
+            .sort()
+            .reverse()[0];
+        if (legacy) {
+            bakFile = legacy;
+            bakDir = legacyDir;
+        }
+    }
+    if (!bakFile) {
+        throw new Error(`undo: no backups found for ${absPath} in ${legacyDir}`);
+    }
+    const bakPath = path.join(bakDir, bakFile);
+    const buf = await fs.readFile(bakPath);
+    // backup current file before restoring
+    await backupFile(absPath, ctx);
+    await atomicWrite(absPath, buf);
+    return `restored ${absPath} from backup ${bakPath}`;
+}
+function stripAnsi(s) {
+    // eslint-disable-next-line no-control-regex
+    return s
+        .replace(/\u001b\[[0-9;]*[A-Za-z]/g, '') // CSI sequences (SGR, cursor, erase, scroll, etc.)
+        .replace(/\u001b\][^\u0007]*\u0007/g, '') // OSC sequences
+        .replace(/\u001b[()][AB012]/g, '') // Character set selection
+        .replace(/\u001b[=>Nc7-9]/g, ''); // Other common single-char escapes
+}
+function dedupeRepeats(lines, maxLineLen = 400) {
+    const out = [];
+    let prev = null;
+    let count = 0;
+    const flush = () => {
+        if (prev == null)
+            return;
+        if (count <= 1)
+            out.push(prev);
+        else
+            out.push(prev, `[repeated ${count - 1} more times]`);
+    };
+    for (const raw of lines) {
+        const line = raw.length > maxLineLen ? raw.slice(0, maxLineLen) + '…' : raw;
+        if (prev === line) {
+            count++;
+            continue;
+        }
+        flush();
+        prev = line;
+        count = 1;
+    }
+    flush();
+    return out;
+}
+function collapseStackTraces(lines) {
+    const out = [];
+    let inStack = false;
+    let stackCount = 0;
+    let firstFrame = '';
+    let lastError = '';
+    const isStackFrame = (l) => /^\s+at\s/.test(l);
+    const flush = () => {
+        if (!inStack)
+            return;
+        if (firstFrame)
+            out.push(firstFrame);
+        if (stackCount > 1)
+            out.push(`    [${stackCount - 1} more frames]`);
+        if (lastError)
+            out.push(lastError);
+        inStack = false;
+        stackCount = 0;
+        firstFrame = '';
+        lastError = '';
+    };
+    for (const line of lines) {
+        if (isStackFrame(line)) {
+            if (!inStack) {
+                inStack = true;
+                stackCount = 1;
+                firstFrame = line;
+            }
+            else {
+                stackCount++;
+            }
+        }
+        else {
+            if (inStack) {
+                // Lines between stack frames that look like error messages
+                if (/^\w*(Error|Exception|Caused by)/.test(line.trim())) {
+                    lastError = line;
+                    continue;
+                }
+                flush();
+            }
+            out.push(line);
+        }
+    }
+    flush();
+    return out;
+}
+function truncateBytes(s, maxBytes, totalBytesHint) {
+    const b = Buffer.from(s, 'utf8');
+    const total = typeof totalBytesHint === 'number' && Number.isFinite(totalBytesHint) ? totalBytesHint : b.length;
+    if (b.length <= maxBytes)
+        return { text: s, truncated: false };
+    // cut to boundary
+    const cut = b.subarray(0, maxBytes);
+    return { text: cut.toString('utf8') + `\n[truncated, ${total} bytes total]`, truncated: true };
+}
+async function rotateBackups(absPath, ctx) {
+    const { keyDir } = backupDirForPath(ctx, absPath);
+    const limit = ctx.maxBackupsPerFile ?? DEFAULT_MAX_BACKUPS_PER_FILE;
+    if (limit <= 0)
+        return;
+    await fs.mkdir(keyDir, { recursive: true });
+    const ents = await fs.readdir(keyDir, { withFileTypes: true }).catch(() => []);
+    const backups = ents
+        .filter((e) => e.isFile())
+        .map((e) => e.name)
+        .filter((n) => n.endsWith('.bak'))
+        .sort(); // oldest → newest due to ISO timestamp
+    const toDelete = backups.length > limit ? backups.slice(0, backups.length - limit) : [];
+    for (const name of toDelete) {
+        const bak = path.join(keyDir, name);
+        const meta = path.join(keyDir, `${name.replace(/\.bak$/, '')}.meta.json`);
+        await fs.rm(bak, { force: true }).catch(() => { });
+        await fs.rm(meta, { force: true }).catch(() => { });
+    }
+}
+async function backupFile(absPath, ctx) {
+    const { bdir, keyDir } = backupDirForPath(ctx, absPath);
+    await fs.mkdir(bdir, { recursive: true });
+    await fs.mkdir(keyDir, { recursive: true });
+    // Auto-create .gitignore in state dir to prevent backups from being committed
+    const gitignorePath = path.join(bdir, '.gitignore');
+    await fs.writeFile(gitignorePath, '*\n', { flag: 'wx' }).catch(() => { });
+    // 'wx' flag = create only if doesn't exist, silently skip if it does
+    const st = await fs.stat(absPath).catch(() => null);
+    if (!st || !st.isFile())
+        return;
+    const content = await fs.readFile(absPath);
+    const hash = crypto.createHash('sha256').update(content).digest('hex');
+    const ts = formatBackupTs();
+    const bakName = `${ts}.bak`;
+    const metaName = `${ts}.meta.json`;
+    const bakPath = path.join(keyDir, bakName);
+    const metaPath = path.join(keyDir, metaName);
+    await fs.writeFile(bakPath, content);
+    await fs.writeFile(metaPath, JSON.stringify({ original_path: absPath, timestamp: ts, size: st.size, sha256_before: hash }, null, 2) + '\n', 'utf8');
+    await rotateBackups(absPath, ctx);
+}
+async function checkpointReplay(ctx, payload) {
+    if (!ctx.replay)
+        return '';
+    let note;
+    if (ctx.lens && payload.before && payload.after) {
+        try {
+            note = await ctx.lens.summarizeDiffToText(payload.before.toString('utf8'), payload.after.toString('utf8'), payload.filePath);
+        }
+        catch {
+            // ignore and fallback to raw checkpoint
+        }
+    }
+    try {
+        await ctx.replay.checkpoint({ ...payload, note });
+        return '';
+    }
+    catch (e) {
+        return ` replay_skipped: ${e?.message ?? String(e)}`;
+    }
+}
+export async function atomicWrite(absPath, data) {
+    const dir = path.dirname(absPath);
+    await fs.mkdir(dir, { recursive: true });
+    // Capture original permissions before overwriting
+    const origStat = await fs.stat(absPath).catch(() => null);
+    const origMode = origStat?.mode;
+    const tmp = path.join(dir, `.${path.basename(absPath)}.idlehands.tmp.${process.pid}.${Date.now()}`);
+    await fs.writeFile(tmp, data);
+    // Restore original file mode bits if the file existed
+    if (origMode != null) {
+        await fs.chmod(tmp, origMode & 0o7777).catch(() => { });
+    }
+    await fs.rename(tmp, absPath);
+}
+export async function undo_path(ctx, args) {
+    const directPath = args?.path === undefined ? undefined : String(args.path);
+    const p = directPath ? resolvePath(ctx, directPath) : ctx.lastEditedPath;
+    if (!p)
+        throw new Error('undo: missing path');
+    if (!ctx.noConfirm && ctx.confirm) {
+        const ok = await ctx.confirm(`Restore latest backup for:\n  ${p}\nThis will overwrite the current file. Proceed? (y/N) `);
+        if (!ok)
+            return 'undo: cancelled';
+    }
+    if (!ctx.noConfirm && !ctx.confirm) {
+        throw new Error('undo: confirmation required (run with --no-confirm/--yolo or in interactive mode)');
+    }
+    if (ctx.dryRun)
+        return `dry-run: would restore latest backup for ${p}`;
+    return await restoreLatestBackup(p, ctx);
+}
+export async function read_file(ctx, args) {
+    const p = resolvePath(ctx, args?.path);
+    const offset = args?.offset ? Number(args.offset) : undefined;
+    const limit = Math.max(10, Math.min(args?.limit ? Number(args.limit) : 100, 500));
+    const search = typeof args?.search === 'string' ? args.search : undefined;
+    const context = args?.context ? Number(args.context) : 10;
+    const maxBytes = 100 * 1024;
+    if (!p)
+        throw new Error('read_file: missing path');
+    // Detect directories early with a helpful message instead of cryptic EISDIR
+    try {
+        const stat = await fs.stat(p);
+        if (stat.isDirectory()) {
+            return `read_file: "${p}" is a directory, not a file. Use list_dir to see its contents, or search_files to find specific code.`;
+        }
+    }
+    catch (e) {
+        // stat failure (ENOENT etc.) — let readFile handle it for the standard error path
+    }
+    const buf = await fs.readFile(p).catch((e) => {
+        throw new Error(`read_file: cannot read ${p}: ${e?.message ?? String(e)}`);
+    });
+    if (buf.length > maxBytes) {
+        // Truncate gracefully instead of throwing
+        const truncText = buf.subarray(0, maxBytes).toString('utf8');
+        const truncLines = truncText.split(/\r?\n/);
+        const numbered = truncLines.map((l, i) => `${String(i + 1).padStart(4)}| ${l}`).join('\n');
+        return `# ${p} [TRUNCATED: ${buf.length} bytes, showing first ${maxBytes}]\n${numbered}`;
+    }
+    // Binary detection: NUL byte in first 512 bytes (§8)
+    for (let i = 0; i < Math.min(buf.length, 512); i++) {
+        if (buf[i] === 0) {
+            const mimeGuess = guessMimeType(p, buf);
+            return `[binary file, ${buf.length} bytes, detected type: ${mimeGuess}]`;
+        }
+    }
+    const text = buf.toString('utf8');
+    const lines = text.split(/\r?\n/);
+    let start = 1;
+    let end = Math.min(lines.length, limit);
+    if (search) {
+        const matchLines = [];
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].includes(search))
+                matchLines.push(i + 1);
+        }
+        if (!matchLines.length) {
+            return `# ${p}\n# search not found: ${JSON.stringify(search)}\n# file has ${lines.length} lines`;
+        }
+        const firstIdx = matchLines[0];
+        start = Math.max(1, firstIdx - context);
+        end = Math.min(lines.length, firstIdx + context);
+        const out = [];
+        out.push(`# ${p}`);
+        out.push(`# matches at lines: ${matchLines.join(', ')}${matchLines.length > 20 ? ' [truncated]' : ''}`);
+        for (let ln = start; ln <= end; ln++) {
+            out.push(`${String(ln).padStart(6, ' ')}| ${lines[ln - 1] ?? ''}`);
+        }
+        if (end < lines.length)
+            out.push(`# ... (${lines.length - end} more lines)`);
+        return out.join('\n');
+    }
+    else if (offset && offset >= 1) {
+        start = offset;
+        end = Math.min(lines.length, offset + limit - 1);
+    }
+    // Lens projection: only for large files (200+ lines) without search/offset.
+    // Small files should return full content — the agent needs exact text for edits,
+    // and a structural skeleton for a 15-line file just wastes a tool call.
+    if (!search && !offset && lines.length >= 200) {
+        try {
+            const lensSummary = await ctx.lens?.projectFile(p, text);
+            if (lensSummary)
+                return lensSummary;
+        }
+        catch (e) {
+            // Lens parse failure should not block read_file.
+            console.warn(`[warn] lens unavailable for ${p}: ${e?.message ?? 'failed'}`);
+        }
+    }
+    const out = [];
+    out.push(`# ${p}`);
+    for (let ln = start; ln <= end; ln++) {
+        out.push(`${String(ln).padStart(6, ' ')}| ${lines[ln - 1] ?? ''}`);
+    }
+    if (end < lines.length)
+        out.push(`# ... (${lines.length - end} more lines)`);
+    return out.join('\n');
+}
+export async function read_files(ctx, args) {
+    const reqs = Array.isArray(args?.requests) ? args.requests : [];
+    if (!reqs.length)
+        throw new Error('read_files: missing requests[]');
+    const parts = [];
+    for (const r of reqs) {
+        parts.push(await read_file(ctx, r));
+        parts.push('');
+    }
+    return parts.join('\n');
+}
+export async function write_file(ctx, args) {
+    const p = resolvePath(ctx, args?.path);
+    // Content may arrive as a string (normal) or as a parsed JSON object
+    // (when llama-server's XML parser auto-parses JSON content values).
+    const raw = args?.content;
+    const content = typeof raw === 'string' ? raw
+        : (raw != null && typeof raw === 'object' ? JSON.stringify(raw, null, 2) : undefined);
+    if (!p)
+        throw new Error('write_file: missing path');
+    if (content == null)
+        throw new Error('write_file: missing content (got ' + typeof raw + ')');
+    // Out-of-cwd enforcement: block creating NEW files outside cwd, warn on editing existing ones.
+    const cwdWarning = checkCwdWarning('write_file', p, ctx);
+    if (cwdWarning) {
+        // Check if the file already exists — only allow editing existing files outside cwd
+        const exists = await fs.stat(p).then(() => true, () => false);
+        if (!exists) {
+            throw new Error(`write_file: BLOCKED — cannot create new file "${p}" outside the working directory "${path.resolve(ctx.cwd)}". Use relative paths to create files within your project.`);
+        }
+    }
+    // Path safety check (Phase 9)
+    const pathVerdict = checkPathSafety(p);
+    if (pathVerdict.tier === 'forbidden') {
+        throw new Error(`write_file: ${pathVerdict.reason}`);
+    }
+    if (pathVerdict.tier === 'cautious' && !ctx.noConfirm) {
+        if (ctx.confirm) {
+            const ok = await ctx.confirm(pathVerdict.prompt || `Write to ${p}?`, { tool: 'write_file', args: { path: p } });
+            if (!ok)
+                throw new Error(`write_file: cancelled by user (${pathVerdict.reason})`);
+        }
+        else {
+            throw new Error(`write_file: blocked (${pathVerdict.reason}) without --no-confirm/--yolo`);
+        }
+    }
+    if (ctx.dryRun)
+        return `dry-run: would write ${p} (${Buffer.byteLength(content, 'utf8')} bytes)${cwdWarning}`;
+    // Phase 9d: snapshot /etc/ files before editing
+    if (ctx.mode === 'sys' && ctx.vault) {
+        await snapshotBeforeEdit(ctx.vault, p).catch(() => { });
+    }
+    const beforeBuf = await fs.readFile(p).catch(() => Buffer.from(''));
+    await backupFile(p, ctx);
+    await atomicWrite(p, content);
+    ctx.onMutation?.(p);
+    const afterBuf = Buffer.from(content, 'utf8');
+    const replayNote = await checkpointReplay(ctx, { op: 'write_file', filePath: p, before: beforeBuf, after: afterBuf });
+    return `wrote ${p} (${Buffer.byteLength(content, 'utf8')} bytes)${replayNote}${cwdWarning}`;
+}
+export async function insert_file(ctx, args) {
+    const p = resolvePath(ctx, args?.path);
+    const line = Number(args?.line);
+    const rawText = args?.text;
+    const text = typeof rawText === 'string' ? rawText
+        : (rawText != null && typeof rawText === 'object' ? JSON.stringify(rawText, null, 2) : undefined);
+    if (!p)
+        throw new Error('insert_file: missing path');
+    if (!Number.isFinite(line))
+        throw new Error('insert_file: missing/invalid line');
+    if (text == null)
+        throw new Error('insert_file: missing text (got ' + typeof rawText + ')');
+    // Path safety check (Phase 9)
+    const pathVerdict = checkPathSafety(p);
+    if (pathVerdict.tier === 'forbidden') {
+        throw new Error(`insert_file: ${pathVerdict.reason}`);
+    }
+    if (pathVerdict.tier === 'cautious' && !ctx.noConfirm) {
+        if (ctx.confirm) {
+            const ok = await ctx.confirm(pathVerdict.prompt || `Insert into ${p}?`, { tool: 'insert_file', args: { path: p } });
+            if (!ok)
+                throw new Error(`insert_file: cancelled by user (${pathVerdict.reason})`);
+        }
+        else {
+            throw new Error(`insert_file: blocked (${pathVerdict.reason}) without --no-confirm/--yolo`);
+        }
+    }
+    if (ctx.dryRun)
+        return `dry-run: would insert into ${p} at line=${line} (${Buffer.byteLength(text, 'utf8')} bytes)`;
+    // Phase 9d: snapshot /etc/ files before editing
+    if (ctx.mode === 'sys' && ctx.vault) {
+        await snapshotBeforeEdit(ctx.vault, p).catch(() => { });
+    }
+    const beforeText = await fs.readFile(p, 'utf8').catch(() => '');
+    // Detect original newline style
+    const eol = beforeText.includes('\r\n') ? '\r\n' : '\n';
+    // Handle empty file: just write the inserted text directly (avoid spurious leading newline).
+    if (beforeText === '') {
+        const out = text;
+        await backupFile(p, ctx);
+        await atomicWrite(p, out);
+        ctx.onMutation?.(p);
+        const replayNote = await checkpointReplay(ctx, {
+            op: 'insert_file',
+            filePath: p,
+            before: Buffer.from(beforeText, 'utf8'),
+            after: Buffer.from(out, 'utf8')
+        });
+        const cwdWarning = checkCwdWarning('insert_file', p, ctx);
+        return `inserted into ${p} at 0${replayNote}${cwdWarning}`;
+    }
+    const lines = beforeText.split(/\r?\n/);
+    let idx;
+    if (line === -1)
+        idx = lines.length;
+    else
+        idx = Math.max(0, Math.min(lines.length, line));
+    // When appending to a file that ends with a newline, the split produces a
+    // trailing empty element (e.g. "a\n" → ["a",""]). Inserting at lines.length
+    // pushes content AFTER that empty element, producing a double-newline on rejoin.
+    // Fix: when appending (line === -1) and the last element is empty (trailing newline),
+    // insert before the trailing empty element instead.
+    if (line === -1 && lines.length > 0 && lines[lines.length - 1] === '') {
+        idx = lines.length - 1;
+    }
+    const insertLines = text.split(/\r?\n/);
+    lines.splice(idx, 0, ...insertLines);
+    const out = lines.join(eol);
+    await backupFile(p, ctx);
+    await atomicWrite(p, out);
+    ctx.onMutation?.(p);
+    const replayNote = await checkpointReplay(ctx, {
+        op: 'insert_file',
+        filePath: p,
+        before: Buffer.from(beforeText, 'utf8'),
+        after: Buffer.from(out, 'utf8')
+    });
+    const cwdWarning = checkCwdWarning('insert_file', p, ctx);
+    return `inserted into ${p} at ${idx}${replayNote}${cwdWarning}`;
+}
+export async function edit_file(ctx, args) {
+    const p = resolvePath(ctx, args?.path);
+    const rawOld = args?.old_text;
+    const oldText = typeof rawOld === 'string' ? rawOld
+        : (rawOld != null && typeof rawOld === 'object' ? JSON.stringify(rawOld, null, 2) : undefined);
+    const rawNew = args?.new_text;
+    const newText = typeof rawNew === 'string' ? rawNew
+        : (rawNew != null && typeof rawNew === 'object' ? JSON.stringify(rawNew, null, 2) : undefined);
+    const replaceAll = Boolean(args?.replace_all);
+    if (!p)
+        throw new Error('edit_file: missing path');
+    if (oldText == null)
+        throw new Error('edit_file: missing old_text');
+    if (newText == null)
+        throw new Error('edit_file: missing new_text');
+    // Path safety check (Phase 9)
+    const pathVerdict = checkPathSafety(p);
+    if (pathVerdict.tier === 'forbidden') {
+        throw new Error(`edit_file: ${pathVerdict.reason}`);
+    }
+    if (pathVerdict.tier === 'cautious' && !ctx.noConfirm) {
+        if (ctx.confirm) {
+            const ok = await ctx.confirm(pathVerdict.prompt || `Edit ${p}?`, { tool: 'edit_file', args: { path: p, old_text: oldText, new_text: newText } });
+            if (!ok)
+                throw new Error(`edit_file: cancelled by user (${pathVerdict.reason})`);
+        }
+        else {
+            throw new Error(`edit_file: blocked (${pathVerdict.reason}) without --no-confirm/--yolo`);
+        }
+    }
+    // Phase 9d: snapshot /etc/ files before editing
+    if (ctx.mode === 'sys' && ctx.vault) {
+        await snapshotBeforeEdit(ctx.vault, p).catch(() => { });
+    }
+    const cur = await fs.readFile(p, 'utf8').catch((e) => {
+        throw new Error(`edit_file: cannot read ${p}: ${e?.message ?? String(e)}`);
+    });
+    const idx = cur.indexOf(oldText);
+    if (idx === -1) {
+        // Find closest near-match via normalized comparison
+        const normalize = (s) => s.replace(/\s+/g, ' ').trim().toLowerCase();
+        const needle = normalize(oldText);
+        const curLines = cur.split(/\r?\n/);
+        const needleLines = oldText.split(/\r?\n/).length;
+        let bestScore = 0;
+        let bestLine = -1;
+        let bestText = '';
+        for (let i = 0; i < curLines.length; i++) {
+            // Build a window of the same number of lines as old_text
+            const windowEnd = Math.min(curLines.length, i + needleLines);
+            const window = curLines.slice(i, windowEnd).join('\n');
+            const normWindow = normalize(window);
+            // Similarity: count matching character bigrams (handles differences anywhere, not just prefix).
+            const score = bigramSimilarity(needle, normWindow);
+            if (score > bestScore) {
+                bestScore = score;
+                bestLine = i + 1;
+                bestText = window;
+            }
+        }
+        let hint = '';
+        if (bestScore > 0.3 && bestLine > 0) {
+            const preview = bestText.length > 600 ? bestText.slice(0, 600) + '…' : bestText;
+            hint = `\nClosest match at line ${bestLine} (${Math.round(bestScore * 100)}% similarity):\n${preview}`;
+        }
+        else if (!cur.trim()) {
+            hint = `\nFile is empty.`;
+        }
+        else {
+            hint = `\nFile head (first 400 chars):\n${cur.slice(0, 400)}`;
+        }
+        throw new Error(`edit_file: old_text not found in ${p}. Re-read the file and retry with exact text.${hint}`);
+    }
+    const next = replaceAll ? cur.split(oldText).join(newText) : cur.slice(0, idx) + newText + cur.slice(idx + oldText.length);
+    if (ctx.dryRun)
+        return `dry-run: would edit ${p} (replace_all=${replaceAll})`;
+    await backupFile(p, ctx);
+    await atomicWrite(p, next);
+    ctx.onMutation?.(p);
+    const replayNote = await checkpointReplay(ctx, {
+        op: 'edit_file',
+        filePath: p,
+        before: Buffer.from(cur, 'utf8'),
+        after: Buffer.from(next, 'utf8')
+    });
+    const cwdWarning = checkCwdWarning('edit_file', p, ctx);
+    return `edited ${p} (replace_all=${replaceAll})${replayNote}${cwdWarning}`;
+}
+export async function list_dir(ctx, args) {
+    const p = resolvePath(ctx, args?.path ?? '.');
+    const recursive = Boolean(args?.recursive);
+    const maxEntries = Math.min(args?.max_entries ? Number(args.max_entries) : 200, 500);
+    if (!p)
+        throw new Error('list_dir: missing path');
+    const lines = [];
+    let count = 0;
+    async function walk(dir, depth) {
+        if (count >= maxEntries)
+            return;
+        const ents = await fs.readdir(dir, { withFileTypes: true }).catch((e) => {
+            throw new Error(`list_dir: cannot read ${dir}: ${e?.message ?? String(e)}`);
+        });
+        for (const ent of ents) {
+            if (count >= maxEntries)
+                return;
+            const full = path.join(dir, ent.name);
+            const st = await fs.lstat(full).catch(() => null);
+            const kind = ent.isDirectory() ? 'dir' : ent.isSymbolicLink() ? 'link' : 'file';
+            lines.push(`${kind}\t${st?.size ?? 0}\t${full}`);
+            count++;
+            if (recursive && ent.isDirectory() && depth < 3) {
+                await walk(full, depth + 1);
+            }
+        }
+    }
+    await walk(p, 0);
+    if (count >= maxEntries)
+        lines.push(`[truncated after ${maxEntries} entries]`);
+    return lines.join('\n');
+}
+export async function search_files(ctx, args) {
+    const root = resolvePath(ctx, args?.path ?? '.');
+    const pattern = typeof args?.pattern === 'string' ? args.pattern : undefined;
+    const include = typeof args?.include === 'string' ? args.include : undefined;
+    const maxResults = Math.min(args?.max_results ? Number(args.max_results) : 50, 100);
+    if (!root)
+        throw new Error('search_files: missing path');
+    if (!pattern)
+        throw new Error('search_files: missing pattern');
+    // Prefer rg if available (fast, bounded output)
+    if (await hasRg()) {
+        const cmd = ['rg', '-n', '--no-heading', '--color', 'never', pattern, root];
+        if (include)
+            cmd.splice(1, 0, '-g', include);
+        try {
+            const rawJson = await exec(ctx, { command: cmd.map(shellEscape).join(' '), timeout: 30 });
+            const parsed = JSON.parse(rawJson);
+            // rg exits 1 when no matches found (not an error), 2+ for real errors.
+            if (parsed.rc === 1 && !parsed.out?.trim()) {
+                return `No matches for pattern "${pattern}" in ${root}. STOP — do NOT read files individually to search. Try a broader regex pattern, different keywords, or use exec: grep -rn "keyword" ${root}`;
+            }
+            if (parsed.rc >= 2) {
+                // Real rg error — fall through to regex fallback below
+            }
+            else {
+                const rgOutput = parsed.out ?? '';
+                if (rgOutput) {
+                    const lines = rgOutput.split(/\r?\n/).filter(Boolean).slice(0, maxResults);
+                    if (lines.length >= maxResults)
+                        lines.push(`[truncated after ${maxResults} results]`);
+                    return lines.join('\n');
+                }
+            }
+        }
+        catch {
+            // JSON parse failed or exec error — fall through to regex fallback
+        }
+    }
+    // Slow fallback
+    const re = new RegExp(pattern);
+    const out = [];
+    async function walk(dir, depth) {
+        if (out.length >= maxResults)
+            return;
+        const ents = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const ent of ents) {
+            if (out.length >= maxResults)
+                return;
+            const full = path.join(dir, ent.name);
+            if (ent.isDirectory()) {
+                if (ent.name === 'node_modules' || ent.name === '.git' || ent.name === 'dist' || ent.name === 'build')
+                    continue;
+                if (depth < 6)
+                    await walk(full, depth + 1);
+                continue;
+            }
+            if (!ent.isFile())
+                continue;
+            if (include && !globishMatch(ent.name, include))
+                continue;
+            // Skip binary files (NUL byte in first 512 bytes)
+            const rawBuf = await fs.readFile(full).catch(() => null);
+            if (!rawBuf)
+                continue;
+            let isBinary = false;
+            for (let bi = 0; bi < Math.min(rawBuf.length, 512); bi++) {
+                if (rawBuf[bi] === 0) {
+                    isBinary = true;
+                    break;
+                }
+            }
+            if (isBinary)
+                continue;
+            const buf = rawBuf.toString('utf8');
+            const lines = buf.split(/\r?\n/);
+            for (let i = 0; i < lines.length; i++) {
+                if (re.test(lines[i])) {
+                    out.push(`${full}:${i + 1}:${lines[i]}`);
+                    if (out.length >= maxResults)
+                        return;
+                }
+            }
+        }
+    }
+    await walk(root, 0);
+    if (out.length >= maxResults)
+        out.push(`[truncated after ${maxResults} results]`);
+    const result = out.join('\n');
+    if (!result)
+        return `No matches for pattern "${pattern}" in ${root}. STOP — do NOT read files individually to search. Try a broader regex pattern, different keywords, or use exec: grep -rn "keyword" ${root}`;
+    return result;
+}
+export async function exec(ctx, args) {
+    const command = typeof args?.command === 'string' ? args.command : undefined;
+    const cwd = args?.cwd ? resolvePath(ctx, args.cwd) : ctx.cwd;
+    const defaultTimeout = ctx.mode === 'sys' ? 60 : 30;
+    const timeout = Math.min(args?.timeout ? Number(args.timeout) : defaultTimeout, 120);
+    if (!command)
+        throw new Error('exec: missing command');
+    // Out-of-cwd enforcement: block exec cwd or `cd` navigating outside the project.
+    const absCwd = path.resolve(ctx.cwd);
+    let execCwdWarning = '';
+    if (args?.cwd) {
+        const absExecCwd = path.resolve(cwd);
+        if (!absExecCwd.startsWith(absCwd + path.sep) && absExecCwd !== absCwd) {
+            throw new Error(`exec: BLOCKED — cwd "${absExecCwd}" is outside the working directory "${absCwd}". Use relative paths and work within the project directory.`);
+        }
+    }
+    if (command) {
+        // Detect `cd /absolute/path` anywhere in the command
+        const cdPattern = /\bcd\s+(['"]?)(\/[^\s'";&|]+)\1/g;
+        let cdMatch;
+        while ((cdMatch = cdPattern.exec(command)) !== null) {
+            const cdTarget = path.resolve(cdMatch[2]);
+            if (!cdTarget.startsWith(absCwd + path.sep) && cdTarget !== absCwd) {
+                throw new Error(`exec: BLOCKED — command navigates to "${cdTarget}" which is outside the working directory "${absCwd}". Use relative paths and work within the project directory.`);
+            }
+        }
+        // Detect absolute paths in file-creating commands (mkdir, cat >, tee, touch, etc.)
+        // that target directories outside cwd — HARD BLOCK
+        const absPathPattern = /(?:mkdir|cat\s*>|tee|touch|cp|mv)\s+(?:-\S+\s+)*(['"]?)(\/[^\s'";&|]+)\1/g;
+        let apMatch;
+        while ((apMatch = absPathPattern.exec(command)) !== null) {
+            const absTarget = path.resolve(apMatch[2]);
+            if (!absTarget.startsWith(absCwd + path.sep) && absTarget !== absCwd) {
+                throw new Error(`exec: BLOCKED — command targets "${absTarget}" which is outside the working directory "${absCwd}". Use relative paths to work within the project directory.`);
+            }
+        }
+    }
+    // ── Safety tier check (Phase 9) ──
+    const verdict = checkExecSafety(command);
+    // Forbidden: ALWAYS blocked, even in yolo/noConfirm mode. No override.
+    if (verdict.tier === 'forbidden') {
+        throw new Error(`exec: ${verdict.reason} — command: ${command}`);
+    }
+    // Extra protection: block rm targeting protected root directories
+    if (isProtectedDeleteTarget(command)) {
+        throw new Error(`exec: BLOCKED: rm targeting protected directory — command: ${command}`);
+    }
+    // Cautious: require confirmation unless yolo/noConfirm
+    if (verdict.tier === 'cautious' && !ctx.noConfirm) {
+        if (ctx.confirm) {
+            const ok = await ctx.confirm(verdict.prompt || `About to run:\n\n${command}\n\nProceed? (y/N) `, { tool: 'exec', args: { command } });
+            if (!ok) {
+                throw new Error(`exec: cancelled by user (${verdict.reason}): ${command}`);
+            }
+        }
+        else {
+            throw new Error(`exec: blocked (${verdict.reason}) without --no-confirm/--yolo: ${command}`);
+        }
+    }
+    if (ctx.dryRun)
+        return `dry-run: would exec in ${cwd}: ${command}`;
+    // ── Sudo handling (Phase 9c) ──
+    // Non-TTY: probe for NOPASSWD / cached credentials before running.
+    if (/^\s*sudo\s/.test(command) && !process.stdin.isTTY) {
+        try {
+            const probe = spawnSync('sudo', ['-n', 'true'], { timeout: 5000, stdio: 'ignore' });
+            if (probe.status !== 0) {
+                throw new Error('exec: sudo requires a TTY for password input, but stdin is not a TTY. ' +
+                    'Options: run idlehands interactively, configure NOPASSWD for this command, or pre-cache sudo credentials.');
+            }
+        }
+        catch (e) {
+            if (e.message?.includes('sudo requires a TTY'))
+                throw e;
+            // spawnSync error (sudo not found, etc.) — let the actual command fail naturally
+        }
+    }
+    const maxBytes = ctx.maxExecBytes ?? DEFAULT_MAX_EXEC_BYTES;
+    const captureLimit = ctx.maxExecCaptureBytes ?? Math.max(maxBytes * 64, 256 * 1024);
+    // TTY interactive sudo path (Phase 9c): use node-pty when available.
+    if (/^\s*sudo\s/.test(command) && process.stdin.isTTY) {
+        const pty = await loadNodePty();
+        if (!pty) {
+            throw new Error('exec: interactive sudo requires node-pty, but it is not installed. Install optional dependency `node-pty` (build tools: python3, make, g++) or use non-interactive sudo (NOPASSWD/cached credentials).');
+        }
+        return await execWithPty({
+            pty,
+            command,
+            cwd,
+            timeout,
+            maxBytes,
+            captureLimit,
+            signal: ctx.signal,
+        }) + execCwdWarning;
+    }
+    // Use spawn with shell:true — lets Node.js resolve the shell internally,
+    // avoiding ENOENT issues with explicit bash paths in certain environments.
+    const child = spawn(command, [], {
+        cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        shell: BASH_PATH,
+    });
+    const outChunks = [];
+    const errChunks = [];
+    let outSeen = 0;
+    let errSeen = 0;
+    let outCaptured = 0;
+    let errCaptured = 0;
+    let killed = false;
+    const killTimer = setTimeout(() => {
+        killed = true;
+        child.kill('SIGKILL');
+    }, Math.max(1, timeout) * 1000);
+    // §11: kill child process if parent abort signal fires (Ctrl+C).
+    const onAbort = () => { killed = true; child.kill('SIGKILL'); };
+    ctx.signal?.addEventListener('abort', onAbort, { once: true });
+    const pushCapped = (chunks, buf, kind) => {
+        const n = buf.length;
+        if (kind === 'out')
+            outSeen += n;
+        else
+            errSeen += n;
+        const captured = kind === 'out' ? outCaptured : errCaptured;
+        const remaining = captureLimit - captured;
+        if (remaining <= 0)
+            return;
+        const take = n <= remaining ? buf : buf.subarray(0, remaining);
+        chunks.push(Buffer.from(take));
+        if (kind === 'out')
+            outCaptured += take.length;
+        else
+            errCaptured += take.length;
+    };
+    child.stdout.on('data', (d) => pushCapped(outChunks, d, 'out'));
+    child.stderr.on('data', (d) => pushCapped(errChunks, d, 'err'));
+    const rc = await new Promise((resolve, reject) => {
+        child.on('error', (err) => {
+            clearTimeout(killTimer);
+            ctx.signal?.removeEventListener('abort', onAbort);
+            reject(new Error(`exec: failed to spawn shell: ${err.message} (${err.code ?? 'unknown'})`));
+        });
+        child.on('close', (code) => resolve(code ?? 0));
+    });
+    clearTimeout(killTimer);
+    ctx.signal?.removeEventListener('abort', onAbort);
+    const outRaw = stripAnsi(Buffer.concat(outChunks).toString('utf8'));
+    const errRaw = stripAnsi(Buffer.concat(errChunks).toString('utf8'));
+    const outLines = collapseStackTraces(dedupeRepeats(outRaw.split(/\r?\n/))).join('\n').trimEnd();
+    const errLines = collapseStackTraces(dedupeRepeats(errRaw.split(/\r?\n/))).join('\n').trimEnd();
+    const outT = truncateBytes(outLines, maxBytes, outSeen);
+    const errT = truncateBytes(errLines, maxBytes, errSeen);
+    let outText = outT.text;
+    let errText = errT.text;
+    const capOut = outSeen > outCaptured;
+    const capErr = errSeen > errCaptured;
+    // If we had to cap capture but the post-processed output ended up short
+    // (e.g., massive repeated output collapsed), still surface that truncation.
+    if (capOut && !outT.truncated) {
+        outText = truncateBytes(outText + `\n[capture truncated, ${outSeen} bytes total]`, maxBytes, outSeen).text;
+    }
+    if (capErr && !errT.truncated) {
+        errText = truncateBytes(errText + `\n[capture truncated, ${errSeen} bytes total]`, maxBytes, errSeen).text;
+    }
+    if (killed) {
+        errText = (errText ? errText + '\n' : '') + `[killed after ${timeout}s timeout]`;
+    }
+    const result = { rc, out: outText, err: errText, truncated: outT.truncated || errT.truncated || capOut || capErr };
+    // Phase 9d: auto-note system changes in sys mode
+    if (ctx.mode === 'sys' && ctx.vault && rc === 0) {
+        autoNoteSysChange(ctx.vault, command, outText).catch(() => { });
+    }
+    return JSON.stringify(result) + execCwdWarning;
+}
+async function execWithPty(args) {
+    const { pty, command, cwd, timeout, maxBytes, captureLimit, signal } = args;
+    const proc = pty.spawn(BASH_PATH, ['-lc', command], {
+        name: 'xterm-color',
+        cwd,
+        cols: 120,
+        rows: 30,
+        env: process.env,
+    });
+    const chunks = [];
+    let seen = 0;
+    let captured = 0;
+    let killed = false;
+    const onDataDisposable = proc.onData((data) => {
+        // Real-time stream for interactive UX
+        if (process.stdout.isTTY) {
+            process.stdout.write(data);
+        }
+        const n = Buffer.byteLength(data, 'utf8');
+        seen += n;
+        const remaining = captureLimit - captured;
+        if (remaining <= 0)
+            return;
+        if (n <= remaining) {
+            chunks.push(data);
+            captured += n;
+        }
+        else {
+            const buf = Buffer.from(data, 'utf8');
+            const slice = buf.subarray(0, remaining).toString('utf8');
+            chunks.push(slice);
+            captured += Buffer.byteLength(slice, 'utf8');
+        }
+    });
+    const kill = () => {
+        killed = true;
+        try {
+            proc.kill();
+        }
+        catch {
+            // ignore
+        }
+    };
+    const killTimer = setTimeout(kill, Math.max(1, timeout) * 1000);
+    const onAbort = () => kill();
+    signal?.addEventListener('abort', onAbort, { once: true });
+    const rc = await new Promise((resolve) => {
+        proc.onExit((e) => resolve(Number(e?.exitCode ?? 0)));
+    });
+    clearTimeout(killTimer);
+    signal?.removeEventListener('abort', onAbort);
+    onDataDisposable?.dispose?.();
+    const raw = stripAnsi(chunks.join(''));
+    const lines = collapseStackTraces(dedupeRepeats(raw.split(/\r?\n/))).join('\n').trimEnd();
+    const outT = truncateBytes(lines, maxBytes, seen);
+    let outText = outT.text;
+    const cap = seen > captured;
+    if (cap && !outT.truncated) {
+        outText = truncateBytes(outText + `\n[capture truncated, ${seen} bytes total]`, maxBytes, seen).text;
+    }
+    let errText = '';
+    if (killed) {
+        errText = `[killed after ${timeout}s timeout]`;
+    }
+    const result = {
+        rc,
+        out: outText,
+        err: errText,
+        truncated: outT.truncated || cap || killed,
+    };
+    return JSON.stringify(result);
+}
+export async function vault_note(ctx, args) {
+    const key = typeof args?.key === 'string' ? args.key.trim() : '';
+    const value = typeof args?.value === 'string' ? args.value : undefined;
+    if (!key)
+        throw new Error('vault_note: missing key');
+    if (value == null)
+        throw new Error('vault_note: missing value');
+    if (ctx.dryRun)
+        return `dry-run: would add vault note ${JSON.stringify(key)}`;
+    if (!ctx.vault) {
+        throw new Error('vault_note: vault disabled');
+    }
+    const id = await ctx.vault.note(key, String(value));
+    return `vault_note: saved ${id}`;
+}
+export async function vault_search(ctx, args) {
+    const query = typeof args?.query === 'string' ? args.query.trim() : '';
+    const limit = Number(args?.limit);
+    if (!query)
+        return 'vault_search: missing query';
+    const n = Number.isFinite(limit) && limit > 0 ? Math.min(50, Math.max(1, Math.floor(limit))) : 8;
+    if (!ctx.vault)
+        return 'vault disabled';
+    const results = await ctx.vault.search(query, n);
+    if (!results.length) {
+        return `vault_search: no results for ${JSON.stringify(query)}`;
+    }
+    const lines = results.map((r) => {
+        const title = r.kind === 'note' ? `note:${r.key}` : `tool:${r.tool || r.key || 'unknown'}`;
+        const body = r.value ?? r.snippet ?? r.content ?? '';
+        const short = body.replace(/\s+/g, ' ').slice(0, 160);
+        return `${r.updatedAt} ${title} ${JSON.stringify(short)}`;
+    });
+    return lines.join('\n');
+}
+/** Phase 9: sys_context tool (mode-gated in agent schema). */
+export async function sys_context(ctx, args) {
+    return sysContextTool(ctx, args);
+}
+function resolvePath(ctx, p) {
+    if (typeof p !== 'string' || !p.trim())
+        throw new Error('missing path');
+    return path.resolve(ctx.cwd, p);
+}
+/**
+ * Check if a resolved path is outside the working directory.
+ * Returns a model-visible warning string if so, empty string otherwise.
+ */
+function checkCwdWarning(tool, resolvedPath, ctx) {
+    const absCwd = path.resolve(ctx.cwd);
+    if (resolvedPath.startsWith(absCwd + path.sep) || resolvedPath === absCwd)
+        return '';
+    const warning = `\n[WARNING] Path "${resolvedPath}" is OUTSIDE the working directory "${absCwd}". You MUST use relative paths and work within the project directory. Do NOT create or edit files outside the cwd.`;
+    console.warn(`[warning] ${tool}: path "${resolvedPath}" is outside the working directory "${absCwd}".`);
+    return warning;
+}
+async function hasRg() {
+    try {
+        await fs.access('/usr/bin/rg');
+        return true;
+    }
+    catch {
+        // try PATH
+        return await new Promise((resolve) => {
+            const c = spawn(BASH_PATH, ['-lc', 'command -v rg >/dev/null 2>&1'], { stdio: 'ignore' });
+            c.on('error', () => resolve(false));
+            c.on('close', (code) => resolve(code === 0));
+        });
+    }
+}
+/** Sørensen-Dice coefficient on character bigrams. Returns 0–1. */
+function bigramSimilarity(a, b) {
+    if (a.length < 2 && b.length < 2)
+        return a === b ? 1 : 0;
+    const bigrams = (s) => {
+        const m = new Map();
+        for (let i = 0; i < s.length - 1; i++) {
+            const bi = s.slice(i, i + 2);
+            m.set(bi, (m.get(bi) ?? 0) + 1);
+        }
+        return m;
+    };
+    const aB = bigrams(a);
+    const bB = bigrams(b);
+    let overlap = 0;
+    for (const [k, v] of aB) {
+        overlap += Math.min(v, bB.get(k) ?? 0);
+    }
+    const total = (a.length - 1) + (b.length - 1);
+    return total > 0 ? (2 * overlap) / total : 0;
+}
+function globishMatch(name, glob) {
+    // supports only simple '*.ext' and exact matches
+    if (glob === name)
+        return true;
+    const m = /^\*\.(.+)$/.exec(glob);
+    if (m)
+        return name.endsWith('.' + m[1]);
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Phase 9d: System memory helpers
+// ---------------------------------------------------------------------------
+/** Patterns that indicate system-modifying commands worth auto-noting. */
+const SYS_CHANGE_PATTERNS = [
+    /\b(apt|apt-get|dnf|yum|pacman|pip|npm)\s+(install|remove|purge|upgrade|update)\b/i,
+    /\bsystemctl\s+(start|stop|restart|enable|disable)\b/i,
+    /\bufw\s+(allow|deny|delete|enable|disable)\b/i,
+    /\biptables\s+(-A|-I|-D)\b/i,
+    /\buseradd\b/i,
+    /\buserdel\b/i,
+    /\bcrontab\b/i,
+];
+/** Auto-note significant system changes to Vault (sys mode only). */
+async function autoNoteSysChange(vault, command, output) {
+    const isSignificant = SYS_CHANGE_PATTERNS.some(p => p.test(command));
+    if (!isSignificant)
+        return;
+    const summary = output.length > 200 ? output.slice(0, 197) + '...' : output;
+    const value = `Command: ${command}\nOutput: ${summary}`;
+    await vault.note(`sys:${command.slice(0, 80)}`, value);
+}
+/** Snapshot a file's contents to Vault before editing (for /etc/ config tracking). */
+export async function snapshotBeforeEdit(vault, filePath) {
+    if (!filePath.startsWith('/etc/'))
+        return;
+    try {
+        const content = await fs.readFile(filePath, 'utf8');
+        const snippet = content.length > 500 ? content.slice(0, 497) + '...' : content;
+        await vault.note(`sys:pre-edit:${filePath}`, `Snapshot before edit:\n${snippet}`);
+    }
+    catch {
+        // File doesn't exist yet or not readable — skip
+    }
+}
+//# sourceMappingURL=tools.js.map