memtrace-skills 1.1.12 → 1.2.0

package/dist/commands/install.js

@@ -4,6 +4,7 @@ import { loadSkills } from '../skills.js';
 import { ALL_TRANSFORMERS, findTransformer } from '../transformers/index.js';
 import { commandExists, execCommand } from '../utils.js';
 import { canPrompt, promptForChoices } from './picker.js';
+import { persistHookOptOut } from '../rail-runtime.js';
 export async function resolveMemtraceBinary() {
     if (await commandExists('memtrace'))
         return 'memtrace';
@@ -31,6 +32,9 @@ function selectTransformers(options) {
     return picks;
 }
 export async function runInstall(options) {
+    if (options.scope === 'global' && process.env.MEMTRACE_INSTALL_NO_HOOKS === '1') {
+        persistHookOptOut();
+    }
     console.log('\n  Memtrace Skills Installer\n');
     // Interactive prompt only when TTY is available and user didn't pre-specify
     if (!options.yes && (!options.only || options.only.length === 0) && canPrompt()) {

package/dist/rail-hook.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/rail-hook.js

@@ -0,0 +1,105 @@
+/** Cached host hooks stop here when Memtrace is absent. No output and no network. */
+import { spawn } from 'node:child_process';
+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())
+        return;
+    let input = '';
+    for await (const chunk of process.stdin) {
+        input += chunk;
+        if (input.length > 2_000_000)
+            return;
+    }
+    const payload = JSON.parse(input);
+    const cwd = payload.cwd || payload.workspace_roots?.[0] || process.cwd();
+    if (typeof cwd !== 'string')
+        return;
+    const runtime = runtimeForCwd(cwd);
+    if (!runtime)
+        return;
+    const hostIndex = process.argv.indexOf('--host');
+    const host = hostIndex >= 0 ? process.argv[hostIndex + 1] : 'generic';
+    const jsonMode = process.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);
+        }
+        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}` },
+    });
+    let output = '';
+    let stderr = '';
+    child.stdout.on('data', chunk => { if (output.length < 2_000_000)
+        output += chunk; });
+    child.stderr.on('data', chunk => { if (stderr.length < 2_000_000)
+        stderr += chunk; });
+    child.stdin.on('error', () => { });
+    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 code = await new Promise(resolve => {
+        child.once('error', () => resolve(null));
+        child.once('close', resolve);
+    });
+    clearTimeout(timer);
+    clearInterval(monitor);
+    if (!runtimeForCwd(cwd))
+        return;
+    if (code === 0)
+        process.stdout.write(output);
+    else if (host === 'windsurf' && code === 2) {
+        process.stderr.write(stderr);
+        process.exitCode = 2;
+    }
+}
+main().catch(() => { });

package/dist/rail-install.js

@@ -6,6 +6,7 @@
 import fs from 'fs';
 import os from 'os';
 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';
@@ -27,6 +28,9 @@ function cursorHooksPath(ctx) {
  * Idempotent. Does not install skills or MCP — hooks only.
  */
 export function installRailHooks(ctx) {
+    if (!railIsActive()) {
+        return uninstallRailHooks(ctx).map(result => ({ ...result, skipped: 'Memtrace is not active; no hook registered' }));
+    }
     const bin = ctx.memtraceBinary?.trim() ?? '';
     if (!bin) {
         throw new Error('memtrace binary path is required to install Rail hooks');

package/dist/rail-lifecycle.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/rail-lifecycle.js

@@ -0,0 +1,87 @@
+/** The daemon owns this process through stdin; EOF also covers SIGKILL/crashes. */
+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 } from './rail-runtime.js';
+import { writeJsonAtomic } from './fs-safe.js';
+const arg = (name) => {
+    const index = process.argv.indexOf(name);
+    return index >= 0 ? process.argv[index + 1] : '';
+};
+const pid = Number(arg('--pid'));
+const port = Number(arg('--port'));
+const binary = arg('--binary');
+const cwd = arg('--cwd');
+const routeBinary = arg('--route-binary') || undefined;
+async function main() {
+    if (process.argv.includes('--sync')) {
+        const live = activeRailRuntimes();
+        const ctx = { scope: 'global', cwd: process.cwd(),
+            memtraceBinary: live[0]?.binary || '', skipMcp: true };
+        if (live.length)
+            installRailHooks(ctx);
+        else
+            uninstallRailHooks(ctx);
+        return;
+    }
+    if (!pidAlive(pid) || !path.isAbsolute(binary || '') || !path.isAbsolute(cwd || '')
+        || !Number.isInteger(port) || port < 1 || port > 65535)
+        return;
+    const ctx = { scope: 'global', cwd, memtraceBinary: binary, skipMcp: true };
+    const directory = runtimeDirectory();
+    fs.mkdirSync(directory, { recursive: true });
+    const lease = path.join(directory, `${pid}-${randomUUID()}.json`);
+    let done = false;
+    let wired;
+    const reconcile = () => {
+        if (done)
+            return;
+        if (!pidAlive(pid)) {
+            stop();
+            return;
+        }
+        writeJsonAtomic(lease, { pid, guardianPid: process.pid, updatedAt: Date.now(), cwd, binary, port, routeBinary });
+        const enabled = !railDisabled();
+        if (enabled === wired)
+            return;
+        if (enabled)
+            installRailHooks(ctx);
+        else
+            uninstallRailHooks(ctx);
+        wired = enabled;
+    };
+    const stop = () => {
+        if (done)
+            return;
+        done = true;
+        clearInterval(timer);
+        try {
+            fs.unlinkSync(lease);
+        }
+        catch { /* already absent */ }
+        // One departing daemon must not disable a different live workspace.
+        if (activeRailRuntimes().length === 0)
+            uninstallRailHooks(ctx);
+        process.stdin.destroy();
+    };
+    const timer = setInterval(() => {
+        try {
+            reconcile();
+        }
+        catch {
+            stop();
+        }
+    }, 500);
+    if (!process.argv.includes('--watch-pid')) {
+        process.stdin.on('end', stop);
+        // Windows named pipes report a killed writer as ECONNRESET/close.
+        process.stdin.on('error', stop);
+        process.stdin.on('close', stop);
+        process.stdin.resume();
+    }
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    reconcile();
+}
+main().catch(() => { process.exitCode = 1; });

package/dist/rail-runtime.d.ts

@@ -0,0 +1,26 @@
+export interface RailRuntime {
+    pid: number;
+    guardianPid: number;
+    updatedAt: number;
+    cwd: string;
+    binary: string;
+    port: number;
+    /** Local development override; packaged hooks normally use the daemon HTTP API. */
+    routeBinary?: string;
+}
+export declare const LEASE_MAX_AGE_MS = 3000;
+export declare const RAIL_GUARD_MARKER = "rail-hook.js";
+export declare function runtimeDirectory(): string;
+export declare function railDisabled(): boolean;
+export declare function persistHookOptOut(): void;
+export declare function pidAlive(pid: number): boolean;
+export declare function activeRailRuntimes(): RailRuntime[];
+export declare function railIsActive(): boolean;
+export declare function runtimeForCwd(cwd: string): RailRuntime | undefined;
+export declare function railHookInvocation(host: 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 isRailCommand(command: string): boolean;

package/dist/rail-runtime.js

@@ -0,0 +1,112 @@
+/** Local daemon leases. Reading these never contacts a server or starts Memtrace. */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { writeJsonAtomic } from './fs-safe.js';
+export const LEASE_MAX_AGE_MS = 3000;
+export const RAIL_GUARD_MARKER = 'rail-hook.js';
+export function runtimeDirectory() {
+    return process.env.MEMTRACE_RAIL_RUNTIME_DIR?.trim()
+        || path.join(os.homedir(), '.memtrace', 'rail-runtimes');
+}
+export function railDisabled() {
+    if (process.env.MEMTRACE_INSTALL_NO_HOOKS === '1')
+        return true;
+    const configPath = process.env.MEMTRACE_RAIL_CONFIG?.trim()
+        || path.join(os.homedir(), '.memtrace', 'rail.json');
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        // An explicit durable opt-out wins over an old agent's environment.
+        return config.mode === 'off' || config.hooksEnabled === false;
+    }
+    catch (error) {
+        return error.code !== 'ENOENT';
+    }
+}
+export function persistHookOptOut() {
+    const configPath = process.env.MEMTRACE_RAIL_CONFIG?.trim()
+        || path.join(os.homedir(), '.memtrace', 'rail.json');
+    let config = {};
+    try {
+        config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    writeJsonAtomic(configPath, { ...config, hooksEnabled: false });
+}
+export function pidAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the PID exists but this token cannot signal it (for
+        // example an elevated Windows daemon). No signal is sent with signal 0.
+        // ESRCH is absence; leases also require a live guardian and fresh heartbeat.
+        return error.code === 'EPERM';
+    }
+}
+export function activeRailRuntimes() {
+    if (railDisabled())
+        return [];
+    try {
+        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 age = now - runtime.updatedAt;
+                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)
+                    || (runtime.routeBinary !== undefined && !path.isAbsolute(runtime.routeBinary))
+                    || typeof runtime.cwd !== 'string' || !path.isAbsolute(runtime.cwd)
+                    || !Number.isInteger(runtime.port) || runtime.port < 1 || runtime.port > 65535)
+                    return [];
+                return [runtime];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+export function railIsActive() { return activeRailRuntimes().length > 0; }
+function normalizedWorkspacePath(directory) {
+    let resolved = path.resolve(directory);
+    try {
+        resolved = fs.realpathSync.native(resolved);
+    }
+    catch { /* Unavailable paths retain the existing lexical matching behavior. */ }
+    const normalized = resolved.replace(/\\/g, '/').replace(/\/$/, '');
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+export function runtimeForCwd(cwd) {
+    const target = normalizedWorkspacePath(cwd);
+    return activeRailRuntimes()
+        .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) {
+    return { command: process.execPath,
+        args: [fileURLToPath(new URL('./rail-hook.js', import.meta.url)), '--host', host] };
+}
+/** POSIX and Windows hosts that accept only command text. Claude uses exec form. */
+export function railHookCommand(host, platform = process.platform) {
+    const invocation = railHookInvocation(host);
+    const quote = platform === 'win32'
+        ? (s) => '"' + s.replace(/\\/g, '/').replace(/"/g, '\\"') + '"'
+        : (s) => "'" + s.replace(/'/g, "'\\''") + "'";
+    return [invocation.command, ...invocation.args].map(quote).join(' ');
+}
+export function isRailCommand(command) {
+    return command.includes('route --hook') || command.includes(RAIL_GUARD_MARKER);
+}

package/dist/transformers/claude.d.ts

@@ -19,33 +19,20 @@ export interface SettingsMutationResult {
  * Merge-add the memtrace MCP server into a Claude settings.json file.
  * Never overwrites a malformed file — backs it up and returns registered=false.
  */
-export declare function registerMcpInSettingsAt(settingsPath: string, memtraceBinary: string): SettingsMutationResult;
+export declare function registerMcpInSettingsAt(settingsPath: string, memtraceBinary: string, legacyEnv?: Record<string, string>): SettingsMutationResult;
 /**
- * The Claude Code PreToolUse hook command.
- *
- * POSIX hosts POST the hook payload to the running daemon's in-process router
- * (`POST /api/rail/hook`) with one `curl` — ~5ms of process instead of the
- * full memtrace binary (node shim + native pair, ~59MB alive for ~0.5s) per
- * Grep/Glob/Bash call. Fail-open is structural: no daemon (connection
- * refused, bounded by `--connect-timeout`) or an old daemon without the
- * endpoint (`-f` on 404) produces no output, and `|| true` exits 0 — Claude
- * Code treats that as allow-with-no-decision. The full binary is NEVER the
- * fallback. The agent session's `MEMTRACE_RAIL` / `MEMTRACE_RAW_SEARCH` ride
- * along as query params, so per-session mode/escape semantics are identical
- * to the spawn era; `MEMTRACE_RAIL_SEARCH_URL` / `MEMTRACE_UI_PORT` override
- * the endpoint the same way they steered the binary's own daemon lookup.
- *
- * Windows keeps the gen-1 binary spawn: hook commands there do not run under
- * a POSIX shell, so the env-forwarding one-liner has no portable equivalent.
+ * Every host enters a local liveness guard before contacting Memtrace. The
+ * daemon lifecycle registers/removes this command; a cached registration is
+ * silent after a stop or crash. Windows uses exec-form command/args below.
  */
-export declare function claudeRailHookCommand(memtraceBinary: string, platform?: NodeJS.Platform): string;
+export declare function claudeRailHookCommand(_memtraceBinary: string, platform?: NodeJS.Platform): string;
 /**
  * Register the Memtrace Rail PreToolUse hook in a Claude settings.json.
  *
  * This is what makes Rail "part of memtrace" rather than a manual install:
  * `memtrace install` wires a PreToolUse hook that pipes every Grep/Glob/Bash
  * attempt through the Rail router (see {@link claudeRailHookCommand} for the
- * transport). The hook defaults to **observe** (zero behavior change) —
+ * transport). While a daemon is running the hook defaults to **observe** —
  * `MEMTRACE_RAIL=nudge|rail|strict` opts into more. Mode is intentionally NOT
  * baked into the command so the user can change it via env without
  * re-installing.
@@ -75,6 +62,11 @@ export interface SettingsCleanupResult {
  * installer versions and Claude marketplace schema changes.
  */
 export declare function removeClaudeSettingsEntriesAt(settingsPath: string): SettingsCleanupResult;
+/**
+ * Register the memtrace MCP server in Claude Code's settings.
+ * This adds the MCP server config so Claude Code can connect to memtrace tools.
+ */
+export declare function registerMcpServer(memtraceBinaryPath: string): Promise<void>;
 /** `~/.claude.json` — where Claude Code stores user-scope `mcpServers`. */
 export declare function claudeUserConfigFile(): string;
 /**

package/dist/transformers/claude.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'url';
 import { copyCanonicalPluginAssets, copyCanonicalPluginManifest, readCanonicalPluginVersion, } from '../../plugin-assets/index.js';
 import { execCommand, commandExists } from '../utils.js';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
+import { railIsActive, railHookInvocation, railHookCommand, RAIL_GUARD_MARKER } from '../rail-runtime.js';
 import { LEGACY_MCP_SERVER_NAME, MEMTRACE_MCP_ENV, removeLegacyMcpServer, } from './shared.js';
 const PLUGIN_NAME = 'memtrace-skills';
 const MARKETPLACE_NAME = 'memtrace';
@@ -74,7 +75,10 @@ async function tryMcpAddJson(memtraceBinary) {
         // The legacy server is normally absent. Removal is a best-effort upgrade migration.
     }
     const settingsFile = path.join(os.homedir(), '.claude', 'settings.json');
-    const existingEnv = readExistingMemtraceEnv(settingsFile);
+    const existingEnv = {
+        ...readExistingMemtraceEnv(settingsFile),
+        ...readExistingMemtraceEnv(path.join(os.homedir(), '.claude.json')),
+    };
     const mergedEnv = { ...existingEnv, ...MEMTRACE_MCP_ENV };
     const config = JSON.stringify({
         command: memtraceBinary,
@@ -181,7 +185,7 @@ async function tryClaudeCliInstall() {
  * Merge-add the memtrace MCP server into a Claude settings.json file.
  * Never overwrites a malformed file — backs it up and returns registered=false.
  */
-export function registerMcpInSettingsAt(settingsPath, memtraceBinary) {
+export function registerMcpInSettingsAt(settingsPath, memtraceBinary, legacyEnv = {}) {
     const { value, corrupted, backupPath } = safeReadJson(settingsPath);
     if (corrupted) {
         console.warn(`memtrace: ${settingsPath} is malformed; backed up to ${backupPath}. Skipped MCP registration for Claude.`);
@@ -198,7 +202,7 @@ export function registerMcpInSettingsAt(settingsPath, memtraceBinary) {
     const existingEnv = (isRecord(existing) && isRecord(existing.env))
         ? existing.env
         : {};
-    const mergedEnv = { ...existingEnv, ...MEMTRACE_MCP_ENV };
+    const mergedEnv = { ...legacyEnv, ...existingEnv, ...MEMTRACE_MCP_ENV };
     // Hosts defer MCP tool definitions behind ToolSearch by default, so an
     // unmarked server reaches the model as bare tool names while built-in
     // Grep/Glob/Read arrive with full schemas — a routing bias no instruction
@@ -231,29 +235,12 @@ const LEGACY_HOOK_SCRIPT_BASENAMES = [
     'posttool-mcp-telemetry.sh',
 ];
 /**
- * The Claude Code PreToolUse hook command.
- *
- * POSIX hosts POST the hook payload to the running daemon's in-process router
- * (`POST /api/rail/hook`) with one `curl` — ~5ms of process instead of the
- * full memtrace binary (node shim + native pair, ~59MB alive for ~0.5s) per
- * Grep/Glob/Bash call. Fail-open is structural: no daemon (connection
- * refused, bounded by `--connect-timeout`) or an old daemon without the
- * endpoint (`-f` on 404) produces no output, and `|| true` exits 0 — Claude
- * Code treats that as allow-with-no-decision. The full binary is NEVER the
- * fallback. The agent session's `MEMTRACE_RAIL` / `MEMTRACE_RAW_SEARCH` ride
- * along as query params, so per-session mode/escape semantics are identical
- * to the spawn era; `MEMTRACE_RAIL_SEARCH_URL` / `MEMTRACE_UI_PORT` override
- * the endpoint the same way they steered the binary's own daemon lookup.
- *
- * Windows keeps the gen-1 binary spawn: hook commands there do not run under
- * a POSIX shell, so the env-forwarding one-liner has no portable equivalent.
+ * Every host enters a local liveness guard before contacting Memtrace. The
+ * daemon lifecycle registers/removes this command; a cached registration is
+ * silent after a stop or crash. Windows uses exec-form command/args below.
  */
-export function claudeRailHookCommand(memtraceBinary, platform = process.platform) {
-    if (platform === 'win32')
-        return `${memtraceBinary} route --hook`;
-    const endpoint = '${MEMTRACE_RAIL_SEARCH_URL:-http://127.0.0.1:${MEMTRACE_UI_PORT:-3030}}';
-    const query = 'host=claude-code&mode=${MEMTRACE_RAIL:-}&escape=${MEMTRACE_RAW_SEARCH:-}';
-    return `curl -sf --connect-timeout 0.05 --max-time 2 --data-binary @- "${endpoint}/api/rail/hook?${query}" 2>/dev/null || true`;
+export function claudeRailHookCommand(_memtraceBinary, platform = process.platform) {
+    return railHookCommand('claude-code', platform);
 }
 /**
  * Register the Memtrace Rail PreToolUse hook in a Claude settings.json.
@@ -261,7 +248,7 @@ export function claudeRailHookCommand(memtraceBinary, platform = process.platfor
  * This is what makes Rail "part of memtrace" rather than a manual install:
  * `memtrace install` wires a PreToolUse hook that pipes every Grep/Glob/Bash
  * attempt through the Rail router (see {@link claudeRailHookCommand} for the
- * transport). The hook defaults to **observe** (zero behavior change) —
+ * transport). While a daemon is running the hook defaults to **observe** —
  * `MEMTRACE_RAIL=nudge|rail|strict` opts into more. Mode is intentionally NOT
  * baked into the command so the user can change it via env without
  * re-installing.
@@ -271,6 +258,10 @@ export function claudeRailHookCommand(memtraceBinary, platform = process.platfor
  * a malformed file.
  */
 export function registerRailHookInSettingsAt(settingsPath, memtraceBinary, platform = process.platform) {
+    if (!railIsActive()) {
+        removeRailHookFromSettingsAt(settingsPath);
+        return { registered: false };
+    }
     const { value, corrupted, backupPath } = safeReadJson(settingsPath);
     if (corrupted) {
         console.warn(`memtrace: ${settingsPath} is malformed; backed up to ${backupPath}. Skipped Rail hook registration.`);
@@ -289,7 +280,9 @@ export function registerRailHookInSettingsAt(settingsPath, memtraceBinary, platf
         hooks: [
             {
                 type: 'command',
-                command: claudeRailHookCommand(memtraceBinary, platform),
+                ...(platform === 'win32'
+                    ? railHookInvocation('claude-code')
+                    : { command: claudeRailHookCommand(memtraceBinary, platform) }),
             },
         ],
     });
@@ -299,7 +292,7 @@ export function registerRailHookInSettingsAt(settingsPath, memtraceBinary, platf
 }
 /** True when a PreToolUse entry is a memtrace-owned Rail hook (any generation). */
 function isRailHookEntry(entry) {
-    return hookCommands(entry).some((command) => RAIL_HOOK_MARKERS.some((marker) => command.includes(marker)));
+    return hookCommands(entry).some((command) => command.includes(RAIL_GUARD_MARKER) || RAIL_HOOK_MARKERS.some((marker) => command.includes(marker)));
 }
 function isLegacyMemtraceHookEntry(entry) {
     return hookCommands(entry).some((command) => (LEGACY_HOOK_SCRIPT_BASENAMES.some((basename) => command.includes(basename))));
@@ -317,7 +310,8 @@ function hookCommands(entry) {
     if (Array.isArray(entry.hooks)) {
         for (const hook of entry.hooks) {
             if (isRecord(hook) && typeof hook.command === 'string') {
-                commands.push(hook.command);
+                const args = Array.isArray(hook.args) ? hook.args.filter((arg) => typeof arg === 'string') : [];
+                commands.push([hook.command, ...args].join(' '));
             }
         }
     }
@@ -329,11 +323,23 @@ function pruneMemtraceOwnedHookEntries(hooks) {
         const entries = hooks[key];
         if (!Array.isArray(entries))
             continue;
-        const preserved = entries.filter((entry) => !isMemtraceOwnedHookEntry(entry));
-        if (preserved.length === entries.length)
-            continue;
-        changed = true;
-        hooks[key] = preserved.length === 0 ? undefined : preserved;
+        const preserved = entries.flatMap((entry) => {
+            if (isRecord(entry) && Array.isArray(entry.hooks)) {
+                const remaining = entry.hooks.filter(hook => !isMemtraceOwnedHookEntry({ hooks: [hook] }));
+                if (remaining.length === entry.hooks.length)
+                    return [entry];
+                changed = true;
+                return remaining.length ? [{ ...entry, hooks: remaining }] : [];
+            }
+            if (!isMemtraceOwnedHookEntry(entry))
+                return [entry];
+            changed = true;
+            return [];
+        });
+        if (preserved.length === 0)
+            delete hooks[key];
+        else
+            hooks[key] = preserved;
     }
     return changed;
 }
@@ -354,19 +360,13 @@ export function removeRailHookFromSettingsAt(settingsPath) {
     if (!value)
         return { changed: false };
     const settings = value;
-    if (!isRecord(settings.hooks) || !Array.isArray(settings.hooks.PreToolUse)) {
+    if (!isRecord(settings.hooks)) {
         return { changed: false };
     }
-    const before = settings.hooks.PreToolUse;
-    const after = before.filter((entry) => !isRailHookEntry(entry));
-    if (after.length === before.length)
+    // Retire legacy advisory/telemetry hooks too: they must not wake an agent
+    // while Memtrace is stopped, and the running Rail integration replaces them.
+    if (!pruneMemtraceOwnedHookEntries(settings.hooks))
         return { changed: false };
-    if (after.length === 0) {
-        delete settings.hooks.PreToolUse;
-    }
-    else {
-        settings.hooks.PreToolUse = after;
-    }
     if (Object.keys(settings.hooks).length === 0)
         delete settings.hooks;
     writeJsonAtomic(settingsPath, settings);
@@ -482,12 +482,12 @@ function removeClaudeInstalledPluginMetadata() {
  * Register the memtrace MCP server in Claude Code's settings.
  * This adds the MCP server config so Claude Code can connect to memtrace tools.
  */
-async function registerMcpServer(memtraceBinaryPath) {
+export async function registerMcpServer(memtraceBinaryPath) {
     const settingsFile = path.join(os.homedir(), '.claude', 'settings.json');
-    // ─── memtrace-rail ─── Always wire the Memtrace-first discovery hook so it
+    // ─── memtrace-rail ─── Reconcile the daemon-owned discovery hook so it
     // ships as part of `memtrace install` (not a manual step). Hooks live in
     // settings.json regardless of which MCP-registration strategy wins, and the
-    // hook defaults to observe mode (zero behavior change) until the user opts
+    // hook is absent while stopped, and observes while active until the user opts
     // into MEMTRACE_RAIL=nudge|rail|strict. Failure here must not block MCP
     // registration.
     // `memtrace install --no-hooks` (memtrace-public #25) propagates here via
@@ -500,20 +500,18 @@ async function registerMcpServer(memtraceBinaryPath) {
             console.warn(`memtrace: failed to register Rail hook: ${e.message}`);
         }
     }
+    else {
+        removeRailHookFromSettingsAt(settingsFile);
+    }
     // Strategy 1 (preferred): claude CLI's own add-json path
     const viaCli = await tryMcpAddJson(memtraceBinaryPath);
     if (viaCli)
         return;
-    // Strategy 2 (fallback): direct JSON merge (safe + atomic).
-    //
-    // MEMBIZ-66: Claude Code reads user-scope MCP servers from `~/.claude.json`,
-    // not from `~/.claude/settings.json`. When the `claude` CLI was missing or
-    // slow (a 5 s timeout on Windows is easy to hit), this fallback wrote only
-    // settings.json — skills loaded, every `mcp__memtrace__*` tool was absent,
-    // and `memtrace doctor` still reported the registration as healthy. Write
-    // the file the CLI actually reads, and keep settings.json for older
-    // tooling that still looks there.
-    registerMcpInSettingsAt(claudeUserConfigFile(), memtraceBinaryPath);
+    // Desktop-only installs have no `claude` CLI. Claude Code reads user MCP
+    // registrations from ~/.claude.json, not ~/.claude/settings.json (hooks).
+    // Migrate legacy env values without overriding the authoritative user entry.
+    registerMcpInSettingsAt(claudeUserConfigFile(), memtraceBinaryPath, readExistingMemtraceEnv(settingsFile));
+    // Retain staging's mirror for older tooling after migrating the user entry.
     registerMcpInSettingsAt(settingsFile, memtraceBinaryPath);
 }
 /** `~/.claude.json` — where Claude Code stores user-scope `mcpServers`. */
@@ -613,13 +611,17 @@ export async function uninstallClaudePlugin() {
     if (fs.existsSync(cacheRoot)) {
         fs.rmSync(cacheRoot, { recursive: true });
     }
-    // Remove from settings.json
-    const settingsFile = path.join(os.homedir(), '.claude', 'settings.json');
-    if (fs.existsSync(settingsFile)) {
-        try {
-            removeClaudeSettingsEntriesAt(settingsFile);
+    // Hooks/plugin settings and user MCP registrations are separate files.
+    for (const settingsFile of [
+        path.join(os.homedir(), '.claude', 'settings.json'),
+        path.join(os.homedir(), '.claude.json'),
+    ]) {
+        if (fs.existsSync(settingsFile)) {
+            try {
+                removeClaudeSettingsEntriesAt(settingsFile);
+            }
+            catch { /* */ }
         }
-        catch { /* */ }
     }
     removeClaudeMarketplaceCacheDirs();
     removeClaudeInstalledPluginMetadata();
@@ -676,7 +678,7 @@ export const claudeTransformer = {
                 agent: 'claude',
                 skillsWritten: skillCount,
                 skillsDir: path.join(os.homedir(), '.claude', 'skills'),
-                mcpConfigPath: path.join(os.homedir(), '.claude', 'settings.json'),
+                mcpConfigPath: path.join(os.homedir(), '.claude.json'),
                 mcpRegistered: !ctx.skipMcp,
                 warnings: [],
             };

package/dist/transformers/opencode.js

@@ -1,4 +1,5 @@
 import fs from 'fs';
+import { railIsActive } from '../rail-runtime.js';
 import path from 'path';
 import { registerOpenCodeMcpAt, removeMemtraceSkills, removeOpenCodeMcpAt, writeSkills, } from './shared.js';
 import { openCodeConfigDir, openCodeRailPluginPaths, openCodePluginSource, } from './rail-hooks.js';
@@ -32,6 +33,10 @@ export const opencodeTransformer = {
         try {
             const src = openCodePluginSource(ctx.memtraceBinary);
             for (const pluginPath of openCodeRailPluginPaths(ctx)) {
+                if (!railIsActive()) {
+                    fs.rmSync(pluginPath, { force: true });
+                    continue;
+                }
                 fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
                 fs.writeFileSync(pluginPath, src);
             }

package/dist/transformers/rail-hooks.d.ts

@@ -4,7 +4,7 @@ export declare const RAIL_HOOK_MARKER = "route --hook";
 export declare const CLAUDE_MATCHER = "Grep|Glob|Bash";
 export declare const CODEX_MATCHER = "Bash";
 export declare const GEMINI_MATCHER = "run_shell_command|read_file|read_many_files|glob|search_file_content";
-export declare function railCommand(binary: string, host: string): string;
+export declare function railCommand(_binary: string, host: string): string;
 export interface OpenCodePathContext {
     scope: 'global' | 'local';
     cwd: string;

package/dist/transformers/rail-hooks.js

@@ -19,14 +19,15 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
+import { railIsActive, railHookCommand, railHookInvocation, isRailCommand } from '../rail-runtime.js';
 /** Substring identifying a memtrace-owned Rail hook entry. */
 export const RAIL_HOOK_MARKER = 'route --hook';
 /** The discovery tools each host surfaces. */
 export const CLAUDE_MATCHER = 'Grep|Glob|Bash';
 export const CODEX_MATCHER = 'Bash';
 export const GEMINI_MATCHER = 'run_shell_command|read_file|read_many_files|glob|search_file_content';
-export function railCommand(binary, host) {
-    return `${binary} route --hook --host ${host}`;
+export function railCommand(_binary, host) {
+    return railHookCommand(host);
 }
 function trimmed(value) {
     const clean = value?.trim();
@@ -84,7 +85,7 @@ function isRecord(v) {
 export function isRailHookEntry(entry) {
     if (!isRecord(entry) || !Array.isArray(entry.hooks))
         return false;
-    return entry.hooks.some((h) => isRecord(h) && typeof h.command === 'string' && h.command.includes(RAIL_HOOK_MARKER));
+    return entry.hooks.some((h) => isRecord(h) && typeof h.command === 'string' && isRailCommand(h.command));
 }
 /**
  * Register a Claude-style settings.json hook (Codex `PreToolUse`, Gemini
@@ -92,6 +93,10 @@ export function isRailHookEntry(entry) {
  * malformed file.
  */
 export function registerSettingsHook(settingsPath, binary, host, eventName, matcher, extraSettings) {
+    if (!railIsActive()) {
+        removeSettingsHook(settingsPath, eventName);
+        return { registered: false };
+    }
     const { value, corrupted, backupPath } = safeReadJson(settingsPath);
     if (corrupted) {
         console.warn(`memtrace: ${settingsPath} is malformed; backed up to ${backupPath}. Skipped Rail hook.`);
@@ -150,6 +155,10 @@ export function removeSettingsHook(settingsPath, eventName) {
  * both shell execution (where rg/grep/find run) and file reads.
  */
 export function registerCursorRailHook(hooksPath, binary) {
+    if (!railIsActive()) {
+        removeCursorRailHook(hooksPath);
+        return { registered: false };
+    }
     const { value, corrupted, backupPath } = safeReadJson(hooksPath);
     if (corrupted) {
         console.warn(`memtrace: ${hooksPath} is malformed; backed up to ${backupPath}. Skipped Cursor Rail hook.`);
@@ -164,7 +173,7 @@ export function registerCursorRailHook(hooksPath, binary) {
     // hooking it would spawn a router subprocess on every file read for no benefit.
     const event = 'beforeShellExecution';
     const existing = Array.isArray(cfg.hooks[event]) ? cfg.hooks[event] : [];
-    const preserved = existing.filter((e) => !(isRecord(e) && typeof e.command === 'string' && e.command.includes(RAIL_HOOK_MARKER)));
+    const preserved = existing.filter((e) => !(isRecord(e) && typeof e.command === 'string' && isRailCommand(e.command)));
     preserved.push({ command: cmd });
     cfg.hooks[event] = preserved;
     writeJsonAtomic(hooksPath, cfg);
@@ -180,6 +189,10 @@ export function windsurfHooksPath() {
  * `show_output: true` so nudge context on stdout is visible in Cascade.
  */
 export function registerWindsurfRailHook(hooksPath, binary) {
+    if (!railIsActive()) {
+        removeWindsurfRailHook(hooksPath);
+        return { registered: false };
+    }
     const { value, corrupted, backupPath } = safeReadJson(hooksPath);
     if (corrupted) {
         console.warn(`memtrace: ${hooksPath} is malformed; backed up to ${backupPath}. Skipped Windsurf Rail hook.`);
@@ -192,7 +205,7 @@ export function registerWindsurfRailHook(hooksPath, binary) {
     const existing = Array.isArray(cfg.hooks[event]) ? cfg.hooks[event] : [];
     const preserved = existing.filter((e) => !(isRecord(e) &&
         typeof e.command === 'string' &&
-        e.command.includes(RAIL_HOOK_MARKER)));
+        isRailCommand(e.command)));
     preserved.push({ command: cmd, show_output: true });
     cfg.hooks[event] = preserved;
     writeJsonAtomic(hooksPath, cfg);
@@ -211,7 +224,7 @@ export function removeWindsurfRailHook(hooksPath) {
     const before = cfg.hooks.pre_run_command;
     const after = before.filter((e) => !(isRecord(e) &&
         typeof e.command === 'string' &&
-        e.command.includes(RAIL_HOOK_MARKER)));
+        isRailCommand(e.command)));
     if (after.length === before.length)
         return { changed: false };
     if (after.length === 0)
@@ -232,6 +245,10 @@ export function vscodeCopilotRailHookPath() {
  * Writes a dedicated file under `~/.copilot/hooks/` (loaded by default in recent VS Code).
  */
 export function registerVsCodeRailHook(hookFilePath, binary) {
+    if (!railIsActive()) {
+        removeVsCodeRailHook(hookFilePath);
+        return { registered: false };
+    }
     const { value, corrupted, backupPath } = safeReadJson(hookFilePath);
     if (corrupted) {
         console.warn(`memtrace: ${hookFilePath} is malformed; backed up to ${backupPath}. Skipped VS Code Rail hook.`);
@@ -242,7 +259,7 @@ export function registerVsCodeRailHook(hookFilePath, binary) {
     const pre = Array.isArray(existing.hooks?.PreToolUse) ? existing.hooks.PreToolUse : [];
     const preserved = pre.filter((e) => !(isRecord(e) &&
         typeof e.command === 'string' &&
-        e.command.includes(RAIL_HOOK_MARKER)));
+        isRailCommand(e.command)));
     preserved.push({ type: 'command', command: cmd, timeout: 30 });
     writeJsonAtomic(hookFilePath, {
         hooks: {
@@ -263,7 +280,7 @@ export function removeVsCodeRailHook(hookFilePath) {
     const before = cfg.hooks.PreToolUse;
     const after = before.filter((e) => !(isRecord(e) &&
         typeof e.command === 'string' &&
-        e.command.includes(RAIL_HOOK_MARKER)));
+        isRailCommand(e.command)));
     if (after.length === before.length)
         return { changed: false };
     if (after.length === 0) {
@@ -292,7 +309,7 @@ export function removeCursorRailHook(hooksPath) {
         if (!Array.isArray(cfg.hooks[event]))
             continue;
         const before = cfg.hooks[event];
-        const after = before.filter((e) => !(isRecord(e) && typeof e.command === 'string' && e.command.includes(RAIL_HOOK_MARKER)));
+        const after = before.filter((e) => !(isRecord(e) && typeof e.command === 'string' && isRailCommand(e.command)));
         if (after.length !== before.length) {
             changed = true;
             if (after.length === 0)
@@ -316,12 +333,14 @@ export function removeCursorRailHook(hooksPath) {
  * the Memtrace result as the error the agent sees.
  */
 export function openCodePluginSource(binary) {
+    const hook = railHookInvocation('open-code');
     return `// AUTO-GENERATED by memtrace install — Memtrace Rail discovery hook.
 // Routes OpenCode tool calls through \`${binary} route\`. Defaults to observe
 // (no-op) unless MEMTRACE_RAIL=nudge|rail|strict. Remove via 'memtrace uninstall'.
 import { execFileSync } from 'node:child_process';
 
-const BIN = ${JSON.stringify(binary)};
+const BIN = ${JSON.stringify(hook.command)};
+const ARGS = ${JSON.stringify([...hook.args, '--json'])};
 
 export const MemtraceRail = async ({ project, client, $ }) => ({
   'tool.execute.before': async (input, output) => {
@@ -335,8 +354,8 @@ export const MemtraceRail = async ({ project, client, $ }) => ({
         input: output?.args || {},
         session_id: input?.sessionID || 'opencode',
       };
-      const out = execFileSync(BIN, ['route', '--json', '-'], {
-        input: JSON.stringify(attempt), timeout: 1500, encoding: 'utf8',
+      const out = execFileSync(BIN, ARGS, {
+        input: JSON.stringify(attempt), timeout: 6000, encoding: 'utf8', windowsHide: true,
       });
       const decision = JSON.parse(out);
       if (decision.action === 'suppress_raw_with_result') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace-skills",
-  "version": "1.1.12",
+  "version": "1.2.0",
   "description": "Memtrace skills for AI coding agents — codebase exploration, temporal evolution, impact analysis, and more.",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "prebuild": "node scripts/copy-skills.js",
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "test": "vitest run",
+    "test": "vitest run && tsc && node --test tests/runtime/rail-lifecycle.test.mjs",
     "test:watch": "vitest"
   },
   "dependencies": {