auxilo-mcp 0.9.16 → 0.9.18

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
@@ -573,7 +586,7 @@ async function cmdStatus() {
     );
     if (autoupdateLine) console.log(autoupdateLine);
   }
-  console.log(extractionProviderLine(await providers.resolveProvider({})));
+  console.log(extractionProviderLine(lastRecordedProviderResolution()));
   // Lazy require: scripts/runner.js is a heavier module (sources, sensitivity
   // filter, ops-alert) than this one status line needs at require-time for
   // every CLI invocation.
@@ -612,18 +625,58 @@ function runnerSkewLine(skew) {
  */
 const CLI_CLEAN_LANE_CALIBRATED_PROVIDERS = ['claude-code'];
 
+/**
+ * EXTRACTION-MODEL-PROVENANCE (PUNCH-LIST P1): `auxilo status` used to feed
+ * extractionProviderLine() a LIVE `providers.resolveProvider({})` call — a
+ * fresh detect() answering "what would run right now" (and, on a full scan,
+ * capable of writing ~/.auxilo/providers.json's `selected` field as a side
+ * effect of a status check), not "what actually ran". This function replaces
+ * that with two read-only, no-detect sources of TRUTH, in priority order:
+ * (1) AUXILO_EXTRACTION_PROVIDER, if set, is a certain fact about the
+ *     current session's config — reading it is not a guess — validated
+ *     against providers.PROVIDER_ORDER exactly as resolveProvider() itself
+ *     validates an override, without calling it.
+ * (2) Otherwise, providers.json's `selected` field — the LAST provider a
+ *     genuine resolveProvider() full-scan actually chose and persisted
+ *     (scripts/providers/index.js's persistSelected(), only ever called
+ *     after a real detect() succeeded) — read here with a plain
+ *     fs.readFileSync, no detect() invoked, no possibility of writing.
+ * Neither source can misrepresent "would run" as "ran": (1) is what WILL
+ * run (an explicit operator override, not a probe), and (2) is what was
+ * last recorded to have been selected, honestly labeled as such below.
+ * `{ok:false}` (shown as "no recorded provider selection yet") when neither
+ * source has an answer — e.g. a fresh install that has never extracted.
+ */
+function lastRecordedProviderResolution() {
+  const override = process.env.AUXILO_EXTRACTION_PROVIDER;
+  if (override) {
+    if (providers.PROVIDER_ORDER.includes(override)) return { ok: true, id: override };
+    return {
+      ok: false,
+      reason: `AUXILO_EXTRACTION_PROVIDER="${override}" is not a known provider (expected one of: ${providers.PROVIDER_ORDER.join(', ')})`,
+    };
+  }
+  try {
+    const raw = fs.readFileSync(providers.PROVIDERS_STATE_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    const id = parsed && typeof parsed === 'object' && typeof parsed.selected === 'string' ? parsed.selected : null;
+    if (id) return { ok: true, id };
+  } catch { /* no recorded selection yet, or the file is unreadable/corrupt */ }
+  return { ok: false, reason: 'no recorded provider selection yet' };
+}
+
 /**
  * EXTRACT-PER-CLIENT W1 PART A/C — one unconditional line naming which
- * extraction model provider resolves, why (env override vs auto-detected),
- * and (PART C) whether that provider's submissions can reach the clean-lane
- * auto-publish path at all (server-side gate: lib/clean-lane.js's
- * CLEAN_LANE_CALIBRATED_PROVIDERS, mirrored above).
+ * extraction model provider resolves, why (env override vs last recorded
+ * selection), and (PART C) whether that provider's submissions can reach
+ * the clean-lane auto-publish path at all (server-side gate:
+ * lib/clean-lane.js's CLEAN_LANE_CALIBRATED_PROVIDERS, mirrored above).
  */
 function extractionProviderLine(resolution) {
   if (resolution && resolution.ok) {
     const via = process.env.AUXILO_EXTRACTION_PROVIDER
       ? 'env override AUXILO_EXTRACTION_PROVIDER'
-      : 'auto-detected';
+      : 'last recorded selection';
     const calibration = CLI_CLEAN_LANE_CALIBRATED_PROVIDERS.includes(resolution.id)
       ? 'clean-lane calibrated'
       : 'review-lane only';
@@ -1626,6 +1679,7 @@ module.exports = {
   parseFlags,
   runnerSkewLine,
   extractionProviderLine,
+  lastRecordedProviderResolution,
   resolveBaseUrl,
   shortFlags,
   groupSummaryRows,

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.18' },
   {
     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.18",
   "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",

package/scripts/extract-local.js

@@ -400,37 +400,37 @@ function judgeUsage(usage, prompt, completion) {
 
 /**
  * PART C — resolve the extraction_model identity for a runModel result.
- * Prefers the additive `identity` field a provider's runModel result may
- * carry. Current state (post Gate-A item a): byo-key.js always sets one
- * ({provider:'byo-key', model, version:null, vendor}); codex-cli.js sets one
- * on success ({provider:'codex-cli', model:null, version:<codex --version>,
- * vendor:null} — its result also carries the same object under the
- * deprecated `extraction_model` alias, kept for one release only for
- * test/codex-cli-provider.test.js). claude-code.js is the one provider that
- * still sets no `identity` on its result — that's the case this function's
- * fallback exists for: it re-resolves via providers.resolveProvider() and
- * stamps {provider: resolved.id, model: null, version: null, vendor: null},
- * so every provider gets SOME stamp, never silently none. That re-resolution
- * walks scripts/providers/index.js's PROVIDER_ORDER (claude-code →
- * codex-cli → byo-key); resolveProvider/runModel there fall through from one
- * provider to the next only on a NON_RETRYABLE_FOR_THIS_PROVIDER reasonCode
- * (unauthenticated, not installed, a billing helper configured, an
- * unconfigured BYO key, or an unsafe providers.json mode) — a provider that
- * merely failed once (a timeout, a model error) is not retried under a
- * different one. Best-effort throughout: a resolution failure here must
- * never block extraction itself.
+ *
+ * EXTRACTION-MODEL-PROVENANCE (PUNCH-LIST P1): this function used to fall
+ * back to a FRESH, INDEPENDENT providers.resolveProvider() call whenever the
+ * result carried no `identity` — a re-detect decoupled from which provider
+ * actually produced `runModelResult`, which is what "what would run now"
+ * answers, not "what ran". That re-resolve could also silently rewrite
+ * `~/.auxilo/providers.json` (resolveProvider's full-scan path calls
+ * persistSelected) from what should have been a read-only identity lookup.
+ * Both are gone. `identity` is now ALWAYS attached by
+ * scripts/providers/index.js's runModel() itself — centrally, because that
+ * registry is the only thing that knows which module it actually invoked
+ * for this call (see its withIdentity()/deriveIdentity() — claude-code's own
+ * cliVersion is used there when present, richer than the null/null/null
+ * triple this function used to guess). This function's job shrinks to: use
+ * the identity the result actually carries, or admit the honest
+ * `provider:'unknown'` when none exists (the `no-usable-provider` /
+ * bad-override-name aggregate failures — nothing actually ran to
+ * completion, so there is nothing to attribute). Never re-derives, never
+ * writes, never blocks extraction on failure.
  */
-async function resolveExtractionModelIdentity(runModelResult, opts) {
-  if (runModelResult && runModelResult.identity && typeof runModelResult.identity === 'object') {
+function resolveExtractionModelIdentity(runModelResult) {
+  if (
+    runModelResult
+    && runModelResult.identity
+    && typeof runModelResult.identity === 'object'
+    && typeof runModelResult.identity.provider === 'string'
+    && runModelResult.identity.provider
+  ) {
     return runModelResult.identity;
   }
-  try {
-    const resolved = await providers.resolveProvider(opts);
-    if (resolved && resolved.ok && resolved.id) {
-      return { provider: resolved.id, model: null, version: null, vendor: null };
-    }
-  } catch { /* identity is best-effort; never block extraction on it */ }
-  return null;
+  return { provider: 'unknown', model: null, version: null, vendor: null };
 }
 
 /**
@@ -456,7 +456,7 @@ async function defaultInvokeModel(transcript, invokeOpts, opts) {
     reason: result.reason,
     reasonCode: result.reasonCode,
     authStatus: result.authStatus,
-    extractionModel: await resolveExtractionModelIdentity(result, opts),
+    extractionModel: resolveExtractionModelIdentity(result),
     ...(result.authDiscrepancy !== undefined && { authDiscrepancy: result.authDiscrepancy }),
     // EXTRACTION-RUN-LOG (0.9.15): additive passthrough for the one-line-per-run
     // provider summary logged at the end of extractLocally() below. Only
@@ -704,12 +704,53 @@ function formatArgvForLog(argv) {
  * (spawned) this run, not whether it succeeded — a spawn that ran and then
  * hit a model error still counts as "ran" (it happened; the failure is in
  * `reason`, not in whether isolation applied). `hooks` is `claude-code`-
- * specific: 'isolated' whenever a claude-code spawn this run carried
- * --setting-sources (the only state a spawn can be in per the fail-closed
- * gate in scripts/providers/claude-code.js — it never spawns without the
- * flag), 'unsupported' when the CLI was found not to support the flag at
- * all, 'n/a' for a non-claude-code provider (codex-cli/byo-key isolate by a
- * different mechanism entirely, out of this row's scope).
+ * specific and EVIDENCE-DERIVED (EXTRACT-LOG-HOOKS-EVIDENCE, PUNCH-LIST P2):
+ * it reads the argv this run actually captured rather than inferring
+ * isolation from the provider name plus the absence of a reason code —
+ * 'isolated' ONLY when that argv literally contains --setting-sources (the
+ * flag scripts/providers/claude-code.js's fail-closed gate never spawns
+ * without), 'unsupported' when the CLI was found not to support the flag at
+ * all (existing reason-code path, unchanged), 'unknown' when no argv was
+ * captured this run (finder skipped pre-spawn, or the run that actually
+ * produced this result fell through to a different/no provider — see the
+ * EXTRACT-LOG-HOOKS-EVIDENCE root-cause note below), and 'n/a' for a
+ * non-claude-code provider (codex-cli/byo-key isolate by a different
+ * mechanism entirely, out of this row's scope). Never 'isolated' without an
+ * argv carrying the flag in hand — a safety claim needs evidence, not an
+ * absence of contrary evidence.
+ *
+ * Root cause of the missing-argv runs (EXTRACT-LOG-HOOKS-EVIDENCE
+ * investigation): claude-code.js's own runExtractMode() never omits argv on
+ * a claude-code result that actually reached this line — every return after
+ * `const argv = EXTRACT_MODE_ARGV` carries it, and the two pre-spawn
+ * short-circuits that don't (cached --setting-sources-unsupported,
+ * cli-unauthenticated) both carry reasonCodes already in
+ * PRE_SPAWN_SKIP_REASON_CODES, so they render finder=skipped, not ran. The
+ * observed defect lines (finder=ran, flags=n/a) come from a DIFFERENT case:
+ * scripts/providers/index.js's runModel() falls through from claude-code to
+ * the next configured provider (e.g. codex-cli) whenever claude-code's own
+ * attempt fails with a NON_RETRYABLE_FOR_THIS_PROVIDER reasonCode, and
+ * returns that OTHER provider's result directly when it stops there. That
+ * provider's result carries no `argv` field at all (argv is a
+ * claude-code-only concept), so there is no shipped argv being hidden here —
+ * 'unknown' remains the correct, honest `hooks` value regardless of which
+ * provider is named.
+ *
+ * EXTRACTION-MODEL-PROVENANCE (PUNCH-LIST P1) closed the mismatch this
+ * docblock used to describe as a known, deferred gap: a fallthrough
+ * provider's result used to reach this function carrying no `identity` on
+ * failure (codex-cli/byo-key only self-stamped on success), so
+ * resolveExtractionModelIdentity()'s old fallback re-resolved the label via
+ * a FRESH, INDEPENDENT providers.resolveProvider() call — decoupled from
+ * which provider's runModel() result was actually being logged, and prone to
+ * landing back on 'claude-code' (its detect() only checks the
+ * billing-helper gate + auth status, not whether the earlier attempt
+ * actually spawned). That fallback is gone. `identity` is now attached
+ * centrally by providers/index.js's runModel() to EVERY result it returns —
+ * success or failure, fallthrough or not — because that registry alone
+ * knows which module it actually invoked for a given attempt. The line this
+ * function renders now names the provider that actually ran (or 'unknown'
+ * only when nothing did), not a guess.
  */
 function logProviderRunSummary(opts, runId, modelResult, judged) {
   try {
@@ -725,8 +766,11 @@ function logProviderRunSummary(opts, runId, modelResult, judged) {
     const cliVersion = modelResult.cliVersion || (judged && judged.judgeCliVersion) || null;
     const finderUnsupported = modelResult.reasonCode === 'cli-settings-isolation-unsupported';
     const judgeUnsupported = Boolean(judged && judged.judgeReasonCode === 'cli-settings-isolation-unsupported');
+    const hasSettingSourcesArgv = Array.isArray(argv) && argv.includes('--setting-sources');
     const hooks = provider === 'claude-code'
-      ? ((finderUnsupported || judgeUnsupported) ? 'unsupported' : 'isolated')
+      ? ((finderUnsupported || judgeUnsupported)
+        ? 'unsupported'
+        : (hasSettingSourcesArgv ? 'isolated' : 'unknown'))
       : 'n/a';
     log(
       `[providers] run=${runId || 'unknown'} provider=${provider} cli=${cliVersion || '-'} ` +
@@ -875,4 +919,7 @@ module.exports = {
   resolveClaudeBin: claudeCodeProvider.resolveClaudeBin,
   // EXTRACTION-RUN-LOG (0.9.15) — exported for direct unit coverage.
   formatArgvForLog, logProviderRunSummary, PRE_SPAWN_SKIP_REASON_CODES,
+  // EXTRACTION-MODEL-PROVENANCE (PUNCH-LIST P1) — exported for direct unit
+  // coverage of the "never guess, fail closed to unknown" contract.
+  resolveExtractionModelIdentity,
 };

package/scripts/providers/index.js

@@ -245,6 +245,92 @@ const NON_RETRYABLE_FOR_THIS_PROVIDER = new Set([
   'cli-settings-isolation-unsupported',
 ]);
 
+/**
+ * EXTRACTION-MODEL-PROVENANCE (PUNCH-LIST P1, follow-up to the
+ * EXTRACT-LOG-HOOKS-EVIDENCE row): `identity` on a runModel() result is
+ * provenance — a record of which provider actually produced this text — not
+ * a guess. It must never be re-derived after the fact from a fresh detect(),
+ * because a fresh detect() answers "what would run now", not "what ran".
+ * This registry is the only thing that KNOWS which module's runModel() it
+ * just invoked for a given attempt, so identity is enforced HERE, centrally,
+ * rather than trusted to per-provider convention (the gap this row closes:
+ * before this fix, a provider `ok:true` return that forgot to attach
+ * `identity` would silently fall through to extract-local.js's
+ * resolveExtractionModelIdentity() re-detecting via resolveProvider() —
+ * decoupled from which module actually ran).
+ */
+function hasUsableIdentity(identity) {
+  return Boolean(
+    identity
+    && typeof identity === 'object'
+    && typeof identity.provider === 'string'
+    && identity.provider
+  );
+}
+
+/**
+ * Derive an identity for the module actually invoked as `id`, used only when
+ * that module's own result didn't already carry one. The derivation differs
+ * by outcome, because a SUCCESS identity can reach a published learning and
+ * the clean-lane calibration gate, while a FAILURE identity is purely
+ * diagnostic (extract-local.js returns before stamping anything onto a
+ * candidate on `ok:false` — see its `:824-834`):
+ *
+ * - claude-code: always gets a real, provider-specific identity — it
+ *   already has `cliVersion` in hand on every returned result (success or
+ *   failure), richer than the null/null/null triple this used to guess, and
+ *   claude-code is the one provider documented to never self-stamp
+ *   `identity` at all, so this is filling a KNOWN, structural gap, not
+ *   papering over a violated contract.
+ * - Every other provider on a FAILURE: `{provider:id, model:null,
+ *   version:null, vendor:null}` — naming the module we actually invoked is
+ *   a plain structural fact (we chose to call it), not a guess, and it is
+ *   what lets the per-run `[providers]` log name the provider that actually
+ *   ran even when that provider's own failure return carries no identity
+ *   (codex-cli and byo-key only self-stamp on their SINGLE success return —
+ *   this is the exact fall-through failure case the investigation traced:
+ *   claude-code skipped, codex-cli ran and failed, no identity of its own,
+ *   the label used to be re-guessed as claude-code by the old fallback).
+ * - Every other provider on a SUCCESS: `{provider:'unknown', ...}` —
+ *   byo-key.js and codex-cli.js both self-stamp `identity` on their only
+ *   success return BY CONTRACT; a success with none means that contract was
+ *   violated, so this registry has no provider-reported basis for the
+ *   claim. Confidently naming the module here would look like provenance
+ *   without being backed by anything the provider itself reported — since
+ *   this stamp CAN reach a published learning, the fail-closed, honest
+ *   answer is 'unknown', never a guess dressed up as a fact.
+ */
+function deriveIdentity(id, result) {
+  if (id === 'claude-code') {
+    return {
+      provider: 'claude-code',
+      model: null,
+      version: (result && result.cliVersion) || null,
+      vendor: 'anthropic',
+    };
+  }
+  if (!(result && result.ok)) {
+    return { provider: id, model: null, version: null, vendor: null };
+  }
+  return { provider: 'unknown', model: null, version: null, vendor: null };
+}
+
+/**
+ * Attach a derived identity to `result` IFF it doesn't already carry a
+ * usable one — never overwrites a provider-reported identity (e.g.
+ * byo-key's real model name). Applied to every result this registry
+ * returns, success or failure, so the per-run `[providers]` log
+ * (scripts/extract-local.js's logProviderRunSummary) names the provider
+ * that actually ran even on a failure — that is the fall-through failure
+ * case this row's investigation traced (claude-code skipped, codex-cli ran
+ * and failed with no identity of its own, the stamp used to be re-guessed
+ * as claude-code by the caller).
+ */
+function withIdentity(id, result) {
+  if (hasUsableIdentity(result && result.identity)) return result;
+  return { ...result, identity: deriveIdentity(id, result) };
+}
+
 /**
  * runModel(opts) — resolve a starting provider via resolveProvider(), then
  * walk PROVIDER_ORDER from there, calling each candidate's OWN runModel()
@@ -262,7 +348,9 @@ const NON_RETRYABLE_FOR_THIS_PROVIDER = new Set([
  * as-is. When every provider tried is exhausted, returns reasonCode
  * 'no-usable-provider' with a bounded summary of every provider's reason in
  * `reason` (no secrets — each provider's own reason string is already
- * secret-free by contract). Never throws.
+ * secret-free by contract) and NO identity — nothing actually ran to
+ * completion, so the caller (extract-local.js) stamps `provider:'unknown'`
+ * rather than have this registry guess one. Never throws.
  */
 async function runModel(opts = {}) {
   const mode = opts.mode === 'judge' ? 'judge' : 'extract';
@@ -281,7 +369,8 @@ async function runModel(opts = {}) {
         authStatus: 'unknown',
       };
     }
-    return resolved.module.runModel({ ...opts, mode });
+    const result = await resolved.module.runModel({ ...opts, mode });
+    return withIdentity(resolved.id, result);
   }
 
   const log = typeof opts.log === 'function' ? opts.log : console.error;
@@ -293,7 +382,8 @@ async function runModel(opts = {}) {
   for (const id of order) {
     const mod = PROVIDERS[id];
     // eslint-disable-next-line no-await-in-loop
-    const result = await mod.runModel({ ...opts, mode });
+    const rawResult = await mod.runModel({ ...opts, mode });
+    const result = withIdentity(id, rawResult);
     if (result.ok) return result;
     attempts.push({ id, reasonCode: result.reasonCode, reason: result.reason });
     if (!NON_RETRYABLE_FOR_THIS_PROVIDER.has(result.reasonCode)) {