@henryqw/pi-pr 3.1.9 → 4.0.2

package/extensions/pr.ts

@@ -1,10 +1,23 @@
+import { randomUUID } from "node:crypto";
+import { realpath } from "node:fs/promises";
 import {
 	isBashToolResult,
 	type ExtensionAPI,
 	type ExtensionContext,
 } 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,
@@ -13,6 +26,7 @@ import {
 	samePullRequestObservation,
 	type PullRequestObservation,
 } from "./pr-github.ts";
+import { runChecked, spawnBounded } from "./pr-execution.ts";
 import {
 	discoveryIssueKey,
 	discoveryIssueMessage,
@@ -22,8 +36,12 @@ 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;
+const ROUTING_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const ROUTING_WIDGET_TEXT = "Checking pull request…";
 const HERDR_TIMEOUT_MS = 10_000;
 const UI_KEY = "pi-pr";
 const OBSERVATION_ENTRY = "pi-pr-observation";
@@ -32,13 +50,150 @@ 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);
 }
@@ -102,6 +257,12 @@ 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) => {
@@ -130,9 +291,220 @@ export default function pullRequestExtension(
 	let mergeCompleted = false;
 	let displayedWidget: PrDisplay | undefined;
 	let commandGeneration = 0;
-	const activeInvocations = new Map<number, "routing" | "create-workflow" | "workflow">();
+	let workflowContext: WorkflowContext | undefined;
+	const activeInvocations = new Map<number, "routing" | "resolved" | "create-workflow" | "workflow">();
+	let widgetKind: "presentation" | "routing" = "presentation";
+	let routingSpinnerFrame = 0;
+	let routingSpinnerTimer: ReturnType<typeof setInterval> | undefined;
+	let routingSpinnerTui: TUI | undefined;
+	let routingSpinnerComponent: (Component & { dispose(): void }) | undefined;
+
+	const stopRoutingSpinner = (): void => {
+		if (routingSpinnerTimer !== undefined) clearInterval(routingSpinnerTimer);
+		routingSpinnerTimer = undefined;
+		routingSpinnerTui = undefined;
+		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";
 		if (display?.widget === undefined) {
 			ctx.ui.setWidget(UI_KEY, undefined);
 			return;
@@ -147,6 +519,57 @@ export default function pullRequestExtension(
 		ctx.ui.setWidget(UI_KEY, formatPrWidget(display));
 	};
 
+	const setRoutingWidget = (ctx: ExtensionContext): void => {
+		if (widgetKind === "routing") return;
+		stopRoutingSpinner();
+		widgetKind = "routing";
+		routingSpinnerFrame = 0;
+		if (ctx.mode !== "tui") {
+			ctx.ui.setWidget(UI_KEY, [`${ROUTING_SPINNER_FRAMES[0]} ${ROUTING_WIDGET_TEXT}`]);
+			return;
+		}
+
+		ctx.ui.setWidget(UI_KEY, (tui, theme) => {
+			let cachedWidth: number | undefined;
+			let cachedLines: string[] | undefined;
+			const component: Component & { dispose(): void } = {
+				invalidate() {
+					cachedWidth = undefined;
+					cachedLines = undefined;
+				},
+				render(width) {
+					if (width <= 0) return [];
+					if (cachedLines !== undefined && cachedWidth === width) return cachedLines;
+					const line = `${theme.fg("accent", ROUTING_SPINNER_FRAMES[routingSpinnerFrame]!)} ${ROUTING_WIDGET_TEXT}`;
+					cachedWidth = width;
+					cachedLines = [truncateToWidth(line, Math.max(1, width))];
+					return cachedLines;
+				},
+				dispose() {
+					if (routingSpinnerComponent !== component) return;
+					stopRoutingSpinner();
+					widgetKind = "presentation";
+				},
+			};
+			routingSpinnerTui = tui;
+			routingSpinnerComponent = component;
+			return component;
+		});
+		routingSpinnerTimer = setInterval(() => {
+			routingSpinnerFrame = (routingSpinnerFrame + 1) % ROUTING_SPINNER_FRAMES.length;
+			routingSpinnerComponent?.invalidate();
+			routingSpinnerTui?.requestRender();
+		}, ROUTING_SPINNER_INTERVAL_MS);
+	};
+
+	const reconcileWidget = (ctx: ExtensionContext): void => {
+		if ([...activeInvocations.values()].includes("routing")) {
+			setRoutingWidget(ctx);
+			return;
+		}
+		setWidget(ctx, activeInvocations.size > 0 ? undefined : displayedWidget);
+	};
+
 	const render = (
 		ctx: ExtensionContext,
 		discovery: Awaited<ReturnType<typeof loadCurrentPullRequest>>,
@@ -159,7 +582,7 @@ export default function pullRequestExtension(
 			lastDiscovery = "inactive";
 			displayedWidget = undefined;
 			ctx.ui.setStatus(UI_KEY, undefined);
-			setWidget(ctx, undefined);
+			reconcileWidget(ctx);
 			return;
 		}
 		const display = projectPrDisplay(discovery, localCommit);
@@ -168,9 +591,8 @@ export default function pullRequestExtension(
 			throw new Error("Pull request display is missing a footer");
 		}
 		displayedWidget = display.widget === undefined ? undefined : display;
-		const widget = activeInvocations.size > 0 ? undefined : displayedWidget;
 		ctx.ui.setStatus(UI_KEY, footer);
-		setWidget(ctx, widget);
+		reconcileWidget(ctx);
 		if (discovery.kind === "blocked") {
 			const key = discoveryIssueKey(discovery.issue);
 			if (lastBlockedIssueKey !== key) {
@@ -202,7 +624,10 @@ export default function pullRequestExtension(
 		mergeCompleted = false;
 		displayedWidget = undefined;
 		commandGeneration = 0;
+		clearWorkflow(workflowContext);
 		activeInvocations.clear();
+		stopRoutingSpinner();
+		widgetKind = "presentation";
 		if (timer !== undefined) clearInterval(timer);
 		timer = undefined;
 		active?.abort();
@@ -255,8 +680,9 @@ export default function pullRequestExtension(
 				if (!controller.signal.aborted && sessionGeneration === generation) {
 					if (!displayEstablished) {
 						const unavailable = unavailablePrDisplay();
+						displayedWidget = undefined;
 						ctx.ui.setStatus(UI_KEY, formatPrFooter(unavailable, ctx.ui.theme));
-						setWidget(ctx, undefined);
+						reconcileWidget(ctx);
 						displayEstablished = true;
 					}
 					reportRefreshFailure();
@@ -301,6 +727,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;
@@ -317,19 +750,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);
 	});
 
@@ -344,25 +791,42 @@ export default function pullRequestExtension(
 		}
 	});
 
-	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=<host>/<owner>/<repository>:<ref>] — 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");
-			if (displayedWidget !== undefined) setWidget(ctx, undefined);
+			reconcileWidget(ctx);
+			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);
+				nextStep = await commandHandler(args, ctx, commandInvocation);
+				routeResolved();
 			} catch (error) {
 				if (sessionGeneration === generation) {
 					cancelRefresh();
 					activeInvocations.delete(invocation);
-					if (!activeInvocations.size) {
-						setWidget(ctx, displayedWidget);
-					}
+					reconcileWidget(ctx);
 					refreshInBackground();
 				}
 				throw error;
@@ -372,7 +836,7 @@ export default function pullRequestExtension(
 			if (WORKFLOW_ROUTES.has(nextStep)) {
 				activeInvocations.set(invocation, nextStep === "create" ? "create-workflow" : "workflow");
 				if (nextStep === "create") ctx.ui.setStatus(UI_KEY, undefined);
-				setWidget(ctx, undefined);
+				reconcileWidget(ctx);
 			} else {
 				if (nextStep === "merge") mergeCompleted = true;
 				activeInvocations.delete(invocation);

package/package.json

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