@haven_ai/connect 0.0.0-dev.202609031523.fd49e1a → 0.0.0-dev.202609031608.fceb089

package/README.md

@@ -377,7 +377,9 @@ npx @haven_ai/connect@alpha --doctor --repair --runtime codex-desktop
 ```
 
 `--doctor` is read-only and needs NO setup token: it checks the runtime config,
-the agent credential files, the pinned signer runtime install, the hosted MCP
+the agent credential files, the pinned signer runtime install (and, since
+#2424, whether that install was made under a local runtime-spec override —
+see the last section of this file), the hosted MCP
 (authorized `tools/list`), and starts the local signer for a real stdio
 handshake — reporting its advertised compat versions. Every failing check
 prints one concrete repair action; the exit code is non-zero on any failure.
@@ -404,3 +406,75 @@ which.
 `--repair` re-runs what setup already owns — reinstall the pinned signer
 runtime, rewrite the wrapper + sidecar, and re-write the runtime config from
 the STORED credentials. It never touches keys and never needs a new token.
+
+## Installing an unpublished signer / SDK / MCP build (`HAVEN_SIGNER_SPEC`, #2424)
+
+Setup installs the connector's **pinned** siblings — `@haven_ai/signer@<pin>`
+and `@haven_ai/sdk@<pin>` into `~/.haven/signer-runtime/<pin>`, and for
+`--local` also `@haven_ai/mcp@<pin>` into `~/.haven/mcp-runtime/<pin>`. That
+is right for every user and wrong for the one developer iterating on the
+signer or SDK, who otherwise has to publish to find out whether a change works
+end to end. Three environment variables name a different spec:
+
+| Variable | Replaces | Read by |
+|---|---|---|
+| `HAVEN_SIGNER_SPEC` | `@haven_ai/signer@<pin>` | the signer runtime (default topology) |
+| `HAVEN_SDK_SPEC` | `@haven_ai/sdk@<pin>` | both runtimes — each installs the SDK |
+| `HAVEN_MCP_SPEC` | `@haven_ai/mcp@<pin>` | the `--local` MCP runtime |
+
+A value is anything `npm install` accepts for that package: a checkout
+(`file:/abs/path/to/packages/signer`), a tarball from `npm pack`
+(`/abs/haven_ai-signer-0.0.0.tgz`), or an explicit version
+(`@haven_ai/signer@<version>`). Set it in the shell that runs the setup
+command — the command itself is unchanged:
+
+```bash
+HAVEN_SIGNER_SPEC=file:$PWD/packages/signer npx @haven_ai/connect@alpha --setup <token> --runtime claude-code
+```
+
+Environment variables rather than a flag, deliberately: the install runs from
+three entry points (`--setup`, `--doctor --repair`, `--rekey-finish`) and all
+three honour the same variables, so a re-key cannot silently reinstall the
+registry build; and the setup command is minted by the dashboard and pasted
+verbatim, often by an agent, so the override sits beside it instead of being
+spliced into a line the developer did not write.
+
+**What an active override changes:**
+
+- The runtime directory is `~/.haven/signer-runtime/override-<hash>` (or
+  `mcp-runtime/override-<hash>`), keyed by a short hash of the **resolved**
+  specs — overridden and pinned alike — so it can never poison the
+  version-named directory the normal path reuses, and a pinned-sibling bump
+  gets a fresh one.
+- The install is **never reused** from an earlier run: a rebuilt `file:`
+  package must not be shadowed by a cache hit.
+- Setup prints `RUNTIME SPEC OVERRIDE ACTIVE …` first, naming each variable
+  and the pin it replaced; `--rekey-finish` prints the same line.
+- `signer-runtime.json` / `mcp-runtime.json` record the override under
+  `runtime_spec_override`, and their `*_version` fields hold what npm actually
+  installed rather than the manifest pins.
+- The wrapper the agent client launches carries a
+  `// HAVEN RUNTIME SPEC OVERRIDE (#2424): …` comment.
+- `--doctor` reports a failing `runtime_spec_override` check — "runtime spec
+  overridden — not the pinned manifest" — whenever the sidecar says the
+  install ran under one **or** a `HAVEN_*_SPEC` variable is set in the shell
+  running the doctor (a `--repair` from that shell would install it). The
+  override is legitimate; the finding is its record. Under an override the
+  `signer_runtime` check compares the directory against the sidecar's own
+  record, not the manifest.
+
+**What it never changes:** the post-setup handshake probe still requires
+every tool in the manifest's `requiredTools` / `requiredSignerTools`, so a
+local build that dropped a tool fails setup exactly like a bad registry
+version would. A set-but-malformed value — empty, containing whitespace or a
+shell metacharacter — is refused **before** npm runs and before anything is
+written, with a message naming the variable. With no variable set, nothing
+here runs: the install arguments, directory, sidecar and wrapper are
+byte-for-byte what they were before the override existed (pinned by exact
+characterization tests in `signer-runtime.test.ts` and
+`local-mcp-runtime.test.ts`).
+
+To return to the pinned manifest: unset the variables and run
+`--doctor --repair --runtime <runtime>` (or re-run setup). The override
+directories live under `~/.haven` like every other runtime directory, so the
+same reset that removes `~/.haven` removes them.

package/dist/cli.cjs

@@ -535,9 +535,9 @@ var init_runtime_manifest = __esm({
       mcpPackage: "@haven_ai/mcp",
       mcpVersion: mcp.MCP_VERSION,
       sdkPackage: "@haven_ai/sdk",
-      sdkVersion: "0.0.0-dev.202609031523.fd49e1a",
+      sdkVersion: "0.0.0-dev.202609031608.fceb089",
       signerPackage: "@haven_ai/signer",
-      signerVersion: "0.0.0-dev.202609031523.fd49e1a",
+      signerVersion: "0.0.0-dev.202609031608.fceb089",
       // Sourced from the SDK, never a literal (#1161). This field read '20.0.0'
       // while every package's `engines` said `>=24` and the docs said `>=24.0.0`,
       // so the guard that was supposed to enforce the floor waved Node v23 through
@@ -1608,32 +1608,129 @@ var init_probes = __esm({
   "src/probes.ts"() {
   }
 });
+function resolveRuntimeSpecOverride(env) {
+  const override = {};
+  for (const pkg of Object.keys(RUNTIME_SPEC_ENV)) {
+    const variable = RUNTIME_SPEC_ENV[pkg];
+    const raw = env[variable];
+    if (raw === void 0) continue;
+    override[pkg] = validateSpec(variable, raw);
+  }
+  return Object.keys(override).length > 0 ? override : void 0;
+}
+function validateSpec(variable, raw) {
+  if (raw.length === 0 || raw.trim().length === 0) {
+    throw new RuntimeSpecOverrideError(variable, "it is empty");
+  }
+  if (/\s/.test(raw)) {
+    throw new RuntimeSpecOverrideError(variable, "it contains whitespace");
+  }
+  if (/[\u0000-\u001f\u007f]/.test(raw)) {
+    throw new RuntimeSpecOverrideError(variable, "it contains a control character");
+  }
+  const meta = SHELL_METACHARACTERS.exec(raw);
+  if (meta) {
+    throw new RuntimeSpecOverrideError(variable, `it contains the shell metacharacter ${JSON.stringify(meta[0])}`);
+  }
+  return raw;
+}
+function runtimeSpecOverrideDirectoryKey(resolvedSpecs) {
+  const digest = crypto.createHash("sha256").update(resolvedSpecs.join("\n")).digest("hex");
+  return `override-${digest.slice(0, 12)}`;
+}
+function overrideApplies(override, packages) {
+  return override !== void 0 && packages.some((pkg) => override[pkg] !== void 0);
+}
+function runtimeSpecOverrideNotice(runtimeLabel, override, pinned, runtimeDirectory) {
+  const lines = [`RUNTIME SPEC OVERRIDE ACTIVE for the local Haven ${runtimeLabel} \u2014 this is NOT the pinned manifest.`];
+  for (const pkg of Object.keys(RUNTIME_SPEC_ENV)) {
+    const spec = override[pkg];
+    if (spec === void 0) continue;
+    const pin = pinned[pkg];
+    lines.push(`  ${RUNTIME_SPEC_ENV[pkg]}=${spec}${pin ? ` (instead of ${pin})` : ""}`);
+  }
+  lines.push(`  Installing into ${runtimeDirectory} \u2014 the pinned runtime directory is untouched.`);
+  lines.push("  Unset the variable(s) and re-run to return to the pinned manifest.");
+  return lines;
+}
+function describeRuntimeSpecOverride(override) {
+  return Object.keys(RUNTIME_SPEC_ENV).filter((pkg) => override[pkg] !== void 0).map((pkg) => `${RUNTIME_SPEC_ENV[pkg]}=${override[pkg]}`).join(" ");
+}
+var RUNTIME_SPEC_ENV, SHELL_METACHARACTERS, RuntimeSpecOverrideError;
+var init_runtime_spec_override = __esm({
+  "src/runtime-spec-override.ts"() {
+    RUNTIME_SPEC_ENV = {
+      signer: "HAVEN_SIGNER_SPEC",
+      sdk: "HAVEN_SDK_SPEC",
+      mcp: "HAVEN_MCP_SPEC"
+    };
+    SHELL_METACHARACTERS = /[;&|<>$`'"()!#*?[\]{}\\]/;
+    RuntimeSpecOverrideError = class extends Error {
+      code = "runtime_spec_override_invalid";
+      variable;
+      constructor(variable, reason) {
+        super(`${variable} is set but not usable as an npm package spec: ${reason}. Unset it, or set it to a spec npm install accepts (file:/abs/path, a .tgz, or @haven_ai/<pkg>@<version>).`);
+        this.name = "RuntimeSpecOverrideError";
+        this.variable = variable;
+      }
+    };
+  }
+});
 async function prepareSignerRuntime(input, deps = {}) {
   const homeDir = input.homeDir ?? os.homedir();
-  const runtimeDirectory = path.resolve(homeDir, ".haven", "signer-runtime", MCP_RUNTIME_MANIFEST.signerVersion);
+  const override = resolveSignerRuntimeOverride(deps.env ?? process.env);
+  const signerSpec = override?.signer ?? signerPackageSpec();
+  const sdkSpec = override?.sdk ?? sdkPackageSpec();
+  const resolvedSpecs = [signerSpec, sdkSpec];
+  const overrideRecord = override ? { specs: override, resolved_specs: resolvedSpecs, directory_key: runtimeSpecOverrideDirectoryKey(resolvedSpecs) } : void 0;
+  const runtimeDirectory = path.resolve(
+    homeDir,
+    ".haven",
+    "signer-runtime",
+    overrideRecord ? overrideRecord.directory_key : MCP_RUNTIME_MANIFEST.signerVersion
+  );
   const npmCacheDirectory = path.resolve(homeDir, ".haven", "npm-cache");
   const cliPath = path.join(runtimeDirectory, "node_modules", "@haven_ai", "signer", "dist", "cli.js");
   const messages = [];
+  if (override) {
+    messages.push(...runtimeSpecOverrideNotice(
+      "signer runtime",
+      override,
+      { signer: signerPackageSpec(), sdk: sdkPackageSpec() },
+      runtimeDirectory
+    ));
+  }
   await promises.mkdir(runtimeDirectory, { recursive: true, mode: 448 });
   await promises.chmod(runtimeDirectory, 448).catch(() => void 0);
   await promises.mkdir(npmCacheDirectory, { recursive: true, mode: 448 });
   await promises.chmod(npmCacheDirectory, 448).catch(() => void 0);
-  if (await installedRuntimeMatches(runtimeDirectory, cliPath)) {
+  if (override) {
+    await installRuntimePackages(runtimeDirectory, npmCacheDirectory, resolvedSpecs, deps);
+    messages.push(`Installed local Haven signer runtime from override (${resolvedSpecs.join(" ")}).`);
+  } else if (await installedRuntimeMatches(runtimeDirectory, cliPath)) {
     messages.push(`Using existing local Haven signer runtime ${signerPackageSpec()}.`);
   } else {
-    await installRuntimePackages(runtimeDirectory, npmCacheDirectory, deps);
+    await installRuntimePackages(runtimeDirectory, npmCacheDirectory, resolvedSpecs, deps);
     messages.push(`Installed local Haven signer runtime ${signerPackageSpec()}.`);
   }
   await assertFileExists(cliPath, "local Haven signer CLI");
+  const installedVersions = override ? await readInstalledVersions(runtimeDirectory) : void 0;
   const wrapperPath = path.join(input.credentialDirectory, "bin", "haven-signer.mjs");
-  await writeWrapper({ wrapperPath, cliPath, signerPath: input.signerPath });
+  await writeWrapper({
+    wrapperPath,
+    cliPath,
+    signerPath: input.signerPath,
+    overrideComment: override ? describeRuntimeSpecOverride(override) : void 0
+  });
   await writeRuntimeSidecar({
     path: path.join(input.credentialDirectory, "signer-runtime.json"),
     wrapperPath,
     runtimeDirectory,
     npmCacheDirectory,
     cliPath,
-    serverName: input.serverName
+    serverName: input.serverName,
+    override: overrideRecord,
+    installedVersions
   });
   messages.push(`Prepared stable local Haven signer wrapper: ${wrapperPath}`);
   return {
@@ -1643,10 +1740,17 @@ async function prepareSignerRuntime(input, deps = {}) {
     runtimeDirectory,
     npmCacheDirectory,
     cliPath,
-    messages
+    messages,
+    ...overrideRecord ? { runtimeSpecOverride: overrideRecord } : {}
   };
 }
-async function installRuntimePackages(runtimeDirectory, npmCacheDirectory, deps) {
+function resolveSignerRuntimeOverride(env) {
+  const override = resolveRuntimeSpecOverride(env);
+  if (!overrideApplies(override, ["signer", "sdk"])) return void 0;
+  const { signer, sdk } = override;
+  return { ...signer !== void 0 ? { signer } : {}, ...sdk !== void 0 ? { sdk } : {} };
+}
+async function installRuntimePackages(runtimeDirectory, npmCacheDirectory, packageSpecs, deps) {
   const { runCommand, onProgress } = deps;
   const baseArgs = [
     "install",
@@ -1656,8 +1760,7 @@ async function installRuntimePackages(runtimeDirectory, npmCacheDirectory, deps)
     "--no-fund",
     "--omit=dev",
     "--prefer-offline",
-    signerPackageSpec(),
-    sdkPackageSpec()
+    ...packageSpecs
   ];
   const run = async (args) => {
     const startedAt = Date.now();
@@ -1680,23 +1783,33 @@ async function installRuntimePackages(runtimeDirectory, npmCacheDirectory, deps)
       await run([...baseArgs, "--cache", npmCacheDirectory]);
     } catch (err) {
       throw new Error(
-        `Could not install local Haven signer runtime ${signerPackageSpec()}: ${err instanceof Error ? err.message : String(err)}`
+        `Could not install local Haven signer runtime ${packageSpecs.join(" ")}: ${err instanceof Error ? err.message : String(err)}`
       );
     }
   }
 }
 async function installedRuntimeMatches(runtimeDirectory, cliPath) {
+  return installedRuntimeMatchesVersions(runtimeDirectory, cliPath, {
+    signerVersion: MCP_RUNTIME_MANIFEST.signerVersion,
+    sdkVersion: MCP_RUNTIME_MANIFEST.sdkVersion
+  });
+}
+async function installedRuntimeMatchesVersions(runtimeDirectory, cliPath, expected) {
   try {
     await assertFileExists(cliPath, "local Haven signer CLI");
-    const [signerPackage, sdkPackage] = await Promise.all([
-      readPackageJson(path.join(runtimeDirectory, "node_modules", "@haven_ai", "signer", "package.json")),
-      readPackageJson(path.join(runtimeDirectory, "node_modules", "@haven_ai", "sdk", "package.json"))
-    ]);
-    return signerPackage.version === MCP_RUNTIME_MANIFEST.signerVersion && sdkPackage.version === MCP_RUNTIME_MANIFEST.sdkVersion;
+    const installed = await readInstalledVersions(runtimeDirectory);
+    return installed.signerVersion === expected.signerVersion && installed.sdkVersion === expected.sdkVersion;
   } catch {
     return false;
   }
 }
+async function readInstalledVersions(runtimeDirectory) {
+  const [signerPackage, sdkPackage] = await Promise.all([
+    readPackageJson(path.join(runtimeDirectory, "node_modules", "@haven_ai", "signer", "package.json")),
+    readPackageJson(path.join(runtimeDirectory, "node_modules", "@haven_ai", "sdk", "package.json"))
+  ]);
+  return { signerVersion: signerPackage.version ?? "", sdkVersion: sdkPackage.version ?? "" };
+}
 async function readPackageJson(path) {
   return JSON.parse(await promises.readFile(path, "utf8"));
 }
@@ -1705,6 +1818,7 @@ async function writeWrapper(input) {
   await promises.chmod(path.dirname(input.wrapperPath), 448).catch(() => void 0);
   const source = [
     "#!/usr/bin/env node",
+    ...input.overrideComment ? [`// HAVEN RUNTIME SPEC OVERRIDE (#2424): ${input.overrideComment} \u2014 this wrapper launches a NON-pinned signer build.`] : [],
     "import { spawn } from 'node:child_process'",
     "",
     `const cliPath = ${JSON.stringify(input.cliPath)}`,
@@ -1736,13 +1850,14 @@ async function writeRuntimeSidecar(input) {
   const value = {
     ...input.serverName ? { server_name: input.serverName } : {},
     signer_package: MCP_RUNTIME_MANIFEST.signerPackage,
-    signer_version: MCP_RUNTIME_MANIFEST.signerVersion,
+    signer_version: input.installedVersions?.signerVersion ?? MCP_RUNTIME_MANIFEST.signerVersion,
     sdk_package: MCP_RUNTIME_MANIFEST.sdkPackage,
-    sdk_version: MCP_RUNTIME_MANIFEST.sdkVersion,
+    sdk_version: input.installedVersions?.sdkVersion ?? MCP_RUNTIME_MANIFEST.sdkVersion,
     wrapper_path: input.wrapperPath,
     runtime_directory: input.runtimeDirectory,
     npm_cache_directory: input.npmCacheDirectory,
-    cli_path: input.cliPath
+    cli_path: input.cliPath,
+    ...input.override ? { runtime_spec_override: input.override } : {}
   };
   await promises.writeFile(input.path, `${JSON.stringify(value, null, 2)}
 `, { mode: 384 });
@@ -1759,6 +1874,7 @@ var execFileAsync, SIGNER_INSTALL_TIMEOUT_MS, SIGNER_INSTALL_HEARTBEAT_MS;
 var init_signer_runtime = __esm({
   "src/signer-runtime.ts"() {
     init_runtime_manifest();
+    init_runtime_spec_override();
     execFileAsync = util.promisify(child_process.execFile);
     SIGNER_INSTALL_TIMEOUT_MS = 6e5;
     SIGNER_INSTALL_HEARTBEAT_MS = 15e3;
@@ -1767,27 +1883,50 @@ var init_signer_runtime = __esm({
 async function prepareLocalMcpRuntime(input, deps = {}) {
   assertSupportedNodeVersion(input.nodeVersion);
   const homeDir = input.homeDir ?? os.homedir();
-  const runtimeDirectory = path.resolve(homeDir, ".haven", "mcp-runtime", MCP_RUNTIME_MANIFEST.mcpVersion);
+  const override = resolveLocalMcpRuntimeOverride(deps.env ?? process.env);
+  const mcpSpec = override?.mcp ?? mcpPackageSpec();
+  const sdkSpec = override?.sdk ?? sdkPackageSpec();
+  const resolvedSpecs = [mcpSpec, sdkSpec];
+  const overrideRecord = override ? { specs: override, resolved_specs: resolvedSpecs, directory_key: runtimeSpecOverrideDirectoryKey(resolvedSpecs) } : void 0;
+  const runtimeDirectory = path.resolve(
+    homeDir,
+    ".haven",
+    "mcp-runtime",
+    overrideRecord ? overrideRecord.directory_key : MCP_RUNTIME_MANIFEST.mcpVersion
+  );
   const npmCacheDirectory = path.resolve(homeDir, ".haven", "npm-cache");
   const cliPath = path.join(runtimeDirectory, "node_modules", "@haven_ai", "mcp", "dist", "cli.js");
   const messages = [];
+  if (override) {
+    messages.push(...runtimeSpecOverrideNotice(
+      "MCP runtime",
+      override,
+      { mcp: mcpPackageSpec(), sdk: sdkPackageSpec() },
+      runtimeDirectory
+    ));
+  }
   await promises.mkdir(runtimeDirectory, { recursive: true, mode: 448 });
   await promises.chmod(runtimeDirectory, 448).catch(() => void 0);
   await promises.mkdir(npmCacheDirectory, { recursive: true, mode: 448 });
   await promises.chmod(npmCacheDirectory, 448).catch(() => void 0);
-  if (await installedRuntimeMatches2(runtimeDirectory, cliPath)) {
+  if (override) {
+    await installRuntimePackages2(runtimeDirectory, npmCacheDirectory, resolvedSpecs, deps);
+    messages.push(`Installed local Haven MCP runtime from override (${resolvedSpecs.join(" ")}).`);
+  } else if (await installedRuntimeMatches2(runtimeDirectory, cliPath)) {
     messages.push(`Using existing local Haven MCP runtime ${mcpPackageSpec()}.`);
   } else {
-    await installRuntimePackages2(runtimeDirectory, npmCacheDirectory, deps);
+    await installRuntimePackages2(runtimeDirectory, npmCacheDirectory, resolvedSpecs, deps);
     messages.push(`Installed local Haven MCP runtime ${mcpPackageSpec()}.`);
   }
   await assertFileExists2(cliPath, "local Haven MCP CLI");
+  const installedVersions = override ? await readInstalledVersions2(runtimeDirectory) : void 0;
   const wrapperPath = path.join(input.credentialDirectory, "bin", "haven-mcp");
   await writeWrapper2({
     wrapperPath,
     cliPath,
     identityPath: input.identityPath,
-    signerPath: input.signerPath
+    signerPath: input.signerPath,
+    overrideComment: override ? describeRuntimeSpecOverride(override) : void 0
   });
   await writeRuntimeSidecar2({
     path: path.join(input.credentialDirectory, "mcp-runtime.json"),
@@ -1795,7 +1934,9 @@ async function prepareLocalMcpRuntime(input, deps = {}) {
     runtimeDirectory,
     npmCacheDirectory,
     cliPath,
-    serverName: input.serverName
+    serverName: input.serverName,
+    override: overrideRecord,
+    installedVersions
   });
   messages.push(`Prepared stable local Haven MCP wrapper: ${wrapperPath}`);
   return {
@@ -1805,7 +1946,8 @@ async function prepareLocalMcpRuntime(input, deps = {}) {
     runtimeDirectory,
     npmCacheDirectory,
     cliPath,
-    messages
+    messages,
+    ...overrideRecord ? { runtimeSpecOverride: overrideRecord } : {}
   };
 }
 function assertSupportedNodeVersion(nodeVersion = process.versions.node, minimumNodeVersion = MCP_RUNTIME_MANIFEST.minimumNodeVersion, subject = "Haven setup") {
@@ -1813,7 +1955,13 @@ function assertSupportedNodeVersion(nodeVersion = process.versions.node, minimum
     throw new UnsupportedNodeVersionError(nodeVersion, minimumNodeVersion, subject);
   }
 }
-async function installRuntimePackages2(runtimeDirectory, npmCacheDirectory, deps) {
+function resolveLocalMcpRuntimeOverride(env) {
+  const override = resolveRuntimeSpecOverride(env);
+  if (!overrideApplies(override, ["mcp", "sdk"])) return void 0;
+  const { mcp, sdk } = override;
+  return { ...mcp !== void 0 ? { mcp } : {}, ...sdk !== void 0 ? { sdk } : {} };
+}
+async function installRuntimePackages2(runtimeDirectory, npmCacheDirectory, packageSpecs, deps) {
   const { runCommand, onProgress } = deps;
   const baseArgs = [
     "install",
@@ -1823,8 +1971,7 @@ async function installRuntimePackages2(runtimeDirectory, npmCacheDirectory, deps
     "--no-fund",
     "--omit=dev",
     "--prefer-offline",
-    mcpPackageSpec(),
-    sdkPackageSpec()
+    ...packageSpecs
   ];
   const run = async (args) => {
     const startedAt = Date.now();
@@ -1846,22 +1993,26 @@ async function installRuntimePackages2(runtimeDirectory, npmCacheDirectory, deps
     try {
       await run([...baseArgs, "--cache", npmCacheDirectory]);
     } catch (err) {
-      throw new Error(`Could not install local Haven MCP runtime ${mcpPackageSpec()}: ${err instanceof Error ? err.message : String(err)}`);
+      throw new Error(`Could not install local Haven MCP runtime ${packageSpecs.join(" ")}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
 }
 async function installedRuntimeMatches2(runtimeDirectory, cliPath) {
   try {
     await assertFileExists2(cliPath, "local Haven MCP CLI");
-    const [mcpPackage, sdkPackage] = await Promise.all([
-      readPackageJson2(path.join(runtimeDirectory, "node_modules", "@haven_ai", "mcp", "package.json")),
-      readPackageJson2(path.join(runtimeDirectory, "node_modules", "@haven_ai", "sdk", "package.json"))
-    ]);
-    return mcpPackage.version === MCP_RUNTIME_MANIFEST.mcpVersion && sdkPackage.version === MCP_RUNTIME_MANIFEST.sdkVersion;
+    const installed = await readInstalledVersions2(runtimeDirectory);
+    return installed.mcpVersion === MCP_RUNTIME_MANIFEST.mcpVersion && installed.sdkVersion === MCP_RUNTIME_MANIFEST.sdkVersion;
   } catch {
     return false;
   }
 }
+async function readInstalledVersions2(runtimeDirectory) {
+  const [mcpPackage, sdkPackage] = await Promise.all([
+    readPackageJson2(path.join(runtimeDirectory, "node_modules", "@haven_ai", "mcp", "package.json")),
+    readPackageJson2(path.join(runtimeDirectory, "node_modules", "@haven_ai", "sdk", "package.json"))
+  ]);
+  return { mcpVersion: mcpPackage.version ?? "", sdkVersion: sdkPackage.version ?? "" };
+}
 async function readPackageJson2(path) {
   return JSON.parse(await promises.readFile(path, "utf8"));
 }
@@ -1870,6 +2021,7 @@ async function writeWrapper2(input) {
   await promises.chmod(path.dirname(input.wrapperPath), 448).catch(() => void 0);
   const source = [
     "#!/usr/bin/env node",
+    ...input.overrideComment ? [`// HAVEN RUNTIME SPEC OVERRIDE (#2424): ${input.overrideComment} \u2014 this wrapper launches a NON-pinned MCP build.`] : [],
     "import { spawn } from 'node:child_process'",
     "",
     `const cliPath = ${JSON.stringify(input.cliPath)}`,
@@ -1893,14 +2045,15 @@ async function writeRuntimeSidecar2(input) {
   const value = {
     ...input.serverName ? { server_name: input.serverName } : {},
     mcp_package: MCP_RUNTIME_MANIFEST.mcpPackage,
-    mcp_version: MCP_RUNTIME_MANIFEST.mcpVersion,
+    mcp_version: input.installedVersions?.mcpVersion ?? MCP_RUNTIME_MANIFEST.mcpVersion,
     sdk_package: MCP_RUNTIME_MANIFEST.sdkPackage,
-    sdk_version: MCP_RUNTIME_MANIFEST.sdkVersion,
+    sdk_version: input.installedVersions?.sdkVersion ?? MCP_RUNTIME_MANIFEST.sdkVersion,
     minimum_node_version: MCP_RUNTIME_MANIFEST.minimumNodeVersion,
     wrapper_path: input.wrapperPath,
     runtime_directory: input.runtimeDirectory,
     npm_cache_directory: input.npmCacheDirectory,
-    cli_path: input.cliPath
+    cli_path: input.cliPath,
+    ...input.override ? { runtime_spec_override: input.override } : {}
   };
   await promises.writeFile(input.path, `${JSON.stringify(value, null, 2)}
 `, { mode: 384 });
@@ -1918,6 +2071,7 @@ var init_local_mcp_runtime = __esm({
   "src/local-mcp-runtime.ts"() {
     init_signer_runtime();
     init_runtime_manifest();
+    init_runtime_spec_override();
     execFileAsync2 = util.promisify(child_process.execFile);
     UnsupportedNodeVersionError = class extends Error {
       code = "local_mcp_unsupported_node_version";
@@ -2704,7 +2858,7 @@ function supportsLocalMcp(runtime) {
   return runtime === "codex-cli" || runtime === "codex-desktop" || runtime === "claude-code";
 }
 async function prepareRuntimeForLocalMcp(input, deps) {
-  const prepare = deps.prepareLocalMcpRuntime ?? ((runtimeInput) => prepareLocalMcpRuntime(runtimeInput, { runCommand: deps.runCommand, onProgress: deps.onProgress }));
+  const prepare = deps.prepareLocalMcpRuntime ?? ((runtimeInput) => prepareLocalMcpRuntime(runtimeInput, { runCommand: deps.runCommand, onProgress: deps.onProgress, env: deps.env }));
   return prepare({
     credentialDirectory: input.credentialDirectory,
     identityPath: input.identityPath,
@@ -2719,7 +2873,7 @@ async function prepareSignerForRuntime(input, deps) {
     // install heartbeat was dead code in production and the console still
     // went silent for the whole cold install — the exact symptom the issue
     // set out to remove, at a longer timeout.
-    prepareSignerRuntime(runtimeInput, { runCommand: deps.runCommand, onProgress: deps.onProgress })
+    prepareSignerRuntime(runtimeInput, { runCommand: deps.runCommand, onProgress: deps.onProgress, env: deps.env })
   ));
   return prepare({
     credentialDirectory: input.credentialDirectory,
@@ -3167,7 +3321,7 @@ async function finishRekey(options, deps = {}) {
         signerPath: `${stored.directory}/signer.json`,
         homeDir: options.homeDir
       },
-      { runCommand: deps.runCommand }
+      { runCommand: deps.runCommand, env: deps.env }
     );
     const result = await (deps.writeConfig ?? writeHostedRuntimeConfig)(
       { runCommand: deps.runCommand, homeDir: options.homeDir },
@@ -3183,6 +3337,11 @@ async function finishRekey(options, deps = {}) {
       { command: prepared.command, args: prepared.args }
     );
     configRewritten = result.hostedConfigured;
+    if (prepared.runtimeSpecOverride) {
+      messages.push(
+        `  Signer runtime:   RUNTIME SPEC OVERRIDE ACTIVE \u2014 ${describeRuntimeSpecOverride(prepared.runtimeSpecOverride.specs)} (NOT the pinned manifest; installed into ${prepared.runtimeDirectory})`
+      );
+    }
     messages.push(`  Config:           ${result.target}`);
     messages.push(...result.messages.map((line) => `  ${line}`));
     if (!configRewritten) {
@@ -3249,6 +3408,7 @@ var init_rekey = __esm({
     init_api();
     init_runtime_install();
     init_signer_runtime();
+    init_runtime_spec_override();
     init_key();
     init_redact();
     init_rekey_messages();
@@ -3425,6 +3585,46 @@ function rekeyPendingCheck(status, hostedDelegateAddress, runtime, slug) {
     detail: `A re-key started ${started} is still open (expires ${status.expiresAt ?? "unknown"}). Paste this address into "Replace signing key" on the Haven agent page: ${address}. Parked at ${status.path}. ` + wedgeNote
   };
 }
+async function runtimeSpecOverrideCheck(directory, sidecar, env) {
+  const facts = [];
+  const installed = sidecar?.runtime_spec_override;
+  if (installed) {
+    facts.push(
+      `signer runtime installed under ${describeRuntimeSpecOverride(installed.specs)} (resolved: ${installed.resolved_specs.join(" ")}; directory key ${installed.directory_key})`
+    );
+  }
+  const mcpInstalled = await readMcpSidecarOverride(directory);
+  if (mcpInstalled) {
+    facts.push(
+      `local MCP runtime installed under ${describeRuntimeSpecOverride(mcpInstalled.specs)} (resolved: ${mcpInstalled.resolved_specs.join(" ")}; directory key ${mcpInstalled.directory_key})`
+    );
+  }
+  let shell;
+  try {
+    const active = resolveRuntimeSpecOverride(env);
+    if (active) shell = `set in this shell: ${describeRuntimeSpecOverride(active)} \u2014 a --repair from here installs these, not the pin`;
+  } catch (err) {
+    shell = err instanceof RuntimeSpecOverrideError ? `set in this shell but REFUSED: ${err.message}` : `set in this shell but unreadable: ${err instanceof Error ? err.message : String(err)}`;
+  }
+  if (shell) facts.push(shell);
+  if (facts.length === 0) return void 0;
+  const variables = Object.values(RUNTIME_SPEC_ENV).join(" / ");
+  return {
+    id: "runtime_spec_override",
+    label: "Runtime spec override",
+    ok: false,
+    detail: `runtime spec overridden \u2014 not the pinned manifest (${MCP_RUNTIME_MANIFEST.signerPackage}@${MCP_RUNTIME_MANIFEST.signerVersion}, ${MCP_RUNTIME_MANIFEST.sdkPackage}@${MCP_RUNTIME_MANIFEST.sdkVersion}). ${facts.join(". ")}.`,
+    repair: `Developer override (#2424). To return to the pinned manifest: unset ${variables}, then run ${RERUN} --doctor --repair --runtime <runtime>. If the override is intentional, this finding is the record of it.`
+  };
+}
+async function readMcpSidecarOverride(directory) {
+  try {
+    const parsed = JSON.parse(await promises.readFile(path.join(directory, "mcp-runtime.json"), "utf8"));
+    return parsed.runtime_spec_override;
+  } catch {
+    return void 0;
+  }
+}
 async function readIdentity(directory) {
   try {
     return JSON.parse(await promises.readFile(path.join(directory, "identity.json"), "utf8"));
@@ -3459,6 +3659,18 @@ async function checksForAgent(entry, input, deps) {
       detail: "No signer-runtime.json sidecar \u2014 the pinned signer runtime was never prepared (or a pre-#1586 npx config).",
       repair: `Run: ${RERUN} --doctor --repair --runtime ${input.runtime}`
     });
+  } else if (sidecar.runtime_spec_override) {
+    const matches = await installedRuntimeMatchesVersions(sidecar.runtime_directory, sidecar.cli_path, {
+      signerVersion: sidecar.signer_version,
+      sdkVersion: sidecar.sdk_version
+    });
+    checks.push({
+      id: "signer_runtime",
+      label: "Signer runtime (preinstalled wrapper)",
+      ok: matches,
+      detail: matches ? `Installed ${sidecar.signer_package}@${sidecar.signer_version} at ${sidecar.runtime_directory} (override install \u2014 see runtime_spec_override)` : `Override runtime directory is stale or empty (${sidecar.runtime_directory}) \u2014 the CLI or package versions are missing.`,
+      ...matches ? {} : { repair: `Run: ${RERUN} --doctor --repair --runtime ${input.runtime} with the same HAVEN_*_SPEC variables set.` }
+    });
   } else {
     const matches = await installedRuntimeMatches(sidecar.runtime_directory, sidecar.cli_path);
     const versionOk = sidecar.signer_version === MCP_RUNTIME_MANIFEST.signerVersion;
@@ -3471,6 +3683,8 @@ async function checksForAgent(entry, input, deps) {
       ...ok ? {} : { repair: `Run: ${RERUN} --doctor --repair --runtime ${input.runtime}` }
     });
   }
+  const overrideCheck = await runtimeSpecOverrideCheck(directory, sidecar, deps.env ?? process.env);
+  if (overrideCheck) checks.push(overrideCheck);
   const hostedUrl = identity?.hosted_mcp_url ?? (identity?.api_url ? `${identity.api_url}/mcp` : void 0);
   if (identity?.api_key && hostedUrl) {
     const probe = await (deps.probeHosted ?? probeHostedMcpTools)(identity.api_key, hostedUrl, deps.fetch);
@@ -3665,7 +3879,7 @@ async function runDoctor(input, deps = {}) {
       signerCapabilities = result.signerCapabilities;
       for (const check of result.checks) primaryChecksById.set(check.id, check);
     }
-    for (const id of ["credentials", "signer_runtime"]) {
+    for (const id of ["credentials", "signer_runtime", "runtime_spec_override"]) {
       const check = primaryChecksById.get(id);
       if (check) checks.push(check);
     }
@@ -3828,7 +4042,7 @@ async function runRepair(input, deps = {}) {
   const signerPath = path.join(directory, "signer.json");
   const prepared = await prepareSignerRuntime(
     { credentialDirectory: directory, signerPath, homeDir, serverName },
-    { runCommand: deps.runCommand }
+    { runCommand: deps.runCommand, env: deps.env }
   );
   messages.push(...prepared.messages);
   const names = serverNamesFor(serverName);
@@ -3855,6 +4069,7 @@ var init_doctor = __esm({
     init_runtime_manifest();
     init_probes();
     init_signer_runtime();
+    init_runtime_spec_override();
     init_config_writers();
     init_runtime_registry();
     init_signer_consent();
@@ -4055,7 +4270,7 @@ function defaultPromptIo() {
 // src/runtime.ts
 init_local_mcp_runtime();
 init_runtime_manifest();
-var CONNECTOR_VERSION = "0.0.0-dev.202609031523.fd49e1a";
+var CONNECTOR_VERSION = "0.0.0-dev.202609031608.fceb089";
 var CONNECT_OUTCOME_SCHEMA_VERSION = 1;
 var failureOutcomesByError = /* @__PURE__ */ new WeakMap();
 function failureOutcomeFor(runtimeHint, error) {