@henryqw/pi-pr 4.0.6 → 4.0.7

package/README.md

@@ -70,7 +70,7 @@ Each footer entry is one linked `PR #number` plus one plain-language status: `N
 | 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. |
 | GitHub Actions job failed | Run the CI fix workflow when the same local prerequisite holds. |
 | External check or commit status failed | Show `CI failed` as a no-action blocker. |
-| Changes requested or unresolved review threads | Run the package comment sweep when the same local prerequisite holds. |
+| Changes requested or unresolved review threads | Start or resume the package comment sweep when the same local prerequisite holds. |
 | 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. |
 
@@ -90,6 +90,10 @@ The creation workflow repeats destination, remote OID, PR, and configuration che
 
 Each helper workflow receives a random run ID and its first action. The run stays bound to one session, canonical worktree, route, and fresh authority. Helper calls from another run, session, worktree, or route fail.
 
+For comment sweeps, `/pr` checks the package recovery file without changing it. It selects `start` when recovery is absent. It selects `resume` only when valid recovery matches the fresh route authority. Invalid recovery stays unchanged and blocks dispatch with its path and reason.
+
+Direct skill or `pi_pr_*` tool calls cannot create route authority. Run `/pr` to reserve a fresh route.
+
 Only one helper run can exist at a time. Most runs expire when the agent settles. A create or branch-update conflict stays available for one user-guided continuation, then expires after that continuation settles. Session replacement and shutdown forget the run without aborting or cleaning a pending merge.
 
 After a `/pr` create workflow settles, the extension waits for a refresh that finds a configured current PR. It then prefixes the Herdr workspace label with `#<number> • `.
@@ -149,7 +153,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`.
-- Presentation refreshes do 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 starts or resumes 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-command.ts

@@ -17,15 +17,17 @@ import {
 
 export type WorkflowNextStep = Extract<NextStep, "create" | "update-branch" | "sweep" | "fix-ci">;
 
-const WORKFLOWS: Record<WorkflowNextStep, { command: string; action: string }> = {
-	create: { command: "skill:pi-pr-create", action: "prepare" },
-	"update-branch": { command: "skill:pi-pr-update-branch", action: "merge" },
-	sweep: { command: "skill:pi-pr-comment-sweep", action: "start" },
-	"fix-ci": { command: "skill:pi-pr-fix-ci", action: "collect" },
+const WORKFLOWS: Record<WorkflowNextStep, { command: string }> = {
+	create: { command: "skill:pi-pr-create" },
+	"update-branch": { command: "skill:pi-pr-update-branch" },
+	sweep: { command: "skill:pi-pr-comment-sweep" },
+	"fix-ci": { command: "skill:pi-pr-fix-ci" },
 };
 export type WorkflowReservation =
 	| { route: "create"; target: PullRequestTarget; base?: string }
 	| { route: Exclude<WorkflowNextStep, "create">; pullRequest: CurrentPullRequest };
+export type WorkflowLaunchAction = "prepare" | "merge" | "start" | "resume" | "collect";
+export type WorkflowReservationResult = { runId: string; action: WorkflowLaunchAction };
 
 type PrCommandPi = Pick<ExtensionAPI, "exec" | "getCommands" | "sendUserMessage">;
 export type PrCommandInvocation = ((nextStep: NextStep) => void) & {
@@ -42,7 +44,7 @@ export type WorkflowPromptIdentity = Readonly<{
 	route: WorkflowNextStep;
 	skill: string;
 	runId: string;
-	action: string;
+	action: WorkflowLaunchAction;
 }>;
 
 export type PrCommandDependencies = {
@@ -52,7 +54,7 @@ export type PrCommandDependencies = {
 		reservation: WorkflowReservation,
 		ctx: ExtensionCommandContext,
 		invocation?: PrCommandInvocation,
-	) => Promise<string>;
+	) => Promise<WorkflowReservationResult>;
 	markWorkflowPromptQueued?: (identity: WorkflowPromptIdentity, queued: boolean) => void;
 	releaseWorkflow?: (runId: string, invocation?: PrCommandInvocation) => void;
 };
@@ -96,7 +98,7 @@ function packageWorkflowCommand(pi: PrCommandPi, route: WorkflowNextStep) {
 		candidate.sourceInfo.origin === "package"
 	);
 	if (!command) throw new Error(`${workflow.command} failed: bundled workflow is unavailable`);
-	return { command, action: workflow.action };
+	return command;
 }
 
 async function dispatchWorkflow(
@@ -113,10 +115,11 @@ async function dispatchWorkflow(
 	const workflow = packageWorkflowCommand(pi, route);
 	let runId: string | undefined;
 	try {
-		runId = await reserve(reservation, ctx, invocation);
+		const reserved = await reserve(reservation, ctx, invocation);
+		runId = reserved.runId;
 		invocation?.assertCurrent();
 		const queued = !ctx.isIdle();
-		const identity = { route, skill: workflow.command.name, runId, action: workflow.action };
+		const identity = { route, skill: workflow.name, runId, action: reserved.action };
 		markPromptQueued(identity, queued);
 		const options = queued
 			? { deliverAs: "followUp" as const, expandPromptTemplates: true }

package/extensions/pr-comment-sweep.ts

@@ -231,6 +231,16 @@ function sameLinkage(expected: SweepAuthority, current: SweepAuthority, remoteHe
 		current.target.remoteOid === remoteHead;
 }
 
+function recoveryMatchesRouteAuthority(state: SweepState, suppliedAuthority: SweepAuthority): boolean {
+	const permittedHeads = new Set<string>();
+	if (state.attempts.push.state !== "applied") permittedHeads.add(state.original.lease);
+	if (
+		(state.attempts.push.state === "attempting" || state.attempts.push.state === "unknown" || state.attempts.push.state === "applied") &&
+		state.publicationHead
+	) permittedHeads.add(state.publicationHead);
+	return [...permittedHeads].some((head) => sameLinkage(state.authority, suppliedAuthority, head));
+}
+
 function feedbackMatchesAuthority(snapshot: FeedbackSnapshot, authority: SweepAuthority, head: string): boolean {
 	const current = snapshot.pullRequest;
 	return current.id === authority.id && current.number === authority.number && current.url === authority.url &&
@@ -575,6 +585,17 @@ export class PullRequestCommentSweep {
 		return (await this.location()).path;
 	}
 
+	async recoveryLaunchAction(): Promise<"start" | "resume"> {
+		if (!this.suppliedAuthority) throw new Error("Comment sweep recovery inspection requires route authority");
+		const location = await this.location();
+		const state = await this.loadIfPresent(location);
+		if (!state) return "start";
+		if (!recoveryMatchesRouteAuthority(state, this.suppliedAuthority)) {
+			throw new Error(`Comment sweep recovery is preserved at ${location.path}: recovery does not match freshly discovered route authority`);
+		}
+		return "resume";
+	}
+
 	private async loadState(location: Awaited<ReturnType<PullRequestCommentSweep["location"]>>): Promise<SweepState> {
 		const raw = await readTextFileBounded(location.path, SWEEP_RECOVERY_MAX_BYTES, { signal: this.signal });
 		let value: unknown;
@@ -789,17 +810,10 @@ export class PullRequestCommentSweep {
 	async resume(): Promise<SweepStatus> {
 		return await withWorktreeLock(this.cwd, async () => {
 			if (!this.suppliedAuthority) throw new Error("Comment sweep resume requires route authority");
-			const suppliedAuthority = this.suppliedAuthority;
 			const location = await this.location();
 			const state = await this.loadState(location);
-			const permittedHeads = new Set<string>();
-			if (state.attempts.push.state !== "applied") permittedHeads.add(state.original.lease);
-			if (
-				(state.attempts.push.state === "attempting" || state.attempts.push.state === "unknown" || state.attempts.push.state === "applied") &&
-				state.publicationHead
-			) permittedHeads.add(state.publicationHead);
-			if (![...permittedHeads].some((head) => sameLinkage(state.authority, suppliedAuthority, head))) {
-				throw new Error("Comment sweep recovery does not match supplied route authority");
+			if (!recoveryMatchesRouteAuthority(state, this.suppliedAuthority)) {
+				throw new Error(`Comment sweep recovery is preserved at ${location.path}: recovery does not match supplied route authority`);
 			}
 			await this.reconcile(state);
 			state.attempts.resolutions = state.attempts.resolutions.filter(({ state: attempt }) => attempt !== "blocked");

package/extensions/pr.ts

@@ -140,7 +140,7 @@ const FixCiParameters = Type.Union([
 
 type UpdateBranchWorkflow = Pick<PullRequestBranchUpdater, "state" | "merge" | "continue" | "publish">;
 type CreateWorkflow = Pick<PullRequestCreator, "state" | "prepare" | "merge" | "continue" | "push" | "publish">;
-type SweepWorkflow = Pick<PullRequestCommentSweep, "start" | "resume" | "show" | "record" | "publish" | "refresh" | "resolve" | "finalize">;
+type SweepWorkflow = Pick<PullRequestCommentSweep, "recoveryLaunchAction" | "start" | "resume" | "show" | "record" | "publish" | "refresh" | "resolve" | "finalize">;
 type FixCiWorkflow = Pick<PullRequestCiFixer, "collect" | "publish">;
 
 type WorkflowContextBase = {
@@ -337,7 +337,7 @@ export default function pullRequestExtension(
 						loadCurrentPullRequest: load,
 					}),
 				};
-				break;
+				return { runId, action: "merge" };
 			case "create":
 				workflowContext = {
 					...common,
@@ -350,9 +350,9 @@ export default function pullRequestExtension(
 						loadCurrentPullRequest: load,
 					}),
 				};
-				break;
-			case "sweep":
-				workflowContext = {
+				return { runId, action: "prepare" };
+			case "sweep": {
+				const selected: Extract<WorkflowContext, { route: "sweep" }> = {
 					...common,
 					route: "sweep",
 					workflow: createCommentSweep({
@@ -362,7 +362,17 @@ export default function pullRequestExtension(
 						loadCurrentPullRequest: load,
 					}),
 				};
-				break;
+				workflowContext = selected;
+				try {
+					const action = await selected.workflow.recoveryLaunchAction();
+					invocation.assertCurrent();
+					if (workflowContext !== selected) throw new Error("PR workflow session changed during recovery inspection");
+					return { runId, action };
+				} catch (error) {
+					clearWorkflow(selected);
+					throw error;
+				}
+			}
 			case "fix-ci":
 				workflowContext = {
 					...common,
@@ -374,9 +384,8 @@ export default function pullRequestExtension(
 						loadCurrentPullRequest: load,
 					}),
 				};
-				break;
+				return { runId, action: "collect" };
 		}
-		return common.runId;
 	};
 
 	const markWorkflowPromptQueued: NonNullable<PrCommandDependencies["markWorkflowPromptQueued"]> = (identity, queued) => {
@@ -403,7 +412,7 @@ export default function pullRequestExtension(
 	) => {
 		signal?.throwIfAborted();
 		const selected = workflowContext;
-		if (!selected) throw new Error("No PR workflow is active");
+		if (!selected) throw new Error("No PR workflow is active; run /pr to discover and reserve the current route");
 		if (selected.runId !== runId) throw new Error("PR workflow runId is wrong or stale");
 		if (selected.sessionGeneration !== sessionGeneration) throw new Error("PR workflow session is stale");
 		if (selected.route !== route) throw new Error(`PR workflow route is ${selected.route}, not ${route}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-pr",
-  "version": "4.0.6",
+  "version": "4.0.7",
   "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",

package/skills/pi-pr-comment-sweep/SKILL.md

@@ -9,9 +9,10 @@ Use the package-owned comment-sweep workflow. It exposes these closed actions:
 `start`, `resume`, `show`, `record`, `publish`, `refresh`, `resolve`, and
 `finalize`.
 
-1. Call `start` for a fresh current-branch pull request. Call `resume` only for
-   saved work. Never replace or delete blocked recovery state by hand. See
-   [Sweep recovery](references/recovery.md).
+1. Use the `start` or `resume` action supplied by `/pr`. `/pr` checks saved work
+   and chooses the action. Do not change it. Direct skill or tool calls cannot
+   create route authority; run `/pr` instead. Never replace or delete blocked
+   recovery state by hand. See [Sweep recovery](references/recovery.md).
 2. Use `show` for one feedback ID at a time. Inspect every conversation
    comment, review, thread, and thread comment. Follow
    [Thread triage](references/thread-triage.md).

package/skills/pi-pr-comment-sweep/references/recovery.md

@@ -10,10 +10,14 @@ The file is private, bounded to 1 MiB, and replaced atomically. It contains the
 frozen PR authority, original head and lease, complete feedback, exact ledger,
 owned paths, and mutation attempts.
 
-Use `resume` when this file exists. Resume checks the canonical worktree, local
-changes, PR linkage, and remote head. It reconciles an attempted push or thread
-resolution before issuing a new epoch and run ID. Calls from the old run then
-fail.
+Run `/pr` to enter recovery. After fresh route discovery, `/pr` checks this file
+without changing it. It selects `start` when the file is absent. It selects
+`resume` only when valid recovery matches the fresh route authority.
+
+Resume checks the canonical worktree, local changes, PR linkage, and remote
+head again under its lock. It reconciles an attempted push or thread resolution
+before issuing a new epoch and run ID. Calls from the old run then fail. Direct
+skill or tool calls cannot create route authority.
 
 A completed post-publish `refresh` stores the new complete snapshot before any
 replacement ledger. Recovery keeps that snapshot in `refresh-pending`, with its
@@ -22,7 +26,9 @@ Use `show` with the resumed guard to inspect each frozen item. Then use `record`
 without `ownedPaths` to supply exact complete coverage for that snapshot.
 Resolution and finalization remain blocked until this record succeeds.
 
-Malformed or oversized recovery is preserved and blocks the workflow. Never
-repair, move, replace, or delete it automatically. An unknown mutation is never
-replayed. If reconciliation cannot prove its exact result, stop and report the
-state path and blocker.
+Malformed, oversized, obsolete, wrong-worktree, or route-mismatched recovery is
+preserved and blocks dispatch. Never repair, move, replace, or delete it
+automatically. Report the state path and exact blocker.
+
+An unknown mutation is never replayed. If reconciliation cannot prove its exact
+result, stop and report the state path and blocker.