@bridge_gpt/mcp-server 0.2.62 → 0.2.66

package/build/install-bridge.js

@@ -143,10 +143,11 @@ import { randomBytes as cryptoRandomBytes, createHash } from "crypto";
 import os from "os";
 import path from "path";
 import readline from "readline";
-import { runInit, InitPreflightError, buildBridgeApiEntry, mergeBridgeApiProfileToken, resolveInitScaffoldAssets, refreshBridgeApiPackageSpec, currentBridgePackageSpec, } from "./init.js";
+import { runInit, InitPreflightError, buildBridgeApiEntry, buildBridgeConfigManifest, mergeBridgeApiProfileToken, resolveInitScaffoldAssets, refreshBridgeApiPackageSpec, currentBridgePackageSpec, classifyTrackedProbeExitCode, decideExistingProjectRoot, formatUndeterminedRootReplacedWarning, } from "./init.js";
 import { hasProjectRootMarker as sharedHasProjectRootMarker } from "./project-root.js";
 import { VERSION } from "./version.generated.js";
-import { validateRepoName } from "./bridge-config.js";
+import { bridgeConfigPath, parseBridgeConfigToml, rewriteBridgeConfigRepoName, validateBridgeConfigRepoNameRepresentability, validateRepoName, } from "./bridge-config.js";
+import { renderDiagnosticValue } from "./diagnostic-text.js";
 import { MCP_HOST_TARGETS, HOST_PLATFORM_ORDER, allHostTargets, agentForPlatform, isHostPlatformId, detectDefaultPlatforms, hostAdapterForTarget, } from "./mcp-host-targets.js";
 import { provisionHostTarget, createDefaultVendorProcessDeps, inspectBridgeApiProfileToken, } from "./mcp-host-config.js";
 import { adaptBridgeEntryForHostTarget, } from "./mcp-host-entry-adapter.js";
@@ -190,6 +191,8 @@ import { fetchBitbucketConfigurationState } from "./connect-bitbucket-api.js";
 import { createDefaultConnectBitbucketDeps, runBitbucketConnectionFlow } from "./connect-bitbucket.js";
 import { resolveAgentSpec, isAgentName, formatValidAgentNames, resolveModelAlias, } from "./agent-registry.js";
 import { buildGenericAgentShellCommand, getDefaultSpawnTerminalTabForPlatform, detectTerminal, createDefaultStartTicketsDeps, materializeWorkerLaunchCommand, MAX_TERMINAL_COMMAND_BYTES, validateResolvedModelAliasForAgent, } from "./start-tickets.js";
+import { defaultNpmEntryFileExists, resolveNpmEntry } from "./windows-npm-entry.js";
+import { macosTerminalPermissionGuidance } from "./macos-terminal-permission-guidance.js";
 /** Redaction sentinel — the API-key value is NEVER printed; this stands in. */
 export const REDACTED_API_KEY = "<REDACTED>";
 /**
@@ -1261,11 +1264,32 @@ export function sanitizePrewarmEnv(env) {
     delete sanitized[INSTALL_REEXEC_KEY_SOURCE_ENV];
     return sanitized;
 }
-function spawnPrewarmDefault(command, args, env) {
+export function spawnPrewarmDefault(command, args, env, options = {}) {
+    const doSpawn = options.spawn ?? spawn;
     return new Promise((resolve) => {
         const sanitizedEnv = sanitizePrewarmEnv(env);
+        // WINDOWS (BAPI-1319): a bare `npx` is ENOENT without a shell, so the
+        // pre-warm never ran. Map it to npm's `npx-cli.js` through Node, resolved
+        // against the SANITIZED env the child actually receives. Other platforms
+        // pass through unchanged.
+        let spawnCommand = command;
+        let spawnArgs = args;
+        if (command === "npx") {
+            const resolved = resolveNpmEntry("npx", args, {
+                platform: options.platform ?? process.platform,
+                env: sanitizedEnv,
+                execPath: options.execPath ?? process.execPath,
+                fileExists: options.fileExists ?? defaultNpmEntryFileExists,
+            });
+            if (resolved.status !== "resolved") {
+                resolve({ ok: false, warning: "the pre-warm process could not be started" });
+                return;
+            }
+            spawnCommand = resolved.command;
+            spawnArgs = resolved.args;
+        }
         try {
-            const child = spawn(command, args, {
+            const child = doSpawn(spawnCommand, spawnArgs, {
                 shell: false,
                 stdio: "ignore",
                 timeout: 60_000,
@@ -1929,7 +1953,10 @@ export async function resolveInviteToken(options, deps) {
 const INSTALL_BRIDGE_SIGNUP_EMAIL_SHAPE = /^[^@\s]+@[^@\s]+$/;
 /** The one hint line printed after a blank/malformed email, before the single re-prompt. */
 export const INSTALL_BRIDGE_SIGNUP_EMAIL_HINT = "Enter a valid email address (e.g. you@example.com).";
-export async function resolveSignupEmail(options, deps) {
+export function buildInstallBridgeSignupPrivacyNotice(baseUrl) {
+    return `Privacy Policy: ${baseUrl.replace(/\/+$/, "")}/privacy`;
+}
+export async function resolveSignupEmail(options, deps, baseUrl = DEFAULT_BAPI_BASE_URL) {
     // BAPI-757 (R-3 / AC-9): self-serve signup now REQUIRES an interactive terminal,
     // and the check runs FIRST — before `--email` and before `BAPI_SIGNUP_EMAIL` —
     // so an unattended run fails before any request is made, no verification email
@@ -1940,6 +1967,7 @@ export async function resolveSignupEmail(options, deps) {
     if (!deps.isTTY || !deps.promptLine) {
         return { ok: false, error: INSTALL_BRIDGE_SIGNUP_REQUIRES_TTY };
     }
+    deps.log(buildInstallBridgeSignupPrivacyNotice(baseUrl));
     if (typeof options.email === "string" && options.email.trim().length > 0) {
         return { ok: true, value: options.email.trim() };
     }
@@ -2987,23 +3015,25 @@ function trackedConfigWarning(relPath) {
  * Read-only probe: is `relPath` already tracked by git in the project (BAPI-666)?
  * Runs `git ls-files --error-unmatch -- <relPath>` through the injected, list-based
  * command seam (never a shell string) with `cwd = deps.cwd`. ONLY exit code 0 means
- * tracked; every other outcome — a non-zero exit (untracked / gitignored), a non-git
- * directory, or a thrown command failure — is treated as NOT tracked, preserving the
- * required fail-open behavior (a probe failure must never block the install). Emits at
- * most a fixed debug-level line (safe relative path + exit classification) and never
- * the command's stdout/stderr, exception text, env, or config content.
+ * tracked; exit 1 is untracked, and every other outcome — another exit code (a
+ * non-git directory), or a thrown command failure — is `undetermined` (BAPI-1318).
+ * Every caller treats `undetermined` as NOT tracked, preserving the required
+ * fail-open behavior (a probe failure must never block the install). Emits at most a
+ * fixed debug-level line (safe relative path + exit classification) and never the
+ * command's stdout/stderr, exception text, env, or config content.
  */
 async function isTrackedProjectConfig(deps, relPath) {
     try {
         const result = await deps.startTicketsDeps.runCommand("git", ["ls-files", "--error-unmatch", "--", relPath], { cwd: deps.cwd });
-        if (result.exitCode === 0)
-            return true;
+        const verdict = classifyTrackedProbeExitCode(result.exitCode);
+        if (verdict === "tracked")
+            return verdict;
         deps.debugLog(`install-bridge: git-tracked probe for ${relPath} → not tracked (exit ${result.exitCode})`);
-        return false;
+        return verdict;
     }
     catch {
         deps.debugLog(`install-bridge: git-tracked probe for ${relPath} → not tracked (probe failed)`);
-        return false;
+        return "undetermined";
     }
 }
 /**
@@ -3038,12 +3068,24 @@ async function requestTrackedConfigConsent(deps, relPath) {
  * cannot recognize — the new template args (which DO include `serve`) are used
  * verbatim. `command` and `env` always come from the freshly built entry: this
  * helper governs launcher-token migration only, never credentials.
+ *
+ * BAPI-1318: the one exception is `BAPI_PROJECT_ROOT`. With `preserveProjectRoot`
+ * set (the config is git-tracked), an existing non-blank value is kept exactly
+ * rather than replaced by this machine's `cwd`; a blank or absent value still
+ * takes the fresh entry's root.
  */
-export function preserveExistingLauncherArgs(existing, entry) {
+export function preserveExistingLauncherArgs(existing, entry, options = {}) {
     const existingEntry = asRecord(existing) ?? {};
     const existingArgs = asRecord(existing)?.args;
     const preserved = refreshBridgeApiPackageSpec(existingArgs, currentBridgePackageSpec());
-    return { ...existingEntry, ...entry, ...(preserved ? { args: preserved } : {}) };
+    const merged = { ...existingEntry, ...entry, ...(preserved ? { args: preserved } : {}) };
+    if (options.preserveProjectRoot) {
+        const existingRoot = asRecord(existingEntry.env)?.BAPI_PROJECT_ROOT;
+        if (typeof existingRoot === "string" && existingRoot.trim().length > 0) {
+            merged.env = { ...merged.env, BAPI_PROJECT_ROOT: existingRoot };
+        }
+    }
+    return merged;
 }
 /**
  * Read-only pre-scan for both-key configs across EVERY project target (BAPI-807).
@@ -3107,7 +3149,8 @@ async function writeHostConfigs(deps, targets, entries, trackedState, ctx) {
         }
         // Choose the entry variant. A real key only lands in an untracked target, or a
         // tracked target the user EXPLICITLY consented to on a TTY.
-        const tracked = trackedState.get(target.relPath) ?? false;
+        const trackedVerdict = trackedState.get(target.relPath) ?? "untracked";
+        const tracked = trackedVerdict === "tracked";
         let entry = entries.real;
         let mode = "real-key";
         if (tracked) {
@@ -3154,7 +3197,18 @@ async function writeHostConfigs(deps, targets, entries, trackedState, ctx) {
         // real-key and secret-free variants: credential safety must not decide whether
         // a launcher is migrated.
         const physicalEntry = adaptBridgeEntryForHostTarget(entry, target.target);
-        topLevel[registrationKey] = preserveExistingLauncherArgs(topLevel[registrationKey], physicalEntry);
+        // BAPI-1318: the tracked-root rule matches runInit's, for BOTH variants: a
+        // tracked config keeps its committed non-blank BAPI_PROJECT_ROOT. An
+        // undetermined probe fails open (cwd is written) and warns once when that
+        // replaces a different existing value.
+        const existingRoot = asRecord(asRecord(topLevel[registrationKey])?.env)?.BAPI_PROJECT_ROOT;
+        const rootDecision = decideExistingProjectRoot(existingRoot, deps.cwd, trackedVerdict);
+        if (asRecord(topLevel[registrationKey]) && rootDecision.warnReplaced) {
+            deps.errorLog(formatUndeterminedRootReplacedWarning(target.relPath));
+        }
+        topLevel[registrationKey] = preserveExistingLauncherArgs(topLevel[registrationKey], physicalEntry, {
+            preserveProjectRoot: tracked,
+        });
         config[target.topLevelKey] = topLevel;
         await deps.mkdir(path.dirname(fullPath), { recursive: true });
         await deps.writeFile(fullPath, JSON.stringify(config, null, 2) + "\n", {
@@ -3164,6 +3218,160 @@ async function writeHostConfigs(deps, targets, entries, trackedState, ctx) {
     }
     return { written, skipped, duplicateRegistrations: [] };
 }
+// ---------------------------------------------------------------------------
+// BAPI-1318: `.bridge/config` final-name reconciliation and consented repair
+// ---------------------------------------------------------------------------
+/** The doctor command every `.bridge/config` repair warning points at. */
+const BRIDGE_CONFIG_DOCTOR_HINT = `Then run "npx -y ${MCP_PACKAGE_NAME} doctor" to confirm.`;
+/** Mismatch warning with the exact fix line (non-TTY or declined repair). */
+export function formatBridgeConfigMismatchWarning(fileName, provenName) {
+    const file = renderDiagnosticValue(fileName);
+    const proven = renderDiagnosticValue(provenName);
+    return (`.bridge/config names '${file}' but this project is '${proven}'. Worktrees and shell tools ` +
+        `will use the wrong project. Fix: set repo_name = "${proven}" in .bridge/config. ` +
+        BRIDGE_CONFIG_DOCTOR_HINT);
+}
+/** Warning for a proven name the manifest's TOML subset cannot hold: no fix line. */
+export function formatBridgeConfigUnrepresentableWarning(fileName, provenName) {
+    const proven = renderDiagnosticValue(provenName);
+    const lead = fileName === null
+        ? `.bridge/config could not be updated to '${proven}'`
+        : `.bridge/config names '${renderDiagnosticValue(fileName)}' but this project is '${proven}'`;
+    return (`${lead}, and that name cannot be written in .bridge/config (quotes and backslashes are not ` +
+        `supported). Automatic repair is unavailable. ${BRIDGE_CONFIG_DOCTOR_HINT}`);
+}
+/** Warning for a `.bridge/config` that does not parse. */
+export function formatBridgeConfigMalformedWarning() {
+    return (".bridge/config could not be parsed, so its project name was not checked or changed. " +
+        `Fix the file by hand. ${BRIDGE_CONFIG_DOCTOR_HINT}`);
+}
+/** Warning for a read, prompt, or write failure during the advisory repair. */
+export function formatBridgeConfigRepairFailedWarning() {
+    return (".bridge/config could not be checked or updated (a read or write failed); it was left " +
+        `unchanged. Check its repo_name by hand. ${BRIDGE_CONFIG_DOCTOR_HINT}`);
+}
+/**
+ * Replace `.bridge/config` atomically: write a sibling temp file with the
+ * original file mode, then rename it over the target. A failure removes the temp
+ * file (best effort) and rethrows so the advisory caller can warn.
+ */
+async function writeBridgeConfigAtomically(deps, configPath, text) {
+    let mode;
+    try {
+        const info = (await deps.stat(configPath));
+        if (typeof info?.mode === "number")
+            mode = info.mode & 0o777;
+    }
+    catch {
+        mode = undefined;
+    }
+    const tempPath = `${configPath}.${deps.randomBytes(6).toString("hex")}.tmp`;
+    try {
+        await deps.writeFile(tempPath, text, mode !== undefined ? { encoding: "utf-8", mode } : { encoding: "utf-8" });
+        if (mode !== undefined)
+            await deps.chmod(tempPath, mode);
+        await deps.rename(tempPath, configPath);
+    }
+    catch (error) {
+        try {
+            await deps.unlink(tempPath);
+        }
+        catch {
+            /* best-effort temp cleanup only; the original file is untouched */
+        }
+        throw error;
+    }
+}
+/**
+ * After the ping has PROVEN `provenName`, make `<cwd>/.bridge/config` agree with
+ * it (BAPI-1318). Only the install folder's own file is read — never a parent's,
+ * so a monorepo subfolder that is its own Bridge project stays safe.
+ *
+ *  - `createdText` is the exact text THIS run scaffolded (null when it did not
+ *    create the file). If the file still holds exactly that text, it is this
+ *    run's own output: a later rename (409 loop or invite exchange) is written
+ *    through without a prompt, with one line saying so.
+ *  - Otherwise the file is user-owned. A differing name is repaired only after a
+ *    default-No TTY consent; a non-TTY run or a "no" leaves it byte-identical and
+ *    warns with the exact fix.
+ *
+ * Advisory by contract: every failure warns and returns; nothing here can fail
+ * the install. Warnings name only the two project names, never file content.
+ */
+export async function reconcileBridgeConfigAfterPing(deps, provenName, createdText) {
+    const configPath = bridgeConfigPath(deps.cwd);
+    try {
+        let text;
+        try {
+            text = await deps.readFile(configPath);
+        }
+        catch (error) {
+            if (error?.code === "ENOENT")
+                return;
+            deps.errorLog(formatBridgeConfigRepairFailedWarning());
+            return;
+        }
+        const parsed = parseBridgeConfigToml(text);
+        if (!parsed.ok) {
+            deps.errorLog(formatBridgeConfigMalformedWarning());
+            return;
+        }
+        const fileName = parsed.manifest.repoName;
+        if (fileName === provenName)
+            return;
+        const representable = validateBridgeConfigRepoNameRepresentability(provenName);
+        if (!representable.ok) {
+            deps.errorLog(formatBridgeConfigUnrepresentableWarning(fileName, provenName));
+            return;
+        }
+        const ownFile = createdText !== null && text === createdText;
+        if (!ownFile) {
+            if (!deps.isTTY || !deps.promptLine) {
+                deps.errorLog(formatBridgeConfigMismatchWarning(fileName, provenName));
+                return;
+            }
+            const answer = (await deps.promptLine(`.bridge/config names '${renderDiagnosticValue(fileName)}' but this project is ` +
+                `'${renderDiagnosticValue(provenName)}'. Update repo_name in .bridge/config? (y/N) `)).trim().toLowerCase();
+            if (answer !== "y" && answer !== "yes") {
+                deps.errorLog(formatBridgeConfigMismatchWarning(fileName, provenName));
+                return;
+            }
+        }
+        // This run's own file already carries the notice from the scaffold, so a
+        // rewrite adds it only to an older user-owned file the user consented to.
+        const rewritten = rewriteBridgeConfigRepoName(text, provenName);
+        if (!rewritten.ok) {
+            deps.errorLog(rewritten.kind === "unrepresentable-name"
+                ? formatBridgeConfigUnrepresentableWarning(fileName, provenName)
+                : formatBridgeConfigMalformedWarning());
+            return;
+        }
+        await writeBridgeConfigAtomically(deps, configPath, rewritten.text);
+        deps.log(`  .bridge/config: repo_name updated from '${renderDiagnosticValue(fileName)}' to ` +
+            `'${renderDiagnosticValue(provenName)}'`);
+    }
+    catch {
+        deps.errorLog(formatBridgeConfigRepairFailedWarning());
+    }
+}
+/**
+ * Best-effort cleanup for a run that ends in failure before the ping proved the
+ * name (BAPI-1318): remove the `.bridge/config` this run created, but ONLY when
+ * its bytes still equal what this run wrote. A retry then scaffolds it fresh
+ * with the right name. A pre-existing or since-edited file is never removed, and
+ * a cleanup failure never masks the original failure.
+ */
+async function removeUnprovenBridgeConfig(deps, createdText) {
+    const configPath = bridgeConfigPath(deps.cwd);
+    try {
+        if ((await deps.readFile(configPath)) !== createdText)
+            return;
+        await deps.unlink(configPath);
+    }
+    catch {
+        /* advisory cleanup only */
+    }
+}
 /**
  * Provision the selected GLOBAL (Codex) and MANUAL (Windsurf)
  * targets through the registry-driven emitter (BAPI-635). Project JSON targets
@@ -4949,6 +5157,24 @@ export async function resolveValidatedPremiumModelAlias(deps, agent) {
  * parser/resolution errors return 1; a ping failure halts (return 1) BEFORE the
  * credential persist and agent spawn. The API key is never logged on any path.
  */
+/**
+ * The fixed message a bare install prints under Git Bash / mintty (BAPI-1319).
+ * mintty gives Node no TTY, so no prompt can be shown there; this replaces the
+ * confusing "no interactive terminal" credential error with the actual remedy.
+ */
+export const INSTALL_BRIDGE_MINTTY_MESSAGE = "This terminal (Git Bash / mintty) can't show Bridge's interactive prompts. " +
+    "Run the install from PowerShell or Windows Terminal, or pass --api-key <key> --repo <name>.";
+/**
+ * True for a native-Windows, non-TTY Git Bash / mintty session (BAPI-1319).
+ * Pure. Prompts are deliberately NOT enabled here: GitHub's Windows runners use
+ * bash with `MSYSTEM` set, and a prompt there would hang CI.
+ */
+export function isMinttyNonInteractiveInstall(platform, env, isTTY) {
+    if (platform !== "win32" || isTTY)
+        return false;
+    const msystem = env.MSYSTEM;
+    return (typeof msystem === "string" && msystem.trim().length > 0) || env.TERM_PROGRAM === "mintty";
+}
 export async function runInstallBridgeCli(argv, overrides = {}) {
     const deps = { ...createDefaultInstallBridgeDeps(), ...overrides };
     // When the caller overrode only `fetch` (the common test seam), bind the
@@ -5120,6 +5346,16 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // every downstream `deps.env` consumer observes it. The caller-owned object (and
     // `process.env`) is never mutated.
     deps.env = { ...deps.env, BAPI_BASE_URL: baseUrl };
+    // ---- BAPI-1319: bare install under Git Bash / mintty ----
+    // A bare run there has no TTY and no credential, so it would fall through to
+    // the "no interactive terminal" credential error. Say what actually helps
+    // instead, before anything is prompted for or written. Runs with arguments or
+    // an env credential are untouched.
+    const hasEnvCredential = (deps.env.BAPI_API_KEY ?? "").trim().length > 0 || (deps.env.BAPI_INVITE ?? "").trim().length > 0;
+    if (argv.length === 0 && !hasEnvCredential && isMinttyNonInteractiveInstall(deps.platform, deps.env, deps.isTTY)) {
+        errorLog(INSTALL_BRIDGE_MINTTY_MESSAGE);
+        return 1;
+    }
     // ---- BAPI-818 (R2): --dry-run short-circuits HERE — genuinely inert ----
     // Fires immediately after argument parsing and the pure base-URL validation
     // above, and strictly BEFORE the project-root confirmation prompt, onboarding
@@ -5296,7 +5532,7 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // key-authentication ping, so there is no source to attribute.
     let apiKeySource;
     if (selfServeSignupMode) {
-        const emailResult = await resolveSignupEmail(options, deps);
+        const emailResult = await resolveSignupEmail(options, deps, baseUrl);
         if (!emailResult.ok) {
             errorLog(`Error: ${emailResult.error}`);
             return 1;
@@ -5674,6 +5910,10 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
     // an exception that ESCAPED all of them.
     let currentStep = INSTALL_BRIDGE_STEP_LABELS.scaffold;
     let bootstrapExchangeSucceeded = false;
+    // BAPI-1318: the `.bridge/config` text Step 1 created (null when it created
+    // none), and whether it still awaits the ping that proves its name.
+    let scaffoldedBridgeConfigText = null;
+    let unprovenBridgeConfigPending = false;
     try {
         // ---- Step 1 — scaffold (secret-free placeholders only) ----
         currentStep = INSTALL_BRIDGE_STEP_LABELS.scaffold;
@@ -5683,9 +5923,17 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
         // Step 2 mints/verifies the key and Step 4 persists it, so a placeholder
         // warning here would be a false alarm about a config the installer is
         // actively configuring. The key value itself never crosses this boundary.
-        await deps.runInit(deps.cwd, {
+        const initResult = await deps.runInit(deps.cwd, {
             creationContext: { repoName, baseUrl, credentialAvailable: true },
+            isTrackedConfig: (relPath) => isTrackedProjectConfig(deps, relPath),
         });
+        // BAPI-1318: remember the exact `.bridge/config` text this run scaffolded. The
+        // name can still change (409 rename, server-returned invite name) before the
+        // ping proves it; until then a failed run removes its own unchanged file.
+        if (initResult && initResult.bridgeConfigCreated) {
+            scaffoldedBridgeConfigText = buildBridgeConfigManifest(initResult.bridgeConfigRepoName ?? repoName);
+            unprovenBridgeConfigPending = true;
+        }
         // ---- Step 2 — mint (invite mode) or verify (normal mode) the credential ----
         let inviteFingerprint = "";
         if (bootstrapInviteMode) {
@@ -6229,6 +6477,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                 : `Error: ${ping.message}`);
         }
         log("  connectivity OK");
+        // BAPI-1318: the name is proven now. Make `.bridge/config` agree with it —
+        // a rename of this run's own scaffold, or a consented repair of an older
+        // file. Advisory: it warns on any problem and never fails the install.
+        unprovenBridgeConfigPending = false;
+        await reconcileBridgeConfigAfterPing(deps, repoName, scaffoldedBridgeConfigText);
         // ---- BAPI-1221 (S2): persist the captured posture, now that connectivity
         // is validated and `repoName`/`apiKey` are both final. Overwrites any
         // existing value unconditionally — the old value is never read first. A
@@ -6567,6 +6820,10 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
                     // deterministic setup is complete, so this is a non-fatal warning (exit 0), with
                     // the same shared continuation so the remediation is consistent.
                     errorLog(`Warning: setup steps completed, but the agent session could not be opened (${spawnResult.error}).`);
+                    // BAPI-1319: on macOS the usual cause is a missing Automation or
+                    // Accessibility grant — the same guidance start-tickets prints.
+                    if (deps.platform === "darwin")
+                        errorLog(macosTerminalPermissionGuidance());
                     log(buildManualInstallBridgeContinuation("configured", labelsForPlatforms(selectedPlatforms)));
                     return 0;
                 }
@@ -6643,4 +6900,11 @@ export async function runInstallBridgeCli(argv, overrides = {}) {
             errorLog(line);
         return 1;
     }
+    finally {
+        // BAPI-1318: every exit before the ping proved the name is a failure, so a
+        // still-pending scaffold is removed when it is unchanged (see helper).
+        if (unprovenBridgeConfigPending && scaffoldedBridgeConfigText !== null) {
+            await removeUnprovenBridgeConfig(deps, scaffoldedBridgeConfigText);
+        }
+    }
 }