@bridge_gpt/mcp-server 0.2.53 → 0.2.54

package/build/conductor/epic-runtime.js

@@ -39,6 +39,7 @@ import { createDefaultStartTicketsDeps, orchestrateStartTickets } from "../start
 import { orchestrateReviewTickets } from "../review-tickets.js";
 import { createStartTicketsConductorContext, provisionConductorHooksForRows, emitStartTicketsRunStarted, } from "../start-tickets-conductor.js";
 import { validateBranchName } from "../base-ref.js";
+import { resolveDeclaredRunBaseBranch } from "./run-branch.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -1108,15 +1109,26 @@ export async function runEpicTick(options, deps = {}) {
             // tickets, gated by quiescence. Invert the impl-dispatch maps so ledger
             // events can be attributed back to a ticket for local-first PR binding.
             const dispatchedBackstopPolicy = resolveDispatchedBackstopPolicy(epicRunState.epic_run.policy_json);
-            // BAPI-586: resolve the run's configured base branch so the done-gate pass
-            // can catch a wrong-base PR (one not targeting the run base) at
-            // reconciliation time — the backstop to the executor's own finalization
-            // guard. A malformed configured base defaults to undefined (base check
-            // skipped) rather than failing the whole tick; dispatch already fails
-            // closed on a malformed base separately.
-            const runBaseResolution = resolveConfiguredRunBaseBranch(epicRunState.epic_run.policy_json);
+            // BAPI-586/BAPI-1127: resolve the run's EFFECTIVE base branch so the
+            // done-gate pass can catch a wrong-base PR (one not targeting the run
+            // base) at reconciliation time — the backstop to the executor's own
+            // finalization guard.
+            //
+            // BAPI-1127 moved branch-name validation out of the shared declaration
+            // resolver and into this operational wrapper, so this call site now owns
+            // the fail-closed disposition it used to inherit. It fails CLOSED: when
+            // the declared base is not a usable ref the pass is SKIPPED entirely
+            // rather than run with the base comparison silently disabled. A pass that
+            // cannot verify a PR's base cannot honestly admit one as done, and the
+            // wrong-base PR this check exists to catch is exactly what would slip
+            // through. The skip happens BEFORE any PR binding resolution, CI
+            // observation, or provider call, and reports only the failed rule.
+            const runBaseResolution = resolveEffectiveRunBaseBranch(epicRunState.epic_run.policy_json);
+            if (!runBaseResolution.ok) {
+                errorLog(`[epic-tick] done-gate pass skipped for ${epic_key}: ${runBaseResolution.error}`);
+            }
             const doneGateExpectedBaseBranch = runBaseResolution.ok
-                ? runBaseResolution.baseBranch
+                ? runBaseResolution.effectiveBaseBranch
                 : undefined;
             const ticketForRunId = new Map();
             for (const [tk, rid] of ticketRunIdMap)
@@ -1134,63 +1146,65 @@ export async function runEpicTick(options, deps = {}) {
                 policy: dispatchedBackstopPolicy,
                 resolveImplRunId: resolveTicketRunId,
             });
-            await runConductorDoneGatePass(observed.ticket_statuses, {
-                observePrCi: observePrCiSeamFn,
-                // BAPI-586: the run base so the done-gate pass fails a wrong-base PR
-                // before CI/review evaluation (reconciliation backstop to executor
-                // finalization).
-                expectedBaseBranch: doneGateExpectedBaseBranch,
-                resolvePrBinding,
-                // BAPI-525 Change B: local-first binding + quiescence gate for the new
-                // dispatched/running admission (policy default OFF ⇒ no behavior change).
-                resolveActivePrBinding,
-                dispatchedBackstopPolicy,
-                resolveActiveTicketQuiescence,
-                // BAPI-487: re-evaluate a blocked ticket only when its PR head advanced
-                // past the head recorded on its latest blocking signal.
-                resolveBlockedHeadSha: (tk) => observed.ticket_blocked_heads?.get(tk) ?? null,
-                resolveRunId: resolveTicketRunId,
-                resolveWorkerId: resolveDoneGateWorkerId,
-                // BAPI-494: convert a detected conflict into a durable, head-scoped
-                // `merge.conflict` ledger event stamped with the ticket's dispatch run/worker
-                // so the fold correlates it and the remediation pass redispatches. Emitted via
-                // the shared injectable emitter, idempotent per conflict head. Folded next tick
-                // (this pass runs after rebuildObservedState), matching the gate.met latency.
-                emitConflictSignal: (input) => {
-                    emitConductorEventFn({
-                        source: MERGE_CONFLICT_EVENT_SOURCE,
-                        type: "merge.conflict",
-                        subject: input.ticketKey,
-                        run_id: input.runId,
-                        worker_id: input.workerId,
-                        producer: MERGE_CONFLICT_EVENT_PRODUCER,
-                        observed_via: "supervisor",
-                        time: new Date(nowFn()).toISOString(),
-                        data: {
-                            summary: `PR #${input.prNumber} for ${input.ticketKey} is not mergeable`,
-                            status: "blocked",
-                            reason: "merge.conflict",
-                            details: {
-                                epic_key,
-                                ticket_key: input.ticketKey,
-                                repo: input.repoName,
-                                pr_number: input.prNumber,
-                                head_sha: input.headSha,
-                                mergeable: input.mergeable,
-                                mergeStateStatus: input.mergeStateStatus,
+            if (runBaseResolution.ok) {
+                await runConductorDoneGatePass(observed.ticket_statuses, {
+                    observePrCi: observePrCiSeamFn,
+                    // BAPI-586: the run base so the done-gate pass fails a wrong-base PR
+                    // before CI/review evaluation (reconciliation backstop to executor
+                    // finalization).
+                    expectedBaseBranch: doneGateExpectedBaseBranch,
+                    resolvePrBinding,
+                    // BAPI-525 Change B: local-first binding + quiescence gate for the new
+                    // dispatched/running admission (policy default OFF ⇒ no behavior change).
+                    resolveActivePrBinding,
+                    dispatchedBackstopPolicy,
+                    resolveActiveTicketQuiescence,
+                    // BAPI-487: re-evaluate a blocked ticket only when its PR head advanced
+                    // past the head recorded on its latest blocking signal.
+                    resolveBlockedHeadSha: (tk) => observed.ticket_blocked_heads?.get(tk) ?? null,
+                    resolveRunId: resolveTicketRunId,
+                    resolveWorkerId: resolveDoneGateWorkerId,
+                    // BAPI-494: convert a detected conflict into a durable, head-scoped
+                    // `merge.conflict` ledger event stamped with the ticket's dispatch run/worker
+                    // so the fold correlates it and the remediation pass redispatches. Emitted via
+                    // the shared injectable emitter, idempotent per conflict head. Folded next tick
+                    // (this pass runs after rebuildObservedState), matching the gate.met latency.
+                    emitConflictSignal: (input) => {
+                        emitConductorEventFn({
+                            source: MERGE_CONFLICT_EVENT_SOURCE,
+                            type: "merge.conflict",
+                            subject: input.ticketKey,
+                            run_id: input.runId,
+                            worker_id: input.workerId,
+                            producer: MERGE_CONFLICT_EVENT_PRODUCER,
+                            observed_via: "supervisor",
+                            time: new Date(nowFn()).toISOString(),
+                            data: {
+                                summary: `PR #${input.prNumber} for ${input.ticketKey} is not mergeable`,
+                                status: "blocked",
+                                reason: "merge.conflict",
+                                details: {
+                                    epic_key,
+                                    ticket_key: input.ticketKey,
+                                    repo: input.repoName,
+                                    pr_number: input.prNumber,
+                                    head_sha: input.headSha,
+                                    mergeable: input.mergeable,
+                                    mergeStateStatus: input.mergeStateStatus,
+                                },
                             },
-                        },
-                    }, {
-                        event_type: "merge.conflict",
-                        run_id: input.runId ?? undefined,
-                        commit_sha: input.headSha,
-                    });
-                },
-                access,
-                env,
-                log,
-                errorLog,
-            });
+                        }, {
+                            event_type: "merge.conflict",
+                            run_id: input.runId ?? undefined,
+                            commit_sha: input.headSha,
+                        });
+                    },
+                    access,
+                    env,
+                    log,
+                    errorLog,
+                });
+            }
             const maxSeqForRun = (runId) => {
                 let maxSeq = 0;
                 for (const ev of localEvents) {
@@ -1554,39 +1568,46 @@ export async function runEpicTick(options, deps = {}) {
     }
 }
 /**
- * BAPI-586: resolve the epic run's configured base branch from `policy_json`
- * (`base_branch`, else `baseBranch`), mirroring the server-side reconciler's
- * spec-review base resolution. The authoritative run base — NOT a hard-coded
- * `main` — is what every fresh dispatch and PR must target.
+ * BAPI-586/BAPI-1127: resolve the epic run's EFFECTIVE base branch — the branch
+ * every fresh dispatch cuts from and every child PR targets.
+ *
+ * Two layers, deliberately kept apart:
  *
- * - absent/empty → `main` (the legacy/default value).
- * - present and a valid branch name → that branch (e.g. `develop`).
- * - present but malformed (non-string, `..`, `.lock`, control chars, leading `-`)
- *   → a contract failure so dispatch fails CLOSED rather than emitting a malformed
- *   base (a wrong base is exactly the BAPI-586 defect).
+ * 1. DECLARATION, delegated in full to the dependency-free
+ *    {@link resolveDeclaredRunBaseBranch} leaf, which is the shared cross-runtime
+ *    contract this function does not get a second opinion about. The ordered
+ *    `base_branch` → `baseBranch` scan, the skip-and-continue treatment of a
+ *    non-string or blank candidate, and the trim all live there.
+ * 2. OPERATIONAL POLICY, which is this function's own and is NOT shared with
+ *    Python: an undeclared policy defaults to `main`, and the branch that will
+ *    actually be handed to git is validated before it is returned.
+ *
+ * The frozen dispositions (BAPI-1127) show up here as follows:
+ *
+ * - A NON-STRING candidate is absent, not fatal. `{base_branch: 42,
+ *   baseBranch: "epic/X"}` now resolves to `epic/X`; before BAPI-1127 it failed
+ *   closed, and `{base_branch: "", baseBranch: "epic/X"}` reported `main` — a
+ *   different real branch from the one the server provisioned.
+ * - A MALFORMED declared name does NOT fall back to `main`. Silently
+ *   substituting the default for a bad declaration is how a wrong base becomes
+ *   invisible (the BAPI-586 defect), so it fails closed and dispatch refuses.
+ *   Only an ACTUAL absence of a declaration reaches the default.
+ *
+ * Validation happens here, once, ahead of both operational consumers (dispatch
+ * and the done gate) rather than inside the shared resolver, so that Python and
+ * TypeScript agree about what a policy declares while each keeps its own
+ * judgment about what is safe to use. The failure carries only the rule that
+ * failed — never the policy document or an unbounded branch value.
  */
-export function resolveConfiguredRunBaseBranch(policyJson) {
+export function resolveEffectiveRunBaseBranch(policyJson) {
     const DEFAULT_BASE = "main";
-    if (!policyJson || typeof policyJson !== "object") {
-        return { ok: true, baseBranch: DEFAULT_BASE };
-    }
-    const raw = policyJson.base_branch ??
-        policyJson.baseBranch;
-    if (raw === undefined || raw === null) {
-        return { ok: true, baseBranch: DEFAULT_BASE };
-    }
-    if (typeof raw !== "string") {
-        return { ok: false, error: "epic run policy base_branch is present but is not a string." };
-    }
-    const trimmed = raw.trim();
-    if (trimmed.length === 0) {
-        return { ok: true, baseBranch: DEFAULT_BASE };
-    }
-    const validationError = validateBranchName(trimmed);
+    const declaredBaseBranch = resolveDeclaredRunBaseBranch(policyJson);
+    const effectiveBaseBranch = declaredBaseBranch ?? DEFAULT_BASE;
+    const validationError = validateBranchName(effectiveBaseBranch);
     if (validationError) {
         return { ok: false, error: `epic run policy base_branch is invalid: ${validationError}` };
     }
-    return { ok: true, baseBranch: trimmed };
+    return { ok: true, declaredBaseBranch, effectiveBaseBranch };
 }
 /**
  * Build the production EpicRuntimeDeps for use inside `runEpicTickCommand`.
@@ -1615,13 +1636,23 @@ export async function buildProductionEpicRuntimeDeps(epicKey) {
     // error (observe-only would already default to `main`); a malformed configured
     // base is captured as an error and re-raised at dispatch time so a bad base
     // never silently dispatches.
-    let cachedRunBase = { ok: true, baseBranch: "main" };
+    //
+    // BAPI-1127: the fetch-failure fallback declares NOTHING and dispatches from
+    // `main`, which is what "we could not read the policy" honestly means — the
+    // two values are kept separate so a later reader cannot mistake the default
+    // for a declaration the run never made.
+    const UNDECLARED_MAIN = {
+        ok: true,
+        declaredBaseBranch: undefined,
+        effectiveBaseBranch: "main",
+    };
+    let cachedRunBase = UNDECLARED_MAIN;
     try {
         const runState = await fetchEpicRunState(access, epicKey);
-        cachedRunBase = resolveConfiguredRunBaseBranch(runState.epic_run.policy_json);
+        cachedRunBase = resolveEffectiveRunBaseBranch(runState.epic_run.policy_json);
     }
     catch {
-        cachedRunBase = { ok: true, baseBranch: "main" };
+        cachedRunBase = UNDECLARED_MAIN;
     }
     // Shared closure state populated by fetchPlan and consumed by dispatchSeam.
     let cachedPlanVersion = 0;
@@ -1687,12 +1718,17 @@ export async function buildProductionEpicRuntimeDeps(epicKey) {
         if (cachedPlanVersion === 0) {
             throw new Error(`dispatchSeam called before fetchPlan for epic ${ek} ticket ${tk}; cachedPlanVersion is 0`);
         }
-        // BAPI-586: fail CLOSED on a malformed configured run base rather than
-        // dispatching a worker (and opening a PR) against a bad base.
+        // BAPI-586/BAPI-1127: fail CLOSED on a malformed configured run base rather
+        // than dispatching a worker (and opening a PR) against a bad base. The check
+        // is here — ahead of the dispatch claim, the spawn command, and any git or
+        // provider work — because `resolveEffectiveRunBaseBranch` validates the ref
+        // but this is the boundary that actually uses it. Only `effectiveBaseBranch`
+        // (declaration, else `main`) is handed on; the declaration itself stays
+        // separately readable on `cachedRunBase` and is never overwritten.
         if (!cachedRunBase.ok) {
             throw new Error(`invalid configured base branch for epic ${ek}: ${cachedRunBase.error}`);
         }
-        const runBaseBranch = cachedRunBase.baseBranch;
+        const runBaseBranch = cachedRunBase.effectiveBaseBranch;
         // BAPI-441: a remediation re-dispatch (attempt > 0) reuses the existing
         // branch/worktree (resume mode) and claims an attempt-scoped dispatch key so
         // it is not deduped against the original epic dispatch.

package/build/conductor/readiness.js

@@ -112,6 +112,12 @@ export const SERVER_READINESS_DESCRIPTORS = [
     { id: "executor-readiness", label: "Executor server observation" },
     { id: "review-workflow", label: "Review workflow protocol" },
     { id: "conductor-ci-workflow", label: "Conductor CI migration guard" },
+    // BAPI-1102 — the two ONE-TIME unattended prerequisites plus the aggregate the
+    // third unattended refusal reads. Noun phrases, like every row above: these
+    // render as list items under a source heading, not as sentences.
+    { id: "unattended-consent", label: "Repository unattended consent" },
+    { id: "unattended-notify-default", label: "Verified notify webhook default" },
+    { id: "repository-workflow-readiness", label: "Repository workflow readiness" },
 ];
 /** Fixed, secret-free prose per failure kind. Never a status body or header. */
 const SERVER_FAILURE_COPY = {
@@ -153,6 +159,11 @@ const SERVER_REMEDIATIONS = {
     ciWorkflowUnknown: "re-run; the default branch's conductor CI workflow could not be evaluated, which is not the same as the guard being absent.",
     ciWorkflowMissingGuard: "add the migration-guard job to the conductor CI workflow on the default branch so migrations are checked before a merge.",
     olderServer: "upgrade the Bridge API deploy so it reports this fact; its state is unknown here, not healthy.",
+    // BAPI-1102. Each names the ONE action that clears it, and none of them
+    // mentions a webhook URL, a destination, or any configuration value.
+    unattendedConsent: "set `unattended_conductor_allowed` for this repository (docs/claude/account-settings-operator-runbook.md), or run setup with --attended.",
+    unattendedNotifyDefault: "supply a --policy-file declaring notify.webhook_url, or run setup with --attended; an unattended run must have a working escalation channel, and notify.local_sink is not one.",
+    repositoryWorkflowReadiness: "run `install-bridge conductor` so the review and conductor-CI workflows are confirmed on the default branch, or run setup with --attended.",
 };
 /**
  * Project the validated server readiness response into `server.*` checks.
@@ -261,6 +272,7 @@ export function mapServerReadinessToChecks(readiness, failure = "unreachable") {
     outcomes.push(executorOutcome(readiness));
     outcomes.push(reviewWorkflowOutcome(readiness));
     outcomes.push(ciWorkflowOutcome(readiness));
+    outcomes.push(...unattendedOutcomes(readiness));
     const byId = new Map(outcomes.map((outcome) => [outcome.id, outcome]));
     return SERVER_READINESS_DESCRIPTORS.map(({ id, label }) => {
         const outcome = byId.get(id);
@@ -286,6 +298,79 @@ export function mapServerReadinessToChecks(readiness, failure = "unreachable") {
         });
     });
 }
+/**
+ * The three BAPI-1102 unattended prerequisite rows.
+ *
+ * Returned as a group because they share one absence rule: a server older than
+ * BAPI-1102 reports no `unattended` block at all, and an unreported fact is a
+ * FAILURE with the older-server remediation — never a pass. "Could not be read"
+ * and "read and healthy" are the two answers this whole module refuses to
+ * conflate, and these are prerequisites for an UNATTENDED merge, which is the
+ * worst place to guess.
+ *
+ * Consent and workflow readiness are `warn`, not `fail`, when confirmed absent:
+ * a repository that never runs an unattended epic needs neither, so reporting
+ * them as failures would mark a perfectly healthy attended install broken. They
+ * become hard refusals only at `setup-epic`, and only for a run whose effective
+ * policy is actually unattended.
+ */
+function unattendedOutcomes(readiness) {
+    const u = readiness.unattended;
+    if (u === null) {
+        return [
+            "unattended-consent",
+            "unattended-notify-default",
+            "repository-workflow-readiness",
+        ].map((id) => ({
+            id,
+            status: "fail",
+            detail: "this server fact was not reported",
+            remediation: SERVER_REMEDIATIONS.olderServer,
+        }));
+    }
+    return [
+        u.conductor_allowed
+            ? {
+                id: "unattended-consent",
+                status: "pass",
+                detail: "this repository has consented to unattended conductor runs",
+            }
+            : {
+                id: "unattended-consent",
+                status: "warn",
+                detail: "unattended_conductor_allowed is NOT set — an unattended run will be refused before it is created",
+                remediation: SERVER_REMEDIATIONS.unattendedConsent,
+            },
+        u.notify_webhook_default_declared
+            ? {
+                id: "unattended-notify-default",
+                status: "pass",
+                // Presence only. The URL is never reported by the server and is never
+                // rendered here.
+                detail: u.notify_webhook_default_verified === true
+                    ? "a notify webhook default is declared and verified"
+                    : "a notify webhook default is declared (verified at approval, not here)",
+            }
+            : {
+                id: "unattended-notify-default",
+                status: "warn",
+                detail: "no repository notify webhook default is declared — an unattended run needs an escalation channel, and no column supplies a repository default today, so the run must declare notify.webhook_url itself",
+                remediation: SERVER_REMEDIATIONS.unattendedNotifyDefault,
+            },
+        u.repository_readiness_confirmed
+            ? {
+                id: "repository-workflow-readiness",
+                status: "pass",
+                detail: "the review and conductor-CI workflows are both confirmed",
+            }
+            : {
+                id: "repository-workflow-readiness",
+                status: "warn",
+                detail: "the review and conductor-CI workflows are not both confirmed — an unattended auto-merging run will be refused",
+                remediation: SERVER_REMEDIATIONS.repositoryWorkflowReadiness,
+            },
+    ];
+}
 /** Review-policy presence and alignment, as one check with one fix each. */
 function reviewPolicyOutcome(readiness) {
     const s = readiness.supervisor;

package/build/conductor/run-branch.js

@@ -0,0 +1,137 @@
+/**
+ * Canonical TypeScript run-branch DECLARATION resolution (BAPI-1127).
+ *
+ * The TypeScript counterpart of `api/models/run_branch.py`, and the only place
+ * in this package that answers "which base branch, if any, does this persisted
+ * run's `policy_json` DECLARE?" Before BAPI-1127 the question was answered in
+ * three places that disagreed — the defaulting resolver in `epic-runtime.ts`
+ * (a `??` scan that stopped on a present-but-blank `base_branch` and therefore
+ * never consulted the camelCase alias), `bridge-api-client.ts#readEpicRunCompletionState`
+ * (snake_case only, and it did not trim), and the Python resolver across the
+ * wire. The two runtimes feed the SAME epic run from opposite sides, so a
+ * disagreement means the server provisions one branch while the CLI cuts worker
+ * branches from another, silently.
+ *
+ * **Declaration only.** This module answers exactly one question and stops:
+ * what branch did the policy declare? It deliberately does NOT:
+ *
+ *   - apply the TypeScript-only `main` default. That is a DISPATCH-layer policy
+ *     owned by `epic-runtime.ts#resolveEffectiveRunBaseBranch`. A classification
+ *     or observation consumer that adopted it would report `main` for a run that
+ *     declared nothing, conflating "declared no branch" with "dispatches from
+ *     main" — the exact confusion that kept `featureBranch` honest before.
+ *   - apply branch-name validity rules. `validateBranchName` is an OPERATIONAL
+ *     judgment made by whichever caller is about to hand the value to git or a
+ *     provider, and it is applied there.
+ *
+ * **The frozen cross-runtime dispositions** (BAPI-1127, and the same two rules
+ * `api/models/run_branch.py` states):
+ *
+ *   - A NON-STRING candidate is ABSENT, not fatal. The ordered scan skips it and
+ *     continues to the next key, so the legacy row
+ *     `{"base_branch": 42, "baseBranch": "epic/X"}` resolves to `epic/X` rather
+ *     than failing closed on the unusable snake_case value. The strict server-side
+ *     `RunPolicy` boundary already rejects a non-string `base_branch` before it can
+ *     be stored, so this rule governs legacy and out-of-band rows only.
+ *   - A MALFORMED or over-length declaration is still a DECLARATION. It is
+ *     returned complete and trimmed, never truncated, rejected, or replaced with
+ *     a default; format and length are validated at the point of operational use.
+ *
+ * **Why a leaf.** `epic-runtime.ts` already imports from `bridge-api-client.ts`,
+ * so putting the shared resolver in either one and importing it from the other
+ * would close a cycle. This module imports NOTHING — not the API client, not a
+ * command runner, not `base-ref.js`'s validator — so every consumer can depend on
+ * it freely. That is the same reasoning `api/models/run_branch.py:13-24` gives for
+ * its own placement.
+ *
+ * The cross-language contract is frozen as data in
+ * `tests/pytest/fixtures/run_branch_vectors.json` and enforced from both sides by
+ * `mcp_server/src/conductor/run-branch.test.ts` and
+ * `tests/pytest/models/test_run_branch_vectors.py`.
+ */
+/**
+ * The policy keys consulted, IN ORDER. Both spellings are accepted because both
+ * have been written by real clients; `base_branch` is canonical and `baseBranch`
+ * is the legacy alias. Named once so the precedence is stated in exactly one
+ * place, mirroring `POLICY_BASE_BRANCH_KEYS` in `api/models/run_branch.py`.
+ */
+export const POLICY_BASE_BRANCH_KEYS = ["base_branch", "baseBranch"];
+/**
+ * Return the trimmed string, or `undefined` for anything that is not a usable
+ * one.
+ *
+ * A blank or whitespace-only value is NOT a branch: accepting it would let a run
+ * created with `base_branch: "   "` classify as a feature-branch run, which at
+ * the merge-admission boundary would hand it the ungated-auto-merge exception on
+ * the strength of whitespace. The Python twin is `run_branch._nonblank`.
+ *
+ * KNOWN GAP — the trim is proven equivalent only for ASCII whitespace
+ * (BAPI-1127 review). `String.prototype.trim()` and Python's `str.strip()` do
+ * not strip the same character class, so four inputs resolve differently and
+ * none is in the vector table:
+ *
+ * | declared value      | Python `_nonblank`   | this function        |
+ * |---------------------|----------------------|----------------------|
+ * | `"\u001cepic/X"`    | `"epic/X"`           | `"\u001cepic/X"`     |
+ * | `"\u0085"`          | absent (blank)       | `"\u0085"`           |
+ * | `"\u0085epic/X"`    | `"epic/X"`           | `"\u0085epic/X"`     |
+ * | `"\ufeffmain"`      | `"\ufeffmain"`       | `"main"`             |
+ *
+ * `str.strip()` also strips U+001C-U+001F and U+0085; `trim()` also strips
+ * U+FEFF. Note the second row is the sharp one: U+0085 is above 0x7F, so
+ * `validateBranchName`'s control-character rule does NOT reject it either.
+ *
+ * Left as FOLLOW-UP rather than fixed here, deliberately. Picking the canonical
+ * class is a contract decision of the same kind BAPI-1127 froze for the
+ * non-string and malformed-name rows — and it was frozen in the TICKET, not by
+ * the implementer. Normalizing Python's class would additionally change
+ * feature-branch classification for a policy the `RunPolicy` boundary accepts
+ * today (`{"base_branch": "\u0085"}` classifies as no-feature-branch now), which
+ * BAPI-1127's acceptance criteria forbid. `RunPolicy` accepts any strict string,
+ * so these values are storable, but they are vanishingly unlikely in practice.
+ * Recorded alongside the `git check-ref-format` follow-up in `base-ref.ts`.
+ */
+function nonblank(candidate) {
+    if (typeof candidate !== "string")
+        return undefined;
+    const trimmed = candidate.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * Resolve the branch a persisted run's `policy_json` declares, if any.
+ *
+ * Returns the first non-blank string found across {@link POLICY_BASE_BRANCH_KEYS},
+ * in that order, trimmed; or `undefined` when the policy declares none.
+ *
+ * The scan is SEQUENTIAL, not nullish-coalescing: a candidate that is not a
+ * non-blank string is skipped and the scan CONTINUES to the next key. `??` falls
+ * through only for `null`/`undefined`, which is why the pre-BAPI-1127 expression
+ * stopped at a present-but-blank `base_branch` and reported the dispatch default
+ * for a policy that plainly declared `baseBranch: "epic/X"`.
+ *
+ * A non-mapping policy (`null`, `undefined`, a primitive, an array) declares
+ * nothing. Shape is the typed boundary's job, not this resolver's — the Python
+ * twin makes the same call for the same reason.
+ *
+ * The returned value is never truncated and carries no operational length or
+ * format bound. See the module docstring for both frozen dispositions.
+ */
+export function resolveDeclaredRunBaseBranch(policyJson) {
+    if (policyJson === null || typeof policyJson !== "object" || Array.isArray(policyJson)) {
+        return undefined;
+    }
+    const policy = policyJson;
+    for (const key of POLICY_BASE_BRANCH_KEYS) {
+        // OWN properties only. A Python dict has no prototype chain, so a plain
+        // `policy[key]` would not be the same read: it also sees `Object.prototype`,
+        // and a polluted prototype would make EVERY policy in the process appear to
+        // declare a branch. Real inputs come from `JSON.parse`, which never produces
+        // inherited keys, so this costs nothing and closes the gap.
+        if (!Object.prototype.hasOwnProperty.call(policy, key))
+            continue;
+        const resolved = nonblank(policy[key]);
+        if (resolved !== undefined)
+            return resolved;
+    }
+    return undefined;
+}