@bridge_gpt/mcp-server 0.2.31 → 0.2.32

package/README.md

@@ -31,18 +31,29 @@ npx -y @bridge_gpt/mcp-server@latest install-bridge
 ```
 
 Run bare like that in a terminal and it starts by asking
-**`Do you have a Bridge API key or invite? [Y/n]`**:
-
-- **Yes** (or just press Enter) — the existing-key flow. It asks for your **API key**
-  (generate one on the Bridge API web UI **Security** page) and a **repo name**
-  matching your server-side registration; everything else is derived. A
-  `bapi_inv_…` credential entered here instead of a full API key is automatically
-  detected and redeemed as a **bootstrap invite** — it creates a brand-new project
-  and mints your admin API key rather than looking up an existing repository.
-- **No** — the **self-serve** flow. It asks for an **email**, then a name for your new
-  Bridge project, and creates the workspace and your own admin API key for you. No
-  account, no key, and no invite needed beforehand. Same as passing
-  `--email you@example.com` (see below).
+**`How would you like to connect to Bridge API?`** with three numbered choices:
+
+```
+1. I have a Bridge API key
+2. I have an invite token
+3. I'm new — set me up with just my email
+```
+
+- **1** — the existing-key flow. It asks for your **API key** (generate one on the
+  Bridge API web UI **Security** page) and a **repo name** matching your server-side
+  registration; everything else is derived. A `bapi_inv_…` credential entered here
+  instead of a full API key is automatically detected and redeemed as a **bootstrap
+  invite** — it creates a brand-new project and mints your admin API key rather than
+  looking up an existing repository.
+- **2** — the **bootstrap-invite** flow. It asks for the invite token you were given,
+  with echo suppressed. Same as passing `--invite` (see below).
+- **3** — the **self-serve** flow, and the right answer if you have nothing yet. It
+  asks for an **email**, then a name for your new Bridge project, and creates the
+  workspace and your own admin API key for you. No account, no key, and no invite
+  needed beforehand. Same as passing `--email you@example.com` (see below).
+
+There is **no default**: pressing Enter selects nothing. A blank or invalid answer
+re-prompts once with a hint, then exits with guidance naming all three routes.
 
 That question is asked only for a *bare interactive* run. Passing any flag, setting
 `BAPI_API_KEY`, or running without an interactive terminal skips it and keeps the
@@ -51,11 +62,12 @@ existing deterministic behavior.
 From there `install-bridge` scaffolds the project, writes your editor's MCP config
 with real values, verifies connectivity, persists your API key to the user-scoped
 credential store, and opens a fresh agent session that runs `/install-bridge` to
-derive and apply the remaining config, presents a **capability report** (what you can
-use now and what you'll unlock), and closes by asking whether to index the
-repository. It does **not** automatically run `/learn-repository` or index without
-your consent — both remain available as separate steps. Add `--dry-run` to preview
-every step without writing, pinging, or spawning anything.
+derive and apply the remaining config, presents a concise **capability report**
+("What Bridge can help with"), and recommends `/learn-repository` as your next step.
+It does **not** run `/learn-repository` itself — that stays your next explicit
+invocation. There is **no indexing question**: indexing starts automatically
+server-side once the repository reaches full parse readiness. Add `--dry-run` to
+preview every step without writing, pinging, or spawning anything.
 
 **Were you sent a bootstrap invite?** Then you don't need an API key or the web UI
 at all — run the command your operator gave you:
@@ -148,12 +160,30 @@ shown**.
 The email may instead come from the `BAPI_SIGNUP_EMAIL` environment variable or a
 **visible** interactive prompt (email is not a secret, so it is echoed as you type —
 unlike the API key and the invite token, which use a hidden prompt). That prompt is
-what answering **no** to `Do you have a Bridge API key or invite? [Y/n]` on a bare run reaches,
-so `install-bridge --email you@example.com` and a bare `install-bridge` + "no" land
-in the same place. The email is still **never written to a log line**. No email
+what **option 3** of the bare-run chooser reaches, so
+`install-bridge --email you@example.com` and a bare `install-bridge` + `3` land in
+the same place. The email is still **never written to a log line**. No email
 verification is performed and no message is sent to the address — it only labels your
 new workspace. `--email` is mutually exclusive with `--api-key` and `--invite`.
 
+##### Self-serve retries resume automatically
+
+A self-serve run that fails part-way through — a network blip on the exchange, a
+failed connectivity check, an interrupted credential write — saves its signup state
+under `bootstrap-pending:<repo>` in the credential store (mode `0600`, fsync'd, the
+same record that already holds your `key_secret`).
+
+**Just re-run the self-serve flow.** It detects that saved attempt, prints
+`resuming your previous signup attempt for <repo>`, and re-drives the *same*
+exchange — it does **not** sign up again, so a retry never creates a second
+workspace. This is why the self-serve record stores the minted invite token: you
+were never shown that token, so nothing else could re-present it.
+
+Do **not** copy, display, or hand-remove that record. If the saved invite has
+genuinely expired, the CLI says so and **asks for confirmation** before discarding
+it and starting fresh — it never discards it silently, because a record whose
+exchange already succeeded is the only trace of a live admin key.
+
 Because this flow *creates* the project, it asks you to **name a new project**
 (`Name your new Bridge project [<inferred>]: `) rather than to match an existing
 server-side registration. The name must be globally unique; if it's taken, you're
@@ -689,12 +719,14 @@ Per-OS prerequisites: macOS `wt`, `git`, `osascript`; Windows `git-wt`, Git for
 
 ### `doctor`
 
-The package also ships a strictly **read-only** `doctor` subcommand that diagnoses the `start-tickets` prerequisites for the current OS without changing anything:
+The package also ships a strictly **read-only** `doctor` subcommand — titled **`bridge doctor — read-only diagnostics`** — that diagnoses your whole Bridge install without changing anything:
 
 ```
 npx -y @bridge_gpt/mcp-server doctor [--agent <name>]
 ```
 
+The report always leads with the advisory **`Install status`** section (repo identity, credential resolution, server connectivity, bootstrap-field completeness, integration credentials, indexing state) **before** the `start-tickets` prerequisite diagnostics; the launcher-cache and MCP tool-surface sections follow. `Install status` is read-only GETs only and never affects the exit code.
+
 It is **read-only**: it never installs anything, modifies your system, adds an npm `postinstall`, spawns a terminal, or starts the MCP server, and there is no `--fix`. For each prerequisite it prints found/missing and, when missing, the exact per-OS install command **as a manual instruction you run yourself**. The checked set is the `start-tickets` preflight prerequisites **plus `uv`** **plus the selected agent's command** (`claude` by default, or `cursor-agent` with `--agent cursor-agent`). The Worktrunk binary is probed via the resolved name (honoring `BAPI_WORKTRUNK_BIN`), not a hard-coded one. **Exit code:** `0` when all required prerequisites are present, non-zero when any is missing or the platform is unsupported. A failing `start-tickets` preflight now hints you to run `doctor` for an actionable diagnostics report.
 
 ### `setup-epic`

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.