@gmickel/gno 2.9.2 → 2.10.0

package/README.md

@@ -139,7 +139,7 @@ See the [guide](docs/COMPILED-CONTEXT.md).
 
 <!-- public-truth:current-version -->
 
-> Current source version: **v2.9.2**. See [CHANGELOG.md](./CHANGELOG.md).
+> Current source version: **v2.10.0**. See [CHANGELOG.md](./CHANGELOG.md).
 
 <!-- /public-truth -->
 
@@ -332,7 +332,7 @@ Manage the detached process with `gno daemon --status` and `gno daemon --stop`.
 
 <!-- public-truth:runtime -->
 
-Requires [Bun](https://bun.sh/) >=1.3.0.
+Requires [Bun](https://bun.sh/) >=1.4.1.
 
 <!-- /public-truth -->
 

package/browser-extension/artifacts/gno-browser-clipper-v2.10.0.zip.sha256

@@ -0,0 +1 @@
+56174f38783259cef05d81ae53adceebc8467799b735c2f3026b928f7070ae76  gno-browser-clipper-v2.10.0.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "2.9.2"
+  "version": "2.10.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "2.9.2",
+  "version": "2.10.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",
@@ -268,7 +268,7 @@
     "file-type": "22.0.2"
   },
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.1"
   },
   "trustedDependencies": [
     "bun",

package/spec/cli.md

@@ -393,6 +393,13 @@ is alive but did not answer its status request within 500ms). Each resident is
 asked once with that 500ms budget, so `gno status` never waits on a hung
 resident. Terminal output lists the same issues under `Background issues:`.
 
+When an MCP client registration or a running resident uses a missing, old or
+other Bun, JSON output adds `runtimeIssues` (absent otherwise) and terminal
+output lists them under `Bun runtime:`. Each item has `kind`
+(`registration` or `resident`), `severity` (`error`, `warn` or `info`),
+`subject`, `message` and `repair`, the same findings as the doctor checks
+`mcp-runtime` and `resident-runtime` below.
+
 Local activation fingerprints use active-document identifiers and source/mirror
 hashes plus schema, tokenizer, and owned FTS synchronization metadata. Passive
 status never selects or compares stored markdown or FTS bodies. On a receipt
@@ -1507,7 +1514,12 @@ executable, which cannot start the worker, runs the phases in a child process
 of itself (internal environment flag) under the same limits; the child's
 resident memory counts toward `conversion.maxMemoryMb` (Linux `/proc`, `ps`
 elsewhere; time only on Windows). A processor that cannot start fails the file
-with `ISOLATION_UNAVAILABLE`; nothing is prepared without the budget. The
+with `ISOLATION_UNAVAILABLE`; nothing is prepared without the budget. A
+message to or from the processor that cannot be deserialized fails the file
+with `PROCESSOR_MESSAGE_FAILED` (details: `direction` `job`, `result`, or
+`unknown` for the child backend, whose channel Bun closes on both ends;
+`backend`; `phase`), replaces the processor, and writes one stderr line naming
+the direction, backend, `<collection>/<relPath>` and phase. The
 child is SIGKILLed on process exit, SIGTERM, SIGINT (via the CLI's exit
 path) and resident shutdown; on Linux it also carries a parent-death signal,
 so it dies with a SIGKILLed parent, and elsewhere it exits at its next step
@@ -3019,6 +3031,30 @@ gno doctor [--json|--md]
 }
 ```
 
+The `mcp-runtime` check reads every MCP client registration GNO can install
+(all targets and scopes) and reports one `error` when a registration's Bun or
+GNO entrypoint no longer exists or its Bun is below the supported minimum
+(`engines.bun`), and `info` when it resolves to a different Bun than the one
+running doctor. A Bun version comes from a version manager's install path when
+the interpreter resolves into one, else from `<interpreter> --version` under a
+2-second limit; a probe that fails or times out reports the version as unknown.
+The registered MCP command itself is never started. A registration that runs
+the `gno` launcher finds Bun on `PATH` and is only checked for existence. Each
+detail names the client, scope and file, and the repair
+`gno mcp install --target <target> --scope <scope> --force`.
+
+The `resident-runtime` check reads the `serve` and `daemon` pid-files. A live
+resident's Bun comes from the pid-file's `bun_version` (written since this
+release) or, when absent, from `bootstrap.runtime.currentVersion` of
+`GET /api/status` on its recorded port (2-second limit; trusted only when the
+response is a GNO status payload). It is an `error` below the supported
+minimum, a `warn` when older than the Bun running doctor, and `info` when a
+resident from another GNO version does not report its Bun. The check never
+signals a process. Its repair restarts the resident: `gno <kind> --stop` then
+start it again, or, for a resident started by another GNO version (which
+`--stop` refuses), `kill <pid>` (`taskkill /PID <pid>` on Windows) and start it
+again.
+
 The `findings-pass` check reports the daemon's scheduled findings pass from
 its persisted run state: `ok` when disabled or the last run succeeded, `warn`
 on `skipped_lease` / `overdue` / no recorded run, `error` on `failed` or a
@@ -3093,7 +3129,7 @@ gno mcp install [--target <target>] [--scope <scope>] [--force] [--dry-run] [--e
 | ---------------- | ------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `--target`       | string  | claude-desktop | Target client (see table below)                                                                                                                             |
 | `--scope`        | string  | target default | Scope: `user` or `project`; LibreChat defaults to project                                                                                                   |
-| `--force`        | boolean | false          | Overwrite existing gno configuration                                                                                                                        |
+| `--force`        | boolean | false          | Repair an existing gno entry: rewrite its Bun and GNO paths, keep its other arguments, environment and keys, and apply only the options passed explicitly   |
 | `--dry-run`      | boolean | false          | Show what would be done without changes                                                                                                                     |
 | `--enable-write` | boolean | false          | Start the registered server with write tools enabled                                                                                                        |
 | `--tool-profile` | string  | full           | Advertised tool set written into the registration: `core` (7 read tools, plus capture and remember with `--enable-write`) or `full`; omitted writes no flag |
@@ -3132,6 +3168,25 @@ gno mcp install [--target <target>] [--scope <scope>] [--force] [--dry-run] [--e
 | lmstudio       | user    | `~/.lmstudio/mcp.json`                                            | `~/.lmstudio/mcp.json`                        | `~/.lmstudio/mcp.json`                        |
 | librechat      | project | `./librechat.yaml`                                                | `./librechat.yaml`                            | `./librechat.yaml`                            |
 
+**Launch paths and repair:** the command is the running Bun, the first
+argument after `run` the running package's `src/index.ts`. When either sits in
+a version manager's versioned install directory (mise, asdf or proto
+`installs/bun/<version>/` or `tools/bun/<version>/`, Homebrew
+`Cellar/bun/<version>/`), the manager's version-independent link
+(`installs/bun/latest/...`, `opt/bun/...`) is written instead, but only if it
+resolves to the same file; otherwise the versioned path is kept, the text
+output adds a note, and `--json` adds `installed.pinnedPaths`. Shims that pick
+a version from the shell environment are never written. A standalone compiled
+executable is written as is. With `--force` over an existing entry that
+launches GNO (`run <entrypoint> ... mcp ...`, or a `gno` executable), only the
+launch prefix is rewritten; `--index`, `--config`, `--tool-profile` and
+`--enable-write` change only when passed in this invocation, existing
+environment values win over the installer's data and cache directories, and
+keys GNO does not write are kept in every format, Codex TOML included;
+`installed.repaired` is `true`. A Codex key that the TOML writer cannot express
+stops the command before anything is written. An entry that does not launch GNO
+is replaced as before. Without `--force` an existing entry is refused.
+
 **Config Formats:**
 
 - JSONC-compatible (`mcpServers` key): Claude Desktop, Claude Code, Cursor, Windsurf, LM Studio
@@ -3352,6 +3407,19 @@ MCP Server Status
 }
 ```
 
+An entry is reported (and offered to the connector verifier) only when its
+keys are the launch keys (`command`, `args`, `env`; OpenCode `type: "local"`,
+`command`, `environment`) plus inert client settings: `type: "stdio"`, numeric
+`timeout` / `startup_timeout_sec` / `tool_timeout_sec`, a string
+`description`, string-array `autoApprove` / `alwaysAllow`, and boolean
+`enabled` / `disabled` (OpenCode: numeric `timeout` and `enabled`).
+`serverEntry` carries only the launch keys. An entry with `enabled: false` or
+`disabled: true` is `configured: false` without an error. Any other key or
+value, including `cwd`, another transport `type`, `url`, `headers`, and
+environment variables other than `GNO_DATA_DIR` / `GNO_CACHE_DIR`, makes the
+entry `configured: false` with `error: "Malformed MCP server entry"`, and the
+connector verifier reports it as `connector_unsupported_config`.
+
 **Exit Codes:**
 
 - 0: Success

package/src/app/bun-runtime.ts

@@ -0,0 +1,41 @@
+/**
+ * Minimum supported Bun (fn-213).
+ *
+ * `engines.bun` in package.json is the single source of truth. Bun 1.4.0
+ * and 1.4.1 fixed structured-clone bugs in the path worker messages take,
+ * which can crash a long-running process; older runtimes still start, but
+ * `serve`, `daemon` and `mcp` say so once on stderr.
+ *
+ * @module src/app/bun-runtime
+ */
+
+import pkg from "../../package.json";
+
+/** Supported Bun range, e.g. `>=1.4.1`. */
+export const BUN_ENGINE_RANGE: string = pkg.engines.bun;
+
+/** The minimum version in that range, e.g. `1.4.1`. */
+export const BUN_FLOOR: string = BUN_ENGINE_RANGE.replace(/^>=\s*/, "");
+
+/** Whether a Bun version is within the supported range. */
+export function bunMeetsFloor(version: string = Bun.version): boolean {
+  return Bun.semver.satisfies(version, BUN_ENGINE_RANGE);
+}
+
+/** One-line warning for a command started on an unsupported Bun, else null. */
+export function bunFloorWarning(
+  command: string,
+  version: string = Bun.version
+): string | null {
+  if (bunMeetsFloor(version)) return null;
+  return `gno ${command}: running on Bun ${version}, older than the supported minimum ${BUN_FLOOR}; older runtimes can crash long-running processes. Upgrade Bun and restart.`;
+}
+
+/** Print the warning for `command` when the running Bun is unsupported. */
+export function warnIfBunBelowFloor(
+  command: string,
+  write: (line: string) => void = console.warn
+): void {
+  const warning = bunFloorWarning(command);
+  if (warning) write(warning);
+}

package/src/cli/commands/daemon.ts

@@ -5,6 +5,7 @@ import type { FindingsPassResult } from "../../serve/findings-pass";
 import type { ResidentRuntime } from "../../serve/resident-runtime";
 import type { SessionAutomationRunResult } from "../../sessions/types";
 
+import { warnIfBunBelowFloor } from "../../app/bun-runtime";
 import {
   enforceCollectionEgress,
   EGRESS_DENIED_MESSAGE,
@@ -203,6 +204,8 @@ export async function daemon(
     },
   };
 
+  warnIfBunBelowFloor("daemon", logger.error);
+
   const runtimeResult: BackgroundRuntimeResult = await (
     deps.startBackgroundRuntime ?? startBackgroundRuntime
   )({

package/src/cli/commands/doctor.ts

@@ -45,6 +45,12 @@ import {
 import { getStoredEmbeddingFingerprint } from "../../store/vector/freshness";
 import { currentOwnerCount } from "../../store/vector/runtime-compat";
 import { storedVectorPartition } from "../../store/vector/status";
+import {
+  checkRegistrationRuntimes,
+  checkResidentRuntimes,
+  formatRuntimeIssue,
+  type RuntimeIssue,
+} from "../runtime-health";
 import {
   buildDoctorActivation,
   checkConnectorActivation,
@@ -622,6 +628,58 @@ async function checkSqliteExtensions(): Promise<DoctorCheck[]> {
  * Report the daemon's scheduled findings pass from its persisted state so a
  * misconfigured, starved, or failing scheduler is visible without the daemon.
  */
+const SEVERITY_RANK: Record<RuntimeIssue["severity"], number> = {
+  info: 0,
+  warn: 1,
+  error: 2,
+};
+
+function runtimeCheck(
+  name: string,
+  issues: RuntimeIssue[],
+  okMessage: string
+): DoctorCheck {
+  if (issues.length === 0) {
+    return { name, status: "ok", message: okMessage };
+  }
+  const worst = issues.reduce((current, issue) =>
+    SEVERITY_RANK[issue.severity] > SEVERITY_RANK[current.severity]
+      ? issue
+      : current
+  );
+  return {
+    name,
+    status: worst.severity,
+    message:
+      issues.length === 1
+        ? `${worst.subject}: ${worst.message}`
+        : `${issues.length} need attention; first: ${worst.subject}: ${worst.message}`,
+    details: issues.map(formatRuntimeIssue),
+  };
+}
+
+/** Bun used by MCP registrations and by running residents. */
+export async function checkRuntimes(
+  overrides: { cwd?: string; homeDir?: string } = {}
+): Promise<DoctorCheck[]> {
+  const [registrations, residents] = await Promise.all([
+    checkRegistrationRuntimes(overrides),
+    checkResidentRuntimes(),
+  ]);
+  return [
+    runtimeCheck(
+      "mcp-runtime",
+      registrations,
+      "MCP registrations launch an existing, supported Bun"
+    ),
+    runtimeCheck(
+      "resident-runtime",
+      residents,
+      "No running resident is on an older Bun"
+    ),
+  ];
+}
+
 export async function checkFindingsPass(
   config: Config,
   indexName?: string
@@ -727,6 +785,9 @@ export async function doctor(
   // Scheduled findings pass (daemon-only, opt-in)
   checks.push(await checkFindingsPass(config, options.indexName));
 
+  // Which Bun client registrations and running residents use (fn-213)
+  checks.push(...(await checkRuntimes()));
+
   const activation = await buildDoctorActivation(config, options);
   checks.push(checkRetrievalActivation(activation));
   const connectorActivation = checkConnectorActivation(activation);

package/src/cli/commands/mcp/config-editors.ts

@@ -371,19 +371,66 @@ function tomlString(value: string): string {
   return JSON.stringify(value);
 }
 
-function serializeTomlEntry(entry: StandardMcpEntry, newline: string): string {
+const TOML_BARE_KEY = /^[A-Za-z0-9_-]+$/;
+
+function tomlKey(key: string): string {
+  return TOML_BARE_KEY.test(key) ? key : tomlString(key);
+}
+
+/** A kept key's value as TOML; null for values this writer cannot express. */
+function tomlValue(value: unknown): string | null {
+  if (typeof value === "string") {
+    return tomlString(value);
+  }
+  if (
+    typeof value === "boolean" ||
+    (typeof value === "number" && Number.isFinite(value))
+  ) {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    const items = value.map(tomlValue);
+    return items.every((item) => item !== null)
+      ? `[${items.join(", ")}]`
+      : null;
+  }
+  return null;
+}
+
+/** Keys of an existing GNO entry kept by a repair (see repair-entry.ts). */
+export interface TomlEntryExtras {
+  env?: Record<string, string>;
+  extra?: Record<string, unknown>;
+}
+
+function serializeTomlEntry(
+  entry: StandardMcpEntry,
+  newline: string,
+  configPath: string,
+  extras: TomlEntryExtras = {}
+): string {
   const args = entry.args.map(tomlString).join(", ");
   const lines = [
     "[mcp_servers.gno]",
     `command = ${tomlString(entry.command)}`,
     `args = [${args}]`,
   ];
-  if (entry.env && Object.keys(entry.env).length > 0) {
+  for (const [key, value] of Object.entries(extras.extra ?? {})) {
+    const serialized = tomlValue(value);
+    if (serialized === null) {
+      throw new CliError(
+        "RUNTIME",
+        `Cannot keep "${key}" of the GNO MCP entry in ${configPath}; remove the entry with gno mcp uninstall, or edit the key, then install again.`
+      );
+    }
+    lines.push(`${tomlKey(key)} = ${serialized}`);
+  }
+  const env = { ...entry.env, ...extras.env };
+  if (Object.keys(env).length > 0) {
     lines.push("", "[mcp_servers.gno.env]");
-    for (const key of ["GNO_DATA_DIR", "GNO_CACHE_DIR"] as const) {
-      const value = entry.env[key];
+    for (const [key, value] of Object.entries(env)) {
       if (value) {
-        lines.push(`${key} = ${tomlString(value)}`);
+        lines.push(`${tomlKey(key)} = ${tomlString(value)}`);
       }
     }
   }
@@ -393,7 +440,8 @@ function serializeTomlEntry(entry: StandardMcpEntry, newline: string): string {
 export function setTomlServerEntry(
   content: string,
   configPath: string,
-  entry: StandardMcpEntry
+  entry: StandardMcpEntry,
+  extras?: TomlEntryExtras
 ): string {
   const parsed = getTomlServerEntry(content, configPath);
   const removed = removeTomlGnoSections(content, configPath);
@@ -405,8 +453,8 @@ export function setTomlServerEntry(
   }
   const prefix = removed.content.trimEnd();
   const updated = prefix
-    ? `${prefix}${removed.newline}${removed.newline}${serializeTomlEntry(entry, removed.newline)}`
-    : serializeTomlEntry(entry, removed.newline);
+    ? `${prefix}${removed.newline}${removed.newline}${serializeTomlEntry(entry, removed.newline, configPath, extras)}`
+    : serializeTomlEntry(entry, removed.newline, configPath, extras);
   parseTomlRoot(updated, configPath);
   return updated;
 }

package/src/cli/commands/mcp/install.ts

@@ -29,14 +29,22 @@ import {
 } from "./config.js";
 import {
   buildMcpServerEntry,
+  resolveLaunchPaths,
   getDefaultTargetScope,
   getTargetScopes,
   getTargetDisplayName,
+  type McpConfigFormat,
   type McpScope,
   type McpServerEntry,
   type McpTarget,
   resolveMcpConfigPath,
 } from "./paths.js";
+import {
+  type ExplicitInstallValues,
+  readExistingRegistration,
+  type RepairedRegistration,
+  repairRegistration,
+} from "./repair-entry.js";
 import { normalizeMcpServerEntryForInstall } from "./server-entry.js";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -71,6 +79,8 @@ export interface McpInstallResult {
   configPath: string;
   action: "created" | "updated" | "dry_run_create" | "dry_run_update";
   serverEntry: McpServerEntry;
+  /** `--force` kept the existing entry's settings and repaired its launch path. */
+  repaired?: boolean;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -89,6 +99,12 @@ export async function installMcpToTarget(
     dryRun?: boolean;
     cwd?: string;
     homeDir?: string;
+    /**
+     * With `force` over an existing entry: keep its settings and apply only
+     * these explicit options (repair-entry.ts). Without it, the entry is
+     * replaced.
+     */
+    preserveExisting?: ExplicitInstallValues;
   }
 ): Promise<McpInstallResult> {
   const { force = false, dryRun = false, cwd, homeDir } = options;
@@ -120,23 +136,45 @@ export async function installMcpToTarget(
     );
   }
 
-  const entry = buildEntry(
-    normalizedEntry.command,
-    normalizedEntry.args,
-    configFormat,
-    normalizedEntry.env
-  );
-  const standardEntry = {
-    command: normalizedEntry.command,
-    args: normalizedEntry.args,
-    ...(normalizedEntry.env ? { env: normalizedEntry.env } : {}),
-  };
-  const updated =
-    configFormat === "codex_toml"
-      ? setTomlServerEntry(content, configPath, standardEntry)
-      : configFormat === "yaml_standard"
-        ? setYamlServerEntry(content, configPath, serversKey, standardEntry)
-        : setJsoncServerEntry(content, configPath, serversKey, entry);
+  const existing =
+    alreadyExists && options.preserveExisting
+      ? readExistingRegistration(parsed.entry, configFormat)
+      : null;
+  const repaired =
+    existing && options.preserveExisting
+      ? repairRegistration(existing, normalizedEntry, options.preserveExisting)
+      : null;
+  if (repaired) {
+    // Same structural rules as a fresh entry for what this command writes.
+    normalizeMcpServerEntryForInstall({
+      command: repaired.command,
+      args: repaired.args,
+    });
+  }
+  const updated = repaired
+    ? writeRepairedEntry(
+        content,
+        configPath,
+        configFormat,
+        serversKey,
+        repaired
+      )
+    : writeFreshEntry(
+        content,
+        configPath,
+        configFormat,
+        serversKey,
+        normalizedEntry
+      );
+  const writtenEntry: McpServerEntry = repaired
+    ? {
+        command: repaired.command,
+        args: repaired.args,
+        ...(Object.keys(repaired.env).length > 0
+          ? { env: repaired.env as McpServerEntry["env"] }
+          : {}),
+      }
+    : normalizedEntry;
 
   const wouldCreate = !alreadyExists;
   if (dryRun) {
@@ -145,7 +183,8 @@ export async function installMcpToTarget(
       scope,
       configPath,
       action: wouldCreate ? "dry_run_create" : "dry_run_update",
-      serverEntry: normalizedEntry,
+      serverEntry: writtenEntry,
+      ...(repaired ? { repaired: true } : {}),
     };
   }
 
@@ -157,8 +196,73 @@ export async function installMcpToTarget(
     scope,
     configPath,
     action,
-    serverEntry: normalizedEntry,
+    serverEntry: writtenEntry,
+    ...(repaired ? { repaired: true } : {}),
+  };
+}
+
+function writeFreshEntry(
+  content: string,
+  configPath: string,
+  configFormat: McpConfigFormat,
+  serversKey: string,
+  normalizedEntry: McpServerEntry
+): string {
+  const standardEntry = {
+    command: normalizedEntry.command,
+    args: normalizedEntry.args,
+    ...(normalizedEntry.env ? { env: normalizedEntry.env } : {}),
+  };
+  if (configFormat === "codex_toml") {
+    return setTomlServerEntry(content, configPath, standardEntry);
+  }
+  if (configFormat === "yaml_standard") {
+    return setYamlServerEntry(content, configPath, serversKey, standardEntry);
+  }
+  const entry = buildEntry(
+    normalizedEntry.command,
+    normalizedEntry.args,
+    configFormat,
+    normalizedEntry.env
+  );
+  return setJsoncServerEntry(content, configPath, serversKey, entry);
+}
+
+/** Write a repaired entry, keeping the keys GNO does not manage. */
+function writeRepairedEntry(
+  content: string,
+  configPath: string,
+  configFormat: McpConfigFormat,
+  serversKey: string,
+  repaired: RepairedRegistration
+): string {
+  const hasEnv = Object.keys(repaired.env).length > 0;
+  if (configFormat === "codex_toml") {
+    return setTomlServerEntry(
+      content,
+      configPath,
+      { command: repaired.command, args: repaired.args },
+      { env: repaired.env, extra: repaired.extra }
+    );
+  }
+  if (configFormat === "mcp") {
+    return setJsoncServerEntry(content, configPath, serversKey, {
+      type: "local",
+      enabled: true,
+      ...repaired.extra,
+      command: [repaired.command, ...repaired.args],
+      ...(hasEnv ? { environment: repaired.env } : {}),
+    });
+  }
+  const entry = {
+    ...repaired.extra,
+    command: repaired.command,
+    args: repaired.args,
+    ...(hasEnv ? { env: repaired.env } : {}),
   };
+  return configFormat === "yaml_standard"
+    ? setYamlServerEntry(content, configPath, serversKey, entry)
+    : setJsoncServerEntry(content, configPath, serversKey, entry);
 }
 
 /**
@@ -200,6 +304,14 @@ export async function installMcp(opts: InstallOptions = {}): Promise<void> {
     opts.configPath ?? paths.configFile,
     opts.cwd
   );
+  // Only what the user passed overrides an existing entry under --force;
+  // the defaults above never do.
+  const explicit: ExplicitInstallValues = {
+    ...(opts.indexName !== undefined ? { indexName } : {}),
+    ...(opts.configPath !== undefined ? { configPath } : {}),
+    ...(toolProfile !== undefined ? { toolProfile } : {}),
+    ...(opts.enableWrite ? { enableWrite: true } : {}),
+  };
   const globals = safeGetGlobals();
   const json = opts.json ?? globals.json;
   const quiet = opts.quiet ?? globals.quiet;
@@ -228,11 +340,18 @@ export async function installMcp(opts: InstallOptions = {}): Promise<void> {
     dryRun,
     cwd: opts.cwd,
     homeDir: opts.homeDir,
+    preserveExisting: explicit,
   });
+  const launch = resolveLaunchPaths();
+  const pinnedPaths = [launch.bun, launch.entrypoint]
+    .filter((path) => path.pinned)
+    .map((path) => path.path);
 
   // Output
   if (json) {
-    process.stdout.write(`${JSON.stringify({ installed: result }, null, 2)}\n`);
+    process.stdout.write(
+      `${JSON.stringify({ installed: { ...result, ...(pinnedPaths.length > 0 ? { pinnedPaths } : {}) } }, null, 2)}\n`
+    );
     return;
   }
 
@@ -247,8 +366,9 @@ export async function installMcp(opts: InstallOptions = {}): Promise<void> {
       `Would ${dryRunVerb} gno in ${getTargetDisplayName(target)}:\n`
     );
     process.stdout.write(`  Config: ${result.configPath}\n`);
-    process.stdout.write(`  Command: ${serverEntry.command}\n`);
-    process.stdout.write(`  Args: ${serverEntry.args.join(" ")}\n`);
+    process.stdout.write(`  Command: ${result.serverEntry.command}\n`);
+    process.stdout.write(`  Args: ${result.serverEntry.args.join(" ")}\n`);
+    writePinNote(pinnedPaths);
     return;
   }
 
@@ -256,8 +376,23 @@ export async function installMcp(opts: InstallOptions = {}): Promise<void> {
   process.stdout.write(
     `${verb} gno MCP server in ${getTargetDisplayName(target)}.\n`
   );
-  process.stdout.write(`  Config: ${result.configPath}\n\n`);
+  process.stdout.write(`  Config: ${result.configPath}\n`);
+  if (result.repaired) {
+    process.stdout.write(
+      "  Kept the existing settings; updated the Bun and GNO paths.\n"
+    );
+  }
+  writePinNote(pinnedPaths);
   process.stdout.write(
-    `Restart ${getTargetDisplayName(target)} to load the server.\n`
+    `\nRestart ${getTargetDisplayName(target)} to load the server.\n`
   );
 }
+
+/** Say when a launch path stays on one installed version. */
+function writePinNote(pinnedPaths: string[]): void {
+  for (const path of pinnedPaths) {
+    process.stdout.write(
+      `  Note: ${path} is inside a versioned install directory with no version-independent link to it; this registration keeps using that version after an upgrade. Run gno mcp install --force again after upgrading (gno doctor reports it).\n`
+    );
+  }
+}