@bridge_gpt/mcp-server 0.2.60 → 0.2.65

package/build/conductor/recovery-operations.js

@@ -18,9 +18,11 @@
  * callers: `recovery-cli.ts` and `plane/shutdown.ts`.
  */
 import { randomUUID } from "crypto";
-import { adoptCurrentHeadAndUnparkTicket, completeMergeChild, ConductorBridgeApiError, dispatchRemediation, fetchEpicRunState, mergeChild, patchPolicy, resumeRun, safeDiagnosticMessage, scopeCatchUp, scopeReparse, stopEpicRun, unparkEpicTicket, updateEpicRunStatus, } from "./bridge-api-client.js";
+import { adoptCurrentHeadAndUnparkTicket, completeMergeChild, ConductorBridgeApiError, dispatchRemediation, fetchEpicRunState, mergeChild, patchPolicy, resumeRun, safeDiagnosticMessage, scopeCatchUp, scopeReparse, stopEpicRun, unparkEpicTicket, updateEpicRunStatus, fetchChildContinuationStatus, postContinueParkedChild, REVIEW_HEAD_REFUSAL_CODES, } from "./bridge-api-client.js";
 import { DEFAULT_GATE_NAME } from "./git-ci-types.js";
+import { clearContinuationReference, computeContinuationFingerprint, isFullSha, newContinuationRequestId, readContinuationReference, writeContinuationReference, } from "./epic-child-continuation.js";
 import { resolveLocalMergeCredential, resolveLocalMergeMethod, runApprovedLocalMerge, } from "./local-merge.js";
+import { RESUME_RUN_UNCONFIRMED_MESSAGE } from "./repair-contract.js";
 /**
  * Bounded total attempts for a ticket-recovery CAS retry loop. Each attempt
  * begins with a fresh, authoritative state read — so this bounds full
@@ -179,6 +181,17 @@ async function ticketRecoveryWithRetry(access, options, mutate) {
             });
         }
         catch (err) {
+            const refusal = reviewHeadRefusal(err);
+            if (refusal !== null) {
+                return {
+                    ok: false,
+                    kind: "refused",
+                    epicRunId: options.epicRunId,
+                    ticketKey: options.ticketKey,
+                    errorCode: refusal.errorCode,
+                    message: refusal.message,
+                };
+            }
             return {
                 ok: false,
                 kind: "unavailable",
@@ -188,12 +201,14 @@ async function ticketRecoveryWithRetry(access, options, mutate) {
             };
         }
         if (result.ok) {
+            const recovery = result.ticket_status.review_head_recovery;
             return {
                 ok: true,
                 kind: "unparked",
                 epicRunId: options.epicRunId,
                 ticketKey: options.ticketKey,
                 status: result.ticket_status.status,
+                ...(recovery ? { reviewHeadRecovery: recovery } : {}),
             };
         }
         // `result.kind === "cas-conflict"`: a concurrent write moved the ticket's
@@ -207,6 +222,31 @@ async function ticketRecoveryWithRetry(access, options, mutate) {
         ticketKey: options.ticketKey,
     };
 }
+/**
+ * BAPI-1310 (E1): fixed operator sentences for the review-head refusal codes.
+ * Chosen by code so no server or provider text reaches the terminal.
+ */
+const REVIEW_HEAD_REFUSAL_MESSAGES = {
+    REVIEW_HEAD_ADOPTION_REQUIRED: "the ticket is parked on an unexplained review-head change; accept the current " +
+        "head with `epic-implementer adopt-current-head-and-unpark` (keeps spent repair " +
+        "allowances, resumes at CI). A generic unpark or remediation is refused",
+    REVIEW_HEAD_EPISODE_CONFLICT: "the ticket is no longer on the stop this request was made for; re-check its " +
+        "status (explain-run) before trying again",
+    REVIEW_HEAD_STATE_INVALID: "the ticket's stored recovery state cannot support an allowance-preserving " +
+        "adoption",
+    REVIEW_HEAD_BINDING_CHANGED: "the ticket's pull request could not be confirmed open with an unchanged identity",
+    REVIEW_HEAD_LIVE_WORK: "an executor job is, or may be, active for this ticket; retry when it has finished",
+    REVIEW_HEAD_UNAVAILABLE: "the current head or the ticket specification could not be read; retry shortly",
+};
+/** Map a thrown client error to an E1 refusal, or `null` for anything else. */
+function reviewHeadRefusal(err) {
+    if (!(err instanceof ConductorBridgeApiError) || err.status !== 409)
+        return null;
+    const code = err.errorCode;
+    if (typeof code !== "string" || !REVIEW_HEAD_REFUSAL_CODES.includes(code))
+        return null;
+    return { errorCode: code, message: REVIEW_HEAD_REFUSAL_MESSAGES[code] ?? "refused" };
+}
 /**
  * Unpark a parked `needs_human` ticket, with a bounded authoritative-reread
  * retry on a concurrent `row_version` bump.
@@ -385,9 +425,17 @@ export async function patchPolicyRepair(access, options, deps = {}) {
     }
 }
 /**
- * Resume a paused run, or a quarantined one with `clearQuarantine`. The server
- * re-evaluates activation and owns the control-generation CAS retry; nothing here
- * reads or sends a generation.
+ * Resume a paused run, a quarantined one with `clearQuarantine`, or a run held by
+ * an eligible integration block. The server re-evaluates activation and owns the
+ * control-generation CAS retry; nothing here reads or sends a generation. It makes
+ * exactly ONE mutation call and returns a parsed success verbatim — no read, no
+ * retry, no poll, and no legacy `/resume` fallback.
+ *
+ * Only a structured 4xx is an authoritative refusal (the server decided and wrote
+ * nothing). A 5xx — even one carrying an `error_code` — a timeout, a dropped
+ * connection, or an unparseable/unexpected 2xx cannot prove whether the resume
+ * committed, so each is `unavailable` with {@link RESUME_RUN_UNCONFIRMED_MESSAGE}.
+ * Other repair verbs keep {@link classifyRepairError} unchanged.
  */
 export async function resumeRunRepair(access, options, deps = {}) {
     try {
@@ -395,6 +443,204 @@ export async function resumeRunRepair(access, options, deps = {}) {
         return { ok: true, result: await call(access, options) };
     }
     catch (err) {
-        return classifyRepairError(err, "resume-run request failed");
+        if (err instanceof ConductorBridgeApiError &&
+            typeof err.status === "number" &&
+            err.status >= 400 &&
+            err.status < 500 &&
+            err.errorCode) {
+            return classifyRepairError(err, "resume-run request failed");
+        }
+        return { ok: false, kind: "unavailable", message: RESUME_RUN_UNCONFIRMED_MESSAGE };
+    }
+}
+const AUTHORITATIVE_OUTCOMES = new Set([
+    "committed",
+    "already_continued",
+    "stale_historical_episode",
+    "refused",
+    "unsupported",
+]);
+/**
+ * Look the request's receipt up exactly once. Returns a decided result only when
+ * a durable receipt for THIS request id proves the commit; anything else is
+ * `null` (still unconfirmed). Never re-reads CAS tokens and never mutates.
+ */
+async function lookupOwnReceipt(access, reference, fetchStatus) {
+    let status;
+    try {
+        status = await fetchStatus(access, {
+            epicRunId: reference.bindings.epicRunId,
+            ticketKey: reference.bindings.ticketKey,
+            requestId: reference.requestId,
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!status.found || status.receipt === null)
+        return null;
+    if (status.receipt.request_id !== reference.requestId)
+        return null;
+    const outcome = status.outcome === "stale_historical_episode" ? "stale_historical_episode" : "committed";
+    return {
+        outcome,
+        reason_code: outcome === "committed" ? null : "stale_episode",
+        explanation: outcome === "committed"
+            ? "The receipt proves this request's continuation committed."
+            : "The receipt proves this request's continuation committed; the child has since parked again.",
+        replayed: true,
+        retryable: false,
+        receipt: status.receipt,
+        current: status.current,
+    };
+}
+/**
+ * Continue a parked child through the server's atomic continuation, at most one
+ * POST per invocation.
+ *
+ * A pending recovery reference for this child is REUSED as-is — same request id,
+ * same bindings — so a lost response is resolved by a replay the server answers
+ * from its receipt, and a restarted process can never approve a new head or
+ * episode by re-reading the child. Only when no reference exists are the
+ * bindings read (once), fingerprinted, and stored BEFORE the POST is sent.
+ *
+ * After a transport failure, a malformed success body, or a 5xx, exactly one
+ * receipt lookup follows. No second POST, no new request id, no polling for
+ * completion, and never a fallback to unpark.
+ */
+export async function continueChildOnce(access, options, deps = {}) {
+    const fetchStatus = deps.fetchStatus ?? fetchChildContinuationStatus;
+    const post = deps.post ?? postContinueParkedChild;
+    const store = deps.store ?? {};
+    let reference = await readContinuationReference(options.epicRunId, options.ticketKey, store);
+    if (reference !== null && reference.bindings.repoName !== access.repoName) {
+        reference = null;
+    }
+    const reusedReference = reference !== null;
+    if (reference === null) {
+        let status;
+        try {
+            status = await fetchStatus(access, {
+                epicRunId: options.epicRunId,
+                ticketKey: options.ticketKey,
+            });
+        }
+        catch (err) {
+            return { kind: "unavailable", message: safeDiagnosticMessage(err, "could not read the child") };
+        }
+        const current = status.current;
+        if (!current.parked ||
+            !current.continuation_available ||
+            current.parked_gate === null ||
+            current.park_generation === null) {
+            return { kind: "not_continuable", current };
+        }
+        const head = current.expected_head_sha === null ? null : current.expected_head_sha.toLowerCase();
+        if (head !== null && !isFullSha(head)) {
+            return { kind: "unavailable", message: "the child's bound head is not a full SHA" };
+        }
+        const bindings = {
+            repoName: access.repoName,
+            epicRunId: status.epic_run_id,
+            ticketKey: status.ticket_key,
+            parkedGate: current.parked_gate,
+            expectedRowVersion: current.row_version,
+            expectedHeadSha: head,
+            sourceParkGeneration: current.park_generation,
+        };
+        reference = {
+            version: 1,
+            bindings,
+            requestId: (deps.newRequestId ?? newContinuationRequestId)(),
+            requestFingerprint: computeContinuationFingerprint(bindings),
+            createdAt: new Date().toISOString(),
+        };
+        try {
+            // Also keyed by the caller's own addressing so the next invocation (which
+            // may use the epic key rather than the resolved id) finds it.
+            await writeContinuationReference(reference, store);
+            if (options.epicRunId !== bindings.epicRunId || options.ticketKey !== bindings.ticketKey) {
+                await writeContinuationReference(reference, store, {
+                    epicRunId: options.epicRunId,
+                    ticketKey: options.ticketKey,
+                });
+            }
+        }
+        catch {
+            return {
+                kind: "unavailable",
+                message: "could not store the local recovery reference, so the request was not sent",
+            };
+        }
+    }
+    const ref = reference;
+    const clear = async () => {
+        await clearContinuationReference(options.epicRunId, options.ticketKey, store);
+        await clearContinuationReference(ref.bindings.epicRunId, ref.bindings.ticketKey, store);
+    };
+    const outcome = await post(access, {
+        bindings: ref.bindings,
+        requestId: ref.requestId,
+        requestFingerprint: ref.requestFingerprint,
+        reason: options.reason,
+    });
+    if (outcome.kind === "result" && AUTHORITATIVE_OUTCOMES.has(outcome.result.outcome)) {
+        await clear();
+        return { kind: "decided", requestId: ref.requestId, reusedReference, result: outcome.result };
+    }
+    if (outcome.kind === "refused_http") {
+        await clear();
+        return {
+            kind: "refused_http",
+            requestId: ref.requestId,
+            status: outcome.status,
+            errorCode: outcome.errorCode,
+        };
+    }
+    // Uncertain (transport, malformed 2xx, 5xx, or the server's own unconfirmed).
+    const transport = outcome.kind === "uncertain"
+        ? outcome.status !== undefined
+            ? `${outcome.reason} (status ${outcome.status})`
+            : outcome.reason
+        : "indeterminate commit";
+    const proven = await lookupOwnReceipt(access, ref, fetchStatus);
+    if (proven !== null) {
+        await clear();
+        return { kind: "decided", requestId: ref.requestId, reusedReference, result: proven };
+    }
+    return { kind: "unconfirmed", requestId: ref.requestId, reusedReference, transport };
+}
+/**
+ * Read a child's current episode and, when a local recovery reference exists (or
+ * `requestId` is given), that request's receipt. One bounded GET; read-only. A
+ * reference is cleared only when the lookup PROVES its commit; `not_found` keeps
+ * it, because the absence of a receipt right now does not prove the request will
+ * never have committed if it is still in flight.
+ */
+export async function lookupContinuationReceipt(access, options, deps = {}) {
+    const fetchStatus = deps.fetchStatus ?? fetchChildContinuationStatus;
+    const store = deps.store ?? {};
+    const reference = options.requestId
+        ? null
+        : await readContinuationReference(options.epicRunId, options.ticketKey, store);
+    const requestId = options.requestId ?? reference?.requestId ?? null;
+    let status;
+    try {
+        status = await fetchStatus(access, {
+            epicRunId: reference?.bindings.epicRunId ?? options.epicRunId,
+            ticketKey: reference?.bindings.ticketKey ?? options.ticketKey,
+            ...(requestId ? { requestId } : {}),
+        });
+    }
+    catch (err) {
+        return { kind: "unavailable", message: safeDiagnosticMessage(err, "could not read the child") };
+    }
+    if (status.found && status.receipt !== null) {
+        if (reference !== null && status.receipt.request_id === reference.requestId) {
+            await clearContinuationReference(options.epicRunId, options.ticketKey, store);
+            await clearContinuationReference(reference.bindings.epicRunId, reference.bindings.ticketKey, store);
+        }
+        return { kind: "found", requestId, status };
     }
+    return { kind: "not_found", requestId, status };
 }

package/build/conductor/repair-contract.js

@@ -43,6 +43,14 @@ export const DRIVER_CONTEXT_MAX_BYTES = 16384;
  * never parsed, printed, or transmitted.
  */
 export const POLICY_PATCH_MAX_BYTES = 16384;
+/**
+ * BAPI-1294 — the bounded `unavailable` message for a `resume-run` whose outcome
+ * the client cannot confirm (a 5xx, timeout, dropped connection, or unreadable
+ * 2xx). It never repeats server body text and never claims either outcome.
+ */
+export const RESUME_RUN_UNCONFIRMED_MESSAGE = "resume-run outcome could not be confirmed: the server may or may not have " +
+    "committed the resume. Inspect the run read-only before choosing any separately " +
+    "authorized mutation";
 /**
  * The closed refusal-code vocabulary, mirroring the server table.
  *

package/build/conductor-bundle-artifacts.js

@@ -225,6 +225,7 @@ export async function validateConductorBundleInputs(args, fs) {
         epic_plan_path: path.join(resolvedEpicDir.value, "epic-plan.md"),
         sidecar_path: path.join(resolvedEpicDir.value, "epic-plan.dag.json"),
         manifest_path: path.join(resolvedEpicDir.value, "sibling-ticket-manifest.json"),
+        meta_path: path.join(resolvedEpicDir.value, "epic-plan.meta.json"),
         report_path: path.join(resolvedEpicDir.value, "harmonization-report.json"),
         plan_version: planVersion.value,
         mappings: resolvedMappings,

package/build/credential-store.js

@@ -1370,6 +1370,12 @@ export async function upsertBapiCredential(repoName, apiKey, deps) {
         const action = hadKey ? "updated" : "created";
         // Preserve sibling secret names; replace ONLY BAPI_API_KEY.
         const nextEntry = { ...(existingEntry ?? {}), BAPI_API_KEY: trimmedKey };
+        // BAPI-1260: an epic-launch binding approves ONE key for one endpoint. A
+        // different key is a different credential, so its approval does not carry
+        // over — guided setup re-binds it explicitly.
+        if (existingEntry && existingEntry.BAPI_API_KEY !== trimmedKey) {
+            delete nextEntry[BAPI_EPIC_LAUNCH_BOUND_BASE_URL_FIELD];
+        }
         const next = { ...base, [target]: nextEntry };
         const dir = path.dirname(primaryPath);
         const suffix = (deps.tempSuffix ?? defaultTempSuffix)();
@@ -1408,3 +1414,191 @@ export async function upsertBapiCredential(repoName, apiKey, deps) {
         return { ok: true, path: primaryPath, target, action, migratedFallback };
     }, (error) => ({ ok: false, path: primaryPath, target, kind: "lock-error", error }));
 }
+// ---------------------------------------------------------------------------
+// Epic-launch credential binding (BAPI-1260)
+// ---------------------------------------------------------------------------
+/**
+ * NON-SECRET sibling field under `bapi:<repo>` naming the one normalized Bridge
+ * API base URL the stored `BAPI_API_KEY` was approved for by guided setup.
+ *
+ * Every pre-existing reader asks for `BAPI_API_KEY` only, so the extra field is
+ * invisible to them — existing credential clients and the public decoding of
+ * the store are unchanged. Only the epic-launch contract below reads it.
+ */
+export const BAPI_EPIC_LAUNCH_BOUND_BASE_URL_FIELD = "BAPI_EPIC_LAUNCH_BOUND_BASE_URL";
+/** Trim and drop trailing slashes — the executor's own base-URL normalization. */
+function normalizeBoundBaseUrl(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const normalized = raw.trim().replace(/\/+$/, "");
+    return normalized.length > 0 ? normalized : null;
+}
+/**
+ * Resolve the `BAPI_API_KEY` for an EPIC LAUNCH against one selected target.
+ *
+ * Unlike {@link resolveBapiCredentials}, the credential is coupled to the
+ * normalized base URL AND the repository, so a repo-only credential is never
+ * silently sent to a different endpoint:
+ *
+ *   - An ambient `BAPI_API_KEY` is used only when the same environment also sets
+ *     `BAPI_BASE_URL` to exactly the target — the pair is its provenance.
+ *     Anything else is `ambient-key-unbound`, and the key is NOT sent.
+ *   - A stored key is used when its entry carries
+ *     {@link BAPI_EPIC_LAUNCH_BOUND_BASE_URL_FIELD} equal to the target.
+ *   - BAPI-1272: a stored key with NO binding field is also used when the
+ *     target normalizes to `options.productionBaseUrl` (`production-default`).
+ *     For any other target an entry with no binding is `binding-unbound` (a
+ *     legacy credential, upgraded once through guided setup).
+ *   - A binding to a different endpoint — or a binding field that is present
+ *     but empty — is `binding-mismatch`, even when the target is production:
+ *     a key approved for a local server is never sent to production.
+ *
+ * Read-only and migration-free: it never writes the store. Errors name the
+ * logical target and the store path only — never a secret or the entry's
+ * contents.
+ */
+export async function resolveEpicLaunchCredential(repoName, targetBaseUrl, deps, options = {}) {
+    const target = normalizeBoundBaseUrl(targetBaseUrl);
+    const bundleKey = `bapi:${repoName}`;
+    if (target === null || repoName.trim().length === 0) {
+        return { ok: false, kind: "missing-key", error: "An epic launch needs a target and a repository." };
+    }
+    const envKey = (deps.env.BAPI_API_KEY ?? "").trim();
+    if (envKey.length > 0) {
+        const envBase = normalizeBoundBaseUrl(deps.env.BAPI_BASE_URL);
+        if (envBase !== target) {
+            return {
+                ok: false,
+                kind: "ambient-key-unbound",
+                error: "BAPI_API_KEY is set in this environment, but BAPI_BASE_URL does not name the selected " +
+                    "target, so the key's endpoint cannot be shown. It was not sent. Unset BAPI_API_KEY to use " +
+                    "the credential approved by setup, or set BAPI_BASE_URL to the selected target.",
+            };
+        }
+        return { ok: true, apiKey: envKey, source: "env", binding: "env-paired" };
+    }
+    // Read the stored entry exactly as the shared resolver would, but with the
+    // environment cleared so the ambient branch above stays the only env path.
+    // XDG_CONFIG_HOME is kept: it locates the store, and dropping it would read the
+    // key from a different file than the binding below (and than setup wrote).
+    const stored = await resolveCredentialBundle(bundleKey, ["BAPI_API_KEY"], {
+        ...deps,
+        env: { XDG_CONFIG_HOME: deps.env.XDG_CONFIG_HOME },
+    });
+    if (!stored.ok)
+        return { ok: false, kind: stored.kind, error: stored.error };
+    const binding = await readStoredBindingState(bundleKey, deps);
+    const primaryPath = getPrimaryCredentialStorePath(deps);
+    if (binding.state === "absent" || binding.state === "no-entry") {
+        const production = normalizeBoundBaseUrl(options.productionBaseUrl);
+        if (binding.state === "absent" && production !== null && production === target) {
+            return { ok: true, apiKey: stored.values.BAPI_API_KEY, source: "file", binding: "production-default" };
+        }
+        return {
+            ok: false,
+            kind: "binding-unbound",
+            error: `The stored credential "${bundleKey}" has not been approved for this Bridge API endpoint ` +
+                `(${primaryPath}). Production needs no approval; any other endpoint does. Run guided setup ` +
+                `once to bind it: install conductor --launch-profile <name> --base-url ${target}.`,
+        };
+    }
+    // An unreadable read-back is refused like a mismatch: the key was read a
+    // moment ago, so failing closed is the only safe reading.
+    if (binding.state === "invalid" || binding.state === "unreadable" || binding.baseUrl !== target) {
+        return {
+            ok: false,
+            kind: "binding-mismatch",
+            error: `The stored credential "${bundleKey}" is approved for a different Bridge API endpoint than the ` +
+                "selected target. It was not sent. A key approved for a local server is never sent to " +
+                "production: pass that server's --launch-profile <name> or --base-url <url>, or bind the key " +
+                "once with install conductor --launch-profile <name> --base-url <url>.",
+        };
+    }
+    return { ok: true, apiKey: stored.values.BAPI_API_KEY, source: "file", binding: "store-bound" };
+}
+/**
+ * Read the binding field of one bundle in the three states of
+ * {@link StoredBindingState}. Never throws.
+ */
+export async function readStoredBindingState(bundleKey, deps) {
+    try {
+        const resolution = await resolveCredentialStorePath(deps);
+        if (!resolution.found)
+            return { state: "no-entry" };
+        const parsed = parseCredentialStoreJson(await deps.readFile(resolution.path));
+        if (!parsed.ok)
+            return { state: "unreadable" };
+        const entry = parsed.value[bundleKey];
+        if (entry === undefined)
+            return { state: "no-entry" };
+        if (!Object.prototype.hasOwnProperty.call(entry, BAPI_EPIC_LAUNCH_BOUND_BASE_URL_FIELD)) {
+            return { state: "absent" };
+        }
+        const baseUrl = normalizeBoundBaseUrl(entry[BAPI_EPIC_LAUNCH_BOUND_BASE_URL_FIELD]);
+        return baseUrl === null ? { state: "invalid" } : { state: "bound", baseUrl };
+    }
+    catch {
+        return { state: "unreadable" };
+    }
+}
+/**
+ * Read the non-secret bound base URL for one bundle, or `null` when the store,
+ * the entry, or the field is absent or unreadable. Never throws.
+ */
+export async function readStoredBinding(bundleKey, deps) {
+    try {
+        const resolution = await resolveCredentialStorePath(deps);
+        if (!resolution.found)
+            return null;
+        const parsed = parseCredentialStoreJson(await deps.readFile(resolution.path));
+        if (!parsed.ok)
+            return null;
+        return normalizeBoundBaseUrl(parsed.value[bundleKey]?.[BAPI_EPIC_LAUNCH_BOUND_BASE_URL_FIELD]);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The explicit ONE-TIME upgrade path: approve the stored `bapi:<repo>` key for
+ * one normalized base URL. Called only by guided setup after it has re-verified
+ * access and administrative authorization at that target — never by a launch.
+ *
+ * Writes only the non-secret binding field, under the shared lock, through the
+ * durable replacement; every other entry and sibling field is preserved. A store
+ * with no key for the repository is refused rather than creating one.
+ */
+export async function bindEpicLaunchCredential(repoName, targetBaseUrl, deps) {
+    const target = `bapi:${repoName.trim()}`;
+    const baseUrl = normalizeBoundBaseUrl(targetBaseUrl);
+    if (repoName.trim().length === 0 || baseUrl === null) {
+        return { ok: false, target, kind: "invalid-input", error: "A repository and a target are required." };
+    }
+    const primaryPath = getPrimaryCredentialStorePath(deps);
+    return withCredentialStoreLock(deps, async () => {
+        const primary = await readCredentialStoreJsonIfPresent(primaryPath, deps);
+        if (primary.state === "error") {
+            return { ok: false, target, kind: primary.kind, error: primary.error };
+        }
+        const entry = primary.state === "present" ? primary.value[target] : undefined;
+        if (!entry || typeof entry.BAPI_API_KEY !== "string" || entry.BAPI_API_KEY.trim() === "") {
+            return {
+                ok: false,
+                target,
+                kind: "not-found",
+                error: `No stored BAPI_API_KEY under "${target}" in ${primaryPath} to bind.`,
+            };
+        }
+        const previous = normalizeBoundBaseUrl(entry[BAPI_EPIC_LAUNCH_BOUND_BASE_URL_FIELD]);
+        if (previous === baseUrl)
+            return { ok: true, target, action: "unchanged", path: primaryPath };
+        const next = {
+            ...(primary.state === "present" ? primary.value : {}),
+            [target]: { ...entry, [BAPI_EPIC_LAUNCH_BOUND_BASE_URL_FIELD]: baseUrl },
+        };
+        const written = await durablyReplaceCredentialStoreJson(primaryPath, next, deps);
+        if (!written.ok)
+            return { ok: false, target, kind: written.kind, error: written.error };
+        return { ok: true, target, action: previous === null ? "bound" : "rebound", path: primaryPath };
+    }, (error) => ({ ok: false, target, kind: "lock-error", error }));
+}