@event4u/agent-config 14.19.0 → 14.21.0

package/src/scripts/_lib/blocked_by_marker.ts

@@ -0,0 +1,189 @@
+/**
+ * Ask before park — the inline `blocked-by:` marker, and the decision that must
+ * precede writing one.
+ *
+ * road-to-asked-not-parked Phase 3. `terminal-states.md` defines `blocked` to
+ * include "a decision only the user can make", and `roadmap-process-loop.md`
+ * writes and reads the inline marker with NO ask in between. The result is a
+ * decision the user never sees: it is filed, correctly labelled, in a file
+ * nobody is watching.
+ *
+ * This module is the executable half of the fix. It answers two questions and
+ * nothing else:
+ *
+ *   1. Given a context — is the host interactive, was the question put, was it
+ *      answered, did it time out — what does the run DO? ({@link decideAsk})
+ *   2. What does the marker then look like? ({@link renderBlockedByMarker})
+ *
+ * The obligations it encodes:
+ *
+ * - On an interactive host a user-decision block is PUT TO THE USER FIRST. Only
+ *   a decline, a timeout, or a non-interactive context writes a marker.
+ * - A TIMEOUT IS NOT CONSENT, and neither is a non-interactive context. Where
+ *   the ask cannot be completed the run ends `approval-required` — a state
+ *   `terminal-states.md` already defines — carrying the unanswered question
+ *   verbatim and its conservative default UNADOPTED. Nothing here ever returns
+ *   the default as an answer.
+ * - The marker records WHETHER the question was put, and when it was not, WHY.
+ *   `asked: no` with no reason is not a legal marker: the whole point is that a
+ *   later reader can tell a decision that was declined from one that was never
+ *   offered.
+ */
+import type { RunTerminalState } from './outcome_vocabularies.js';
+
+/** A parsed inline `<!-- blocked-by: … -->` marker. */
+export interface BlockedByMarker {
+    /** The blocker id the marker points at. */
+    readonly id: string;
+    /** Whether the question was put to the user. `null` when the marker predates the field. */
+    readonly asked: boolean | null;
+    /** Why it was not put. Required whenever `asked` is `false`. */
+    readonly reason: string | null;
+}
+
+/**
+ * The marker grammar, extended with an optional `| asked: …` tail.
+ *
+ * The tail is OPTIONAL in the grammar and required by the linter for the
+ * user-decision class only. Parsing and policy are separated on purpose: a
+ * parser that rejects the old shape would make every archived roadmap
+ * unreadable, which is a migration, not a fix.
+ */
+export const BLOCKED_BY_MARKER_RE =
+    /<!--[ \t]*blocked-by:[ \t]*([a-z0-9-]+)[ \t]*(?:\|[ \t]*asked:[ \t]*(yes|no)[ \t]*(?:[—-][ \t]*([^>]*?))?[ \t]*)?-->/i;
+
+/** Parse one marker, or `null` when the text carries none. */
+export function parseBlockedByMarker(text: string): BlockedByMarker | null {
+    const m = BLOCKED_BY_MARKER_RE.exec(text);
+    if (m === null) {
+        return null;
+    }
+    const asked = m[2] === undefined ? null : m[2].toLowerCase() === 'yes';
+    const reason = m[3] === undefined || m[3].trim() === '' ? null : m[3].trim();
+    return { id: (m[1] as string).toLowerCase(), asked, reason };
+}
+
+/** Render a marker. Throws on `asked: no` with no reason — the state the field exists to prevent. */
+export function renderBlockedByMarker(marker: BlockedByMarker): string {
+    if (marker.asked === null) {
+        return `<!-- blocked-by: ${marker.id} -->`;
+    }
+    if (marker.asked) {
+        return `<!-- blocked-by: ${marker.id} | asked: yes -->`;
+    }
+    const reason = (marker.reason ?? '').trim();
+    if (reason === '') {
+        throw new Error(
+            `blocked-by marker for '${marker.id}': asked: no needs a reason — ` +
+                'a marker that does not say why the question was not put is the parking ' +
+                'lot this field exists to end',
+        );
+    }
+    return `<!-- blocked-by: ${marker.id} | asked: no — ${reason} -->`;
+}
+
+/** What the run knows when it reaches a step blocked on a user decision. */
+export interface AskContext {
+    /** The blocker id. */
+    readonly id: string;
+    /** The question, in the words it would be put in. */
+    readonly question: string;
+    /** The conservative option, named so a reader can see what was NOT adopted. */
+    readonly conservativeDefault: string;
+    /** Can this run reach the user at all? */
+    readonly interactive: boolean;
+    /** Why not, when it cannot. Required whenever `interactive` is `false`. */
+    readonly nonInteractiveReason?: string | undefined;
+    /** The user's answer, when one arrived. */
+    readonly answer?: string | undefined;
+    /** The ask was put and no answer came back. */
+    readonly timedOut?: boolean | undefined;
+}
+
+/** What the run does next. */
+export interface AskDecision {
+    /**
+     * `ask` — put the question and come back with an answer or a timeout.
+     * `answered` — an answer exists; nothing is parked.
+     * `park` — write the marker; the run may continue with other steps.
+     * `approval-required` — the run stops and hands the unanswered question back.
+     */
+    readonly action: 'ask' | 'answered' | 'park' | 'approval-required';
+    /** The terminal state to report, when this decision ends the run. */
+    readonly terminal: RunTerminalState | null;
+    /** The marker to write, when one is written. */
+    readonly marker: string | null;
+    /** The text the run puts in front of the user. Never a silent default. */
+    readonly surfaced: string | null;
+    /** Whether the conservative default was adopted. ALWAYS false — see the module header. */
+    readonly defaultAdopted: false;
+}
+
+/**
+ * Decide, for one user-decision block, whether to ask, park, or stop.
+ *
+ * Order matters: an ANSWER wins over everything, then a timeout, then a
+ * non-interactive context, then the interactive path. A timeout is checked
+ * before interactivity so a run that asked and got nothing is never quietly
+ * re-classified as "could not ask".
+ */
+export function decideAsk(ctx: AskContext): AskDecision {
+    const unanswered =
+        `${ctx.question}\n\nConservative option (NOT adopted): ${ctx.conservativeDefault}`;
+
+    if (ctx.answer !== undefined && ctx.answer.trim() !== '') {
+        return {
+            action: 'answered',
+            terminal: null,
+            marker: null,
+            surfaced: null,
+            defaultAdopted: false,
+        };
+    }
+
+    if (ctx.timedOut === true) {
+        return {
+            action: 'approval-required',
+            terminal: 'approval-required',
+            marker: renderBlockedByMarker({
+                id: ctx.id,
+                asked: true,
+                reason: null,
+            }),
+            surfaced: unanswered,
+            defaultAdopted: false,
+        };
+    }
+
+    if (!ctx.interactive) {
+        const why = (ctx.nonInteractiveReason ?? '').trim();
+        return {
+            action: 'park',
+            terminal: null,
+            marker: renderBlockedByMarker({
+                id: ctx.id,
+                asked: false,
+                reason: why === '' ? 'non-interactive context, reason not recorded' : why,
+            }),
+            surfaced: unanswered,
+            defaultAdopted: false,
+        };
+    }
+
+    return {
+        action: 'ask',
+        terminal: null,
+        marker: null,
+        surfaced: ctx.question,
+        defaultAdopted: false,
+    };
+}
+
+/**
+ * The user declined to decide. That IS an answer about the ask — the question
+ * was put — so the marker records `asked: yes` and the decline is the reason
+ * the step stays blocked.
+ */
+export function parkAfterDecline(id: string): string {
+    return renderBlockedByMarker({ id, asked: true, reason: null });
+}

package/src/scripts/_lib/host_capability.ts

@@ -67,6 +67,50 @@ export interface HostCapabilityManifest {
      * stop-loss behaviour — loudly, never silently.
      */
     worker_respawn: boolean;
+    /**
+     * The host exposes its own structured-ask tool — a native question picker
+     * the agent can call instead of rendering a numbered-options block as prose.
+     *
+     * A STRICT BOOLEAN, and the per-host detail deliberately lives elsewhere.
+     * The source draft for road-to-asked-not-parked proposed a nested object
+     * carrying the tool name and the question/option ceilings; `asBool` below
+     * coerces every non-`true` value to `false`, so such an object would
+     * normalize silently to nothing. The shape lives in
+     * `_lib/structured_ask.ts` (`STRUCTURED_ASK_SHAPES`), which a caller reads
+     * explicitly; this field answers only whether there is anything to read.
+     *
+     * `false` is the safe default on purpose: an unknown host degrades to a
+     * text ask, and the agent never fires a tool call into a host that has no
+     * such tool.
+     */
+    structured_ask: boolean;
+    /**
+     * The host reads a PROJECT-scope MCP config file (`.mcp.json` or its
+     * per-host equivalent) and starts the servers it names.
+     *
+     * Added because nothing in this tree could answer it: the installer writes
+     * `.mcp.json` for `claude-code` alone while writing other hosts' config
+     * files for hooks, and no code could say whether that omission was a
+     * measured absence or an unasked question.
+     *
+     * Same discipline as `worker_respawn`: `true` only once OBSERVED on a host,
+     * never inferred from the fact that a host supports MCP at all — a host may
+     * read a user-scope config and ignore a project one, which is precisely the
+     * distinction a consumer needs and the one an inference would erase.
+     */
+    reads_project_mcp_config: boolean;
+    /**
+     * The host requires a human action after installation before the MCP server
+     * is live — an approval dialog, a restart, a manual enable.
+     *
+     * `true` is the SAFE default here, and it is the opposite of every other
+     * field in this manifest. The others answer "can the host do X", where an
+     * unknown must not read as a capability. This one answers "is there a step
+     * left for the user", where an unknown must not read as "nothing to do":
+     * an install that silently omits a required step leaves a server nobody
+     * started and no message saying so.
+     */
+    mcp_needs_manual_activation: boolean;
 }
 
 /** Safe default — unknown host assumes no subagent primitive. */
@@ -78,6 +122,11 @@ const SAFE_DEFAULT: HostCapabilityManifest = {
     separate_quota_pool: false,
     agent_teams: false,
     worker_respawn: false,
+    structured_ask: false,
+    reads_project_mcp_config: false,
+    // `true` because the safe answer here is "there is still a step", not
+    // "there is nothing to do" — see the field's own note.
+    mcp_needs_manual_activation: true,
 };
 
 /** Coerce one field: only a strict boolean `true` survives; everything else is `false`. */
@@ -106,6 +155,12 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
         separate_quota_pool: asBool(src.separate_quota_pool),
         agent_teams: asBool(src.agent_teams),
         worker_respawn: asBool(src.worker_respawn),
+        structured_ask: asBool(src.structured_ask),
+        reads_project_mcp_config: asBool(src.reads_project_mcp_config),
+        // Inverted coercion, matching the inverted default: only an explicit
+        // `false` clears the residual, so an absent or malformed value keeps
+        // the manual step visible instead of silently dropping it.
+        mcp_needs_manual_activation: src.mcp_needs_manual_activation !== false,
     };
 }
 
@@ -179,9 +234,26 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
  *
  * `agent_teams` — out of scope for a row by construction; see its own field
  *   doc comment and the protocol section.
+ *
+ * `structured_ask: false` — OBSERVED ABSENT, not never-looked, and the
+ *   difference is why it is written rather than omitted. claude (Claude Code
+ *   2.1.263, Opus 5 1M session, 2026-09-07). The host delivers the session's
+ *   tool surface at session start; that surface carried no structured-ask tool
+ *   under any name `_lib/structured_ask.ts` matches, and no per-host shape is
+ *   recorded for it in `STRUCTURED_ASK_SHAPES`. Artefact:
+ *   `agents/evidence/analysis/structured-ask-host-observation-2026-09.md`.  code-comment-allow provenance-comment -- the observation protocol declares a row inadmissible without its artefact citation, so this pointer is part of the contract the row satisfies, not evidence duplicated from a roadmap
+ *   The observation is about the delivered surface of one session on one
+ *   version; it is not a claim that the vendor ships no such tool anywhere,
+ *   and a later session observing one writes the `true` row over it.
+ *
+ * NO ROW ANYWHERE SETS THE STRUCTURED-ASK FIELD TRUE, and the observation
+ * protocol above is the only path to the first one that does. A vendor's
+ * documentation is not that path — and the phrasing here avoids the literal
+ * key-value pair on purpose, because the roadmap step that ships this field
+ * verifies the absence with a grep for exactly that string.
  */
 const HOST_CAPABILITY_REGISTRY: Readonly<Record<string, Partial<HostCapabilityManifest>>> = {
-    claude: { subagent_spawn: true, parallel_spawn: true },
+    claude: { subagent_spawn: true, parallel_spawn: true, structured_ask: false },
 };
 
 /**
@@ -287,6 +359,9 @@ const CAPABILITY_FIELDS: readonly CapabilityField[] = [
     'separate_quota_pool',
     'agent_teams',
     'worker_respawn',
+    'structured_ask',
+    'reads_project_mcp_config',
+    'mcp_needs_manual_activation',
 ];
 
 /**

package/src/scripts/_lib/install_reach_checks.ts

@@ -34,6 +34,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import type { WiringCheck } from './runtime_wiring_checks.js';
+import { TOOL_TO_HOST, residualReport } from './mcp_consent_residual.js';
 
 /**
  * Root agent-instruction files, as a multi-vendor ecosystem convention rather
@@ -477,11 +478,41 @@ export function checkOverrideSet(projectRoot: string): WiringCheck {
     };
 }
 
+/**
+ * Step 3.2 — what remains non-automatic per host, and where that came from.
+ *
+ * Belongs to reach rather than to a doctor-local check because that is what it
+ * measures: the gap between "installed" and "actually running". A residual is
+ * exactly the distance the install did not cover.
+ *
+ * Reports the residual, never a checklist of what worked — a list of successes
+ * is noise a reader has to filter, while a named residual is the one thing they
+ * can act on. An UNRECORDED host warns too, because "nobody checked" must not
+ * read as "nothing to do".
+ */
+export function checkMcpConsentResidual(): WiringCheck {
+    const id = 'mcp-consent-residual';
+    const lines = residualReport(Object.keys(TOOL_TO_HOST));
+    if (lines.length === 0) {
+        return { id, status: 'ok', message: 'no MCP consent residual recorded for any known host', remedy: '' };
+    }
+    const actionable = lines.filter((l) => l.state === 'residual');
+    return {
+        id,
+        status: 'warn',
+        message: lines.map((l) => l.text).join(' · '),
+        remedy:
+            actionable.length > 0
+                ? 'complete the step named above on each host you use'
+                : 'record an observation for the unchecked hosts, or ignore if you do not use them',
+    };
+}
+
 // ---------------------------------------------------------------------------
 // Wiring — the shape `cmd_doctor` consumes
 // ---------------------------------------------------------------------------
 
-export const REACH_CHECK_IDS = ['instruction-path-reach', 'version-axis', 'override-set'] as const;
+export const REACH_CHECK_IDS = ['instruction-path-reach', 'version-axis', 'override-set', 'mcp-consent-residual'] as const;
 
 export function reachRunners(opts: {
     projectRoot: string;
@@ -491,5 +522,6 @@ export function reachRunners(opts: {
         'instruction-path-reach': () => checkInstructionPaths(opts.projectRoot),
         'version-axis': () => checkVersionAxis(opts.projectRoot, opts.resolvableVersion),
         'override-set': () => checkOverrideSet(opts.projectRoot),
+        'mcp-consent-residual': () => checkMcpConsentResidual(),
     };
 }

package/src/scripts/_lib/mcp_bridge.ts

@@ -15,6 +15,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { probeHostCapabilities } from './host_capability.js';
 
 /** `install.ts`'s deploy tuple: [written, skipped, status, paths]. */
 export type DeployTuple = [number, number, string, string[]];
@@ -35,14 +36,43 @@ export type MergeJsonFile = (
  * installer end up with the same entry rather than two that drift.
  */
 export const MCP_SERVER_KEY = 'agent-config';
-export const MCP_BRIDGE_ENTRY = {
-    mcpServers: {
-        [MCP_SERVER_KEY]: {
-            command: 'npx',
-            args: ['-y', '@event4u/agent-config', 'mcp-server'],
+export const MCP_PACKAGE_NAME = '@event4u/agent-config';
+
+/**
+ * The entry, pinned to the version the installer is running from.
+ *
+ * Unpinned, `npx -y @event4u/agent-config` resolves the `latest` dist-tag on
+ * every server start, so the server a consumer runs is whatever the registry
+ * served most recently — not the one their installer approved, and not the one
+ * their lockfile records. The pin makes those the same artefact.
+ *
+ * A version that cannot be read is left unpinned rather than guessed: an
+ * invented specifier would fail to resolve at server start, which is a worse
+ * failure than the drift it was meant to close.
+ */
+export function mcpBridgeEntry(packageRoot: string): Record<string, unknown> {
+    const version = readPackageVersion(packageRoot);
+    const spec = version === null ? MCP_PACKAGE_NAME : `${MCP_PACKAGE_NAME}@${version}`;
+    return {
+        mcpServers: {
+            [MCP_SERVER_KEY]: {
+                command: 'npx',
+                args: ['-y', spec, 'mcp-server'],
+            },
         },
-    },
-};
+    };
+}
+
+/** The manifest `version`, or `null` when it is absent or unreadable. */
+export function readPackageVersion(packageRoot: string): string | null {
+    try {
+        const raw = fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8');
+        const v = (JSON.parse(raw) as { version?: unknown }).version;
+        return typeof v === 'string' && v.trim() !== '' ? v : null;
+    } catch {
+        return null;
+    }
+}
 
 /**
  * `.mcp.json` — the project-scope MCP config Claude Code reads.
@@ -66,9 +96,191 @@ export const MCP_BRIDGE_ENTRY = {
  */
 export function makeEnsureMcpBridge(
     mergeJsonFile: MergeJsonFile,
-): (projectRoot: string, force: boolean) => Record<string, unknown>[] {
-    return (projectRoot, force) =>
-        mergeJsonFile(path.join(projectRoot, '.mcp.json'), MCP_BRIDGE_ENTRY, force, '.mcp.json');
+): (projectRoot: string, force: boolean, packageRoot?: string) => Record<string, unknown>[] {
+    return (projectRoot, force, packageRoot = projectRoot) =>
+        mergeJsonFile(
+            path.join(projectRoot, '.mcp.json'),
+            mcpBridgeEntry(packageRoot),
+            force,
+            '.mcp.json',
+        );
+}
+
+/**
+ * Where each host reads a PROJECT-scope MCP config, and which capability-manifest
+ * row gates writing to it (roadmap step 3.3).
+ *
+ * Keyed by the installer's `--tools` id; `hostId` is the SEPARATE
+ * platform identifier the capability manifest is keyed by (`claude`, not
+ * `claude-code`). Conflating the two namespaces is the mistake
+ * `host_capability.ts` warns about in its own registry doc, so the mapping is
+ * written out rather than derived.
+ *
+ * Presence in this table is NOT permission to write. It records where the file
+ * would go IF the axis said the host reads one; the axis decides, and it says
+ * `true` only once someone observed it.
+ */
+export const MCP_PROJECT_CONFIG: Readonly<Record<string, { hostId: string; relPath: string }>> = {
+    'claude-code': { hostId: 'claude', relPath: '.mcp.json' },
+    cursor: { hostId: 'cursor', relPath: '.cursor/mcp.json' },
+    'gemini-cli': { hostId: 'gemini', relPath: '.gemini/settings.json' },
+};
+
+/** One host to register, resolved from the `--tools` set and the capability axis. */
+export interface McpRegistrationTarget {
+    toolId: string;
+    hostId: string;
+    relPath: string;
+}
+
+/** Injectable capability reader — the installer passes the real probe. */
+export type ReadsProjectMcpConfig = (hostId: string) => boolean;
+
+/**
+ * The hosts an install may register the server on, beyond `claude-code`.
+ *
+ * TWO gates, both required. `--tools` is the consumer's selection; the
+ * capability axis is the evidence. A host is registered only where BOTH say so,
+ * so a config file this package already writes for hooks does not silently
+ * acquire an MCP entry on the strength of the file existing.
+ *
+ * `claude-code` is excluded here on purpose: its `.mcp.json` registration
+ * predates the axis and is written unconditionally by `makeEnsureMcpBridge`.
+ * Routing it through the axis would DELETE a working registration, because the
+ * axis reports `false` for every host today — "nobody answered", not "checked
+ * and absent". This function adds reach; it never removes any.
+ *
+ * MEASURED STATE, 2026-09-07: the capability registry carries one row
+ * (`claude`) and it does not set `reads_project_mcp_config`, so this returns an
+ * EMPTY list for every `--tools` set. That is the honest reading of the axis,
+ * not a defect in this function — and it is a recorded absence, never a finding
+ * that these hosts do not read such a file.
+ */
+export function mcpRegistrationTargets(
+    tools: ReadonlySet<string>,
+    readsConfig: ReadsProjectMcpConfig,
+): McpRegistrationTarget[] {
+    const out: McpRegistrationTarget[] = [];
+    for (const [toolId, spec] of Object.entries(MCP_PROJECT_CONFIG)) {
+        if (toolId === 'claude-code') continue;
+        if (!tools.has(toolId)) continue;
+        if (!readsConfig(spec.hostId)) continue;
+        out.push({ toolId, hostId: spec.hostId, relPath: spec.relPath });
+    }
+    return out;
+}
+
+/**
+ * Merge the server entry into every target's config file.
+ *
+ * Returns the merged keys per tool id, in the shape the installer's
+ * `merged_keys_by_tool` lockfile record expects. An empty map is the normal
+ * result today and is not an error.
+ */
+export function makeEnsureMcpRegistrations(
+    mergeJsonFile: MergeJsonFile,
+): (
+    projectRoot: string,
+    force: boolean,
+    packageRoot: string,
+    targets: readonly McpRegistrationTarget[],
+) => Record<string, Record<string, unknown>[]> {
+    return (projectRoot, force, packageRoot, targets) => {
+        const merged: Record<string, Record<string, unknown>[]> = {};
+        for (const t of targets) {
+            merged[t.toolId] = mergeJsonFile(
+                path.join(projectRoot, ...t.relPath.split('/')),
+                mcpBridgeEntry(packageRoot),
+                force,
+                t.relPath,
+            );
+        }
+        return merged;
+    };
+}
+
+/** The axis reader the installer uses. Injected in tests, never overridden there. */
+function readsProjectMcpConfig(hostId: string): boolean {
+    return probeHostCapabilities(hostId).reads_project_mcp_config;
+}
+
+/**
+ * Write every MCP registration one install owes, and record the merged keys.
+ *
+ * ONE call site rather than three, because `install.ts` is 3,900 lines over the
+ * source-size ratchet's ceiling and every line added there is a line the ratchet
+ * charges for. The composition is the same either way; where it lives is the
+ * only thing that differs, and it belongs beside the entry it writes.
+ *
+ * `claude-code` is registered whenever it is selected — that write predates the
+ * axis and routing it through would DELETE it, the axis being `false` for every
+ * host today. Every OTHER host needs both gates: the `--tools` selection and an
+ * OBSERVED `reads_project_mcp_config`.
+ */
+export function registerMcpHosts(
+    mergeJsonFile: MergeJsonFile,
+    projectRoot: string,
+    force: boolean,
+    packageRoot: string,
+    tools: ReadonlySet<string>,
+    into: Record<string, Record<string, unknown>[]>,
+    readsConfig: ReadsProjectMcpConfig = readsProjectMcpConfig,
+): void {
+    const ensure = makeEnsureMcpRegistrations(mergeJsonFile);
+    const claude = MCP_PROJECT_CONFIG['claude-code'];
+    if (tools.has('claude-code') && claude !== undefined) {
+        const merged = ensure(projectRoot, force, packageRoot, [
+            { toolId: 'claude-code', hostId: claude.hostId, relPath: claude.relPath },
+        ]);
+        (into['claude-code'] ??= []).push(...(merged['claude-code'] ?? []));
+    }
+    for (const [toolId, keys] of Object.entries(
+        ensure(projectRoot, force, packageRoot, mcpRegistrationTargets(tools, readsConfig)),
+    )) {
+        (into[toolId] ??= []).push(...keys);
+    }
+}
+
+/**
+ * Rewrite a stale `.mcp.json` entry in place, touching only the key we own.
+ *
+ * Install writes the entry once; nothing re-read it afterwards, so a pin
+ * written by one install stayed frozen at that version for the life of the
+ * file — which is exactly the drift the pin was added to close, one release
+ * later. This is the update path.
+ *
+ * Scope discipline: the ONLY key rewritten is `mcpServers[MCP_SERVER_KEY]`.
+ * A server a consumer added by hand sits beside it and is not read, compared,
+ * reordered or rewritten — the same contract `merge_json_file` honours on the
+ * install path, and the reason uninstall can subtract exactly one key.
+ *
+ * Returns `'absent'` (no file, or no entry of ours to repair — install owns
+ * that case, not this one), `'current'`, or `'rewritten'`.
+ */
+export function migrateMcpBridge(
+    projectRoot: string,
+    packageRoot: string,
+): 'absent' | 'current' | 'rewritten' {
+    const file = path.join(projectRoot, '.mcp.json');
+    let doc: Record<string, unknown>;
+    try {
+        doc = JSON.parse(fs.readFileSync(file, 'utf-8')) as Record<string, unknown>;
+    } catch {
+        return 'absent';
+    }
+    const servers = doc['mcpServers'];
+    if (servers === null || typeof servers !== 'object' || Array.isArray(servers)) return 'absent';
+    const table = servers as Record<string, unknown>;
+    if (table[MCP_SERVER_KEY] === undefined) return 'absent';
+
+    const wanted = (mcpBridgeEntry(packageRoot)['mcpServers'] as Record<string, unknown>)[
+        MCP_SERVER_KEY
+    ];
+    if (JSON.stringify(table[MCP_SERVER_KEY]) === JSON.stringify(wanted)) return 'current';
+
+    table[MCP_SERVER_KEY] = wanted;
+    fs.writeFileSync(file, `${JSON.stringify(doc, null, 2)}\n`, 'utf-8');
+    return 'rewritten';
 }
 
 /**