@bridge_gpt/mcp-server 0.2.65 → 0.2.66

package/build/sfcc/setup-status.js

@@ -6,6 +6,7 @@
  * prevent the others from running.
  */
 import { SFCC_VERSIONS, getSfccVersionConfig } from "./config.js";
+import { publishSfccVersion } from "./tools-configured.js";
 import { getAmToken } from "./client.js";
 // ---------------------------------------------------------------------------
 // Implementation
@@ -38,6 +39,7 @@ export async function sfccSetupStatusTool(deps) {
     if (apiKeyOk && repoOk) {
         try {
             resolvedVersion = await getSfccVersionConfig(deps.buildGetUrl, deps.getGetHeaders, deps.repoName);
+            publishSfccVersion(resolvedVersion);
             if (resolvedVersion === null) {
                 versionStatus = "✗ Not set (configure the 'version' field in Bridge API project settings)";
             }

package/build/sfcc/tool-wrapper.js

@@ -62,6 +62,7 @@
  * no per-tool opt-in and no exemption flag.
  */
 import { SFCC_VERSIONS, getSfccVersionConfig } from "./config.js";
+import { publishSfccVersion } from "./tools-configured.js";
 import { resolveSfccCredentials } from "./credentials.js";
 import { formatSfccFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
@@ -385,6 +386,7 @@ export function withSfccGate(deps, handler) {
         }
         // (a) Read /config-field/version
         const version = await getSfccVersionConfig(deps.buildGetUrl, deps.getGetHeaders, deps.repoName);
+        publishSfccVersion(version);
         if (version === null) {
             return notConfigured("bridge-auth", "Could not read the SFCC version from Bridge API (/config-field/version). " +
                 "Ensure your Bridge API key is set and the repo is configured. " +

package/build/sfcc/tools-configured.js

@@ -0,0 +1,96 @@
+/** Process-local, secret-free SFCC setup verdict for authenticated Bridge requests. */
+import { access } from "fs/promises";
+import { constants } from "fs";
+import path from "path";
+import { resolveSfccCredentials } from "./credentials.js";
+import { getSfccVersionConfig, SFCC_VERSIONS } from "./config.js";
+const DIAGNOSTIC = "SFCC tools header omitted: version lookup did not establish SFCC setup; check setup status.";
+/** Existence and readability are enough to establish the local gate. */
+export async function hasRootDwJson() {
+    try {
+        await access(path.join(process.cwd(), "dw.json"), constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Isolated state is injectable for offline tests; the MCP uses one instance. */
+export function createSfccToolsHeaderState(deps) {
+    let credentialVerdict;
+    let knownVersion;
+    let lookupStarted = false;
+    let diagnosticPrinted = false;
+    function getCredentialVerdict() {
+        credentialVerdict ??= Promise.resolve().then(() => deps.resolveCredentials(deps.env, {
+            ...deps.credentialDeps,
+            writeFile: async () => { },
+            mkdir: async () => { },
+        })).then((result) => result.ok ? "yes" : "no")
+            .catch(() => "no");
+        return credentialVerdict;
+    }
+    function publishVersion(version) {
+        if (version !== null && knownVersion === undefined)
+            knownVersion = version;
+        if (version !== null && SFCC_VERSIONS.includes(version))
+            knownVersion = version;
+    }
+    function reportUnresolved() {
+        if (diagnosticPrinted)
+            return;
+        diagnosticPrinted = true;
+        deps.diagnostic(DIAGNOSTIC);
+    }
+    async function withHeader(headers, options) {
+        if (options.skipSfccToolsHeader)
+            return headers;
+        try {
+            const localFile = await deps.hasDwJson();
+            if (knownVersion === undefined && !lookupStarted && options.repoName) {
+                lookupStarted = true;
+                void deps.getVersion(options.buildGetUrl, options.getLookupHeaders, options.repoName)
+                    .then((version) => {
+                    if (version !== null)
+                        publishVersion(version);
+                    if (knownVersion === undefined) {
+                        knownVersion = null;
+                        if (!localFile)
+                            reportUnresolved();
+                    }
+                })
+                    .catch(() => {
+                    if (knownVersion === undefined) {
+                        knownVersion = null;
+                        if (!localFile)
+                            reportUnresolved();
+                    }
+                });
+            }
+            const isSfcc = knownVersion !== undefined && knownVersion !== null
+                && SFCC_VERSIONS.includes(knownVersion);
+            if (!localFile && !isSfcc) {
+                if (!options.repoName)
+                    reportUnresolved();
+                return headers;
+            }
+            headers["X-Bridge-SFCC-Tools"] = await getCredentialVerdict();
+        }
+        catch {
+            // Optional enrichment cannot interrupt authenticated requests.
+        }
+        return headers;
+    }
+    return { getCredentialVerdict, publishVersion, withHeader };
+}
+const processState = createSfccToolsHeaderState({
+    hasDwJson: hasRootDwJson,
+    resolveCredentials: (env, credentialDeps) => resolveSfccCredentials(undefined, env, credentialDeps),
+    credentialDeps: {},
+    env: process.env,
+    getVersion: getSfccVersionConfig,
+    diagnostic: (message) => console.error(message),
+});
+export const getSfccCredentialVerdict = processState.getCredentialVerdict;
+export const publishSfccVersion = processState.publishVersion;
+export const withSfccToolsHeader = processState.withHeader;

package/build/start-tickets.js

@@ -54,6 +54,7 @@
  * unit-testable on Linux CI without spawning real commands or terminals.
  */
 import { execFile } from "child_process";
+import { macosTerminalPermissionGuidance } from "./macos-terminal-permission-guidance.js";
 import { readFile, writeFile, mkdir, mkdtemp, stat, lstat, symlink, unlink, copyFile, readdir, rm, } from "fs/promises";
 import os from "node:os";
 import { createHash } from "node:crypto";
@@ -136,7 +137,7 @@ export function getStartTicketsUsage() {
         "  Cursor with --auto launches headlessly after a bounded readiness check; without --auto it stays interactive for the review gate.",
         "  --workflow implement|review-and-implement  Command each spawned worktree runs (default: implement). review-and-implement runs review-ticket then, after a per-ticket halt gate, hands off to a fresh implement-ticket session; --auto applies to both phases.",
         "  --tier cheap|basic|premium  Strict manual model-routing override: bypasses the per-ticket difficulty/tier lookup and applies this tier to every ticket exactly as supplied, with no per-session posture adjustment. Claude/Cursor use registry aliases and repository overrides; Codex uses the authenticated Bridge catalog. It is NOT a raw --model alias and never carries an API key or credential. A malformed value requests premium routing when available. Mutually exclusive with --auto-tier.",
-        "  --auto-tier cheap|basic|premium  Internal/advanced machine-carried raw backend tier for chained automation handoffs (e.g. /review-and-implement): bypasses the per-ticket lookup like --tier, but remains subject to per-session optimization-posture adjustment (may be downshifted under maximize_subscription). Not the strict-override mechanism — use --tier for a human override. Mutually exclusive with --tier.",
+        "  --auto-tier cheap|basic|premium  Internal/advanced machine-carried raw backend tier for chained automation handoffs (e.g. /review-and-implement): bypasses the per-ticket lookup like --tier, but remains subject to per-session optimization-posture adjustment (may be downshifted under maximize_subscription, unless the server reports configured thresholds). Not the strict-override mechanism — use --tier for a human override. Mutually exclusive with --tier.",
         "  --rounds 1|2                Review round count forwarded to the review phase; review-only, valid only with --workflow review-and-implement",
         "  --terminal terminal|iterm   Override the macOS terminal app (default: auto-detect via $TERM_PROGRAM); honored on macOS only",
         "  --dry-run                   Print intended actions; creates no worktrees and opens no tabs, but DOES resolve model routing read-only (may compute+cache a ticket's difficulty) to preview the --model each tab would use",
@@ -2749,14 +2750,32 @@ export async function fetchCodexModelCatalog(access) {
         return invalid();
     return { ok: true, catalog: { models: models, revision } };
 }
+/**
+ * True only when stored thresholds decided the tier (`configured` or
+ * `anomaly`). The merged resolver maps every `anomaly` tier to `premium` as a
+ * fail-safe, so a threshold-decided tier is final and must never be downshifted.
+ *
+ * A `source: "fallback"` response is never threshold-decided: the server could
+ * not obtain a difficulty and assumed premium, even though it still reports the
+ * stored thresholds' mode. Treating it as decided would give review tabs a
+ * premium fallback and skip the maximize downshift for a guess.
+ */
+export function isThresholdDecidedTierResponse(value) {
+    if (value.source === "fallback")
+        return false;
+    return value.thresholdMode === "configured" || value.thresholdMode === "anomaly";
+}
 /**
  * Fetch the coarse tier for one ticket with a bounded timeout. Never throws to
  * the batch orchestrator: failures/timeouts return a structured warning plus a
  * classified diagnostic that preserves the ticket key in metadata.
  */
-export async function fetchTicketModelTierForStartTickets(access, ticket) {
+export async function fetchTicketModelTierForStartTickets(access, ticket, fetchOptions = {}) {
     try {
-        const url = buildStartTicketsJiraUrl(access.baseUrl, `/tickets/${encodeURIComponent(ticket)}/model-tier`, { repo_name: access.repoName });
+        const params = { repo_name: access.repoName };
+        if (fetchOptions.consumer)
+            params.consumer = fetchOptions.consumer;
+        const url = buildStartTicketsJiraUrl(access.baseUrl, `/tickets/${encodeURIComponent(ticket)}/model-tier`, params);
         const body = await fetchJsonWithTimeout(url, startTicketsGetHeaders(access), TICKET_MODEL_TIER_FETCH_TIMEOUT_MS);
         const obj = (body ?? {});
         const tier = isModelTier(obj.tier) ? obj.tier : null;
@@ -2764,7 +2783,17 @@ export async function fetchTicketModelTierForStartTickets(access, ticket) {
         const source = obj.source === "cached" || obj.source === "computed" || obj.source === "fallback"
             ? obj.source
             : "fallback";
-        return { ok: true, value: { difficulty, tier, source } };
+        const value = { difficulty, tier, source };
+        // BAPI-1343: additive fields are attached only when the server sent them,
+        // so an older server's response parses to exactly the pre-feature shape.
+        if (obj.threshold_mode !== undefined && obj.threshold_mode !== null) {
+            value.thresholdMode =
+                obj.threshold_mode === "configured" || obj.threshold_mode === "anomaly" ? obj.threshold_mode : "legacy";
+        }
+        if (obj.consumer === "review" || obj.consumer === "implementation") {
+            value.consumer = obj.consumer;
+        }
+        return { ok: true, value };
     }
     catch (err) {
         return {
@@ -2779,15 +2808,23 @@ export async function fetchTicketModelTierForStartTickets(access, ticket) {
         };
     }
 }
+/**
+ * Fetch tiers for ticket keys with bounded parallelism (capped at 3). One
+ * ticket's failure never aborts the others; results are keyed by ticket. The
+ * shared bounded fetch behind both `start-tickets` and `/review-tickets`.
+ */
+export async function fetchTicketModelTiersForKeys(access, keys, maxParallel, fetchOptions = {}) {
+    const limit = Math.min(maxParallel, 3);
+    const results = await runWithConcurrency(keys, limit, (key) => fetchTicketModelTierForStartTickets(access, key, fetchOptions).then((res) => [key, res]));
+    return new Map(results);
+}
 /**
  * Fetch tiers for the still-spawnable rows with bounded parallelism (capped at
  * 3). One ticket's failure never aborts the others; results are keyed by ticket.
  */
-export async function fetchTicketModelTiersForRows(access, rows, maxParallel, isEligible = (r) => r.status === "created" && !!r.path) {
+export async function fetchTicketModelTiersForRows(access, rows, maxParallel, isEligible = (r) => r.status === "created" && !!r.path, fetchOptions = {}) {
     const eligible = rows.filter(isEligible);
-    const limit = Math.min(maxParallel, 3);
-    const results = await runWithConcurrency(eligible, limit, (row) => fetchTicketModelTierForStartTickets(access, row.key).then((res) => [row.key, res]));
-    return new Map(results);
+    return fetchTicketModelTiersForKeys(access, eligible.map((row) => row.key), maxParallel, fetchOptions);
 }
 /**
  * Parse a model-list command's stdout into a set of advertised model aliases.
@@ -2874,7 +2911,15 @@ export function applyDefaultModelRoutingMetadata(row, reason, diagnostic) {
         ...(diagnostic ? { modelRoutingDiagnostic: diagnostic } : {}),
     };
 }
-function resolveRoutingAlias(agent, tier, overrides, catalog) {
+/**
+ * Map a coarse tier to the agent's alias: the Codex authenticated catalog for
+ * `codex`, otherwise the agent registry plus per-repo
+ * `difficulty_model_tier_overrides`. Exported (BAPI-1343) so `/review-tickets`
+ * maps review-threshold tiers exactly as `start-tickets` does, without copying
+ * the registry or catalog rules. The result still needs
+ * {@link validateResolvedModelAliasForAgent} before it reaches a shell.
+ */
+export function resolveRoutingAlias(agent, tier, overrides, catalog) {
     return agent.name === "codex"
         ? catalog?.models[tier] ?? null
         : resolveModelAlias(agent, tier, overrides);
@@ -2951,8 +2996,12 @@ const isDryRunRoutingEligible = (r) => r.status === "dry-run";
  * routing (posture `not_evaluated_manual_override`) and for `quality`/`speed`;
  * the exact transition token — including the `cheap` floor — under
  * `maximize_subscription`. Total and exhaustive over {@link ModelTier}.
+ * BAPI-1343: `none` whenever a `threshold` marker is supplied, because a
+ * threshold-decided tier is final and is never downshifted.
  */
-function resolveModelRoutingDecisionAdjustment(posture, baseline) {
+function resolveModelRoutingDecisionAdjustment(posture, baseline, threshold) {
+    if (threshold)
+        return "none";
     if (posture !== "maximize_subscription")
         return "none";
     switch (baseline) {
@@ -2973,7 +3022,24 @@ function resolveModelRoutingDecisionAdjustment(posture, baseline) {
 export function formatModelRoutingDecisionDiagnosticLine(input) {
     return (`[model-routing] source=${input.source} baseline=${input.baseline} ` +
         `posture=${input.posture} adjustment=${input.adjustment} effective=${input.effective} ` +
-        `alias=${input.alias ?? "unresolved"}`);
+        `alias=${input.alias ?? "unresolved"}` +
+        (input.threshold ? ` threshold=${input.threshold}` : ""));
+}
+/**
+ * BAPI-1343 R-6: the threshold marker for a successfully fetched `/model-tier`
+ * response when — and only when — the maximize downshift must be skipped:
+ * posture is `maximize_subscription` AND the response is threshold-decided
+ * (`configured` or `anomaly`). Every other case returns `undefined`, so the
+ * caller keeps today's exact downshift and text.
+ */
+function thresholdSkipMarker(posture, tierResult) {
+    if (posture !== "maximize_subscription")
+        return undefined;
+    if (!tierResult || !tierResult.ok)
+        return undefined;
+    if (!isThresholdDecidedTierResponse(tierResult.value))
+        return undefined;
+    return tierResult.value.thresholdMode;
 }
 /**
  * Best-effort emitter: calls the supplied stderr sink once and swallows any
@@ -3160,36 +3226,63 @@ errorLog = (message) => console.error(message)) {
         // chained automation handoff (e.g. `/review-and-implement`'s `--auto-tier`).
         // Routed through the CURRENT session's posture EXACTLY ONCE — unlike the
         // manual override above, this path IS subject to `downshiftModelTier()`
-        // under `maximize_subscription` — while skipping ONLY the redundant
-        // per-ticket `fetchTicketModelTiersForRows()` lookup. The alias is
-        // resolved+validated ONCE (identical for every row), matching the premium
-        // fallback / injected-tier hoisting pattern above.
-        const effectiveTier = posture === "maximize_subscription" ? downshiftModelTier(autoTier) : autoTier;
-        const adjustment = resolveModelRoutingDecisionAdjustment(posture, autoTier);
-        const lineageSuffix = posture === "maximize_subscription"
-            ? `; auto-tier:${autoTier}->maximize:${effectiveTier}`
-            : "";
-        const alias = resolveRoutingAlias(agent, effectiveTier, overrides, catalog);
-        let resolvedAlias = null;
-        let aliasWarning = null;
-        if (!alias) {
-            aliasWarning = `model routing: no valid alias for tier=${effectiveTier}; using agent default`;
-        }
-        else {
-            const validation = await validateResolvedModelAliasForAgent(deps, agent, alias);
-            if (validation.ok) {
-                resolvedAlias = validation.alias;
+        // under `maximize_subscription` — while never re-deriving the tier from a
+        // per-ticket lookup. The alias is resolved+validated at most ONCE per
+        // distinct effective tier, matching the premium fallback / injected-tier
+        // hoisting pattern above.
+        //
+        // BAPI-1343 R-6: under `maximize_subscription` ONLY, each eligible row's
+        // `/model-tier` is fetched once (the shared bounded fetch, no `consumer`
+        // parameter) purely to read `threshold_mode`. A threshold-decided
+        // (`configured`/`anomaly`) response keeps the carried tier — stored
+        // thresholds made it final. A fetch failure, `legacy`, or anything else
+        // downshifts exactly as before. `quality`/`speed` never downshift, so they
+        // make no extra request.
+        const thresholdTierMap = posture === "maximize_subscription"
+            ? await fetchTicketModelTiersForRows(access, eligible, options.maxParallel, isEligible)
+            : null;
+        const aliasByEffectiveTier = new Map();
+        const resolveAutoTierAlias = async (effectiveTier) => {
+            const cached = aliasByEffectiveTier.get(effectiveTier);
+            if (cached)
+                return cached;
+            const alias = resolveRoutingAlias(agent, effectiveTier, overrides, catalog);
+            let resolved;
+            if (!alias) {
+                resolved = {
+                    resolvedAlias: null,
+                    aliasWarning: `model routing: no valid alias for tier=${effectiveTier}; using agent default`,
+                };
             }
             else {
-                aliasWarning = validation.warning;
+                const validation = await validateResolvedModelAliasForAgent(deps, agent, alias);
+                resolved = validation.ok
+                    ? { resolvedAlias: validation.alias, aliasWarning: null }
+                    : { resolvedAlias: null, aliasWarning: validation.warning };
             }
-        }
-        const reason = resolvedAlias
-            ? `auto-tier=${autoTier} model=${resolvedAlias} (posture=${posture})${lineageSuffix}`
-            : `${aliasWarning}${lineageSuffix}`;
-        out = rows.map((row) => {
-            if (!isEligible(row))
-                return row;
+            aliasByEffectiveTier.set(effectiveTier, resolved);
+            return resolved;
+        };
+        const autoOut = [];
+        for (const row of rows) {
+            if (!isEligible(row)) {
+                autoOut.push(row);
+                continue;
+            }
+            const threshold = thresholdSkipMarker(posture, thresholdTierMap?.get(row.key));
+            const effectiveTier = posture === "maximize_subscription" && !threshold
+                ? downshiftModelTier(autoTier)
+                : autoTier;
+            const adjustment = resolveModelRoutingDecisionAdjustment(posture, autoTier, threshold);
+            const lineageSuffix = threshold
+                ? `; threshold:${threshold}`
+                : posture === "maximize_subscription"
+                    ? `; auto-tier:${autoTier}->maximize:${effectiveTier}`
+                    : "";
+            const { resolvedAlias, aliasWarning } = await resolveAutoTierAlias(effectiveTier);
+            const reason = resolvedAlias
+                ? `auto-tier=${autoTier} model=${resolvedAlias} (posture=${posture})${lineageSuffix}`
+                : `${aliasWarning}${lineageSuffix}`;
             const baseRow = {
                 ...row,
                 difficulty: null,
@@ -3201,14 +3294,10 @@ errorLog = (message) => console.error(message)) {
                     ? { modelRoutingDiagnostic: codexEntitlementDiagnostic(access.repoName) }
                     : {}),
             };
-            return aliasWarning ? appendSummaryRowWarning(baseRow, aliasWarning) : baseRow;
-        });
-        // BAPI-1236: one `automatic_snapshot` diagnostic per eligible row — the
-        // carried baseline, the newly resolved posture, the exact adjustment token,
-        // the calculated effective tier, and the validated alias (or `unresolved`).
-        for (const row of rows) {
-            if (!isEligible(row))
-                continue;
+            autoOut.push(aliasWarning ? appendSummaryRowWarning(baseRow, aliasWarning) : baseRow);
+            // BAPI-1236: one `automatic_snapshot` diagnostic per eligible row — the
+            // carried baseline, the newly resolved posture, the exact adjustment token,
+            // the calculated effective tier, and the validated alias (or `unresolved`).
             emitModelRoutingDecisionDiagnostic(errorLog, {
                 source: "automatic_snapshot",
                 baseline: autoTier,
@@ -3216,8 +3305,10 @@ errorLog = (message) => console.error(message)) {
                 adjustment,
                 effective: effectiveTier,
                 alias: resolvedAlias,
+                ...(threshold ? { threshold } : {}),
             });
         }
+        out = autoOut;
     }
     else {
         // Ordinary per-ticket difficulty-lookup path.
@@ -3298,12 +3389,24 @@ errorLog = (message) => console.error(message)) {
             // alias table. Copilot never reaches this loop at all: it has no
             // `AGENT_REGISTRY` entry and `isRunnableHostTarget()` rejects hosts
             // without a launch agent before an `AgentSpec` is ever resolved.
+            //
+            // BAPI-1343 R-6: the response is already in hand — when it is
+            // threshold-decided (`configured`/`anomaly`), stored thresholds made the
+            // tier final, so the maximize downshift is skipped and the lineage and
+            // diagnostic carry a distinct `threshold` marker instead. The harness-
+            // local premium fallback above is untouched.
             const difficultyTier = tier;
-            const effectiveTier = posture === "maximize_subscription" ? downshiftModelTier(difficultyTier) : difficultyTier;
-            const adjustment = resolveModelRoutingDecisionAdjustment(posture, difficultyTier);
-            const lineageSuffix = posture === "maximize_subscription"
-                ? `; difficulty:${difficultyTier}->maximize:${effectiveTier}`
-                : "";
+            const threshold = thresholdSkipMarker(posture, tierResult);
+            const effectiveTier = posture === "maximize_subscription" && !threshold
+                ? downshiftModelTier(difficultyTier)
+                : difficultyTier;
+            const adjustment = resolveModelRoutingDecisionAdjustment(posture, difficultyTier, threshold);
+            const lineageSuffix = threshold
+                ? `; threshold:${threshold}`
+                : posture === "maximize_subscription"
+                    ? `; difficulty:${difficultyTier}->maximize:${effectiveTier}`
+                    : "";
+            const thresholdField = threshold ? { threshold } : {};
             // BAPI-1236: stamp `difficulty_lookup` rather than copying the backend
             // cache/computation source (`cached`/`computed`/`fallback`) into the
             // summary's own routing-provenance field — that backend source is
@@ -3325,6 +3428,7 @@ errorLog = (message) => console.error(message)) {
                     adjustment,
                     effective: effectiveTier,
                     alias: null,
+                    ...thresholdField,
                 });
                 continue;
             }
@@ -3338,6 +3442,7 @@ errorLog = (message) => console.error(message)) {
                     adjustment,
                     effective: effectiveTier,
                     alias: null,
+                    ...thresholdField,
                 });
                 continue;
             }
@@ -3356,6 +3461,7 @@ errorLog = (message) => console.error(message)) {
                 adjustment,
                 effective: effectiveTier,
                 alias: validation.alias,
+                ...thresholdField,
             });
         }
         out = loopOut;
@@ -3835,14 +3941,13 @@ export async function orchestrateStartTickets(deps, options, overrides = {}) {
     const rows = await spawnTabsFn(deps, scoped, terminal, platformConfig.config.buildAgentShellCommand);
     return { ok: true, rows };
 }
-/** Platform-specific guidance printed when one or more tabs fail to spawn. */
-function spawnFailureHintForPlatform(platform) {
+/**
+ * Platform-specific guidance printed when one or more tabs fail to spawn.
+ * Exported for the BAPI-1319 byte-identity pin on the darwin sentence.
+ */
+export function spawnFailureHintForPlatform(platform) {
     if (platform === "darwin") {
-        return ("One or more tabs failed to spawn. If osascript reported a permission error, grant the " +
-            "required macOS permissions under System Settings -> Privacy & Security, then re-run: " +
-            "Automation (to let the terminal app be controlled) and, for the Terminal.app path, " +
-            "Accessibility (the new-tab step sends Cmd-T via System Events keystrokes, which Automation " +
-            "alone does not cover).");
+        return "One or more tabs failed to spawn. " + macosTerminalPermissionGuidance();
     }
     if (platform === "win32") {
         return ("One or more tabs failed to spawn. Ensure Windows Terminal (wt.exe) or PowerShell is " +

package/build/upgrade-cli.js

@@ -42,26 +42,85 @@ import { fetchLatestVersion } from "./cli-release.js";
 import { CANONICAL_UPGRADE_COMMAND } from "./upgrade-advice.js";
 import { describeLauncherReason, inspectLauncherConfigs, isApplicableStandardLauncher, isPrerequisiteFailure, LAUNCHER_CONFIG_TARGETS, } from "./launcher-config-inspection.js";
 import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
+import { defaultNpmEntryFileExists, resolveNpmEntry } from "./windows-npm-entry.js";
 /** The sentinel this CLI passes to the child it re-execs from `@latest`. */
 const INTERNAL_REEXEC_FLAG = "--internal-reexec";
-// ---------------------------------------------------------------------------
-// Default dependency construction
-// ---------------------------------------------------------------------------
-function defaultReexec(cwd, oldVersion) {
-    const npxCmd = process.platform === "win32" ? "npx.cmd" : "npx";
+/**
+ * The fixed, secret-free message printed when, on Windows, the latest CLI could
+ * not be STARTED. Upgrade stops here rather than continuing with the local copy.
+ */
+export const UPGRADE_REEXEC_START_FAILURE_MESSAGE = "Bridge API upgrade failed: could not start the latest version of the CLI. " +
+    `Nothing was changed. Run ${CANONICAL_UPGRADE_COMMAND} to run the latest copy directly.`;
+export function defaultReexec(cwd, oldVersion, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const doSpawn = options.spawn ?? spawn;
+    const errorLog = options.errorLog ?? ((message) => console.error(message));
+    const reexecArgs = [
+        "-y",
+        `${MCP_PACKAGE_NAME}@latest`,
+        "upgrade",
+        INTERNAL_REEXEC_FLAG,
+        "--old-version",
+        oldVersion,
+    ];
+    if (platform !== "win32") {
+        return new Promise((resolve) => {
+            const child = doSpawn("npx", reexecArgs, { stdio: "inherit", cwd });
+            child.on("close", (code) => resolve(code ?? 0));
+            child.on("error", (err) => {
+                errorLog(`Bridge API upgrade failed: could not re-exec npx: ${err.message}`);
+                resolve(1);
+            });
+        });
+    }
+    // WINDOWS (BAPI-1319): run npm's `npx-cli.js` through Node, never `npx.cmd`
+    // (EINVAL without a shell since CVE-2024-27980). A launch that fails before the
+    // child starts STOPS the upgrade with a fixed message — it never continues with
+    // the local copy, and a sync throw can no longer escape as an unhandled rejection.
+    const resolved = resolveNpmEntry("npx", reexecArgs, {
+        platform,
+        env: options.env ?? process.env,
+        execPath: options.execPath ?? process.execPath,
+        fileExists: options.fileExists ?? defaultNpmEntryFileExists,
+    });
+    if (resolved.status !== "resolved") {
+        errorLog(UPGRADE_REEXEC_START_FAILURE_MESSAGE);
+        return Promise.resolve(1);
+    }
     return new Promise((resolve) => {
-        const child = spawn(npxCmd, [
-            "-y",
-            `${MCP_PACKAGE_NAME}@latest`,
-            "upgrade",
-            INTERNAL_REEXEC_FLAG,
-            "--old-version",
-            oldVersion,
-        ], { stdio: "inherit", cwd });
-        child.on("close", (code) => resolve(code ?? 0));
+        let settled = false;
+        let started = false;
+        const settle = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(code);
+        };
+        const failToStart = () => {
+            if (settled)
+                return;
+            errorLog(UPGRADE_REEXEC_START_FAILURE_MESSAGE);
+            settle(1);
+        };
+        let child;
+        try {
+            child = doSpawn(resolved.command, resolved.args, { shell: false, stdio: "inherit", cwd });
+        }
+        catch {
+            failToStart();
+            return;
+        }
+        child.on("spawn", () => {
+            started = true;
+        });
+        child.on("close", (code) => settle(code ?? 0));
         child.on("error", (err) => {
-            console.error(`Bridge API upgrade failed: could not re-exec npx: ${err.message}`);
-            resolve(1);
+            if (!started) {
+                failToStart();
+                return;
+            }
+            errorLog(`Bridge API upgrade failed: could not re-exec npx: ${err.message}`);
+            settle(1);
         });
     });
 }
@@ -77,13 +136,39 @@ async function defaultHasCompetingLocalInstall(cwd) {
         return false;
     }
 }
-function defaultRemoveCompetingLocalInstall(cwd) {
-    const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
-    return new Promise((resolve) => {
-        const child = spawn(npmCmd, ["uninstall", MCP_PACKAGE_NAME], {
-            stdio: "inherit",
-            cwd,
+export function defaultRemoveCompetingLocalInstall(cwd, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const doSpawn = options.spawn ?? spawn;
+    const removeArgs = ["uninstall", MCP_PACKAGE_NAME];
+    if (platform !== "win32") {
+        return new Promise((resolve) => {
+            const child = doSpawn("npm", removeArgs, {
+                stdio: "inherit",
+                cwd,
+            });
+            child.on("close", (code) => resolve(code === 0));
+            child.on("error", () => resolve(false));
         });
+    }
+    // WINDOWS (BAPI-1319): `npm-cli.js` through Node. Every launch failure resolves
+    // false, which reaches the caller's existing "could not remove" message.
+    const resolved = resolveNpmEntry("npm", removeArgs, {
+        platform,
+        env: options.env ?? process.env,
+        execPath: options.execPath ?? process.execPath,
+        fileExists: options.fileExists ?? defaultNpmEntryFileExists,
+    });
+    if (resolved.status !== "resolved")
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = doSpawn(resolved.command, resolved.args, { shell: false, stdio: "inherit", cwd });
+        }
+        catch {
+            resolve(false);
+            return;
+        }
         child.on("close", (code) => resolve(code === 0));
         child.on("error", () => resolve(false));
     });
@@ -95,9 +180,9 @@ export function createDefaultUpgradeCliDeps(cwd) {
         fetchLatestVersion,
         readFile: (filePath) => readFile(filePath, "utf-8"),
         hasCompetingLocalInstall: defaultHasCompetingLocalInstall,
-        removeCompetingLocalInstall: defaultRemoveCompetingLocalInstall,
+        removeCompetingLocalInstall: (installCwd) => defaultRemoveCompetingLocalInstall(installCwd),
         runInit,
-        reexecFromLatest: defaultReexec,
+        reexecFromLatest: (reexecCwd, oldVersion) => defaultReexec(reexecCwd, oldVersion),
         stdout: (m) => console.log(m),
         stderr: (m) => console.error(m),
         env: process.env,

package/build/version.generated.js

@@ -1,4 +1,4 @@
 // AUTO-GENERATED — do not edit manually. Regenerate with: npm run build
-export const VERSION = "0.2.65";
-export const BUILD_COMMIT = "a6ee899f43d8";
-export const LAUNCHER_ARGS = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.65", "serve"];
+export const VERSION = "0.2.66";
+export const BUILD_COMMIT = "b90190f51abc";
+export const LAUNCHER_ARGS = ["-y", "--prefer-offline", "@bridge_gpt/mcp-server@0.2.66", "serve"];