memtrace-skills 1.2.9 → 1.2.11

package/dist/managed-skills.d.ts

@@ -0,0 +1,4 @@
+export declare const RECEIPT_SUFFIX = ".memtrace-managed.sha256";
+export declare function skillDigest(content: string): string;
+export declare function writeManagedSkill(rootDir: string, name: string, content: string, steering?: boolean): boolean;
+export declare function removeManagedSkills(rootDir: string, steering?: boolean): void;

package/dist/managed-skills.js

@@ -0,0 +1,95 @@
+import fs from 'fs';
+import path from 'path';
+import { createHash } from 'crypto';
+import { fileURLToPath } from 'url';
+// A name is not ownership. Receipts bind the exact last-installed bytes; the
+// stock catalogue admits upgrades from installers that predate receipts.
+const stockFile = fileURLToPath(new URL('../skills/managed-stock-sha256.txt', import.meta.url));
+const stock = new Set(fs.readFileSync(stockFile, 'utf8').split(/\r?\n/).filter(line => !line.startsWith('#')));
+export const RECEIPT_SUFFIX = '.memtrace-managed.sha256';
+export function skillDigest(content) {
+    return createHash('sha256').update(content.replace(/\r\n/g, '\n')).digest('hex');
+}
+function safeFile(rootDir, relative) {
+    const parts = relative.split(/[\\/]/);
+    if (parts.some(part => !part || part === '.' || part === '..'))
+        return;
+    let current = path.resolve(rootDir);
+    if (fs.existsSync(current) && (!fs.lstatSync(current).isDirectory() || fs.lstatSync(current).isSymbolicLink()))
+        return;
+    for (const part of parts) {
+        current = path.join(current, part);
+        try {
+            const stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink() || (!stat.isDirectory() && current !== path.resolve(rootDir, relative)))
+                return;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    try {
+        const receipt = fs.lstatSync(current + RECEIPT_SUFFIX);
+        if (!receipt.isFile() || receipt.isSymbolicLink())
+            return;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return current;
+}
+function owned(file, name, content) {
+    const digest = skillDigest(content);
+    if (stock.has(`${name} ${digest}`))
+        return true;
+    try {
+        return fs.readFileSync(file + RECEIPT_SUFFIX, 'utf8').trim() === digest;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return false;
+    }
+}
+export function writeManagedSkill(rootDir, name, content, steering = false) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(name))
+        throw new Error(`Invalid managed skill name: ${name}`);
+    const file = safeFile(rootDir, steering ? `${name}.md` : `${name}/SKILL.md`);
+    if (!file)
+        return false;
+    if (fs.existsSync(file)) {
+        if (!fs.lstatSync(file).isFile())
+            return false;
+        const prior = fs.readFileSync(file, 'utf8');
+        if (prior !== content && !owned(file, name, prior)) {
+            console.warn(`memtrace: preserved customized skill ${file}`);
+            return false;
+        }
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content);
+    fs.writeFileSync(file + RECEIPT_SUFFIX, `${skillDigest(content)}\n`);
+    return true;
+}
+export function removeManagedSkills(rootDir, steering = false) {
+    if (!fs.existsSync(rootDir) || fs.lstatSync(rootDir).isSymbolicLink())
+        return;
+    for (const entry of fs.readdirSync(rootDir)) {
+        const name = steering ? entry.replace(/\.md$/, '') : entry;
+        if (!/^memtrace-[a-z0-9-]+$/.test(name) || (steering && !entry.endsWith('.md')))
+            continue;
+        const file = safeFile(rootDir, steering ? entry : `${entry}/SKILL.md`);
+        if (!file || !fs.existsSync(file) || !fs.lstatSync(file).isFile())
+            continue;
+        if (!owned(file, name, fs.readFileSync(file, 'utf8')))
+            continue;
+        fs.unlinkSync(file);
+        if (fs.existsSync(file + RECEIPT_SUFFIX))
+            fs.unlinkSync(file + RECEIPT_SUFFIX);
+        // Never recursively delete a skill folder: user references/assets survive.
+        if (!steering && fs.readdirSync(path.dirname(file)).length === 0)
+            fs.rmdirSync(path.dirname(file));
+    }
+}

package/dist/rail-hook.d.ts

@@ -1 +1,7 @@
-export {};
+/**
+ * Post-phase gate, before any lease read or network call (design 4.1): only a
+ * native Grep, or a shell command that runs a search program and did not
+ * fail, is worth one loopback POST. Glob, Read and every other shell command
+ * exit here.
+ */
+export declare function enrichEligible(payload: any): boolean;

package/dist/rail-hook.js

@@ -1,77 +1,187 @@
 /** Cached host hooks stop here when Memtrace is absent. No output and no network. */
 import { spawn } from 'node:child_process';
+import fs from 'node:fs';
 import http from 'node:http';
-import { railIsActive, runtimeForCwd, pidAlive } from './rail-runtime.js';
-async function main() {
-    if (process.env.MEMTRACE_RAIL?.trim().toLowerCase() === 'off'
-        || process.env.MEMTRACE_RAW_SEARCH?.trim().toLowerCase() === 'allow'
-        || !railIsActive())
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { activeRailRuntimes, enrichEnabled, pidAlive, runtimeForCwd, ENRICH_HOOK_KILL_MS, SEARCH_COMMAND_RE, } from './rail-runtime.js';
+const argv = process.argv;
+function arg(name) {
+    const index = argv.indexOf(name);
+    return index >= 0 ? argv[index + 1] : undefined;
+}
+function off(value) {
+    return value?.trim().toLowerCase() === 'off';
+}
+const SEARCH_TOOLS = new Set(['grep', 'search_file_content', 'grep_search']);
+const SHELL_TOOLS = new Set(['bash', 'powershell', 'shell', 'run_shell_command', 'run_terminal_cmd', 'execute_command', 'run_in_terminal']);
+/**
+ * Post-phase gate, before any lease read or network call (design 4.1): only a
+ * native Grep, or a shell command that runs a search program and did not
+ * fail, is worth one loopback POST. Glob, Read and every other shell command
+ * exit here.
+ */
+export function enrichEligible(payload) {
+    if (!payload || typeof payload !== 'object')
+        return false;
+    const tool = String(payload.tool_name ?? '').toLowerCase();
+    const input = payload.tool_input ?? {};
+    if (SEARCH_TOOLS.has(tool))
+        return true;
+    const command = typeof input.command === 'string' ? input.command
+        : (!tool && typeof payload.command === 'string' ? payload.command : undefined);
+    if (!(SHELL_TOOLS.has(tool) || (!tool && command !== undefined)))
+        return false;
+    if (typeof command !== 'string' || !SEARCH_COMMAND_RE.test(command))
+        return false;
+    // A failed command (exit >= 2, nothing printed) is not a search result.
+    // grep's exit 1 with no output is a real zero-match and stays eligible.
+    const response = payload.tool_response ?? payload.tool_output ?? {};
+    if (response && typeof response === 'object') {
+        const code = Number(response.exit_code ?? response.exitCode ?? response.returnCode);
+        const stdout = response.stdout ?? response.output ?? response.llmContent ?? '';
+        if (Number.isFinite(code) && code >= 2 && String(stdout).trim() === '')
+            return false;
+    }
+    return true;
+}
+function ledgerDirectory() {
+    const home = process.env.MEMTRACE_HOME?.trim();
+    return home || path.join(os.homedir(), '.memtrace');
+}
+/** One timing row per enrichment hook call, written after stdout (design 10). */
+function logHookTiming(row) {
+    if (process.env.MEMTRACE_TELEMETRY?.trim().toLowerCase() === 'off')
         return;
+    try {
+        const dir = ledgerDirectory();
+        fs.mkdirSync(dir, { recursive: true });
+        // One write per line: concurrent hooks never merge records.
+        fs.appendFileSync(path.join(dir, 'rail-enrich-hook.jsonl'), JSON.stringify(row) + '\n');
+    }
+    catch { /* timing is best effort */ }
+}
+/** POST to the daemon; resolves empty on timeout, error or daemon death. */
+function postToDaemon(runtime, requestPath, input, killMs) {
+    return new Promise(resolve => {
+        let finished = false;
+        const finish = (value = { status: 0, body: '', headers: {} }) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(deadline);
+            clearInterval(monitor);
+            resolve(value);
+        };
+        const request = http.request({ hostname: '127.0.0.1', port: runtime.port,
+            method: 'POST', path: requestPath,
+            headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(input) },
+        }, response => {
+            let value = '';
+            response.on('data', chunk => {
+                value += chunk;
+                if (value.length > 2_000_000) {
+                    finish();
+                    request.destroy();
+                }
+            });
+            response.on('error', () => finish());
+            response.on('end', () => finish({ status: response.statusCode ?? 0, body: value, headers: response.headers }));
+        });
+        const deadline = setTimeout(() => { finish(); request.destroy(); }, killMs);
+        const monitor = setInterval(() => {
+            if (!pidAlive(runtime.pid) || !pidAlive(runtime.guardianPid)) {
+                finish();
+                request.destroy();
+            }
+        }, 50);
+        request.on('error', () => finish());
+        request.end(input);
+    });
+}
+async function readStdin() {
     let input = '';
     for await (const chunk of process.stdin) {
         input += chunk;
         if (input.length > 2_000_000)
-            return;
+            return undefined;
     }
+    return input;
+}
+async function main() {
+    const started = Date.now();
+    const env = process.env;
+    if (off(env.MEMTRACE_RAIL) || env.MEMTRACE_RAW_SEARCH?.trim().toLowerCase() === 'allow')
+        return;
+    const host = arg('--host') ?? 'generic';
+    const phase = arg('--phase');
+    const event = arg('--event');
+    const enrichPath = phase === 'post' || event === 'precompact';
+    // Explicit off (or a non-Nudge mode without opt-in) means no stdin parse,
+    // no lease read and no HTTP. Fresh Nudge enables bounded context by default.
+    if (enrichPath && !enrichEnabled(env))
+        return;
+    const input = await readStdin();
+    if (input === undefined)
+        return;
     const payload = JSON.parse(input);
+    if (phase === 'post' && !enrichEligible(payload))
+        return;
     const cwd = payload.cwd || payload.workspace_roots?.[0] || process.cwd();
     if (typeof cwd !== 'string')
         return;
-    const runtime = runtimeForCwd(cwd);
+    // Leases are read ONCE per call.
+    const runtime = runtimeForCwd(cwd, activeRailRuntimes());
     if (!runtime)
         return;
-    const hostIndex = process.argv.indexOf('--host');
-    const host = hostIndex >= 0 ? process.argv[hostIndex + 1] : 'generic';
-    const jsonMode = process.argv.includes('--json');
+    const alive = () => pidAlive(runtime.pid) && pidAlive(runtime.guardianPid);
+    if (event === 'precompact') {
+        const session = typeof payload.session_id === 'string' ? payload.session_id : '';
+        await postToDaemon(runtime, `/api/rail/enrich/reset?${new URLSearchParams({ session })}`, input, ENRICH_HOOK_KILL_MS);
+        return;
+    }
+    if (phase === 'post') {
+        const query = new URLSearchParams({ host, phase: 'post', enrich: env.MEMTRACE_ENRICH || '',
+            mode: env.MEMTRACE_RAIL || '', escape: env.MEMTRACE_RAW_SEARCH || '' });
+        const result = await postToDaemon(runtime, `/api/rail/enrich?${query}`, input, ENRICH_HOOK_KILL_MS);
+        let wrote = 0;
+        let malformed = false;
+        if (result.status === 200 && result.body && alive()) {
+            try {
+                JSON.parse(result.body); // never emit malformed endpoint output into an agent
+                process.stdout.write(result.body);
+                wrote = Buffer.byteLength(result.body);
+            }
+            catch {
+                malformed = true;
+            }
+        }
+        logHookTiming({
+            ts: new Date().toISOString(), host, phase: 'post', tool: payload.tool_name ?? null,
+            status: result.status,
+            outcome: malformed ? 'error' : result.headers['x-memtrace-enrich-outcome'] ?? (result.status ? null : 'no_daemon'),
+            bytes: Number(result.headers['x-memtrace-enrich-bytes'] ?? 0), stdout_bytes: wrote,
+            server_ms: Number(result.headers['x-memtrace-enrich-server-ms'] ?? 0), hook_ms: Date.now() - started,
+        });
+        return;
+    }
+    const jsonMode = argv.includes('--json');
     // JSON-mode/OpenCode and Windsurf retain their CLI response contracts.
     // Other hosts use the in-process daemon router with no native binary spawn.
     if (!jsonMode && host !== 'windsurf' && !runtime.routeBinary) {
-        const query = new URLSearchParams({ host, mode: process.env.MEMTRACE_RAIL || '',
-            escape: process.env.MEMTRACE_RAW_SEARCH || '' });
-        const body = await new Promise(resolve => {
-            let finished = false;
-            const finish = (value = '') => {
-                if (finished)
-                    return;
-                finished = true;
-                clearTimeout(deadline);
-                clearInterval(monitor);
-                resolve(value);
-            };
-            const request = http.request({ hostname: '127.0.0.1', port: runtime.port,
-                method: 'POST', path: `/api/rail/hook?${query}`,
-                headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(input) },
-            }, response => {
-                let value = '';
-                response.on('data', chunk => {
-                    value += chunk;
-                    if (value.length > 2_000_000) {
-                        finish();
-                        request.destroy();
-                    }
-                });
-                response.on('error', () => finish());
-                response.on('end', () => finish(response.statusCode === 200 ? value : ''));
-            });
-            const deadline = setTimeout(() => { finish(); request.destroy(); }, 5500);
-            const monitor = setInterval(() => {
-                if (!pidAlive(runtime.pid) || !pidAlive(runtime.guardianPid)) {
-                    finish();
-                    request.destroy();
-                }
-            }, 50);
-            request.on('error', () => finish());
-            request.end(input);
-        });
-        if (body && runtimeForCwd(cwd)) {
-            JSON.parse(body); // never emit malformed endpoint output into an agent
-            process.stdout.write(body);
+        const query = new URLSearchParams({ host, mode: env.MEMTRACE_RAIL || '', enrich: env.MEMTRACE_ENRICH || '',
+            escape: env.MEMTRACE_RAW_SEARCH || '' });
+        const result = await postToDaemon(runtime, `/api/rail/hook?${query}`, input, 5500);
+        if (result.status === 200 && result.body && alive()) {
+            JSON.parse(result.body); // never emit malformed endpoint output into an agent
+            process.stdout.write(result.body);
         }
         return;
     }
     const child = spawn(runtime.routeBinary || runtime.binary, jsonMode ? ['route', '--json', '-'] : ['route', '--hook', '--host', host], {
         cwd, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
-        env: { ...process.env, MEMTRACE_RAIL_SEARCH_URL: `http://127.0.0.1:${runtime.port}` },
+        env: { ...env, MEMTRACE_RAIL_SEARCH_URL: `http://127.0.0.1:${runtime.port}` },
     });
     let output = '';
     let stderr = '';
@@ -83,17 +193,15 @@ async function main() {
     child.stdin.end(input);
     const timer = setTimeout(() => child.kill(), 5500);
     // If the daemon exits while a request is in flight, discard the response.
-    const monitor = setInterval(() => {
-        if (!pidAlive(runtime.pid) || !pidAlive(runtime.guardianPid))
-            child.kill();
-    }, 50);
+    const monitor = setInterval(() => { if (!alive())
+        child.kill(); }, 50);
     const code = await new Promise(resolve => {
         child.once('error', () => resolve(null));
         child.once('close', resolve);
     });
     clearTimeout(timer);
     clearInterval(monitor);
-    if (!runtimeForCwd(cwd))
+    if (!alive())
         return;
     if (code === 0)
         process.stdout.write(output);
@@ -102,4 +210,16 @@ async function main() {
         process.exitCode = 2;
     }
 }
-main().catch(() => { });
+// Only run as a hook process, not when a test imports `enrichEligible`.
+const invokedDirectly = (() => {
+    try {
+        const self = fs.realpathSync(fileURLToPath(import.meta.url));
+        return fs.realpathSync(path.resolve(process.argv[1] ?? '')) === self;
+    }
+    catch {
+        return true;
+    }
+})();
+if (invokedDirectly) {
+    main().catch(() => { });
+}

package/dist/rail-install.js

@@ -9,7 +9,7 @@ import path from 'path';
 import { railIsActive } from './rail-runtime.js';
 import { registerRailHookInSettingsAt, removeRailHookFromSettingsAt, } from './transformers/claude.js';
 import { geminiSettingsPath } from './transformers/gemini.js';
-import { registerCursorRailHook, removeCursorRailHook, registerSettingsHook, removeSettingsHook, registerWindsurfRailHook, removeWindsurfRailHook, registerVsCodeRailHook, removeVsCodeRailHook, windsurfHooksPath, vscodeCopilotRailHookPath, CODEX_MATCHER, GEMINI_MATCHER, openCodeRailPluginPaths, openCodePluginSource, } from './transformers/rail-hooks.js';
+import { registerCursorRailHook, removeCursorRailHook, registerSettingsHook, removeSettingsHook, registerWindsurfRailHook, removeWindsurfRailHook, registerVsCodeRailHook, removeVsCodeRailHook, windsurfHooksPath, vscodeCopilotRailHookPath, CODEX_MATCHER, GEMINI_MATCHER, openCodeRailPluginPaths, openCodePluginSource, writeOpenCodeRailPlugin, } from './transformers/rail-hooks.js';
 /** Hosts with no Rail hook surface yet (MCP/skills only). */
 export const RAIL_UNSUPPORTED = [
     { host: 'hermes', reason: 'Hermes pre_tool_call adapter not wired yet' },
@@ -73,14 +73,11 @@ export function installRailHooks(ctx) {
     });
     try {
         const src = openCodePluginSource(bin);
-        for (const pluginPath of openCodeRailPluginPaths(ctx)) {
-            fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
-            fs.writeFileSync(pluginPath, src);
-        }
+        const pluginPath = writeOpenCodeRailPlugin(ctx, src);
         results.push({
             host: 'opencode',
             registered: true,
-            path: openCodeRailPluginPaths(ctx)[0],
+            path: pluginPath,
         });
     }
     catch (e) {

package/dist/rail-lifecycle.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { installRailHooks, uninstallRailHooks } from './rail-install.js';
-import { runtimeDirectory, railDisabled, activeRailRuntimes, pidAlive, LEASE_REFRESH_INTERVAL_MS } from './rail-runtime.js';
+import { runtimeDirectory, railDisabled, activeRailRuntimes, pidAlive, LEASE_REFRESH_INTERVAL_MS, enrichEnabled, railMode } from './rail-runtime.js';
 import { writeJsonAtomic } from './fs-safe.js';
 const arg = (name) => {
     const index = process.argv.indexOf(name);
@@ -43,13 +43,16 @@ async function main() {
         }
         writeJsonAtomic(lease, { pid, guardianPid: process.pid, updatedAt: Date.now(), cwd, binary, port, routeBinary });
         const enabled = !railDisabled();
-        if (enabled === wired)
+        // Grep enrichment and the Rail mode decide WHICH hooks are registered,
+        // so a rail.json change to either re-wires them without a restart.
+        const signature = enabled ? `on:${enrichEnabled()}:${railMode()}` : 'off';
+        if (signature === wired)
             return;
         if (enabled)
             installRailHooks(ctx);
         else
             uninstallRailHooks(ctx);
-        wired = enabled;
+        wired = signature;
     };
     const stop = () => {
         if (done)

package/dist/rail-runtime.d.ts

@@ -15,13 +15,48 @@ export declare function runtimeDirectory(): string;
 export declare function railDisabled(): boolean;
 export declare function persistHookOptOut(): void;
 export declare function pidAlive(pid: number): boolean;
+/** A lease this old whose owner and guardian are both gone is garbage. */
+export declare const LEASE_PRUNE_AGE_MS = 60000;
+/** Grep enrichment's hook kill (design section 10): the hook never waits longer. */
+export declare const ENRICH_HOOK_KILL_MS = 600;
+/**
+ * Cheap pre-network gate for shell commands: only these programs are code
+ * searches worth a loopback round trip (design 4.1). `git tag v1` must not
+ * match `ag`, so a program must start a word.
+ */
+export declare const SEARCH_COMMAND_RE: RegExp;
+export interface RailConfig {
+    mode?: string;
+    enrich?: boolean;
+    hooksEnabled?: boolean;
+}
+/** `~/.memtrace/rail.json` (or `MEMTRACE_RAIL_CONFIG`); `{}` when absent or unreadable. */
+export declare function railConfig(): RailConfig;
+/**
+ * Grep enrichment on/off: `MEMTRACE_ENRICH`, then rail.json `"enrich"`, then
+ * non-blocking Nudge mode. Explicit Observe, Off, Rail and Strict modes do
+ * not implicitly enable this additional post-search path.
+ */
+export declare function enrichEnabled(env?: NodeJS.ProcessEnv, config?: RailConfig): boolean;
+/** Rail mode: `MEMTRACE_RAIL`, then rail.json `"mode"`, then non-blocking nudge. */
+export declare function railMode(env?: NodeJS.ProcessEnv, config?: RailConfig): string;
+/**
+ * Live leases. Reading them also deletes garbage: a lease whose owner and
+ * guardian are both dead and whose heartbeat stopped over a minute ago.
+ * Every hook call reads every lease, and old daemons used to leave dozens.
+ */
 export declare function activeRailRuntimes(): RailRuntime[];
 export declare function railIsActive(): boolean;
-export declare function runtimeForCwd(cwd: string): RailRuntime | undefined;
-export declare function railHookInvocation(host: string): {
+export declare function runtimeForCwd(cwd: string, runtimes?: RailRuntime[]): RailRuntime | undefined;
+/**
+ * Exec-form hook invocation. `extra` selects the hook's role: none for the
+ * Rail PreToolUse router, `--phase post` for grep enrichment, `--event
+ * precompact` for the enrichment dedupe reset.
+ */
+export declare function railHookInvocation(host: string, extra?: string[]): {
     command: string;
     args: string[];
 };
 /** POSIX and Windows hosts that accept only command text. Claude uses exec form. */
-export declare function railHookCommand(host: string, platform?: NodeJS.Platform): string;
+export declare function railHookCommand(host: string, platform?: NodeJS.Platform, extra?: string[]): string;
 export declare function isRailCommand(command: string): boolean;

package/dist/rail-runtime.js

@@ -54,6 +54,73 @@ export function pidAlive(pid) {
         return error.code === 'EPERM';
     }
 }
+/** A lease this old whose owner and guardian are both gone is garbage. */
+export const LEASE_PRUNE_AGE_MS = 60_000;
+/** Grep enrichment's hook kill (design section 10): the hook never waits longer. */
+export const ENRICH_HOOK_KILL_MS = 600;
+/**
+ * Cheap pre-network gate for shell commands: only these programs are code
+ * searches worth a loopback round trip (design 4.1). `git tag v1` must not
+ * match `ag`, so a program must start a word.
+ */
+export const SEARCH_COMMAND_RE = /(^|[\s;|&(`])(rg|grep|egrep|fgrep|rgrep|ugrep|ug|ag|ack|git\s+grep)(\s|$)/;
+/** `~/.memtrace/rail.json` (or `MEMTRACE_RAIL_CONFIG`); `{}` when absent or unreadable. */
+export function railConfig() {
+    const configPath = process.env.MEMTRACE_RAIL_CONFIG?.trim()
+        || path.join(os.homedir(), '.memtrace', 'rail.json');
+    try {
+        const value = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        return value && typeof value === 'object' ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+function flag(value) {
+    switch (value?.trim().toLowerCase()) {
+        case 'on':
+        case '1':
+        case 'true':
+        case 'yes':
+        case 'enabled': return true;
+        case 'off':
+        case '0':
+        case 'false':
+        case 'no':
+        case 'disabled': return false;
+        default: return undefined;
+    }
+}
+/**
+ * Grep enrichment on/off: `MEMTRACE_ENRICH`, then rail.json `"enrich"`, then
+ * non-blocking Nudge mode. Explicit Observe, Off, Rail and Strict modes do
+ * not implicitly enable this additional post-search path.
+ */
+export function enrichEnabled(env = process.env, config = railConfig()) {
+    // Durable opt-outs remain effective even when an old agent inherited an
+    // enabling environment. This is the same no-hooks gate used by the lease.
+    if (env.MEMTRACE_INSTALL_NO_HOOKS === '1' || config.hooksEnabled === false
+        || (typeof config.mode === 'string' && config.mode.trim().toLowerCase() === 'off')
+        || env.MEMTRACE_RAIL?.trim().toLowerCase() === 'off'
+        || env.MEMTRACE_RAW_SEARCH?.trim().toLowerCase() === 'allow')
+        return false;
+    return flag(env.MEMTRACE_ENRICH)
+        ?? (typeof config.enrich === 'boolean' ? config.enrich : railMode(env, config) === 'nudge');
+}
+/** Rail mode: `MEMTRACE_RAIL`, then rail.json `"mode"`, then non-blocking nudge. */
+export function railMode(env = process.env, config = railConfig()) {
+    const valid = ['off', 'observe', 'nudge', 'rail', 'strict'];
+    const fromEnv = env.MEMTRACE_RAIL?.trim().toLowerCase();
+    if (fromEnv && valid.includes(fromEnv))
+        return fromEnv;
+    const fromConfig = typeof config.mode === 'string' ? config.mode.trim().toLowerCase() : '';
+    return valid.includes(fromConfig) ? fromConfig : 'nudge';
+}
+/**
+ * Live leases. Reading them also deletes garbage: a lease whose owner and
+ * guardian are both dead and whose heartbeat stopped over a minute ago.
+ * Every hook call reads every lease, and old daemons used to leave dozens.
+ */
 export function activeRailRuntimes() {
     if (railDisabled())
         return [];
@@ -61,8 +128,17 @@ export function activeRailRuntimes() {
         const now = Date.now();
         return fs.readdirSync(runtimeDirectory()).filter(name => name.endsWith('.json')).flatMap(name => {
             try {
-                const runtime = JSON.parse(fs.readFileSync(path.join(runtimeDirectory(), name), 'utf8'));
+                const file = path.join(runtimeDirectory(), name);
+                const runtime = JSON.parse(fs.readFileSync(file, 'utf8'));
                 const age = now - runtime.updatedAt;
+                if (Number.isFinite(age) && age > LEASE_PRUNE_AGE_MS
+                    && !pidAlive(runtime.pid) && !pidAlive(runtime.guardianPid)) {
+                    try {
+                        fs.rmSync(file, { force: true });
+                    }
+                    catch { /* best effort */ }
+                    return [];
+                }
                 if (!Number.isFinite(age) || age < -1000 || age > LEASE_MAX_AGE_MS
                     || !pidAlive(runtime.pid) || !pidAlive(runtime.guardianPid)
                     || typeof runtime.binary !== 'string' || !path.isAbsolute(runtime.binary)
@@ -91,20 +167,25 @@ function normalizedWorkspacePath(directory) {
     const normalized = resolved.replace(/\\/g, '/').replace(/\/$/, '');
     return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
 }
-export function runtimeForCwd(cwd) {
+export function runtimeForCwd(cwd, runtimes = activeRailRuntimes()) {
     const target = normalizedWorkspacePath(cwd);
-    return activeRailRuntimes()
+    return runtimes
         .map(runtime => ({ runtime, root: normalizedWorkspacePath(runtime.cwd) }))
         .filter(({ root }) => target === root || target.startsWith(root + '/'))
         .sort((a, b) => b.root.length - a.root.length || b.runtime.updatedAt - a.runtime.updatedAt)[0]?.runtime;
 }
-export function railHookInvocation(host) {
+/**
+ * Exec-form hook invocation. `extra` selects the hook's role: none for the
+ * Rail PreToolUse router, `--phase post` for grep enrichment, `--event
+ * precompact` for the enrichment dedupe reset.
+ */
+export function railHookInvocation(host, extra = []) {
     return { command: process.execPath,
-        args: [fileURLToPath(new URL('./rail-hook.js', import.meta.url)), '--host', host] };
+        args: [fileURLToPath(new URL('./rail-hook.js', import.meta.url)), '--host', host, ...extra] };
 }
 /** POSIX and Windows hosts that accept only command text. Claude uses exec form. */
-export function railHookCommand(host, platform = process.platform) {
-    const invocation = railHookInvocation(host);
+export function railHookCommand(host, platform = process.platform, extra = []) {
+    const invocation = railHookInvocation(host, extra);
     const quote = platform === 'win32'
         ? (s) => '"' + s.replace(/\\/g, '/').replace(/"/g, '\\"') + '"'
         : (s) => "'" + s.replace(/'/g, "'\\''") + "'";

package/dist/tool-names.js

@@ -18,6 +18,7 @@ export const MEMTRACE_TOOL_NAMES = Object.freeze([
     'detect_changes',
     'embed_diag',
     'embed_reset_breaker',
+    'explain',
     'export_query_audit',
     'find_api_calls',
     'find_api_endpoints',
@@ -66,6 +67,7 @@ export const MEMTRACE_TOOL_NAMES = Object.freeze([
     'get_function_quality_metrics',
     'get_impact',
     'get_process_flow',
+    'get_query_revision',
     'get_repository_stats',
     'get_service_diagram',
     'get_source_window',
@@ -74,6 +76,7 @@ export const MEMTRACE_TOOL_NAMES = Object.freeze([
     'get_timeline',
     'governing_contracts',
     'governing_rules',
+    'guided_refactor',
     'index_directory',
     'ingest_graph_fragment',
     'link_repositories',
@@ -86,10 +89,13 @@ export const MEMTRACE_TOOL_NAMES = Object.freeze([
     'list_watched_paths',
     'list_worktrees',
     'mem_diag',
+    'pdg_query',
     'preflight_check',
+    'query_graph',
     'read_doc',
     'recall_decision',
     'record_external_episode',
+    'rename_symbol',
     'replay_history',
     'review_agent_sessions',
     'review_github_pr',