@bridge_gpt/mcp-server 0.2.66 → 0.2.68

package/build/conductor/repair-contract.js

@@ -1,8 +1,8 @@
 /**
- * The shared contract for the seven operator repair verbs: BAPI-1154's
+ * The shared contract for the eight operator repair verbs: BAPI-1154's
  * `scope-reparse`, `dispatch-remediation`, and `merge-child`, BAPI-1176's
- * `scope-catch-up`, `patch-policy`, and `resume-run`, and BAPI-1326's
- * ticket-addressed `resume-ci`.
+ * `scope-catch-up`, `patch-policy`, and `resume-run`, BAPI-1326's
+ * ticket-addressed `resume-ci`, and BAPI-1388's ticket-addressed `rerun-ci`.
  *
  * CLI-only, exactly like the BAPI-872 recovery verbs: none of these names is ever
  * registered as an MCP tool (`index-static.test.ts` pins that). This module is the
@@ -22,6 +22,7 @@ export const VERB_SCOPE_CATCH_UP = "scope-catch-up";
 export const VERB_PATCH_POLICY = "patch-policy";
 export const VERB_RESUME_RUN = "resume-run";
 export const VERB_RESUME_CI = "resume-ci";
+export const VERB_RERUN_CI = "rerun-ci";
 /** Every repair verb, in the order an operator meets them. */
 export const OPERATOR_REPAIR_VERBS = [
     VERB_SCOPE_REPARSE,
@@ -31,6 +32,7 @@ export const OPERATOR_REPAIR_VERBS = [
     VERB_PATCH_POLICY,
     VERB_RESUME_RUN,
     VERB_RESUME_CI,
+    VERB_RERUN_CI,
 ];
 /**
  * The ONE cap on driver context, in UTF-8 BYTES — the same number the server
@@ -156,3 +158,52 @@ export const CI_RESUME_RECEIPT_RETENTION = "latest_only";
 export function isCiResumeRefusalCode(code) {
     return (typeof code === "string" && CI_RESUME_REFUSAL_CODES.includes(code));
 }
+// ---------------------------------------------------------------------------
+// BAPI-1388 — `rerun-ci`
+// ---------------------------------------------------------------------------
+/**
+ * The closed `rerun-ci` refusal subset — mirrors `RERUN_CI_REFUSAL_CODES` in
+ * `operator_repair_contract.py`. It mints no new code: every member already
+ * exists in {@link OPERATOR_REPAIR_REFUSAL_CODES}.
+ */
+export const RERUN_CI_REFUSAL_CODES = [
+    "TICKET_NOT_IN_RUN",
+    "GUIDED_REPAIR_DISABLED",
+    "REPAIR_SUBJECT_STALE",
+    "RUN_NOT_DISPATCHABLE",
+    "TICKET_NOT_REMEDIABLE",
+    "REMEDIATION_JOB_IN_FLIGHT",
+    "REMEDIATION_LANE_BUSY",
+    "REMEDIATION_HELD",
+    "REMEDIATION_NO_PULL_REQUEST",
+    "ROW_VERSION_CONFLICT",
+    "DISPATCH_ENQUEUE_FAILED",
+];
+/** True when `code` is one of the closed `rerun-ci` refusal codes. */
+export function isRerunCiRefusalCode(code) {
+    return (typeof code === "string" && RERUN_CI_REFUSAL_CODES.includes(code));
+}
+/**
+ * The bounded reason a `rerun-ci` `ROW_VERSION_CONFLICT` carries when releasing a
+ * reservation lost its guarded write. Whether the unenqueued workflow runs are
+ * still recorded is UNCONFIRMED; the CLI exits 3.
+ */
+export const RERUN_CI_UNCONFIRMED_REASON = "rerun_ci_unconfirmed";
+/**
+ * The closed per-check outcome vocabulary. None of them says a check is green: a
+ * provider re-run is an action, not a verdict.
+ */
+export const RERUN_CI_CHECK_STATUSES = [
+    "enqueued",
+    "deduplicated",
+    "deferred",
+    "not_re_runnable",
+];
+/** Why one failed check is not re-run: a closed token. */
+export const RERUN_CI_NOT_RUNNABLE_REASONS = [
+    "not_github_actions",
+    "no_workflow_run_id",
+    "claude_review_excluded",
+];
+/** The closed overall outcomes of an applied `rerun-ci`. */
+export const RERUN_CI_OUTCOMES = ["enqueued", "partial", "nothing_to_enqueue"];

package/build/conductor/repository-workflow-remedy.js

@@ -0,0 +1,125 @@
+/** The two fixed workflow files unattended auto-merge reads. Named once here. */
+export const REVIEW_WORKFLOW_PATH = ".github/workflows/claude-review.yml";
+export const CI_WORKFLOW_PATH = ".github/workflows/epic-implementer-ci.yml";
+/** The migration guard's stable job id and its exact checker invocation. */
+export const MIGRATION_GUARD_JOB_ID = "migration-guard";
+export const MIGRATION_GUARD_CHECKER_PATH = "scripts/check_alembic_migration_graph.py";
+export const MIGRATION_GUARD_INVOCATION = `python ${MIGRATION_GUARD_CHECKER_PATH}`;
+const RETRY = "Run the readiness check again, or pass --attended. " +
+    "If it keeps failing, contact Bridge operations.";
+const TEMPLATES = {
+    review_workflow_file: `${REVIEW_WORKFLOW_PATH} is missing from the default branch. Add it, or pass --attended.`,
+    review_run_id_marker: `${REVIEW_WORKFLOW_PATH} does not emit the run-id: marker in its verdict comment. ` +
+        "Add it, or pass --attended.",
+    review_reviewed_sha_marker: `${REVIEW_WORKFLOW_PATH} does not emit the Reviewed-SHA: marker in its verdict comment. ` +
+        "Add it, or pass --attended.",
+    review_workflow_unverifiable: `Bridge could not read ${REVIEW_WORKFLOW_PATH} on the default branch. ${RETRY}`,
+    ci_workflow_file: `${CI_WORKFLOW_PATH} is missing from the default branch. Add it, or pass --attended.`,
+    migration_guard_job: `${CI_WORKFLOW_PATH} has no job with id ${MIGRATION_GUARD_JOB_ID} running ${MIGRATION_GUARD_INVOCATION}. ` +
+        "It is required because this repository has alembic.ini on its default branch, " +
+        `and an equivalent checker at ${MIGRATION_GUARD_CHECKER_PATH} is required too. ` +
+        "Add that job, or pass --attended.",
+    migration_chain_unverifiable: "Bridge could not confirm whether this repository has alembic.ini on its default branch, " +
+        `so it could not decide if the ${MIGRATION_GUARD_JOB_ID} job is required. ${RETRY}`,
+    ci_workflow_unverifiable: `Bridge could not read ${CI_WORKFLOW_PATH} on the default branch. ${RETRY}`,
+    // An older server never reported whether the guard is conditional, so its
+    // guard has always been required. This states that requirement and NOTHING
+    // about alembic.ini: an older server observed no such file.
+    migration_guard_job_legacy: `${CI_WORKFLOW_PATH} has no job with id ${MIGRATION_GUARD_JOB_ID} running ${MIGRATION_GUARD_INVOCATION}. ` +
+        "Add that job, or pass --attended.",
+};
+/** Shown when the report is missing, incomplete, or not in a shape we can name. */
+const UNVERIFIABLE_FALLBACK = "Bridge could not verify the review and CI workflows on the default branch. " + RETRY;
+function classifyReview(w) {
+    if (w === null || w === undefined || typeof w !== "object")
+        return "malformed";
+    if (w.probe_succeeded !== true)
+        return ["review_workflow_unverifiable"];
+    if (w.workflow_present === false)
+        return ["review_workflow_file"];
+    if (w.workflow_present !== true ||
+        typeof w.emits_run_id !== "boolean" ||
+        typeof w.emits_reviewed_sha !== "boolean") {
+        return "malformed";
+    }
+    const missing = [];
+    if (!w.emits_run_id)
+        missing.push("review_run_id_marker");
+    if (!w.emits_reviewed_sha)
+        missing.push("review_reviewed_sha_marker");
+    return missing;
+}
+function classifyCi(c) {
+    if (c === null || c === undefined || typeof c !== "object")
+        return "malformed";
+    if (c.probe_succeeded !== true)
+        return ["ci_workflow_unverifiable"];
+    if (c.workflow_present === false)
+        return ["ci_workflow_file"];
+    if (c.workflow_present !== true || typeof c.migration_guard_present !== "boolean") {
+        return "malformed";
+    }
+    if (c.migration_guard_present)
+        return [];
+    const required = c.migration_guard_required;
+    const chainProbed = c.migration_chain_probe_succeeded;
+    // Older server: neither field reported. The guard was always required there,
+    // and the absent fields must never read as "not required".
+    if (required === undefined && chainProbed === undefined) {
+        return ["migration_guard_job_legacy"];
+    }
+    if (typeof required !== "boolean" || typeof chainProbed !== "boolean")
+        return "malformed";
+    if (chainProbed && !required)
+        return []; // confirmed guard-free
+    if (chainProbed && required)
+        return ["migration_guard_job"];
+    return ["migration_chain_unverifiable"];
+}
+/**
+ * Name the first failing workflow section of a parsed readiness report, its
+ * missing facts in stable order, and one fixed-template message.
+ *
+ * `section: null` with the fallback text means the report is missing or malformed
+ * — "could not verify", never "fine". An empty `missing` with `section: null`
+ * cannot occur: a report with nothing failing yields the fallback only when it is
+ * unreadable, and otherwise the empty result below.
+ */
+export function describeRepositoryWorkflowRemedy(readiness) {
+    const review = classifyReview(readiness?.review_workflow);
+    if (review === "malformed") {
+        return { section: null, missing: [], text: UNVERIFIABLE_FALLBACK };
+    }
+    if (review.length > 0)
+        return build("review_workflow", review);
+    const ci = classifyCi(readiness?.conductor_ci_workflow);
+    if (ci === "malformed") {
+        return { section: null, missing: [], text: UNVERIFIABLE_FALLBACK };
+    }
+    if (ci.length > 0)
+        return build("conductor_ci_workflow", ci);
+    return { section: null, missing: [], text: "" };
+}
+function build(section, missing) {
+    return { section, missing, text: missing.map((token) => TEMPLATES[token]).join(" ") };
+}
+/**
+ * The remedy sentence for a repository whose workflows are not confirmed. Never
+ * empty: a report with nothing to name (the server said unconfirmed but this
+ * client can name no item) gets the unverifiable fallback rather than silence.
+ */
+export function repositoryWorkflowRemedy(readiness) {
+    const described = describeRepositoryWorkflowRemedy(readiness);
+    return described.text === "" ? UNVERIFIABLE_FALLBACK : described.text;
+}
+/**
+ * The remedy for the CI workflow section alone — what the readiness CI row shows
+ * when the migration guard is absent. Same templates, same words as
+ * {@link repositoryWorkflowRemedy}, so the row and the refusals cannot drift.
+ */
+export function ciWorkflowRemedy(c) {
+    const tokens = classifyCi(c);
+    if (tokens === "malformed" || tokens.length === 0)
+        return UNVERIFIABLE_FALLBACK;
+    return tokens.map((token) => TEMPLATES[token]).join(" ");
+}

package/build/conductor/tools.js

@@ -82,9 +82,9 @@ function registerExplainRunTool(registerTool) {
         // is the field list: a caller cannot discover the answer shape from a
         // tool that only says "explain a run", and the whole point of the tool is
         // that the answer is in one place.
-        description: "Explain why a Conductor epic run, or one ticket in it, is stuck. One snapshot: " +
+        description: "Explain why an Epic Implementer run, or one ticket in it, is stuck. One snapshot: " +
             "current gate, latest observation and age, outstanding jobs with queue position, " +
-            "lease owner/expiry, blocker reasons, expected-vs-observed head SHA, committed and " +
+            "lease owner/expiry, blocker reasons, expected/observed head SHA, committed and " +
             "pending disposition, usage ceiling. Pass ticket_key to narrow. Read-only; 404 " +
             "returns status 'unknown'.",
         inputSchema: {

package/build/conductor-bundle-artifacts.js

@@ -27,6 +27,14 @@ import { validateTicketKey } from "./ticket-key-utils.js";
 const EPIC_SLUG_RE = /^[A-Za-z][A-Za-z0-9_-]*$/;
 /** Placeholder node identity written by `decompose-epic.md` before tickets exist. */
 const PLACEHOLDER_RE = /TBD-\d+/;
+/**
+ * A whole plan-node key that is still an authoring placeholder (`TBD-<digits>`),
+ * case-insensitive. Anchored on purpose and stateless (no `g` or `y` flag, so
+ * `.test()` carries no `lastIndex`). This is NOT {@link PLACEHOLDER_RE}: that one
+ * is an unanchored scan of a whole serialized plan, and
+ * {@link findResidualPlaceholder} keeps using it unchanged.
+ */
+export const PLACEHOLDER_NODE_KEY_RE = /^TBD-\d+$/i;
 /**
  * The conductor's hard spec bound, mirroring `_SPEC_REVIEW_TICKET_SPEC_MAX_CHARS`
  * (64,000) in `api/library/epic_implementer/reconciler.py`. Since PR #848 the

package/build/connect-bitbucket-api.js

@@ -87,6 +87,25 @@ function asString(value) {
 function asNullableString(value) {
     return typeof value === "string" && value.length > 0 ? value : null;
 }
+/** Same unambiguous alphabet the server draws its codes and check values from. */
+const APPROVAL_CHECK_RE = /^[ABCDEFGHJKLMNPQRSTUVWXYZ23456789]{4,8}$/;
+/**
+ * Decide the mint's mode defensively (BAPI-1401). Approval mode needs BOTH an explicit
+ * `approval_mode: "approve"` and a well-formed check value; any other combination is
+ * code mode, so a partial or unexpected response can never strand the user without the
+ * code they would need.
+ */
+function parseApprovalMode(body) {
+    const check = typeof body.approval_check === "string" ? body.approval_check.trim() : "";
+    if (body.approval_mode === "approve" && APPROVAL_CHECK_RE.test(check)) {
+        return { approvalMode: "approve", approvalCheck: check };
+    }
+    return { approvalMode: "code", approvalCheck: null };
+}
+/** Parse the optional, additive `reason` on a status body. Unknown → null. */
+function parseStatusReason(value) {
+    return value === "declined" ? "declined" : null;
+}
 // ---------------------------------------------------------------------------
 // Retry-After
 // ---------------------------------------------------------------------------
@@ -121,13 +140,23 @@ export function parseRetryAfterMs(header, remainingMs, nowMs) {
 // ---------------------------------------------------------------------------
 // Endpoints
 // ---------------------------------------------------------------------------
-/** Mint a CLI-origin connection code and its Forge install-page URL. */
-export async function mintBitbucketConnection(deps, repoName) {
-    const res = await postJson(deps, "/setup/bitbucket/cli/connection-code", {
-        repo_name: repoName,
-    });
+/**
+ * Mint a CLI-origin connection code and its Forge install-page URL.
+ *
+ * BAPI-1401: when `workspaceSlug` is given, it is sent as the request's workspace claim,
+ * asking the server for an approval-mode connection request. Without it the request body
+ * is exactly the legacy shape. Either way the response decides the mode.
+ */
+export async function mintBitbucketConnection(deps, repoName, workspaceSlug) {
+    const payload = { repo_name: repoName };
+    if (workspaceSlug)
+        payload.workspace_slug = workspaceSlug;
+    const res = await postJson(deps, "/setup/bitbucket/cli/connection-code", payload);
     if (!res.ok)
         return res;
+    if (res.value.status === 429) {
+        return { ok: false, kind: "too-many-pending" };
+    }
     if (res.value.status !== 200) {
         return { ok: false, kind: classifyStatus(res.value.status) };
     }
@@ -143,7 +172,11 @@ export async function mintBitbucketConnection(deps, repoName) {
     // uses. Required-field strictness above is untouched — an optional field must not
     // become a new way for a server change to fail a mint.
     const redeemUrlTemplate = asNullableString(body.redeem_url_template);
-    return { ok: true, value: { state, installUrl, ttlSeconds, redeemUrlTemplate } };
+    const { approvalMode, approvalCheck } = parseApprovalMode(body);
+    return {
+        ok: true,
+        value: { state, installUrl, ttlSeconds, redeemUrlTemplate, approvalMode, approvalCheck },
+    };
 }
 /** Strictly parse candidates. A candidate missing a usable identity fails the whole list. */
 function parseCandidates(value) {
@@ -198,6 +231,7 @@ export async function fetchBitbucketConnectionStatus(deps, repoName, state, nowM
             status: status,
             candidates,
             repoDisplayName: asNullableString(body.repo_display_name),
+            reason: parseStatusReason(body.reason),
             // A single read has no deadline of its own to clamp against; the poller applies
             // its own bound. POLL_DEADLINE_MS is the widest a caller could honor.
             retryAfterMs: parseRetryAfterMs(res.value.retryAfter, POLL_DEADLINE_MS, nowMs),
@@ -348,6 +382,7 @@ export async function pollBitbucketConnection(deps, poll, repoName, state) {
                         status: typed,
                         candidates,
                         repoDisplayName: asNullableString(body.repo_display_name),
+                        reason: parseStatusReason(body.reason),
                         retryAfterMs: null,
                     },
                 };

package/build/connect-bitbucket.js

@@ -5,20 +5,28 @@
  * The whole point of this command is that it needs no Bridge web session: a user who has
  * a Bridge API key can connect Bitbucket without ever opening the setup UI. The flow is
  *
- *   mint → browser (install the Forge app on Bitbucket, paste the printed code into its
- *   admin panel) → poll → pick a repository → confirm
+ *   mint → browser (install the Forge app on Bitbucket, then approve the request on the
+ *   app's workspace settings page) → poll → pick a repository → confirm
  *
  * and the browser half authenticates to *Bitbucket*, not to Bridge. Bridge never asks
  * for, accepts, echoes, or transports a Bitbucket credential. The only thing crossing
  * between the browser and this process is a Bridge-issued state nonce, held in memory.
  *
+ * BAPI-1401 — two modes. **Approval mode** (the default when a Bitbucket workspace is
+ * known from `--workspace` or this project's git remote, and the server supports it):
+ * the mint is a connection request listed on that workspace's Forge settings page, and a
+ * workspace admin clicks Approve on the card showing the check value printed here. No
+ * code is printed. **Code mode** (`--use-code`, no workspace, or an older server): the
+ * legacy flow — the printed code is pasted into the same settings page.
+ *
  * Two properties are load-bearing and easy to erode:
  *
  * 1. **The nonce and install URL are never printed to output the CLI narrates around.**
  *    The URL carries the state as a query parameter, so putting it in a log line or an
  *    error message would paste a live credential-equivalent into the user's scrollback.
- *    The printed code shown to the user for pasting into Bitbucket's own admin panel is
- *    the one deliberate exception — see `runBitbucketConnectionFlow` below.
+ *    In code mode the printed code shown to the user for pasting into Bitbucket's own
+ *    settings page is the one deliberate exception — see `runBitbucketConnectionFlow`
+ *    below. In approval mode it is never printed.
  * 2. **Nothing binds without an explicit human choice.** Even a single-repository
  *    installation is confirmed by hand — the server stages candidates and this command
  *    asks. There is deliberately no `--yes`.
@@ -35,25 +43,30 @@ import { DEFAULT_BAPI_BASE_URL } from "./install-bridge.js";
 import { validateRepoName } from "./bridge-config.js";
 import { resolveStartTicketsRepoName } from "./start-tickets-repo.js";
 import { resolveBapiCredentials, } from "./credential-store.js";
+import { defaultGitRemoteRunner, resolveBitbucketWorkspace, } from "./bitbucket-workspace-remote.js";
 import { POLL_DEADLINE_MS, confirmBitbucketConnection, mintBitbucketConnection, pollBitbucketConnection, } from "./connect-bitbucket-api.js";
-const USAGE = `Usage: connect-bitbucket [--repo <repo_name>] [--workspace <slug>]
+const USAGE = `Usage: connect-bitbucket [--repo <repo_name>] [--workspace <slug>] [--use-code]
 
 Connect a Bitbucket repository to a Bridge project from your terminal.
 
-Opens the Bitbucket Forge app's install page in your browser and prints a
-connection code. Install the app, then redeem the code in Bitbucket under
-Workspace settings → Apps → "Connect Bitbucket to Bridge API" — that is how you
-authenticate to Bitbucket; Bridge never asks for a Bitbucket token or app
-password. Once the app reports the code back, this command asks which single
-repository to connect.
+Opens the Bitbucket Forge app's install page in your browser. Install the app,
+then in Bitbucket open Workspace settings → Forge Apps → "Connect Bitbucket to
+Bridge API" and click Approve on the request this command started (it prints a
+short check value so you can tell it apart). That is how you authenticate to
+Bitbucket; Bridge never asks for a Bitbucket token or app password. Once the
+app reports back, this command asks which single repository to connect.
+
+Without a known workspace, or with --use-code, it prints a connection code to
+paste on that same page instead.
 
 Options:
   --repo <repo_name>   Bridge project to connect (inferred from this directory
                        when omitted; you will be asked to confirm).
-  --workspace <slug>   Bitbucket workspace slug. Prints a direct link to that
-                       workspace's settings page for the app. The connection
-                       code still has to be pasted there by hand — the link only
-                       saves you finding the page.
+  --workspace <slug>   Bitbucket workspace slug. Inferred from this project's
+                       origin git remote when omitted. Lists the request on that
+                       workspace's settings page and prints a direct link to it.
+  --use-code           Print a connection code to paste instead of approving a
+                       request.
   --help               Show this message.`;
 /**
  * Bitbucket workspace slugs are NOT Bridge project names, so they do not go through
@@ -94,7 +107,7 @@ export function validateBitbucketWorkspace(raw) {
  * resolve only through the shared credential-store seam).
  */
 export function parseConnectBitbucketArgs(argv) {
-    const out = { help: false };
+    const out = { useCode: false, help: false };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === "--help" || arg === "-h") {
@@ -137,6 +150,10 @@ export function parseConnectBitbucketArgs(argv) {
             out.workspace = validated.value;
             continue;
         }
+        if (arg === "--use-code") {
+            out.useCode = true;
+            continue;
+        }
         if (arg === "--yes" || arg === "-y") {
             return {
                 ok: false,
@@ -255,6 +272,7 @@ export function createDefaultConnectBitbucketDeps() {
         openBrowser: (url) => defaultOpenBrowser(process.platform, url),
         stdout: (message) => process.stdout.write(`${message}\n`),
         stderr: (message) => process.stderr.write(`${message}\n`),
+        runGit: defaultGitRemoteRunner,
     };
 }
 /**
@@ -313,7 +331,7 @@ export async function openBitbucketInstallPage(deps, installUrl) {
 // ---------------------------------------------------------------------------
 const STEPS = [
     "Connect Bitbucket",
-    "Complete Bitbucket Forge install in browser",
+    "Install the Bitbucket Forge app and connect it in Bitbucket",
     "Verify connection",
     "Choose repository",
     "Confirm connection",
@@ -333,7 +351,7 @@ function renderStep(deps, index) {
  * must never leave the user with nothing. The words are the app's own Bitbucket
  * navigation, so they stay correct without any Bridge-side configuration at all.
  */
-export const BITBUCKET_REDEEM_NAVIGATION_PATH = 'Workspace settings → Apps → "Connect Bitbucket to Bridge API"';
+export const BITBUCKET_REDEEM_NAVIGATION_PATH = 'Workspace settings → Forge Apps → "Connect Bitbucket to Bridge API"';
 /** The one `{workspace}` token a redemption template may carry. */
 const WORKSPACE_TOKEN = "{workspace}";
 /**
@@ -431,6 +449,24 @@ function renderRedemptionGuidance(deps, template, workspace) {
         deps.stderr("  Replace {workspace} with your Bitbucket workspace slug.");
     }
 }
+/**
+ * Print what to do in approval mode (BAPI-1401): install, then Approve the request that
+ * shows this run's check value. The code is never printed. `firstRequest` is false on a
+ * renewal, where the browser is already open and only the new request's check changes.
+ */
+function renderApprovalGuidance(deps, repoName, approvalCheck, template, workspace, firstRequest) {
+    if (firstRequest) {
+        deps.stderr("Step 1: install the app in the browser window that just opened.");
+    }
+    else {
+        deps.stderr("A new request was created. The app install page is already open in your browser.");
+    }
+    deps.stderr(`Step 2: in Bitbucket, go to ${BITBUCKET_REDEEM_NAVIGATION_PATH} and click Approve on ` +
+        `the request for ${repoName} showing check ${approvalCheck}.`);
+    const link = renderBitbucketRedeemLink(template, workspace);
+    if (link)
+        deps.stderr(`  Direct link: ${link}`);
+}
 /** Display identity for a candidate: prefer the unambiguous workspace/repo slug form. */
 function candidateLabel(c) {
     const slugForm = `${c.workspace_slug}/${c.repository_slug}`;
@@ -443,6 +479,8 @@ function candidateLabel(c) {
 const OUTCOME_MESSAGES = {
     expired: "The connection request expired before the Forge app reported back. Run connect-bitbucket again.",
     invalid: "This connection request is no longer valid. Run connect-bitbucket again.",
+    // BAPI-1401: an `invalid` status that carries reason "declined".
+    declined: "The connection request was declined in Bitbucket. Run connect-bitbucket again to start a new request.",
     "no-repositories": "The Bitbucket Forge app installation did not include any repositories Bridge can " +
         "access. Re-run connect-bitbucket and grant access to at least one repository.",
 };
@@ -453,9 +491,13 @@ const FAILURE_MESSAGES = {
     "not-found": "Bridge does not recognize this project. Check --repo matches your Bridge project name.",
     server: "Bridge API returned an error. Run connect-bitbucket again shortly.",
     malformed: "Bridge API returned an unexpected response. Run connect-bitbucket again shortly.",
-    deadline: "Timed out waiting for the Bitbucket Forge app. If you completed the install and pasted " +
-        "the code, run connect-bitbucket again to pick up the connection.",
+    deadline: "Timed out waiting for the Bitbucket Forge app. If you installed the app and approved " +
+        "the request (or pasted the code), run connect-bitbucket again to pick up the connection.",
+    "too-many-pending": "Too many Bitbucket connection requests are waiting. Approve or decline them in " +
+        "Bitbucket, or wait up to 15 minutes for them to expire, then run connect-bitbucket again.",
 };
+/** BAPI-1401: offered after the first approval-mode expiry or deadline. */
+const USE_CODE_FALLBACK_HINT = "Can't see the request? Re-run with --use-code";
 /** Only an explicit, case-insensitive `y`/`yes` approves. One definition, used everywhere. */
 function isAffirmative(answer) {
     const normalized = answer.trim().toLowerCase();
@@ -548,7 +590,7 @@ async function chooseCandidate(deps, candidates) {
  * a renewal can never confirm against a previous code.
  */
 export async function runBitbucketConnectionFlow(deps, api, repoName, options = {}) {
-    const { workspace, initialMintApproved = false } = options;
+    const { workspace, useCode = false, initialMintApproved = false } = options;
     renderStep(deps, 0);
     if (!initialMintApproved) {
         // A standalone run asks before it mints: minting is a side effect (a live code, a
@@ -559,8 +601,11 @@ export async function runBitbucketConnectionFlow(deps, api, repoName, options =
     }
     let browserOpened = false;
     let expiryCount = 0;
+    let useCodeHintShown = false;
     for (;;) {
-        const minted = await mintBitbucketConnection(api, repoName);
+        // BAPI-1401: the workspace is sent as an approval-mode claim unless the user asked
+        // for the code flow. The server's response, not this request, decides the mode.
+        const minted = await mintBitbucketConnection(api, repoName, useCode ? undefined : workspace);
         if (!minted.ok) {
             // Includes a renewal mint: a failed fresh mint is terminal and resumable, never
             // silently retried. An automatic retry here would spend codes the user cannot see.
@@ -568,6 +613,13 @@ export async function runBitbucketConnectionFlow(deps, api, repoName, options =
         }
         // Iteration-local. Nothing outside this block may read a previous code.
         const connection = minted.value;
+        // Approval mode needs a workspace to have been claimed; a server that answers
+        // "approve" to a claimless mint is treated as code mode rather than trusted.
+        const approval = connection.approvalMode === "approve" &&
+            connection.approvalCheck !== null &&
+            !useCode &&
+            workspace !== undefined;
+        const firstRequest = !browserOpened;
         if (!browserOpened) {
             renderStep(deps, 1);
             deps.stderr("Opening Bitbucket…");
@@ -581,13 +633,20 @@ export async function runBitbucketConnectionFlow(deps, api, repoName, options =
             // both noise and a stale destination.
             browserOpened = true;
         }
-        renderRedemptionGuidance(deps, connection.redeemUrlTemplate, workspace);
-        // The code itself is not a bearer credential the way the URL's state parameter is
-        // treated elsewhere in this flow — it must be visible so the user can paste it into
-        // the installed Forge app's admin panel, which is how redemption actually happens for
-        // a Forge app (there is no GitHub-style browser redirect back to Bridge). This is
-        // the single statement in the command that prints a code, and it runs once per mint.
-        deps.stderr(`Paste this code there: ${connection.state}`);
+        if (approval) {
+            // BAPI-1401: nothing to paste. `connection.state` stays in memory, used only for
+            // polling and confirmation below.
+            renderApprovalGuidance(deps, repoName, connection.approvalCheck, connection.redeemUrlTemplate, workspace, firstRequest);
+        }
+        else {
+            renderRedemptionGuidance(deps, connection.redeemUrlTemplate, workspace);
+            // The code itself is not a bearer credential the way the URL's state parameter is
+            // treated elsewhere in this flow — it must be visible so the user can paste it into
+            // the installed Forge app's settings page, which is how redemption happens in code
+            // mode (there is no GitHub-style browser redirect back to Bridge). This is the
+            // single statement in the command that prints a code, and it runs once per mint.
+            deps.stderr(`Paste this code there: ${connection.state}`);
+        }
         renderStep(deps, 2);
         const minutes = Math.floor(POLL_DEADLINE_MS / 60_000);
         deps.stderr(`Waiting for the Bitbucket Forge app… (up to ~${minutes} minutes)`);
@@ -599,14 +658,23 @@ export async function runBitbucketConnectionFlow(deps, api, repoName, options =
         if (renewable) {
             expiryCount += 1;
             deps.stderr("");
-            deps.stderr("That code expired and can no longer be used.");
+            deps.stderr(approval
+                ? "That request expired and can no longer be approved."
+                : "That code expired and can no longer be used.");
+            if (approval && !useCodeHintShown) {
+                deps.stderr(USE_CODE_FALLBACK_HINT);
+                useCodeHintShown = true;
+            }
             if (expiryCount > 1) {
                 // Said only after it has happened more than once — by then the likely cause is
                 // not slowness but a wrong page or an app that was never installed.
                 deps.stderr("If this keeps happening, check that the Forge app is installed and that you " +
                     "have the right workspace's settings page open.");
             }
-            if (await confirm(deps, "Issue a fresh code and keep waiting? [y/N]: ")) {
+            const renewQuestion = approval
+                ? "Create a fresh request and keep waiting? [y/N]: "
+                : "Issue a fresh code and keep waiting? [y/N]: ";
+            if (await confirm(deps, renewQuestion)) {
                 continue;
             }
             return reportNoConnection(deps, polled.ok ? OUTCOME_MESSAGES.expired : FAILURE_MESSAGES.deadline, repoName, "incomplete");
@@ -624,7 +692,8 @@ export async function runBitbucketConnectionFlow(deps, api, repoName, options =
             return { kind: "connected", displayName };
         }
         if (result.status !== "staged") {
-            return reportNoConnection(deps, OUTCOME_MESSAGES[result.status] ?? OUTCOME_MESSAGES.invalid, repoName);
+            const outcomeKey = result.status === "invalid" && result.reason === "declined" ? "declined" : result.status;
+            return reportNoConnection(deps, OUTCOME_MESSAGES[outcomeKey] ?? OUTCOME_MESSAGES.invalid, repoName);
         }
         const candidates = result.candidates;
         if (candidates.length === 0) {
@@ -729,8 +798,12 @@ export async function runConnectBitbucketCli(argv, injected) {
             baseUrl: deps.env.BAPI_BASE_URL?.trim() || DEFAULT_BAPI_BASE_URL,
             apiKey: cred.credentials.apiKey,
         };
+        // BAPI-1401: explicit --workspace, else the origin remote. Inferred even with
+        // --use-code, where it still resolves the printed settings-page link.
+        const workspace = await resolveBitbucketWorkspace(parsed.value.workspace, deps.cwd, deps.runGit, deps.stderr);
         const result = await runBitbucketConnectionFlow(deps, api, repo.value, {
-            workspace: parsed.value.workspace,
+            workspace,
+            useCode: parsed.value.useCode,
             // Standalone: nobody has asked yet, so the flow owns the initial confirmation.
             initialMintApproved: false,
         });