@bridge_gpt/mcp-server 0.2.31 → 0.2.33

package/build/credential-store.js

@@ -10,7 +10,8 @@
  * creates or initializes credential files. The mutation primitives — the
  * best-effort {@link upsertBapiCredential} and the fail-closed bootstrap-invite
  * pending-state operations ({@link prepareBootstrapPendingCredential},
- * {@link repointBootstrapPendingCredential}, {@link promoteBootstrapPendingCredential})
+ * {@link repointBootstrapPendingCredential}, {@link promoteBootstrapPendingCredential},
+ * {@link discardBootstrapPendingCredential})
  * — are the ONLY writers: they mutate the user-scoped primary store from explicit
  * install/migration code paths, preserve every other entry, and never touch
  * project/worktree config files (those remain secret-free). Every mutation runs
@@ -489,12 +490,40 @@ export async function durablyReplaceCredentialStoreJson(primaryPath, value, deps
  * durably saved but NOT yet redeemed. It is a separate top-level key from
  * `bapi:<repo>`, so the resolver never serves an unredeemed secret as a
  * credential, and a failed redemption never leaves a broken `bapi:<repo>` entry.
+ *
+ * A pending record has TWO shapes (BAPI-667), distinguished only by whether
+ * {@link BOOTSTRAP_PENDING_REPLAY_TOKEN_FIELD} is present:
+ *
+ *   - ORDINARY INVITE — `key_secret` + invite fingerprint. The token stays off
+ *     disk because the user holds it and can re-present it on a retry.
+ *   - SELF-SERVE — the same two fields PLUS the minted invite token, because the
+ *     token was never shown to the user and therefore cannot be re-presented.
+ *
+ * Both shapes are read by the same helpers; the ordinary shape is the historical
+ * one and remains fully valid, so records written before BAPI-667 keep working.
  */
 export const BOOTSTRAP_PENDING_TARGET_PREFIX = "bootstrap-pending:";
 /** Secret name holding the client-generated `key_secret` inside a pending record. */
 export const BOOTSTRAP_PENDING_SECRET_FIELD = "BAPI_API_KEY";
 /** Secret name holding the invite FINGERPRINT (a SHA-256 hex digest, not the token). */
 export const BOOTSTRAP_PENDING_FINGERPRINT_FIELD = "BOOTSTRAP_INVITE_FINGERPRINT";
+/**
+ * Secret name holding the INTERNALLY MINTED self-serve invite token (BAPI-667).
+ *
+ * SELF-SERVE RECORDS ONLY. An ordinary invite (`--invite` / `BAPI_INVITE` / an
+ * invite pasted into the ordinary credential input) is supplied BY the user, so a
+ * retry can re-present it and the record needs only the one-way fingerprint. A
+ * self-serve token is minted internally and never shown, so a fingerprint alone
+ * makes replay impossible BY CONSTRUCTION: every retry would mint a fresh token,
+ * present a fresh fingerprint, and hard-fail against its own pending record.
+ * Storing the token is what makes the self-serve arm retryable at all.
+ *
+ * This adds no new exposure class: the record already holds the strictly more
+ * sensitive `key_secret` and is written 0600 through the same locked, fsync'd
+ * {@link durablyReplaceCredentialStoreJson} path. Like every other value here it
+ * is NEVER logged, printed, or placed in an error string.
+ */
+export const BOOTSTRAP_PENDING_REPLAY_TOKEN_FIELD = "BOOTSTRAP_SELF_SERVE_INVITE";
 /** Pending target for a repo: `bootstrap-pending:<repo>`. */
 export function getBootstrapPendingTarget(repoName) {
     return `${BOOTSTRAP_PENDING_TARGET_PREFIX}${(repoName ?? "").trim()}`;
@@ -521,7 +550,19 @@ function hasExistingBapiKey(store, repoName) {
     const entry = store[getBapiTarget(repoName)];
     return (!!entry && typeof entry.BAPI_API_KEY === "string" && entry.BAPI_API_KEY.trim().length > 0);
 }
-/** Read a pending record whose fingerprint matches; `null` when absent/mismatched. */
+/** Trimmed string value of a pending-record field, or `""` when absent/blank. */
+function readPendingField(entry, field) {
+    const value = entry?.[field];
+    return typeof value === "string" ? value.trim() : "";
+}
+/**
+ * Read a pending record whose fingerprint matches; `null` when absent/mismatched.
+ *
+ * `replayToken` is present ONLY for a self-serve record (BAPI-667). An ordinary
+ * invite record predates that field and legitimately omits it, so its absence is
+ * NEVER a validity problem here — it just means "not resumable without the user
+ * re-presenting the token", which is exactly the ordinary-invite contract.
+ */
 function readMatchingPending(store, repoName, inviteFingerprint) {
     const entry = store[getBootstrapPendingTarget(repoName)];
     if (!entry)
@@ -532,7 +573,30 @@ function readMatchingPending(store, repoName, inviteFingerprint) {
         return null;
     if (fingerprint !== inviteFingerprint)
         return null;
-    return { keySecret: secret };
+    const replayToken = readPendingField(entry, BOOTSTRAP_PENDING_REPLAY_TOKEN_FIELD);
+    return replayToken.length > 0 ? { keySecret: secret, replayToken } : { keySecret: secret };
+}
+/**
+ * Build the pending-record entry written by prepare / repoint.
+ *
+ * Sibling secret names on the existing entry are preserved, but the replay-token
+ * field is set EXPLICITLY or removed — never inherited. Inheriting it would let a
+ * stale token from an earlier record ride along with a new `key_secret`,
+ * producing a record whose two halves belong to different redemptions.
+ */
+function buildPendingEntry(existing, keySecret, inviteFingerprint, replayToken) {
+    const next = {
+        ...(existing ?? {}),
+        [BOOTSTRAP_PENDING_SECRET_FIELD]: keySecret,
+        [BOOTSTRAP_PENDING_FINGERPRINT_FIELD]: inviteFingerprint,
+    };
+    if (replayToken && replayToken.length > 0) {
+        next[BOOTSTRAP_PENDING_REPLAY_TOKEN_FIELD] = replayToken;
+    }
+    else {
+        delete next[BOOTSTRAP_PENDING_REPLAY_TOKEN_FIELD];
+    }
+    return next;
 }
 /**
  * Does `bootstrap-pending:<repo>` hold a secret belonging to a DIFFERENT invite?
@@ -560,8 +624,29 @@ function hasConflictingPending(store, repoName, inviteFingerprint) {
         return false;
     return entry[BOOTSTRAP_PENDING_FINGERPRINT_FIELD] !== inviteFingerprint;
 }
-/** One wording for the conflict, so `prepare` and `repoint` cannot drift apart. */
-function pendingConflictError(target, primaryPath) {
+/** Does the stored (conflicting) pending record carry usable self-serve replay material? */
+function storedPendingIsSelfServe(store, repoName) {
+    const entry = store[getBootstrapPendingTarget(repoName)];
+    return readPendingField(entry, BOOTSTRAP_PENDING_REPLAY_TOKEN_FIELD).length > 0;
+}
+/**
+ * One wording for the conflict, so `prepare` and `repoint` cannot drift apart.
+ *
+ * MODE-AWARE (BAPI-667). A conflicting record that carries self-serve replay
+ * material is recoverable WITHOUT the user touching the store: re-running the
+ * self-serve flow resumes it. Telling that user to "remove the entry by hand" is
+ * the single worst instruction available — if its exchange already succeeded, the
+ * record is the only trace of a live admin key. A genuine cross-invite conflict
+ * (an ordinary, fingerprint-only record) keeps the original fail-closed guidance,
+ * because there the CLI genuinely cannot replay it.
+ */
+function pendingConflictError(target, primaryPath, storedIsSelfServe) {
+    if (storedIsSelfServe) {
+        return (`A pending self-serve signup for a DIFFERENT invite already exists at ${target} in ` +
+            `${primaryPath}. It is the only proof that can replay that signup, so it will not be ` +
+            "overwritten. Re-run install-bridge and choose the email option — it will resume that " +
+            "signup automatically. Do NOT remove the entry by hand.");
+    }
     return (`A pending bootstrap-invite credential for a DIFFERENT invite already exists at ${target} ` +
         `in ${primaryPath}. It is the only proof that can replay that redemption, so it will not be ` +
         "overwritten. Complete that redemption first, or — only if you are certain its invite was " +
@@ -579,12 +664,20 @@ function pendingConflictError(target, primaryPath) {
  * A fresh record is written through {@link durablyReplaceCredentialStoreJson}, so
  * a failed write or fsync produces a failure result and NO success value — the
  * caller cannot proceed to the exchange with a secret that is not on disk.
+ *
+ * BAPI-667: an optional {@link PrepareBootstrapPendingParams.selfServeReplayToken}
+ * is persisted in the SAME durable write, making the record self-serve-resumable.
+ * Omitting it (every `--invite` caller) preserves the fingerprint-only record shape
+ * exactly as before.
  */
 export async function prepareBootstrapPendingCredential(params, deps) {
     const primaryPath = getPrimaryCredentialStorePath(deps);
     const repoName = (params.repoName ?? "").trim();
     const fingerprint = (params.inviteFingerprint ?? "").trim();
     const target = getBootstrapPendingTarget(repoName);
+    // `undefined` = ordinary invite (fingerprint-only). A supplied value is trimmed
+    // and validated below; its CONTENTS never reach an error string.
+    const replayToken = params.selfServeReplayToken === undefined ? undefined : params.selfServeReplayToken.trim();
     if (repoName.length === 0) {
         return {
             ok: false,
@@ -603,6 +696,15 @@ export async function prepareBootstrapPendingCredential(params, deps) {
             error: "Cannot prepare a bootstrap-invite credential: the invite fingerprint was empty.",
         };
     }
+    if (replayToken !== undefined && replayToken.length === 0) {
+        return {
+            ok: false,
+            path: primaryPath,
+            target,
+            kind: "invalid-replay-token",
+            error: "Cannot prepare a self-serve bootstrap credential: the supplied replay material was empty.",
+        };
+    }
     return withCredentialStoreLock(deps, async () => {
         const loaded = await loadStoreForMutation(deps);
         if (!loaded.ok) {
@@ -622,10 +724,24 @@ export async function prepareBootstrapPendingCredential(params, deps) {
             };
         }
         const existing = readMatchingPending(base, repoName, fingerprint);
-        if (existing) {
+        if (existing && (replayToken === undefined || existing.replayToken === replayToken)) {
             // Reuse verbatim — this exact value is the replay proof. Do not regenerate.
             return { ok: true, path: primaryPath, target, keySecret: existing.keySecret, reused: true };
         }
+        if (existing) {
+            // Same invite + same repo, but the record predates (or lost) its replay
+            // material. Keep the `key_secret` — it is still the replay proof — and
+            // durably attach the token so the NEXT retry can resume without minting.
+            const upgraded = {
+                ...base,
+                [target]: buildPendingEntry(base[target], existing.keySecret, fingerprint, replayToken),
+            };
+            const rewritten = await durablyReplaceCredentialStoreJson(primaryPath, upgraded, deps);
+            if (!rewritten.ok) {
+                return { ok: false, path: primaryPath, target, kind: rewritten.kind, error: rewritten.error };
+            }
+            return { ok: true, path: primaryPath, target, keySecret: existing.keySecret, reused: true };
+        }
         // Not ours, but someone's: redeeming a second invite against a repo that
         // still holds a pending record for a first one would overwrite that record —
         // and if the first exchange already succeeded, its admin key becomes
@@ -636,17 +752,13 @@ export async function prepareBootstrapPendingCredential(params, deps) {
                 path: primaryPath,
                 target,
                 kind: "pending-conflict",
-                error: pendingConflictError(target, primaryPath),
+                error: pendingConflictError(target, primaryPath, storedPendingIsSelfServe(base, repoName)),
             };
         }
         const keySecret = params.generateKeySecret();
         const next = {
             ...base,
-            [target]: {
-                ...(base[target] ?? {}),
-                [BOOTSTRAP_PENDING_SECRET_FIELD]: keySecret,
-                [BOOTSTRAP_PENDING_FINGERPRINT_FIELD]: fingerprint,
-            },
+            [target]: buildPendingEntry(base[target], keySecret, fingerprint, replayToken),
         };
         const written = await durablyReplaceCredentialStoreJson(primaryPath, next, deps);
         if (!written.ok) {
@@ -716,16 +828,16 @@ export async function repointBootstrapPendingCredential(params, deps) {
                 path: primaryPath,
                 target,
                 kind: "pending-conflict",
-                error: pendingConflictError(target, primaryPath),
+                error: pendingConflictError(target, primaryPath, storedPendingIsSelfServe(base, toRepo)),
             };
         }
         const next = { ...base };
         delete next[getBootstrapPendingTarget(fromRepo)];
-        next[target] = {
-            ...(destination ?? {}),
-            [BOOTSTRAP_PENDING_SECRET_FIELD]: pending.keySecret,
-            [BOOTSTRAP_PENDING_FINGERPRINT_FIELD]: fingerprint,
-        };
+        // BAPI-667: the replay token moves WITH the `key_secret`. A rename that kept
+        // the secret but dropped the token would silently downgrade a resumable
+        // self-serve record into an unreplayable one at exactly the moment (a 409
+        // rename loop) a retry is most likely.
+        next[target] = buildPendingEntry(destination, pending.keySecret, fingerprint, pending.replayToken);
         const written = await durablyReplaceCredentialStoreJson(primaryPath, next, deps);
         if (!written.ok) {
             return { ok: false, path: primaryPath, target, kind: written.kind, error: written.error };
@@ -744,6 +856,11 @@ export async function repointBootstrapPendingCredential(params, deps) {
  *
  * A failed promotion leaves the pending record intact, so the same replay proof is
  * still available to a later run.
+ *
+ * BAPI-667: the pending record is removed WHOLE, so a self-serve replay token is
+ * discarded here rather than copied forward. Only the stored `key_secret` becomes
+ * `bapi:<repo>.BAPI_API_KEY` — the token has served its only purpose (replaying an
+ * unfinished exchange) and a completed redemption must not leave it on disk.
  */
 export async function promoteBootstrapPendingCredential(params, deps) {
     const primaryPath = getPrimaryCredentialStorePath(deps);
@@ -796,6 +913,173 @@ export async function promoteBootstrapPendingCredential(params, deps) {
         return { ok: true, path: primaryPath, target, action: hadKey ? "updated" : "created" };
     }, (error) => ({ ok: false, path: primaryPath, target, kind: "lock-error", error }));
 }
+/**
+ * Look up the SELF-SERVE pending record for a repo (BAPI-667) — the read that
+ * makes a self-serve retry resume instead of minting a second workspace.
+ *
+ * SECRET-BEARING on `state: "resumable"`: the result carries the stored invite
+ * token AND the stored `key_secret`. Neither may be logged, printed, embedded in
+ * an error, or shown in a dry-run preview; they exist only to be re-POSTed to the
+ * exchange. Every failure variant is deliberately secret-free — it names the
+ * logical target and the store path and nothing else.
+ *
+ * States:
+ *   - `none` — no record, or a record with nothing at stake (no usable secret and
+ *     no replay material). The caller mints normally.
+ *   - `resumable` — a complete self-serve record. The caller MUST reuse it and MUST
+ *     NOT mint.
+ *   - `pending-not-self-serve` — a real pending record with a `key_secret` but no
+ *     replay material: an ordinary `--invite` redemption in flight. Not ours to
+ *     touch.
+ *   - `pending-malformed` — replay material present but the record is incomplete
+ *     (missing `key_secret` or fingerprint). FAIL CLOSED: a half-written record may
+ *     still correspond to a live admin key, so it must never be silently discarded
+ *     or trigger a fresh mint.
+ *   - store failures (`read-error` / `parse-error` / `lock-error`) — propagated so
+ *     an unreadable store never masquerades as "no record, safe to mint".
+ */
+export async function lookupSelfServeBootstrapPendingCredential(params, deps) {
+    const primaryPath = getPrimaryCredentialStorePath(deps);
+    const repoName = (params.repoName ?? "").trim();
+    const target = getBootstrapPendingTarget(repoName);
+    if (repoName.length === 0) {
+        return {
+            ok: false,
+            path: primaryPath,
+            target,
+            kind: "invalid-repo",
+            error: "Cannot look up a bootstrap-invite credential: a non-empty repo name is required.",
+        };
+    }
+    // Read under the SHARED LOCK, even though the store is replaced by an atomic
+    // rename and a lock-free read could never see a half-written file. The lock is
+    // about the read-then-act window, not the read: without it a second install
+    // running concurrently for the same repo could observe the pending record an
+    // instant before the first run promotes it, then replay an exchange for a
+    // redemption that has already completed. Serializing against prepare / repoint /
+    // promote makes the record either wholly present or wholly gone.
+    //
+    // A lock failure is therefore FAIL-CLOSED: it is reported rather than degraded
+    // into `state: "none"`, because "I could not check" must never be answered by
+    // minting a second workspace.
+    return withCredentialStoreLock(deps, async () => {
+        const loaded = await loadStoreForMutation(deps);
+        if (!loaded.ok) {
+            return { ok: false, path: primaryPath, target, kind: loaded.kind, error: loaded.error };
+        }
+        const entry = loaded.base[target];
+        const keySecret = readPendingField(entry, BOOTSTRAP_PENDING_SECRET_FIELD);
+        const fingerprint = readPendingField(entry, BOOTSTRAP_PENDING_FINGERPRINT_FIELD);
+        const replayToken = readPendingField(entry, BOOTSTRAP_PENDING_REPLAY_TOKEN_FIELD);
+        if (replayToken.length === 0) {
+            // No replay material: either nothing is stored, or an ordinary invite
+            // redemption owns this target. Only the latter is a conflict.
+            if (keySecret.length === 0) {
+                return { ok: true, state: "none", path: primaryPath, target };
+            }
+            return {
+                ok: false,
+                path: primaryPath,
+                target,
+                kind: "pending-not-self-serve",
+                error: `A pending bootstrap-invite credential already exists at ${target} in ${primaryPath}. ` +
+                    "It belongs to an invite redemption, not a self-serve signup, so this run will not " +
+                    "touch it. Finish that redemption by re-running install-bridge with the same invite.",
+            };
+        }
+        if (keySecret.length === 0 || fingerprint.length === 0) {
+            return {
+                ok: false,
+                path: primaryPath,
+                target,
+                kind: "pending-malformed",
+                error: `The pending self-serve record at ${target} in ${primaryPath} is incomplete, so it ` +
+                    "cannot be replayed and will not be discarded automatically (it may correspond to a " +
+                    "key that was already created). Ask your Bridge API operator to recover it.",
+            };
+        }
+        return {
+            ok: true,
+            state: "resumable",
+            path: primaryPath,
+            target,
+            keySecret,
+            replayToken,
+            inviteFingerprint: fingerprint,
+        };
+    }, (error) => ({ ok: false, path: primaryPath, target, kind: "lock-error", error }));
+}
+/**
+ * Discard a SELF-SERVE pending record (BAPI-667) — the consent-gated exit from a
+ * signup whose stored invite the server has conclusively rejected (401).
+ *
+ * This is the ONLY destructive operation on a pending record other than promotion,
+ * so it is guarded three ways: the record must exist, its fingerprint must match
+ * what the caller expects, and it must carry self-serve replay material. Those
+ * guards are what keep it from becoming the `--force` that BAPI-606 deliberately
+ * refused to add — an ordinary invite's record can never be reached through here,
+ * and neither can a self-serve record the caller has not actually replayed.
+ *
+ * Returns secret-free path/target metadata only.
+ */
+export async function discardBootstrapPendingCredential(params, deps) {
+    const primaryPath = getPrimaryCredentialStorePath(deps);
+    const repoName = (params.repoName ?? "").trim();
+    const fingerprint = (params.inviteFingerprint ?? "").trim();
+    const target = getBootstrapPendingTarget(repoName);
+    if (repoName.length === 0) {
+        return {
+            ok: false,
+            path: primaryPath,
+            target,
+            kind: "invalid-repo",
+            error: "Cannot discard a bootstrap-invite credential: a non-empty repo name is required.",
+        };
+    }
+    if (fingerprint.length === 0) {
+        return {
+            ok: false,
+            path: primaryPath,
+            target,
+            kind: "invalid-fingerprint",
+            error: "Cannot discard a bootstrap-invite credential: the invite fingerprint was empty.",
+        };
+    }
+    return withCredentialStoreLock(deps, async () => {
+        const loaded = await loadStoreForMutation(deps);
+        if (!loaded.ok) {
+            return { ok: false, path: primaryPath, target, kind: loaded.kind, error: loaded.error };
+        }
+        const base = loaded.base;
+        const pending = readMatchingPending(base, repoName, fingerprint);
+        if (!pending) {
+            return {
+                ok: false,
+                path: primaryPath,
+                target,
+                kind: "pending-missing",
+                error: `No matching pending bootstrap-invite credential for ${target} in ${primaryPath}.`,
+            };
+        }
+        if (!pending.replayToken) {
+            return {
+                ok: false,
+                path: primaryPath,
+                target,
+                kind: "pending-not-self-serve",
+                error: `The pending record at ${target} in ${primaryPath} carries no self-serve replay ` +
+                    "material, so it will not be discarded automatically.",
+            };
+        }
+        const next = { ...base };
+        delete next[target];
+        const written = await durablyReplaceCredentialStoreJson(primaryPath, next, deps);
+        if (!written.ok) {
+            return { ok: false, path: primaryPath, target, kind: written.kind, error: written.error };
+        }
+        return { ok: true, path: primaryPath, target };
+    }, (error) => ({ ok: false, path: primaryPath, target, kind: "lock-error", error }));
+}
 /**
  * Upsert `BAPI_API_KEY` for `bapi:<repoName>` into the user-scoped PRIMARY
  * credential store, atomically (temp file + rename) and secret-safely.

package/build/doctor.js

@@ -20,7 +20,7 @@ import os from "os";
 import path from "path";
 import { createDefaultStartTicketsDeps } from "./start-tickets.js";
 import { VERSION } from "./version.generated.js";
-import { collectInstallStatusChecks, formatInstallStatusReport, resolveInstallDoctorTarget, } from "./install-doctor.js";
+import { collectInstallStatusChecks, formatInstallStatusReport, formatInstallStatusFallbackReport, resolveInstallDoctorTarget, } from "./install-doctor.js";
 import { parseDefaultOnEnvFlag } from "./env-flags.js";
 import { createBridgeApiUrls } from "./bridge-api-urls.js";
 import { probeToolSurface } from "./tool-surface-gating.js";
@@ -28,21 +28,37 @@ import { resolveBapiCredentials } from "./credential-store.js";
 import { DEFAULT_AGENT_NAME, resolveAgentSpec, isAgentName, formatValidAgentNames, } from "./agent-registry.js";
 import { getDoctorPrereqDescriptors, probePrerequisite, } from "./start-tickets-prereqs.js";
 import { resolveProfiles } from "./mcp-profile.js";
+/**
+ * The report/usage title (BAPI-669, U9b). `doctor` diagnoses the whole Bridge
+ * install — install status, prerequisites, launcher cache, and tool surface — so it
+ * is no longer titled as a start-tickets-only tool. Defined once and shared by
+ * {@link getDoctorUsage} and {@link buildDoctorReportHeader} so the two cannot drift.
+ */
+export const DOCTOR_REPORT_TITLE = "bridge doctor — read-only diagnostics";
 /** User-facing usage text for the read-only `doctor` subcommand. */
 export function getDoctorUsage() {
     return [
         "Usage:",
         "  npx -y @bridge_gpt/mcp-server doctor [--agent <name>]",
         "",
-        "Read-only diagnostics for the start-tickets CLI. It only checks your",
-        "environment and prints manual install instructions — it does not install",
-        "anything, modify your system, or start the MCP server.",
+        // BAPI-669 (U9b): `doctor` is the general Bridge diagnostic command, not a
+        // start-tickets-only one — and its report leads with install status, so the
+        // usage text describes it in that order too.
+        `${DOCTOR_REPORT_TITLE}. It only checks your environment and prints manual`,
+        "install instructions — it does not install anything, modify your system, or",
+        "start the MCP server.",
         "",
         "Flags:",
         "  --agent claude|cursor-agent   Agent to include in the prerequisite check (default: claude)",
         "  -h, --help                    Show this help",
         "",
-        "Checks (for the current OS): the start-tickets preflight prerequisites plus",
+        "The report opens with an advisory 'Install status' section (easy-install done",
+        "criteria): repo identity, credential resolution, server connectivity,",
+        "bootstrap-field completeness, integration credentials, and repository-indexing",
+        "state. It performs read-only GETs only and never affects the exit code.",
+        "",
+        "After that come the start-tickets prerequisite checks (for the current OS):",
+        "the start-tickets preflight prerequisites plus",
         "uv, the selected agent's command, Bridge API credential resolution, and",
         "worktree MCP registration reachability. Credential resolution reports the",
         "source it would use (env vs. store target bapi:<repo>); it never reads or",
@@ -50,11 +66,6 @@ export function getDoctorUsage() {
         "migrate a credential, use /install-bridge or the `credentials` subcommand —",
         "doctor stays strictly read-only.",
         "",
-        "The report also includes an advisory 'Install status' section (easy-install",
-        "done criteria): repo identity, credential resolution, server connectivity,",
-        "bootstrap-field completeness, and repository-indexing state. It performs",
-        "read-only GETs only and never affects the exit code.",
-        "",
         "It also includes an advisory 'MCP tool surface' section (BAPI-641): what",
         "dynamic capability gating would advertise for this repo. It performs at most",
         "one read-only GET to /jira/mcp/tool-surface (none under the kill switch) and",
@@ -155,20 +166,31 @@ export async function collectDoctorResults(deps, agentName) {
     return { ok: true, results };
 }
 /**
- * Render the doctor report: platform + selected agent header, one found/missing
- * line per prerequisite, the exact manual install hint for each missing one
- * (framed as manual instructions only), and the selected agent's auth note
- * (especially the `cursor-agent login` reminder). Pure formatting — no probing.
+ * The BROAD report header: title plus the run's platform / agent / profile
+ * metadata (BAPI-669, U9b). Split out from the prerequisite body so `runDoctorCli`
+ * has a clear insertion point for the Install-status section between the two — the
+ * ordering change is the whole point, and it must not require rewriting the
+ * prerequisite formatting below.
  */
-export function formatDoctorReport(platform, agent, collection) {
+export function buildDoctorReportHeader(platform, agent) {
     const activeGroups = Array.from(resolveProfiles(process.env.BRIDGE_MCP_PROFILE)).join(", ");
-    const lines = [
-        "start-tickets doctor (read-only diagnostics)",
+    return [
+        DOCTOR_REPORT_TITLE,
         `Platform: ${platform}`,
         `Selected agent: ${agent.name} (command: ${agent.command})`,
         `Active MCP Groups: \`${activeGroups}\``,
         "",
     ];
+}
+/**
+ * The start-tickets PREREQUISITE section: one found/missing line per prerequisite,
+ * the exact manual install hint for each missing one (framed as manual instructions
+ * only), and the selected agent's auth note (especially the `cursor-agent login`
+ * reminder). Pure formatting — no probing. Byte-identical to what
+ * {@link formatDoctorReport} has always rendered below its header.
+ */
+export function formatDoctorPrereqSection(platform, collection) {
+    const lines = [];
     if (!collection.ok) {
         lines.push(`Platform '${platform}' is unsupported. start-tickets supports darwin, win32, and linux.`);
         return lines.join("\n");
@@ -193,6 +215,17 @@ export function formatDoctorReport(platform, agent, collection) {
     lines.push("For conductor ledger/native-module diagnostics, run: conductor doctor");
     return lines.join("\n");
 }
+/**
+ * Header + prerequisite section, composed. Retained as the single-call rendering
+ * used by direct callers and tests; `runDoctorCli` composes the two halves itself so
+ * it can slot Install status between them (BAPI-669, U9c).
+ */
+export function formatDoctorReport(platform, agent, collection) {
+    return [
+        ...buildDoctorReportHeader(platform, agent),
+        formatDoctorPrereqSection(platform, collection),
+    ].join("\n");
+}
 // ---------------------------------------------------------------------------
 // Launcher-cache diagnostics (BAPI-451 W3, E-4/E-9) — strictly read-only.
 //
@@ -504,25 +537,20 @@ export async function runDoctorCli(argv, overrides = {}) {
     const deps = overrides.deps ?? createDefaultStartTicketsDeps();
     const agent = resolveAgentSpec(parsed.options.agentName) ?? resolveAgentSpec(DEFAULT_AGENT_NAME);
     const collection = await collectDoctorResults(deps, parsed.options.agentName);
-    log(formatDoctorReport(deps.platform, agent, collection));
-    // Strictly read-only launcher-cache diagnostics (BAPI-451). Best-effort: a probe
-    // failure never changes the doctor exit code (cold-start readiness is advisory,
-    // not a hard prerequisite). The exit code remains driven by required prereqs.
-    try {
-        const launcherDeps = {
-            cwd: overrides.launcherProbe?.cwd ?? deps.cwd,
-            readFile: overrides.launcherProbe?.readFile ?? ((p) => readFile(p, "utf-8")),
-            probeNpxNoInstall: overrides.launcherProbe?.probeNpxNoInstall ?? probeNpxNoInstallDefault,
-        };
-        const launcherInspections = await inspectLauncherCache(launcherDeps);
-        log(formatLauncherCacheReport(launcherInspections));
-    }
-    catch {
-        /* launcher-cache diagnostics are advisory; never block the doctor report */
-    }
+    // ---- Section order (BAPI-669, U9c) ----
+    // Broad header → Install status → start-tickets prerequisites → launcher cache →
+    // MCP tool surface. Install status renders FIRST and UNCONDITIONALLY: it answers
+    // "is this project actually set up?", which is what someone running `doctor` after
+    // an install is asking. There is deliberately no "invocation context" flag to gate
+    // the ordering on — the report has a single caller and carries no context, so
+    // always-first is both simpler and equivalent. The `installStatus: false` override
+    // remains a dependency-injection-only seam for hermetic tests; a normal CLI
+    // invocation never takes it.
+    log(buildDoctorReportHeader(deps.platform, agent).join("\n"));
     // Advisory install-status section (easy-install done criteria). Read-only GETs
     // only; any failure degrades to WARN/SKIP lines inside the section, and any
-    // unexpected throw is swallowed — the exit code is never affected.
+    // unexpected throw renders the sanitized fallback rather than dropping the
+    // report's first section — the exit code is never affected either way.
     if (overrides.installStatus !== false) {
         try {
             // Reuse fs deps injected on `deps` (doctor's credential probes place them
@@ -543,9 +571,26 @@ export async function runDoctorCli(argv, overrides = {}) {
             log(formatInstallStatusReport(checks));
         }
         catch {
-            /* install-status diagnostics are advisory; never block the doctor report */
+            // Advisory, but never silently absent: the first section always renders.
+            log(formatInstallStatusFallbackReport());
         }
     }
+    log(formatDoctorPrereqSection(deps.platform, collection));
+    // Strictly read-only launcher-cache diagnostics (BAPI-451). Best-effort: a probe
+    // failure never changes the doctor exit code (cold-start readiness is advisory,
+    // not a hard prerequisite). The exit code remains driven by required prereqs.
+    try {
+        const launcherDeps = {
+            cwd: overrides.launcherProbe?.cwd ?? deps.cwd,
+            readFile: overrides.launcherProbe?.readFile ?? ((p) => readFile(p, "utf-8")),
+            probeNpxNoInstall: overrides.launcherProbe?.probeNpxNoInstall ?? probeNpxNoInstallDefault,
+        };
+        const launcherInspections = await inspectLauncherCache(launcherDeps);
+        log(formatLauncherCacheReport(launcherInspections));
+    }
+    catch {
+        /* launcher-cache diagnostics are advisory; never block the doctor report */
+    }
     // Advisory MCP tool-surface capability section (BAPI-641). Strictly read-only:
     // one 500 ms GET (or none, under the kill switch). Any timeout, malformed
     // response, or unexpected throw degrades to a "fail-open to full surface" line