@henryqw/pi-pr 4.0.4 → 4.0.6

package/README.md

@@ -74,7 +74,7 @@ Each footer entry is one linked `PR #number` plus one plain-language status: `N
 | No-action state | Report the state without taking action. |
 | Merge-ready pull request | Ask for final confirmation, recheck fresh state, and squash-merge if confirmed. |
 
-`pi-pr-create` selects its base in this order: the leading `/pr --base BRANCH`, one `branch.<branch>.gh-merge-base` value, then the default branch of validated `origin`. It captures the selected base OID and merge-base. Creation requires at least one committed change ahead. Dirty work alone does not enable creation.
+`pi-pr-create` selects its base in this order: the leading `/pr --base BRANCH`, one `branch.<branch>.gh-merge-base` value, then the default branch of validated `origin`. It captures the selected base OID and merge-base. Creation requires at least one committed change ahead. Dirty work alone does not enable creation. If the current branch is the selected base, pi-pr stays silent because GitHub cannot create a pull request from a ref to itself.
 
 The base always comes from validated `origin`. The head may use that repository or a fork with the same GitHub source. Base and head must use the same GitHub host. Other fork relationships stop before mutation.
 
@@ -129,17 +129,17 @@ The sweep runs existing non-destructive checks on the clean committed `HEAD` bef
 
 ### Refresh
 
-The footer and widget load at session start. A directory outside a Git worktree stays silent and does not start polling. The UI shows `PR · status unavailable` for other discovery failures and reports only a generic error.
+The footer and widget load once at session start. A directory outside a Git worktree stays silent. The UI shows `PR · status unavailable` for other discovery failures and reports only a generic error.
 
-They refresh after local commits, PR creation, pushes, and each dispatched workflow settles. During creation, intermediate refreshes wait until the workflow settles. They also refresh after any successful delegated task settles. Active Git worktrees poll every 30 seconds. Polling updates presentation only and may be stale.
+They refresh after local commits, PR creation, pushes, and each dispatched workflow settles. During creation, intermediate refreshes wait until the workflow settles. They also refresh after any successful delegated task settles. There is no periodic presentation refresh, so external changes may leave the footer and widget stale indefinitely. `/pr` reads fresh state before routing or acting and remains authoritative.
 
-The create widget stays hidden until the local branch has a commit beyond its creation point. `/pr` replaces any hint with routing feedback while it selects a route. The feedback clears before route interaction. A dispatched workflow keeps the widget hidden until the agent settles. Direct and no-action routes refresh it after completion. A failed command restores the prior hint and schedules a refresh.
+The create widget stays hidden until the local branch has a commit beyond its creation point. `/pr` replaces any hint with routing feedback while it selects a route. The feedback clears before route interaction. A dispatched workflow keeps the widget hidden until the agent settles. Direct and no-action routes refresh it after completion. A failed command restores the prior hint and schedules a refresh, except when fresh lookup hits the GitHub API quota: it shows the sanitized message `GitHub API rate limit exhausted; retry after GitHub resets it` and does not immediately retry.
 
 Presentation uses route priority, so draft appears before running CI. `/pr` reads fresh state before routing or merging. The command is authoritative for actions.
 
 ### Session identity
 
-The extension records one configured PR identity in the Pi session. It stores only the PR URL, number, host, head identity, and configured target identity. It does not store lifecycle, CI, review, readiness, or base state. Repeated polling does not add duplicate entries, and no repository cache file is created.
+The extension records one configured PR identity in the Pi session. It stores only the PR URL, number, host, head identity, and configured target identity. It does not store lifecycle, CI, review, readiness, or base state. Event-driven refreshes do not add duplicate entries, and no repository cache file is created.
 
 Normal discovery always runs first. If the configured remote ref was deleted, the footer and `/pr` may reload the exact observed PR URL. The current host, repository, branch, remote, ref, and local HEAD must still match the observation. Repository names use case-insensitive GitHub matching.
 
@@ -149,7 +149,7 @@ The GitHub response must match the observed URL, host, repository, head ref, hea
 
 - `/pr` accepts creation syntax only as a leading `--base BRANCH`, followed by optional creation guidance. It does not open a browser.
 - It does not run `/done` or `/sweep`.
-- Polling does not auto-triage comments or start a workflow. The package comment sweep runs only when an explicit `/pr` selects it.
+- Presentation refreshes do not auto-triage comments or start a workflow. The package comment sweep runs only when an explicit `/pr` selects it.
 - It does not enable auto-merge or add a merge queue.
 - It does not rebase the local branch, overwrite concurrent remote updates, delete branches, or clean up worktrees. Creation uses exact leases plus ancestry checks; an empty lease is only an atomic absence check.
 - Creation, discovery, and comment-sweep pushes require one unambiguous push URL for the configured destination.

package/extensions/pr-github.ts

@@ -66,6 +66,13 @@ export class PullRequestLoadError extends Error {
 	}
 }
 
+export class GitHubRateLimitError extends PullRequestLoadError {
+	constructor() {
+		super("GitHub API rate limit exhausted; retry after GitHub resets it");
+		this.name = "GitHubRateLimitError";
+	}
+}
+
 export type PullRequestRef = {
 	repository: string;
 	ref: string;
@@ -107,6 +114,10 @@ export type PullRequestCreationPreflight = {
 	ahead: number;
 };
 
+type CreationPreflightResult =
+	| { kind: "same-ref" }
+	| { kind: "distinct-ref"; preflight: PullRequestCreationPreflight };
+
 type CreationIdentity = {
 	target: PullRequestTarget;
 	head: string;
@@ -365,7 +376,11 @@ async function invoke(
 	return parseCommandOutput(result, action);
 }
 
-function commandFailure(action: string, result: CommandOutput): never {
+function commandFailure(action: string, result: CommandOutput, command?: string): never {
+	if (
+		command === "gh" && !result.killed && result.code !== 0 &&
+		result.stderr.includes("GraphQL: API rate limit exceeded")
+	) throw new GitHubRateLimitError();
 	fail(action, result.killed ? "command was cancelled" : `exit code ${result.code}`);
 }
 
@@ -377,7 +392,7 @@ async function execute(
 	args: string[],
 ): Promise<CommandOutput> {
 	const result = await invoke(pi, context, action, command, args);
-	if (result.killed || result.code !== 0) commandFailure(action, result);
+	if (result.killed || result.code !== 0) commandFailure(action, result, command);
 	return result;
 }
 
@@ -1104,19 +1119,18 @@ function parseCreationRepositoryLineage(output: string, expected: PushRepository
 	return normalizeRepository(sourceName);
 }
 
-async function assertCreationRepositoryRelation(
+async function inspectCreationRepositoryRelation(
 	pi: Pick<ExtensionAPI, "exec">,
 	context: PullRequestLoadContext,
 	target: PullRequestTarget,
 	origin: { repository: PushRepository },
 	baseRef: string,
-): Promise<void> {
+): Promise<"same-ref" | "distinct-ref"> {
 	if (target.host !== origin.repository.host) {
 		fail("Read creation repository", "base and head hosts do not match");
 	}
 	if (normalizeRepository(target.repository) === origin.repository.normalizedName) {
-		if (target.ref === baseRef) fail("Read creation repository", "head and base refs match");
-		return;
+		return target.ref === baseRef ? "same-ref" : "distinct-ref";
 	}
 	const read = async (repository: PushRepository): Promise<string> => {
 		const [owner, name] = repository.nameWithOwner.split("/");
@@ -1133,6 +1147,7 @@ async function assertCreationRepositoryRelation(
 		host: target.host,
 	});
 	if (originSource !== targetSource) fail("Read creation repository", "base and head are unrelated");
+	return "distinct-ref";
 }
 
 function parseCreationAhead(output: string): number {
@@ -1149,7 +1164,7 @@ async function preflightCreation(
 	target: PullRequestTarget,
 	explicitBaseRef: string | undefined,
 	identity: CreationIdentity,
-): Promise<PullRequestCreationPreflight> {
+): Promise<CreationPreflightResult> {
 	const validatedTarget = validatedCreationTarget(target);
 	if (!sameCreationTarget(identity.target, validatedTarget)) {
 		fail("Read creation target", "target changed");
@@ -1160,7 +1175,8 @@ async function preflightCreation(
 		? await readConfiguredCreationBaseRef(pi, context, identity.target.branch)
 		: await validateCreationRef(pi, context, explicitBaseRef);
 	const baseRef = configuredBaseRef ?? await readDefaultCreationBaseRef(pi, context, origin);
-	await assertCreationRepositoryRelation(pi, context, identity.target, origin, baseRef);
+	const relation = await inspectCreationRepositoryRelation(pi, context, identity.target, origin, baseRef);
+	if (relation === "same-ref") return { kind: relation };
 	const trackingRef = `refs/remotes/origin/${baseRef}`;
 	await execute(pi, context, "Fetch creation base", "git", [
 		"fetch", "--no-write-fetch-head", "--no-tags", "--no-recurse-submodules", "--",
@@ -1180,16 +1196,19 @@ async function preflightCreation(
 		"rev-list", "--count", `${mergeBase}..${identity.head}`,
 	])).stdout);
 	return {
-		head: identity.head,
-		base: {
-			host: origin.repository.host,
-			repository: origin.repository.nameWithOwner,
-			fetchSource: origin.fetchSource,
-			ref: baseRef,
-			oid: baseOid,
-			mergeBase,
+		kind: relation,
+		preflight: {
+			head: identity.head,
+			base: {
+				host: origin.repository.host,
+				repository: origin.repository.nameWithOwner,
+				fetchSource: origin.fetchSource,
+				ref: baseRef,
+				oid: baseOid,
+				mergeBase,
+			},
+			ahead,
 		},
-		ahead,
 	};
 }
 
@@ -1200,7 +1219,9 @@ export async function preflightPullRequestCreation(
 	explicitBaseRef?: string,
 ): Promise<PullRequestCreationPreflight> {
 	const identity = await captureCreationIdentity(pi, context, target);
-	return await preflightCreation(pi, context, target, explicitBaseRef, identity);
+	const result = await preflightCreation(pi, context, target, explicitBaseRef, identity);
+	if (result.kind === "same-ref") fail("Read creation repository", "head and base refs match");
+	return result.preflight;
 }
 
 async function creationDiscovery(
@@ -1211,8 +1232,12 @@ async function creationDiscovery(
 	identity?: CreationIdentity,
 ): Promise<CurrentPullRequestDiscovery> {
 	const captured = identity ?? await captureCreationIdentity(pi, context, target);
-	const preflight = await preflightCreation(pi, context, target, explicitBaseRef, captured);
-	return { kind: "none", creationTarget: target, branch: { ahead: preflight.ahead } };
+	const result = await preflightCreation(pi, context, target, explicitBaseRef, captured);
+	return {
+		kind: "none",
+		creationTarget: target,
+		branch: { ahead: result.kind === "same-ref" ? 0 : result.preflight.ahead },
+	};
 }
 
 async function readRemoteAuthority(
@@ -1251,6 +1276,7 @@ async function readRemoteAuthority(
 		) fail("Read fetch repository", "fetch and push repositories do not match");
 		return { fetchSource: pushUrl.fetchSource, repository: pushRepository };
 	} catch (error) {
+		if (error instanceof GitHubRateLimitError) throw error;
 		if (!strict && error instanceof PullRequestLoadError) return null;
 		throw error;
 	}

package/extensions/pr.ts

@@ -19,6 +19,7 @@ import {
 } from "./pr-command.ts";
 import { PullRequestCreator, type CreatePullRequestOptions } from "./pr-create.ts";
 import {
+	GitHubRateLimitError,
 	loadCurrentPullRequest,
 	parsePullRequestObservation,
 	pullRequestObservation,
@@ -37,7 +38,6 @@ import {
 } from "./pr-ui.ts";
 import { PullRequestBranchUpdater, type UpdateBranchOptions } from "./pr-update-branch.ts";
 
-const POLL_INTERVAL_MS = 30_000;
 const ROUTING_SPINNER_INTERVAL_MS = 80;
 const ROUTING_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 const ROUTING_WIDGET_TEXT = "Checking pull request…";
@@ -282,10 +282,9 @@ export default function pullRequestExtension(
 		return discovery;
 	};
 	let sessionGeneration = 0;
-	let timer: ReturnType<typeof setInterval> | undefined;
 	let active: AbortController | undefined;
 	let queued = false;
-	let refreshFailureReported = false;
+	let reportedRefreshFailure: "generic" | "quota" | undefined;
 	let displayEstablished = false;
 	let lastDiscovery: "configured" | "inferred" | "absent" | "blocked" | "inactive" | undefined;
 	let lastBlockedIssueKey: string | undefined;
@@ -561,8 +560,6 @@ export default function pullRequestExtension(
 		discovery: Awaited<ReturnType<typeof loadCurrentPullRequest>>,
 	): void => {
 		if (discovery.kind === "inactive") {
-			if (timer !== undefined) clearInterval(timer);
-			timer = undefined;
 			displayEstablished = true;
 			lastDiscovery = "inactive";
 			displayedWidget = undefined;
@@ -600,7 +597,7 @@ export default function pullRequestExtension(
 		context = undefined;
 		observation = undefined;
 		queued = false;
-		refreshFailureReported = false;
+		reportedRefreshFailure = undefined;
 		displayEstablished = false;
 		lastDiscovery = undefined;
 		lastBlockedIssueKey = undefined;
@@ -612,18 +609,22 @@ export default function pullRequestExtension(
 		activeInvocations.clear();
 		stopRoutingSpinner();
 		widgetKind = "presentation";
-		if (timer !== undefined) clearInterval(timer);
-		timer = undefined;
 		active?.abort();
 		active = undefined;
 	};
 
-	const reportRefreshFailure = (): void => {
+	const reportRefreshFailure = (error: unknown): void => {
 		const ctx = context;
-		if (!ctx || refreshFailureReported) return;
-		refreshFailureReported = true;
+		const category = error instanceof GitHubRateLimitError ? "quota" : "generic";
+		if (!ctx || reportedRefreshFailure === category || reportedRefreshFailure === "quota") return;
+		reportedRefreshFailure = category;
 		try {
-			ctx.ui.notify("PR status refresh failed: status unavailable", "error");
+			ctx.ui.notify(
+				error instanceof GitHubRateLimitError
+					? error.message
+					: "PR status refresh failed: status unavailable",
+				"error",
+			);
 		} catch {
 			console.error("PR status refresh failed and could not be reported");
 		}
@@ -655,7 +656,7 @@ export default function pullRequestExtension(
 			try {
 				discovery = await load(pi, loadContext);
 				if (controller.signal.aborted || sessionGeneration !== generation) return;
-			} catch {
+			} catch (error) {
 				// Keep an established footer. A refresh failure must not leave a stale action hint.
 				if (!controller.signal.aborted && sessionGeneration === generation) {
 					displayedWidget = undefined;
@@ -665,13 +666,13 @@ export default function pullRequestExtension(
 						ctx.ui.setStatus(UI_KEY, formatPrFooter(unavailable, ctx.ui.theme));
 						displayEstablished = true;
 					}
-					reportRefreshFailure();
+					reportRefreshFailure(error);
 				}
 				return;
 			}
 			if (controller.signal.aborted || sessionGeneration !== generation) return;
 			render(ctx, discovery);
-			refreshFailureReported = false;
+			reportedRefreshFailure = undefined;
 
 			const pullRequest = discovery.kind === "current" ? discovery.pullRequest : undefined;
 			if (pendingWorkspaceRename && pullRequest?.target.provenance === "configured") {
@@ -716,14 +717,10 @@ export default function pullRequestExtension(
 
 	pi.on("session_start", async (_event, ctx) => {
 		stop();
-		const generation = sessionGeneration;
 		observation = latestObservation(ctx);
 		if (!ctx.hasUI) return;
 		context = ctx;
 		await refresh();
-		if (sessionGeneration === generation && lastDiscovery !== "inactive") {
-			timer = setInterval(refreshInBackground, POLL_INTERVAL_MS);
-		}
 	});
 
 	pi.on("session_shutdown", stop);
@@ -805,8 +802,14 @@ export default function pullRequestExtension(
 				if (sessionGeneration === generation) {
 					cancelRefresh();
 					activeInvocations.delete(invocation);
-					reconcileWidget(ctx);
-					refreshInBackground();
+					if (error instanceof GitHubRateLimitError) {
+						displayedWidget = undefined;
+						reconcileWidget(ctx);
+						reportRefreshFailure(error);
+					} else {
+						reconcileWidget(ctx);
+						refreshInBackground();
+					}
 				}
 				throw error;
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-pr",
-  "version": "4.0.4",
+  "version": "4.0.6",
   "description": "Run /pr to safely discover or link the current pull request, then create, update, address feedback, fix CI, or merge when ready.",
   "keywords": [
     "pi-package",