@henryqw/pi-pr 2.0.1 → 2.0.3

package/README.md

@@ -1,11 +1,6 @@
 # `@henryqw/pi-pr`
 
-Show the current branch pull request in the Pi footer and use `/pr` to run its next safe step.
-
-## Why
-
-- **Created for**: Check pull-request progress without repeated `gh` commands.
-- **Advantage**: See the current pull request and its next step in one place.
+See the current branch pull request in the Pi footer. Use `/pr` to run its next safe step. It shows CI, review, merge, and lifecycle status without repeated `gh` commands.
 
 ## Install
 
@@ -17,24 +12,22 @@ Requires an authenticated GitHub CLI session (`gh auth login`) and a checkout on
 
 The comment sweep resolves its bundled helper and references from the installed package skill path. It does not require an external `jq` executable.
 
-## With
+## Works with
 
-[`@henryqw/pi-footer`](https://pi.henry.wang/extensions/pi-footer) improves this package by showing its pull-request status in the footer.
+**Improves.** [`@henryqw/pi-footer`](https://pi.henry.wang/extensions/pi-footer) shows current-branch pull-request status in the footer.
 
 ## Use
 
-Run `/pr` in a GitHub checkout. Pi opens the current branch pull request when one exists.
-
-If none exists, Pi starts the bundled creation workflow instead.
+Run `/pr` without arguments in a GitHub checkout. It reads the current branch pull request and local state, then runs one route.
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
 | Footer | ui | Show a linked `PR #number` and one plain-language status. |
 | Widget hint | ui | Show at most one hint for the next `/pr` step. |
 
-Footer statuses include `N unresolved`, `draft`, `open`, `approved`, `CI running`, `CI failed`, `changes requested`, `base update required`, `merge conflict`, `merge-ready`, `merged`, and `closed`. Colors support the text; they do not carry meaning alone.
+## Flow
 
-Use `/pr` without arguments. It reads the current branch pull request and local state, then runs one route.
+Each footer entry is one linked `PR #number` plus one plain-language status: `N unresolved`, `draft`, `open`, `approved`, `CI running`, `CI failed`, `changes requested`, `base update required`, `merge conflict`, `merge-ready`, `merged`, or `closed`. Colors support the text; they do not carry meaning alone.
 
 ![Flowchart showing /pr reading fresh GitHub and local state, choosing the first matching condition, and stopping after one route](./docs/pr-routing.svg)
 
@@ -43,7 +36,7 @@ Use `/pr` without arguments. It reads the current branch pull request and local
 | Current condition | `/pr` route |
 | --- | --- |
 | No current-branch pull request, including no upstream push target | Start pull-request creation. |
-| Base update required or merge conflict | Update from the exact base when the tree is clean and local HEAD equals the PR head. |
+| Base update required or merge conflict | Update from the base branch's current target when the tree is clean and local HEAD equals the PR head. |
 | Changes requested or unresolved review threads | Run the package comment sweep when the same local prerequisite holds. |
 | CI failed | Run the CI fix workflow when the same local prerequisite holds. |
 | No-action state | Report the state without taking action. |
@@ -70,7 +63,11 @@ Ordinary conversation comments do not trigger a route or block a merge. Changes
 
 ## Refresh
 
-The footer and widget load at session start. They refresh after local commits, PR creation, and pushes, and poll every 30 seconds. Polling updates presentation only and may be stale. The create hint stays hidden until the local branch has a commit beyond its creation point. Presentation uses route priority, so draft appears before running CI. `/pr` reads fresh state before routing or merging. The command is authoritative for actions.
+The footer and widget load at session start. They refresh after local commits, PR creation, pushes, and each dispatched workflow settles. They also poll every 30 seconds. Polling updates presentation only and may be stale.
+
+The create hint stays hidden until the local branch has a commit beyond its creation point. Any displayed hint clears as soon as `/pr` starts. A dispatched workflow keeps it hidden until the agent settles. A direct merge, no-action route, or failed command refreshes the hint when the handler finishes.
+
+Presentation uses route priority, so draft appears before running CI. `/pr` reads fresh state before routing or merging. The command is authoritative for actions.
 
 ## Safety limits
 
@@ -85,6 +82,7 @@ The footer and widget load at session start. They refresh after local commits, P
 - Applicable ruleset restrictions intersect repository-wide merge methods. An empty intersection stops the workflow.
 - Before merge, `/pr` fetches the exact head OID from the validated push URL without shared fetch state.
 - A merge, rebase, cherry-pick, revert, or sequencer state blocks direct merge, even when `git status` is empty.
+- A branch update resolves the base repository ref directly. It stops if that ref moves before merge or push.
 - Before a comment-sweep push, it revalidates the configured destination, full PR identity, and local HEAD. It pushes the captured OID.
 - An already-published local HEAD needs no second push.
 - Direct merge requires final confirmation and a fresh readiness check.

package/extensions/pr-command.ts

@@ -1,7 +1,6 @@
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
-	RegisteredCommand,
 } from "@earendil-works/pi-coding-agent";
 import {
 	executeGitHubMerge,
@@ -26,7 +25,7 @@ const WORKFLOWS: Record<WorkflowNextStep, string> = {
 };
 
 type PrCommandPi = Pick<ExtensionAPI, "exec" | "getCommands" | "sendUserMessage">;
-export type PrCommandHandler = RegisteredCommand["handler"];
+export type PrCommandHandler = (args: string, ctx: ExtensionCommandContext) => Promise<NextStep>;
 
 function dispatchWorkflow(pi: PrCommandPi, ctx: ExtensionCommandContext, commandName: string): void {
 	const command = pi.getCommands().find((candidate) =>
@@ -141,14 +140,15 @@ export function createPrCommandHandler(pi: PrCommandPi): PrCommandHandler {
 				const notification = noActionNotification(current);
 				ctx.ui.notify(notification.message, notification.type);
 			}
-			return;
+			return nextStep;
 		}
 		if (nextStep === "merge") {
 			if (!current) throw new Error("/pr merge failed: pull request is unavailable");
 			await mergePullRequest(pi, ctx, current);
-			return;
+			return nextStep;
 		}
 
 		dispatchWorkflow(pi, ctx, WORKFLOWS[nextStep]);
+		return nextStep;
 	};
 }

package/extensions/pr-github.ts

@@ -18,6 +18,7 @@ const PR_LIST_LIMIT = 100;
 const PR_SEARCH_CAP = 1_000;
 const PR_FIELDS = "id,number,url,state,isDraft,baseRefName,baseRefOid,headRefName,headRefOid,headRepository,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup";
 const REVIEW_THREADS_QUERY = "query($id:ID!,$endCursor:String){node(id:$id){...on PullRequest{reviewThreads(first:100,after:$endCursor){nodes{isResolved}pageInfo{hasNextPage endCursor}}}}}";
+const BASE_REF_QUERY = "query($owner:String!,$name:String!,$qualifiedName:String!){repository(owner:$owner,name:$name){nameWithOwner ref(qualifiedName:$qualifiedName){name target{oid}}}}";
 const BASE_BRANCH_POLICY_QUERY = "query($owner:String!,$name:String!,$qualifiedName:String!){repository(owner:$owner,name:$name){nameWithOwner ref(qualifiedName:$qualifiedName){name branchProtectionRule{requiresStrictStatusChecks}}}}";
 const OID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
 const FAILED_CHECK_STATES = new Set([
@@ -609,6 +610,25 @@ function parseUnresolvedReviewThreads(output: string): number {
 	return total;
 }
 
+function parseBaseRefOid(output: string, candidate: ListedPullRequest): string {
+	const value = parseJson(output, "Read base ref");
+	if (!isRecord(value)) fail("Read base ref", "invalid GitHub CLI output");
+	if (value.errors !== undefined) {
+		if (!Array.isArray(value.errors)) fail("Read base ref", "invalid GitHub CLI output");
+		if (value.errors.length) fail("Read base ref", "GitHub GraphQL returned errors");
+	}
+	const repository = isRecord(value.data) ? value.data.repository : undefined;
+	if (!isRecord(repository) || !isRecord(repository.ref) || !isRecord(repository.ref.target)) {
+		fail("Read base ref", "invalid GitHub CLI output");
+	}
+	if (
+		normalizeRepository(repositoryName(repository.nameWithOwner, "Read base ref", "repository")) !==
+		normalizeRepository(candidate.base.repository) ||
+		text(repository.ref.name, "Read base ref", "ref") !== candidate.base.ref
+	) fail("Read base ref", "response does not match pull request base");
+	return oid(repository.ref.target.oid, "Read base ref", "target OID");
+}
+
 function parseLegacyBaseBranchPolicy(output: string, candidate: ListedPullRequest): boolean {
 	const value = parseJson(output, "Read base branch policy");
 	if (!isRecord(value)) fail("Read base branch policy", "invalid GitHub CLI output");
@@ -810,6 +830,29 @@ async function readUnresolvedReviewThreads(
 	return parseUnresolvedReviewThreads(result.stdout);
 }
 
+async function readBaseRefOid(
+	pi: Pick<ExtensionAPI, "exec">,
+	context: PullRequestLoadContext,
+	candidate: ListedPullRequest,
+): Promise<string> {
+	const [owner, name] = candidate.base.repository.split("/");
+	const result = await execute(pi, context, "Read base ref", "gh", [
+		"api",
+		"graphql",
+		"--hostname",
+		candidate.url.hostname,
+		"-f",
+		`query=${BASE_REF_QUERY}`,
+		"-F",
+		`owner=${owner}`,
+		"-F",
+		`name=${name}`,
+		"-F",
+		`qualifiedName=refs/heads/${candidate.base.ref}`,
+	]);
+	return parseBaseRefOid(result.stdout, candidate);
+}
+
 async function readLegacyBaseBranchPolicy(
 	pi: Pick<ExtensionAPI, "exec">,
 	context: PullRequestLoadContext,
@@ -877,7 +920,6 @@ export async function loadCurrentPullRequest(
 ): Promise<CurrentPullRequest | null> {
 	const pushTarget = await readPushTarget(pi, context);
 	if (pushTarget === null) return null;
-	const [headOwner] = pushTarget.repository.nameWithOwner.split("/");
 	const search = await execute(pi, context, "Find pull requests", "gh", [
 		"api",
 		"search/issues",
@@ -888,7 +930,7 @@ export async function loadCurrentPullRequest(
 		"-X",
 		"GET",
 		"-f",
-		`q=is:pr head:${headOwner}:${pushTarget.ref}`,
+		`q=is:pr head:${pushTarget.ref}${pushTarget.remoteHeadOid === null ? "" : ` ${pushTarget.remoteHeadOid}`}`,
 		"-f",
 		`per_page=${PR_LIST_LIMIT}`,
 	]);
@@ -914,6 +956,9 @@ export async function loadCurrentPullRequest(
 	const unresolvedThreads = candidate.lifecycle === "open"
 		? await readUnresolvedReviewThreads(pi, context, candidate)
 		: 0;
+	const liveBaseOid = candidate.lifecycle === "open"
+		? await readBaseRefOid(pi, context, candidate)
+		: null;
 	const rulesetPolicy = candidate.lifecycle === "open"
 		? await readRulesetBaseBranchPolicy(pi, context, candidate)
 		: null;
@@ -945,7 +990,7 @@ export async function loadCurrentPullRequest(
 		lifecycle: candidate.lifecycle,
 		conditions: pullRequestConditions,
 		local,
-		base: candidate.base,
+		base: liveBaseOid ? { ...candidate.base, oid: liveBaseOid } : candidate.base,
 		head: candidate.head,
 		headFetchSource: pushTarget.fetchSource,
 		merge,

package/extensions/pr.ts

@@ -34,10 +34,14 @@ export default function pullRequestExtension(
 	const detectLocalCommit = dependencies.hasLocalCommit ?? hasLocalCommit;
 	const createCommandHandler = dependencies.createPrCommandHandler ?? createPrCommandHandler;
 	let context: ExtensionContext | undefined;
+	let sessionGeneration = 0;
 	let timer: ReturnType<typeof setInterval> | undefined;
 	let active: AbortController | undefined;
 	let queued = false;
 	let refreshFailureReported = false;
+	let displayedWidget: string | undefined;
+	let commandGeneration = 0;
+	const activeInvocations = new Map<number, "routing" | "workflow">();
 
 	const render = (
 		ctx: ExtensionContext,
@@ -49,15 +53,20 @@ export default function pullRequestExtension(
 		if (pullRequest !== null && footer === undefined) {
 			throw new Error("Current pull request display is missing a footer");
 		}
-		const widget = formatPrWidget(display);
+		displayedWidget = formatPrWidget(display);
+		const widget = activeInvocations.size > 0 ? undefined : displayedWidget;
 		ctx.ui.setStatus(UI_KEY, footer);
 		ctx.ui.setWidget(UI_KEY, widget === undefined ? undefined : [widget]);
 	};
 
 	const stop = (): void => {
+		sessionGeneration += 1;
 		context = undefined;
 		queued = false;
 		refreshFailureReported = false;
+		displayedWidget = undefined;
+		commandGeneration = 0;
+		activeInvocations.clear();
 		if (timer !== undefined) clearInterval(timer);
 		timer = undefined;
 		active?.abort();
@@ -79,6 +88,7 @@ export default function pullRequestExtension(
 	const refresh = async (): Promise<void> => {
 		const ctx = context;
 		if (!ctx) return;
+		const generation = sessionGeneration;
 		if (active) {
 			queued = true;
 			return;
@@ -92,13 +102,14 @@ export default function pullRequestExtension(
 			let localCommit = false;
 			try {
 				pullRequest = await load(pi, loadContext);
+				if (controller.signal.aborted || sessionGeneration !== generation) return;
 				if (pullRequest === null) localCommit = await detectLocalCommit(pi, loadContext);
 			} catch (error) {
 				// Keep the last known display when lookup is unavailable.
-				if (!controller.signal.aborted && context === ctx) reportRefreshFailure(error);
+				if (!controller.signal.aborted && sessionGeneration === generation) reportRefreshFailure(error);
 				return;
 			}
-			if (controller.signal.aborted || context !== ctx) return;
+			if (controller.signal.aborted || sessionGeneration !== generation) return;
 			render(ctx, pullRequest, localCommit);
 			refreshFailureReported = false;
 		} finally {
@@ -115,16 +126,36 @@ export default function pullRequestExtension(
 		void refresh().catch(reportRefreshFailure);
 	};
 
+	const cancelRefresh = (): void => {
+		active?.abort();
+		active = undefined;
+		queued = false;
+	};
+
 	pi.on("session_start", async (_event, ctx) => {
 		stop();
+		const generation = sessionGeneration;
 		if (!ctx.hasUI) return;
 		context = ctx;
 		await refresh();
-		if (context === ctx) timer = setInterval(refreshInBackground, POLL_INTERVAL_MS);
+		if (sessionGeneration === generation) timer = setInterval(refreshInBackground, POLL_INTERVAL_MS);
 	});
 
 	pi.on("session_shutdown", stop);
 
+	pi.on("agent_settled", async (_event, ctx) => {
+		if (!ctx.hasUI || !ctx.isIdle() || !context) return;
+		let workflowSettled = false;
+		for (const [invocation, phase] of activeInvocations) {
+			if (phase !== "workflow") continue;
+			activeInvocations.delete(invocation);
+			workflowSettled = true;
+		}
+		if (!workflowSettled) return;
+		cancelRefresh();
+		await refresh().catch(reportRefreshFailure);
+	});
+
 	pi.on("tool_result", async (event, ctx) => {
 		if (!ctx.hasUI || event.isError || !isBashToolResult(event)) return;
 		const command = event.input.command;
@@ -137,10 +168,33 @@ export default function pullRequestExtension(
 	pi.registerCommand("pr", {
 		description: "Run the current branch pull request next step",
 		handler: async (args, ctx) => {
-			if (!ctx.hasUI) return;
+			if (!ctx.hasUI || !context) return;
+			const generation = sessionGeneration;
+			const invocation = ++commandGeneration;
+			activeInvocations.set(invocation, "routing");
+			if (displayedWidget !== undefined) ctx.ui.setWidget(UI_KEY, undefined);
+			let nextStep: Awaited<ReturnType<typeof commandHandler>>;
 			try {
-				await commandHandler(args, ctx);
-			} finally {
+				nextStep = await commandHandler(args, ctx);
+			} catch (error) {
+				if (sessionGeneration === generation) {
+					cancelRefresh();
+					activeInvocations.delete(invocation);
+					if (!activeInvocations.size) {
+						ctx.ui.setWidget(UI_KEY, displayedWidget === undefined ? undefined : [displayedWidget]);
+					}
+					refreshInBackground();
+				}
+				throw error;
+			}
+			if (sessionGeneration !== generation) return;
+			cancelRefresh();
+			if (nextStep !== "none" && nextStep !== "merge") {
+				activeInvocations.set(invocation, "workflow");
+				if (nextStep === "create") ctx.ui.setStatus(UI_KEY, undefined);
+				ctx.ui.setWidget(UI_KEY, undefined);
+			} else {
+				activeInvocations.delete(invocation);
 				refreshInBackground();
 			}
 		},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-pr",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Run /pr to automatically choose the current pull request's next safe lifecycle step: create, update, address feedback, fix CI, or merge when ready.",
   "keywords": [
     "pi-package",

package/skills/pi-pr-comment-sweep/scripts/pr-feedback.mjs

@@ -383,10 +383,9 @@ function candidatePrUrls(pages, hostname) {
 
 function discoverOpenPr(localHead) {
   const push = configuredPushTarget();
-  const [owner] = push.repository.split("/", 2);
   const response = readJsonValueCommand("gh", [
     "api", "search/issues", "--hostname", push.hostname, "--paginate", "--slurp", "-X", "GET",
-    "-f", `q=is:pr is:open head:${owner}:${push.ref}`,
+    "-f", `q=is:pr is:open head:${push.ref} ${localHead}`,
     "-f", `per_page=${PR_LIST_LIMIT}`,
   ]);
   const candidates = candidatePrUrls(response, push.hostname).map((url) => {
@@ -1151,7 +1150,7 @@ if [ "$*" = "repo view ${enterpriseHost}/Owner/Repo --json nameWithOwner,url" ];
   echo '{"nameWithOwner":"Owner/Repo","url":"https://${enterpriseHost}/Owner/Repo"}'
   exit 0
 fi
-if [ "$*" = "api search/issues --hostname ${enterpriseHost} --paginate --slurp -X GET -f q=is:pr is:open head:Owner:feature/pr -f per_page=100" ]; then
+if [ "$*" = "api search/issues --hostname ${enterpriseHost} --paginate --slurp -X GET -f q=is:pr is:open head:feature/pr ${discoveryMetadata.headRefOid} -f per_page=100" ]; then
   echo '[{"total_count":1,"incomplete_results":false,"items":[{"html_url":"https://${enterpriseHost}/Upstream/Project/pull/1"}]}]'
   exit 0
 fi
@@ -1198,7 +1197,7 @@ exit 1
     const discoveryCommands = readFileSync(discoveryCalls, "utf8").trim().split("\n");
     assert.equal(discoveryCommands[0], `repo view ${enterpriseHost}/Owner/Repo --json nameWithOwner,url`);
     assert(!discoveryCommands.some((command) => command.includes("account") || command.includes("secret")));
-    assert.equal(discoveryCommands[1], `api search/issues --hostname ${enterpriseHost} --paginate --slurp -X GET -f q=is:pr is:open head:Owner:feature/pr -f per_page=100`);
+    assert.equal(discoveryCommands[1], `api search/issues --hostname ${enterpriseHost} --paginate --slurp -X GET -f q=is:pr is:open head:feature/pr ${discoveryMetadata.headRefOid} -f per_page=100`);
     assert.match(discoveryCommands[2], new RegExp(`^pr view https://${enterpriseHost}/Upstream/Project/pull/1 `));
     assert(!discoveryCommands.some((command) => command.startsWith("pr view --json")));
 
@@ -1215,7 +1214,7 @@ if [ "$*" = "repo view ${enterpriseHost}/Owner/Repo --json nameWithOwner,url" ];
   echo '{"nameWithOwner":"Owner/Repo","url":"https://${enterpriseHost}/Owner/Repo"}'
   exit 0
 fi
-if [ "$*" = "api search/issues --hostname ${enterpriseHost} --paginate --slurp -X GET -f q=is:pr is:open head:Owner:feature/pr -f per_page=100" ]; then
+if [ "$*" = "api search/issues --hostname ${enterpriseHost} --paginate --slurp -X GET -f q=is:pr is:open head:feature/pr ${discoveryMetadata.headRefOid} -f per_page=100" ]; then
   echo '[{"total_count":1,"incomplete_results":false,"items":[{"html_url":"https://${enterpriseHost}/Owner/Repo/pull/1"}]}]'
   exit 0
 fi
@@ -1277,7 +1276,7 @@ exit 1
     assert.equal(readFileSync(resolved, "utf8"), "first\n");
     const resolutionCommands = readFileSync(resolutionCalls, "utf8").trim().split("\n");
     assert.equal(resolutionCommands[0], `repo view ${enterpriseHost}/Owner/Repo --json nameWithOwner,url`);
-    assert.equal(resolutionCommands[1], `api search/issues --hostname ${enterpriseHost} --paginate --slurp -X GET -f q=is:pr is:open head:Owner:feature/pr -f per_page=100`);
+    assert.equal(resolutionCommands[1], `api search/issues --hostname ${enterpriseHost} --paginate --slurp -X GET -f q=is:pr is:open head:feature/pr ${discoveryMetadata.headRefOid} -f per_page=100`);
     assert.match(resolutionCommands[2], new RegExp(`^pr view https://${enterpriseHost}/Owner/Repo/pull/1 `));
     assert(!resolutionCommands.some((command) => command.startsWith("pr view --json")));
 

package/skills/pi-pr-update-branch/SKILL.md

@@ -13,8 +13,9 @@ Before changing anything:
 
 1. Require an attached branch and a clean tree. Save `git symbolic-ref --quiet --short HEAD` as `LOCAL_BRANCH`; it is checkout identity only. Inspect `git status --porcelain=v1 --untracked-files=all` and stop for any staged, unstaged, untracked, unresolved, or in-progress operation. Never commit, clean, stash, or hide a dirty tree.
 2. Read `LOCAL_BRANCH`'s validated `%(push:short)` with `git for-each-ref` and enumerate configured remote names. Match an exact `<remote>/` prefix, choosing the unique longest match so remote names containing `/` work. Save that remote and the remaining ref as `PUSH_REMOTE` and `PUSH_REF`, then validate `PUSH_REF` with `git check-ref-format --branch`. Require one push URL and validate its GitHub host and owner/repository. Do not use `%(push:remoteref)` or fall back to `LOCAL_BRANCH`.
-3. Set `PR_FIELDS=number,url,state,baseRefName,baseRefOid,headRepository,headRefName,headRefOid,mergeStateStatus,mergeable`. On the push target's host, search open pull requests by the exact push owner and `PUSH_REF`. Inspect every candidate by its URL with exactly `PR_FIELDS`; stop for incomplete, capped, duplicate, or ambiguous results. Never use branch-default `gh pr view` or retry with `LOCAL_BRANCH`.
-4. Require exactly one open PR. Require its HTTPS URL to be exactly `HOST/OWNER/REPOSITORY/pull/NUMBER`, with no credentials, port, query, or fragment, and require its number to match. The URL gives the base host and repository. Require `headRepository.nameWithOwner` and `headRefName` to match the recorded push repository and `PUSH_REF`. Require local `HEAD` to equal `headRefOid`. Record the PR and its base/head repositories, refs, and full OIDs. Set `EXPECTED_HEAD_SHA` and `BASE_SHA` from the initial head and base OIDs; never replace them. A fork head and upstream base are normal.
+3. Set `PR_FIELDS=number,url,state,baseRefName,headRepository,headRefName,headRefOid,mergeStateStatus,mergeable`. On the push target's host, search open pull requests by the exact push owner and `PUSH_REF`. Inspect every candidate by its URL with exactly `PR_FIELDS`; stop for incomplete, capped, duplicate, or ambiguous results. Never use branch-default `gh pr view` or retry with `LOCAL_BRANCH`.
+4. Require exactly one open PR. Require its HTTPS URL to be exactly `HOST/OWNER/REPOSITORY/pull/NUMBER`, with no credentials, port, query, or fragment, and require its number to match. The URL gives the base host and repository. Require `headRepository.nameWithOwner` and `headRefName` to match the recorded push repository and `PUSH_REF`. Require local `HEAD` to equal `headRefOid`. Record the PR and its base/head repositories and refs. Set `EXPECTED_HEAD_SHA` from the initial head OID; never replace it. A fork head and upstream base are normal.
+5. Validate `refs/heads/<BASE_REF>` with `git check-ref-format`, then split the validated base repository into its exact owner and name. Query `repository.ref(qualifiedName: "refs/heads/<BASE_REF>") { name target { oid } }` with `gh api graphql --hostname "$PR_HOST"`. Require no GraphQL errors, the exact recorded repository and ref, and one full hexadecimal target OID. Record that target as `BASE_SHA`; never replace it. Do not read `baseRefOid`, REST `pull.base.sha`, a local remote-tracking ref, or `git ls-remote` as a substitute.
 
 ## Fetch, pin, and merge
 
@@ -48,7 +49,7 @@ printf 'Fetched base %s %s at %s\n' "$BASE_REPOSITORY" "$BASE_REF" "$BASE_SHA"
 
 If protocol lookup, API lookup, URL validation, fetch, or object verification fails, stop. The HTTPS helper is command-local and receives credentials only through Git's credential protocol. Never print a token, run `gh auth setup-git`, or change persistent Git config. The recorded `BASE_SHA` is authoritative for this run. Do not fall back to another URL, ref, protocol, or credential source.
 
-Before merging, require the attached branch to remain `LOCAL_BRANCH` and the tree to remain clean. Re-resolve its configured push target exactly as above and require the saved remote, `PUSH_REF`, sole push URL, host, and repository. Re-read the PR by its recorded URL with exactly `PR_FIELDS`; require its number, URL, open state, base repository/ref/OID, head repository, `PUSH_REF`, and head OID to remain unchanged. Immediately before merging, require local `HEAD` to equal `EXPECTED_HEAD_SHA`:
+Before merging, require the attached branch to remain `LOCAL_BRANCH` and the tree to remain clean. Re-resolve its configured push target exactly as above and require the saved remote, `PUSH_REF`, sole push URL, host, and repository. Re-read the PR by its recorded URL with exactly `PR_FIELDS`; require its number, URL, open state, base repository/ref, head repository, `PUSH_REF`, and head OID to remain unchanged. Re-run the exact live base-ref GraphQL query and require its repository, ref, and target OID to match the recorded values and `BASE_SHA`. Immediately before merging, require local `HEAD` to equal `EXPECTED_HEAD_SHA`:
 
 ```bash
 LOCAL_HEAD="$(git rev-parse --verify HEAD)"
@@ -106,7 +107,7 @@ After the merge completes:
    ```
 
    Stop on either failure. Record the validated full local `HEAD` as `MERGED_HEAD`. Do not substitute a newer ref or another SHA.
-3. Immediately before the single push, repeat the complete branch, configured push target, sole push URL, and recorded-URL PR guard used before merging. Require all saved identities and PR fields to remain exact, the tree to be clean, and local `HEAD` to equal `MERGED_HEAD`. Stop on any change.
+3. Immediately before the single push, repeat the complete branch, configured push target, sole push URL, recorded-URL PR guard, and live base-ref GraphQL query used before merging. Require all saved identities and PR fields to remain exact, the live base target to remain `BASE_SHA`, the tree to be clean, and local `HEAD` to equal `MERGED_HEAD`. Stop on any change.
 4. Push once to the saved configured push ref, without force or retry:
 
    ```bash