memtrace 0.8.2 → 0.8.4

package/bin/memtrace.js

@@ -17,6 +17,17 @@ const { fetchLatestVersion, readCachedVersion } = require("../lib/update-check")
 // is the silent-disappearance bug from /tmp/mt-debug/exit.
 const { propagateChildExit } = require("../lib/exit-code");
 
+// ─── Signal-forwarding supervisor (the "npx memtrace start isn't working" fix) ──
+// Spawns the native binary async and forwards SIGINT/SIGTERM/SIGHUP from
+// this shim to the child. Pre-fix, `mcp` forwarded NO signals and the
+// `else` branch (which serves `start`) used `spawnSync` — so a SIGTERM
+// from npx / a supervisor / a terminal close killed the Node shim but
+// orphaned the Rust `memtrace start` daemon (still holding port 3030 +
+// the MemDB lock + the embed model). The next `start` then hit
+// "already running" / port-in-use. See lib/child-supervisor.js + its
+// unit/property/e2e tests.
+const { forwardSignalsTo } = require("../lib/child-supervisor");
+
 // ── Handle `memtrace uninstall` before delegating to the Rust binary ────────
 // npm v7+ does NOT fire preuninstall hooks for global packages (npm/cli#3042).
 // This command provides reliable cleanup users can run before `npm uninstall -g`.
@@ -352,11 +363,14 @@ async function maybePromptForUpgrade(command) {
 
 if (args[0] === "mcp") {
   // MCP mode: async spawn so Node's event loop keeps running long enough
-  // for the update check to print its notice to the agent's stderr.
+  // for the update check to print its notice to the agent's stderr, AND so
+  // forwardSignalsTo can route supervisor/terminal signals to the child
+  // (pre-fix the mcp branch orphaned the server on SIGTERM-to-shim).
   const child = spawn(binaryPath, args, {
     stdio: "inherit",
     env:   process.env,
   });
+  forwardSignalsTo(child);
 
   child.on("error", (e) => {
     process.stderr.write(`memtrace: failed to start: ${e.message}\n`);
@@ -372,12 +386,21 @@ if (args[0] === "mcp") {
   });
 
 } else {
-  // All other commands: synchronous pass-through, but FIRST give the
-  // user a chance to upgrade if cached check found a newer version.
-  // The prompt is gated on TTY + start/index command + cache says newer
-  // (see lib/update-prompt.js for the gating logic). When the user
-  // accepts, maybePromptForUpgrade calls process.exit() and we never
-  // reach the spawn below.
+  // All other commands (notably the long-running `memtrace start` daemon):
+  // FIRST give the user a chance to upgrade if the cached check found a
+  // newer version (gated on TTY + start/index + cache says newer — see
+  // lib/update-prompt.js). When the user accepts, maybePromptForUpgrade
+  // calls process.exit() and we never reach the spawn below.
+  //
+  // Then spawn the native binary ASYNC with signal forwarding — not
+  // `spawnSync`. Pre-fix this branch used `spawnSync`, which blocks Node
+  // and cannot forward a SIGTERM/SIGHUP delivered to the shim itself (only
+  // a foreground-process-group Ctrl-C reached the child). Under
+  // `npx memtrace@latest start`, a supervisor SIGTERM or terminal close
+  // killed the Node shim and orphaned the Rust daemon (port 3030 stuck),
+  // so the next `start` reported "already running" / port-in-use. The
+  // async spawn + forwardSignalsTo pair is the fix; see
+  // lib/child-supervisor.js + test/child-supervisor.test.js.
   (async () => {
     try {
       await maybePromptForUpgrade(args[0]);
@@ -387,17 +410,22 @@ if (args[0] === "mcp") {
         `[memtrace] Update prompt failed (continuing): ${e.message}\n`,
       );
     }
-    const result = spawnSync(binaryPath, args, {
+    const child = spawn(binaryPath, args, {
       stdio: "inherit",
       env:   process.env,
     });
-    if (result.error) {
-      console.error(`Failed to run memtrace: ${result.error.message}`);
+    forwardSignalsTo(child);
+
+    child.on("error", (e) => {
+      console.error(`Failed to run memtrace: ${e.message}`);
       process.exit(1);
-    }
-    // ─── Leaf B T5 ─── same propagation contract as the mcp branch.
-    // `spawnSync` returns `{status, signal}` — `status` is null when
-    // the child was killed; `?? 0` would silently drop signal info.
-    process.exit(propagateChildExit({ code: result.status, signal: result.signal }));
+    });
+    child.on("exit", (code, signal) => {
+      // ─── Leaf B T5 ─── same propagation contract as the mcp branch.
+      // The child's typed exit code (or 128+sig) is forwarded so a
+      // supervisor can distinguish a clean `start` shutdown (0) from
+      // SIGKILL (137) from the Phase-2 partial (75).
+      process.exit(propagateChildExit({ code, signal }));
+    });
   })();
 }

package/installer/dist/commands/doctor.js

@@ -159,6 +159,17 @@ function checkAgent(agent) {
             mcpConfigPath,
         };
     }
+    if (agent === 'warp') {
+        const skillsDir = path.join(os.homedir(), '.warp', 'skills');
+        const mcpConfigPath = path.join(os.homedir(), '.warp', '.mcp.json');
+        return {
+            agent,
+            skillsFound: countMemtraceSkills(skillsDir),
+            skillsDir,
+            mcpRegistered: mcpHasMemtrace(mcpConfigPath),
+            mcpConfigPath,
+        };
+    }
     const skillsDir = path.join(os.homedir(), '.cursor', 'skills');
     const mcpConfigPath = path.join(os.homedir(), '.cursor', 'mcp.json');
     return {

package/installer/dist/index.js

@@ -15,7 +15,7 @@ function parseOnly(val) {
 program
     .command('install')
     .description('Install memtrace skills and register MCP for selected agents')
-    .option('--only <agents>', 'comma-separated agent names (claude,cursor,codex,gemini,windsurf,vscode,hermes,opencode,kiro)', parseOnly)
+    .option('--only <agents>', 'comma-separated agent names (claude,cursor,codex,gemini,windsurf,vscode,hermes,opencode,kiro,warp)', parseOnly)
     .option('--local', 'install into the current project where the selected agent supports project scope', false)
     .option('--global', 'install globally (~/.claude/, ~/.cursor/, ~/.agents/) [default]', false)
     .option('--skip-mcp', 'write skills only, skip MCP server registration', false)

package/installer/dist/rail-install.js

@@ -8,7 +8,7 @@ import os from 'os';
 import path from 'path';
 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, openCodePluginSource, } from './transformers/rail-hooks.js';
+import { registerCursorRailHook, removeCursorRailHook, registerSettingsHook, removeSettingsHook, registerWindsurfRailHook, removeWindsurfRailHook, registerVsCodeRailHook, removeVsCodeRailHook, windsurfHooksPath, vscodeCopilotRailHookPath, CODEX_MATCHER, GEMINI_MATCHER, openCodeRailPluginPaths, openCodePluginSource, } from './transformers/rail-hooks.js';
 /** Hosts with no Rail hook surface yet (MCP/skills only). */
 export const RAIL_UNSUPPORTED = [
     { host: 'hermes', reason: 'Hermes pre_tool_call adapter not wired yet' },
@@ -22,17 +22,6 @@ function cursorHooksPath(ctx) {
     const base = ctx.scope === 'global' ? os.homedir() : ctx.cwd;
     return path.join(base, '.cursor', 'hooks.json');
 }
-function opencodeConfigDir(ctx) {
-    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
-    return ctx.scope === 'global' ? path.join(xdg, 'opencode') : path.join(ctx.cwd, '.opencode');
-}
-function opencodeRailPluginPaths(ctx) {
-    const base = opencodeConfigDir(ctx);
-    return [
-        path.join(base, 'plugin', 'memtrace-rail.js'),
-        path.join(base, 'plugins', 'memtrace-rail.js'),
-    ];
-}
 /**
  * Wire Rail discovery hooks for Claude, Cursor, Codex, Gemini, and OpenCode.
  * Idempotent. Does not install skills or MCP — hooks only.
@@ -80,14 +69,14 @@ export function installRailHooks(ctx) {
     });
     try {
         const src = openCodePluginSource(bin);
-        for (const pluginPath of opencodeRailPluginPaths(ctx)) {
+        for (const pluginPath of openCodeRailPluginPaths(ctx)) {
             fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
             fs.writeFileSync(pluginPath, src);
         }
         results.push({
             host: 'opencode',
             registered: true,
-            path: opencodeRailPluginPaths(ctx)[0],
+            path: openCodeRailPluginPaths(ctx)[0],
         });
     }
     catch (e) {
@@ -135,7 +124,7 @@ export function uninstallRailHooks(ctx) {
     const geminiPath = geminiSettingsPath(ctx);
     const gemini = removeSettingsHook(geminiPath, 'BeforeTool');
     results.push({ host: 'gemini', registered: false, path: geminiPath, skipped: gemini.changed ? undefined : 'no rail hook' });
-    for (const p of opencodeRailPluginPaths(ctx)) {
+    for (const p of openCodeRailPluginPaths(ctx)) {
         try {
             fs.rmSync(p, { force: true });
         }

package/installer/dist/transformers/codex.js

@@ -4,7 +4,6 @@ import path from 'path';
 import { commandExists, execCommand } from '../utils.js';
 import { registerSettingsHook, removeSettingsHook, CODEX_MATCHER, } from './rail-hooks.js';
 const MCP_SERVER_NAME = 'memtrace';
-const CODEX_MCP_SHIM_NAME = 'memtrace-mcp-codex-shim.cjs';
 function codexRailHooksPath(ctx) {
     const base = ctx.scope === 'global' ? path.join(os.homedir(), '.codex') : path.join(ctx.cwd, '.codex');
     return path.join(base, 'hooks.json');
@@ -38,82 +37,6 @@ function writeTextAtomic(filePath, content) {
     fs.writeFileSync(tmpPath, content);
     fs.renameSync(tmpPath, filePath);
 }
-function codexMcpShimSource() {
-    return `#!/usr/bin/env node
-const { spawn } = require('node:child_process');
-
-const binary = process.argv[2] || 'memtrace';
-const child = spawn(binary, ['mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
-
-process.stdin.pipe(child.stdin);
-child.stderr.pipe(process.stderr);
-
-function stripAnnotations(line) {
-  let message;
-  try {
-    message = JSON.parse(line);
-  } catch {
-    return line;
-  }
-
-  const content = message && message.result && message.result.content;
-  if (!Array.isArray(content)) return line;
-
-  const assistantItems = [];
-  const fallbackItems = [];
-  for (const item of content) {
-    if (!item || typeof item !== 'object') continue;
-    const clean = { ...item };
-    const annotations = clean.annotations;
-    delete clean.annotations;
-    fallbackItems.push(clean);
-    const audience = annotations && annotations.audience;
-    if (Array.isArray(audience) && audience.includes('assistant')) {
-      assistantItems.push(clean);
-    }
-  }
-
-  message.result.content = assistantItems.length > 0 ? assistantItems : fallbackItems;
-  return JSON.stringify(message);
-}
-
-let buffer = '';
-child.stdout.on('data', (chunk) => {
-  buffer += chunk.toString('utf8');
-  let index = buffer.indexOf('\\n');
-  while (index !== -1) {
-    const line = buffer.slice(0, index);
-    buffer = buffer.slice(index + 1);
-    process.stdout.write(stripAnnotations(line) + '\\n');
-    index = buffer.indexOf('\\n');
-  }
-});
-
-child.stdout.on('end', () => {
-  if (buffer.length > 0) process.stdout.write(stripAnnotations(buffer));
-});
-
-child.on('exit', (code, signal) => {
-  if (signal) process.kill(process.pid, signal);
-  process.exit(code ?? 0);
-});
-`;
-}
-function codexMcpShimPath(configFile) {
-    return path.join(path.dirname(configFile), CODEX_MCP_SHIM_NAME);
-}
-function writeCodexMcpShim(configFile) {
-    const shimPath = codexMcpShimPath(configFile);
-    writeTextAtomic(shimPath, codexMcpShimSource());
-    try {
-        fs.chmodSync(shimPath, 0o755);
-    }
-    catch {
-        // Windows and locked-down filesystems may reject chmod; Codex invokes it
-        // through Node, so executable bits are a convenience, not a requirement.
-    }
-    return shimPath;
-}
 function isMemtraceMcpTable(tableName) {
     return tableName === `mcp_servers.${MCP_SERVER_NAME}`
         || tableName === `mcp_servers."${MCP_SERVER_NAME}"`
@@ -196,11 +119,15 @@ export function registerCodexMcpAt(configFile, binary) {
     // after the freshly written parent block for readability.
     const stripped = stripCodexMcpServer(existing);
     const { rest, envBlock } = extractMemtraceEnvBlock(stripped);
-    const shimPath = writeCodexMcpShim(configFile);
+    // Bare `memtrace mcp` — no shim. The server now emits a Codex-safe, plain
+    // (annotation-free) tool response when the client identifies as Codex at
+    // `initialize` (MemtraceMcpServer / shape_tool_content), so Codex talks to the
+    // binary directly. This removes the Node shim that hand-configuring users
+    // (who wrote `command = "memtrace"` themselves) used to miss.
     const block = [
         `[mcp_servers.${MCP_SERVER_NAME}]`,
-        `command = ${tomlString(process.execPath)}`,
-        `args = [${[shimPath, binary].map(tomlString).join(', ')}]`,
+        `command = ${tomlString(binary)}`,
+        `args = ["mcp"]`,
     ].join('\n');
     const parts = [];
     if (rest)

package/installer/dist/transformers/index.d.ts

@@ -8,7 +8,8 @@ import { vscodeTransformer } from './vscode.js';
 import { hermesTransformer } from './hermes.js';
 import { opencodeTransformer } from './opencode.js';
 import { kiroTransformer } from './kiro.js';
+import { warpTransformer } from './warp.js';
 export declare const ALL_TRANSFORMERS: Transformer[];
 export declare function findTransformer(name: string): Transformer | undefined;
-export { claudeTransformer, cursorTransformer, codexTransformer, geminiTransformer, windsurfTransformer, vscodeTransformer, hermesTransformer, opencodeTransformer, kiroTransformer, };
+export { claudeTransformer, cursorTransformer, codexTransformer, geminiTransformer, windsurfTransformer, vscodeTransformer, hermesTransformer, opencodeTransformer, kiroTransformer, warpTransformer, };
 export type { Transformer, InstallContext, InstallResult, TransformResult } from './types.js';

package/installer/dist/transformers/index.js

@@ -7,6 +7,7 @@ import { vscodeTransformer } from './vscode.js';
 import { hermesTransformer } from './hermes.js';
 import { opencodeTransformer } from './opencode.js';
 import { kiroTransformer } from './kiro.js';
+import { warpTransformer } from './warp.js';
 export const ALL_TRANSFORMERS = [
     claudeTransformer,
     cursorTransformer,
@@ -17,8 +18,9 @@ export const ALL_TRANSFORMERS = [
     hermesTransformer,
     opencodeTransformer,
     kiroTransformer,
+    warpTransformer,
 ];
 export function findTransformer(name) {
     return ALL_TRANSFORMERS.find(t => t.name === name);
 }
-export { claudeTransformer, cursorTransformer, codexTransformer, geminiTransformer, windsurfTransformer, vscodeTransformer, hermesTransformer, opencodeTransformer, kiroTransformer, };
+export { claudeTransformer, cursorTransformer, codexTransformer, geminiTransformer, windsurfTransformer, vscodeTransformer, hermesTransformer, opencodeTransformer, kiroTransformer, warpTransformer, };

package/installer/dist/transformers/opencode.js

@@ -1,33 +1,17 @@
 import fs from 'fs';
-import os from 'os';
 import path from 'path';
 import { registerOpenCodeMcpAt, removeMemtraceSkills, removeOpenCodeMcpAt, writeSkills, } from './shared.js';
-import { openCodePluginSource } from './rail-hooks.js';
-function opencodeConfigDir() {
-    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
-    return path.join(xdg, 'opencode');
-}
+import { openCodeConfigDir, openCodeRailPluginPaths, openCodePluginSource, } from './rail-hooks.js';
 function skillsRoot(ctx) {
     return ctx.scope === 'global'
-        ? path.join(opencodeConfigDir(), 'skills')
+        ? path.join(openCodeConfigDir(ctx), 'skills')
         : path.join(ctx.cwd, '.opencode', 'skills');
 }
 function mcpPath(ctx) {
     return ctx.scope === 'global'
-        ? path.join(opencodeConfigDir(), 'opencode.json')
+        ? path.join(openCodeConfigDir(ctx), 'opencode.json')
         : path.join(ctx.cwd, 'opencode.json');
 }
-// OpenCode's plugin directory name changed across versions: current official
-// docs use `plugins/` (plural) while older/community builds load `plugin/`
-// (singular). We write the plugin to BOTH so it loads regardless of version;
-// uninstall removes both. (Identical content — whichever the runtime reads.)
-function railPluginPaths(ctx) {
-    const base = ctx.scope === 'global' ? opencodeConfigDir() : path.join(ctx.cwd, '.opencode');
-    return [
-        path.join(base, 'plugin', 'memtrace-rail.js'),
-        path.join(base, 'plugins', 'memtrace-rail.js'),
-    ];
-}
 export const opencodeTransformer = {
     name: 'opencode',
     async install(skills, ctx) {
@@ -47,7 +31,7 @@ export const opencodeTransformer = {
         // has no stdio hook). Defaults to observe; fail-open. Best effort.
         try {
             const src = openCodePluginSource(ctx.memtraceBinary);
-            for (const pluginPath of railPluginPaths(ctx)) {
+            for (const pluginPath of openCodeRailPluginPaths(ctx)) {
                 fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
                 fs.writeFileSync(pluginPath, src);
             }
@@ -67,7 +51,7 @@ export const opencodeTransformer = {
     async uninstall(ctx) {
         removeMemtraceSkills(skillsRoot(ctx));
         removeOpenCodeMcpAt(mcpPath(ctx));
-        for (const p of railPluginPaths(ctx)) {
+        for (const p of openCodeRailPluginPaths(ctx)) {
             try {
                 fs.rmSync(p, { force: true });
             }

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

@@ -5,6 +5,19 @@ 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 interface OpenCodePathContext {
+    scope: 'global' | 'local';
+    cwd: string;
+}
+export interface OpenCodePathOptions {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    homedir?: string;
+}
+export declare function openCodeHomeDir(options?: OpenCodePathOptions): string;
+export declare function openCodeGlobalConfigDir(options?: OpenCodePathOptions): string;
+export declare function openCodeConfigDir(ctx: OpenCodePathContext, options?: OpenCodePathOptions): string;
+export declare function openCodeRailPluginPaths(ctx: OpenCodePathContext, options?: OpenCodePathOptions): string[];
 export declare function isRailHookEntry(entry: unknown): boolean;
 export interface HookResult {
     registered: boolean;

package/installer/dist/transformers/rail-hooks.js

@@ -28,6 +28,56 @@ export const GEMINI_MATCHER = 'run_shell_command|read_file|read_many_files|glob|
 export function railCommand(binary, host) {
     return `${binary} route --hook --host ${host}`;
 }
+function trimmed(value) {
+    const clean = value?.trim();
+    return clean ? clean : undefined;
+}
+function windowsProfileHome(env) {
+    const userProfile = trimmed(env.USERPROFILE);
+    if (userProfile)
+        return userProfile;
+    const drive = trimmed(env.HOMEDRIVE);
+    const homePath = trimmed(env.HOMEPATH);
+    return drive && homePath ? `${drive}${homePath}` : undefined;
+}
+export function openCodeHomeDir(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const fallbackHome = trimmed(options.homedir ?? os.homedir());
+    const posixHome = trimmed(env.HOME);
+    const winHome = windowsProfileHome(env);
+    if (platform === 'win32') {
+        return winHome ?? posixHome ?? fallbackHome ?? '';
+    }
+    return posixHome ?? fallbackHome ?? winHome ?? '';
+}
+export function openCodeGlobalConfigDir(options = {}) {
+    const env = options.env ?? process.env;
+    const xdg = trimmed(env.XDG_CONFIG_HOME);
+    if (xdg)
+        return path.join(xdg, 'opencode');
+    const home = openCodeHomeDir(options);
+    if (!home) {
+        throw new Error('OpenCode config path unavailable: HOME or USERPROFILE is not set');
+    }
+    return path.join(home, '.config', 'opencode');
+}
+export function openCodeConfigDir(ctx, options = {}) {
+    return ctx.scope === 'global'
+        ? openCodeGlobalConfigDir(options)
+        : path.join(ctx.cwd, '.opencode');
+}
+// OpenCode's plugin directory name changed across versions: current official
+// docs use `plugins/` (plural) while older/community builds load `plugin/`
+// (singular). We write the plugin to BOTH so it loads regardless of version;
+// uninstall removes both. (Identical content — whichever the runtime reads.)
+export function openCodeRailPluginPaths(ctx, options = {}) {
+    const base = openCodeConfigDir(ctx, options);
+    return [
+        path.join(base, 'plugin', 'memtrace-rail.js'),
+        path.join(base, 'plugins', 'memtrace-rail.js'),
+    ];
+}
 function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }

package/installer/dist/transformers/types.d.ts

@@ -29,7 +29,7 @@ export interface InstallResult {
     mcpRegistered: boolean;
     warnings: string[];
 }
-export type AgentName = 'claude' | 'cursor' | 'codex' | 'gemini' | 'windsurf' | 'vscode' | 'hermes' | 'opencode' | 'kiro';
+export type AgentName = 'claude' | 'cursor' | 'codex' | 'gemini' | 'windsurf' | 'vscode' | 'hermes' | 'opencode' | 'kiro' | 'warp';
 /**
  * One transformer per supported AI coding agent.
  */

package/installer/dist/transformers/warp.d.ts

@@ -0,0 +1,4 @@
+import { Transformer } from './types.js';
+/** Global Warp MCP config: `~/.warp/.mcp.json` (auto-spawns by default). */
+export declare function warpMcpPath(): string;
+export declare const warpTransformer: Transformer;

package/installer/dist/transformers/warp.js

@@ -0,0 +1,83 @@
+import os from 'os';
+import path from 'path';
+import { registerMcpServersJsonAt, removeMcpServersJsonAt, removeMemtraceSkills, writeSkills, } from './shared.js';
+// Warp (https://docs.warp.dev/agent-platform/capabilities/mcp/) is a terminal
+// with a built-in agent that reads the open Agent Skills format (SKILL.md +
+// name/description frontmatter) and stdio MCP servers from JSON config.
+//
+// Two things make Warp's wiring different from the other transformers:
+//
+//   1. Skills + MCP both live under `~/.warp/` (global) or `<cwd>/.warp/`
+//      (project). We write to Warp's NATIVE provider paths rather than the
+//      `~/.agents/` "Other agents" paths, because the Warp provider row
+//      auto-spawns global servers by default — the "Other agents" row
+//      requires the user to toggle "Auto-spawn servers from third-party
+//      agents" on. Native paths = MCP works on first launch, zero toggling.
+//
+//   2. The MCP config file is a dotfile: `~/.warp/.mcp.json` (note the
+//      leading dot on the filename). The shared JSON helpers don't care
+//      about the basename — they read/merge/write atomically — so the only
+//      thing we customize is the path.
+//
+// Warp uses the same `mcpServers` schema as Claude Code / Windsurf / Kiro
+// (each entry: `{ command, args, env? }`), so we reuse
+// `registerMcpServersJsonAt` / `removeMcpServersJsonAt` from shared.ts —
+// corrupted-file backup, unrelated-server preservation, and empty-file
+// deletion on uninstall all come for free.
+function warpRoot(ctx) {
+    return ctx.scope === 'global'
+        ? path.join(os.homedir(), '.warp')
+        : path.join(ctx.cwd, '.warp');
+}
+function skillsRoot(ctx) {
+    return path.join(warpRoot(ctx), 'skills');
+}
+/** Global Warp MCP config: `~/.warp/.mcp.json` (auto-spawns by default). */
+export function warpMcpPath() {
+    return path.join(os.homedir(), '.warp', '.mcp.json');
+}
+function mcpPath(ctx) {
+    // Global: the Warp provider file (auto-spawns). Local: project-scoped
+    // `.warp/.mcp.json` at the repo root — Warp detects these but NEVER
+    // auto-spawns them (security: a cloned repo can't start arbitrary local
+    // commands). The install warning below tells the user to toggle it on.
+    return ctx.scope === 'global'
+        ? warpMcpPath()
+        : path.join(ctx.cwd, '.warp', '.mcp.json');
+}
+export const warpTransformer = {
+    name: 'warp',
+    async install(skills, ctx) {
+        const rootDir = skillsRoot(ctx);
+        const count = writeSkills(skills, rootDir);
+        const warnings = [];
+        let mcpRegistered = false;
+        const mcpConfigPath = mcpPath(ctx);
+        if (!ctx.skipMcp) {
+            const result = registerMcpServersJsonAt(mcpConfigPath, ctx.memtraceBinary);
+            mcpRegistered = result.registered;
+            if (!mcpRegistered && result.backupPath) {
+                warnings.push(`Warp MCP config was malformed; backed up to ${result.backupPath}.`);
+            }
+            // Project-scoped Warp servers never auto-spawn — the user must toggle
+            // the server on from Settings > Agents > MCP servers after install.
+            // Surface that so a `--local` install doesn't look like a no-op.
+            if (ctx.scope === 'local') {
+                warnings.push('Warp project-scoped MCP servers never auto-spawn — ' +
+                    'enable "memtrace" under Settings > Agents > MCP servers in Warp.');
+            }
+        }
+        return {
+            agent: 'warp',
+            skillsWritten: count,
+            skillsDir: rootDir,
+            mcpConfigPath,
+            mcpRegistered,
+            warnings,
+        };
+    },
+    async uninstall(ctx) {
+        removeMemtraceSkills(skillsRoot(ctx));
+        removeMcpServersJsonAt(mcpPath(ctx));
+    },
+};

package/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace-skills",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Memtrace skills for AI coding agents — codebase exploration, temporal evolution, impact analysis, and more.",
   "type": "module",
   "bin": {

package/installer/skills/commands/memtrace-decision-recall.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-decision-recall
-description: "Recall ranked decisions, bans, and conventions from Cortex decision memory by free-text query. Use when the user asks what was decided, what was chosen or rejected, whether there's a convention/ban/policy on something, or before re-picking a library, pattern, or approach that may already be settled. Do not reconstruct past decisions from git log or guesswork. To verify whether a known decision held, use memtrace-intent-verification; for symbol-scoped decision lineage/contracts, use memtrace-provenance."
+description: "Recall ranked decisions, bans, and conventions from Cortex decision memory by free-text query through the normal Memtrace MCP server. Use when the user asks what was decided/chosen/rejected, whether there is a convention/ban/policy, and before any non-trivial edit/refactor/delete or re-picking a library, pattern, architecture, or subsystem behavior that may already be settled. Do not reconstruct decisions from git log or guesswork. To verify whether a known decision held, use memtrace-intent-verification; for symbol lineage/contracts, use memtrace-provenance."
 allowed-tools:
   - mcp__memtrace__recall_decision
   - mcp__memtrace__verify_intent
@@ -16,7 +16,8 @@ metadata:
 `recall_decision` is the **free-text entry point** to decision memory. Given a query,
 it returns the statistically-ranked set of decisions/conversations that bear on it —
 including **bans** ("never use X", "don't do Y"), which are recorded as decisions.
-Use it before re-litigating a settled choice or contradicting a convention.
+Use it before re-litigating a settled choice, changing existing behavior, or
+contradicting a convention.
 
 This is the one decision-memory tool that takes plain text. The ranked decisions it
 returns carry the `decision_id`s the other tools (`verify_intent`, `get_arc`) need.
@@ -41,7 +42,8 @@ Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bun
 
 `recall_decision(query)` — `query` is free text. Use the noun phrase of the thing in
 question: a library (`"redis vs in-memory cache"`), a pattern (`"error handling
-strategy"`), a subsystem (`"auth tokens"`), or the exact thing you're about to do.
+strategy"`), a subsystem (`"auth tokens"`), a symbol, or the exact edit/refactor/delete
+you are about to do.
 
 ### 2. Read the ranked result
 
@@ -71,7 +73,8 @@ require a Decision node and will honestly return CannotProve. See
 
 | Situation | Action |
 |-----------|--------|
-| About to choose a library/pattern/approach | `recall_decision` FIRST — you may be undoing a deliberate choice or ban |
+| About to edit/refactor/delete existing code where intent may matter | `recall_decision("<symbol/subsystem/behavior>")` FIRST — you may be crossing a recorded decision, ban, or convention |
+| About to choose or replace a library/pattern/architecture | `recall_decision` FIRST — you may be undoing a deliberate choice or ban |
 | User asks "did we decide X?" / "what's our convention on Y?" | `recall_decision("X" / "Y")` |
 | You suspect a "don't do this" rule exists | `recall_decision` — bans are decisions and will surface |
 | Recall returns a decision you're about to contradict | Surface it to the user verbatim; don't silently override |