@bridge_gpt/mcp-server 0.2.19 → 0.2.21

package/build/estimate-epic.js

@@ -0,0 +1,84 @@
+/**
+ * estimate-epic.ts — orchestration for the deterministic `estimate_epic` MCP tool
+ * (BAPI-523).
+ *
+ * `index.ts` stays the thin registration surface; input validation, request
+ * shaping, and response formatting live here so they are unit-testable without a
+ * real network call or credential store. Mirrors the `visual-diff.ts` pattern:
+ * this module never imports `index.ts` — the caller injects `buildUrl`,
+ * `getPostHeaders`, and `handleResponse` (index.ts's existing fetch helpers) as
+ * deps. `epic_key` and `ticket_keys` are mutually exclusive and validated BEFORE
+ * any network call; no `mode` parameter exists — the source is inferred from
+ * which key input is supplied. There is no `recreate` parameter: the BAPI-522
+ * orchestrator does not currently expose one (see `api/routes/estimate_epic.py`
+ * for the backend-side note), so this tool intentionally does not accept one
+ * either.
+ */
+/**
+ * Validate mutually-exclusive/required key inputs before any network call.
+ * Returns a human-readable error message, or `null` when the input is valid.
+ */
+export function validateEstimateEpicInput(input) {
+    const hasEpic = typeof input.epic_key === "string" && input.epic_key.trim().length > 0;
+    const hasKeys = Array.isArray(input.ticket_keys);
+    if (hasEpic && hasKeys) {
+        return "epic_key and ticket_keys are mutually exclusive; supply exactly one, never both.";
+    }
+    if (!hasEpic && !hasKeys) {
+        return "Exactly one of epic_key or ticket_keys is required.";
+    }
+    if (hasKeys && input.ticket_keys.length === 0) {
+        return "ticket_keys was supplied but contained no keys; provide at least one, non-empty ticket_keys.";
+    }
+    return null;
+}
+/** A structured, JSON-safe validation/error envelope — never a successful estimate payload. */
+export function buildEstimateEpicErrorEnvelope(code, message, extras) {
+    return JSON.stringify({ error: code, message, ...(extras ?? {}) }, null, 2);
+}
+/** Serialize a payload with stable two-space indentation for MCP text content. */
+export function toolText(payload) {
+    return typeof payload === "string" ? payload : JSON.stringify(payload, null, 2);
+}
+/**
+ * Run the `estimate_epic` tool: validate input, POST to the Bridge API
+ * `/jira/estimate-epic` endpoint, and return MCP text content. Never throws —
+ * every failure (validation, network, backend error) becomes a structured JSON
+ * error envelope in the returned text content.
+ */
+export async function runEstimateEpic(input, deps) {
+    const validationError = validateEstimateEpicInput(input);
+    if (validationError) {
+        return {
+            content: [{ type: "text", text: buildEstimateEpicErrorEnvelope("VALIDATION_ERROR", validationError) }],
+        };
+    }
+    const payload = { repo_name: deps.repoName };
+    if (typeof input.epic_key === "string")
+        payload.epic_key = input.epic_key;
+    if (Array.isArray(input.ticket_keys))
+        payload.ticket_keys = input.ticket_keys;
+    if (typeof input.allow_partial === "boolean")
+        payload.allow_partial = input.allow_partial;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    let resp;
+    try {
+        resp = await fetchImpl(deps.buildUrl("/estimate-epic"), {
+            method: "POST",
+            headers: await deps.getPostHeaders(),
+            body: JSON.stringify(payload),
+        });
+    }
+    catch {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: buildEstimateEpicErrorEnvelope("NETWORK_ERROR", "Failed to reach the Bridge API estimate-epic endpoint."),
+                },
+            ],
+        };
+    }
+    const text = await deps.handleResponse(resp);
+    return { content: [{ type: "text", text }] };
+}

package/build/executor/job-runner.js

@@ -18,7 +18,7 @@ import os from "node:os";
 import { buildExecutorWorkerEnv } from "./env.js";
 import { runHeartbeatLoop } from "./heartbeat.js";
 import { isExecutorNamedError, toExecutorFailure, secretFreeErrorMessage, MissingVerdictArtifact, } from "./job-errors.js";
-import { buildConductorMergeAccessForExecutorJob, buildDefaultMergeLocalDeps, runExecutorMergeJob, } from "./merge-job.js";
+import { buildConductorMergeAccessForExecutorJob, buildDefaultMergeLocalDeps, runExecutorMergeJob, MERGE_RETRYABLE, MERGE_FAILED, } from "./merge-job.js";
 import { createObservationState } from "./observation.js";
 import { provisionExecutorDenyLayer } from "./permissions.js";
 import { runProcessWithTimeout } from "./process.js";
@@ -89,8 +89,13 @@ function buildJobLogRegistryDeps(deps) {
         platform: deps.platform,
     };
 }
-/** Default merge dispatch: resolve Bridge API access, then run the deterministic merge. */
-async function defaultRunMergeForClaimed(job, deps, _options) {
+/**
+ * Default merge dispatch: resolve Bridge API access, then run the deterministic
+ * merge. Exported for unit tests (access-resolution failure → retryable). The
+ * `controls.signal` (overall-timeout abort) is threaded into local merge deps
+ * without changing the local `gh` credential model.
+ */
+export async function defaultRunMergeForClaimed(job, deps, _options, controls) {
     const accessResult = await buildConductorMergeAccessForExecutorJob({
         env: deps.env,
         cwd: deps.cwd,
@@ -100,10 +105,13 @@ async function defaultRunMergeForClaimed(job, deps, _options) {
         stat: deps.stat,
     });
     if (!accessResult.ok) {
+        // Access resolution feeds only the executor's read-only CI re-poll; a missing
+        // or temporarily-unavailable Bridge API access is transient infrastructure, so
+        // it is RETRYABLE (BAPI-572). The local `gh` credential model is unchanged.
         return {
             ok: false,
             failure: {
-                error_kind: "MergeAccessUnavailable",
+                error_kind: MERGE_RETRYABLE,
                 error_message: accessResult.error,
                 classification: "crashed",
             },
@@ -111,7 +119,9 @@ async function defaultRunMergeForClaimed(job, deps, _options) {
     }
     return runExecutorMergeJob(job, {
         access: accessResult.access,
-        localMergeDeps: buildDefaultMergeLocalDeps(deps),
+        // Thread the overall-timeout abort signal into local merge deps WITHOUT
+        // changing the local `gh` credential model (the signal is not a credential).
+        localMergeDeps: buildDefaultMergeLocalDeps(deps, controls?.signal),
     });
 }
 /** An in-memory owned process for the no-op `smoke` acceptance job. */
@@ -192,7 +202,7 @@ export async function runClaimedJob(job, httpClient, options, deps, _report, sea
     // ensure/recreate or worker-spawn logic — it ensures no worktree and spawns no
     // worker (TDD §5/§9).
     if (job.job_type === "merge") {
-        return runMergeJob(job, httpClient, options, deps, ownership, seams);
+        return runMergeJob(job, httpClient, options, deps, ownership, observation, seams);
     }
     if (job.job_type === "smoke") {
         return runSmokeJob(job, httpClient, options, deps, ownership, observation);
@@ -213,23 +223,146 @@ export async function runClaimedJob(job, httpClient, options, deps, _report, sea
     return { status: "failed", reason: "unsupported_job_type" };
 }
 /**
- * Run a deterministic `merge` job: NO worktree ensured, NO worker spawned. The
- * local merge executor's outcome drives `/complete` (success) or `/fail`
- * (deterministic failure); stale/retry/invalid outcomes reuse T3a handling.
+ * Adapt a `runMerge(...)` promise into an {@link OwnedChildProcess} so the merge
+ * flow is supervised by the SAME heartbeat/deadman/timeout path as spawn/smoke
+ * jobs even though it spawns no worker. `wait()` resolves when the merge outcome
+ * is available (exit_code 0 on `ok`, 1 otherwise); `kill()` aborts the internal
+ * {@link AbortController} (cancelling in-flight local `gh` work) and resolves the
+ * owned process as killed. The stored outcome/error let the runner map the
+ * supervised result to `/complete` or `/fail` afterwards (killed/timeout is read
+ * from the supervised `ProcessRunResult`/`ownership`, not from this adapter).
  */
-async function runMergeJob(job, httpClient, options, deps, ownership, seams) {
-    const runMerge = seams.runMerge ?? defaultRunMergeForClaimed;
+function createMergeFlowProcess(startMerge) {
+    const controller = new AbortController();
     let outcome;
-    try {
-        outcome = await runMerge(job, deps, options);
+    let error;
+    let done = false;
+    let settleWait = () => { };
+    const waitPromise = new Promise((resolve) => {
+        settleWait = resolve;
+    });
+    // Start the merge flow immediately; capture its resolution/rejection.
+    startMerge(controller.signal).then((result) => {
+        outcome = result;
+        if (!done) {
+            done = true;
+            settleWait({ exitCode: result.ok ? 0 : 1, signal: null });
+        }
+    }, (err) => {
+        error = err;
+        if (!done) {
+            done = true;
+            settleWait({ exitCode: 1, signal: null });
+        }
+    });
+    const proc = {
+        pid: undefined,
+        stdout: null,
+        stderr: null,
+        async wait() {
+            return waitPromise;
+        },
+        kill(signal) {
+            if (done)
+                return;
+            controller.abort();
+            done = true;
+            settleWait({ exitCode: null, signal });
+        },
+    };
+    return {
+        proc,
+        getOutcome: () => outcome,
+        getError: () => error,
+    };
+}
+/**
+ * Run a deterministic `merge` job: NO worktree ensured, NO worker spawned. Unlike
+ * the pre-BAPI-572 version, the merge flow now runs under the SHARED heartbeat/
+ * deadman/timeout supervision path (via {@link superviseProcess}) so a live merge
+ * heartbeats (the janitor never re-queues a healthy multi-minute merge) and the
+ * whole flow honors `payload.timeout_seconds`. A timeout is reported as a
+ * RETRYABLE failure and a late merge resolution after timeout/abandonment is
+ * ignored. The local merge executor's outcome otherwise drives `/complete`
+ * (success) or `/fail`; stale/retry/invalid terminal outcomes reuse T3a handling.
+ */
+async function runMergeJob(job, httpClient, options, deps, ownership, observation, seams) {
+    // Resolve + enforce payload.timeout_seconds BEFORE starting any merge work.
+    const timeout = resolveJobTimeoutSeconds(job, options.defaultJobTimeoutSeconds);
+    if (!timeout.ok) {
+        await httpClient.fail(job, {
+            error_kind: "ContractError.Timeout",
+            error_message: timeout.error,
+            classification: "crashed",
+        });
+        return { status: "failed", reason: "timeout_contract" };
     }
-    catch (err) {
+    const timeoutSeconds = timeout.timeoutSeconds;
+    const runMerge = seams.runMerge ?? defaultRunMergeForClaimed;
+    const flow = createMergeFlowProcess((signal) => runMerge(job, deps, options, { signal }));
+    const procResult = await superviseProcess({
+        job,
+        httpClient,
+        options,
+        deps,
+        ownership,
+        observation,
+        proc: flow.proc,
+        timeoutSeconds,
+        collectTelemetry: async () => ({}),
+    });
+    // Ownership abandonment (stale-claim / dead-man) wins: never send a terminal
+    // mutation for a claim we no longer own, and never process a late outcome.
+    if (ownership.abandoned) {
+        return { status: "abandoned", reason: ownership.abandonReason };
+    }
+    // Overall merge flow timed out: fail the active claim as RETRYABLE and ignore
+    // any later merge promise resolution (the abort has already been signalled).
+    if (procResult.classification === "timeout") {
         const terminal = await sendTerminalMutationWithRetry({
             kind: "fail",
             send: () => httpClient.fail(job, {
-                error_kind: "MergeError",
-                error_message: secretFreeErrorMessage(err),
+                error_kind: MERGE_RETRYABLE,
+                error_message: `merge flow timed out after ${timeoutSeconds} seconds`,
+                classification: "timeout",
+                telemetry: observation.snapshot(),
+            }),
+            deps,
+            options,
+            ownership,
+            log: deps.log,
+        });
+        return terminalToRunResult(terminal, "failed");
+    }
+    // A thrown error inside the merge flow maps to a bounded MergeFailed.
+    const flowError = flow.getError();
+    if (flowError !== undefined) {
+        const terminal = await sendTerminalMutationWithRetry({
+            kind: "fail",
+            send: () => httpClient.fail(job, {
+                error_kind: MERGE_FAILED,
+                error_message: secretFreeErrorMessage(flowError),
                 classification: "crashed",
+                telemetry: observation.snapshot(),
+            }),
+            deps,
+            options,
+            ownership,
+            log: deps.log,
+        });
+        return terminalToRunResult(terminal, "failed");
+    }
+    const outcome = flow.getOutcome();
+    if (outcome === undefined) {
+        // Clean process result with no stored outcome — an internal invariant break;
+        // fail loud rather than silently reporting success.
+        const terminal = await sendTerminalMutationWithRetry({
+            kind: "fail",
+            send: () => httpClient.fail(job, {
+                error_kind: MERGE_FAILED,
+                error_message: "merge flow completed without an outcome",
+                classification: "crashed",
+                telemetry: observation.snapshot(),
             }),
             deps,
             options,
@@ -244,6 +377,7 @@ async function runMergeJob(job, httpClient, options, deps, ownership, seams) {
             exit_code: 0,
             classification: "clean_exit",
             result: outcome.result,
+            telemetry: observation.snapshot(),
         };
         const terminal = await sendTerminalMutationWithRetry({
             kind: "complete",
@@ -257,7 +391,7 @@ async function runMergeJob(job, httpClient, options, deps, ownership, seams) {
     }
     const terminal = await sendTerminalMutationWithRetry({
         kind: "fail",
-        send: () => httpClient.fail(job, outcome.failure),
+        send: () => httpClient.fail(job, { ...outcome.failure, telemetry: observation.snapshot() }),
         deps,
         options,
         ownership,

package/build/executor/merge-job.js

@@ -10,6 +10,16 @@
  * GitHub, so no action-key idempotency protocol is needed. On success the merge
  * outcome (accepted / merge commit) is posted at `/complete`; gate advancement is
  * left entirely to the merge OBSERVER (T4/T5) — this module never advances a gate.
+ *
+ * BAPI-572: the local `gh` auth model is unchanged (no App credentials — locked
+ * decision). Two behaviors were hardened here:
+ *  - Ambiguous merge failures are resolved by re-reading the merged state inside
+ *    {@link makeLocalMergeExecutor}, so an already-merged PR at the expected head
+ *    maps to a SUCCESS result (with the merge commit SHA), not a failure.
+ *  - Merge-domain failures no longer collapse into one `error_kind` — they emit a
+ *    machine-readable {@link MERGE_RETRYABLE}, {@link MERGE_CONFLICT}, or
+ *    {@link MERGE_FAILED} `error_kind` (via {@link classifyMergeFailureErrorKind})
+ *    so the companion re-fire lane can route retry-vs-rebase without string parsing.
  */
 import { makeLocalMergeExecutor, resolveLocalMergeMethod, } from "../conductor/local-merge.js";
 import { resolveConductorBridgeApiAccess, } from "../conductor/bridge-api-client.js";
@@ -17,6 +27,10 @@ import { secretFreeErrorMessage } from "./job-errors.js";
 function positiveIntOrNull(value) {
     return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
 }
+/** Read an optional non-negative integer (preserving 0), else `undefined`. */
+function nonNegativeIntOrUndefined(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : undefined;
+}
 function asString(value) {
     return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
 }
@@ -40,9 +54,11 @@ export function readMergeJobPayloadFields(job) {
         ? payload.required_checks.filter((c) => typeof c === "string")
         : [];
     const actionKey = asString(payload.action_key) ?? `merge:pr-${prNumber}:${expectedHeadSha}`;
+    const ciWaitTimeoutMs = nonNegativeIntOrUndefined(payload.ci_wait_timeout_ms);
+    const ciWaitPollIntervalMs = nonNegativeIntOrUndefined(payload.ci_wait_poll_interval_ms);
     return {
         ok: true,
-        fields: { prNumber, expectedHeadSha, method, requiredChecks, actionKey },
+        fields: { prNumber, expectedHeadSha, method, requiredChecks, actionKey, ciWaitTimeoutMs, ciWaitPollIntervalMs },
     };
 }
 /** Construct the {@link ConductorMergeRequest} for the local merge executor. */
@@ -97,11 +113,62 @@ export function buildMergeJobResult(response, fields) {
     }
     return result;
 }
-/** Convert a non-succeeded local-merge response into a bounded executor failure. */
+/**
+ * Machine-readable merge-domain error kinds (BAPI-572). The companion re-fire
+ * lane routes retry-vs-rebase on these values, NOT on free text:
+ *  - {@link MERGE_RETRYABLE}: transient gh/network/auth-refresh, `ci_not_green` —
+ *    safe to re-fire the same merge later.
+ *  - {@link MERGE_CONFLICT}: needs a rebase before it can merge.
+ *  - {@link MERGE_FAILED}: deterministic other failure (bad state, missing input).
+ */
+export const MERGE_RETRYABLE = "MergeRetryable";
+export const MERGE_CONFLICT = "MergeConflict";
+export const MERGE_FAILED = "MergeFailed";
+/** Reasons whose failure is transient/infrastructure and safe to retry. */
+const RETRYABLE_MERGE_REASONS = new Set([
+    "gh_pr_view_timeout",
+    "gh_pr_view_failed",
+    "gh_pr_view_unparseable",
+    "ci_poll_failed",
+    "ci_not_green",
+    "gh_merge_timeout",
+    "gh_merge_failed",
+    "merge_aborted",
+]);
+/**
+ * Classify a non-succeeded merge response into a machine-readable `error_kind`.
+ * A `merge.conflict` ledger event (or a `gh_merge_conflict` reason) is a conflict;
+ * transient/infrastructure reasons are retryable; everything else — including a
+ * missing/malformed reason — is a deterministic {@link MERGE_FAILED}.
+ *
+ * BAPI-577 Part A: the CI re-poll now emits distinct `ci_poll_*` reasons
+ * (`ci_poll_timeout`, `ci_poll_unauthorized`, `ci_poll_http_<status>`, …) instead of a
+ * single `ci_poll_failed`. All of them are transient infrastructure reads, so any
+ * `ci_poll_`-prefixed reason is retryable — a prefix match keeps unbounded HTTP-status
+ * variants covered so a distinct reason never accidentally downgrades to
+ * {@link MERGE_FAILED}. Conflict classification is checked first so it is never masked.
+ */
+export function classifyMergeFailureErrorKind(response) {
+    const hasConflictEvent = response.ledger_events.some((ev) => ev.type === "merge.conflict");
+    const reason = asString(response.reason ?? undefined);
+    if (hasConflictEvent || reason === "gh_merge_conflict")
+        return MERGE_CONFLICT;
+    if (reason && (reason.startsWith("ci_poll_") || RETRYABLE_MERGE_REASONS.has(reason))) {
+        return MERGE_RETRYABLE;
+    }
+    return MERGE_FAILED;
+}
+/**
+ * Convert a non-succeeded local-merge response into a bounded, secret-free
+ * executor failure. `error_kind` is machine-readable (retryable/conflict/failed);
+ * `error_message` includes only the sanitized merge status and reason (never raw
+ * `gh` output). `classification` stays within the executor's vocabulary; the
+ * `error_kind` is the routing signal.
+ */
 export function buildMergeJobFailure(response) {
     const reason = asString(response.reason ?? undefined) ?? response.status;
     return {
-        error_kind: "MergeFailed",
+        error_kind: classifyMergeFailureErrorKind(response),
         error_message: secretFreeErrorMessage(new Error(`local merge ${response.status}: ${reason}`)),
         classification: "crashed",
     };
@@ -126,7 +193,11 @@ export async function runExecutorMergeJob(job, seams) {
     const fields = resolution.fields;
     const request = buildConductorMergeRequestForExecutorJob(fields, seams.access.repoName);
     const make = seams.makeExecutor ?? makeLocalMergeExecutor;
-    const executor = make({ method: fields.method }, seams.localMergeDeps);
+    const executor = make({
+        method: fields.method,
+        ciWaitTimeoutMs: fields.ciWaitTimeoutMs,
+        ciWaitPollIntervalMs: fields.ciWaitPollIntervalMs,
+    }, seams.localMergeDeps);
     let response;
     try {
         response = await executor(seams.access, request);
@@ -146,10 +217,13 @@ export async function runExecutorMergeJob(job, seams) {
     }
     return { ok: false, failure: buildMergeJobFailure(response) };
 }
-/** Build the default local-merge deps for production wiring (no real I/O here). */
-export function buildDefaultMergeLocalDeps(deps) {
-    // Local `gh` auth lives in the ambient environment; makeLocalMergeExecutor
-    // overlays it and pins the no-noise/non-interactive flags. The App token is
-    // never placed here.
-    return { env: deps.env };
+/**
+ * Build the default local-merge deps for production wiring (no real I/O here).
+ * An optional {@link AbortSignal} is threaded through so the job-runner's overall
+ * merge timeout can cancel in-flight local `gh` subprocess work. The signal is
+ * NOT a credential and never reaches `gh` argv/env — the local `gh` auth model is
+ * unchanged (no App token is ever placed here).
+ */
+export function buildDefaultMergeLocalDeps(deps, signal) {
+    return { env: deps.env, signal };
 }

package/build/executor/worker-finalization.js

@@ -7,19 +7,41 @@
  * advisory pre-push suite) and returns before it completes. Without this check
  * the executor still reports `clean_exit`/`succeeded`, and the gap is only ever
  * caught by the reconciler's 3h watchdog. `validateWorkerFinalization` converts
- * that condition into an explicit executor failure instead, using a local
- * `git ls-remote` check (no Bridge API credentials, no conductor identity).
+ * that condition into an explicit executor failure instead, using an authoritative
+ * local `git ls-remote` check (no Bridge API credentials, no conductor identity)
+ * that reads the real origin tip — never a stale local `origin/<branch>` tracking
+ * ref. That lookup is optionally repeated a few times with a short bounded delay
+ * before reporting `WorkerFinalizationMissingRemoteBranchAndPr`, so a recovery
+ * job whose push has landed but whose remote visibility settles just after the
+ * worker exits is not spuriously failed (BAPI-566 Bug A).
  *
  * For `resume`/`remediate`/`ci_fix`/`rebase`, the branch is fetched from origin
  * BEFORE the worker starts (worktree.ts's recovery reuse path, resume-pre-spawn's
  * "recreate ONLY from the pushed branch" path) — so the ref existing on origin is
  * not proof THIS session's commit landed; a stale pre-existing branch would pass
- * an existence-only check. The check instead compares the origin branch's tip SHA
- * against the worker's own HEAD commit (`headSha`, from git telemetry) whenever
- * that comparison is available.
+ * an existence-only check. The check instead compares the authoritative origin
+ * branch tip SHA against the worker's own HEAD commit (`headSha`, from git
+ * telemetry) whenever that comparison is available.
  */
 import { secretFreeErrorMessage, WorkerFinalizationMissingRemoteBranchAndPr } from "./job-errors.js";
 import { isImplementationStyleJobType } from "./job-types.js";
+/** Bounded settling re-check defaults for the authoritative origin-tip lookup. */
+const DEFAULT_ORIGIN_FINALIZATION_ATTEMPTS = 3;
+const DEFAULT_ORIGIN_FINALIZATION_RETRY_DELAY_MS = 500;
+/** Real-timer sleep; overridable via the `sleep` seam for deterministic tests. */
+function sleepMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function normalizeAttempts(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0
+        ? value
+        : DEFAULT_ORIGIN_FINALIZATION_ATTEMPTS;
+}
+function normalizeRetryDelay(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? Math.floor(value)
+        : DEFAULT_ORIGIN_FINALIZATION_RETRY_DELAY_MS;
+}
 function extractPrUrl(result) {
     const raw = result.pr_url;
     return typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : undefined;
@@ -28,13 +50,66 @@ function extractPrUrl(result) {
 function normalizeBranchRef(branch) {
     return branch.startsWith("refs/heads/") ? branch : `refs/heads/${branch}`;
 }
-/** Resolve the origin branch's current tip SHA, or `null` if the ref is absent. */
-async function resolveOriginBranchSha(runCommand, worktreePath, branch) {
-    const result = await runCommand("git", ["ls-remote", "--exit-code", "--heads", "origin", normalizeBranchRef(branch)], { cwd: worktreePath });
+/**
+ * Scan `git ls-remote` stdout and return the SHA for EXACTLY `expectedRef`.
+ * `ls-remote` lines are `<sha>\t<ref>`; only an exact ref match counts, so a
+ * prefix/suffix/child ref (`…-old`, `…/retry`) is never accepted. The returned
+ * SHA is trimmed and lower-cased so callers compare against a normalized worker
+ * HEAD. Raw stderr and credentials are never touched here.
+ */
+function parseLsRemoteHeadSha(stdout, expectedRef) {
+    for (const line of stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const parts = trimmed.split(/\s+/);
+        if (parts.length < 2)
+            continue;
+        const [sha, ref] = parts;
+        if (ref === expectedRef) {
+            const normalized = sha.trim().toLowerCase();
+            return normalized.length > 0 ? normalized : null;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the origin branch's authoritative current tip SHA (normalized), or
+ * `null` if the ref is absent. Uses `git ls-remote` against the exact normalized
+ * ref — never a local `origin/<branch>` remote-tracking ref, which can be stale
+ * on a recovery worktree. A non-zero exit is treated as "branch not found"
+ * without copying raw stderr into diagnostics.
+ */
+export async function resolveOriginBranchSha(runCommand, worktreePath, branch) {
+    const normalizedRef = normalizeBranchRef(branch);
+    const result = await runCommand("git", ["ls-remote", "--exit-code", "--heads", "origin", normalizedRef], { cwd: worktreePath });
     if (result.exitCode !== 0)
         return null;
-    const sha = result.stdout.trim().split(/\s+/)[0];
-    return sha && sha.length > 0 ? sha : null;
+    return parseLsRemoteHeadSha(result.stdout, normalizedRef);
+}
+/**
+ * Repeatedly resolve the authoritative origin tip until it either satisfies
+ * finalization or the bounded retry budget is exhausted. Stops early (no further
+ * lookups) when the origin tip matches the worker HEAD, or when the branch exists
+ * and the worker HEAD is unavailable (degraded telemetry, existence-only). Retries
+ * when the tip is `null` (branch not yet visible) or, with a known HEAD, does not
+ * yet match. Returns the LAST authoritative observation — the caller decides
+ * loud-failure from that final value, so true negatives are preserved.
+ */
+async function resolveOriginBranchShaForFinalization(runCommand, worktreePath, branch, trimmedHeadSha, attempts, retryDelayMs, sleep) {
+    const total = Math.max(1, attempts);
+    let remoteSha = null;
+    for (let attempt = 0; attempt < total; attempt++) {
+        remoteSha = await resolveOriginBranchSha(runCommand, worktreePath, branch);
+        if (remoteSha !== null) {
+            // Existence-only success when HEAD is unknown; exact-match success otherwise.
+            if (!trimmedHeadSha || remoteSha === trimmedHeadSha)
+                return remoteSha;
+        }
+        if (attempt < total - 1)
+            await sleep(retryDelayMs);
+    }
+    return remoteSha;
 }
 function missingBranchAndPrFailure(job, detail) {
     const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
@@ -64,9 +139,21 @@ export async function validateWorkerFinalization(input) {
             failure: missingBranchAndPrFailure(job, "produced no PR URL and no expected branch to verify on origin"),
         };
     }
+    // Recovery/resume jobs fetch `origin/<branch>` before the worker even starts,
+    // so the ref merely existing is not proof this session's commit landed. When
+    // the worker's own HEAD is known, require the authoritative origin tip to match
+    // it exactly — a stale pre-existing branch (this session's push never happened)
+    // fails loud instead of passing. When HEAD is unresolved (degraded telemetry),
+    // fall back to the existence-only check rather than inventing a new failure
+    // mode. The authoritative lookup is retried a few times so a push that settles
+    // just after the worker exits still finalizes (BAPI-566 Bug A).
+    const trimmedHeadSha = typeof headSha === "string" ? headSha.trim().toLowerCase() : "";
+    const attempts = normalizeAttempts(input.originResolveAttempts);
+    const retryDelayMs = normalizeRetryDelay(input.originResolveRetryDelayMs);
+    const sleep = input.sleep ?? sleepMs;
     let remoteSha;
     try {
-        remoteSha = await resolveOriginBranchSha(runCommand, worktreePath, trimmedBranch);
+        remoteSha = await resolveOriginBranchShaForFinalization(runCommand, worktreePath, trimmedBranch, trimmedHeadSha, attempts, retryDelayMs, sleep);
     }
     catch (err) {
         return {
@@ -80,13 +167,6 @@ export async function validateWorkerFinalization(input) {
             failure: missingBranchAndPrFailure(job, `produced no PR URL and branch '${trimmedBranch}' is not on origin`),
         };
     }
-    // Recovery/resume jobs fetch `origin/<branch>` before the worker even starts,
-    // so the ref merely existing is not proof this session's commit landed. When
-    // the worker's own HEAD is known, require the origin tip to match it exactly —
-    // a stale pre-existing branch (this session's push never happened) fails loud
-    // instead of passing. When HEAD is unresolved (degraded telemetry), fall back
-    // to the existence-only check rather than inventing a new failure mode.
-    const trimmedHeadSha = typeof headSha === "string" ? headSha.trim() : "";
     if (trimmedHeadSha && remoteSha !== trimmedHeadSha) {
         return {
             ok: false,