memtrace-skills 1.2.11 → 1.2.14

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/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);
@@ -132,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()) {
@@ -172,7 +187,7 @@ async function main() {
     if (!jsonMode && host !== 'windsurf' && !runtime.routeBinary) {
         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);
@@ -180,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 = '';
@@ -190,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;
@@ -47,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()
@@ -146,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 {
@@ -164,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

@@ -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;
 }>;

package/dist/transformers/claude.js

@@ -554,7 +554,7 @@ export function claudeUserConfigFile() {
  *  2. Fall back to manual: write cache files + update settings.json
  *  3. Register MCP server for memtrace tools
  */
-export async function installClaudePlugin(skills, memtraceBinaryPath) {
+export async function installClaudePlugin(skills, memtraceBinaryPath, options = {}) {
     // Retire known stock bare copies when moving to plugin delivery. Customized
     // strict policies/opt-outs survive; names alone never prove ownership.
     removeManagedSkills(path.join(os.homedir(), '.claude', 'skills'));
@@ -597,12 +597,39 @@ export async function installClaudePlugin(skills, memtraceBinaryPath) {
     }
     enablePluginInSettings();
     // Step 6: Register MCP server
-    await registerMcpServer(memtraceBinaryPath);
+    if (!options.skipMcp)
+        await registerMcpServer(memtraceBinaryPath);
     // Skills ship via the memtrace-skills@memtrace plugin only. Writing
     // bare copies to ~/.claude/skills/memtrace-* duplicates every skill
     // in Claude Code when the plugin is also enabled (issue #11).
     return { cacheDir, skillCount };
 }
+function refreshEnabledClaudePlugin(skills) {
+    const settingsFile = path.join(os.homedir(), '.claude', 'settings.json');
+    if (!fs.existsSync(settingsFile))
+        return 0;
+    const settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+    if (settings.enabledPlugins?.[PLUGIN_KEY] !== true)
+        return 0;
+    const root = getPluginCacheRoot();
+    if (!fs.existsSync(root))
+        return 0;
+    let skillCount = 0;
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const cacheDir = path.join(root, entry.name);
+        copyBundledPluginAssetsAt(cacheDir);
+        for (const skill of skills) {
+            for (const asset of transformForClaude(skill)) {
+                const name = path.basename(path.dirname(asset.relativePath));
+                if (writeManagedSkill(path.join(cacheDir, 'skills'), name, asset.content))
+                    skillCount++;
+            }
+        }
+    }
+    return skillCount;
+}
 /**
  * Write skills to ~/.claude/skills/ for SDK-based integrations.
  */
@@ -677,7 +704,9 @@ export const claudeTransformer = {
     name: 'claude',
     async install(skills, ctx) {
         if (ctx.scope === 'global') {
-            const { skillCount } = await installClaudePlugin(skills, ctx.memtraceBinary);
+            const skillCount = ctx.mode === 'refresh'
+                ? refreshEnabledClaudePlugin(skills)
+                : (await installClaudePlugin(skills, ctx.memtraceBinary, { skipMcp: ctx.skipMcp })).skillCount;
             return {
                 agent: 'claude',
                 skillsWritten: skillCount,

package/dist/transformers/codex-config.d.ts

@@ -0,0 +1,2 @@
+export declare function hasCodexMemtraceServer(raw: string): boolean;
+export declare function refreshCodexCommand(raw: string, command: string): string;

package/dist/transformers/codex-config.js

@@ -0,0 +1,33 @@
+import { isDeepStrictEqual } from 'node:util';
+import { parse } from 'smol-toml';
+const readConfig = (raw) => parse(raw, { integersAsBigInt: 'asNeeded' });
+function memtraceServer(config) {
+    const servers = config.mcp_servers;
+    if (!servers || typeof servers !== 'object' || Array.isArray(servers))
+        return undefined;
+    const server = servers.memtrace;
+    return server && typeof server === 'object' && !Array.isArray(server) ? server : undefined;
+}
+export function hasCodexMemtraceServer(raw) {
+    return memtraceServer(readConfig(raw)) !== undefined;
+}
+export function refreshCodexCommand(raw, command) {
+    const expected = readConfig(raw);
+    const server = memtraceServer(expected);
+    if (!server || typeof server.command !== 'string' || server.command === command)
+        return raw;
+    server.command = command;
+    let inServer = false;
+    const next = raw.split(/(?<=\n)/).map(line => {
+        if (/^\s*\[/.test(line)) {
+            inServer = /^\s*\[\s*mcp_servers\s*\.\s*(?:memtrace|"memtrace"|'memtrace')\s*\]\s*(?:#.*)?$/.test(line.trimEnd());
+        }
+        if (!inServer)
+            return line;
+        return line.replace(/^(\s*command\s*=\s*)(["'])(.*?)\2([ \t]*(?:#.*)?)(\r?\n)?$/, (_match, prefix, _quote, _value, comment, newline) => (`${prefix}${JSON.stringify(command)}${comment}${newline ?? ''}`));
+    }).join('');
+    if (!isDeepStrictEqual(readConfig(next), expected)) {
+        throw new Error('Cannot safely update the Codex MCP command; existing configuration was left unchanged.');
+    }
+    return next;
+}

package/dist/transformers/codex.js

@@ -3,6 +3,7 @@ import os from 'os';
 import path from 'path';
 import { writeManagedSkill, removeManagedSkills } from '../managed-skills.js';
 import { commandExists, execCommand } from '../utils.js';
+import { hasCodexMemtraceServer, refreshCodexCommand } from './codex-config.js';
 import { registerSettingsHook, removeSettingsHook, CODEX_MATCHER, } from './rail-hooks.js';
 const MCP_SERVER_NAME = 'memtrace';
 const LEGACY_MCP_SERVER_NAME = 'memfleet';
@@ -123,6 +124,12 @@ function extractMemtraceEnvBlock(raw) {
 }
 export function registerCodexMcpAt(configFile, binary) {
     const existing = fs.existsSync(configFile) ? fs.readFileSync(configFile, 'utf-8') : '';
+    if (hasCodexMemtraceServer(existing)) {
+        const next = refreshCodexCommand(existing, binary);
+        if (next !== existing)
+            writeTextAtomic(configFile, next);
+        return { registered: true };
+    }
     // Strip leaves the env sub-table intact; split it out so we can reorder it
     // after the freshly written parent block for readability.
     const stripped = stripCodexMcpServer(existing);
@@ -144,6 +151,8 @@ export function registerCodexMcpAt(configFile, binary) {
     if (envBlock)
         parts.push(envBlock);
     const next = `${parts.join('\n\n')}\n`;
+    if (!hasCodexMemtraceServer(next))
+        throw new Error('Codex MCP registration could not be validated.');
     writeTextAtomic(configFile, next);
     return { registered: true };
 }
@@ -172,7 +181,8 @@ export const codexTransformer = {
         const warnings = [];
         const mcpConfigPath = codexConfigPath(ctx);
         if (!ctx.skipMcp) {
-            const cliRegistered = ctx.scope === 'global' && await tryCodexMcpAdd(ctx.memtraceBinary);
+            const cliRegistered = ctx.scope === 'global' && !fs.existsSync(mcpConfigPath)
+                && await tryCodexMcpAdd(ctx.memtraceBinary);
             registerCodexMcpAt(mcpConfigPath, ctx.memtraceBinary);
             mcpRegistered = true;
             if (ctx.scope === 'global' && !cliRegistered) {
@@ -182,7 +192,8 @@ export const codexTransformer = {
         // ─── memtrace-rail ─── Wire the discovery hook into .codex/hooks.json
         // (PreToolUse, Bash matcher — Codex code discovery runs through the shell).
         try {
-            registerSettingsHook(codexRailHooksPath(ctx), ctx.memtraceBinary, 'codex', 'PreToolUse', CODEX_MATCHER);
+            if (ctx.mode !== 'refresh')
+                registerSettingsHook(codexRailHooksPath(ctx), ctx.memtraceBinary, 'codex', 'PreToolUse', CODEX_MATCHER);
         }
         catch (e) {
             warnings.push(`failed to register Codex Rail hook: ${e.message}`);

package/dist/transformers/cursor.js

@@ -107,7 +107,8 @@ export const cursorTransformer = {
         // ─── memtrace-rail ─── Wire the Memtrace-first discovery hook (default
         // observe). Failure must not block the rest of the install.
         try {
-            registerCursorRailHook(railHooksPath(ctx), ctx.memtraceBinary);
+            if (ctx.mode !== 'refresh')
+                registerCursorRailHook(railHooksPath(ctx), ctx.memtraceBinary);
         }
         catch (e) {
             console.warn(`memtrace: failed to register Cursor Rail hook: ${e.message}`);

package/dist/transformers/gemini.js

@@ -46,10 +46,11 @@ export const geminiTransformer = {
         // (PR #14460) — without them a registered BeforeTool hook NEVER fires, so we
         // enable both here (only if the user hasn't already set them).
         try {
-            registerSettingsHook(settingsPath, ctx.memtraceBinary, 'gemini', 'BeforeTool', GEMINI_MATCHER, {
-                enableHooks: true,
-                enableMessageBusIntegration: true,
-            });
+            if (ctx.mode !== 'refresh')
+                registerSettingsHook(settingsPath, ctx.memtraceBinary, 'gemini', 'BeforeTool', GEMINI_MATCHER, {
+                    enableHooks: true,
+                    enableMessageBusIntegration: true,
+                });
         }
         catch (e) {
             warnings.push(`failed to register Gemini Rail hook: ${e.message}`);

package/dist/transformers/opencode.js

@@ -31,13 +31,14 @@ export const opencodeTransformer = {
         // ─── memtrace-rail ─── Write the in-process discovery plugin (OpenCode
         // has no stdio hook). Defaults to observe; fail-open. Best effort.
         try {
-            const src = openCodePluginSource(ctx.memtraceBinary);
-            if (railIsActive()) {
-                writeOpenCodeRailPlugin(ctx, src);
-            }
-            else {
-                for (const pluginPath of openCodeRailPluginPaths(ctx)) {
-                    fs.rmSync(pluginPath, { force: true });
+            if (ctx.mode !== 'refresh') {
+                if (railIsActive()) {
+                    writeOpenCodeRailPlugin(ctx, openCodePluginSource(ctx.memtraceBinary));
+                }
+                else {
+                    for (const pluginPath of openCodeRailPluginPaths(ctx)) {
+                        fs.rmSync(pluginPath, { force: true });
+                    }
                 }
             }
         }

package/dist/transformers/pi.js

@@ -153,7 +153,9 @@ export const piTransformer = {
                 warnings: [`${e.message}`],
             };
         }
-        const result = registerPiPackageAt(settingsFile, packagePath);
+        const result = ctx.mode === 'refresh'
+            ? { registered: false, packagePath, backupPath: undefined }
+            : registerPiPackageAt(settingsFile, packagePath);
         if (!result.registered && result.backupPath) {
             warnings.push(`Pi settings.json was malformed; backed up to ${result.backupPath}.`);
         }

package/dist/transformers/types.d.ts

@@ -20,6 +20,8 @@ export interface InstallContext {
     memtraceBinary: string;
     /** When true, write skills but skip MCP registration. */
     skipMcp?: boolean;
+    /** Refresh resources without changing integration registrations or activation. */
+    mode?: 'refresh';
 }
 export interface InstallResult {
     agent: AgentName;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace-skills",
-  "version": "1.2.11",
+  "version": "1.2.14",
   "description": "Memtrace skills for AI coding agents — codebase exploration, temporal evolution, impact analysis, and more.",
   "type": "module",
   "bin": {
@@ -17,12 +17,13 @@
     "prebuild": "node scripts/copy-skills.js",
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "test": "vitest run && tsc && node --test tests/runtime/rail-lifecycle.test.mjs tests/runtime/rail-enrich-hook.test.mjs tests/runtime/opencode-rail-plugin.test.mjs",
+    "test": "vitest run && tsc && node --test tests/runtime/rail-lifecycle.test.mjs tests/runtime/rail-enrich-hook.test.mjs tests/runtime/opencode-rail-plugin.test.mjs tests/runtime/upgrade-integrations.test.mjs tests/runtime/rail-search-binding.test.mjs",
     "test:watch": "vitest"
   },
   "dependencies": {
     "commander": "^12.0.0",
-    "fs-extra": "^11.0.0"
+    "fs-extra": "^11.0.0",
+    "smol-toml": "1.9.1"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.0",

package/plugins/memtrace-skills/references/mcp-parameters.md

@@ -364,6 +364,17 @@ CALLS/REFERENCES/MAKES_API_CALL. Each result includes `confidence`,
 | `include_external` | boolean | no | `false` | Include calls to services outside indexed repos |
 | `repo_id` | string | no | — | Omit for full cross-service topology |
 
+### `get_env_contract`
+Lays the environment variables a deployment **sets** (Azure Bicep: Container Apps `env`, App Service `appSettings`, Container Instances `environmentVariables`, the `appsettings` config resource) against the ones the code **reads** (`process.env.X`, `os.getenv`, `System.getenv`, `std::env::var`, ...). Answers `matched`, `read_but_never_set` and `set_but_never_read`.
+
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | no | — | Omit to compare across the whole workspace — the infrastructure repo and the services it deploys are usually different repos |
+| `name` | string | no | — | Exact variable name: every place it is read and set |
+| `include_platform_provided` | boolean | no | `false` | List `PORT`, `WEBSITE_*`, `NODE_ENV`, ... under `read_but_never_set` instead of setting them apart |
+
+Only literal names are found, and only Bicep is read as an infrastructure source today; the answer's `caveats` say so.
+
 ### `link_repositories`
 Connects already-indexed repos so `get_api_topology` can stitch their HTTP graphs. Parameters vary — see `link_repositories` tool schema via the MCP `list_tools` call.
 
@@ -408,7 +419,9 @@ No parameters. Returns `{ watches: [{ path, repo_id, branch, started_at, origin
 | Field | Type | Required | Default |
 |---|---|---|---|
 | `repo_id` | string | yes | — |
-| `days` | integer | no | all history |
+| `days` | integer | no | as far back as the newest `MEMTRACE_REPLAY_MAX_COMMITS` commits reach (500 unless set; 0 = no limit) |
+
+Returns `replay_window`: `full_history` is true only when every reachable commit was read; `stopped_at_max_commits` and its `note` say when the limit left older history unread.
 
 ## Session bookends & pre-edit checks