@henryqw/pi-pr 4.0.7 → 4.0.10

package/README.md

@@ -36,6 +36,8 @@ GitHub, use the network, or write files.
 
 **Requires.** [`@henryqw/pi-herdr`](https://pi.henry.wang/extensions/pi-herdr) is the shared Herdr CLI client. It installs with this package.
 
+**Uses.** [`@henryqw/pi-process`](https://pi.henry.wang/packages/pi-process) runs bounded child processes. It installs with this package.
+
 **Improves.** [`@henryqw/pi-footer`](https://pi.henry.wang/extensions/pi-footer) shows current-branch pull-request status in the footer.
 
 ## Use
@@ -44,9 +46,12 @@ Run `/pr` in a GitHub checkout. It reads fresh pull request and local state, the
 
 For creation, put an optional base branch first. For example, run `/pr --base release/2026 Keep the title concise.` The base is a branch name, not a host or repository. Only creation accepts the base and remaining guidance. Other routes reject them instead of ignoring them.
 
+Run `/pr --feedback` to explicitly start or resume a feedback sweep. Use it for actionable conversation comments that do not select the sweep automatically. It cannot be combined with a base, other options, or instructions.
+
 | Surface | Type | Purpose |
 | --- | --- | --- |
 | `/pr [--base BRANCH] [creation instructions]` | command | Run the current pull request's next safe route. |
+| `/pr --feedback` | command | Explicitly start or resume the guarded feedback sweep. |
 | Footer | ui | Show a linked `PR #number` and one plain-language status. |
 | Widget | ui | Show one action hint or transient routing status. |
 
@@ -64,17 +69,18 @@ Each footer entry is one linked `PR #number` plus one plain-language status: `N
 
 | Current condition | `/pr` route |
 | --- | --- |
-| No current-branch pull request, no published matching ref, safe Git push configuration, and a commit ahead of the selected base | Start pull-request creation. |
+| No current-branch pull request, no published matching ref, safe Git push configuration, and a commit or ordinary pending work | Start pull-request creation. |
 | One open pull request inferred from a published matching ref | Confirm the exact `remote/ref`, then link the local branch. |
 | Ambiguous or unsafe discovery | Show the blocked reason and do not mutate Git or GitHub. |
 | 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 | Start or resume the package comment sweep when the same local prerequisite holds. |
+| Explicit `/pr --feedback` on an open, configured pull request | Start or resume the sweep when the tree is clean and local HEAD equals the PR head. |
 | 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. If the current branch is the selected base, pi-pr stays silent because GitHub cannot create a pull request from a ref to itself.
+`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 a commit ahead or ordinary pending work, including untracked files. A Git operation in progress does not count as pending work. 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.
 
@@ -92,6 +98,8 @@ Each helper workflow receives a random run ID and its first action. The run stay
 
 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.
 
+`/pr --feedback` uses the same discovery, reservation, recovery, and guard checks. It can select the sweep even when CI failure or merge readiness would otherwise select another route. Without the flag, route priority stays unchanged.
+
 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.
@@ -121,7 +129,7 @@ A missing pull request uses creation. For an existing pull request, the first ma
 5. Waiting or local safety block: no action.
 6. Merge-ready: allow clean local HEAD equal to or behind the PR head. Confirm, then merge directly.
 
-Ordinary conversation comments do not trigger a route or block a merge. Changes requested and unresolved review threads can select the package comment sweep.
+Ordinary conversation comments do not trigger a route or block a merge. Changes requested and unresolved review threads can select the package comment sweep. Use `/pr --feedback` when a conversation comment needs action.
 
 The comment sweep resolves its bundled helper and references from the installed package skill path. It does not require an external `jq` executable.
 
@@ -137,7 +145,7 @@ The footer and widget load once at session start. A directory outside a Git work
 
 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, 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.
+The create widget stays hidden on a clean branch with no commit ahead. It appears for a commit ahead or ordinary pending work. It stays hidden during a Git operation and when the current branch is the selected base. `/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.
 
@@ -151,7 +159,7 @@ The GitHub response must match the observed URL, host, repository, head ref, hea
 
 ## Limits and recovery
 
-- `/pr` accepts creation syntax only as a leading `--base BRANCH`, followed by optional creation guidance. It does not open a browser.
+- `/pr` accepts either standalone `--feedback` or creation syntax with leading `--base BRANCH` and optional guidance. It rejects unknown or conflicting options. 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 starts or resumes only when an explicit `/pr` selects it.
 - It does not enable auto-merge or add a merge queue.

package/extensions/pr-ci.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { spawnBounded, type Exec, type ExecOptions } from "@henryqw/pi-process";
 import {
 	loadCurrentPullRequest,
 	readValidatedRemoteAuthority,
@@ -15,10 +16,7 @@ import {
 	requiredOid,
 	requiredText,
 	runChecked,
-	spawnBounded,
 	withWorktreeLock,
-	type Exec,
-	type ExecOptions,
 } from "./pr-execution.ts";
 
 const PAGE_BYTES = 512 * 1024;

package/extensions/pr-command.ts

@@ -11,8 +11,11 @@ import {
 } from "./pr-github.ts";
 import {
 	deriveNextStep,
+	deriveRouteDecision,
+	type FeedbackRouteBlocker,
 	type NextStep,
 	type PullRequestTarget,
+	type RouteIntent,
 } from "./pr-routing.ts";
 
 export type WorkflowNextStep = Extract<NextStep, "create" | "update-branch" | "sweep" | "fix-ci">;
@@ -61,18 +64,42 @@ export type PrCommandDependencies = {
 
 type ParsedPrArguments = {
 	base?: string;
+	intent: RouteIntent;
 	instructions: string;
 };
 
 function parsePrArguments(args: string): ParsedPrArguments {
 	const leading = args.trimStart();
+	const trimmed = leading.trim();
+	if (leading.startsWith("--feedback=")) throw new Error("/pr feedback syntax is --feedback");
+	if (/^--feedback(?:\s|$)/.test(leading)) {
+		if (trimmed !== "--feedback") throw new Error("/pr --feedback cannot be combined with other options or instructions");
+		return { intent: "feedback", instructions: "" };
+	}
+	if (/(?:^|\s)--feedback(?=\s|=|$)/.test(leading)) {
+		throw new Error("/pr --feedback cannot be combined with other options or instructions");
+	}
 	if (leading.startsWith("--base=")) throw new Error("/pr base syntax is --base <branch>");
-	if (!leading.startsWith("--base") || !/^--base(?:\s|$)/.test(leading)) {
-		return { instructions: args.trim() };
+	if (/^--base(?:\s|$)/.test(leading)) {
+		const value = /^--base\s+(\S+)/.exec(leading);
+		if (!value) throw new Error("/pr --base requires a branch");
+		const instructions = leading.slice(value[0].length).trim();
+		if (instructions.startsWith("--")) throw new Error(`Unknown /pr option: ${instructions.split(/\s+/, 1)[0]}`);
+		return { base: value[1]!, intent: "automatic", instructions };
+	}
+	if (leading.startsWith("--")) throw new Error(`Unknown /pr option: ${leading.split(/\s+/, 1)[0]}`);
+	return { intent: "automatic", instructions: args.trim() };
+}
+
+function feedbackBlockerMessage(blocker: FeedbackRouteBlocker): string {
+	switch (blocker.kind) {
+		case "discovery-blocked": return "/pr --feedback is blocked because pull request discovery is unsafe";
+		case "pull-request-unavailable": return "/pr --feedback requires a current pull request";
+		case "pull-request-not-open": return "/pr --feedback requires an open pull request";
+		case "target-not-configured": return "/pr --feedback requires a configured pull request target; run /pr to link the branch first";
+		case "worktree-dirty": return "/pr --feedback is blocked by a dirty worktree";
+		case "head-not-equal": return `/pr --feedback is blocked by local HEAD ${blocker.relation}`;
 	}
-	const value = /^--base\s+(\S+)/.exec(leading);
-	if (!value) throw new Error("/pr --base requires a branch");
-	return { base: value[1]!, instructions: leading.slice(value[0].length).trim() };
 }
 
 function workflowReservation(
@@ -257,11 +284,13 @@ export function createPrCommandHandler(
 		const commandInvocation = onRouteResolved && "assertCurrent" in onRouteResolved
 			? onRouteResolved as PrCommandInvocation
 			: undefined;
-		const { base, instructions } = parsePrArguments(args);
+		const { base, intent, instructions } = parsePrArguments(args);
 		const discovery = await load(pi, ctx, undefined, undefined, base);
 		commandInvocation?.assertCurrent();
-		const nextStep = deriveNextStep(discovery);
+		const decision = deriveRouteDecision(discovery, intent);
+		const nextStep = decision.nextStep;
 		onRouteResolved?.(nextStep);
+		if (decision.kind === "feedback-blocked") throw new Error(feedbackBlockerMessage(decision.blocker));
 		if (base !== undefined && nextStep !== "create") {
 			throw new Error("/pr --base is accepted only for pull request creation");
 		}

package/extensions/pr-comment-sweep.ts

@@ -1,7 +1,8 @@
 import { createHash, randomUUID } from "node:crypto";
-import { lstat, realpath, rm } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { realpath, rm } from "node:fs/promises";
+import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { spawnBounded, type Exec, type ExecOptions } from "@henryqw/pi-process";
 import {
 	extensionConfigDir,
 	readTextFileBounded,
@@ -27,6 +28,7 @@ import {
 	type PullRequestLoadContext,
 } from "./pr-github.ts";
 import {
+	inspectGitOperation,
 	isAncestor,
 	parseNulPaths,
 	parseStatusSnapshot,
@@ -35,18 +37,14 @@ import {
 	requiredOid,
 	requiredText,
 	runChecked,
-	spawnBounded,
 	withWorktreeLock,
 	type AttemptState,
-	type Exec,
-	type ExecOptions,
 } from "./pr-execution.ts";
 
 export const SWEEP_RECOVERY_MAX_BYTES = 1024 * 1024;
 
 const STATE_VERSION = 1;
 const STATE_FILE = "state.json";
-const GIT_OPERATION_STATES = ["MERGE_HEAD", "rebase-merge", "rebase-apply", "CHERRY_PICK_HEAD", "REVERT_HEAD", "sequencer"];
 const LEDGER_NOTE_MAX_BYTES = 2 * 1024;
 const CHECK_MAX_COUNT = 32;
 const CHECK_ARGUMENTS_MAX_BYTES = 32 * 1024;
@@ -640,23 +638,8 @@ export class PullRequestCommentSweep {
 	}
 
 	private async requireNoGitOperation(): Promise<void> {
-		const paths = await runChecked(this.exec, "git", [
-			"rev-parse", ...GIT_OPERATION_STATES.flatMap((state) => ["--git-path", state]),
-		], this.options());
-		const normalized = paths.stdout.replace(/\r\n/g, "\n");
-		const values = (normalized.endsWith("\n") ? normalized.slice(0, -1) : normalized).split("\n");
-		if (values.length !== GIT_OPERATION_STATES.length || values.some((path) => !path)) {
-			throw new Error("Git operation state path resolution returned invalid output");
-		}
-		for (const [index, path] of values.entries()) {
-			try {
-				await lstat(resolve(this.cwd, path));
-				throw new Error(`${GIT_OPERATION_STATES[index]} is in progress`);
-			} catch (error) {
-				if (error && typeof error === "object" && (error as NodeJS.ErrnoException).code === "ENOENT") continue;
-				throw error;
-			}
-		}
+		const operation = await inspectGitOperation(this.exec, this.options());
+		if (operation !== null) throw new Error(`${operation} is in progress`);
 	}
 
 	private async localPaths(): Promise<string[]> {

package/extensions/pr-create.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { spawnBounded, type Exec, type ExecOptions } from "@henryqw/pi-process";
 import {
 	branchTrackingRef,
 	fetchBranchTrackingRef,
@@ -15,7 +16,10 @@ import {
 	type PullRequestLoadContext,
 	type PullRequestPublication,
 } from "./pr-github.ts";
-import type { PullRequestTarget } from "./pr-routing.ts";
+import {
+	isPullRequestCreationEligible,
+	type PullRequestTarget,
+} from "./pr-routing.ts";
 import {
 	assertOnlyDeclaredStatusChanged,
 	inspectWorktree,
@@ -26,10 +30,7 @@ import {
 	requiredOid,
 	requiredText,
 	runChecked,
-	spawnBounded,
 	withWorktreeLock,
-	type Exec,
-	type ExecOptions,
 } from "./pr-execution.ts";
 
 const MAX_TITLE_BYTES = 256;
@@ -221,13 +222,14 @@ export class PullRequestCreator {
 		return { cwd: this.cwd, signal: this.signal ?? new AbortController().signal };
 	}
 
-	private async freshNone(): Promise<void> {
+	private async freshNone() {
 		const discovery = await this.load(this.pi(), this.context(), undefined, undefined, this.explicitBase);
 		if (discovery.kind !== "none" || !sameTarget(this.target, discovery.creationTarget)) {
 			throw new Error("PR creation cancelled: fresh complete discovery is no longer none");
 		}
 		const branch = line((await runChecked(this.exec, "git", ["branch", "--show-current"], this.options())).stdout, "current branch");
 		if (branch !== this.target.branch) throw new Error("PR creation cancelled: current branch changed");
+		return discovery;
 	}
 
 	private async liveBase(): Promise<string> {
@@ -270,8 +272,11 @@ export class PullRequestCreator {
 				this.target,
 				this.explicitBase,
 			);
-			if (preflight.ahead === 0) {
-				throw new Error("PR creation requires at least one commit ahead of the selected base");
+			if (preflight.worktree === "operation") {
+				throw new Error("PR creation cannot prepare while a Git operation is in progress");
+			}
+			if (!isPullRequestCreationEligible({ ...preflight, relation: "distinct-ref" })) {
+				throw new Error("PR creation requires at least one commit ahead of the selected base or pending work");
 			}
 			const { base } = preflight;
 			this.state.base = {
@@ -286,11 +291,14 @@ export class PullRequestCreator {
 				"fetch", "--no-write-fetch-head", "--no-tags", "--no-recurse-submodules", base.fetchSource, base.oid,
 			], this.options());
 			await runChecked(this.exec, "git", ["cat-file", "-e", `${base.oid}^{commit}`], this.options());
-			await this.freshNone();
+			const fresh = await this.freshNone();
 			if (await readHead(this.exec, this.options()) !== preflight.head) {
 				throw new Error("PR creation cancelled: local HEAD changed during prepare");
 			}
 			if (await this.liveBase() !== base.oid) throw new Error("PR creation cancelled: base ref moved during prepare");
+			if (!isPullRequestCreationEligible(fresh.branch)) {
+				throw new Error("PR creation cancelled: branch no longer has a committed change or pending work");
+			}
 			this.state.phase = "prepared";
 			return { kind: "prepared", base: { ...this.state.base }, mergeBase: base.mergeBase };
 		}, { agentDir: this.agentDir, signal: this.signal });

package/extensions/pr-execution.ts

@@ -1,47 +1,20 @@
 import { createHash } from "node:crypto";
 import { lstat, mkdir, realpath } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { spawn } from "node:child_process";
 import { extensionConfigDir } from "@henryqw/pi-config-store";
+import { spawnBounded, type Exec, type ExecOptions, type ExecResult } from "@henryqw/pi-process";
 import { lock } from "proper-lockfile";
 
-export const DEFAULT_EXEC_TIMEOUT_MS = 30_000;
-export const DEFAULT_OUTPUT_LIMIT_BYTES = 64 * 1024;
 export const MAX_CONFLICT_PATHS = 128;
 export const MAX_CONFLICT_PATH_BYTES = 1_024;
 export const MAX_CONFLICT_PATHS_BYTES = 32 * 1024;
 
 const OID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 const GIT_OPERATION_STATES = ["MERGE_HEAD", "rebase-merge", "rebase-apply", "CHERRY_PICK_HEAD", "REVERT_HEAD", "sequencer"];
-const PROCESS_TERMINATION_GRACE_MS = 250;
 const WORKTREE_LOCK_OPTIONS = { realpath: false, stale: 30_000, update: 5_000, retries: 0 } as const;
 
-export type ExecResult = {
-	stdout: string;
-	stderr: string;
-	code: number;
-	killed: boolean;
-	stdoutTruncated?: boolean;
-};
-
-export type ExecOptions = {
-	cwd: string;
-	signal?: AbortSignal;
-	timeoutMs?: number;
-	stdoutLimitBytes?: number;
-	stdoutTailBytes?: number;
-	stderrLimitBytes?: number;
-	stdin?: string;
-};
-
-export type Exec = (command: string, args: string[], options: ExecOptions) => Promise<ExecResult>;
-
 export type AttemptState = "none" | "attempting" | "applied" | "blocked" | "unknown";
-
-function positiveInteger(value: number, label: string): number {
-	if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${label} must be a positive safe integer`);
-	return value;
-}
+export type GitWorktreeState = "clean" | "dirty" | "operation";
 
 export function requiredText(value: unknown, label: string): string {
 	if (typeof value !== "string" || !value || value.trim() !== value || /[\u0000-\u001f\u007f]/.test(value)) {
@@ -56,167 +29,6 @@ export function requiredOid(value: unknown, label: string): string {
 	return parsed;
 }
 
-function validatedArguments(args: string[]): string[] {
-	if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string" || arg.includes("\0"))) {
-		throw new TypeError("command arguments must be an array of strings without NUL bytes");
-	}
-	return args;
-}
-
-function decode(chunks: Buffer[], bytes: number, label: string): string {
-	try {
-		return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks, bytes));
-	} catch {
-		throw new Error(`${label} was not valid UTF-8`);
-	}
-}
-
-/** Run one argv-only child process with bounded streaming output, cancellation, and a deadline. */
-export const spawnBounded: Exec = async (command, args, options) => {
-	requiredText(command, "command");
-	validatedArguments(args);
-	requiredText(options.cwd, "cwd");
-	options.signal?.throwIfAborted();
-	const timeoutMs = positiveInteger(options.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS, "timeoutMs");
-	const stdoutLimit = positiveInteger(options.stdoutLimitBytes ?? DEFAULT_OUTPUT_LIMIT_BYTES, "stdoutLimitBytes");
-	const stdoutTailLimit = options.stdoutTailBytes === undefined
-		? undefined
-		: positiveInteger(options.stdoutTailBytes, "stdoutTailBytes");
-	const stderrLimit = positiveInteger(options.stderrLimitBytes ?? DEFAULT_OUTPUT_LIMIT_BYTES, "stderrLimitBytes");
-	if (options.stdin !== undefined && typeof options.stdin !== "string") throw new TypeError("stdin must be a string");
-
-	return await new Promise<ExecResult>((resolve, reject) => {
-		const child = spawn(command, args, {
-			cwd: options.cwd,
-			detached: process.platform !== "win32",
-			env: process.env,
-			stdio: ["pipe", "pipe", "pipe"],
-		});
-		const childPid = child.pid;
-		const processGroup = process.platform !== "win32" && typeof childPid === "number" &&
-			Number.isSafeInteger(childPid) && childPid > 0 ? childPid : null;
-		const stdout: Buffer[] = [];
-		const stderr: Buffer[] = [];
-		const stdoutDecoder = stdoutTailLimit === undefined
-			? undefined
-			: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
-		let stdoutBytes = 0;
-		let stdoutTruncated = false;
-		let stderrBytes = 0;
-		let failure: Error | undefined;
-		let killed = false;
-		let settled = false;
-		let killTimer: ReturnType<typeof setTimeout> | undefined;
-
-		const signalChild = (signal: NodeJS.Signals): void => {
-			if (processGroup !== null) {
-				try {
-					process.kill(-processGroup, signal);
-					killed = true;
-					return;
-				} catch (error) {
-					if (error && typeof error === "object" && (error as NodeJS.ErrnoException).code === "ESRCH") return;
-				}
-			}
-			killed = child.kill(signal) || killed;
-		};
-		const stop = (error: Error): void => {
-			if (failure) return;
-			failure = error;
-			signalChild("SIGTERM");
-			killTimer = setTimeout(() => signalChild("SIGKILL"), PROCESS_TERMINATION_GRACE_MS);
-		};
-		const appendTail = (text: string): void => {
-			if (!text || stdoutTailLimit === undefined) return;
-			const chunk = Buffer.from(text, "utf8");
-			stdout.push(chunk);
-			stdoutBytes += chunk.length;
-			if (stdoutBytes <= stdoutTailLimit) return;
-			stdoutTruncated = true;
-			let remove = stdoutBytes - stdoutTailLimit;
-			while (remove > 0) {
-				const first = stdout[0]!;
-				if (first.length <= remove) {
-					stdout.shift();
-					stdoutBytes -= first.length;
-					remove -= first.length;
-					continue;
-				}
-				let start = remove;
-				while (start < first.length && (first[start]! & 0xc0) === 0x80) start += 1;
-				stdout[0] = Buffer.from(first.subarray(start));
-				stdoutBytes -= start;
-				remove = 0;
-			}
-		};
-		const decodeTail = (chunk?: Buffer): void => {
-			if (!stdoutDecoder) return;
-			try {
-				appendTail(chunk === undefined ? stdoutDecoder.decode() : stdoutDecoder.decode(chunk, { stream: true }));
-			} catch {
-				stop(new Error(`${command} stdout was not valid UTF-8`));
-			}
-		};
-		const timer = setTimeout(() => stop(new Error(`${command} timed out after ${timeoutMs}ms`)), timeoutMs);
-		const abort = (): void => stop(options.signal?.reason instanceof Error
-			? options.signal.reason
-			: new DOMException("The operation was aborted", "AbortError"));
-		options.signal?.addEventListener("abort", abort, { once: true });
-		if (options.signal?.aborted) abort();
-
-		child.stdout.on("data", (chunk: Buffer) => {
-			if (failure) return;
-			if (stdoutDecoder) {
-				decodeTail(chunk);
-				return;
-			}
-			stdoutBytes += chunk.length;
-			if (stdoutBytes > stdoutLimit) {
-				stop(new Error(`${command} stdout exceeded ${stdoutLimit} bytes`));
-				return;
-			}
-			stdout.push(chunk);
-		});
-		child.stderr.on("data", (chunk: Buffer) => {
-			if (failure) return;
-			stderrBytes += chunk.length;
-			if (stderrBytes > stderrLimit) {
-				stop(new Error(`${command} stderr exceeded ${stderrLimit} bytes`));
-				return;
-			}
-			stderr.push(chunk);
-		});
-		child.once("error", stop);
-		child.once("close", (code, signal) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timer);
-			if (killTimer !== undefined && processGroup === null) clearTimeout(killTimer);
-			options.signal?.removeEventListener("abort", abort);
-			if (!failure && stdoutDecoder) decodeTail();
-			if (failure) {
-				reject(failure);
-				return;
-			}
-			try {
-				resolve({
-					stdout: stdoutDecoder
-						? Buffer.concat(stdout, stdoutBytes).toString("utf8")
-						: decode(stdout, stdoutBytes, `${command} stdout`),
-					stderr: decode(stderr, stderrBytes, `${command} stderr`),
-					code: code ?? 1,
-					killed: killed || signal !== null,
-					...(stdoutDecoder ? { stdoutTruncated } : {}),
-				});
-			} catch (error) {
-				reject(error);
-			}
-		});
-		if (options.stdin === undefined) child.stdin.end();
-		else child.stdin.end(options.stdin, "utf8");
-	});
-};
-
 export function commandText(command: string, args: readonly string[]): string {
 	return [command, ...args].join(" ");
 }
@@ -236,9 +48,8 @@ export async function runChecked(
 	return result;
 }
 
-/** Inspect both porcelain state and Git operation markers without mutating the repository. */
-export async function inspectWorktree(exec: Exec, options: ExecOptions): Promise<"clean" | "dirty"> {
-	const status = await runChecked(exec, "git", ["status", "--porcelain=v1", "--untracked-files=all"], options);
+/** Return the active Git operation marker without mutating the repository. */
+export async function inspectGitOperation(exec: Exec, options: ExecOptions): Promise<string | null> {
 	const stateOutput = await runChecked(exec, "git", [
 		"rev-parse",
 		...GIT_OPERATION_STATES.flatMap((state) => ["--git-path", state]),
@@ -251,7 +62,7 @@ export async function inspectWorktree(exec: Exec, options: ExecOptions): Promise
 	for (const [index, path] of statePaths.entries()) {
 		try {
 			await lstat(resolve(options.cwd, path));
-			return "dirty";
+			return GIT_OPERATION_STATES[index]!;
 		} catch (error) {
 			if (error && typeof error === "object" && (error as NodeJS.ErrnoException).code === "ENOENT") continue;
 			const code = error && typeof error === "object" && typeof (error as NodeJS.ErrnoException).code === "string"
@@ -260,9 +71,21 @@ export async function inspectWorktree(exec: Exec, options: ExecOptions): Promise
 			throw new Error(`Git operation state inspection failed for ${GIT_OPERATION_STATES[index]}: ${code}`);
 		}
 	}
+	return null;
+}
+
+/** Distinguish ordinary pending work from an in-progress Git operation. */
+export async function inspectWorktreeState(exec: Exec, options: ExecOptions): Promise<GitWorktreeState> {
+	const status = await runChecked(exec, "git", ["status", "--porcelain=v1", "--untracked-files=all"], options);
+	if (await inspectGitOperation(exec, options) !== null) return "operation";
 	return status.stdout === "" ? "clean" : "dirty";
 }
 
+/** Inspect both porcelain state and Git operation markers without mutating the repository. */
+export async function inspectWorktree(exec: Exec, options: ExecOptions): Promise<"clean" | "dirty"> {
+	return await inspectWorktreeState(exec, options) === "clean" ? "clean" : "dirty";
+}
+
 /** Exclude concurrent PR mutations for one canonical worktree and pi-pr namespace. */
 export async function withWorktreeLock<T>(
 	cwd: string,

package/extensions/pr-feedback.ts

@@ -1,10 +1,9 @@
 import { createHash } from "node:crypto";
+import type { Exec, ExecOptions } from "@henryqw/pi-process";
 import {
 	runChecked,
 	requiredOid,
 	requiredText,
-	type Exec,
-	type ExecOptions,
 } from "./pr-execution.ts";
 import type { CurrentPullRequest } from "./pr-github.ts";
 

package/extensions/pr-github.ts

@@ -5,7 +5,11 @@ import type {
 import { lstatSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { inspectLocalMergeSafety } from "./pr-merge.ts";
-import { withWorktreeLock } from "./pr-execution.ts";
+import {
+	inspectWorktreeState,
+	withWorktreeLock,
+	type GitWorktreeState,
+} from "./pr-execution.ts";
 import type {
 	CiStatus,
 	LocalMergeSafety,
@@ -112,10 +116,11 @@ export type PullRequestCreationPreflight = {
 		mergeBase: string;
 	};
 	ahead: number;
+	worktree: GitWorktreeState;
 };
 
 type CreationPreflightResult =
-	| { kind: "same-ref" }
+	| { kind: "same-ref"; worktree: GitWorktreeState }
 	| { kind: "distinct-ref"; preflight: PullRequestCreationPreflight };
 
 type CreationIdentity = {
@@ -1158,6 +1163,24 @@ function parseCreationAhead(output: string): number {
 	return ahead;
 }
 
+async function inspectCreationWorktree(
+	pi: Pick<ExtensionAPI, "exec">,
+	context: PullRequestLoadContext,
+): Promise<GitWorktreeState> {
+	try {
+		return await inspectWorktreeState(
+			async (command, args) => await invoke(pi, context, "Inspect creation worktree", command, args),
+			{ cwd: context.cwd, signal: context.signal },
+		);
+	} catch (error) {
+		if (error instanceof PullRequestLoadError) throw error;
+		return fail(
+			"Inspect creation worktree",
+			error instanceof Error ? error.message : "inspection failed",
+		);
+	}
+}
+
 async function preflightCreation(
 	pi: Pick<ExtensionAPI, "exec">,
 	context: PullRequestLoadContext,
@@ -1176,7 +1199,8 @@ async function preflightCreation(
 		: await validateCreationRef(pi, context, explicitBaseRef);
 	const baseRef = configuredBaseRef ?? await readDefaultCreationBaseRef(pi, context, origin);
 	const relation = await inspectCreationRepositoryRelation(pi, context, identity.target, origin, baseRef);
-	if (relation === "same-ref") return { kind: relation };
+	const worktree = await inspectCreationWorktree(pi, context);
+	if (relation === "same-ref") return { kind: relation, worktree };
 	const trackingRef = `refs/remotes/origin/${baseRef}`;
 	await execute(pi, context, "Fetch creation base", "git", [
 		"fetch", "--no-write-fetch-head", "--no-tags", "--no-recurse-submodules", "--",
@@ -1208,6 +1232,7 @@ async function preflightCreation(
 				mergeBase,
 			},
 			ahead,
+			worktree,
 		},
 	};
 }
@@ -1236,7 +1261,9 @@ async function creationDiscovery(
 	return {
 		kind: "none",
 		creationTarget: target,
-		branch: { ahead: result.kind === "same-ref" ? 0 : result.preflight.ahead },
+		branch: result.kind === "same-ref"
+			? { ahead: 0, worktree: result.worktree, relation: result.kind }
+			: { ahead: result.preflight.ahead, worktree: result.preflight.worktree, relation: result.kind },
 	};
 }
 

package/extensions/pr-merge.ts

@@ -1,10 +1,10 @@
+import type { Exec } from "@henryqw/pi-process";
 import {
 	inspectWorktree,
 	readHead,
 	requiredOid,
 	requiredText,
 	runChecked,
-	type Exec,
 } from "./pr-execution.ts";
 import type { LocalMergeSafety } from "./pr-routing.ts";
 

package/extensions/pr-routing.ts

@@ -40,6 +40,8 @@ export type PullRequestTarget = {
 
 export type BranchCreationState = {
 	ahead: number;
+	worktree: "clean" | "dirty" | "operation";
+	relation: "same-ref" | "distinct-ref";
 };
 
 export type DiscoveryIssue =
@@ -59,6 +61,17 @@ export type PullRequestDiscovery<T extends PullRequest = PullRequest> =
 	| { kind: "inactive" };
 
 export type NextStep = "create" | "link-branch" | "blocked" | "none" | "update-branch" | "sweep" | "fix-ci" | "merge";
+export type RouteIntent = "automatic" | "feedback";
+export type FeedbackRouteBlocker =
+	| { kind: "discovery-blocked" }
+	| { kind: "pull-request-unavailable" }
+	| { kind: "pull-request-not-open" }
+	| { kind: "target-not-configured" }
+	| { kind: "worktree-dirty" }
+	| { kind: "head-not-equal"; relation: Exclude<LocalHeadRelation, "equal"> };
+export type RouteDecision =
+	| { kind: "selected"; nextStep: NextStep }
+	| { kind: "feedback-blocked"; nextStep: "blocked"; blocker: FeedbackRouteBlocker };
 
 function localMutationSafe(local: LocalMergeSafety): boolean {
 	return local.worktree === "clean" && local.head === "equal";
@@ -88,12 +101,52 @@ export function derivePullRequestNextStep(pullRequest: PullRequest): Exclude<Nex
 	return "merge";
 }
 
-export function deriveNextStep(discovery: PullRequestDiscovery<PullRequest & { target: PullRequestTarget }>): NextStep {
+export function isPullRequestCreationEligible(branch: BranchCreationState): boolean {
+	return branch.relation === "distinct-ref" && branch.worktree !== "operation" &&
+		(branch.ahead > 0 || branch.worktree === "dirty");
+}
+
+function deriveAutomaticNextStep(discovery: PullRequestDiscovery<PullRequest & { target: PullRequestTarget }>): NextStep {
 	if (discovery.kind === "inactive") return "none";
 	if (discovery.kind === "blocked") return "blocked";
-	if (discovery.kind === "none") return discovery.branch.ahead > 0 ? "create" : "none";
+	if (discovery.kind === "none") return isPullRequestCreationEligible(discovery.branch) ? "create" : "none";
 	if (discovery.pullRequest.target.provenance === "inferred") {
 		return discovery.pullRequest.lifecycle === "open" ? "link-branch" : "none";
 	}
 	return derivePullRequestNextStep(discovery.pullRequest);
 }
+
+export function deriveRouteDecision(
+	discovery: PullRequestDiscovery<PullRequest & { target: PullRequestTarget }>,
+	intent: RouteIntent = "automatic",
+): RouteDecision {
+	if (intent === "automatic") return { kind: "selected", nextStep: deriveAutomaticNextStep(discovery) };
+	if (discovery.kind === "blocked") {
+		return { kind: "feedback-blocked", nextStep: "blocked", blocker: { kind: "discovery-blocked" } };
+	}
+	if (discovery.kind !== "current") {
+		return { kind: "feedback-blocked", nextStep: "blocked", blocker: { kind: "pull-request-unavailable" } };
+	}
+	const pullRequest = discovery.pullRequest;
+	if (pullRequest.lifecycle !== "open") {
+		return { kind: "feedback-blocked", nextStep: "blocked", blocker: { kind: "pull-request-not-open" } };
+	}
+	if (pullRequest.target.provenance !== "configured") {
+		return { kind: "feedback-blocked", nextStep: "blocked", blocker: { kind: "target-not-configured" } };
+	}
+	if (pullRequest.local.worktree !== "clean") {
+		return { kind: "feedback-blocked", nextStep: "blocked", blocker: { kind: "worktree-dirty" } };
+	}
+	if (pullRequest.local.head !== "equal") {
+		return {
+			kind: "feedback-blocked",
+			nextStep: "blocked",
+			blocker: { kind: "head-not-equal", relation: pullRequest.local.head },
+		};
+	}
+	return { kind: "selected", nextStep: "sweep" };
+}
+
+export function deriveNextStep(discovery: PullRequestDiscovery<PullRequest & { target: PullRequestTarget }>): NextStep {
+	return deriveRouteDecision(discovery).nextStep;
+}

package/extensions/pr-update-branch.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { spawnBounded, type Exec, type ExecOptions } from "@henryqw/pi-process";
 import {
 	loadCurrentPullRequest,
 	samePullRequestSnapshot,
@@ -15,10 +16,7 @@ import {
 	requiredOid,
 	resolveRepositoryFetchSource,
 	runChecked,
-	spawnBounded,
 	withWorktreeLock,
-	type Exec,
-	type ExecOptions,
 } from "./pr-execution.ts";
 
 export type UpdateBranchPhase = "ready" | "conflict-awaiting-user" | "verified" | "published" | "blocked";

package/extensions/pr.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { spawnBounded } from "@henryqw/pi-process";
 import { realpath } from "node:fs/promises";
 import {
 	isBashToolResult,
@@ -26,7 +27,7 @@ import {
 	samePullRequestObservation,
 	type PullRequestObservation,
 } from "./pr-github.ts";
-import { runChecked, spawnBounded } from "./pr-execution.ts";
+import { runChecked } from "./pr-execution.ts";
 import {
 	discoveryIssueKey,
 	discoveryIssueMessage,
@@ -783,7 +784,7 @@ export default function pullRequestExtension(
 		releaseWorkflow,
 	});
 	pi.registerCommand("pr", {
-		description: "[--base <branch>] [instructions] — Run the current branch pull request next step",
+		description: "[--feedback | --base <branch> [instructions]] — Run the current branch pull request next step",
 		handler: async (args, ctx) => {
 			if (!ctx.hasUI || !context) return;
 			const generation = sessionGeneration;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-pr",
-  "version": "4.0.7",
+  "version": "4.0.10",
   "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",
@@ -34,6 +34,7 @@
   "dependencies": {
     "@henryqw/pi-config-store": "^1.1.0",
     "@henryqw/pi-herdr": "^0.4.5",
+    "@henryqw/pi-process": "^0.1.0",
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {

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

@@ -17,10 +17,10 @@ import {
 	loadCurrentPullRequest,
 	samePullRequestSnapshot,
 } from "../../../extensions/pr-github.ts";
+import { spawnBounded } from "@henryqw/pi-process";
 import {
 	inspectWorktree,
 	readHead,
-	spawnBounded,
 } from "../../../extensions/pr-execution.ts";
 
 class UsageError extends Error {}

package/skills/pi-pr-create/SKILL.md

@@ -7,7 +7,7 @@ description: Prepare and publish the current branch pull request with determinis
 
 Use only `pi_pr_create` for base selection, merge, push, upstream, and GitHub work. Do not repeat its Git or GitHub checks with shell tools.
 
-Start with the prompted `prepare` action. It uses the saved branch base: explicit `/pr --base BRANCH`, one `branch.<branch>.gh-merge-base` value, then validated `origin` default. It requires a committed change ahead. Dirty work alone cannot start this route. The base is always `origin`; fork heads must share its GitHub source and host. Apply trailing prompt guidance only to the PR content.
+Start with the prompted `prepare` action. It uses the saved branch base: explicit `/pr --base BRANCH`, one `branch.<branch>.gh-merge-base` value, then validated `origin` default. It requires a committed change ahead or ordinary pending work, including untracked files. It rejects an in-progress Git operation and a head ref equal to the selected base ref. The base is always `origin`; fork heads must share its GitHub source and host. Apply trailing prompt guidance only to the PR content.
 
 After `prepare`, inspect the returned base and merge-base. Separate and commit coherent pending work. Preserve coherent staging. Exclude `.context/` and unrelated changes. Stop when separation is unsafe.