fix(coding-agents): name the calling harness in every MCP registration (#3612)

* fix(coding-agents): name the calling harness in every MCP registration

Claude Code and Codex launch the same dist/mcp-server.js, and only
HINDSIGHT_MCP_HARNESS tells that server which one is calling. Four
installers never set it — codex, cursor-cli, copilot-cli and grok-build —
so their sessions fell back to "claude-code" for both the retain stamp
and bank derivation: a Codex hindsight_ingest_document landed tagged
harness:claude-code, indistinguishable from Claude Code's own writes.

Every registration now names its own harness (claude-code included, so it
no longer depends on the fallback). Codex's install also REPLACES an
existing [mcp_servers.hindsight] block instead of skipping when one is
present — appending only when absent made it install-once-only, so the
harness-less block could never be repaired by re-running the installer,
which is the upgrade path for anyone already hitting this.

The guard sweeps INSTALLERS and greps whatever the install actually wrote
for mcp-server.js: the harness that forgets is by construction the one
nobody wrote a test for.

Fixes #3603

* fix(coding-agents): require HINDSIGHT_MCP_HARNESS instead of guessing claude-code

The fallback read as a safe convenience and was not. Every host launches
the same mcp-server.js, so a registration that named no harness was
silently served as Claude Code — which is what made #3603 invisible: the
mis-stamped documents looked exactly like Claude Code's own. A wrong
harness corrupts stored data (the harness:<id> stamp and the bank the
session resolves); refusing to start is recoverable by re-running the
installer, and the error says so.

That turned up a second registration site the installer sweep could not
see: the codebase survey builds INLINE MCP recipes for its claude-code
and codex spawns (core/survey.ts), and neither named a harness — so a
Codex-run survey already filed its findings as harness:claude-code in
Claude Code's bank, and would now fail to start at all. Both recipes name
their agent.

Guarded by a source sweep modelled on the daemon-parity test: a module
that points at mcp-server.js is registering it and must assign the
variable. It matches an assignment rather than a mention on purpose — a
bare-name search is satisfied by the comments this fix added next to each
registration, which is exactly how survey.ts would have slipped through
again.

Author: nicoloboschi

hindsight-integrations/coding-agents/src/core/survey.test.ts

@@ -76,6 +76,9 @@ describe("startCodebaseSurvey", () => {
     const parsed = JSON.parse(mcpConfigJson);
     expect(parsed.mcpServers.hindsight.args).toEqual(["/x/mcp-server.js"]);
     expect(parsed.mcpServers.hindsight.env.HINDSIGHT_MCP_PROJECT_CWD).toBe("/repo");
+    // #3603: mcp-server.js requires the harness — an inline recipe that omits it used to be served
+    // as claude-code by default, and now refuses to start at all.
+    expect(parsed.mcpServers.hindsight.env.HINDSIGHT_MCP_HARNESS).toBe("claude-code");
 
     expect(options.cwd).toBe("/repo");
     expect(options.detached).toBe(true);
@@ -110,6 +113,9 @@ describe("startCodebaseSurvey", () => {
     expect(argv).toContain(SURVEY_PROMPT);
     expect(argv).toContain(`mcp_servers.hindsight.command="node"`);
     expect(argv).toContain(`mcp_servers.hindsight.args=["/x/mcp-server.js"]`);
+    // Without this the survey's findings were stamped harness:claude-code and landed in Claude
+    // Code's bank even though Codex ran the survey (#3603).
+    expect(argv).toContain(`mcp_servers.hindsight.env.HINDSIGHT_MCP_HARNESS="codex"`);
     expect(argv).toContain(`mcp_servers.hindsight.env.HINDSIGHT_MCP_PROJECT_CWD="/repo"`);
     // No Claude-only flags leak into the codex recipe.
     expect(argv).not.toContain("--model");

hindsight-integrations/coding-agents/src/core/survey.ts

@@ -205,7 +205,11 @@ function buildSurveyPlan(
           hindsight: {
             command: "node",
             args: [opts.mcpServerPath],
-            env: { HINDSIGHT_MCP_PROJECT_CWD: repoDir },
+            // HINDSIGHT_MCP_HARNESS names the agent whose CLI this recipe drives — the survey's
+            // ingests are its writes. mcp-server.js REQUIRES it (it used to default to
+            // "claude-code", which is how the codex recipe below silently stamped its findings
+            // harness:claude-code and wrote them to Claude Code's bank — #3603).
+            env: { HINDSIGHT_MCP_PROJECT_CWD: repoDir, HINDSIGHT_MCP_HARNESS: "claude-code" },
           },
         },
       });
@@ -250,6 +254,8 @@ function buildSurveyPlan(
           `mcp_servers.hindsight.args=["${opts.mcpServerPath}"]`,
           "-c",
           `mcp_servers.hindsight.env.HINDSIGHT_MCP_PROJECT_CWD="${repoDir}"`,
+          "-c",
+          `mcp_servers.hindsight.env.HINDSIGHT_MCP_HARNESS="codex"`,
           SURVEY_PROMPT,
         ],
         env,

hindsight-integrations/coding-agents/src/installer.test.ts

@@ -1,5 +1,13 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+  existsSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -119,6 +127,10 @@ describe("claude-code installer", () => {
       "--scope",
       "user",
       "hindsight",
+      // Every host launches the same mcp-server.js, so the registration has to name its harness —
+      // otherwise the server falls back to claude-code and mis-attributes the other hosts' writes.
+      "--env",
+      "HINDSIGHT_MCP_HARNESS=claude-code",
       "--",
       "node",
       join(ctx.dist, "mcp-server.js"),
@@ -179,6 +191,7 @@ describe("codex installer", () => {
     expect(toml).toContain("[features]\nhooks = true");
     expect(toml).toContain("[mcp_servers.hindsight]");
     expect(toml).toContain(join(ctx.dist, "mcp-server.js"));
+    expect(toml).toContain('env = { HINDSIGHT_MCP_HARNESS = "codex" }');
   });
 
   it("does NOT duplicate an existing [features] section (only appends mcp) and backs up the toml", () => {
@@ -205,6 +218,25 @@ describe("codex installer", () => {
     expect(toml).toContain("[mcp_servers.hindsight]");
   });
 
+  // Regression: Codex sessions ingested documents tagged `harness:claude-code`. Its registration
+  // carried no HINDSIGHT_MCP_HARNESS, and install skipped whenever a block already existed — so
+  // the stale, harness-less block survived every re-install and the shared mcp-server.js kept
+  // falling back to claude-code for the bank AND the retain stamp.
+  it("re-install REPLACES a harness-less mcp block instead of leaving it stale", () => {
+    const ctx = makeCtx();
+    mkdirSync(join(ctx.home, ".codex"), { recursive: true });
+    writeFileSync(
+      tomlPath(ctx),
+      '[features]\nhooks = true\n\n[mcp_servers.hindsight]\ncommand = "node"\n' +
+        `args = ["${join(ctx.dist, "mcp-server.js")}"]\n\n[ui]\ntheme = "dark"\n`
+    );
+    run(["install", "codex"], ctx);
+    const toml = readFileSync(tomlPath(ctx), "utf8");
+    expect(toml.match(/^\[mcp_servers\.hindsight\]/gm)).toHaveLength(1);
+    expect(toml).toContain('env = { HINDSIGHT_MCP_HARNESS = "codex" }');
+    expect(toml).toContain('[ui]\ntheme = "dark"'); // foreign sections survive the rewrite
+  });
+
   it("uninstall removes the mcp_servers.hindsight block and leaves the rest of the toml", () => {
     const ctx = makeCtx();
     run(["install", "codex"], ctx);
@@ -543,6 +575,7 @@ describe("cursor-cli installer", () => {
     expect(mcp.mcpServers.hindsight).toEqual({
       command: "node",
       args: [join(ctx.dist, "mcp-server.js")],
+      env: { HINDSIGHT_MCP_HARNESS: "cursor-cli" },
     });
   });
 
@@ -585,6 +618,7 @@ describe("grok-build installer", () => {
     expect(config).toContain(join(ctx.dist, "grok-stop-hook.js"));
     expect(config).toContain("[mcp_servers.hindsight]");
     expect(config).toContain(join(ctx.dist, "mcp-server.js"));
+    expect(config).toContain('env = { HINDSIGHT_MCP_HARNESS = "grok-build" }');
     expect(existsSync(join(ctx.home, ".claude"))).toBe(false);
   });
 
@@ -683,6 +717,47 @@ describe("run() CLI behavior", () => {
   });
 });
 
+/**
+ * Every host launches the SAME `dist/mcp-server.js`, so the command line cannot say who is calling
+ * — only `HINDSIGHT_MCP_HARNESS` can. A registration that omits it silently inherits the server's
+ * claude-code fallback, which is how a Codex `hindsight_ingest_document` was stored tagged
+ * `harness:claude-code` on a machine running both (#3603).
+ *
+ * Swept over INSTALLERS rather than a hand-written list of config paths: the harness that gets this
+ * wrong is by construction the one nobody wrote a test for, so the guard has to find the
+ * registration itself — any file the install wrote that names mcp-server.js, wherever it landed.
+ */
+describe("MCP registrations name the calling harness", () => {
+  /** Every file under `dir`, recursively. */
+  function filesUnder(dir: string): string[] {
+    return readdirSync(dir, { withFileTypes: true }).flatMap((e) =>
+      e.isDirectory() ? filesUnder(join(dir, e.name)) : [join(dir, e.name)]
+    );
+  }
+
+  // These hosts have no MCP registration at all: they load our plugin/extension in-process
+  // (src/kilo.ts, src/dsh.ts, src/prime-agent.ts, dist/index.js for opencode), and that entry
+  // hands its own harness name straight to RuntimeCore.
+  const IN_PROCESS = new Set(["opencode", "kilo", "prime-agent", "dsh"]);
+  const MCP_HOSTS = INSTALLERS.map((i) => i.name).filter((n) => !IN_PROCESS.has(n));
+
+  it.each(MCP_HOSTS)("%s", (harness) => {
+    const ctx = makeCtx();
+    expect(run(["install", harness], ctx)).toBe(0);
+    const registrations = [
+      ...filesUnder(ctx.home)
+        .map((f) => readFileSync(f, "utf8"))
+        // claude-code registers through the `claude` CLI instead of a file we write, so its
+        // registration is the argv we handed the mock.
+        .concat(ctx.claudeMcp.mock.calls.map((c) => c[0].join(" ")))
+        .filter((text) => text.includes("mcp-server.js")),
+    ];
+    expect(registrations.length).toBeGreaterThan(0);
+    for (const text of registrations) expect(text).toContain(`HINDSIGHT_MCP_HARNESS`);
+    for (const text of registrations) expect(text).toContain(harness);
+  });
+});
+
 /**
  * `all` is an explicit target rather than the default for a bare command: wiring every detected
  * agent rewrites a lot of a machine's config and should not happen by accident.

hindsight-integrations/coding-agents/src/installer.ts

@@ -144,6 +144,21 @@ const cmdHook = (dist: string, file: string, timeout: number) => ({
   hooks: [{ type: "command", command: `node "${join(dist, file)}"`, timeout }],
 });
 
+/**
+ * The MCP registration for a JSON-configured host.
+ *
+ * Every harness launches the SAME `dist/mcp-server.js`, so the command line alone cannot say who
+ * is calling. `HINDSIGHT_MCP_HARNESS` is what the server reads to answer that; without it it falls
+ * back to "claude-code", which is why a Codex `hindsight_ingest_document` landed tagged
+ * `harness:claude-code` (and derived its bank as Claude Code's) on machines running both. Every
+ * registration MUST name its own harness — pass it here, never rely on the fallback.
+ */
+const mcpServerEntry = (dist: string, harness: HookHarnessName | "cline-cli") => ({
+  command: "node",
+  args: [join(dist, "mcp-server.js")],
+  env: { HINDSIGHT_MCP_HARNESS: harness },
+});
+
 /** Install/uninstall consume the same lifecycle declaration as the runtime entrypoints. Keeping
  * event names and command files here would allow a host to run a different lifecycle than it installs. */
 function mergeHarnessHooks(
@@ -369,6 +384,8 @@ const claudeCode: HarnessInstaller = {
         "--scope",
         "user",
         "hindsight",
+        "--env",
+        "HINDSIGHT_MCP_HARNESS=claude-code",
         "--",
         "node",
         join(c.dist, "mcp-server.js"),
@@ -378,7 +395,7 @@ const claudeCode: HarnessInstaller = {
     } else {
       c.log?.(
         `claude-code: could not run \`claude mcp add\` — register the tools manually:\n` +
-          `  claude mcp add --scope user hindsight -- node "${join(c.dist, "mcp-server.js")}"`
+          `  claude mcp add --scope user hindsight --env HINDSIGHT_MCP_HARNESS=claude-code -- node "${join(c.dist, "mcp-server.js")}"`
       );
     }
   },
@@ -408,6 +425,17 @@ function defaultClaudeMcp(args: string[]): boolean {
   }
 }
 
+/**
+ * Our `[mcp_servers.hindsight]` table (plus any sub-table of it): the header line through to the
+ * next table header or EOF. Shared by install — which REPLACES the block — and uninstall.
+ */
+const CODEX_MCP_BLOCK_RE = /^\[mcp_servers\.hindsight(?:\.[^\]]+)?\][^\n]*\n(?:(?!\[)[^\n]*\n?)*/gm;
+
+/** Inline `env`, so CODEX_MCP_BLOCK_RE never has to straddle a `[mcp_servers.hindsight.env]` table. */
+const codexMcpBlock = (dist: string) =>
+  `[mcp_servers.hindsight]\ncommand = "node"\nargs = [${JSON.stringify(join(dist, "mcp-server.js"))}]\n` +
+  `env = { HINDSIGHT_MCP_HARNESS = "codex" }`;
+
 const codex: HarnessInstaller = {
   name: "codex",
   detect: (c) => onPath("codex") || existsSync(join(c.home, ".codex")),
@@ -419,9 +447,13 @@ const codex: HarnessInstaller = {
     writeJson(hooksPath, cfg);
     c.log?.(`codex: hooks merged into ${hooksPath}`);
 
-    // config.toml: append-only, never rewrite (TOML round-tripping is not worth the risk).
+    // config.toml: append-only for anything that is not ours (TOML round-tripping is not worth the
+    // risk). Our OWN mcp block is stripped and rewritten instead of skipped when present: appending
+    // only when absent made this install-once-only, so the harness-less registration that
+    // attributed every Codex write to claude-code could never be repaired by re-running install.
     const tomlPath = join(c.home, ".codex", "config.toml");
-    let toml = existsSync(tomlPath) ? readFileSync(tomlPath, "utf8") : "";
+    const existing = existsSync(tomlPath) ? readFileSync(tomlPath, "utf8") : "";
+    const toml = existing.replace(CODEX_MCP_BLOCK_RE, "");
     const additions: string[] = [];
     // Codex ≥ 0.145 deprecates `codex_hooks` for `[features].hooks`; accept either as "already
     // enabled", write the modern name for new installs.
@@ -434,18 +466,15 @@ const codex: HarnessInstaller = {
         additions.push("[features]\nhooks = true");
       }
     }
-    if (!toml.includes("[mcp_servers.hindsight]")) {
-      additions.push(
-        `[mcp_servers.hindsight]\ncommand = "node"\nargs = ["${join(c.dist, "mcp-server.js")}"]`
-      );
-    }
-    if (additions.length) {
+    additions.push(codexMcpBlock(c.dist));
+    const next = `${toml.replace(/\n*$/, "\n\n")}${additions.join("\n\n")}\n`;
+    if (next !== existing) {
       if (existsSync(tomlPath) && !existsSync(`${tomlPath}.hindsight-backup`)) {
         copyFileSync(tomlPath, `${tomlPath}.hindsight-backup`);
       }
       mkdirSync(dirname(tomlPath), { recursive: true });
-      writeFileSync(tomlPath, `${toml.replace(/\n*$/, "\n\n")}${additions.join("\n\n")}\n`);
-      c.log?.(`codex: appended ${additions.length} section(s) to ${tomlPath}`);
+      writeFileSync(tomlPath, next);
+      c.log?.(`codex: wrote ${additions.length} section(s) to ${tomlPath}`);
     }
     installSkill(c, "codex", join(c.home, ".agents", "skills")); // agentskills-standard shared dir
   },
@@ -462,10 +491,7 @@ const codex: HarnessInstaller = {
     const tomlPath = join(c.home, ".codex", "config.toml");
     if (existsSync(tomlPath)) {
       const toml = readFileSync(tomlPath, "utf8");
-      const cleaned = toml.replace(
-        /\n?\[mcp_servers\.hindsight\]\ncommand = "node"\nargs = \[[^\]]*\]\n?/g,
-        "\n"
-      );
+      const cleaned = toml.replace(CODEX_MCP_BLOCK_RE, "");
       if (cleaned !== toml) writeFileSync(tomlPath, cleaned);
     }
     c.log?.(
@@ -505,11 +531,7 @@ const antigravity: HarnessInstaller = {
     const mcp = readJson(mcpPath);
     mcp.mcpServers = {
       ...(mcp.mcpServers ?? {}),
-      hindsight: {
-        command: "node",
-        args: [join(c.dist, "mcp-server.js")],
-        env: { HINDSIGHT_MCP_HARNESS: "antigravity-cli" },
-      },
+      hindsight: mcpServerEntry(c.dist, "antigravity-cli"),
     };
     writeJson(mcpPath, mcp);
     const settingsPath = join(c.home, ".gemini", "antigravity-cli", "settings.json");
@@ -915,11 +937,7 @@ const devin: HarnessInstaller = {
     const mcp = readJson(mcpPath);
     mcp.mcpServers = {
       ...(mcp.mcpServers ?? {}),
-      hindsight: {
-        command: "node",
-        args: [join(c.dist, "mcp-server.js")],
-        env: { HINDSIGHT_MCP_HARNESS: "devin-cli" },
-      },
+      hindsight: mcpServerEntry(c.dist, "devin-cli"),
     };
     writeJson(mcpPath, mcp);
     c.log?.(`devin-cli: hooks merged into ${configPath}, MCP into ${mcpPath}`);
@@ -959,7 +977,7 @@ const cursor: HarnessInstaller = {
     const mcp = readJson(mcpPath);
     mcp.mcpServers = {
       ...(mcp.mcpServers ?? {}),
-      hindsight: { command: "node", args: [join(c.dist, "mcp-server.js")] },
+      hindsight: mcpServerEntry(c.dist, "cursor-cli"),
     };
     writeJson(mcpPath, mcp);
     c.log?.(`cursor-cli: hooks merged into ${hooksPath}, MCP into ${mcpPath}`);
@@ -1001,7 +1019,7 @@ const copilot: HarnessInstaller = {
     const mcp = readJson(mcpPath);
     mcp.mcpServers = {
       ...(mcp.mcpServers ?? {}),
-      hindsight: { command: "node", args: [join(c.dist, "mcp-server.js")] },
+      hindsight: mcpServerEntry(c.dist, "copilot-cli"),
     };
     writeJson(mcpPath, mcp);
     installSkill(c, "copilot-cli", join(c.home, ".copilot", "skills"));
@@ -1048,7 +1066,8 @@ const grok: HarnessInstaller = {
       `[[hooks.SessionStart]]\n  [[hooks.SessionStart.hooks]]\n  type = \"command\"\n  command = ${command("grok-sessionstart-hook.js")}\n  timeout = 30\n\n` +
       `[[hooks.UserPromptSubmit]]\n  [[hooks.UserPromptSubmit.hooks]]\n  type = \"command\"\n  command = ${command("grok-hook.js")}\n  timeout = 30\n\n` +
       `[[hooks.Stop]]\n  [[hooks.Stop.hooks]]\n  type = \"command\"\n  command = ${command("grok-stop-hook.js")}\n  timeout = 60\n\n` +
-      `[mcp_servers.hindsight]\ncommand = \"node\"\nargs = [${tomlString(join(c.dist, "mcp-server.js"))}]\n${GROK_MARKER_END}\n`;
+      `[mcp_servers.hindsight]\ncommand = \"node\"\nargs = [${tomlString(join(c.dist, "mcp-server.js"))}]\n` +
+      `env = { HINDSIGHT_MCP_HARNESS = \"grok-build\" }\n${GROK_MARKER_END}\n`;
     if (existsSync(path) && !existsSync(`${path}.hindsight-backup`))
       copyFileSync(path, `${path}.hindsight-backup`);
     mkdirSync(dirname(path), { recursive: true });
@@ -1099,11 +1118,7 @@ const cline: HarnessInstaller = {
     const mcp = readJson(mcpPath);
     mcp.mcpServers = {
       ...(mcp.mcpServers ?? {}),
-      hindsight: {
-        command: "node",
-        args: [join(c.dist, "mcp-server.js")],
-        env: { HINDSIGHT_MCP_HARNESS: "cline-cli" },
-      },
+      hindsight: mcpServerEntry(c.dist, "cline-cli"),
     };
     writeJson(mcpPath, mcp);
     installSkill(c, "cline-cli", join(c.home, ".cline", "data", "settings", "skills"));