auxilo-mcp 0.9.16 → 0.9.17

package/bin/auxilo-cli.js

@@ -553,7 +553,20 @@ async function cmdStatus() {
     const reg = c.mcp
       ? (c.registered ? 'MCP registered' : 'detected, MCP NOT registered')
       : 'poll-based source (no MCP config)';
-    console.log(`  ${c.name}: ${reg}`);
+    // MCP-SERVER-STALENESS (0.9.17): show the pin written into this client's
+    // config alongside the installed runner version, so a stale pin (or a
+    // pre-0.9.17 unpinned entry) is visible without opening the config file.
+    let pinNote = '';
+    if (c.mcp && c.registered) {
+      if (c.mcpPin === 'unpinned') {
+        pinNote = ' (pin: unpinned — run `npx auxilo setup` to pin)';
+      } else if (c.mcpPin) {
+        pinNote = c.mcpPinStale
+          ? ` (pin: v${c.mcpPin}, runner: v${s.runnerVersion} — STALE, run \`npx auxilo setup\`)`
+          : ` (pin: v${c.mcpPin})`;
+      }
+    }
+    console.log(`  ${c.name}: ${reg}${pinNote}`);
   }
 
   console.log(`Auth: ${s.auth.credentialsFile

package/lib/installer.js

@@ -29,9 +29,37 @@ const { hasAuxiloSessionEndHook } = require('./hook-status.js');
 
 // ─── Constants ──────────────────────────────────────────────────────────────
 
-/** MCP registration entry written into every client config (spec §LW-12 step 1). */
+/**
+ * MCP registration entry written into every client config (spec §LW-12
+ * step 1). MCP-SERVER-STALENESS (0.9.17): the entry is now PINNED to an
+ * exact installed version (`npx auxilo-mcp@<version>`) rather than the bare
+ * package name — an unpinned `npx auxilo-mcp` follows whatever npx's local
+ * cache happens to resolve `latest` to, which only refreshes when that
+ * cache expires (the INSTALL-0828 incident: a 10-week-old cached build
+ * served silently). MCP_ENTRY itself stays the UNPINNED template (base
+ * command + package name) — see mcpEntry(version) below for the pinned
+ * shape every writer actually uses.
+ */
 const MCP_ENTRY = Object.freeze({ command: 'npx', args: ['auxilo-mcp'] });
 
+/** Bare package name portion of MCP_ENTRY.args[0], for pin construction/parsing. */
+const MCP_PACKAGE_NAME = MCP_ENTRY.args[0];
+
+/** True when `args` is shaped like an Auxilo-owned MCP entry (pinned or not). */
+function isOwnedMcpArgs(args) {
+  return Array.isArray(args) && args.length === 1 && typeof args[0] === 'string' &&
+    (args[0] === MCP_PACKAGE_NAME || args[0].startsWith(`${MCP_PACKAGE_NAME}@`));
+}
+
+/**
+ * Parse the version pin (or 'unpinned') out of an owned args array, or null
+ * when `args` isn't a recognizable Auxilo entry at all.
+ */
+function parseMcpPin(args) {
+  if (!isOwnedMcpArgs(args)) return null;
+  return args[0] === MCP_PACKAGE_NAME ? 'unpinned' : args[0].slice(MCP_PACKAGE_NAME.length + 1);
+}
+
 /** Default production API base (README.md / openapi.json servers[0]). */
 const DEFAULT_BASE_URL = 'https://auxilo.io';
 
@@ -418,11 +446,66 @@ function detectClients(homeDir, opts = {}) {
 
 // ─── MCP registration (spec §LW-12 step 1) ──────────────────────────────────
 
+/**
+ * F3 (0.9.17 fix pass): a unique `<file>.tmp-<pid>-<rand>` path for atomic
+ * config writers, matching the RUNNER_STACK convention (installRunnerAtomic
+ * above) instead of a fixed `<file>.tmp` name — two concurrent writers
+ * (e.g. `auxilo setup` and a self-update's rewriteMcpPins racing) no longer
+ * collide on the same tmp path and lose one writer's update.
+ */
+function uniqueTmpPath(filePath) {
+  return `${filePath}.tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
+}
+
+/**
+ * F3 (0.9.17 fix pass): sweep leftover `<file>.tmp-<pid>-<rand>` files from
+ * a writer that crashed or was killed mid-write, before starting a new
+ * write to the same path. Scoped tightly: only this exact file's own tmp
+ * prefix, only that file's own directory, and only entries older than an
+ * hour — never a tmp file another concurrent writer just created moments
+ * ago. Best-effort throughout; a sweep failure must never block the real
+ * write.
+ */
+function sweepStaleTmpFiles(filePath) {
+  const dir = path.dirname(filePath);
+  const prefix = `${path.basename(filePath)}.tmp-`;
+  const cutoffMs = Date.now() - 60 * 60 * 1000;
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return; // dir missing/unreadable — nothing to sweep
+  }
+  for (const name of names) {
+    if (!name.startsWith(prefix)) continue;
+    const full = path.join(dir, name);
+    try {
+      if (fs.statSync(full).mtimeMs < cutoffMs) fs.rmSync(full, { force: true });
+    } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * F2 (0.9.17 fix pass): the existing file's mode (owner/group/other bits
+ * only), or null when the file doesn't exist yet (format's own default
+ * applies via the umask, same as before this fix).
+ */
+function existingMode(filePath) {
+  try {
+    return fs.statSync(filePath).mode & 0o777;
+  } catch {
+    return null;
+  }
+}
+
 /** Atomic JSON write: tmp + rename (same convention as mcp-server.js setup). */
 function writeJsonAtomic(filePath, obj) {
-  const tmp = `${filePath}.tmp`;
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  sweepStaleTmpFiles(filePath);
+  const mode = existingMode(filePath);
+  const tmp = uniqueTmpPath(filePath);
   fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n');
+  if (mode !== null) fs.chmodSync(tmp, mode); // F2: preserve the existing file's mode across re-pin
   fs.renameSync(tmp, filePath);
 }
 
@@ -443,9 +526,15 @@ function readClientConfig(configPath) {
   }
 }
 
-/** Fresh copy of the standard MCP server entry (never share the frozen one). */
-function mcpEntry() {
-  return { command: MCP_ENTRY.command, args: [...MCP_ENTRY.args] };
+/**
+ * Fresh MCP server entry object (never share the frozen MCP_ENTRY).
+ * MCP-SERVER-STALENESS (0.9.17): when `version` is given, the package spec
+ * is pinned EXACT (`auxilo-mcp@<version>`); omitted/falsy keeps the legacy
+ * unpinned shape (only used by parity checks below — every real writer call
+ * always passes a version, defaulting to packageVersion() in registerMcp).
+ */
+function mcpEntry(version) {
+  return { command: MCP_ENTRY.command, args: [version ? `${MCP_PACKAGE_NAME}@${version}` : MCP_PACKAGE_NAME] };
 }
 
 /** Result helpers shared by every registerMcp format writer. */
@@ -456,12 +545,45 @@ function registeredResult(configPath) {
   return { changed: true, status: 'registered', configPath };
 }
 
-/** Default writer: Claude-Desktop-style `mcpServers` object (most clients). */
-function registerJsonMcpServers(client) {
+/**
+ * Default writer: Claude-Desktop-style `mcpServers` object (most clients;
+ * also Continue.dev's drop-in file, which shares the identical shape — see
+ * registerJsonDropin below).
+ *
+ * MCP-SERVER-STALENESS (0.9.17): now UPSERTS instead of pure create-once.
+ * An absent entry is created pinned to `version`. An EXISTING entry is
+ * re-pinned only when it is recognizably OURS (isOwnedMcpArgs — command
+ * 'npx', a single `auxilo-mcp`/`auxilo-mcp@X.Y.Z` arg) and the pin differs;
+ * a foreign/hand-edited entry sharing the `auxilo` key is left completely
+ * untouched (never overwritten). F1 (0.9.17 fix pass): an owned entry is
+ * re-pinned by patching `command`/`args` IN PLACE on the existing object,
+ * not by replacing it wholesale — any other keys the user added to their
+ * own Auxilo entry (env, disabled, timeout, alwaysAllow, cwd, …) and their
+ * key order survive both `auxilo setup` re-runs and the self-update rewrite
+ * path, same as the foreign-entry case above.
+ */
+function registerJsonMcpServers(client, version) {
   const config = readClientConfig(client.configPath);
-  if (config.mcpServers && config.mcpServers.auxilo) return unchangedResult(client.configPath);
-  if (!config.mcpServers) config.mcpServers = {};
-  config.mcpServers.auxilo = mcpEntry();
+  const existing = config.mcpServers && config.mcpServers.auxilo;
+  if (existing && !(existing.command === MCP_ENTRY.command && isOwnedMcpArgs(existing.args))) {
+    return unchangedResult(client.configPath); // foreign entry — never touch
+  }
+  const target = mcpEntry(version);
+  if (existing && existing.command === target.command &&
+      JSON.stringify(existing.args) === JSON.stringify(target.args)) {
+    return unchangedResult(client.configPath); // already pinned correctly
+  }
+  if (existing) {
+    // F1 (0.9.17 fix pass): patch command/args IN PLACE on the existing
+    // object instead of replacing it wholesale — any other keys the user
+    // added to their own Auxilo entry (env, disabled, timeout, alwaysAllow,
+    // cwd, …) survive the re-pin, and existing key order is preserved.
+    existing.command = target.command;
+    existing.args = target.args;
+  } else {
+    if (!config.mcpServers) config.mcpServers = {};
+    config.mcpServers.auxilo = target;
+  }
   writeJsonAtomic(client.configPath, config);
   return registeredResult(client.configPath);
 }
@@ -469,60 +591,133 @@ function registerJsonMcpServers(client) {
 /** TOML section header used for Codex idempotency (substring probe — no TOML dep). */
 const CODEX_SECTION_HEADER = '[mcp_servers.auxilo]';
 
+/** Bound our `[mcp_servers.auxilo]` section: header .. next top-level `[` at line-start, or EOF. */
+function codexSectionBounds(raw, headerIdx) {
+  const afterHeader = headerIdx + CODEX_SECTION_HEADER.length;
+  const nextHeaderMatch = raw.slice(afterHeader).match(/\n\[/);
+  const end = nextHeaderMatch ? afterHeader + nextHeaderMatch.index : raw.length;
+  return { start: headerIdx, end };
+}
+
 /**
- * Codex CLI writer: APPEND-ONLY into ~/.codex/config.toml. Existing TOML is
- * never parsed, rewritten, or reformatted — we only ever append our own
- * section, and only when the `[mcp_servers.auxilo]` header is absent.
+ * Codex CLI writer: APPEND-ONLY into ~/.codex/config.toml when our section
+ * is absent. Existing TOML is never parsed or reformatted as a whole file —
+ * MCP-SERVER-STALENESS (0.9.17): when our section IS present, ONLY its own
+ * `args = [...]` line is rewritten (via targeted string replace, scoped to
+ * our section's bounds so an unrelated `[mcp_servers.other]` table sharing
+ * the same key names is never touched), and only when that line is
+ * recognizably ours (isOwnedMcpArgs) — a hand-edited section is left
+ * byte-identical. Every other byte of the file, including comments and
+ * formatting inside or outside our section, survives untouched.
  */
-function registerCodexToml(client) {
+function registerCodexToml(client, version) {
   const raw = fs.existsSync(client.configPath)
     ? fs.readFileSync(client.configPath, 'utf-8')
     : '';
-  if (raw.includes(CODEX_SECTION_HEADER)) return unchangedResult(client.configPath);
+  const target = mcpEntry(version);
+  const headerIdx = raw.indexOf(CODEX_SECTION_HEADER);
+
+  if (headerIdx === -1) {
+    const section = `\n${CODEX_SECTION_HEADER}\n` +
+      `command = ${JSON.stringify(target.command)}\n` +
+      `args = ${JSON.stringify(target.args)}\n`;
+    fs.mkdirSync(path.dirname(client.configPath), { recursive: true });
+    sweepStaleTmpFiles(client.configPath);
+    const mode = existingMode(client.configPath);
+    const tmp = uniqueTmpPath(client.configPath);
+    fs.writeFileSync(tmp, raw + section);
+    if (mode !== null) fs.chmodSync(tmp, mode); // F2: preserve existing file's mode
+    fs.renameSync(tmp, client.configPath);
+    return registeredResult(client.configPath);
+  }
 
-  const section = `\n${CODEX_SECTION_HEADER}\n` +
-    `command = ${JSON.stringify(MCP_ENTRY.command)}\n` +
-    `args = ${JSON.stringify(MCP_ENTRY.args)}\n`;
+  const { start, end } = codexSectionBounds(raw, headerIdx);
+  const section = raw.slice(start, end);
+  const cmdMatch = section.match(/^command = (".*")$/m);
+  const argsMatch = section.match(/^args = (\[.*\])$/m);
+  let currentCommand = null;
+  let currentArgs = null;
+  try {
+    currentCommand = cmdMatch ? JSON.parse(cmdMatch[1]) : null;
+    currentArgs = argsMatch ? JSON.parse(argsMatch[1]) : null;
+  } catch { /* malformed line — treated as not-owned below */ }
 
-  const tmp = `${client.configPath}.tmp`;
-  fs.mkdirSync(path.dirname(client.configPath), { recursive: true });
-  fs.writeFileSync(tmp, raw + section);
+  const owned = currentCommand === target.command && isOwnedMcpArgs(currentArgs);
+  if (!owned) return unchangedResult(client.configPath); // foreign/hand-edited section — never touch
+
+  if (JSON.stringify(currentArgs) === JSON.stringify(target.args)) {
+    return unchangedResult(client.configPath); // already pinned correctly
+  }
+
+  const newSection = section.replace(/^args = \[.*\]$/m, `args = ${JSON.stringify(target.args)}`);
+  const newRaw = raw.slice(0, start) + newSection + raw.slice(end);
+  sweepStaleTmpFiles(client.configPath);
+  const mode = existingMode(client.configPath);
+  const tmp = uniqueTmpPath(client.configPath);
+  fs.writeFileSync(tmp, newRaw);
+  if (mode !== null) fs.chmodSync(tmp, mode); // F2: preserve existing file's mode
   fs.renameSync(tmp, client.configPath);
   return registeredResult(client.configPath);
 }
 
-/** Continue.dev writer: standalone drop-in file under ~/.continue/mcpServers/. */
-function registerJsonDropin(client) {
-  const config = readClientConfig(client.configPath);
-  if (config.mcpServers && config.mcpServers.auxilo) return unchangedResult(client.configPath);
-  if (!config.mcpServers) config.mcpServers = {};
-  config.mcpServers.auxilo = mcpEntry();
-  writeJsonAtomic(client.configPath, config);
-  return registeredResult(client.configPath);
+/** Continue.dev writer: standalone drop-in file under ~/.continue/mcpServers/ — identical shape to registerJsonMcpServers. */
+function registerJsonDropin(client, version) {
+  return registerJsonMcpServers(client, version);
 }
 
 /** opencode writer: `mcp` key, entry shape {type:'local', command:[bin,...args]}. */
-function registerOpencode(client) {
+function registerOpencode(client, version) {
   const config = readClientConfig(client.configPath);
-  if (config.mcp && config.mcp.auxilo) return unchangedResult(client.configPath);
-  if (!config.mcp) config.mcp = {};
-  config.mcp.auxilo = { type: 'local', command: [MCP_ENTRY.command, ...MCP_ENTRY.args] };
+  const existing = config.mcp && config.mcp.auxilo;
+  const existingArgs = existing && Array.isArray(existing.command) ? existing.command.slice(1) : null;
+  const existingOwned = existing && existing.type === 'local' &&
+    Array.isArray(existing.command) && existing.command[0] === MCP_ENTRY.command &&
+    isOwnedMcpArgs(existingArgs);
+  if (existing && !existingOwned) return unchangedResult(client.configPath); // foreign entry — never touch
+
+  const targetCommand = [MCP_ENTRY.command, ...mcpEntry(version).args];
+  if (existing && JSON.stringify(existing.command) === JSON.stringify(targetCommand)) {
+    return unchangedResult(client.configPath); // already pinned correctly
+  }
+  if (existing) {
+    // F1 (0.9.17 fix pass): patch command IN PLACE — preserves any other
+    // keys the user added to their entry (env, cwd, …) and key order.
+    existing.command = targetCommand;
+  } else {
+    if (!config.mcp) config.mcp = {};
+    config.mcp.auxilo = { type: 'local', command: targetCommand };
+  }
   writeJsonAtomic(client.configPath, config);
   return registeredResult(client.configPath);
 }
 
 /** Amp writer: settings.json flat `amp.mcpServers` key (an object of servers). */
-function registerAmp(client) {
+function registerAmp(client, version) {
   const config = readClientConfig(client.configPath);
   const servers = config['amp.mcpServers'];
-  if (servers && servers.auxilo) return unchangedResult(client.configPath);
-  config['amp.mcpServers'] = { ...(servers || {}), auxilo: mcpEntry() };
+  const existing = servers && servers.auxilo;
+  if (existing && !(existing.command === MCP_ENTRY.command && isOwnedMcpArgs(existing.args))) {
+    return unchangedResult(client.configPath); // foreign entry — never touch
+  }
+  const target = mcpEntry(version);
+  if (existing && existing.command === target.command &&
+      JSON.stringify(existing.args) === JSON.stringify(target.args)) {
+    return unchangedResult(client.configPath); // already pinned correctly
+  }
+  if (existing) {
+    // F1 (0.9.17 fix pass): patch command/args IN PLACE — preserves any
+    // other keys the user added to their entry and key order.
+    existing.command = target.command;
+    existing.args = target.args;
+  } else {
+    config['amp.mcpServers'] = { ...(servers || {}), auxilo: target };
+  }
   writeJsonAtomic(client.configPath, config);
   return registeredResult(client.configPath);
 }
 
 /** OpenHands writer: `stdio_servers` ARRAY of {name, command, args}, keyed by name. */
-function registerOpenHands(client) {
+function registerOpenHands(client, version) {
   const config = readClientConfig(client.configPath);
   // GOV-3 M1: a non-array stdio_servers means the schema isn't what we expect
   // (drift, or an object map) — skip loudly rather than clobbering the user's
@@ -531,8 +726,26 @@ function registerOpenHands(client) {
     throw new Error(`Unexpected stdio_servers shape in ${client.configPath} (not an array) — add the Auxilo entry manually`);
   }
   const servers = config.stdio_servers || [];
-  if (servers.some((s) => s && s.name === 'auxilo')) return unchangedResult(client.configPath);
-  config.stdio_servers = [...servers, { name: 'auxilo', ...mcpEntry() }];
+  const idx = servers.findIndex((s) => s && s.name === 'auxilo');
+  const existing = idx === -1 ? null : servers[idx];
+  if (existing && !(existing.command === MCP_ENTRY.command && isOwnedMcpArgs(existing.args))) {
+    return unchangedResult(client.configPath); // foreign entry — never touch
+  }
+  const target = mcpEntry(version);
+  if (existing && existing.command === target.command &&
+      JSON.stringify(existing.args) === JSON.stringify(target.args)) {
+    return unchangedResult(client.configPath); // already pinned correctly
+  }
+  if (existing) {
+    // F1 (0.9.17 fix pass): patch command/args IN PLACE — preserves any
+    // other keys the user added to their entry (env, cwd, …) and array
+    // order/identity (existing === servers[idx] === config.stdio_servers[idx]).
+    existing.command = target.command;
+    existing.args = target.args;
+    config.stdio_servers = servers;
+  } else {
+    config.stdio_servers = [...servers, { name: 'auxilo', ...target }];
+  }
   writeJsonAtomic(client.configPath, config);
   return registeredResult(client.configPath);
 }
@@ -548,17 +761,28 @@ const MCP_WRITERS = Object.freeze({
 });
 
 /**
- * Register the Auxilo MCP server in one client's config file.
+ * Register (or re-pin) the Auxilo MCP server in one client's config file.
  * Dispatches on the client's `format` (default 'json-mcpServers'). All JSON
- * writers are read-modify-write with tmp+rename; existing keys preserved;
- * no-op (file untouched) when the auxilo entry is already present. The Codex
- * TOML writer is append-only and never touches existing content.
+ * writers are read-modify-write with tmp+rename; existing non-Auxilo keys
+ * preserved untouched; no-op (file byte-identical) when the auxilo entry is
+ * already pinned to `version`. An existing entry that doesn't look like ours
+ * (isOwnedMcpArgs) is left completely alone — this function only ever
+ * creates a fresh entry or re-pins one it recognizes as its own. The Codex
+ * TOML writer is append-only for a fresh section, and rewrites only its own
+ * `args =` line for an existing owned one.
+ *
+ * MCP-SERVER-STALENESS (0.9.17): `version` defaults to packageVersion() (the
+ * currently running package's own version) so every call — interactive
+ * setup and the programmatic rewriteMcpPins() path alike — pins to an EXACT
+ * version rather than writing the old bare `auxilo-mcp` (which npx resolves
+ * to whatever `latest` its local cache currently holds).
  *
  * @param {object} client  Entry from clientRegistry (must have configPath).
+ * @param {string} [version]  Exact version to pin; defaults to packageVersion().
  * @returns {{ changed: boolean, status: 'registered'|'already-registered', configPath: string }}
  * @throws on malformed existing JSON (B15 — caller skips that client loudly)
  */
-function registerMcp(client) {
+function registerMcp(client, version) {
   if (!client || !client.configPath) {
     throw new Error(`registerMcp: client ${client && client.id} has no MCP config path`);
   }
@@ -566,7 +790,7 @@ function registerMcp(client) {
   if (!writer) {
     throw new Error(`registerMcp: client ${client.id} has unknown config format "${client.format}"`);
   }
-  return writer(client);
+  return writer(client, version || packageVersion());
 }
 
 /**
@@ -596,6 +820,85 @@ function mcpRegistrationPresent(client) {
   }
 }
 
+/**
+ * Read the pin currently written in a client's config: an exact version
+ * string, `'unpinned'` (legacy bare `auxilo-mcp` entry, pre-0.9.17), or
+ * `null` when not registered / not an owned shape / config unreadable.
+ * Read-only, never throws (status must never throw on local probes).
+ */
+function mcpPinnedVersion(client) {
+  try {
+    if (client.format === 'toml-codex') {
+      const raw = fs.readFileSync(client.configPath, 'utf-8');
+      const headerIdx = raw.indexOf(CODEX_SECTION_HEADER);
+      if (headerIdx === -1) return null;
+      const { start, end } = codexSectionBounds(raw, headerIdx);
+      const argsMatch = raw.slice(start, end).match(/^args = (\[.*\])$/m);
+      return argsMatch ? parseMcpPin(JSON.parse(argsMatch[1])) : null;
+    }
+    const config = JSON.parse(fs.readFileSync(client.configPath, 'utf-8'));
+    switch (client.format || 'json-mcpServers') {
+      case 'opencode': {
+        const entry = config.mcp && config.mcp.auxilo;
+        return entry && Array.isArray(entry.command) ? parseMcpPin(entry.command.slice(1)) : null;
+      }
+      case 'amp': {
+        const entry = config['amp.mcpServers'] && config['amp.mcpServers'].auxilo;
+        return entry ? parseMcpPin(entry.args) : null;
+      }
+      case 'openhands-stdio': {
+        const entry = Array.isArray(config.stdio_servers) &&
+          config.stdio_servers.find((s) => s && s.name === 'auxilo');
+        return entry ? parseMcpPin(entry.args) : null;
+      }
+      default: {
+        const entry = config.mcpServers && config.mcpServers.auxilo;
+        return entry ? parseMcpPin(entry.args) : null;
+      }
+    }
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * MCP-SERVER-STALENESS (0.9.17): rewrite the Auxilo MCP pin to `version` in
+ * every DETECTED client whose config ALREADY carries a registered Auxilo
+ * entry. Called by lib/runner-autoupdate.js's stageAndSwap after a
+ * successful self-update, so a client's `npx auxilo-mcp@<pin>` tracks the
+ * runner version the self-update just installed instead of drifting stale
+ * until the user re-runs `auxilo setup` by hand.
+ *
+ * Deliberately NEVER registers a client that isn't already registered —
+ * that would silently opt a client the user never selected during
+ * interactive `auxilo setup` into MCP registration from the unattended
+ * self-update path. Reuses registerMcp/MCP_WRITERS, so the same ownership
+ * check applies: an existing entry that isn't recognizably ours
+ * (isOwnedMcpArgs) is left completely untouched, byte-identical.
+ *
+ * @param {string} homeDir
+ * @param {string} version  Target pin (the just-installed package version).
+ * @param {object} [opts]   Forwarded to detectClients (platform/env for tests).
+ * @returns {Array<{id:string, name:string, configPath:string, changed:boolean, status:string, error?:string}>}
+ */
+function rewriteMcpPins(homeDir, version, opts = {}) {
+  if (!homeDir) throw new Error('rewriteMcpPins: homeDir is required');
+  if (!version) throw new Error('rewriteMcpPins: version is required');
+  const results = [];
+  for (const client of detectClients(homeDir, opts).filter((c) => c.mcp)) {
+    if (!mcpRegistrationPresent(client)) continue; // not already registered — never first-register here
+    try {
+      const result = registerMcp(client, version);
+      results.push({ id: client.id, name: client.name, ...result });
+    } catch (err) {
+      // B15 discipline: malformed config — skip loudly, never overwrite,
+      // and never let one bad client config abort the rest of the rewrite.
+      results.push({ id: client.id, name: client.name, configPath: client.configPath, changed: false, status: 'error', error: err.message });
+    }
+  }
+  return results;
+}
+
 // ─── Credentials (spec §LW-12 step 2) ───────────────────────────────────────
 
 function credentialsPath(homeDir) {
@@ -1837,11 +2140,22 @@ async function getStatus(homeDir, opts = {}) {
   if (!homeDir) throw new Error('getStatus: homeDir is required');
   const fetchImpl = opts.fetchImpl || fetch;
 
+  // MCP-SERVER-STALENESS (0.9.17): installed runner version, for the
+  // per-client pin-vs-runner comparison below. null when no runner is
+  // installed yet (pre-setup) — mcpPinStale then stays false for everyone,
+  // same as when the pin can't be read at all.
+  const runnerVersion = installedRunnerVersion(homeDir);
+
   // 1. Clients: detected + whether MCP registration is present
   const clients = detectClients(homeDir, opts).map((c) => {
     // null = not applicable (no MCP config); per-format probe otherwise (UC-0).
     const registered = c.mcp ? mcpRegistrationPresent(c) : null;
     const base = { id: c.id, name: c.name, mcp: c.mcp, registered };
+    if (c.mcp && registered) {
+      const pin = mcpPinnedVersion(c);
+      base.mcpPin = pin; // exact version string, 'unpinned' (legacy), or null (foreign entry)
+      base.mcpPinStale = Boolean(pin && pin !== 'unpinned' && runnerVersion && pin !== runnerVersion);
+    }
     // UC-1: capture-hook probe (shim exists AND hook config references it).
     if (c.captureHook) {
       base.captureHook = true;
@@ -1915,6 +2229,7 @@ async function getStatus(homeDir, opts = {}) {
     accountMode,
     sentinel: sentinelPresent(homeDir),
     runnerInstalled,
+    runnerVersion,
     hookInstalled,
     hookScriptInstalled: fs.existsSync(hookPath),
     hookRegistered,
@@ -2005,6 +2320,12 @@ module.exports = {
   detectClients,
   registerMcp,
   mcpRegistrationPresent,
+  mcpPinnedVersion,
+  rewriteMcpPins,
+  writeJsonAtomic,
+  isOwnedMcpArgs,
+  parseMcpPin,
+  MCP_PACKAGE_NAME,
   readClientConfig,
   RULES_MARKER_BEGIN,
   RULES_MARKER_END,

package/lib/runner-autoupdate.js

@@ -609,6 +609,27 @@ function stageAndSwap(homeDir, extractedPackageDir, installer) {
     }
   }
 
+  // MCP-SERVER-STALENESS (0.9.17): the runner stack install above just
+  // stamped binRoot/VERSION = result.version — rewrite every ALREADY
+  // REGISTERED client's Auxilo MCP pin to match, so `npx auxilo-mcp@<pin>`
+  // tracks the runner version this self-update just installed instead of
+  // drifting stale until the user re-runs `auxilo setup` by hand (the
+  // INSTALL-0828 vector, one level up the stack: an unpinned entry only
+  // refreshed when npx's own cache happened to expire).
+  //
+  // Uses the EXTRACTED tree's own installer (same B2 reasoning as
+  // installRunnerAtomic above — a newer release may register a client
+  // format this running copy doesn't know about yet) and is a BEST-EFFORT
+  // step: the runner swap itself already succeeded by this point and must
+  // not be reported as failed over a client-config quirk. Optional
+  // capability — an extracted tree that predates this function (or a test
+  // fixture's minimal installer stub) simply skips the rewrite.
+  if (typeof extractedInstaller.rewriteMcpPins === 'function') {
+    try {
+      extractedInstaller.rewriteMcpPins(homeDir, result.version);
+    } catch { /* best-effort — the runner swap itself already succeeded */ }
+  }
+
   return binRoot;
 }
 

package/mcp-server.js

@@ -198,7 +198,7 @@ async function postBulkChunks(headers, decisions) {
 }
 
 const server = new Server(
-  { name: 'auxilo', version: '0.9.16' },
+  { name: 'auxilo', version: '0.9.17' },
   {
     capabilities: { tools: {} },
     instructions: `You are connected to Auxilo, a knowledge marketplace where AI agents buy and sell operational learnings.
@@ -1037,6 +1037,25 @@ if (process.argv[2] === 'login') {
     }
   })();
 } else {
+  // MCP-SERVER-STALENESS (0.9.17): ONE stderr notice, printed once at
+  // startup, when this running package's own version differs from the
+  // runner version installer.js last stamped into ~/.auxilo/bin/VERSION —
+  // e.g. this process is a stale cached `npx auxilo-mcp` build while the
+  // runner has already self-updated past it (or vice versa, right after a
+  // fresh `auxilo setup`). No network call, no behaviour change — advisory
+  // only, and silent when the VERSION stamp is absent (no runner installed
+  // yet) or matches.
+  try {
+    const installer = require('./lib/installer.js');
+    const ownVersion = installer.packageVersion();
+    const installedVersion = installer.installedRunnerVersion(os.homedir());
+    if (installedVersion && installedVersion !== ownVersion) {
+      console.error(
+        `[auxilo-mcp] Note: this MCP server is running v${ownVersion}, but the installed runner is v${installedVersion}. Run \`npx auxilo setup\` to re-pin.`
+      );
+    }
+  } catch { /* advisory only — must never block startup */ }
+
   // Normal MCP server startup
   async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auxilo-mcp",
-  "version": "0.9.16",
+  "version": "0.9.17",
   "mcpName": "io.github.silent-architects/auxilo",
   "description": "MCP server for Auxilo. Your agent stops solving the same problem twice: auto-extracted learnings, free self-unlocks, and earnings when other agents unlock yours.",
   "main": "mcp-server.js",