memtrace 0.6.0 → 0.6.11

package/installer/dist/transformers/gemini.js

@@ -0,0 +1,78 @@
+import os from 'os';
+import path from 'path';
+import { registerMcpServersJsonAt, removeMcpServersJsonAt, removeMemtraceSkills, writeSkills, } from './shared.js';
+import { registerSettingsHook, removeSettingsHook, GEMINI_MATCHER, } from './rail-hooks.js';
+/**
+ * Gemini CLI transformer.
+ *
+ * Gemini CLI (v0.26+) supports:
+ *  - MCP servers in `.gemini/settings.json` under `mcpServers` — the SAME
+ *    shape as the generic JSON registration (`command`/`args`/`env`).
+ *  - Lifecycle hooks under `hooks.BeforeTool` (matcher against the tool name,
+ *    e.g. `run_shell_command`) — where Memtrace Rail wires the discovery hook.
+ *
+ * Both live in the one `settings.json`; we register MCP first, then the Rail
+ * hook (each is a read-modify-write that preserves the other's keys).
+ */
+function geminiBase(ctx) {
+    return ctx.scope === 'global' ? path.join(os.homedir(), '.gemini') : path.join(ctx.cwd, '.gemini');
+}
+function skillsRoot(ctx) {
+    return path.join(geminiBase(ctx), 'skills');
+}
+export function geminiSettingsPath(ctx) {
+    return path.join(geminiBase(ctx), 'settings.json');
+}
+export const geminiTransformer = {
+    name: 'gemini',
+    async install(skills, ctx) {
+        const warnings = [];
+        const rootDir = skillsRoot(ctx);
+        // Skills as Markdown context files (Gemini reads MCP-server instructions
+        // for tool guidance; the skill files document the Memtrace-first workflow).
+        const skillsWritten = writeSkills(skills, rootDir);
+        const settingsPath = geminiSettingsPath(ctx);
+        let mcpRegistered = false;
+        if (!ctx.skipMcp) {
+            const result = registerMcpServersJsonAt(settingsPath, ctx.memtraceBinary);
+            mcpRegistered = result.registered;
+            if (!mcpRegistered && result.backupPath) {
+                warnings.push(`Gemini settings.json was malformed; backed up to ${result.backupPath}.`);
+            }
+        }
+        // ─── memtrace-rail ─── Wire the BeforeTool discovery hook (default
+        // observe). Matches Gemini's shell/read/glob/grep tool names. Gemini gates
+        // its hook system behind `enableHooks` + `enableMessageBusIntegration`
+        // (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,
+            });
+        }
+        catch (e) {
+            warnings.push(`failed to register Gemini Rail hook: ${e.message}`);
+        }
+        return {
+            agent: 'gemini',
+            skillsWritten,
+            skillsDir: rootDir,
+            mcpConfigPath: settingsPath,
+            mcpRegistered,
+            warnings,
+        };
+    },
+    async uninstall(ctx) {
+        removeMemtraceSkills(skillsRoot(ctx));
+        const settingsPath = geminiSettingsPath(ctx);
+        try {
+            removeSettingsHook(settingsPath, 'BeforeTool');
+        }
+        catch { /* best effort */ }
+        try {
+            removeMcpServersJsonAt(settingsPath);
+        }
+        catch { /* best effort */ }
+    },
+};

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

@@ -2,6 +2,7 @@ import { Transformer } from './types.js';
 import { claudeTransformer } from './claude.js';
 import { cursorTransformer } from './cursor.js';
 import { codexTransformer } from './codex.js';
+import { geminiTransformer } from './gemini.js';
 import { windsurfTransformer } from './windsurf.js';
 import { vscodeTransformer } from './vscode.js';
 import { hermesTransformer } from './hermes.js';
@@ -9,5 +10,5 @@ import { opencodeTransformer } from './opencode.js';
 import { kiroTransformer } from './kiro.js';
 export declare const ALL_TRANSFORMERS: Transformer[];
 export declare function findTransformer(name: string): Transformer | undefined;
-export { claudeTransformer, cursorTransformer, codexTransformer, windsurfTransformer, vscodeTransformer, hermesTransformer, opencodeTransformer, kiroTransformer, };
+export { claudeTransformer, cursorTransformer, codexTransformer, geminiTransformer, windsurfTransformer, vscodeTransformer, hermesTransformer, opencodeTransformer, kiroTransformer, };
 export type { Transformer, InstallContext, InstallResult, TransformResult } from './types.js';

package/installer/dist/transformers/index.js

@@ -1,6 +1,7 @@
 import { claudeTransformer } from './claude.js';
 import { cursorTransformer } from './cursor.js';
 import { codexTransformer } from './codex.js';
+import { geminiTransformer } from './gemini.js';
 import { windsurfTransformer } from './windsurf.js';
 import { vscodeTransformer } from './vscode.js';
 import { hermesTransformer } from './hermes.js';
@@ -10,6 +11,7 @@ export const ALL_TRANSFORMERS = [
     claudeTransformer,
     cursorTransformer,
     codexTransformer,
+    geminiTransformer,
     windsurfTransformer,
     vscodeTransformer,
     hermesTransformer,
@@ -19,4 +21,4 @@ export const ALL_TRANSFORMERS = [
 export function findTransformer(name) {
     return ALL_TRANSFORMERS.find(t => t.name === name);
 }
-export { claudeTransformer, cursorTransformer, codexTransformer, windsurfTransformer, vscodeTransformer, hermesTransformer, opencodeTransformer, kiroTransformer, };
+export { claudeTransformer, cursorTransformer, codexTransformer, geminiTransformer, windsurfTransformer, vscodeTransformer, hermesTransformer, opencodeTransformer, kiroTransformer, };

package/installer/dist/transformers/opencode.js

@@ -1,6 +1,8 @@
+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');
@@ -15,6 +17,17 @@ function mcpPath(ctx) {
         ? path.join(opencodeConfigDir(), '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) {
@@ -30,6 +43,18 @@ export const opencodeTransformer = {
                 warnings.push(`OpenCode config was malformed; backed up to ${result.backupPath}.`);
             }
         }
+        // ─── 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);
+            for (const pluginPath of railPluginPaths(ctx)) {
+                fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
+                fs.writeFileSync(pluginPath, src);
+            }
+        }
+        catch (e) {
+            warnings.push(`failed to write OpenCode Rail plugin: ${e.message}`);
+        }
         return {
             agent: 'opencode',
             skillsWritten: count,
@@ -42,5 +67,11 @@ export const opencodeTransformer = {
     async uninstall(ctx) {
         removeMemtraceSkills(skillsRoot(ctx));
         removeOpenCodeMcpAt(mcpPath(ctx));
+        for (const p of railPluginPaths(ctx)) {
+            try {
+                fs.rmSync(p, { force: true });
+            }
+            catch { /* best effort */ }
+        }
     },
 };

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

@@ -0,0 +1,56 @@
+/** Substring identifying a memtrace-owned Rail hook entry. */
+export declare const RAIL_HOOK_MARKER = "route --hook";
+/** The discovery tools each host surfaces. */
+export declare const CLAUDE_MATCHER = "Grep|Glob|Bash";
+export declare const CODEX_MATCHER = "Bash";
+export declare const GEMINI_MATCHER = "run_shell_command|read_file|read_many_files|glob|search_file_content";
+export declare function railCommand(binary: string, host: string): string;
+export declare function isRailHookEntry(entry: unknown): boolean;
+export interface HookResult {
+    registered: boolean;
+    backupPath?: string;
+}
+export interface CleanupResult {
+    changed: boolean;
+    backupPath?: string;
+}
+/**
+ * Register a Claude-style settings.json hook (Codex `PreToolUse`, Gemini
+ * `BeforeTool`). Idempotent; preserves unrelated hooks; never overwrites a
+ * malformed file.
+ */
+export declare function registerSettingsHook(settingsPath: string, binary: string, host: string, eventName: string, matcher: string, extraSettings?: Record<string, unknown>): HookResult;
+/** Remove a Rail hook from a Claude-style settings.json event array. */
+export declare function removeSettingsHook(settingsPath: string, eventName: string): CleanupResult;
+/**
+ * Register the Cursor Rail hook in `.cursor/hooks.json`. Cursor uses a distinct
+ * schema: `{version, hooks: {beforeShellExecution: [{command}]}}`. We intercept
+ * both shell execution (where rg/grep/find run) and file reads.
+ */
+export declare function registerCursorRailHook(hooksPath: string, binary: string): HookResult;
+/** Remove the Cursor Rail hook entries. */
+/** Windsurf Cascade hooks path (user-level). */
+export declare function windsurfHooksPath(): string;
+/**
+ * Register Windsurf `pre_run_command` Rail hook. Uses exit codes (not JSON stdout);
+ * `show_output: true` so nudge context on stdout is visible in Cascade.
+ */
+export declare function registerWindsurfRailHook(hooksPath: string, binary: string): HookResult;
+export declare function removeWindsurfRailHook(hooksPath: string): CleanupResult;
+/** VS Code / Copilot user hooks file (global). */
+export declare function vscodeCopilotRailHookPath(): string;
+/**
+ * Register VS Code agent `PreToolUse` hook (Claude-compatible JSON on stdio).
+ * Writes a dedicated file under `~/.copilot/hooks/` (loaded by default in recent VS Code).
+ */
+export declare function registerVsCodeRailHook(hookFilePath: string, binary: string): HookResult;
+export declare function removeVsCodeRailHook(hookFilePath: string): CleanupResult;
+export declare function removeCursorRailHook(hooksPath: string): CleanupResult;
+/**
+ * The OpenCode in-process plugin source. OpenCode has no stdio hook — plugins
+ * are TS/JS modules with a `tool.execute.before` async hook. This plugin shells
+ * out to the SAME router via `--host generic` (a ToolAttempt in, a
+ * DecisionEnvelope out) and, on suppression, throws to block the raw tool with
+ * the Memtrace result as the error the agent sees.
+ */
+export declare function openCodePluginSource(binary: string): string;

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

@@ -0,0 +1,303 @@
+/**
+ * memtrace-rail — per-host installer wiring for the Memtrace-first discovery
+ * hook. Each supported agent intercepts tool calls differently, so each gets a
+ * thin host-specific registration that points at the SAME router
+ * (`memtrace route --hook --host <h>`). All entries are idempotent and remove
+ * cleanly. Hooks default to observe mode (zero behavior change); the user opts
+ * into more via `MEMTRACE_RAIL=nudge|rail|strict`.
+ *
+ * Host families:
+ *  - Claude Code   → `.claude/settings.json` hooks.PreToolUse (in claude.ts)
+ *  - Codex         → `.codex/hooks.json`     hooks.PreToolUse
+ *  - Gemini CLI    → `.gemini/settings.json` hooks.BeforeTool
+ *  - Cursor        → `.cursor/hooks.json`    beforeShellExecution/beforeReadFile
+ *  - OpenCode      → `.opencode/plugin/memtrace-rail.js` (in-process plugin)
+ *  - Windsurf      → `~/.codeium/windsurf/hooks.json`  pre_run_command (exit-code contract)
+ *  - VS Code       → `~/.copilot/hooks/memtrace-rail.json` PreToolUse (Claude-shaped)
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
+/** Substring identifying a memtrace-owned Rail hook entry. */
+export const RAIL_HOOK_MARKER = 'route --hook';
+/** The discovery tools each host surfaces. */
+export const CLAUDE_MATCHER = 'Grep|Glob|Bash';
+export const CODEX_MATCHER = 'Bash';
+export const GEMINI_MATCHER = 'run_shell_command|read_file|read_many_files|glob|search_file_content';
+export function railCommand(binary, host) {
+    return `${binary} route --hook --host ${host}`;
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+export function isRailHookEntry(entry) {
+    if (!isRecord(entry) || !Array.isArray(entry.hooks))
+        return false;
+    return entry.hooks.some((h) => isRecord(h) && typeof h.command === 'string' && h.command.includes(RAIL_HOOK_MARKER));
+}
+/**
+ * Register a Claude-style settings.json hook (Codex `PreToolUse`, Gemini
+ * `BeforeTool`). Idempotent; preserves unrelated hooks; never overwrites a
+ * malformed file.
+ */
+export function registerSettingsHook(settingsPath, binary, host, eventName, matcher, extraSettings) {
+    const { value, corrupted, backupPath } = safeReadJson(settingsPath);
+    if (corrupted) {
+        console.warn(`memtrace: ${settingsPath} is malformed; backed up to ${backupPath}. Skipped Rail hook.`);
+        return { registered: false, backupPath };
+    }
+    const settings = (value ?? {});
+    // Some hosts gate the hook system behind top-level feature flags (e.g. Gemini
+    // requires `enableHooks` + `enableMessageBusIntegration` or BeforeTool hooks
+    // never fire). Merge them in without clobbering a value the user already set.
+    if (extraSettings) {
+        for (const [k, v] of Object.entries(extraSettings)) {
+            if (!(k in settings))
+                settings[k] = v;
+        }
+    }
+    settings.hooks = settings.hooks ?? {};
+    const existing = Array.isArray(settings.hooks[eventName])
+        ? settings.hooks[eventName]
+        : [];
+    const preserved = existing.filter((e) => !isRailHookEntry(e));
+    preserved.push({
+        matcher,
+        hooks: [{ type: 'command', command: railCommand(binary, host) }],
+    });
+    settings.hooks[eventName] = preserved;
+    writeJsonAtomic(settingsPath, settings);
+    return { registered: true };
+}
+/** Remove a Rail hook from a Claude-style settings.json event array. */
+export function removeSettingsHook(settingsPath, eventName) {
+    const { value, corrupted, backupPath } = safeReadJson(settingsPath);
+    if (corrupted)
+        return { changed: false, backupPath };
+    if (!value)
+        return { changed: false };
+    const settings = value;
+    if (!isRecord(settings.hooks) || !Array.isArray(settings.hooks[eventName])) {
+        return { changed: false };
+    }
+    const before = settings.hooks[eventName];
+    const after = before.filter((e) => !isRailHookEntry(e));
+    if (after.length === before.length)
+        return { changed: false };
+    if (after.length === 0)
+        delete settings.hooks[eventName];
+    else
+        settings.hooks[eventName] = after;
+    if (Object.keys(settings.hooks).length === 0)
+        delete settings.hooks;
+    writeJsonAtomic(settingsPath, settings);
+    return { changed: true };
+}
+/**
+ * Register the Cursor Rail hook in `.cursor/hooks.json`. Cursor uses a distinct
+ * schema: `{version, hooks: {beforeShellExecution: [{command}]}}`. We intercept
+ * both shell execution (where rg/grep/find run) and file reads.
+ */
+export function registerCursorRailHook(hooksPath, binary) {
+    const { value, corrupted, backupPath } = safeReadJson(hooksPath);
+    if (corrupted) {
+        console.warn(`memtrace: ${hooksPath} is malformed; backed up to ${backupPath}. Skipped Cursor Rail hook.`);
+        return { registered: false, backupPath };
+    }
+    const cfg = (value ?? {});
+    cfg.version = cfg.version ?? 1;
+    cfg.hooks = cfg.hooks ?? {};
+    const cmd = railCommand(binary, 'cursor');
+    // Only `beforeShellExecution` — that's where rg/grep/find run. We do NOT wire
+    // `beforeReadFile`: a file Read always classifies non-discovery (→ allow), so
+    // hooking it would spawn a router subprocess on every file read for no benefit.
+    const event = 'beforeShellExecution';
+    const existing = Array.isArray(cfg.hooks[event]) ? cfg.hooks[event] : [];
+    const preserved = existing.filter((e) => !(isRecord(e) && typeof e.command === 'string' && e.command.includes(RAIL_HOOK_MARKER)));
+    preserved.push({ command: cmd });
+    cfg.hooks[event] = preserved;
+    writeJsonAtomic(hooksPath, cfg);
+    return { registered: true };
+}
+/** Remove the Cursor Rail hook entries. */
+/** Windsurf Cascade hooks path (user-level). */
+export function windsurfHooksPath() {
+    return path.join(os.homedir(), '.codeium', 'windsurf', 'hooks.json');
+}
+/**
+ * Register Windsurf `pre_run_command` Rail hook. Uses exit codes (not JSON stdout);
+ * `show_output: true` so nudge context on stdout is visible in Cascade.
+ */
+export function registerWindsurfRailHook(hooksPath, binary) {
+    const { value, corrupted, backupPath } = safeReadJson(hooksPath);
+    if (corrupted) {
+        console.warn(`memtrace: ${hooksPath} is malformed; backed up to ${backupPath}. Skipped Windsurf Rail hook.`);
+        return { registered: false, backupPath };
+    }
+    const cfg = (value ?? {});
+    cfg.hooks = cfg.hooks ?? {};
+    const event = 'pre_run_command';
+    const cmd = railCommand(binary, 'windsurf');
+    const existing = Array.isArray(cfg.hooks[event]) ? cfg.hooks[event] : [];
+    const preserved = existing.filter((e) => !(isRecord(e) &&
+        typeof e.command === 'string' &&
+        e.command.includes(RAIL_HOOK_MARKER)));
+    preserved.push({ command: cmd, show_output: true });
+    cfg.hooks[event] = preserved;
+    writeJsonAtomic(hooksPath, cfg);
+    return { registered: true };
+}
+export function removeWindsurfRailHook(hooksPath) {
+    const { value, corrupted, backupPath } = safeReadJson(hooksPath);
+    if (corrupted)
+        return { changed: false, backupPath };
+    if (!value)
+        return { changed: false };
+    const cfg = value;
+    if (!isRecord(cfg.hooks) || !Array.isArray(cfg.hooks.pre_run_command)) {
+        return { changed: false };
+    }
+    const before = cfg.hooks.pre_run_command;
+    const after = before.filter((e) => !(isRecord(e) &&
+        typeof e.command === 'string' &&
+        e.command.includes(RAIL_HOOK_MARKER)));
+    if (after.length === before.length)
+        return { changed: false };
+    if (after.length === 0)
+        delete cfg.hooks.pre_run_command;
+    else
+        cfg.hooks.pre_run_command = after;
+    if (Object.keys(cfg.hooks).length === 0)
+        delete cfg.hooks;
+    writeJsonAtomic(hooksPath, cfg);
+    return { changed: true };
+}
+/** VS Code / Copilot user hooks file (global). */
+export function vscodeCopilotRailHookPath() {
+    return path.join(os.homedir(), '.copilot', 'hooks', 'memtrace-rail.json');
+}
+/**
+ * Register VS Code agent `PreToolUse` hook (Claude-compatible JSON on stdio).
+ * Writes a dedicated file under `~/.copilot/hooks/` (loaded by default in recent VS Code).
+ */
+export function registerVsCodeRailHook(hookFilePath, binary) {
+    const { value, corrupted, backupPath } = safeReadJson(hookFilePath);
+    if (corrupted) {
+        console.warn(`memtrace: ${hookFilePath} is malformed; backed up to ${backupPath}. Skipped VS Code Rail hook.`);
+        return { registered: false, backupPath };
+    }
+    const cmd = railCommand(binary, 'vscode');
+    const existing = (value ?? {});
+    const pre = Array.isArray(existing.hooks?.PreToolUse) ? existing.hooks.PreToolUse : [];
+    const preserved = pre.filter((e) => !(isRecord(e) &&
+        typeof e.command === 'string' &&
+        e.command.includes(RAIL_HOOK_MARKER)));
+    preserved.push({ type: 'command', command: cmd, timeout: 30 });
+    writeJsonAtomic(hookFilePath, {
+        hooks: {
+            PreToolUse: preserved,
+        },
+    });
+    return { registered: true };
+}
+export function removeVsCodeRailHook(hookFilePath) {
+    const { value, corrupted, backupPath } = safeReadJson(hookFilePath);
+    if (corrupted)
+        return { changed: false, backupPath };
+    if (!value)
+        return { changed: false };
+    const cfg = value;
+    if (!Array.isArray(cfg.hooks?.PreToolUse))
+        return { changed: false };
+    const before = cfg.hooks.PreToolUse;
+    const after = before.filter((e) => !(isRecord(e) &&
+        typeof e.command === 'string' &&
+        e.command.includes(RAIL_HOOK_MARKER)));
+    if (after.length === before.length)
+        return { changed: false };
+    if (after.length === 0) {
+        try {
+            fs.rmSync(hookFilePath, { force: true });
+        }
+        catch {
+            writeJsonAtomic(hookFilePath, { hooks: {} });
+        }
+        return { changed: true };
+    }
+    writeJsonAtomic(hookFilePath, { hooks: { PreToolUse: after } });
+    return { changed: true };
+}
+export function removeCursorRailHook(hooksPath) {
+    const { value, corrupted, backupPath } = safeReadJson(hooksPath);
+    if (corrupted)
+        return { changed: false, backupPath };
+    if (!value)
+        return { changed: false };
+    const cfg = value;
+    if (!isRecord(cfg.hooks))
+        return { changed: false };
+    let changed = false;
+    for (const event of ['beforeShellExecution', 'beforeReadFile']) {
+        if (!Array.isArray(cfg.hooks[event]))
+            continue;
+        const before = cfg.hooks[event];
+        const after = before.filter((e) => !(isRecord(e) && typeof e.command === 'string' && e.command.includes(RAIL_HOOK_MARKER)));
+        if (after.length !== before.length) {
+            changed = true;
+            if (after.length === 0)
+                delete cfg.hooks[event];
+            else
+                cfg.hooks[event] = after;
+        }
+    }
+    if (changed) {
+        if (isRecord(cfg.hooks) && Object.keys(cfg.hooks).length === 0)
+            delete cfg.hooks;
+        writeJsonAtomic(hooksPath, cfg);
+    }
+    return { changed };
+}
+/**
+ * The OpenCode in-process plugin source. OpenCode has no stdio hook — plugins
+ * are TS/JS modules with a `tool.execute.before` async hook. This plugin shells
+ * out to the SAME router via `--host generic` (a ToolAttempt in, a
+ * DecisionEnvelope out) and, on suppression, throws to block the raw tool with
+ * the Memtrace result as the error the agent sees.
+ */
+export function openCodePluginSource(binary) {
+    return `// AUTO-GENERATED by memtrace install — Memtrace Rail discovery hook.
+// Routes OpenCode tool calls through \`${binary} route\`. Defaults to observe
+// (no-op) unless MEMTRACE_RAIL=nudge|rail|strict. Remove via 'memtrace uninstall'.
+import { execFileSync } from 'node:child_process';
+
+const BIN = ${JSON.stringify(binary)};
+
+export const MemtraceRail = async ({ project, client, $ }) => ({
+  'tool.execute.before': async (input, output) => {
+    try {
+      const tool = input?.tool;
+      if (tool !== 'bash' && tool !== 'grep' && tool !== 'glob') return;
+      const attempt = {
+        host: 'open-code',
+        cwd: output?.args?.cwd || process.cwd(),
+        tool: tool === 'bash' ? 'Bash' : tool === 'grep' ? 'Grep' : 'Glob',
+        input: output?.args || {},
+        session_id: input?.sessionID || 'opencode',
+      };
+      const out = execFileSync(BIN, ['route', '--json', '-'], {
+        input: JSON.stringify(attempt), timeout: 1500, encoding: 'utf8',
+      });
+      const decision = JSON.parse(out);
+      if (decision.action === 'suppress_raw_with_result') {
+        throw new Error('[Memtrace Rail] ' + (decision.message || 'Use Memtrace for code discovery.') +
+          (decision.result ? '\\n' + JSON.stringify(decision.result, null, 2) : ''));
+      }
+    } catch (e) {
+      // Fail open on any router/exec error — never block the agent.
+      if (e && String(e.message || '').startsWith('[Memtrace Rail]')) throw e;
+    }
+  },
+});
+`;
+}

package/installer/dist/transformers/shared.js

@@ -2,12 +2,11 @@ import fs from 'fs';
 import path from 'path';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
 export const MCP_SERVER_NAME = 'memtrace';
-// Phase 3 (ArcadeDB removal): the binary uses an embedded MemDB by default and
-// reads MEMTRACE_MEMDB_MODE / workspace anchors directly. No env vars are
-// required at MCP-registration time. Preserved as an empty constant so any
-// future env-var plumbing (e.g. RUST_LOG, MEMTRACE_DATA_DIR overrides) has
-// one place to land. The corresponding upgrade migration in install.js strips
-// any legacy MEMTRACE_ARCADEDB_* keys from existing MCP entries on upgrade.
+// The binary reads its configuration (workspace anchors, mode) directly, so no
+// env vars are required at MCP-registration time. Kept as an empty constant so
+// any future env-var plumbing (e.g. RUST_LOG, MEMTRACE_DATA_DIR overrides) has
+// one place to land. The upgrade migration in install.js also prunes stale env
+// keys from pre-existing MCP entries.
 export const MEMTRACE_MCP_ENV = {};
 export function skillName(skill) {
     return skill.filename.replace(/\.md$/, '');

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

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

package/installer/skills/commands/memtrace-fleet-publish-intent.md

@@ -0,0 +1,51 @@
+---
+name: memtrace-fleet-publish-intent
+description: "Use to declare a structural intent BEFORE editing in a fleet — what symbols you'll touch and why — so other agents on your branch coordinate around you. Triggered by: 'I'm about to edit/rename/refactor X', starting any non-trivial edit while other agents share your repo+branch. Returns the graph blast radius, overlapping live intents on your branch, and a shift-left coordination/partition hint. Do not start editing shared symbols without publishing first."
+allowed-tools:
+  - mcp__memtrace__fleet_publish_intent
+  - mcp__memtrace__fleet_preflight
+---
+
+## Overview
+
+`fleet_publish_intent` is step 1 of the fleet protocol: announce what you're about
+to touch so other agents on the **same `(repo, branch)`** coordinate around you.
+It's a typed, ~20-token declaration — not prose.
+
+## Call it
+
+```jsonc
+fleet_publish_intent({
+  repo_id: "myrepo",
+  branch:  "session/auth-revamp",      // your fleet's session branch
+  agent_id:"agent-a",
+  touched: ["auth::verify_token"],     // qualified symbol identities
+  intent:  {"refactor": {"pattern": "change_signature"}},
+  assignment: "widen verify_token signature for pagination"   // the alignment anchor
+})
+```
+
+You get back:
+- `impact_preview` — the real graph blast radius of the touched symbols.
+- `active_conflicts` — overlapping live intents **on your branch** (none from other
+  branches; coordination is branch-scoped).
+- `coordination` — a shift-left hint: `would_escalate`, a `suggested_partition`
+  (who should own a contested symbol), and advice to realign *before* you edit.
+
+## Intent kinds (JSON, snake_case, externally-tagged)
+
+- `{"refactor":{"pattern":"rename_symbol"|"change_signature"|"move_symbol"|"extract_function"|…}}`
+- `{"feature_add":{"surface":"new_symbol"|"new_endpoint"|…}}`
+- `{"bug_fix":{"defect":"logic_error"|"null_handling"|…}}`
+- `{"cleanup":{"kind":"dead_code"|"unused_import"|…}}`
+- `{"performance":{"axis":"latency"|…}}`, `{"security_fix":{"severity":"high"}}`,
+  `{"test_add":{"covers":[…]}}`, `"docs_only"`, `"exploratory"`
+
+**Destructive** kinds — `change_signature`, `move_symbol`, `cleanup/dead_code` —
+are what raise a Class C decision when they overlap another agent's work.
+
+## Rules
+
+- Always pass `branch` (your session branch) and `assignment` (your task).
+- Read-only check first? Use `fleet_preflight` (same inputs, no registration).
+- An empty `active_conflicts` is good — proceed and `fleet_record_episode` when done.

package/installer/skills/commands/memtrace-fleet-record-episode.md

@@ -0,0 +1,48 @@
+---
+name: memtrace-fleet-record-episode
+description: "Use AFTER an edit in a fleet to record it and get its conflict class (A/B/C) against agents on your branch. Triggered by: finishing an edit, 'I just changed X', completing a refactor step while other agents share your repo+branch. Returns conflict_class + replan_hint; a Class C returns an escalation_id and mediation_request that starts the decision loop. Do not finish a coordinated edit without recording it."
+allowed-tools:
+  - mcp__memtrace__fleet_record_episode
+  - mcp__memtrace__fleet_get_escalation
+  - mcp__memtrace__fleet_query_episodes
+---
+
+## Overview
+
+`fleet_record_episode` is step 3 of the fleet protocol: record the edit you just
+made and learn whether it collided with another agent on your branch.
+
+## Call it
+
+```jsonc
+fleet_record_episode({
+  repo_id: "myrepo",
+  branch:  "session/auth-revamp",
+  agent_id:"agent-a",
+  touched: ["auth::verify_token"],
+  intent:  {"refactor": {"pattern": "change_signature"}}
+})
+```
+
+## The result: conflict_class
+
+- **A → proceed.** Additive, order-independent.
+- **B → re-read, then proceed.** Non-destructive overlap; re-read the shared
+  symbols so you build on current state.
+- **C → a decision is needed.** A destructive change overlaps another agent's
+  work. The response includes:
+  - `escalation_id` — the decision's id.
+  - `mediation_request` — the judging task (every agent's `assignment` + the
+    contested symbols). If you're asked to judge, call `fleet_submit_verdict`.
+  - `next_action` — poll `fleet_get_escalation({escalation_id, agent_id})` until
+    `your_directive` ≠ `wait`, then `proceed` / `defer` / `review`.
+
+Class is computed **only against agents on your branch**. Agents on other branches
+never make your edit a Class C.
+
+## After recording
+
+- Class A/B → continue.
+- Class C → enter the decision loop (see `memtrace-fleet-coordination`). Don't keep
+  editing the contested symbols until your directive is `proceed`.
+- Review history with `fleet_query_episodes({repo_id, node?, conflict_class?})`.