@bridge_gpt/mcp-server 0.2.67 → 0.2.69

package/build/start-tickets-prereqs.js

@@ -17,6 +17,7 @@ import path from "path";
 import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { probeWorktreeMcpRegistration } from "./mcp-registration-doctor.js";
+import { VERSION } from "./version.generated.js";
 import { probeWorktreeCommandAssets } from "./command-assets-doctor.js";
 import { MCP_SERVER_NAME, MCP_PACKAGE_NAME } from "./mcp-identity.js";
 // BAPI-941: both are LEAF modules (the pure classifier and its git-backed
@@ -159,7 +160,7 @@ const WORKTRUNK_INSTALL_HINTS = {
     linux: "See the Worktrunk documentation for Linux install instructions: https://worktrunk.dev",
 };
 const GIT_INSTALL_HINTS = {
-    darwin: "xcode-select --install (or brew install git)",
+    darwin: "xcode-select --install (or brew install git). Installing another Git does not ensure PATH selects it; verify with which git and git --version.",
     linux: "Install git with your distro package manager, e.g. apt install git",
     win32: "Install Git for Windows: https://git-scm.com/download/win",
 };
@@ -444,24 +445,19 @@ export function worktreeMcpReachabilityDescriptor() {
         },
     };
 }
-/**
- * Secret-free remediation hint shared by the worktree command-assets descriptor
- * (BAPI-664). Directs users to rerun start-tickets — the supported provisioning
- * workflow — rather than manually copying or committing the generated command
- * files, which are fill-only, never refreshed, and Git-excluded per worktree.
- */
-const WORKTREE_COMMAND_ASSETS_HINT = "Re-run start-tickets to provision the packaged Claude command assets " +
-    "(.claude/commands/) into this worktree. Do not manually copy or commit the " +
-    "generated command files — they are bootstrapped per worktree and Git-excluded.";
+/** Version-pinned fill-only repair; permissions and unsafe paths need their own fix. */
+const WORKTREE_COMMAND_ASSETS_HINT = `Run npx -y ${MCP_PACKAGE_NAME}@${VERSION} repair-assets --project-root <established-root> --host claude ` +
+    "to fill missing packaged files. Resolve permission/path/platform problems separately; refresh/reconnect and run doctor.";
+const WORKTREE_COMMAND_ASSETS_PROVISION_HINT = "In-place asset repair is not supported on this platform. Re-run start-tickets to provision the packaged Claude command assets (.claude/commands/) into this worktree. Existing files are preserved; refresh/reconnect and run doctor.";
 const WORKTREE_COMMAND_ASSETS_INSTALL_HINTS = {
-    darwin: WORKTREE_COMMAND_ASSETS_HINT,
+    darwin: WORKTREE_COMMAND_ASSETS_PROVISION_HINT,
     linux: WORKTREE_COMMAND_ASSETS_HINT,
-    win32: WORKTREE_COMMAND_ASSETS_HINT,
+    win32: WORKTREE_COMMAND_ASSETS_PROVISION_HINT,
 };
 /**
  * Doctor-only, strictly read-only probe: does the current worktree contain every
  * packaged Claude slash-command asset under `.claude/commands/`? Delegates to the
- * read-only {@link probeWorktreeCommandAssets} using only `deps.readFile`,
+ * read-only {@link probeWorktreeCommandAssets} using only `deps.commandAssetMetadata`,
  * `deps.platform`, and `deps.cwd`. Reports an unavailable diagnostic (never a
  * false "present") when the optional read-only filesystem boundary is absent. The
  * probe performs NO writes, Git calls, or process spawns.
@@ -472,15 +468,14 @@ export function worktreeCommandAssetsDescriptor() {
         label: "Worktree Claude command assets",
         installHint: WORKTREE_COMMAND_ASSETS_INSTALL_HINTS,
         probe: async (deps) => {
-            const { readFile } = deps;
-            if (!readFile) {
+            if (!deps.commandAssetMetadata) {
                 return {
                     found: false,
                     detail: "command-asset probe unavailable (no read-only filesystem access)",
                 };
             }
             const result = await probeWorktreeCommandAssets(deps.cwd, {
-                readFile,
+                metadata: deps.commandAssetMetadata,
                 platform: deps.platform,
             });
             return { found: result.found, detail: result.detail };
@@ -817,6 +812,7 @@ export function getDoctorOnlyPrereqDescriptors(_platform, _env, agent) {
     return [
         uvDescriptor(),
         agentDescriptor(agent),
+        gitCompatibilityDescriptor(),
         credentialResolutionDescriptor(),
         worktreeMcpReachabilityDescriptor(),
         worktreeCommandAssetsDescriptor(),
@@ -863,6 +859,7 @@ export async function probePrerequisite(deps, descriptor) {
         label: descriptor.label,
         found: outcome.found,
         detail: outcome.detail,
+        gitCompatibility: outcome.gitCompatibility,
         installHint: hintForPlatform(descriptor.installHint, deps.platform),
         authNote: descriptor.authNote,
         // Deliberately NOT carried through when the probe THREW: the catch above
@@ -872,6 +869,63 @@ export async function probePrerequisite(deps, descriptor) {
         renderDetailWhenMissing: descriptor.renderDetailWhenMissing === true && !probeThrew ? true : undefined,
     };
 }
+/** Release-specific advisory baseline; never a launcher admission requirement.
+ * Evidence: https://github.com/max-sixty/worktrunk/blob/v0.80.0/src/git/version.rs
+ */
+export const WORKTRUNK_GIT_BASELINE = "Worktrunk v0.80.0 (Git >= 2.43.0)";
+/** Read-only, advisory compatibility with the documented release, not every release. */
+export async function probeGitWorktrunkCompatibility(deps) {
+    const basis = WORKTRUNK_GIT_BASELINE;
+    let executable;
+    let version;
+    const unknown = (reason) => ({ status: "unknown", executable, version, basis, reason });
+    try {
+        const locator = getCommandProbe("git", deps.platform);
+        const located = await deps.runCommand(locator.file, locator.args, { timeoutMs: 3000 });
+        if (located.unavailable)
+            return unknown("locator-unavailable");
+        if (!commandSucceeded(located))
+            return unknown(located.exitCode === 1 ? "git-missing" : "locator-unavailable");
+        const candidate = located.stdout.trim().split(/\r?\n/)[0];
+        // Only absolute paths from a successful locator are diagnostic metadata.
+        if (!candidate || candidate.length > 512 || /[\x00-\x1f\x7f]/.test(candidate) ||
+            !(deps.platform === "win32" ? path.win32.isAbsolute(candidate) : path.posix.isAbsolute(candidate))) {
+            return unknown("locator-unavailable");
+        }
+        executable = candidate;
+        const result = await deps.runCommand(executable, ["--version"], { timeoutMs: 3000 });
+        if (!commandSucceeded(result))
+            return unknown("version-unavailable");
+        const match = /^git version (\d{1,5})\.(\d{1,5})(?:\.(\d{1,5}))?(?:\.windows\.\d+| \(Apple Git-[\w.-]+\))?$/.exec(result.stdout.trim());
+        if (!match)
+            return unknown("version-unparseable");
+        const parts = [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)];
+        version = parts.join(".");
+        if (deps.env[WORKTRUNK_BINARY_OVERRIDE_ENV]?.trim())
+            return unknown("override-unconfirmed");
+        const minimum = [2, 43, 0];
+        const differing = parts.findIndex((n, i) => n !== minimum[i]);
+        const compatible = differing < 0 || parts[differing] > minimum[differing];
+        return { status: compatible ? "compatible" : "incompatible", executable, version, basis };
+    }
+    catch {
+        return unknown(executable ? "version-unavailable" : "locator-unavailable");
+    }
+}
+/** Pure formatter shared by doctor and first-build output. No raw probe output. */
+export function formatGitCompatibilityDiagnostic(result) {
+    const metadata = [result.executable, result.version && `Git ${result.version}`].filter(Boolean).join("; ");
+    return `Git compatibility advisory: ${result.status}${metadata ? ` — ${metadata}` : ""}; comparison: ${result.basis}` +
+        (result.reason ? `; ${result.reason}` : "") +
+        (result.status === "incompatible" ? ". Verify the Git executable/version selected on PATH and install a supported Git manually." : "") +
+        (result.reason === "override-unconfirmed" ? ". Custom Worktrunk release requirement is unconfirmed." : "");
+}
+export function gitCompatibilityDescriptor() {
+    return {
+        id: "git-compatibility", label: "Git compatibility advisory", installHint: GIT_INSTALL_HINTS,
+        probe: async (deps) => ({ found: true, gitCompatibility: await probeGitWorktrunkCompatibility(deps) }),
+    };
+}
 /**
  * Enforce the preflight descriptors fail-fast (matching the existing
  * `runPreflight` behaviour). Iterates the shared preflight descriptors in order

package/build/start-tickets.js

@@ -1,3 +1,4 @@
+import { recordProvisionedAssets } from "./generated-assets-inventory.js";
 /**
  * start-tickets — packaged CLI subcommand of the bridge-api-mcp-server bin.
  *
@@ -62,6 +63,8 @@ import path from "path";
 import { fileURLToPath } from "node:url";
 import { validateHttpBaseUrl } from "./base-url.js";
 import { VERSION } from "./version.generated.js";
+import { getNoticeDecision } from "./session-upgrade-notice.js";
+import { formatUpdateAdvice } from "./upgrade-advice.js";
 import { resolveBapiCredentials, getPrimaryCredentialStorePath, } from "./credential-store.js";
 import { LEGACY_SERVER_NAMES, MCP_PACKAGE_NAME, MCP_SERVER_NAME } from "./mcp-identity.js";
 // BAPI-941: the shared drift diagnostic formatter. The leaf drift module imports
@@ -836,6 +839,7 @@ export function createDefaultStartTicketsDeps() {
             encoding: "utf-8",
             // Optional bounded timeout (e.g. cursor-agent --list-models probes).
             timeout: options?.timeoutMs,
+            signal: options?.signal,
         }, (error, stdout, stderr) => {
             const exitCode = error && typeof error.code === "number"
                 ? (error.code)
@@ -846,6 +850,7 @@ export function createDefaultStartTicketsDeps() {
                 stdout: stdout ?? "",
                 stderr: stderr ?? "",
                 exitCode,
+                ...(error && typeof error.code === "string" ? { unavailable: true } : {}),
             });
         });
     });
@@ -1643,7 +1648,7 @@ export async function spawnMacOSTerminalTab(deps, terminal, shellCommand, contex
         : buildTerminalAppleScript(shellCommand, title);
     const result = await deps.runCommand("osascript", ["-e", script]);
     if (commandSucceeded(result))
-        return { ok: true };
+        return { ok: true, destination: terminal === "iterm" ? "iTerm tab" : "macOS Terminal tab" };
     const reason = (result.stderr || result.stdout || "").trim();
     return {
         ok: false,
@@ -1731,7 +1736,7 @@ export async function spawnWindowsTerminalTab(deps, _terminal, shellCommand, con
         const args = buildWindowsTerminalArgs(worktreePath, shellCommand, title);
         const result = await deps.runCommand(WINDOWS_TERMINAL_COMMAND, args);
         if (commandSucceeded(result))
-            return { ok: true };
+            return { ok: true, destination: "Windows Terminal tab" };
         const reason = combineCommandOutput(result);
         return {
             ok: false,
@@ -1754,7 +1759,7 @@ export async function spawnWindowsTerminalTab(deps, _terminal, shellCommand, con
         fallback,
     ]);
     if (commandSucceeded(result))
-        return { ok: true };
+        return { ok: true, destination: "PowerShell fallback window" };
     const reason = combineCommandOutput(result);
     return {
         ok: false,
@@ -1858,7 +1863,7 @@ export async function spawnLinuxTmuxTerminalTab(deps, _terminal, shellCommand, c
         : buildTmuxNewSessionArgs(session, window, worktreePath, paneCommand);
     const result = await deps.runCommand(TMUX_COMMAND, args);
     if (commandSucceeded(result))
-        return { ok: true };
+        return { ok: true, destination: "detached tmux session" };
     const reason = combineCommandOutput(result);
     return {
         ok: false,
@@ -2118,7 +2123,7 @@ export async function spawnTabsForCreatedWorktrees(deps, rows, terminal, buildSh
             worktreePath: row.path,
         });
         if (result.ok) {
-            out.push({ ...row, status: "spawned" });
+            out.push({ ...row, status: "spawned", ...(result.destination ? { sessionDestination: result.destination } : {}) });
         }
         else {
             out.push({ ...row, status: "spawn-failed", error: result.error });
@@ -2220,6 +2225,23 @@ export function buildDryRunDetailLines(agent, key, branch, platform = process.pl
  * `  path=PATH` when available) followed by warning lines for any create/spawn
  * failures.
  */
+/** Explain only actual successful sessions; summary serialization stays stable. */
+export function formatSpawnedSessionExplanation(rows, context) {
+    const spawned = rows.filter((row) => row.status === "spawned");
+    if (!spawned.length)
+        return "";
+    const lines = ["Spawned sessions:"];
+    for (const row of spawned) {
+        lines.push(`  ${row.key}: ${context.agent} runs in ${row.path ?? "a worktree whose path was not reported"} on branch ${row.branch}; ${row.sessionDestination ?? "terminal destination not reported"}.`);
+    }
+    lines.push("Work on each branch from its reported folder: it is already checked out there and normally cannot also be checked out in the original folder.");
+    lines.push("Monitor the reported terminal session and its agent output; use the attach commands below on Linux. Session startup is not review or implementation completion.");
+    if (context.workflow === "review-and-implement")
+        lines.push("Each session reviews independently, then opens a fresh implementation session only after its review halt gate permits it.");
+    if (spawned.length > 1)
+        lines.push("Coordinate ownership across these independent sessions; pause affected work if overlapping changes or conflicts appear.");
+    return lines.join("\n");
+}
 export function formatSummaryReport(rows) {
     const lines = ["Summary:"];
     // Surface the single conductor run id near the top (first line stays
@@ -2323,6 +2345,7 @@ export function buildCommandProvisioningDeps(deps) {
         runCommand: deps.runCommand,
         platform: deps.platform,
         cwd: deps.cwd,
+        ...(!deps.readFile && !deps.writeFile && !deps.mkdir ? { recordAssets: recordProvisionedAssets } : {}),
     };
 }
 /**
@@ -4129,6 +4152,19 @@ export async function runStartTicketsCli(argv, overrides = {}) {
     const options = parsed.options;
     const rawDeps = overrides.deps ?? createDefaultStartTicketsDeps();
     const orchestrate = overrides.orchestrate ?? orchestrateStartTickets;
+    // BAPI-1446: one cache-only upgrade reminder per run, on the existing stderr
+    // sink. The decision is evaluated over the EFFECTIVE environment, so a worker's
+    // markers (set when this CLI is itself run by an unattended process) keep it
+    // silent. It reads the local cache only, never the network, and any failure is
+    // contained: it never changes command execution or the exit status.
+    try {
+        const decision = (overrides.upgradeNotice ?? ((env) => getNoticeDecision(env, VERSION)))(rawDeps.env);
+        if (decision.show)
+            errorLog(formatUpdateAdvice(decision.current, decision.latest));
+    }
+    catch {
+        // Advisory only.
+    }
     // The parser validates `--agent`, so this resolves to a real spec; the guard
     // is defensive only.
     const agent = resolveAgentSpec(options.agentName);
@@ -4213,6 +4249,9 @@ export async function runStartTicketsCli(argv, overrides = {}) {
         return 1;
     }
     log(formatSummaryReport(result.rows));
+    const explanation = formatSpawnedSessionExplanation(result.rows, { agent: options.agentName, workflow: options.workflow ?? "implement" });
+    if (explanation)
+        log(explanation);
     // Linux: each spawned ticket runs in a detached tmux session — tell the user
     // how to attach.
     const spawned = result.rows.filter((r) => r.status === "spawned");

package/build/tool-call-advisory.js

@@ -0,0 +1,162 @@
+/**
+ * First-completed-tool-result upgrade notice (BAPI-1446).
+ *
+ * Wraps the SDK's `tools/call` handler so the first eligible completed result in
+ * a stdio session carries one extra text content item naming both versions and
+ * `/upgrade-bridge`. Tool execution is untouched: the original handler runs
+ * outside the decoration error boundary, so a thrown tool error propagates
+ * exactly as it would without this wrapper, and any failure while decorating
+ * returns the original result.
+ *
+ * Eligibility is decided synchronously, after the original handler resolves, by
+ * `getNoticeDecision`. It never waits for a background lookup. The once-per-
+ * session flag is set only after a successful decoration, so an unknown latest
+ * version, a silent decision, or a result that cannot be decorated safely leaves
+ * the opportunity for a later call.
+ *
+ * Like `installToolSurfaceListOverride`, this reads the SDK's private
+ * `_requestHandlers` map through one localized compatibility adapter.
+ */
+import { getMethodLiteral } from "@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";
+import { getNoticeDecision } from "./session-upgrade-notice.js";
+import { formatSessionUpgradeNotice } from "./upgrade-advice.js";
+/** Fixed diagnostic. It never carries exception text or private map contents. */
+export const TOOL_CALL_ADVISORY_INSTALL_FAILURE = "Bridge MCP upgrade notice: tools/call advisory could not be installed (incompatible MCP SDK).";
+/**
+ * Private provenance mark for the genuine, server-sourced `ping` advice item. A
+ * symbol-keyed property survives a shallow copy and is ignored by
+ * `JSON.stringify`, so it never reaches the wire. The symbol is not exported, so
+ * only this module can create or recognize the mark.
+ */
+const SERVER_ADVICE_MARK = Symbol("bridge.serverUpgradeAdvice");
+/** Mark a content item as the genuine server-sourced upgrade advice. Returns it. */
+export function markServerUpgradeAdvice(item) {
+    Object.defineProperty(item, SERVER_ADVICE_MARK, {
+        value: true,
+        enumerable: true,
+        configurable: true,
+        writable: false,
+    });
+    return item;
+}
+function isServerUpgradeAdvice(item) {
+    return (item !== null &&
+        typeof item === "object" &&
+        item[SERVER_ADVICE_MARK] === true);
+}
+/** Protocol servers that already carry the wrapper, so reinstall is a no-op. */
+const installedServers = new WeakSet();
+function authoritativeFrom(getStatus) {
+    const status = getStatus?.();
+    if (status && status.known === true && typeof status.latestVersion === "string") {
+        return { known: true, latest: status.latestVersion };
+    }
+    return { known: false };
+}
+function emit(stderr) {
+    try {
+        stderr?.(TOOL_CALL_ADVISORY_INSTALL_FAILURE);
+    }
+    catch {
+        // A diagnostic sink failure must never affect startup.
+    }
+}
+/**
+ * Install the wrapper. Returns true when it is in place (including an earlier
+ * install on the same protocol server) and false after emitting the one fixed
+ * diagnostic. Never throws, and leaves the original handler in place on failure.
+ */
+export function installToolCallAdvisory(options) {
+    const { protocolServer, callSchema, env, currentVersion, getStatus, stderr } = options;
+    try {
+        if (protocolServer && installedServers.has(protocolServer))
+            return true;
+        let method;
+        try {
+            method = getMethodLiteral(callSchema);
+        }
+        catch {
+            emit(stderr);
+            return false;
+        }
+        if (method !== "tools/call") {
+            emit(stderr);
+            return false;
+        }
+        const handlers = protocolServer?._requestHandlers;
+        if (!handlers || typeof handlers.get !== "function") {
+            emit(stderr);
+            return false;
+        }
+        const original = handlers.get(method);
+        if (typeof original !== "function") {
+            emit(stderr);
+            return false;
+        }
+        // Delivery state belongs to this installation, so it is isolated to one
+        // stdio session.
+        let delivered = false;
+        const decorate = (result) => {
+            if (delivered)
+                return result;
+            if (result === null || typeof result !== "object")
+                return result;
+            const content = result.content;
+            if (!Array.isArray(content))
+                return result;
+            const decision = getNoticeDecision(env, currentVersion, authoritativeFrom(getStatus));
+            if (!decision.show)
+                return result;
+            if (content.some(isServerUpgradeAdvice)) {
+                // The genuine ping advice already told the session.
+                delivered = true;
+                return result;
+            }
+            const notice = formatSessionUpgradeNotice(decision.current, decision.latest);
+            const decorated = {
+                ...result,
+                content: [...content, { type: "text", text: notice }],
+            };
+            delivered = true;
+            return decorated;
+        };
+        const wrapped = async (request, extra) => {
+            // Outside the boundary below: a tool-call error propagates unchanged.
+            const result = await original(request, extra);
+            try {
+                return decorate(result);
+            }
+            catch {
+                return result;
+            }
+        };
+        try {
+            // Replace in place; never remove the original first.
+            protocolServer.setRequestHandler(callSchema, wrapped);
+        }
+        catch {
+            // The replacement may have begun before the failure. Put the original back.
+            try {
+                if (handlers.get(method) !== original) {
+                    try {
+                        protocolServer.setRequestHandler(callSchema, original);
+                    }
+                    catch {
+                        handlers.set(method, original);
+                    }
+                }
+            }
+            catch {
+                // Nothing more can be done safely.
+            }
+            emit(stderr);
+            return false;
+        }
+        installedServers.add(protocolServer);
+        return true;
+    }
+    catch {
+        emit(stderr);
+        return false;
+    }
+}

package/build/tool-surface-gating.js

@@ -372,80 +372,55 @@ function setsEqual(a, b) {
     return true;
 }
 // ---------------------------------------------------------------------------
-// Update-staleness advisory decoration (BAPI-728)
+// Asset-recovery advisory composition
 // ---------------------------------------------------------------------------
-/** 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. */
+//
+// BAPI-1446 removed the update-staleness decoration (BAPI-728) from `tools/list`:
+// the `_meta` key and the text prepended to the `ping` description were an
+// invisible channel, and the upgrade notice now reaches a session through the
+// startup instructions, the first completed tool result, and the SessionStart
+// hook. Only the asset-recovery advisory decorates the list now.
+/** The tool whose description carries the model-visible recovery advisory. */
 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, over the `ping` description
- * from the static tool catalog. That static catalog is untouched, so the
- * description prose pins that guard `mcp_server/src/index.ts` are unaffected —
- * but a LIVE `tools/list` capture DOES include this decoration whenever the
- * update status is stale, and so is NOT automatically safe for tools-budget
- * measurement. Budget measurements stay repository-owned only because their
- * child process explicitly disables the update check via
- * `BAPI_MCP_UPDATE_CHECK_ENABLED=false` (BAPI-917) — see
- * `mcp_server/src/integration/measure-tools.ts`.
- *
- * 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;
+/** Compose once over undecorated SDK results, preserving the recovery metadata.
+ * Weak keys prevent retained results from accumulating session-wide state. */
+const undecoratedResults = new WeakMap();
+export function composeListAdvisories(original, recovery) {
+    const base = undecoratedResults.get(original) ?? original;
+    if (!recovery)
+        return base;
     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 },
+        const anchor = base.tools.find(t => t.name === ADVISORY_HOST_TOOL) ?? base.tools[0];
+        const result = { ...base,
+            tools: base.tools.map(tool => tool.name === anchor?.name
+                ? { ...tool, description: `${recovery.text}\n\n${anchor?.description ?? ""}`.trimEnd() } : tool),
+            _meta: { ...(base._meta ?? {}), "bridge-api/asset-recovery": { host: recovery.host,
+                    missingCount: recovery.missingCount, paths: recovery.paths, capabilities: recovery.capabilities, command: recovery.command } },
         };
+        undecoratedResults.set(result, base);
+        return result;
     }
     catch {
-        return original;
+        return base;
     }
 }
 /**
- * Compose an advisory-decorating handler over `inner`.
+ * Compose the recovery advisory 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.
+ * never turns recovery visibility off with it. A failure to retrieve or apply the
+ * advisory returns the undecorated original result.
  */
-export function createUpdateAdvisoryListHandler(inner, getAdvisory, onListServed) {
+export function createComposedAdvisoryListHandler(inner, getRecovery) {
     return async (request, extra) => {
-        const result = await inner(request, extra);
+        const original = await inner(request, extra);
         try {
-            onListServed?.();
-            return decorateListResultWithUpdateAdvisory(result, getAdvisory());
+            const recovery = await getRecovery();
+            return composeListAdvisories(original, recovery);
         }
         catch {
-            // Never let advisory decoration break tool discovery.
-            return result;
+            return original;
         }
     };
 }