@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/sfcc/writes-system-object.js

@@ -12,65 +12,26 @@
  *
  * Every handler follows the BAPI-582 foundation write recipe: parse inputs →
  * `rejectIfNotSandboxForWrite` → build a decoupled payload → `ocapiPut`/`ocapiPatch`
- * → `formatOcapiWriteToolResult` (which echoes the OCAPI write-grant JSON on 403).
+ * → `formatOcapiWriteToolResult`.
+ *
+ * This module owns no failure representation of its own. Its annotations, result
+ * type, path encoder, and every pre-transport failure envelope come from
+ * `write-tool-common.ts`, so all nine SFCC write tools emit byte-comparable
+ * bodies for equivalent failures (BAPI-766). The private near-duplicates this
+ * module used to carry leaked raw Zod issue objects and serialized compactly
+ * while the shared helpers pretty-printed — exactly the divergence that made
+ * `isError` non-total.
  */
 import { z } from "zod";
 import { ocapiPut, ocapiPatch } from "./client.js";
 import { withSfccGate } from "./tool-wrapper.js";
 import { rejectIfNotSandboxForWrite } from "./write-guard.js";
 import { formatOcapiWriteToolResult } from "./write-result.js";
-import { objectAttributeDefinitionCreateBodySchema, objectAttributeDefinitionPatchBodySchema, attributeGroupPatchBodySchema, localizedStringSchema, SfccWritePayloadFault, buildObjectAttributeDefinitionCreatePayload, buildObjectAttributeDefinitionPatchPayload, buildAttributeGroupPutPayload, buildAttributeGroupPatchPayload, buildEmptyRelationPayload, } from "./writes-system-object-payloads.js";
-// ---------------------------------------------------------------------------
-// Annotations (destructive OCAPI writes against a developer sandbox)
-// ---------------------------------------------------------------------------
-const WRITE_ANNOTATIONS = {
-    readOnlyHint: false,
-    destructiveHint: true,
-    idempotentHint: false,
-    openWorldHint: true,
-};
-function textResult(text) {
-    return { content: [{ type: "text", text }] };
-}
-/** Safe 400 envelope for a Zod validation failure — no stacks, no raw thrown strings. */
-function zodValidationEnvelope(err) {
-    return textResult(JSON.stringify({
-        error: "VALIDATION_ERROR",
-        status: 400,
-        message: "Invalid SFCC write tool input.",
-        issues: err.issues,
-    }));
-}
-/** Safe 400 envelope for a local payload-shape fault, in OCAPI-fault vocabulary. */
-function payloadFaultEnvelope(fault) {
-    return textResult(JSON.stringify({
-        error: "OCAPI_WRITE_ERROR",
-        status: fault.status,
-        fault: { type: fault.faultType, message: fault.message },
-    }));
-}
-/** Safe 500 envelope — never includes stacks, secrets, headers, or raw error text. */
-function unexpectedEnvelope() {
-    return textResult(JSON.stringify({
-        error: "INTERNAL_ERROR",
-        status: 500,
-        message: "Unexpected SFCC write tool failure",
-    }));
-}
-/** Map a pre-transport error (parse or payload-build) to its safe envelope. */
-function preTransportErrorEnvelope(err) {
-    if (err instanceof z.ZodError)
-        return zodValidationEnvelope(err);
-    if (err instanceof SfccWritePayloadFault)
-        return payloadFaultEnvelope(err);
-    return unexpectedEnvelope();
-}
+import { objectAttributeDefinitionCreateBodySchema, objectAttributeDefinitionPatchBodySchema, attributeGroupPatchBodySchema, localizedStringSchema, buildObjectAttributeDefinitionCreatePayload, buildObjectAttributeDefinitionPatchPayload, buildAttributeGroupPutPayload, buildAttributeGroupPatchPayload, buildEmptyRelationPayload, } from "./writes-system-object-payloads.js";
+import { WRITE_ANNOTATIONS, encodedSegment, preTransportErrorEnvelope, unexpectedEnvelope, } from "./write-tool-common.js";
 // ---------------------------------------------------------------------------
 // OCAPI path builders (every dynamic segment URL-encoded)
 // ---------------------------------------------------------------------------
-function encodedSegment(segment) {
-    return encodeURIComponent(segment);
-}
 function attributeDefinitionPath(objectType, attributeId) {
     return `/system_object_definitions/${encodedSegment(objectType)}/attribute_definitions/${encodedSegment(attributeId)}`;
 }

package/build/start-tickets-prereqs.js

@@ -18,6 +18,7 @@ import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./creden
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { probeWorktreeMcpRegistration } from "./mcp-registration-doctor.js";
 import { probeWorktreeCommandAssets } from "./command-assets-doctor.js";
+import { CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV, formatClaudeMcpShadowFinding, formatClaudeUserConfigDiagnostic, inspectClaudeUserConfigForMcpShadowing, resolveClaudeUserConfigPath, } from "./claude-user-config-doctor.js";
 // ---------------------------------------------------------------------------
 // Constants (moved here from start-tickets.ts so both consumers share them)
 // ---------------------------------------------------------------------------
@@ -480,6 +481,126 @@ export function worktreeCommandAssetsDescriptor() {
         },
     };
 }
+// ---------------------------------------------------------------------------
+// BAPI-727 Claude user-configuration MCP shadowing. Doctor-only and strictly
+// read-only: it reads `~/.claude.json` and runs `git worktree list --porcelain`
+// (a non-mutating query) to learn which checkout is the MAIN worktree, then
+// reports whether a foreign `bridge-api` registration could shadow the
+// provisioning a conductor worker depends on.
+// ---------------------------------------------------------------------------
+/** Stable descriptor id — pinned by tests and by the doctor render. */
+export const CLAUDE_MCP_SHADOWING_ID = "claude-mcp-shadowing";
+/**
+ * Read-only resolution of the MAIN worktree path via
+ * `git worktree list --porcelain` under `deps.cwd`. The porcelain format lists
+ * the main checkout FIRST, one record per blank-line-separated block whose first
+ * line is `worktree <path>`.
+ *
+ * Degrades to `null` on a non-zero exit, a thrown runner, or malformed/empty
+ * output — never throws, and never retains Git's stderr or an exception message.
+ * A null result means "the main path is unknown", which the descriptor reports as
+ * degraded uncertainty rather than as a collision.
+ */
+export async function resolveMainWorktreePathForDoctor(deps) {
+    let result;
+    try {
+        result = await deps.runCommand("git", ["worktree", "list", "--porcelain"], {
+            cwd: deps.cwd,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!commandSucceeded(result))
+        return null;
+    for (const line of result.stdout.split(/\r?\n/)) {
+        if (!line.startsWith("worktree "))
+            continue;
+        const candidate = line.slice("worktree ".length).trim();
+        return candidate.length > 0 ? candidate : null;
+    }
+    return null;
+}
+/**
+ * Secret-free remediation hint shared by the Claude MCP shadowing descriptor.
+ *
+ * WORDING CONSTRAINT: this module is guarded by a static source scan
+ * (`start-tickets-credential-invariants.static.test.ts`) proving the prereqs
+ * module performs no filesystem writes. It rejects the bare filesystem-mutation
+ * identifiers ANYWHERE in the source — including comments and user-facing prose,
+ * which is why the advice below is phrased as "delete, or move aside". Keep every
+ * such identifier out of this file, even inside a comment like this one.
+ */
+const CLAUDE_MCP_SHADOWING_HINT = "Delete, or move aside, the 'bridge-api' MCP registration in ~/.claude.json (at user scope, " +
+    "or under the projects entry for this repository/worktree) so the registration the " +
+    "conductor provisions into each worker worktree is the one that takes effect. If the " +
+    "collision is deliberate, set " +
+    `${CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING_ENV}=1 to override the executor's refusal ` +
+    "(doctor still reports it).";
+const CLAUDE_MCP_SHADOWING_INSTALL_HINTS = {
+    darwin: CLAUDE_MCP_SHADOWING_HINT,
+    linux: CLAUDE_MCP_SHADOWING_HINT,
+    win32: CLAUDE_MCP_SHADOWING_HINT,
+};
+/**
+ * Doctor-only, strictly read-only probe: does the machine's Claude user
+ * configuration register a `bridge-api` MCP server that could shadow a worker's
+ * provisioned registration?
+ *
+ * Status mapping:
+ *   - no registration, or only acceptable provisioned shims → `found: true`
+ *   - a CONFIRMED foreign registration                      → `found: false`
+ *   - unreadable / malformed config, or an unresolved main
+ *     worktree path                                          → `found: true` + detail
+ *
+ * The failing case is deliberately independent of
+ * `BAPI_CONDUCTOR_ALLOW_CLAUDE_MCP_SHADOWING`: the override changes what the
+ * EXECUTOR does at runtime, not whether the collision exists. A diagnostic that
+ * went quiet because an override happened to be exported would hide the exact
+ * condition an operator ran doctor to find.
+ */
+export function claudeMcpShadowingDescriptor() {
+    return {
+        id: CLAUDE_MCP_SHADOWING_ID,
+        label: "Claude user-config MCP shadowing (~/.claude.json)",
+        installHint: CLAUDE_MCP_SHADOWING_INSTALL_HINTS,
+        // The detail below is built exclusively from the inspector's safe metadata
+        // (scope labels, the config path, a fixed shape label, sorted env KEY names),
+        // so it is safe to render even when this prerequisite reads as missing.
+        renderDetailWhenMissing: true,
+        probe: async (deps) => {
+            const { readFile, homedir } = deps;
+            if (!readFile || !homedir) {
+                return {
+                    found: true,
+                    detail: "shadowing probe unavailable (no read-only filesystem access)",
+                };
+            }
+            const mainWorktreePath = await resolveMainWorktreePathForDoctor(deps);
+            const inspection = await inspectClaudeUserConfigForMcpShadowing({
+                claudeConfigPath: resolveClaudeUserConfigPath(homedir(), deps.platform),
+                platform: deps.platform,
+                cwd: deps.cwd,
+                mainRepositoryPath: mainWorktreePath ?? undefined,
+                worktreePath: deps.cwd,
+            }, { readFile });
+            const degraded = inspection.diagnostics.map(formatClaudeUserConfigDiagnostic);
+            if (mainWorktreePath === null) {
+                degraded.push("the main worktree path could not be resolved; only user and current-worktree scopes were checked");
+            }
+            if (inspection.findings.length > 0) {
+                const findings = inspection.findings.map(formatClaudeMcpShadowFinding);
+                return { found: false, detail: [...findings, ...degraded].join("; ") };
+            }
+            return {
+                found: true,
+                detail: degraded.length > 0
+                    ? degraded.join("; ")
+                    : "no foreign bridge-api registration in the Claude user config",
+            };
+        },
+    };
+}
 /**
  * Conservatively normalize a filesystem path for comparison: trim, drop a
  * trailing separator, and resolve `.`/`..` segments via `path.resolve`. Symlink
@@ -628,6 +749,7 @@ export function getDoctorOnlyPrereqDescriptors(_platform, _env, agent) {
         ripgrepDescriptor(),
         reviewTicketsGitDescriptor(),
         liveSourceGuardDescriptor(),
+        claudeMcpShadowingDescriptor(),
     ];
 }
 /**
@@ -648,10 +770,12 @@ export function getDoctorPrereqDescriptors(platform, env, agent) {
 /** Probe one descriptor without throwing, resolving its platform-specific hint. */
 export async function probePrerequisite(deps, descriptor) {
     let outcome;
+    let probeThrew = false;
     try {
         outcome = await descriptor.probe(deps);
     }
     catch (err) {
+        probeThrew = true;
         outcome = { found: false, detail: err instanceof Error ? err.message : String(err) };
     }
     return {
@@ -661,6 +785,11 @@ export async function probePrerequisite(deps, descriptor) {
         detail: outcome.detail,
         installHint: hintForPlatform(descriptor.installHint, deps.platform),
         authNote: descriptor.authNote,
+        // Deliberately NOT carried through when the probe THREW: the catch above
+        // replaces the audited detail with the exception's message, which is exactly
+        // the arbitrary text the missing-detail suppression exists to keep out of the
+        // report. The audit only covers details the probe returned deliberately.
+        renderDetailWhenMissing: descriptor.renderDetailWhenMissing === true && !probeThrew ? true : undefined,
     };
 }
 /**

package/build/start-tickets.js

@@ -64,6 +64,7 @@ import { provisionMcpRegistrationsForCreatedWorktrees, } from "./mcp-provisionin
 import { provisionCommandsForCreatedWorktrees, } from "./command-provisioning.js";
 import { resolveMcpShimInvocationForRuntime, buildMcpShimCommand, } from "./mcp-server-invocation.js";
 import { existsSync } from "node:fs";
+import { TICKET_KEY_PATTERN as SHARED_TICKET_KEY_PATTERN, TICKET_KEY_USAGE_SUMMARY, validateTicketKey, } from "./ticket-key-utils.js";
 // Per-OS prerequisite knowledge + low-level command probes live in the shared
 // prereqs module so `runPreflight` (enforce) and the read-only `doctor` (render)
 // can never drift. `start-tickets.ts` imports VALUES from there; the prereqs
@@ -80,8 +81,15 @@ export { WORKTRUNK_BINARY_OVERRIDE_ENV, WINDOWS_TERMINAL_COMMAND, WINDOWS_POWERS
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-/** Jira-style ticket key, e.g. BAPI-248. */
-export const TICKET_KEY_PATTERN = /^[A-Z]+-[0-9]+$/;
+/**
+ * The canonical ticket-key shape, e.g. `BAPI-248` or `MY_PROJ-248`.
+ *
+ * Re-exported from `ticket-key-utils.ts` (BAPI-710) rather than redefined:
+ * `review-tickets.ts` still imports the name from here, and the previous local
+ * `/^[A-Z]+-[0-9]+$/` rejected underscore-containing and single-character
+ * prefixes that the server happily mints.
+ */
+export const TICKET_KEY_PATTERN = SHARED_TICKET_KEY_PATTERN;
 /** Default cap on concurrently-created worktrees. */
 export const DEFAULT_MAX_PARALLEL = 3;
 /** Default tmux session-name prefix; one detached session is created per ticket. */
@@ -146,7 +154,7 @@ export function getStartTicketsUsage() {
         "  Windows  git-wt, Git for Windows / Git Bash, Windows Terminal or PowerShell",
         "  Linux    wt, git, tmux",
         "",
-        "Each KEY must match [A-Z]+-[0-9]+ (e.g., BAPI-248).",
+        TICKET_KEY_USAGE_SUMMARY,
     ].join("\n");
 }
 /**
@@ -366,11 +374,9 @@ export function parseStartTicketsArgs(argv) {
     }
     const seen = new Set();
     for (const key of keys) {
-        if (!TICKET_KEY_PATTERN.test(key)) {
-            return {
-                status: "error",
-                message: `Invalid ticket key: '${key}' (keys must match [A-Z]+-[0-9]+, e.g., BAPI-248).`,
-            };
+        const keyCheck = validateTicketKey(key);
+        if (!keyCheck.ok) {
+            return { status: "error", message: keyCheck.message };
         }
         if (seen.has(key)) {
             return { status: "error", message: `Duplicate ticket key: '${key}'.` };
@@ -400,11 +406,9 @@ export function parseStartTicketsArgs(argv) {
         }
         const overrideKey = entry.slice(0, sepIndex);
         const branchName = entry.slice(sepIndex + 1);
-        if (!TICKET_KEY_PATTERN.test(overrideKey)) {
-            return {
-                status: "error",
-                message: `Invalid --branch override key: '${overrideKey}' (keys must match [A-Z]+-[0-9]+).`,
-            };
+        const overrideCheck = validateTicketKey(overrideKey, "--branch override key");
+        if (!overrideCheck.ok) {
+            return { status: "error", message: overrideCheck.message };
         }
         if (!seen.has(overrideKey)) {
             return {

package/build/ticket-backend-metadata.js

@@ -0,0 +1,59 @@
+/**
+ * ticket-backend-metadata — attach the server's `X-Ticket-Backend` header to a
+ * SUCCESSFUL ticket response as labeled metadata (BAPI-710).
+ *
+ * The server has always set this header; nothing on the MCP side read it, so an
+ * agent could not tell whether a ticket came from Jira or the local backend —
+ * which matters because a `local://` URL, an absent comment thread, and a
+ * four-status workflow are all correct for one backend and a symptom for the other.
+ *
+ * Two rules hold this in its lane:
+ *
+ *   - **Metadata only, success only.** The header is never an authorization or
+ *     error-control signal. Error responses are governed exclusively by the
+ *     structured 409 body (`tool-error-envelope.ts`), because a raised FastAPI
+ *     error builds a fresh response and DROPS this header — so treating its
+ *     absence as meaningful would misread every error.
+ *   - **The payload survives intact.** An object gains one labeled field; an
+ *     array or scalar is wrapped in an explicit `{ ticket_backend, data }`
+ *     envelope rather than being flattened, coerced, or dropped.
+ */
+/** The response header the Bridge API sets on ticket routes. */
+export const TICKET_BACKEND_HEADER = "X-Ticket-Backend";
+/** The field name added to a successful response payload. */
+export const TICKET_BACKEND_FIELD = "ticket_backend";
+/** Narrow a raw header value to a recognized backend, or `null`. */
+export function parseTicketBackendHeader(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "local" || normalized === "jira")
+        return normalized;
+    return null;
+}
+/**
+ * Return the response body to serialize, with backend metadata attached.
+ *
+ * - `backend === null` (header absent or unrecognized) → `body` unchanged. A
+ *   supplemental signal must never alter a payload just by being missing.
+ * - plain object → the original fields plus `ticket_backend`.
+ * - array / scalar / null → `{ ticket_backend, data: <original> }`, because
+ *   there is nowhere on an array to put a labeled field without changing what
+ *   the array means.
+ */
+export function attachTicketBackendMetadata(body, backend) {
+    if (backend === null)
+        return body;
+    if (body !== null && typeof body === "object" && !Array.isArray(body)) {
+        return { ...body, [TICKET_BACKEND_FIELD]: backend };
+    }
+    return { [TICKET_BACKEND_FIELD]: backend, data: body };
+}
+/**
+ * Serialize a successful JSON response with backend metadata attached.
+ * Formatting matches `handleResponse`'s existing `JSON.stringify(body, null, 2)`.
+ */
+export function formatSuccessWithTicketBackend(body, headerValue) {
+    const backend = parseTicketBackendHeader(headerValue);
+    return JSON.stringify(attachTicketBackendMetadata(body, backend), null, 2);
+}

package/build/ticket-key-utils.js

@@ -0,0 +1,92 @@
+/**
+ * ticket-key-utils — the ONE ticket-key grammar every MCP and CLI surface uses.
+ *
+ * Before BAPI-710 three patterns disagreed across the client/server boundary:
+ *
+ *   | Layer                                       | Pattern                  | Accepts `MY_PROJ` |
+ *   | ------------------------------------------- | ------------------------ | ----------------- |
+ *   | server `field_validators.py` (prefix)       | `^[A-Z][A-Z0-9_]{0,19}$` | yes               |
+ *   | `chain-orchestrator.ts`                     | `^[A-Z][A-Z0-9]+-\d+$`   | no                |
+ *   | `start-tickets.ts`                          | `^[A-Z]+-[0-9]+$`        | no                |
+ *
+ * A repository configured with `jira_ticket_key = "MY_PROJ"` therefore minted
+ * keys the server considered valid and the clients rejected — `/full-automation`
+ * silently dropped them. Jira project keys may contain underscores too, so this
+ * was never a local-mode-only defect.
+ *
+ * This module mirrors the public Python contract
+ * (`api.library.config.field_validators.TICKET_KEY_PREFIX_PATTERN_SOURCE` plus a
+ * `-<digits>` suffix). The two must be changed together; the Python side is
+ * authoritative because it is what mints keys.
+ *
+ * Everything here is pure: no I/O, no normalization. A key that reaches a client
+ * has already been minted, so it must round-trip byte-for-byte — upper-casing or
+ * trimming it here would silently retarget or invent a ticket.
+ */
+/** The configured prefix grammar, mirroring the server's public prefix source. */
+export const TICKET_KEY_PREFIX_PATTERN_SOURCE = "[A-Z][A-Z0-9_]{0,19}";
+/**
+ * A complete ticket key: an upper-case prefix (a letter followed by up to 19
+ * letters, digits, or underscores), a hyphen, and a numeric suffix.
+ * Examples: `A-1`, `BAPI-248`, `MY_PROJ-248`, `A1_B2-0007`.
+ */
+export const TICKET_KEY_PATTERN = /^[A-Z][A-Z0-9_]{0,19}-\d+$/;
+/**
+ * The single actionable rejection message. Names every rule the grammar
+ * enforces, so one failure is enough for a caller to correct its input.
+ */
+export const TICKET_KEY_VALIDATION_MESSAGE = "keys must be an upper-case prefix (a letter followed by up to 19 letters, " +
+    "digits, or underscores — 20 characters maximum), a hyphen, and a number " +
+    "(e.g., BAPI-248, MY_PROJ-248, A-1)";
+/** Compact contract summary for usage/help text. */
+export const TICKET_KEY_USAGE_SUMMARY = "Each KEY is an upper-case prefix (letters, digits, underscores; 20 max), a " +
+    "hyphen, and a number (e.g., BAPI-248, MY_PROJ-248).";
+/** True when `value` is exactly a canonical ticket key. Never normalizes. */
+export function isValidTicketKey(value) {
+    return typeof value === "string" && TICKET_KEY_PATTERN.test(value);
+}
+/**
+ * Validate a single key, returning an actionable message on failure.
+ *
+ * The rejected value is echoed via `JSON.stringify` so an empty string, a value
+ * with trailing whitespace, or a non-string is visibly distinguishable in the
+ * error — "Invalid ticket key: ''" is otherwise indistinguishable from a bug in
+ * the caller's own formatting.
+ */
+export function validateTicketKey(value, label = "ticket key") {
+    if (isValidTicketKey(value))
+        return { ok: true };
+    const rendered = typeof value === "string" ? value : JSON.stringify(value);
+    return {
+        ok: false,
+        invalidKeys: [String(rendered)],
+        message: `Invalid ${label}: ${JSON.stringify(rendered)} — ${TICKET_KEY_VALIDATION_MESSAGE}.`,
+    };
+}
+/**
+ * Validate a whole list and report EVERY rejected key in one message.
+ *
+ * Reporting the complete rejected set (rather than the first failure, or —
+ * worse — silently continuing with the valid subset) is the point: a caller that
+ * learns about one bad key at a time needs one round trip per key, and a caller
+ * that is never told at all runs downstream side effects against a quietly
+ * truncated list.
+ */
+export function validateTicketKeys(values, label = "ticket key") {
+    const invalidKeys = [];
+    for (const value of values) {
+        if (isValidTicketKey(value))
+            continue;
+        invalidKeys.push(typeof value === "string" ? value : JSON.stringify(value));
+    }
+    if (invalidKeys.length === 0)
+        return { ok: true };
+    const plural = invalidKeys.length === 1 ? "" : "s";
+    return {
+        ok: false,
+        invalidKeys,
+        message: `Invalid ${label}${plural}: ` +
+            `${invalidKeys.map((k) => JSON.stringify(k)).join(", ")} — ` +
+            `${TICKET_KEY_VALIDATION_MESSAGE}.`,
+    };
+}

package/build/tool-error-envelope.js

@@ -0,0 +1,71 @@
+/**
+ * tool-error-envelope — pure parsing for the serialized MCP error envelopes that
+ * `handleResponse` (index.ts) emits for a non-OK Bridge API response.
+ *
+ * The envelope shape is `{ error: string, status: number, message: string, ... }`.
+ * One condition is recognized specifically (BAPI-710): the backend's terminal
+ * "this operation has no local-backend equivalent" refusal, which the ticket
+ * routes return as HTTP 409 with `detail.error = "UNSUPPORTED_IN_LOCAL_MODE"`.
+ *
+ * Recognition is by the exact `(error, status)` PAIR — never by message text.
+ * Message text is prose that gets reworded; matching on it would make a copy
+ * edit silently change orchestration control flow.
+ *
+ * Everything here is pure: parse, inspect, return. Malformed JSON, scalars,
+ * arrays, and absent fields all produce a safe non-match rather than throwing.
+ */
+/** The recognized machine-readable marker for an unsupported local operation. */
+export const UNSUPPORTED_IN_LOCAL_MODE_ERROR = "UNSUPPORTED_IN_LOCAL_MODE";
+/** The HTTP status that marker is only ever valid with. */
+export const UNSUPPORTED_IN_LOCAL_MODE_STATUS = 409;
+/**
+ * Parse `text` as a tool-error envelope, or return `null`.
+ *
+ * Requires a JSON object with a string `error` and a numeric `status` — the same
+ * strict shape `pipeline-orchestrator.ts`'s `isToolFailureEnvelope` uses, so the
+ * two agree on what counts as a failure envelope.
+ */
+export function parseToolErrorEnvelope(text) {
+    if (typeof text !== "string")
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return null;
+    }
+    const obj = parsed;
+    if (typeof obj.error !== "string" || typeof obj.status !== "number")
+        return null;
+    const envelope = {
+        error: obj.error,
+        status: obj.status,
+        message: typeof obj.message === "string" ? obj.message : "",
+    };
+    if (Array.isArray(obj.supported_in)) {
+        envelope.supported_in = obj.supported_in.filter((v) => typeof v === "string");
+    }
+    if (Array.isArray(obj.unsupported_fields)) {
+        envelope.unsupported_fields = obj.unsupported_fields.filter((v) => typeof v === "string");
+    }
+    return envelope;
+}
+/** True for the exact unsupported-local contract: the marker AND HTTP 409. */
+export function isUnsupportedInLocalModeEnvelope(envelope) {
+    return (envelope !== null &&
+        envelope.error === UNSUPPORTED_IN_LOCAL_MODE_ERROR &&
+        envelope.status === UNSUPPORTED_IN_LOCAL_MODE_STATUS);
+}
+/**
+ * Convenience: parse `text` and return the envelope only when it is the
+ * recognized unsupported-local refusal. Returns `null` for everything else,
+ * including an ordinary 409 and a 500 that happens to carry the marker string.
+ */
+export function parseUnsupportedInLocalModeEnvelope(text) {
+    const envelope = parseToolErrorEnvelope(text);
+    return isUnsupportedInLocalModeEnvelope(envelope) ? envelope : null;
+}

package/build/tool-surface-gating.js

@@ -371,6 +371,78 @@ function setsEqual(a, b) {
     }
     return true;
 }
+// ---------------------------------------------------------------------------
+// Update-staleness advisory decoration (BAPI-728)
+// ---------------------------------------------------------------------------
+/** The `_meta` key carrying the structured staleness advisory. */
+export const UPDATE_ADVISORY_META_KEY = "bridge-api/update-advisory";
+/** The tool whose description carries the model-visible advisory when stale. */
+const ADVISORY_HOST_TOOL = "ping";
+/**
+ * Wrap a `tools/list` handler so a KNOWN-stale server tells the model so.
+ *
+ * Why decorate the list at all: the staleness value was already computed on every
+ * server start and emitted to an MCP log sink nothing reads, so a session talking
+ * to a twenty-release-old build looked completely normal — the visible symptom was
+ * an agent that could not find `council`, with no signal explaining why. Tool
+ * discovery is the one surface every session reads without being asked to.
+ *
+ * What is preserved, exactly: tool NAMES, their ORDER, their input/output SCHEMAS,
+ * their enabled state, and every other response property. The advisory is added in
+ * two places, both additive:
+ *
+ *   - `_meta` — the protocol's sanctioned extension point, for clients that
+ *     surface structured metadata;
+ *   - the `ping` tool's DESCRIPTION — the surface a model actually reads. `ping`
+ *     is the topically correct host: its description already documents the
+ *     version/upgrade metadata it returns. Note this does not require anyone to
+ *     CALL `ping` — reading its description during ordinary discovery is enough,
+ *     which is the precise gap the ticket describes.
+ *
+ * The description text is appended at RUNTIME only. The static tool catalog is
+ * untouched, so the tools-budget ratchet and the description prose pins that
+ * guard `mcp_server/src/index.ts` are unaffected.
+ *
+ * Fail-open: if the advisory cannot be produced, the original result is returned
+ * byte-for-byte.
+ */
+export function decorateListResultWithUpdateAdvisory(original, advisory) {
+    if (!advisory)
+        return original;
+    try {
+        const tools = original.tools.map((tool) => tool.name === ADVISORY_HOST_TOOL
+            ? { ...tool, description: `${advisory}\n\n${tool.description ?? ""}`.trimEnd() }
+            : tool);
+        return {
+            ...original,
+            tools,
+            _meta: { ...(original._meta ?? {}), [UPDATE_ADVISORY_META_KEY]: advisory },
+        };
+    }
+    catch {
+        return original;
+    }
+}
+/**
+ * Compose an advisory-decorating handler over `inner`.
+ *
+ * `inner` is the capability gate's handler when dynamic gating is enabled, and
+ * the SDK's own captured handler when it is disabled — so turning gating off
+ * never turns update visibility off with it.
+ */
+export function createUpdateAdvisoryListHandler(inner, getAdvisory, onListServed) {
+    return async (request, extra) => {
+        const result = await inner(request, extra);
+        try {
+            onListServed?.();
+            return decorateListResultWithUpdateAdvisory(result, getAdvisory());
+        }
+        catch {
+            // Never let advisory decoration break tool discovery.
+            return result;
+        }
+    };
+}
 /** Fixed, sanitized boot error (never includes map contents or config). */
 const COMPAT_ERROR = "tool-surface gating: incompatible MCP SDK — the tools/list handler could not be resolved for override.";
 /**