memtrace-skills 1.2.10 → 1.2.13

package/dist/commands/install.d.ts

@@ -3,6 +3,7 @@ export interface InstallOptions {
     only?: string[];
     skipMcp?: boolean;
     yes?: boolean;
+    mode?: 'refresh';
 }
 export declare function resolveMemtraceBinary(): Promise<string | null>;
 export declare function runInstall(options: InstallOptions): Promise<void>;

package/dist/commands/install.js

@@ -48,7 +48,7 @@ export async function runInstall(options) {
         console.error('  Error: No skills found. Ensure skills/ directory exists.\n');
         process.exit(1);
     }
-    const memtraceBin = await resolveMemtraceBinary();
+    const memtraceBin = options.mode === 'refresh' ? '' : await resolveMemtraceBinary();
     if (memtraceBin === null) {
         console.warn('  ⚠ memtrace binary not found on PATH.');
         console.warn('    MCP registration will be skipped for every agent.\n');
@@ -58,7 +58,8 @@ export async function runInstall(options) {
         scope: options.scope,
         cwd: process.cwd(),
         memtraceBinary: memtraceBin ?? '',
-        skipMcp: options.skipMcp || memtraceBin === null,
+        skipMcp: options.mode === 'refresh' || options.skipMcp || memtraceBin === null,
+        mode: options.mode,
     };
     for (const t of transformers) {
         console.log(`  [${t.name}] installing...`);

package/dist/index.js

@@ -30,6 +30,15 @@ program
     };
     await runInstall(options);
 });
+program
+    .command('refresh')
+    .description('Update skills without registering MCP servers or enabling plugins and hooks')
+    .option('--only <agents>', 'comma-separated agent names', parseOnly)
+    .option('--local', 'refresh project-scoped skills', false)
+    .option('-y, --yes', 'non-interactive')
+    .action(async (opts) => {
+    await runInstall({ scope: opts.local ? 'local' : 'global', only: opts.only, yes: opts.yes, mode: 'refresh' });
+});
 program
     .command('doctor')
     .description('Check memtrace install health across all agents')

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.js

@@ -5,7 +5,7 @@ import http from 'node:http';
 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';
+import { activeRailRuntimes, bindSearch, enrichEnabled, pidAlive, ENRICH_HOOK_KILL_MS, SEARCH_COMMAND_RE, } from './rail-runtime.js';
 const argv = process.argv;
 function arg(name) {
     const index = argv.indexOf(name);
@@ -118,7 +118,8 @@ async function main() {
     const phase = arg('--phase');
     const event = arg('--event');
     const enrichPath = phase === 'post' || event === 'precompact';
-    // Grep enrichment is opt-in: off means no stdin parse, no lease read, no HTTP.
+    // 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();
@@ -131,19 +132,34 @@ async function main() {
     if (typeof cwd !== 'string')
         return;
     // Leases are read ONCE per call.
-    const runtime = runtimeForCwd(cwd, activeRailRuntimes());
-    if (!runtime)
-        return;
-    const alive = () => pidAlive(runtime.pid) && pidAlive(runtime.guardianPid);
+    const runtimes = activeRailRuntimes();
     if (event === 'precompact') {
+        // The dedupe lives in whichever runtime answered this session's
+        // searches, which a session above its repositories cannot tell.
         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);
+        const owner = bindSearch(payload, cwd, runtimes).runtime;
+        await Promise.all((owner ? [owner] : runtimes).map(runtime => postToDaemon(runtime, `/api/rail/enrich/reset?${new URLSearchParams({ session })}`, input, ENRICH_HOOK_KILL_MS)));
+        return;
+    }
+    const bound = bindSearch(payload, cwd, runtimes);
+    const runtime = bound.runtime;
+    if (!runtime) {
+        // Say why nothing was added: Memtrace runs, but for other folders. With
+        // nothing running at all the call stays silent and writes nothing.
+        if (phase === 'post' && runtimes.length) {
+            logHookTiming({ ts: new Date().toISOString(), host, phase: 'post', tool: payload.tool_name ?? null,
+                status: 0, outcome: 'no_runtime_for_cwd', bytes: 0, stdout_bytes: 0,
+                server_ms: 0, hook_ms: Date.now() - started });
+        }
         return;
     }
+    // The daemon resolves the repository from `cwd`: send the one bound.
+    const body = bound.cwd === cwd ? input : JSON.stringify({ ...payload, cwd: bound.cwd });
+    const alive = () => pidAlive(runtime.pid) && pidAlive(runtime.guardianPid);
     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);
+        const result = await postToDaemon(runtime, `/api/rail/enrich?${query}`, body, ENRICH_HOOK_KILL_MS);
         let wrote = 0;
         let malformed = false;
         if (result.status === 200 && result.body && alive()) {
@@ -169,9 +185,9 @@ async function main() {
     // 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: env.MEMTRACE_RAIL || '',
+        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);
+        const result = await postToDaemon(runtime, `/api/rail/hook?${query}`, body, 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);
@@ -179,7 +195,7 @@ async function main() {
         return;
     }
     const child = spawn(runtime.routeBinary || runtime.binary, jsonMode ? ['route', '--json', '-'] : ['route', '--hook', '--host', host], {
-        cwd, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
+        cwd: bound.cwd, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
         env: { ...env, MEMTRACE_RAIL_SEARCH_URL: `http://127.0.0.1:${runtime.port}` },
     });
     let output = '';
@@ -189,7 +205,7 @@ async function main() {
     child.stderr.on('data', chunk => { if (stderr.length < 2_000_000)
         stderr += chunk; });
     child.stdin.on('error', () => { });
-    child.stdin.end(input);
+    child.stdin.end(body);
     const timer = setTimeout(() => child.kill(), 5500);
     // If the daemon exits while a request is in flight, discard the response.
     const monitor = setInterval(() => { if (!alive())

package/dist/rail-lifecycle.js

@@ -14,6 +14,48 @@ const port = Number(arg('--port'));
 const binary = arg('--binary');
 const cwd = arg('--cwd');
 const routeBinary = arg('--route-binary') || undefined;
+/** Every repository the owner serves (`--root`, repeated). */
+const roots = process.argv.flatMap((value, index) => process.argv[index - 1] === '--root' && path.isAbsolute(value) ? [value] : []);
+const settingsFile = arg('--settings-file');
+/** Saved Settings keys that decide which hooks are registered. */
+const SETTINGS_KEYS = ['MEMTRACE_RAIL', 'MEMTRACE_ENRICH'];
+const startupEnv = Object.fromEntries(SETTINGS_KEYS.map(key => [key, process.env[key]]));
+/**
+ * Follow a Settings change while the owner runs. The daemon handed down the
+ * values it applied from the settings file (MEMTRACE_SETTINGS_APPLIED); those
+ * - and unset keys - track the file, while a variable the user set in the
+ * environment still wins, as everywhere else.
+ */
+function followSavedSettings() {
+    if (!settingsFile)
+        return;
+    let applied = {};
+    try {
+        applied = JSON.parse(process.env.MEMTRACE_SETTINGS_APPLIED || '{}') ?? {};
+    }
+    catch { /* none applied */ }
+    let saved;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+        saved = parsed && typeof parsed.values === 'object' && parsed.values ? parsed.values : {};
+    }
+    catch (error) {
+        // A file being rewritten keeps the current choice; a deleted one is "nothing saved".
+        if (error.code !== 'ENOENT')
+            return;
+        saved = {};
+    }
+    for (const key of SETTINGS_KEYS) {
+        const initial = startupEnv[key];
+        if (initial !== undefined && applied[key] !== initial)
+            continue;
+        const value = saved[key];
+        if (typeof value === 'string' && value.trim())
+            process.env[key] = value;
+        else
+            delete process.env[key];
+    }
+}
 async function main() {
     if (process.argv.includes('--sync')) {
         const live = activeRailRuntimes();
@@ -41,10 +83,11 @@ async function main() {
             stop();
             return;
         }
-        writeJsonAtomic(lease, { pid, guardianPid: process.pid, updatedAt: Date.now(), cwd, binary, port, routeBinary });
+        writeJsonAtomic(lease, { pid, guardianPid: process.pid, updatedAt: Date.now(), cwd, roots, binary, port, routeBinary });
+        followSavedSettings();
         const enabled = !railDisabled();
         // Grep enrichment and the Rail mode decide WHICH hooks are registered,
-        // so a rail.json change to either re-wires them without a restart.
+        // so a rail.json or Settings change to either re-wires them without a restart.
         const signature = enabled ? `on:${enrichEnabled()}:${railMode()}` : 'off';
         if (signature === wired)
             return;

package/dist/rail-runtime.d.ts

@@ -7,6 +7,11 @@ export interface RailRuntime {
     port: number;
     /** Local development override; packaged hooks normally use the daemon HTTP API. */
     routeBinary?: string;
+    /**
+     * Repository roots the runtime serves besides `cwd` (its workspace
+     * members), so a session in a member it was not started in still reaches it.
+     */
+    roots?: string[];
 }
 export declare const LEASE_MAX_AGE_MS = 3000;
 export declare const LEASE_REFRESH_INTERVAL_MS = 1000;
@@ -34,10 +39,11 @@ export interface RailConfig {
 export declare function railConfig(): RailConfig;
 /**
  * Grep enrichment on/off: `MEMTRACE_ENRICH`, then rail.json `"enrich"`, then
- * OFF — the default stays off until the A/B gate passes.
+ * 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 observe. */
+/** 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
@@ -46,7 +52,37 @@ export declare function railMode(env?: NodeJS.ProcessEnv, config?: RailConfig):
  */
 export declare function activeRailRuntimes(): RailRuntime[];
 export declare function railIsActive(): boolean;
+/** The live runtime whose start folder or served repository contains `cwd`; the innermost wins. */
 export declare function runtimeForCwd(cwd: string, runtimes?: RailRuntime[]): RailRuntime | undefined;
+/** The git checkout containing `start` (a directory or a file), if any. */
+export declare function gitRootOf(start: string): string | undefined;
+/**
+ * A linked worktree (`git worktree add ../x`) to its main checkout, through
+ * `.git` -> gitdir -> commondir. Anything else (a normal checkout, a
+ * submodule, an unreadable file) is returned unchanged.
+ */
+export declare function mainCheckout(root: string): string;
+/**
+ * Where a search looked, from the search itself: the Grep path, a leading
+ * `cd`, absolute path arguments, and the files its results name. Existing
+ * paths only, resolved against the session's working directory.
+ */
+export declare function searchTargets(payload: any, cwd: string): string[];
+/**
+ * Which runtime answers a search, and the directory to send it as `cwd`.
+ *
+ * The session's cwd alone misses common layouts: an orchestrator (and every
+ * subagent, which keeps its cwd) opened in a folder ABOVE the repositories, a
+ * daemon started in a repository's subfolder, and a linked worktree beside
+ * the main checkout. A session inside a covered repository keeps the plain
+ * cwd match; otherwise the repository the search itself names is bound, by
+ * its git root or its worktree's main checkout, and sent as the cwd so the
+ * daemon resolves that repository.
+ */
+export declare function bindSearch(payload: any, cwd: string, runtimes: RailRuntime[]): {
+    runtime?: RailRuntime;
+    cwd: string;
+};
 /**
  * Exec-form hook invocation. `extra` selects the hook's role: none for the
  * Rail PreToolUse router, `--phase post` for grep enrichment, `--event

package/dist/rail-runtime.js

@@ -63,7 +63,7 @@ export const ENRICH_HOOK_KILL_MS = 600;
  * 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|$)/;
+export const SEARCH_COMMAND_RE = /(^|[\s;|&(`])(rg|grep|egrep|fgrep|rgrep|ugrep|ug|ag|ack|git\s+grep|select-string|sls|findstr(?:\.exe)?)(\s|$)/i;
 /** `~/.memtrace/rail.json` (or `MEMTRACE_RAIL_CONFIG`); `{}` when absent or unreadable. */
 export function railConfig() {
     const configPath = process.env.MEMTRACE_RAIL_CONFIG?.trim()
@@ -93,19 +93,28 @@ function flag(value) {
 }
 /**
  * Grep enrichment on/off: `MEMTRACE_ENRICH`, then rail.json `"enrich"`, then
- * OFF — the default stays off until the A/B gate passes.
+ * 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()) {
-    return flag(env.MEMTRACE_ENRICH) ?? (typeof config.enrich === 'boolean' ? config.enrich : false);
+    // 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 observe. */
+/** 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 : 'observe';
+    return valid.includes(fromConfig) ? fromConfig : 'nudge';
 }
 /**
  * Live leases. Reading them also deletes garbage: a lease whose owner and
@@ -137,6 +146,10 @@ export function activeRailRuntimes() {
                     || typeof runtime.cwd !== 'string' || !path.isAbsolute(runtime.cwd)
                     || !Number.isInteger(runtime.port) || runtime.port < 1 || runtime.port > 65535)
                     return [];
+                // Older leases have no roots; a malformed entry never widens a lease.
+                runtime.roots = Array.isArray(runtime.roots)
+                    ? runtime.roots.filter(root => typeof root === 'string' && path.isAbsolute(root))
+                    : [];
                 return [runtime];
             }
             catch {
@@ -155,16 +168,136 @@ function normalizedWorkspacePath(directory) {
         resolved = fs.realpathSync.native(resolved);
     }
     catch { /* Unavailable paths retain the existing lexical matching behavior. */ }
-    const normalized = resolved.replace(/\\/g, '/').replace(/\/$/, '');
+    // A verbatim `\\?\C:\x` (a canonical Windows path) is the same folder as `C:\x`.
+    const normalized = resolved.replace(/\\/g, '/').replace(/^\/\/\?\/(UNC\/)?/i, (_m, unc) => unc ? '//' : '')
+        .replace(/\/$/, '');
     return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
 }
+function leaseRoots(runtime) {
+    return [runtime.cwd, ...(runtime.roots ?? [])];
+}
+/** The live runtime whose start folder or served repository contains `cwd`; the innermost wins. */
 export function runtimeForCwd(cwd, runtimes = activeRailRuntimes()) {
     const target = normalizedWorkspacePath(cwd);
     return runtimes
-        .map(runtime => ({ runtime, root: normalizedWorkspacePath(runtime.cwd) }))
-        .filter(({ root }) => target === root || target.startsWith(root + '/'))
+        .map(runtime => ({ runtime, root: leaseRoots(runtime).map(normalizedWorkspacePath)
+            .filter(root => target === root || target.startsWith(root + '/'))
+            .sort((a, b) => b.length - a.length)[0] ?? '' }))
+        .filter(({ root }) => root !== '')
         .sort((a, b) => b.root.length - a.root.length || b.runtime.updatedAt - a.runtime.updatedAt)[0]?.runtime;
 }
+function samePath(a, b) {
+    return normalizedWorkspacePath(a) === normalizedWorkspacePath(b);
+}
+/** The git checkout containing `start` (a directory or a file), if any. */
+export function gitRootOf(start) {
+    let dir = path.resolve(start);
+    for (let depth = 0; depth < 64; depth++) {
+        if (fs.existsSync(path.join(dir, '.git')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * A linked worktree (`git worktree add ../x`) to its main checkout, through
+ * `.git` -> gitdir -> commondir. Anything else (a normal checkout, a
+ * submodule, an unreadable file) is returned unchanged.
+ */
+export function mainCheckout(root) {
+    try {
+        const dotGit = path.join(root, '.git');
+        if (!fs.statSync(dotGit).isFile())
+            return root;
+        const gitdir = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(dotGit, 'utf8'))?.[1]?.trim();
+        if (!gitdir)
+            return root;
+        const absoluteGitdir = path.resolve(root, gitdir);
+        const common = path.resolve(absoluteGitdir, fs.readFileSync(path.join(absoluteGitdir, 'commondir'), 'utf8').trim());
+        return path.basename(common) === '.git' ? path.dirname(common) : root;
+    }
+    catch {
+        return root;
+    }
+}
+const CD_RE = /(?:^|&&|;|\|\|)\s*(?:cd|pushd|set-location|sl)\s+(?:"([^"]+)"|'([^']+)'|([^\s;&|]+))/i;
+const ABSOLUTE_ARG_RE = /"((?:[A-Za-z]:)?[\\/][^"]+)"|'((?:[A-Za-z]:)?[\\/][^']+)'|(?:^|\s)((?:[A-Za-z]:)?[\\/][^\s"';|&]+)/g;
+const RESULT_LINE_RE = /^((?:[A-Za-z]:)?[^:\r\n]+?):\d+[:-]/;
+/**
+ * Where a search looked, from the search itself: the Grep path, a leading
+ * `cd`, absolute path arguments, and the files its results name. Existing
+ * paths only, resolved against the session's working directory.
+ */
+export function searchTargets(payload, cwd) {
+    const found = [];
+    const add = (value) => {
+        if (typeof value !== 'string' || !value.trim() || found.length >= 12)
+            return;
+        const resolved = path.resolve(cwd, value.trim().replace(/^["']|["']$/g, ''));
+        if (!found.some(existing => samePath(existing, resolved)) && fs.existsSync(resolved))
+            found.push(resolved);
+    };
+    const input = payload?.tool_input ?? {};
+    add(input.path);
+    add(input.file_path);
+    const command = typeof input.command === 'string' ? input.command : '';
+    const cd = CD_RE.exec(command);
+    if (cd)
+        add(cd[1] ?? cd[2] ?? cd[3]);
+    for (const match of command.matchAll(ABSOLUTE_ARG_RE))
+        add(match[1] ?? match[2] ?? match[3]);
+    const response = payload?.tool_response ?? payload?.tool_output ?? {};
+    if (Array.isArray(response?.filenames))
+        response.filenames.slice(0, 5).forEach(add);
+    const text = typeof response === 'string' ? response
+        : String(response?.stdout ?? response?.content ?? response?.output ?? '');
+    for (const line of text.split('\n').slice(0, 20))
+        add(RESULT_LINE_RE.exec(line.trim())?.[1]);
+    return found;
+}
+/**
+ * Which runtime answers a search, and the directory to send it as `cwd`.
+ *
+ * The session's cwd alone misses common layouts: an orchestrator (and every
+ * subagent, which keeps its cwd) opened in a folder ABOVE the repositories, a
+ * daemon started in a repository's subfolder, and a linked worktree beside
+ * the main checkout. A session inside a covered repository keeps the plain
+ * cwd match; otherwise the repository the search itself names is bound, by
+ * its git root or its worktree's main checkout, and sent as the cwd so the
+ * daemon resolves that repository.
+ */
+export function bindSearch(payload, cwd, runtimes) {
+    const direct = runtimeForCwd(cwd, runtimes);
+    const cwdRoot = gitRootOf(cwd);
+    if (direct && cwdRoot)
+        return { runtime: direct, cwd };
+    const forRepository = (root) => {
+        const main = mainCheckout(root);
+        const runtime = runtimeForCwd(root, runtimes) ?? runtimeForCwd(main, runtimes)
+            ?? runtimes.find(candidate => leaseRoots(candidate).some(leaseRoot => {
+                const leaseRepository = gitRootOf(leaseRoot);
+                return leaseRepository !== undefined && (samePath(leaseRepository, root) || samePath(leaseRepository, main));
+            }));
+        return { main, runtime };
+    };
+    for (const target of searchTargets(payload, cwd)) {
+        const root = gitRootOf(target);
+        if (!root)
+            continue;
+        const { main, runtime } = forRepository(root);
+        if (runtime)
+            return { runtime, cwd: main };
+    }
+    if (cwdRoot) {
+        const { main, runtime } = forRepository(cwdRoot);
+        if (runtime)
+            return { runtime, cwd: samePath(main, cwdRoot) ? cwd : path.join(main, path.relative(cwdRoot, cwd)) };
+    }
+    return { runtime: direct, cwd };
+}
 /**
  * Exec-form hook invocation. `extra` selects the hook's role: none for the
  * Rail PreToolUse router, `--phase post` for grep enrichment, `--event

package/dist/tool-names.js

@@ -62,6 +62,7 @@ export const MEMTRACE_TOOL_NAMES = Object.freeze([
     'get_codebase_briefing',
     'get_daily_briefing',
     'get_directory_tree',
+    'get_env_contract',
     'get_episode_replay',
     'get_evolution',
     'get_function_quality_metrics',

package/dist/transformers/claude.d.ts

@@ -32,8 +32,8 @@ export declare function claudeRailHookCommand(_memtraceBinary: string, platform?
  * 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). While a daemon is running the hook defaults to **observe** —
- * `MEMTRACE_RAIL=nudge|rail|strict` opts into more. Mode is intentionally NOT
+ * transport). While a daemon is running the hook defaults to **nudge** —
+ * context alongside ordinary tools. Explicit modes are preserved. Mode is intentionally NOT
  * baked into the command so the user can change it via env without
  * re-installing.
  *
@@ -49,7 +49,7 @@ export declare const ENRICH_HOOK_MATCHER = "Grep|Bash|PowerShell";
 /** Claude hook timeout for the enrichment hooks, in seconds. */
 export declare const ENRICH_HOOK_TIMEOUT_S = 2;
 export interface RailHookOptions {
-    /** Register the grep-enrichment hooks. Default: `MEMTRACE_ENRICH`, then rail.json, then off. */
+    /** Register grep-enrichment hooks. Explicit env/config wins; implicit on only in Nudge. */
     enrich?: boolean;
     /** The Rail mode the PreToolUse decision depends on. Default: env, then rail.json. */
     mode?: string;
@@ -88,7 +88,9 @@ export declare function claudeUserConfigFile(): string;
  *  2. Fall back to manual: write cache files + update settings.json
  *  3. Register MCP server for memtrace tools
  */
-export declare function installClaudePlugin(skills: Skill[], memtraceBinaryPath: string): Promise<{
+export declare function installClaudePlugin(skills: Skill[], memtraceBinaryPath: string, options?: {
+    skipMcp?: boolean;
+}): Promise<{
     cacheDir: string;
     skillCount: number;
 }>;