@bridge_gpt/mcp-server 0.2.62 → 0.2.66

package/build/executor/watch-cli.js

@@ -3,7 +3,13 @@
  *
  * Ad-hoc, READ-ONLY attachment to a running (or recently-run) job's worker log:
  * it resolves the local job-log registry record, verifies the log file exists,
- * and `tail -f`s it with inherited stdio. It NEVER sends a signal to the worker
+ * and `tail -f`s it with inherited stdio.
+ *
+ * BAPI-1330: each attempt has its own stable log file. The newest attempt is
+ * watched by default and `--attempt <n>` selects an earlier one. A reference the
+ * registry cannot vouch for — a legacy fixed-alias record, an unknown attempt,
+ * a transcript that was never recorded — is reported by its named reason; the
+ * watch never follows a guessed or shared file. It NEVER sends a signal to the worker
  * process and never owns the execution lifecycle — closing the watch leaves the
  * worker untouched. Missing registry records or missing log files fail loud with
  * actionable stderr text and a non-zero exit code.
@@ -15,7 +21,7 @@ import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { readExecutorJobLogRecord, } from "./job-log-registry.js";
 export function getExecutorWatchUsage() {
     return [
-        "Usage: mcp-server executor watch <job-id>",
+        "Usage: mcp-server executor watch <job-id> [--attempt <n>]",
         "",
         "Attach read-only to a running (or recently-run) executor job's worker log",
         "via `tail -f`. Closing the watch never affects the worker process.",
@@ -24,15 +30,32 @@ export function getExecutorWatchUsage() {
         "  <job-id>        Numeric executor job id to watch.",
         "",
         "Options:",
+        "  --attempt <n>   Watch that attempt's log instead of the newest one.",
         "  -h, --help      Show this help.",
     ].join("\n");
 }
-/** Accept EXACTLY one numeric job id; reject missing/non-numeric/extra args. */
+/**
+ * Accept EXACTLY one numeric job id plus an optional `--attempt <n>` (or
+ * `--attempt=<n>`); reject missing/non-numeric/extra args.
+ */
 export function parseExecutorWatchArgs(argv) {
     const positionals = [];
-    for (const arg of argv) {
+    let attemptRaw;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
         if (arg === "-h" || arg === "--help")
             return { kind: "help" };
+        if (arg === "--attempt" || arg.startsWith("--attempt=")) {
+            if (attemptRaw !== undefined) {
+                return { kind: "error", message: "--attempt may be given only once" };
+            }
+            const value = arg === "--attempt" ? argv[++i] : arg.slice("--attempt=".length);
+            if (value === undefined || !/^[0-9]+$/.test(value)) {
+                return { kind: "error", message: "--attempt requires a non-negative attempt number" };
+            }
+            attemptRaw = value;
+            continue;
+        }
         if (arg.startsWith("-"))
             return { kind: "error", message: `unknown argument: ${arg}` };
         positionals.push(arg);
@@ -47,7 +70,9 @@ export function parseExecutorWatchArgs(argv) {
     if (!/^[0-9]+$/.test(raw)) {
         return { kind: "error", message: `job id must be numeric: '${raw}'` };
     }
-    return { kind: "ok", jobId: Number(raw) };
+    return attemptRaw === undefined
+        ? { kind: "ok", jobId: Number(raw) }
+        : { kind: "ok", jobId: Number(raw), attempt: Number(attemptRaw) };
 }
 /**
  * Spawn `tail -f <log_path>` with inherited stdio for interactive CLI attachment.
@@ -98,14 +123,16 @@ export async function runExecutorWatchCli(argv, overrides = {}) {
     }
     const registryDeps = overrides.registryDeps ?? createDefaultWatchRegistryDeps();
     const readRecord = overrides.readRecord ?? readExecutorJobLogRecord;
-    const record = await readRecord(parsed.jobId, registryDeps);
+    const selector = parsed.attempt === undefined ? {} : { attempt: parsed.attempt };
+    const record = await readRecord(parsed.jobId, registryDeps, selector);
     if (!record.ok) {
-        errorLog(`Error: no worker log registered for job ${parsed.jobId}: ${record.reason}`);
+        errorLog(`Error: worker log for job ${parsed.jobId} is unavailable (${record.code}): ${record.reason}`);
         return 1;
     }
     const logExists = overrides.logExists ?? defaultLogExists;
     if (!(await logExists(record.record.log_path))) {
-        errorLog(`Error: worker log for job ${parsed.jobId} is missing at ${record.record.log_path}`);
+        errorLog(`Error: worker log for job ${parsed.jobId} attempt ${record.record.attempt} is unavailable ` +
+            `(log_file_missing): expected at ${record.record.log_path}`);
         return 1;
     }
     const spawnTail = overrides.spawnTail ?? ((logPath) => spawnTailFollow(logPath));

package/build/executor/worker-command.js

@@ -17,13 +17,19 @@
  * distinct from the argv vocabulary is what stops a future flag rename in one
  * agent's CLI from becoming an operator-visible policy break across all of them.
  */
-import { ExecutorNamedError } from "./job-errors.js";
-import { isRecoveryJobType } from "./job-types.js";
+import { CiFixContext, ExecutorNamedError } from "./job-errors.js";
+import { isRemainingWork, validateCorrectionIntent } from "./correction-dispatch.js";
+/**
+ * BAPI-1296: `ci_fix` is the one recovery job with a FOCUSED prompt route. It
+ * renders its server-authored `payload.prompt_spec` (the dispatched failing and
+ * missing checks) in `job-runner.ts`, and is never given the full recipe.
+ */
+export const CI_FIX_JOB_TYPE = "ci_fix";
 /**
  * Resolve the worker prompt for the explicit-prompt and legacy synthesis paths.
- * Uses an explicit non-empty `payload.prompt` verbatim; otherwise, for
- * `implement` and the recovery jobs, builds the conservative
- * `/implement-ticket <ticket_key> --auto` prompt.
+ * Remaining work first requires a validated bounded correction intent. Only an
+ * initial `implement` job may synthesize `/implement-ticket <ticket_key> --auto`.
+ * `ci_fix` uses the focused prompt-spec route after pre-worktree validation.
  *
  * Structured `payload.prompt_spec` rendering is NOT done here: it needs the
  * prepared worktree/git state, so `job-runner.ts` renders it in the prepared-spawn
@@ -38,46 +44,76 @@ import { isRecoveryJobType } from "./job-types.js";
  * explicit prompt. It no longer depends on the prompt-spec fall-through.
  */
 /**
- * True for the job types that synthesize `/implement-ticket <KEY> --auto` when no
- * explicit `payload.prompt` is present: the first-pass `implement` plus the
- * recovery jobs (`remediate`/`ci_fix`/`rebase`), which re-enter the SAME
- * correction loop on the ticket's existing branch/PR. Recovery classification is
- * shared with dispatch and worktree reuse via `isRecoveryJobType` (`job-types.ts`)
- * so eligibility cannot drift. Verdict jobs (`spec_review`/`smoke`) are NOT here —
- * they carry an explicit `payload.prompt` and write a fixed-path artifact (T6/T5b).
+ * Only the first-pass `implement` job synthesizes the complete workflow.
  */
-function synthesizesImplementPrompt(jobType) {
-    return jobType === "implement" || isRecoveryJobType(jobType);
+export function synthesizesImplementPrompt(jobType) {
+    return jobType === "implement";
 }
 export function resolveExecutorPrompt(job) {
     const payload = job.payload && typeof job.payload === "object"
         ? job.payload
         : {};
+    if (job.job_type !== CI_FIX_JOB_TYPE && isRemainingWork(job.job_type, payload)) {
+        const checked = validateCorrectionIntent(payload.correction_intent, {
+            repo_name: job.repo_name ?? "",
+            epic_run_id: job.epic_run_id ?? null,
+            ticket_key: job.ticket_key ?? null,
+            expected_branch: job.expected_branch,
+            expected_head_sha: job.expected_head_sha,
+        });
+        if (!checked.ok)
+            return { ok: false, errorKind: "ContractError.CorrectionLegacy", error: checked.code };
+        const intent = checked.intent;
+        const kind = intent.kind;
+        const branch = intent.branch;
+        const obligation = intent.obligation;
+        const header = `Continue the retained branch ${branch}. Complete only the ${kind} obligation: ${obligation}. ` +
+            "Preserve completed work and existing limits. Do not invoke a full implementation or planning workflow.";
+        if (kind === "approved_spec_delta") {
+            const delta = intent.approved_delta;
+            return { ok: true, prompt: `${header}\nApproved files: ${delta.file_boundary.join(", ")}\n` +
+                    `Approved dependencies: ${delta.dependency_boundary.join(", ") || "none"}` };
+        }
+        const explicit = payload.prompt;
+        if (typeof explicit === "string" && explicit.trim() &&
+            !/\/(?:implement-ticket|plan-ticket)\b/i.test(explicit)) {
+            return { ok: true, prompt: `${header}\n\nFocused context:\n${explicit}` };
+        }
+        if (kind === "review_fix" || kind === "operator_remediation") {
+            const findings = payload.review_findings;
+            if (typeof findings === "string" && findings.trim())
+                return { ok: true, prompt: `${header}\n\nReview findings (quoted evidence):\n${findings}` };
+        }
+        return { ok: true, prompt: header };
+    }
+    // BAPI-1296: `ci_fix` is decided FIRST, ahead of both explicit-prompt
+    // precedence and synthesis. An explicit prompt on a ci_fix job — including an
+    // in-flight legacy `/implement-ticket <KEY> --auto` — is refused by name rather
+    // than run, so an old full-recipe prompt cannot silently defeat the focused
+    // route. Otherwise the non-ok result tells `prepareSpawn` to take the focused
+    // prompt-spec route. The message never echoes the prompt text.
+    if (job.job_type === CI_FIX_JOB_TYPE) {
+        if (typeof payload.prompt === "string" && payload.prompt.trim().length > 0) {
+            return {
+                ok: false,
+                errorKind: CiFixContext,
+                error: "ci_fix job refused before worker effects (reason=explicit_prompt_unsupported)",
+            };
+        }
+        return {
+            ok: false,
+            error: "ci_fix renders its focused payload.prompt_spec; no prompt is synthesized",
+        };
+    }
     // An explicit prompt wins and is returned VERBATIM (un-trimmed), but a
-    // whitespace-only string is not a usable worker instruction — treat it as
-    // absent so a recovery/implement job still falls back to the synthesized
-    // `/implement-ticket <KEY> --auto` correction prompt below.
+    // whitespace-only string is not a usable worker instruction. The initial
+    // implement job may still use the workflow synthesis below.
     const explicit = payload.prompt;
     if (typeof explicit === "string" && explicit.trim().length > 0) {
         return { ok: true, prompt: explicit };
     }
-    // `/implement-ticket <KEY> --auto` is the full correction engine, not just a
-    // first-pass implementer: its post-PR loop owns CI-failure correction, review-
-    // change addressing, and merge-conflict resolution (see .claude/commands/
-    // implement-ticket.md "Clean session exit"). So the recovery jobs that operate
-    // on the ticket's existing branch/PR — `remediate`/`ci_fix`/`rebase` — resume
-    // by RE-ENTERING THE COMPLETE RECIPE from step 1, not a distinct resume path.
-    // That re-entry is safe (BAPI-746), backed by re-entry handling already
-    // present in three of the recipe's own steps, not a new assumption: plan
-    // generation is idempotent because the server reuses a fresh existing plan
-    // instead of regenerating it (BAPI-745, `reused: true`); commit-and-push.md
-    // treats a clean tree with an already-pushed branch/PR as a legitimate
-    // re-entry rather than an empty implementation; and create-pr.md treats an
-    // already-open pull request on the head branch as satisfying its success
-    // condition. Without synthesizing this command, a code_review
-    // `changes_requested` (near-certain in real runs) enqueues a `remediate` job
-    // that fails `no usable prompt` and strands the run (BAPI-528 Milestone-A gap
-    // #3).
+    // This final synthesis route is for initial feature work only. The remaining
+    // work branch returned a focused prompt or a named refusal above.
     const ticketKey = typeof job.ticket_key === "string" && job.ticket_key.trim().length > 0
         ? job.ticket_key.trim()
         : null;

package/build/executor/worker-finalization.js

@@ -45,9 +45,20 @@
  * so an omitted body opens a PR with no description at all), and — when the
  * provider reports it — sitting at the same pushed head. Anything short of that
  * is `WorkerFinalizationPrNotAttached`, whose guidance names attachment and never
- * suggests removing or re-writing the branch: the commits ARE the completed
- * implementation, and both of the stale-worktree guard's historical remedies
- * would have destroyed them.
+ * suggests removing or re-writing the branch: the commits are durable pushed
+ * work, and both of the stale-worktree guard's historical remedies would have
+ * destroyed them.
+ *
+ * BAPI-1330: publication is not completion. A pushed head and an attached pull
+ * request prove the work was PUBLISHED; they say nothing about whether the
+ * required work is finished or whether any check passed, so no message here
+ * claims either. A clean exit that fails finalization keeps the `clean_exit`
+ * classification the process actually earned — the finalization failure rides
+ * separately as the error kind. And a COVERED attempt (one the server enrolled
+ * in the completion-evidence contract) may not use the existence-only fallback:
+ * without a full worker HEAD, a matching origin tip and a pull request that
+ * reports its head, publication is `unknown`
+ * (`WorkerFinalizationPublicationUnverified`), never `ok`.
  *
  * This check is deliberately fail-CLOSED, unlike the BAPI-586 base check it now
  * shares a lookup with. "The PR could not be verified" and "there is no PR" are
@@ -56,8 +67,20 @@
  * this ticket removes. The reconciler stays the decision-maker — the executor
  * only reports the observation (R14 rule 3).
  */
-import { ReconcileOverlapPushUnfinalized, secretFreeErrorMessage, WorkerFinalizationMissingRemoteBranchAndPr, WorkerFinalizationPrBaseMismatch, WorkerFinalizationPrNotAttached, WorkerFinalizationSavedButUnfinalized, } from "./job-errors.js";
+import { ReconcileOverlapPushUnfinalized, secretFreeErrorMessage, WorkerFinalizationMissingRemoteBranchAndPr, WorkerFinalizationPrBaseMismatch, WorkerFinalizationPrNotAttached, WorkerFinalizationPublicationUnverified, WorkerFinalizationSavedButUnfinalized, } from "./job-errors.js";
 import { isImplementationStyleJobType } from "./job-types.js";
+/** A full, lower-case 40-hex commit SHA. */
+const FULL_SHA_RE = /^[0-9a-f]{40}$/;
+/** The `runCommand` options for one bounded read; `{ cwd }` alone when unbounded. */
+function callOptions(worktreePath, bound) {
+    return bound && typeof bound.timeoutMs === "number"
+        ? { cwd: worktreePath, timeoutMs: Math.max(1, Math.floor(bound.timeoutMs)) }
+        : { cwd: worktreePath };
+}
+/** True when a bounded call has no time left and must not be issued at all. */
+function callExpired(bound) {
+    return bound !== undefined && typeof bound.timeoutMs === "number" && bound.timeoutMs <= 0;
+}
 /** 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;
@@ -113,9 +136,11 @@ function parseLsRemoteHeadSha(stdout, expectedRef) {
  * 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) {
+export async function resolveOriginBranchSha(runCommand, worktreePath, branch, bound) {
     const normalizedRef = normalizeBranchRef(branch);
-    const result = await runCommand("git", ["ls-remote", "--exit-code", "--heads", "origin", normalizedRef], { cwd: worktreePath });
+    if (callExpired(bound))
+        return null;
+    const result = await runCommand("git", ["ls-remote", "--exit-code", "--heads", "origin", normalizedRef], callOptions(worktreePath, bound));
     if (result.exitCode !== 0)
         return null;
     return parseLsRemoteHeadSha(result.stdout, normalizedRef);
@@ -129,11 +154,11 @@ export async function resolveOriginBranchSha(runCommand, worktreePath, branch) {
  * 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) {
+async function resolveOriginBranchShaForFinalization(runCommand, worktreePath, branch, trimmedHeadSha, attempts, retryDelayMs, sleep, bound) {
     const total = Math.max(1, attempts);
     let remoteSha = null;
     for (let attempt = 0; attempt < total; attempt++) {
-        remoteSha = await resolveOriginBranchSha(runCommand, worktreePath, branch);
+        remoteSha = await resolveOriginBranchSha(runCommand, worktreePath, branch, bound?.());
         if (remoteSha !== null) {
             // Existence-only success when HEAD is unknown; exact-match success otherwise.
             if (!trimmedHeadSha || remoteSha === trimmedHeadSha) {
@@ -170,14 +195,16 @@ const PR_LOOKUP_ABSENT = {
  * collapses to {@link PR_LOOKUP_ABSENT} without copying raw stderr, an
  * authenticated remote, or the command line into anything the caller can render.
  */
-async function resolvePrForFinalization(runCommand, worktreePath, branch) {
+async function resolvePrForFinalization(runCommand, worktreePath, branch, bound) {
     const args = ["pr", "view"];
     if (branch)
         args.push(branch);
     args.push("--json", PR_VIEW_JSON_FIELDS);
+    if (callExpired(bound))
+        return PR_LOOKUP_ABSENT;
     let result;
     try {
-        result = await runCommand("gh", args, { cwd: worktreePath });
+        result = await runCommand("gh", args, callOptions(worktreePath, bound));
     }
     catch {
         return PR_LOOKUP_ABSENT;
@@ -254,7 +281,7 @@ function evaluatePrBase(job, pr, expectedBase) {
  * means the provider has not yet reflected the push, not that the push is in
  * doubt.
  */
-function evaluatePrContract(pr, workerHeadSha) {
+function evaluatePrContract(pr, workerHeadSha, coveredAttempt = false) {
     if (!pr.found) {
         return {
             ok: false,
@@ -282,6 +309,17 @@ function evaluatePrContract(pr, workerHeadSha) {
             retryable: false,
         };
     }
+    if (coveredAttempt && pr.headRefOid === null) {
+        // BAPI-1330: a legacy attempt accepts a PR whose head the provider did not
+        // report; a covered one cannot, because the PR head is part of what binds
+        // the published work to this attempt's final head.
+        return {
+            ok: false,
+            detail: "its pull request reports no head commit",
+            retryable: true,
+            unverified: true,
+        };
+    }
     if (workerHeadSha && pr.headRefOid !== null && pr.headRefOid !== workerHeadSha) {
         return {
             ok: false,
@@ -303,9 +341,16 @@ function evaluatePrContract(pr, workerHeadSha) {
  *    so the executor failure and the reconciler's observation are searchable as
  *    one state instead of two vocabularies for the same thing.
  * 2. It recommends attachment and says plainly that removing or re-writing the
- *    branch destroys completed work. In the F4 incident the pushed branch WAS the
- *    finished implementation, and both remedies the stale-worktree guard offered
- *    would have thrown it away.
+ *    branch destroys pushed work. In the F4 incident the pushed branch held the
+ *    implementation, and both remedies the stale-worktree guard offered would
+ *    have thrown it away.
+ *
+ * BAPI-1330: it claims ONLY what finalization observed — durable pushed commits
+ * and an unmet pull-request attachment. Whether the required work is finished,
+ * and whether any check passed, is stated as not established here; only the
+ * completion evidence (when the attempt was covered) can speak to either. The
+ * classification is `clean_exit`, because that is how the process ended; the
+ * finalization failure is carried by the error kind, not by rewriting the exit.
  */
 function prNotAttachedFailure(job, branch, workerHeadSha, expectedBase, detail) {
     const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
@@ -314,14 +359,31 @@ function prNotAttachedFailure(job, branch, workerHeadSha, expectedBase, detail)
     return {
         error_kind: WorkerFinalizationPrNotAttached,
         error_message: `${label} exited cleanly and its HEAD${headLabel} is durable on origin branch '${branch}', ` +
-            `but ${detail}. This is the pr_not_attached state: the implementation is COMPLETE and ` +
-            `published, only its pull request is missing. Recovery: open or attach a pull request for ` +
-            `'${branch}'${baseLabel} with a non-empty description. Removing or re-writing that branch ` +
-            `would destroy finished work — the commits on it are the implementation.`,
-        classification: "crashed",
+            `but ${detail}. This is the pr_not_attached state: the commits are pushed and the pull ` +
+            `request attachment is unmet. Whether the required work is finished, and whether any ` +
+            `check passed, is not established by this observation. Recovery: open or attach a pull ` +
+            `request for '${branch}'${baseLabel} with a non-empty description. Removing or re-writing ` +
+            `that branch would destroy pushed work.`,
+        classification: "clean_exit",
         last_commit_sha: workerHeadSha || undefined,
     };
 }
+/**
+ * BAPI-1330: a covered attempt whose publication could not be PROVEN. Built only
+ * from public identifiers and a fixed detail phrase. It never says a pull request
+ * is absent, because none was observed to be — the verdict is `unknown`.
+ */
+function publicationUnverifiedFailure(job, branch, workerHeadSha, detail) {
+    const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
+    return {
+        error_kind: WorkerFinalizationPublicationUnverified,
+        error_message: `${label} exited cleanly, but publication of branch '${branch}' could not be verified: ` +
+            `${detail}. Publication, required-work completion and check status are unknown for this ` +
+            `attempt; nothing was observed to be missing and nothing on the branch was changed.`,
+        classification: "clean_exit",
+        last_commit_sha: FULL_SHA_RE.test(workerHeadSha) ? workerHeadSha : undefined,
+    };
+}
 /**
  * `detail` describes a state with NO evidence any work reached origin (branch
  * unresolved, branch absent from origin, or the origin lookup itself failed).
@@ -398,6 +460,8 @@ export async function validateWorkerFinalization(input) {
     if (!isImplementationStyleJobType(job.job_type)) {
         return { ok: true };
     }
+    // BAPI-1311: resolved fresh for every call so each read gets only the time left.
+    const bound = () => input.callTimeoutMs ? { timeoutMs: input.callTimeoutMs() } : undefined;
     const hasPrUrl = Boolean(extractPrUrl(result));
     // BAPI-762: `branch`/`headSha` are normalized once here and reused through the
     // rest of the check — including by the diagnostics below — instead of being
@@ -418,7 +482,7 @@ export async function validateWorkerFinalization(input) {
     // unconditional. Their dispositions still differ on purpose (see `PrLookup`),
     // and the ORDER is unchanged: a wrong-base PR is still reported before any
     // origin lookup, exactly as BAPI-586 specified.
-    let pr = await resolvePrForFinalization(runCommand, worktreePath, trimmedBranch);
+    let pr = await resolvePrForFinalization(runCommand, worktreePath, trimmedBranch, bound());
     // BAPI-586: a wrong-base PR (opened against a dependency's feature branch or the
     // repo default instead of the run base) never fires `claude-review.yml` and
     // strands the ticket at `code_review`. When the run base is known, fail loud on
@@ -443,12 +507,23 @@ export async function validateWorkerFinalization(input) {
     // runs unconditionally — including when `hasPrUrl` is true (BAPI-762, AC-5): a
     // PR being open is never accepted as proof this worker's own commit landed.
     const trimmedHeadSha = typeof headSha === "string" ? headSha.trim().toLowerCase() : "";
+    const covered = input.coveredAttempt === true;
+    // BAPI-1330: the existence-only fallback below is a LEGACY concession to
+    // degraded telemetry. A covered attempt cannot bind its final head to anything
+    // without the worker's full HEAD, so it stops here with an `unknown` verdict
+    // rather than accepting "the branch exists" as publication.
+    if (covered && !FULL_SHA_RE.test(trimmedHeadSha)) {
+        return {
+            ok: false,
+            failure: publicationUnverifiedFailure(job, trimmedBranch, trimmedHeadSha, "the worker's full HEAD commit could not be established"),
+        };
+    }
     const attempts = normalizeAttempts(input.originResolveAttempts);
     const retryDelayMs = normalizeRetryDelay(input.originResolveRetryDelayMs);
     const sleep = input.sleep ?? sleepMs;
     let origin;
     try {
-        origin = await resolveOriginBranchShaForFinalization(runCommand, worktreePath, trimmedBranch, trimmedHeadSha, attempts, retryDelayMs, sleep);
+        origin = await resolveOriginBranchShaForFinalization(runCommand, worktreePath, trimmedBranch, trimmedHeadSha, attempts, retryDelayMs, sleep, bound);
     }
     catch (err) {
         return {
@@ -497,16 +572,22 @@ export async function validateWorkerFinalization(input) {
     // base check fail-opened on it, and the PR that has since appeared must not
     // reach success without that check.
     if (origin.attemptsUsed > 1) {
-        pr = await resolvePrForFinalization(runCommand, worktreePath, trimmedBranch);
+        pr = await resolvePrForFinalization(runCommand, worktreePath, trimmedBranch, bound());
         const refreshedBaseVerdict = evaluatePrBase(job, pr, expectedBase);
         if (refreshedBaseVerdict)
             return { ok: false, failure: refreshedBaseVerdict };
     }
-    let contract = evaluatePrContract(pr, trimmedHeadSha);
+    let contract = evaluatePrContract(pr, trimmedHeadSha, covered);
     for (let attempt = 1; attempt < attempts && !contract.ok && contract.retryable; attempt++) {
         await sleep(retryDelayMs);
-        pr = await resolvePrForFinalization(runCommand, worktreePath, trimmedBranch);
-        contract = evaluatePrContract(pr, trimmedHeadSha);
+        pr = await resolvePrForFinalization(runCommand, worktreePath, trimmedBranch, bound());
+        contract = evaluatePrContract(pr, trimmedHeadSha, covered);
+    }
+    if (!contract.ok && contract.unverified === true) {
+        return {
+            ok: false,
+            failure: publicationUnverifiedFailure(job, trimmedBranch, trimmedHeadSha, contract.detail),
+        };
     }
     if (!contract.ok) {
         return {
@@ -514,5 +595,66 @@ export async function validateWorkerFinalization(input) {
             failure: prNotAttachedFailure(job, trimmedBranch, trimmedHeadSha, expectedBase, contract.detail),
         };
     }
-    return { ok: true, prUrl: pr.url ?? undefined, prNumber: pr.prNumber };
+    return {
+        ok: true,
+        prUrl: pr.url ?? undefined,
+        prNumber: pr.prNumber,
+        // BAPI-1311: the verified origin tip — proven equal to the worker's HEAD above
+        // whenever that HEAD was known. Only for a caller that asked for it.
+        ...(input.exposePushedHead === true ? { pushedHeadSha: remoteSha } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// BAPI-1311 — the focused rebase wait's pull-request read
+// ---------------------------------------------------------------------------
+/**
+ * The bounded public projection the focused rebase wait asks for. Separate from
+ * {@link PR_VIEW_JSON_FIELDS} on purpose: legacy finalization keeps its exact
+ * field selection, and only the rebase wait pays for state and mergeability.
+ */
+const FOCUSED_PR_VIEW_JSON_FIELDS = "number,state,headRefOid,headRefName,baseRefName,mergeable";
+/**
+ * Read the bound pull request's current state with ONE bounded `gh pr view`.
+ *
+ * Addresses the pull request by NUMBER, never by branch, so a second pull request
+ * opened for the same branch can never be mistaken for the bound one. Parses only
+ * {@link FOCUSED_PR_VIEW_JSON_FIELDS}; raw stdout/stderr never leave this
+ * function. An already-expired bound issues no command at all.
+ */
+export async function readFocusedPullRequest(runCommand, worktreePath, prNumber, bound) {
+    if (!Number.isInteger(prNumber) || prNumber <= 0 || callExpired(bound)) {
+        return { available: false };
+    }
+    let result;
+    try {
+        result = await runCommand("gh", ["pr", "view", String(prNumber), "--json", FOCUSED_PR_VIEW_JSON_FIELDS], callOptions(worktreePath, bound));
+    }
+    catch {
+        return { available: false };
+    }
+    if (result.exitCode !== 0)
+        return { available: false };
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        return { available: false };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return { available: false };
+    const obj = parsed;
+    const rawState = nonBlankString(obj.state);
+    const rawHead = nonBlankString(obj.headRefOid);
+    const rawMergeable = nonBlankString(obj.mergeable);
+    const mergeable = rawMergeable === "MERGEABLE" ? "mergeable" : rawMergeable === "CONFLICTING" ? "conflicting" : "unknown";
+    return {
+        available: true,
+        number: typeof obj.number === "number" && Number.isInteger(obj.number) ? obj.number : null,
+        state: rawState === null ? null : rawState.toUpperCase(),
+        headRefOid: rawHead === null ? null : rawHead.toLowerCase(),
+        headRefName: nonBlankString(obj.headRefName),
+        baseRefName: nonBlankString(obj.baseRefName),
+        mergeable,
+    };
 }