@henryqw/pi-pr 3.1.10 → 4.0.3

package/extensions/pr.ts

@@ -1,3 +1,5 @@
+import { randomUUID } from "node:crypto";
+import { realpath } from "node:fs/promises";
 import {
 	isBashToolResult,
 	type ExtensionAPI,
@@ -5,15 +7,25 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, type Component, type TUI } from "@earendil-works/pi-tui";
 import { createHerdrClient } from "@henryqw/pi-herdr";
-import { createPrCommandHandler } from "./pr-command.ts";
+import { Type } from "typebox";
+import { PullRequestCiFixer, type PullRequestCiFixOptions } from "./pr-ci.ts";
+import { PullRequestCommentSweep, type PullRequestCommentSweepOptions } from "./pr-comment-sweep.ts";
+import {
+	createPrCommandHandler,
+	type PrCommandDependencies,
+	type PrCommandInvocation,
+	type WorkflowPromptIdentity,
+	type WorkflowReservation,
+} from "./pr-command.ts";
+import { PullRequestCreator, type CreatePullRequestOptions } from "./pr-create.ts";
 import {
-	hasLocalCommit,
 	loadCurrentPullRequest,
 	parsePullRequestObservation,
 	pullRequestObservation,
 	samePullRequestObservation,
 	type PullRequestObservation,
 } from "./pr-github.ts";
+import { runChecked, spawnBounded } from "./pr-execution.ts";
 import {
 	discoveryIssueKey,
 	discoveryIssueMessage,
@@ -23,6 +35,7 @@ import {
 	unavailablePrDisplay,
 	type PrDisplay,
 } 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;
@@ -36,13 +49,149 @@ const GIT_COMMIT = /(?:^|[;&|]\s*|\n\s*)git\s+commit(?=\s|$|[;&|])/;
 const GIT_PUSH = /(?:^|[;&|]\s*|\n\s*)git\s+push(?=\s|$|[;&|])/;
 const WORKFLOW_ROUTES = new Set(["create", "update-branch", "sweep", "fix-ci"]);
 const DELEGATED_TOOLS = new Set(["delegate_task", "delegate_flow", "delegate_flow_continue"]);
+const CLOSED = { additionalProperties: false } as const;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+const RouteRunId = Type.String({ minLength: 36, maxLength: 36, pattern: UUID.source });
+const ResolvedPaths = Type.Array(Type.String({ minLength: 1, maxLength: 4_096 }), { minItems: 1, maxItems: 128 });
+const OwnedPaths = Type.Array(Type.String({ minLength: 1, maxLength: 4_096 }), { maxItems: 128 });
+const SweepGuard = Type.Object({
+	epoch: Type.Integer({ minimum: 1 }),
+	runId: Type.String({ minLength: 1, maxLength: 128 }),
+	generation: Type.Integer({ minimum: 1 }),
+	fingerprint: Type.String({ minLength: 64, maxLength: 64 }),
+}, CLOSED);
+const SweepLedgerEntry = Type.Object({
+	id: Type.String({ minLength: 1, maxLength: 1_024 }),
+	kind: Type.Union([
+		Type.Literal("conversation_comment"), Type.Literal("review"), Type.Literal("thread"), Type.Literal("thread_comment"),
+	]),
+	disposition: Type.Union([Type.Literal("addressed"), Type.Literal("non-actionable"), Type.Literal("blocked")]),
+	note: Type.String({ maxLength: 2_048 }),
+}, CLOSED);
+const SweepLedger = Type.Array(SweepLedgerEntry, { maxItems: 1_000 });
+const SweepProjection = Type.Object({
+	generation: Type.Integer({ minimum: 1 }),
+	contentFingerprint: Type.String({ minLength: 64, maxLength: 64 }),
+	items: Type.Array(Type.Object({
+		id: Type.String({ minLength: 1, maxLength: 1_024 }),
+		kind: Type.Union([
+			Type.Literal("conversation_comment"), Type.Literal("review"), Type.Literal("thread"), Type.Literal("thread_comment"),
+		]),
+	}, CLOSED), { maxItems: 1_000 }),
+	threads: Type.Array(Type.Object({
+		id: Type.String({ minLength: 1, maxLength: 1_024 }),
+		isResolved: Type.Boolean(),
+	}, CLOSED), { maxItems: 1_000 }),
+}, CLOSED);
+const SweepChecks = Type.Array(Type.Object({
+	command: Type.String({ minLength: 1, maxLength: 1_024 }),
+	args: Type.Array(Type.String({ maxLength: 4_096 }), { maxItems: 256 }),
+}, CLOSED), { maxItems: 32 });
+
+const UpdateBranchParameters = Type.Union([
+	Type.Object({ runId: RouteRunId, action: Type.Literal("merge") }, CLOSED),
+	Type.Object({ runId: RouteRunId, action: Type.Literal("continue"), resolvedPaths: ResolvedPaths }, CLOSED),
+	Type.Object({ runId: RouteRunId, action: Type.Literal("publish") }, CLOSED),
+]);
+const CreateParameters = Type.Union([
+	Type.Object({ runId: RouteRunId, action: Type.Literal("prepare") }, CLOSED),
+	Type.Object({ runId: RouteRunId, action: Type.Literal("merge") }, CLOSED),
+	Type.Object({ runId: RouteRunId, action: Type.Literal("continue"), resolvedPaths: ResolvedPaths }, CLOSED),
+	Type.Object({ runId: RouteRunId, action: Type.Literal("push") }, CLOSED),
+	Type.Object({
+		runId: RouteRunId,
+		action: Type.Literal("publish"),
+		title: Type.String({ minLength: 1, maxLength: 256 }),
+		body: Type.String({ maxLength: 65_536 }),
+	}, CLOSED),
+]);
+const SweepParameters = Type.Union([
+	Type.Object({ runId: RouteRunId, action: Type.Literal("start") }, CLOSED),
+	Type.Object({ runId: RouteRunId, action: Type.Literal("resume") }, CLOSED),
+	Type.Object({ runId: RouteRunId, action: Type.Literal("show"), guard: SweepGuard, id: Type.String({ minLength: 1, maxLength: 1_024 }) }, CLOSED),
+	Type.Object({
+		runId: RouteRunId,
+		action: Type.Literal("record"),
+		guard: SweepGuard,
+		ledger: SweepLedger,
+		ownedPaths: Type.Optional(OwnedPaths),
+	}, CLOSED),
+	Type.Object({ runId: RouteRunId, action: Type.Literal("publish"), guard: SweepGuard }, CLOSED),
+	Type.Object({ runId: RouteRunId, action: Type.Literal("refresh"), guard: SweepGuard }, CLOSED),
+	Type.Object({
+		runId: RouteRunId,
+		action: Type.Literal("resolve"),
+		guard: SweepGuard,
+		threadIds: Type.Array(Type.String({ minLength: 1, maxLength: 1_024 }), { maxItems: 1_000 }),
+	}, CLOSED),
+	Type.Object({
+		runId: RouteRunId,
+		action: Type.Literal("finalize"),
+		guard: SweepGuard,
+		projection: SweepProjection,
+		checks: SweepChecks,
+	}, CLOSED),
+]);
+const FixCiParameters = Type.Union([
+	Type.Object({ runId: RouteRunId, action: Type.Literal("collect") }, CLOSED),
+	Type.Object({ runId: RouteRunId, action: Type.Literal("publish") }, CLOSED),
+]);
+
+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 FixCiWorkflow = Pick<PullRequestCiFixer, "collect" | "publish">;
+
+type WorkflowContextBase = {
+	runId: string;
+	sessionGeneration: number;
+	worktree: string;
+	controller: AbortController;
+	usedSinceSettlement: boolean;
+	queuedPrompt?: WorkflowPromptIdentity;
+	conflictRetained: boolean;
+};
+type WorkflowContext =
+	| (WorkflowContextBase & { route: "update-branch"; workflow: UpdateBranchWorkflow })
+	| (WorkflowContextBase & { route: "create"; base?: string; workflow: CreateWorkflow })
+	| (WorkflowContextBase & { route: "sweep"; workflow: SweepWorkflow })
+	| (WorkflowContextBase & { route: "fix-ci"; workflow: FixCiWorkflow });
 
 type PullRequestExtensionDependencies = {
 	loadCurrentPullRequest?: typeof loadCurrentPullRequest;
-	hasLocalCommit?: typeof hasLocalCommit;
 	createPrCommandHandler?: typeof createPrCommandHandler;
+	createBranchUpdater?: (options: UpdateBranchOptions) => UpdateBranchWorkflow;
+	createPullRequestCreator?: (options: CreatePullRequestOptions) => CreateWorkflow;
+	createCommentSweep?: (options: PullRequestCommentSweepOptions) => SweepWorkflow;
+	createCiFixer?: (options: PullRequestCiFixOptions) => FixCiWorkflow;
+	canonicalWorktree?: (cwd: string, signal?: AbortSignal) => Promise<string>;
+	newRunId?: () => string;
 };
 
+async function canonicalWorktree(cwd: string, signal?: AbortSignal): Promise<string> {
+	const result = await runChecked(spawnBounded, "git", ["rev-parse", "--show-toplevel"], { cwd, signal });
+	const normalized = result.stdout.replace(/\r\n/g, "\n");
+	const lines = (normalized.endsWith("\n") ? normalized.slice(0, -1) : normalized).split("\n");
+	if (lines.length !== 1 || !lines[0]) throw new Error("Git worktree root resolution returned invalid output");
+	return await realpath(lines[0]);
+}
+
+function toolResult(value: unknown) {
+	return {
+		content: [{ type: "text" as const, text: JSON.stringify(value) }],
+		details: value,
+	};
+}
+
+function matchesWorkflowPrompt(prompt: string, identity: WorkflowPromptIdentity): boolean {
+	const tokens = new Set(prompt.split(/\s+/).filter(Boolean));
+	const skillName = identity.skill.startsWith("skill:") ? identity.skill.slice("skill:".length) : "";
+	const matchesSkill = tokens.has(`/${identity.skill}`) ||
+		(skillName !== "" && tokens.has("<skill") && tokens.has(`name="${skillName}"`));
+	return matchesSkill && tokens.has(`runId=${identity.runId}`) && tokens.has(`action=${identity.action}`);
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -104,13 +253,24 @@ export default function pullRequestExtension(
 	};
 
 	const discover = dependencies.loadCurrentPullRequest ?? loadCurrentPullRequest;
-	const detectLocalCommit = dependencies.hasLocalCommit ?? hasLocalCommit;
 	const createCommandHandler = dependencies.createPrCommandHandler ?? createPrCommandHandler;
+	const createBranchUpdater = dependencies.createBranchUpdater ?? ((options) => new PullRequestBranchUpdater(options));
+	const createPullRequestCreator = dependencies.createPullRequestCreator ?? ((options) => new PullRequestCreator(options));
+	const createCommentSweep = dependencies.createCommentSweep ?? ((options) => new PullRequestCommentSweep(options));
+	const createCiFixer = dependencies.createCiFixer ?? ((options) => new PullRequestCiFixer(options));
+	const resolveCanonicalWorktree = dependencies.canonicalWorktree ?? canonicalWorktree;
+	const newRunId = dependencies.newRunId ?? randomUUID;
 	let context: ExtensionContext | undefined;
 	let observation: PullRequestObservation | undefined;
-	const load: typeof loadCurrentPullRequest = async (api, loadContext, inspectedLocal) => {
+	const load: typeof loadCurrentPullRequest = async (
+		api,
+		loadContext,
+		inspectedLocal,
+		_observed,
+		explicitCreationBase,
+	) => {
 		const generation = sessionGeneration;
-		const discovery = await discover(api, loadContext, inspectedLocal, observation);
+		const discovery = await discover(api, loadContext, inspectedLocal, observation, explicitCreationBase);
 		if (generation !== sessionGeneration) return discovery;
 		if (discovery.kind === "current") {
 			const current = pullRequestObservation(discovery.pullRequest);
@@ -131,9 +291,9 @@ export default function pullRequestExtension(
 	let lastBlockedIssueKey: string | undefined;
 	let delegatedWorkPending = false;
 	let pendingWorkspaceRename = false;
-	let mergeCompleted = false;
 	let displayedWidget: PrDisplay | undefined;
 	let commandGeneration = 0;
+	let workflowContext: WorkflowContext | undefined;
 	const activeInvocations = new Map<number, "routing" | "resolved" | "create-workflow" | "workflow">();
 	let widgetKind: "presentation" | "routing" = "presentation";
 	let routingSpinnerFrame = 0;
@@ -148,6 +308,202 @@ export default function pullRequestExtension(
 		routingSpinnerComponent = undefined;
 	};
 
+	const clearWorkflow = (selected: WorkflowContext | undefined): void => {
+		if (!selected || workflowContext !== selected) return;
+		workflowContext = undefined;
+		selected.controller.abort();
+	};
+
+	const reserveWorkflow: NonNullable<PrCommandDependencies["reserveWorkflow"]> = async (reservation, ctx, invocation) => {
+		if (!invocation) throw new Error("PR workflow command generation is unavailable");
+		invocation.assertCurrent();
+		const worktree = await resolveCanonicalWorktree(ctx.cwd, ctx.signal);
+		invocation.assertCurrent();
+		if (workflowContext) throw new Error(`PR workflow ${workflowContext.runId} is still active`);
+		const runId = newRunId();
+		if (!UUID.test(runId)) throw new Error("PR workflow runId generator returned an invalid UUID");
+		const common: WorkflowContextBase = {
+			runId,
+			sessionGeneration: invocation.sessionGeneration,
+			worktree,
+			controller: new AbortController(),
+			usedSinceSettlement: false,
+			conflictRetained: false,
+		};
+		switch (reservation.route) {
+			case "update-branch":
+				workflowContext = {
+					...common,
+					route: "update-branch",
+					workflow: createBranchUpdater({
+						cwd: worktree,
+						authority: reservation.pullRequest,
+						signal: common.controller.signal,
+						loadCurrentPullRequest: load,
+					}),
+				};
+				break;
+			case "create":
+				workflowContext = {
+					...common,
+					route: "create",
+					...(reservation.base === undefined ? {} : { base: reservation.base }),
+					workflow: createPullRequestCreator({
+						cwd: worktree,
+						target: reservation.target,
+						signal: common.controller.signal,
+						loadCurrentPullRequest: load,
+					}),
+				};
+				break;
+			case "sweep":
+				workflowContext = {
+					...common,
+					route: "sweep",
+					workflow: createCommentSweep({
+						cwd: worktree,
+						authority: reservation.pullRequest,
+						signal: common.controller.signal,
+						loadCurrentPullRequest: load,
+					}),
+				};
+				break;
+			case "fix-ci":
+				workflowContext = {
+					...common,
+					route: "fix-ci",
+					workflow: createCiFixer({
+						cwd: worktree,
+						authority: reservation.pullRequest,
+						signal: common.controller.signal,
+						loadCurrentPullRequest: load,
+					}),
+				};
+				break;
+		}
+		return common.runId;
+	};
+
+	const markWorkflowPromptQueued: NonNullable<PrCommandDependencies["markWorkflowPromptQueued"]> = (identity, queued) => {
+		if (workflowContext?.runId !== identity.runId || workflowContext.route !== identity.route) {
+			throw new Error("PR workflow reservation is wrong or stale");
+		}
+		workflowContext.queuedPrompt = queued ? identity : undefined;
+	};
+
+	const releaseWorkflow: NonNullable<PrCommandDependencies["releaseWorkflow"]> = (runId, invocation) => {
+		const selected = workflowContext;
+		if (
+			invocation && selected?.runId === runId &&
+			selected.sessionGeneration === invocation.sessionGeneration
+		) clearWorkflow(selected);
+	};
+
+	const executeWorkflowAction = async <Route extends WorkflowContext["route"]>(
+		runId: string,
+		route: Route,
+		ctx: ExtensionContext,
+		signal: AbortSignal | undefined,
+		action: (selected: Extract<WorkflowContext, { route: Route }>) => Promise<unknown>,
+	) => {
+		signal?.throwIfAborted();
+		const selected = workflowContext;
+		if (!selected) throw new Error("No PR workflow is active");
+		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}`);
+		const abortRun = () => selected.controller.abort(signal?.reason);
+		if (signal?.aborted) abortRun();
+		else signal?.addEventListener("abort", abortRun, { once: true });
+		try {
+			selected.controller.signal.throwIfAborted();
+			const worktree = await resolveCanonicalWorktree(ctx.cwd, selected.controller.signal);
+			if (workflowContext !== selected || selected.sessionGeneration !== sessionGeneration) {
+				throw new Error("PR workflow session changed during validation");
+			}
+			selected.controller.signal.throwIfAborted();
+			if (worktree !== selected.worktree) throw new Error("PR workflow worktree is wrong or stale");
+			selected.usedSinceSettlement = true;
+			return toolResult(await action(selected as Extract<WorkflowContext, { route: Route }>));
+		} finally {
+			signal?.removeEventListener("abort", abortRun);
+		}
+	};
+
+	pi.registerTool({
+		name: "pi_pr_update_branch",
+		label: "Update PR Branch",
+		description: "Run one guarded action for the /pr branch-update route.",
+		parameters: UpdateBranchParameters,
+		executionMode: "sequential",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			return executeWorkflowAction(params.runId, "update-branch", ctx, signal, async (selected) => {
+				switch (params.action) {
+					case "merge": return await selected.workflow.merge();
+					case "continue": return await selected.workflow.continue(params.resolvedPaths);
+					case "publish": return await selected.workflow.publish();
+				}
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "pi_pr_create",
+		label: "Create Pull Request",
+		description: "Run one guarded action for the /pr creation route.",
+		parameters: CreateParameters,
+		executionMode: "sequential",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			return executeWorkflowAction(params.runId, "create", ctx, signal, async (selected) => {
+				switch (params.action) {
+					case "prepare": return await selected.workflow.prepare(selected.base);
+					case "merge": return await selected.workflow.merge();
+					case "continue": return await selected.workflow.continue(params.resolvedPaths);
+					case "push": return await selected.workflow.push();
+					case "publish": return await selected.workflow.publish(params.title, params.body);
+				}
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "pi_pr_sweep",
+		label: "Sweep PR Feedback",
+		description: "Run one guarded action for the /pr feedback route.",
+		parameters: SweepParameters,
+		executionMode: "sequential",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			return executeWorkflowAction(params.runId, "sweep", ctx, signal, async (selected) => {
+				switch (params.action) {
+					case "start": return await selected.workflow.start();
+					case "resume": return await selected.workflow.resume();
+					case "show": return await selected.workflow.show(params.guard, params.id);
+					case "record": return await selected.workflow.record(params.guard, params.ledger, params.ownedPaths);
+					case "publish": return await selected.workflow.publish(params.guard);
+					case "refresh": return await selected.workflow.refresh(params.guard);
+					case "resolve": return await selected.workflow.resolve(params.guard, params.threadIds);
+					case "finalize": return await selected.workflow.finalize(params.guard, params.projection, params.checks);
+				}
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "pi_pr_fix_ci",
+		label: "Fix PR CI",
+		description: "Run one guarded action for the /pr failed-CI route.",
+		parameters: FixCiParameters,
+		executionMode: "sequential",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			return executeWorkflowAction(params.runId, "fix-ci", ctx, signal, async (selected) => {
+				switch (params.action) {
+					case "collect": return await selected.workflow.collect();
+					case "publish": return await selected.workflow.publish();
+				}
+			});
+		},
+	});
+
 	const setWidget = (ctx: ExtensionContext, display: PrDisplay | undefined): void => {
 		stopRoutingSpinner();
 		widgetKind = "presentation";
@@ -219,7 +575,6 @@ export default function pullRequestExtension(
 	const render = (
 		ctx: ExtensionContext,
 		discovery: Awaited<ReturnType<typeof loadCurrentPullRequest>>,
-		localCommit: boolean,
 	): void => {
 		if (discovery.kind === "inactive") {
 			if (timer !== undefined) clearInterval(timer);
@@ -231,7 +586,7 @@ export default function pullRequestExtension(
 			reconcileWidget(ctx);
 			return;
 		}
-		const display = projectPrDisplay(discovery, localCommit);
+		const display = projectPrDisplay(discovery);
 		const footer = formatPrFooter(display, ctx.ui.theme);
 		if ((discovery.kind === "current" || discovery.kind === "blocked") && footer === undefined) {
 			throw new Error("Pull request display is missing a footer");
@@ -267,9 +622,9 @@ export default function pullRequestExtension(
 		lastBlockedIssueKey = undefined;
 		delegatedWorkPending = false;
 		pendingWorkspaceRename = false;
-		mergeCompleted = false;
 		displayedWidget = undefined;
 		commandGeneration = 0;
+		clearWorkflow(workflowContext);
 		activeInvocations.clear();
 		stopRoutingSpinner();
 		widgetKind = "presentation";
@@ -313,21 +668,17 @@ export default function pullRequestExtension(
 		active = controller;
 		try {
 			let discovery: Awaited<ReturnType<typeof loadCurrentPullRequest>>;
-			let localCommit = false;
 			try {
 				discovery = await load(pi, loadContext);
 				if (controller.signal.aborted || sessionGeneration !== generation) return;
-				if (discovery.kind === "none") {
-					localCommit = !mergeCompleted && await detectLocalCommit(pi, loadContext);
-				}
 			} catch {
-				// Keep an established display. A cold Git-worktree failure gets a sanitized placeholder.
+				// Keep an established footer. A refresh failure must not leave a stale action hint.
 				if (!controller.signal.aborted && sessionGeneration === generation) {
+					displayedWidget = undefined;
+					reconcileWidget(ctx);
 					if (!displayEstablished) {
 						const unavailable = unavailablePrDisplay();
-						displayedWidget = undefined;
 						ctx.ui.setStatus(UI_KEY, formatPrFooter(unavailable, ctx.ui.theme));
-						reconcileWidget(ctx);
 						displayEstablished = true;
 					}
 					reportRefreshFailure();
@@ -335,7 +686,7 @@ export default function pullRequestExtension(
 				return;
 			}
 			if (controller.signal.aborted || sessionGeneration !== generation) return;
-			render(ctx, discovery, localCommit);
+			render(ctx, discovery);
 			refreshFailureReported = false;
 
 			const pullRequest = discovery.kind === "current" ? discovery.pullRequest : undefined;
@@ -372,6 +723,13 @@ export default function pullRequestExtension(
 		queued = false;
 	};
 
+	pi.on("before_agent_start", (event) => {
+		const selected = workflowContext;
+		if (selected?.queuedPrompt && matchesWorkflowPrompt(event.prompt, selected.queuedPrompt)) {
+			selected.queuedPrompt = undefined;
+		}
+	});
+
 	pi.on("session_start", async (_event, ctx) => {
 		stop();
 		const generation = sessionGeneration;
@@ -388,19 +746,33 @@ export default function pullRequestExtension(
 
 	pi.on("agent_settled", async (_event, ctx) => {
 		if (!ctx.hasUI || !ctx.isIdle() || !context) return;
+		const selected = workflowContext;
+		const helperSettled = selected?.usedSinceSettlement ?? false;
+		const queuedHelperPending = selected?.queuedPrompt !== undefined && !helperSettled;
 		let workflowSettled = false;
 		let createWorkflowSettled = false;
 		for (const [invocation, phase] of activeInvocations) {
 			if (phase !== "workflow" && phase !== "create-workflow") continue;
+			if (queuedHelperPending) continue;
 			activeInvocations.delete(invocation);
 			workflowSettled = true;
 			if (phase === "create-workflow") createWorkflowSettled = true;
 		}
+		if (selected) {
+			const conflictPending = (selected.route === "create" || selected.route === "update-branch") &&
+				selected.workflow.state.phase === "conflict-awaiting-user";
+			if (!queuedHelperPending) {
+				if (helperSettled && conflictPending && !selected.conflictRetained) {
+					selected.usedSinceSettlement = false;
+					selected.conflictRetained = true;
+				} else clearWorkflow(selected);
+			}
+		}
 		const delegatedRefresh = delegatedWorkPending && lastDiscovery !== "inactive";
 		delegatedWorkPending = false;
-		if (!workflowSettled && !delegatedRefresh) return;
+		if (!workflowSettled && !helperSettled && !delegatedRefresh) return;
 		cancelRefresh();
-		if (createWorkflowSettled) pendingWorkspaceRename = true;
+		if (createWorkflowSettled || helperSettled && selected?.route === "create") pendingWorkspaceRename = true;
 		await refresh().catch(reportRefreshFailure);
 	});
 
@@ -410,28 +782,40 @@ export default function pullRequestExtension(
 		if (!isBashToolResult(event)) return;
 		const command = event.input.command;
 		if (typeof command === "string" && (GH_PR_CREATE.test(command) || GIT_COMMIT.test(command) || GIT_PUSH.test(command))) {
-			if (GIT_COMMIT.test(command)) mergeCompleted = false;
 			await refresh().catch(reportRefreshFailure);
 		}
 	});
 
-	const commandHandler = createCommandHandler(pi, { loadCurrentPullRequest: load });
+	const commandHandler = createCommandHandler(pi, {
+		loadCurrentPullRequest: load,
+		reserveWorkflow,
+		markWorkflowPromptQueued,
+		releaseWorkflow,
+	});
 	pi.registerCommand("pr", {
-		description: "[instructions] — Run the current branch pull request next step",
+		description: "[--base <branch>] [instructions] — Run the current branch pull request next step",
 		handler: async (args, ctx) => {
 			if (!ctx.hasUI || !context) return;
 			const generation = sessionGeneration;
 			const invocation = ++commandGeneration;
 			activeInvocations.set(invocation, "routing");
 			reconcileWidget(ctx);
-			const routeResolved = (): void => {
+			const routeResolved = (_nextStep?: unknown): void => {
 				if (sessionGeneration !== generation || activeInvocations.get(invocation) !== "routing") return;
 				activeInvocations.set(invocation, "resolved");
 				reconcileWidget(ctx);
 			};
+			const commandInvocation: PrCommandInvocation = Object.assign(routeResolved, {
+				sessionGeneration: generation,
+				assertCurrent() {
+					if (sessionGeneration !== generation) {
+						throw new Error("PR command session changed during dispatch");
+					}
+				},
+			});
 			let nextStep: Awaited<ReturnType<typeof commandHandler>>;
 			try {
-				nextStep = await commandHandler(args, ctx, routeResolved);
+				nextStep = await commandHandler(args, ctx, commandInvocation);
 				routeResolved();
 			} catch (error) {
 				if (sessionGeneration === generation) {
@@ -449,7 +833,6 @@ export default function pullRequestExtension(
 				if (nextStep === "create") ctx.ui.setStatus(UI_KEY, undefined);
 				reconcileWidget(ctx);
 			} else {
-				if (nextStep === "merge") mergeCompleted = true;
 				activeInvocations.delete(invocation);
 				refreshInBackground();
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-pr",
-  "version": "3.1.10",
+  "version": "4.0.3",
   "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",
@@ -28,9 +28,11 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.85.1",
-    "@earendil-works/pi-tui": "^0.85.1"
+    "@earendil-works/pi-tui": "^0.85.1",
+    "typebox": "^1.3.15"
   },
   "dependencies": {
+    "@henryqw/pi-config-store": "^1.1.0",
     "@henryqw/pi-herdr": "^0.4.5"
   },
   "repository": {