@ferris1225/pi-subagents 4.1.13 → 4.1.16

package/src/widget.ts

@@ -15,6 +15,10 @@ import {
 
 export const SUBAGENTS_WIDGET_ID = "pi-subagents";
 
+/** The TUI caps string-array widgets at this many lines; a factory widget owns
+ * the same bound itself, or a wide parallel dispatch floods the editor area. */
+const MAX_WIDGET_LINES = 10;
+
 /** Keep the elapsed tail visible while clipping the descriptive left side. */
 function compactLine(left: string, right: string, width: number): string {
 	if (width <= 0) return "";
@@ -256,6 +260,11 @@ export function formatActiveRunLines(
 			lines.push(...runActivityLine(child, theme, width, "      "));
 		});
 	}
+	const hidden = lines.length - (MAX_WIDGET_LINES - 1);
+	if (hidden > 0) {
+		lines.length = MAX_WIDGET_LINES - 1;
+		lines.push(theme.fg("dim", `… +${hidden} more (subagent_status)`));
+	}
 	return lines;
 }
 

package/src/workflow.ts

@@ -1,248 +1,199 @@
-/**
- * Managed workflow policy and handoff formatting.
- *
- * Successful top-level worker/cleaner runs continue through an independent
- * code review gate. A passing gate may run one conditional documentation
- * sync; a failing gate is delivered to the main agent, which owns the fix
- * decision — the runtime never edits code on a reviewer's behalf. Reviewers
- * classify documentation drift explicitly, so the low-cost final documenter
- * runs only when needed (or conservatively when an older/custom reviewer
- * omits the marker). Direct passing gates use the same policy. Top-level
- * documenters are explicit standalone writing tasks. Internal steps are
- * launched by dispatch directly, so they never re-enter this policy or wake
- * the main agent mid-chain.
- */
-
-import { isWriteCapableAgent, type AgentConfig } from "./agents.ts";
-import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
-import { formatUsageCompact, sumUsage } from "./monitor.ts";
-
-export interface WorkflowAgentAvailability {
-	cleaner: boolean;
-	documenter: boolean;
-	reviewer: boolean;
-	writer: boolean;
-}
-
-export function workflowAgentAvailability(
-	agents: readonly Pick<AgentConfig, "name" | "tools">[],
-): WorkflowAgentAvailability {
-	const names = new Set(agents.map((agent) => agent.name));
-	return {
-		cleaner: names.has("cleaner"),
-		documenter: names.has("documenter"),
-		reviewer: names.has("reviewer"),
-		writer: agents.some(isWriteCapableAgent),
-	};
-}
-
-export type DocumentationDisposition = "clean" | "needed";
-
-/** Only the last standalone documentation disposition line counts. Inline
- * examples and prose are ignored so a prompt echo cannot suppress a needed
- * conservative sync. */
-export function documentationDisposition(output: string): DocumentationDisposition | undefined {
-	const lines = output.split("\n");
-	for (let index = lines.length - 1; index >= 0; index--) {
-		const match = /^\s*DOCUMENTATION:\s*(CLEAN|NEEDED)\s*$/i.exec(lines[index]);
-		if (match) return match[1].toUpperCase() === "CLEAN" ? "clean" : "needed";
-	}
-	return undefined;
-}
-
-export type ManagedWorkflowKind = "post-writer" | "review-pass-sync";
-
-export interface ManagedWorkflowPlan {
-	kind: ManagedWorkflowKind;
-	initialRelation: string;
-}
-
-/** Conservative pre-run check used to reserve one shared-repository lane
- * around a complete writer workflow or a reviewer that needs a stable diff.
- * The actual result is classified again by getManagedWorkflowPlan before a
- * downstream child starts. */
-export function canStartManagedWorkflow(
-	agent: Pick<AgentConfig, "name" | "tools">,
-	availability: WorkflowAgentAvailability,
-): boolean {
-	// Every shared write-capable role—including custom agents—owns the repository
-	// lane even when no downstream role is enabled. Otherwise its edits can race
-	// a managed writer's documentation snapshot.
-	if (isWriteCapableAgent(agent)) return true;
-	if (agent.name === "reviewer") {
-		// Hold a stable diff snapshot against every discoverable writer even when
-		// this review is advisory. Classification happens only after the read-only
-		// child returns, too late to acquire the lane safely.
-		return availability.writer;
-	}
-	return false;
-}
-
-/** Classify only healthy top-level results. In particular, a reviewer without a
- * machine verdict is advisory and cannot start any write-capable child; a
- * failing gate is not a workflow at all — its findings are delivered to the
- * main agent, which decides the fixes. */
-export function getManagedWorkflowPlan(
-	result: SingleResult,
-	availability: WorkflowAgentAvailability,
-	advisoryReview = false,
-): ManagedWorkflowPlan | undefined {
-	if (result.dispatchFailed || isFailedResult(result)) return undefined;
-	if (result.agent === "worker" || result.agent === "cleaner") {
-		if (!availability.documenter && !availability.reviewer) return undefined;
-		return {
-			kind: "post-writer",
-			initialRelation: result.agent === "cleaner" ? "initial cleanup" : "initial implementation",
-		};
-	}
-	// A top-level documenter is already an explicit docs/comments write task. It
-	// owns the writer lane but delivers directly without an automatic code gate.
-	if (result.agent === "documenter") return undefined;
-	if (result.agent !== "reviewer") return undefined;
-	// An advisory dispatch never chains: the caller asked for a report, so even
-	// a stray gate verdict must be delivered rather than acted on.
-	if (advisoryReview) return undefined;
-
-	const output = getResultOutput(result);
-	// The pass stands as the code gate. Run the conditional documenter only for
-	// explicit drift or when an older/custom reviewer omitted the marker.
-	if (
-		reviewVerdict(output) === "pass" &&
-		availability.documenter &&
-		documentationDisposition(output) !== "clean"
-	) {
-		return { kind: "review-pass-sync", initialRelation: "pre-documentation review" };
-	}
-	return undefined;
-}
-
-/** Build the single documentation handoff selected after the review gate
- * settles or as the reviewer-disabled fallback. The top-level writer's report
- * and the terminal gate review are leads; the pending diff stays authoritative.
- * At most one of the two is undefined in every managed flow. */
-export function buildFinalDocumenterBrief(
-	lastWriterResult?: SingleResult,
-	finalReviewResult?: SingleResult,
-): string {
-	const reportSections = [
-		...(lastWriterResult
-			? [
-				`The last writer (${lastWriterResult.agent}) reported:`,
-				`---`,
-				getResultOutput(lastWriterResult),
-				`---`,
-				``,
-			]
-			: []),
-		...(finalReviewResult
-			? [
-				`The final gate review reported:`,
-				`---`,
-				getResultOutput(finalReviewResult),
-				`---`,
-				``,
-			]
-			: []),
-	];
-	return [
-		`Final documentation sync: the review gate settled and you are the last managed stage before delivery.`,
-		``,
-		...reportSections,
-		`Inspect the actual git diff and relevant implementation; the reports are only leads.`,
-		`Apply every documentation note the reviews recorded, then synchronize stale README/docs, examples, API comments, docstrings,`,
-		`and explanatory comments with the behavior that will be committed.`,
-		`Change documentation surfaces only; make zero edits when the diff creates no documentation drift.`,
-		`The workflow delivers directly after you; no fresh reviewer runs.`,
-		`Report exact documentation/comment paths changed, or state explicitly that no sync was needed.`,
-	].join("\n");
-}
-
-/**
- * One step of a managed workflow as delivered: the run id (so the condensed
- * summary can point at per-run detail via subagent_status), the result, and
- * the human-readable role within the workflow ("initial implementation",
- * "final review", "final documentation sync"). runId is optional only for
- * synthetic steps that never spawned a child.
- */
-export interface ChainStep {
-	runId?: number;
-	result: SingleResult;
-	relation: string;
-}
-
-export interface ManagedWorkflowOutcome {
-	kind: ManagedWorkflowKind;
-	steps: ChainStep[];
-}
-
-function workflowResultStatus(result: SingleResult): string {
-	if (isFailedResult(result)) return "failed";
-	if (result.agent === "reviewer") {
-		const verdict = reviewVerdict(getResultOutput(result));
-		return verdict ? verdict.toUpperCase() : "NO_VERDICT";
-	}
-	return "completed";
-}
-
-function workflowStepLine(step: ChainStep): string {
-	const id = step.runId !== undefined ? `#${step.runId} ` : "";
-	return `- ${id}${step.result.agent} · ${step.relation} · ${workflowResultStatus(step.result)}`;
-}
-
-function appendWorkflowFooter(lines: string[], steps: readonly ChainStep[]): void {
-	const total = sumUsage(steps.map((step) => step.result.usage));
-	const usage = formatUsageCompact(total);
-	lines.push("", `Totals: ${steps.length} run${steps.length === 1 ? "" : "s"}${usage ? ` · ${usage}` : ""}`);
-	const ids = steps.filter((step) => step.runId !== undefined).map((step) => `#${step.runId}`);
-	lines.push(`Per-run details: subagent_status ${ids.join(" ")}`);
-}
-
-/** One clear final delivery for post-writer and direct reviewer → documenter workflows. */
-export function formatManagedWorkflowSummary(
-	steps: readonly ChainStep[],
-	terminalResult: SingleResult = steps[steps.length - 1]!.result,
-): string {
-	const route = steps.map((step) => step.result.agent).join(" → ");
-	const lines = [`## Managed workflow: ${route} — final ${workflowResultStatus(terminalResult)}`, "", ...steps.map(workflowStepLine)];
-	appendWorkflowFooter(lines, steps);
-	return lines.join("\n");
-}
-
-export interface GateBriefOptions {
-	/** A conditional final documenter is available after the gate settles.
-	 * Documentation drift is then routed to it as non-gating notes instead of
-	 * failing the code gate. */
-	documenterPending: boolean;
-}
-
-/** Build the code gate that runs directly after a top-level writer, before any
- * documentation. Reports carry intent; the actual pending diff remains
- * authoritative. */
-export function buildFinalReviewBrief(
-	initialResult: SingleResult,
-	options: GateBriefOptions,
-): string {
-	return [
-		`Fresh code gate for a managed ${initialResult.agent} workflow.`,
-		``,
-		`The top-level ${initialResult.agent}'s full report:`,
-		`---`,
-		getResultOutput(initialResult),
-		`---`,
-		``,
-		`Run \`git status\` and \`git diff\` and inspect the actual pending code; the report is context, not proof.`,
-		`Remain read-only. Attach a concrete fix instruction to EVERY gate finding: what to change, where, and how to verify the fix`,
-		`— the report returns to the main agent, which uses your instructions to drive the fix.`,
-		...(options.documenterPending
-			? [
-				`A conditional documentation sync is available AFTER this gate, so documentation drift is not a code-gate finding:`,
-				`record it under "## Documentation notes" and emit the standalone line DOCUMENTATION: NEEDED,`,
-				`or DOCUMENTATION: CLEAN when no documentation update is needed.`,
-			]
-			: [
-				`No documenter is pending, so documentation drift is an ordinary gate finding.`,
-			]),
-		`This is an acceptance gate, not an advisory audit. End with exactly one standalone machine verdict line:`,
-		`VERDICT: REVIEW_PASS when no finding remains, otherwise VERDICT: REVIEW_FAIL.`,
-	].join("\n");
-}
+/**
+ * Managed workflow policy and handoff formatting.
+ *
+ * Successful top-level worker/cleaner runs continue through one independent
+ * code review gate. A failing managed gate continues into the reviewer fix
+ * stage: the same retained reviewer session gets write access and applies its
+ * own fix instructions, so nobody outside the gate has to guess what satisfies
+ * it. Direct reviewer results never chain — a failing direct gate returns its
+ * findings to the main agent, which owns that fix decision. Documentation
+ * drift is an ordinary gate finding; dispatching a documenter stays the main
+ * agent's call. Internal steps are launched by dispatch directly, so they
+ * never re-enter this policy or wake the main agent mid-chain.
+ */
+
+import { isWriteCapableAgent, type AgentConfig } from "./agents.ts";
+import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
+import { formatUsageCompact, sumUsage } from "./monitor.ts";
+
+export interface WorkflowAgentAvailability {
+	reviewer: boolean;
+	writer: boolean;
+}
+
+export function workflowAgentAvailability(
+	agents: readonly Pick<AgentConfig, "name" | "tools">[],
+): WorkflowAgentAvailability {
+	const names = new Set(agents.map((agent) => agent.name));
+	return {
+		reviewer: names.has("reviewer"),
+		writer: agents.some(isWriteCapableAgent),
+	};
+}
+
+export interface ManagedWorkflowPlan {
+	initialRelation: string;
+}
+
+/** Fixed cap on reviewer fix → re-review rounds inside one managed workflow.
+ * Re-reviews converge by construction (they verify fixes and fix regressions
+ * instead of re-scanning the whole surface); the cap only stops pathological
+ * burn and hands the still-failing gate back to the main agent. */
+export const MAX_REVIEW_FIX_ROUNDS = 2;
+
+/** Conservative pre-run check used to reserve one shared-repository lane
+ * around a complete writer workflow or a reviewer that needs a stable diff. */
+export function canStartManagedWorkflow(
+	agent: Pick<AgentConfig, "name" | "tools">,
+	availability: WorkflowAgentAvailability,
+): boolean {
+	// Every shared write-capable role—including custom agents—owns the repository
+	// lane even when no downstream role is enabled. Otherwise its edits can race
+	// a managed writer's pending diff.
+	if (isWriteCapableAgent(agent)) return true;
+	if (agent.name === "reviewer") {
+		// Hold a stable diff snapshot against every discoverable writer even when
+		// this review is advisory: a gate over a moving diff is unsound.
+		return availability.writer;
+	}
+	return false;
+}
+
+/** Classify only healthy top-level writer results; everything else delivers
+ * directly, including every reviewer result — a direct reviewer dispatch never
+ * starts another child. A failing managed gate is expanded by the workflow
+ * itself into the reviewer fix stage. */
+export function getManagedWorkflowPlan(
+	result: SingleResult,
+	availability: WorkflowAgentAvailability,
+): ManagedWorkflowPlan | undefined {
+	if (result.dispatchFailed || isFailedResult(result)) return undefined;
+	if (result.agent === "worker" || result.agent === "cleaner") {
+		if (!availability.reviewer) return undefined;
+		return {
+			initialRelation: result.agent === "cleaner" ? "initial cleanup" : "initial implementation",
+		};
+	}
+	return undefined;
+}
+
+/** Build the code gate that runs directly after a top-level writer. Reports
+ * carry intent; the actual pending diff remains authoritative. */
+export function buildFinalReviewBrief(initialResult: SingleResult): string {
+	return [
+		`Fresh code gate for a managed ${initialResult.agent} workflow.`,
+		``,
+		`The top-level ${initialResult.agent}'s full report:`,
+		`---`,
+		getResultOutput(initialResult),
+		`---`,
+		``,
+		`Run \`git status\` and \`git diff\` and judge the actual pending code; the report is context, not proof.`,
+		`Remain read-only. Attach a concrete fix instruction to EVERY gate finding — including documentation drift —:`,
+		`what to change, where, and how to verify it. A failing gate continues into your own write-enabled fix stage,`,
+		`so make every instruction executable exactly as written.`,
+		`End with exactly one standalone machine verdict line:`,
+		`VERDICT: REVIEW_PASS when no finding remains, otherwise VERDICT: REVIEW_FAIL.`,
+	].join("\n");
+}
+
+/** Build the follow-up brief for the reviewer fix stage: the same retained
+ * reviewer session continues with its read-only boundary lifted and applies
+ * its own fix instructions. The workflow continues with a converging re-review. */
+export function buildReviewerFixBrief(gateOutput: string): string {
+	return [
+		`Fix stage: your gate review returned REVIEW_FAIL. You now have full write access in this same session.`,
+		`Apply every one of your own fix instructions now — exactly the changes you specified, nothing broader.`,
+		`Then re-check the code your fixes touch, so the next scan does not open with your own regression, and run`,
+		`the narrowest decisive checks (type check, focused tests) to verify.`,
+		``,
+		`Your gate review:`,
+		`---`,
+		gateOutput,
+		`---`,
+		``,
+		`Report:`,
+		`## Fixed`,
+		`- each finding → the exact fix applied (path + what changed)`,
+		`## Verification`,
+		`- checks actually run and their results`,
+		`Do not emit another VERDICT; a converging gate re-reviews the diff after you.`,
+	].join("\n");
+}
+
+/** Fresh gate over the updated diff after a fix round. The re-review runs in a
+ * brand-new context but with a converging contract: verify the recorded fixes
+ * landed and hunt regressions the fixes introduced. It must not reopen new
+ * structural or style findings — the initial gate owned those — or every fresh
+ * scan would surface fresh nits forever and the loop would never end. */
+export function buildReReviewBrief(fixResult: SingleResult, round: number): string {
+	return [
+		`Re-review after fix round ${round}. This gate CONVERGES: it verifies fixes, it does not re-scan the whole surface.`,
+		``,
+		`The fix stage reported:`,
+		`---`,
+		getResultOutput(fixResult),
+		`---`,
+		``,
+		`Verify every recorded fix actually landed in the code, and hunt regressions the fixes introduced in the touched`,
+		`code and its direct blast radius (\`git status\` + \`git diff\`). Do NOT open new structural, style, or pre-existing`,
+		`findings — the initial gate owned those; a remaining earlier finding counts only if its fix failed to land.`,
+		`Remain read-only. Attach a concrete fix instruction to every finding you do report.`,
+		`End with exactly one standalone machine verdict line:`,
+		`VERDICT: REVIEW_PASS when nothing remains, otherwise VERDICT: REVIEW_FAIL.`,
+	].join("\n");
+}
+
+/**
+ * One step of a managed workflow as delivered: the run id (so the condensed
+ * summary can point at per-run detail via subagent_status), the result, and
+ * the human-readable role within the workflow ("initial implementation",
+ * "final review"). runId is optional only for synthetic steps that never
+ * spawned a child.
+ */
+export interface ChainStep {
+	runId?: number;
+	result: SingleResult;
+	relation: string;
+}
+
+export interface ManagedWorkflowOutcome {
+	steps: ChainStep[];
+}
+
+function workflowResultStatus(result: SingleResult, relation?: string): string {
+	if (isFailedResult(result)) return "failed";
+	// The fix stage is reviewer-named writer work: judge it by outcome, not by
+	// the verdict contract its review stage was held to.
+	if (relation === "review fix") return "completed";
+	if (result.agent === "reviewer") {
+		const verdict = reviewVerdict(getResultOutput(result));
+		return verdict ? verdict.toUpperCase() : "NO_VERDICT";
+	}
+	return "completed";
+}
+
+function workflowStepLine(step: ChainStep): string {
+	const id = step.runId !== undefined ? `#${step.runId} ` : "";
+	return `- ${id}${step.result.agent} · ${step.relation} · ${workflowResultStatus(step.result, step.relation)}`;
+}
+
+function appendWorkflowFooter(lines: string[], steps: readonly ChainStep[]): void {
+	const total = sumUsage(steps.map((step) => step.result.usage));
+	const usage = formatUsageCompact(total);
+	lines.push("", `Totals: ${steps.length} run${steps.length === 1 ? "" : "s"}${usage ? ` · ${usage}` : ""}`);
+	const ids = steps.filter((step) => step.runId !== undefined).map((step) => `#${step.runId}`);
+	lines.push(`Per-run details: subagent_status ${ids.join(" ")}`);
+}
+
+/** One clear final delivery for managed writer → gate workflows. */
+export function formatManagedWorkflowSummary(
+	steps: readonly ChainStep[],
+	terminalResult: SingleResult = steps[steps.length - 1]!.result,
+	terminalRelation: string = steps[steps.length - 1]!.relation,
+): string {
+	const route = steps.map((step) => step.result.agent).join(" → ");
+	const lines = [`## Managed workflow: ${route} — final ${workflowResultStatus(terminalResult, terminalRelation)}`, "", ...steps.map(workflowStepLine)];
+	appendWorkflowFooter(lines, steps);
+	return lines.join("\n");
+}

package/src/worktree.ts

@@ -10,7 +10,7 @@
 
 import { spawn, type ChildProcess } from "node:child_process";
 import { existsSync } from "node:fs";
-import { mkdir, mkdtemp, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, mkdtemp, realpath, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { isAbsolute, join, relative, resolve } from "node:path";
 
@@ -34,6 +34,8 @@ export interface CommandRunOptions {
 	signal?: AbortSignal;
 	timeoutMs?: number;
 	maxOutputBytes?: number;
+	/** Extra environment entries merged over the inherited environment. */
+	env?: Record<string, string>;
 }
 
 export interface CommandResult {
@@ -54,33 +56,9 @@ export const GIT_COMMAND_KILL_GRACE_MS = 2_000;
 export const GIT_OUTPUT_MAX_BYTES = 64 * 1024 * 1024;
 export const WORKTREE_PATCH_MAX_BYTES = GIT_OUTPUT_MAX_BYTES;
 
-/** Git apply validates and writes in one process, but two apply processes can
- * validate the same old bytes concurrently before either writes. Chain applies
- * per canonical source worktree so an overlapping later patch conflicts instead
- * of silently winning a last-writer race. */
-const originalRootApplyTails = new Map<string, Promise<void>>();
-
-async function withSerializedOriginalRootApply<T>(
-	originalRoot: string,
-	operation: () => Promise<T>,
-): Promise<T> {
-	const key = process.platform === "win32" ? originalRoot.toLowerCase() : originalRoot;
-	const previous = originalRootApplyTails.get(key) ?? Promise.resolve();
-	let release!: () => void;
-	const gate = new Promise<void>((resolveGate) => {
-		release = resolveGate;
-	});
-	const tail = previous.catch(() => undefined).then(() => gate);
-	originalRootApplyTails.set(key, tail);
-	await previous.catch(() => undefined);
-	try {
-		return await operation();
-	} finally {
-		release();
-		if (originalRootApplyTails.get(key) === tail) originalRootApplyTails.delete(key);
-	}
-}
-
+/** Git apply validates and writes in one process. The repository lane
+ * (thread-lifecycle) already serializes every finalize against all writers of
+ * the same canonical checkout, so applies never race each other here. */
 function terminateCommandTree(child: ChildProcess, force: boolean, processGroup: boolean): void {
 	if (process.platform === "win32" && child.pid !== undefined) {
 		const fallback = (): void => {
@@ -126,6 +104,7 @@ export const runCommand: CommandRunner = (command, args, options) =>
 			windowsHide: true,
 			stdio: ["pipe", "pipe", "pipe"],
 			detached: usePosixProcessGroup,
+			...(options.env ? { env: { ...process.env, ...options.env } } : {}),
 		});
 		const stdout: Buffer[] = [];
 		const stderr: Buffer[] = [];
@@ -315,12 +294,14 @@ async function runGit(
 	args: readonly string[],
 	action: string,
 	input?: Buffer,
+	env?: Record<string, string>,
 ): Promise<CommandResult> {
 	let result: CommandResult;
 	try {
 		result = await runner("git", args, {
 			cwd,
 			input,
+			env,
 			timeoutMs: GIT_COMMAND_TIMEOUT_MS,
 			maxOutputBytes: GIT_OUTPUT_MAX_BYTES,
 		});
@@ -560,15 +541,7 @@ class GitWorktreeIsolation implements WorktreeIsolation {
 			if (hadChanges) {
 				await writeFile(this.patchPath, diff.stdout, { flag: "wx" });
 				patchWritten = true;
-				await withSerializedOriginalRootApply(this.originalRoot, () =>
-					runGit(
-						this.runner,
-						this.originalRoot,
-						["apply", "--binary", "--whitespace=nowarn", this.patchPath],
-						`Applying isolated patch to ${this.originalRoot}`,
-					),
-				);
-				integrated = true;
+				integrated = await this.applyPatchThreeWay();
 			}
 
 			const cleanupError = await this.removeAndPrune();
@@ -606,6 +579,60 @@ class GitWorktreeIsolation implements WorktreeIsolation {
 		};
 	}
 
+	/** Apply the patch as a three-way merge against its recorded preimage
+	 * blobs, so parallel workers that touched disjoint regions (or disjoint
+	 * files) of the same checkout integrate cleanly instead of the whole patch
+	 * failing on context drift. A genuine overlap still fails and retains the
+	 * artifacts, with conflict markers left in place for the main model to
+	 * resolve. `--3way` implies `--index` and demands a working tree matching
+	 * that index, so everything runs against a private copy of the checkout's
+	 * index: the copy first absorbs the current unstaged state (`add -A`),
+	 * making the working tree "ours" of the merge, and the user's real staged
+	 * state is never touched. */
+	private async applyPatchThreeWay(): Promise<boolean> {
+		const indexCopy = join(this.tempDir, "apply-index");
+		try {
+			const indexPath = resolve(
+				this.originalRoot,
+				(await runGit(
+					this.runner,
+					this.originalRoot,
+					["rev-parse", "--git-path", "index"],
+					`Resolving index path for ${this.originalRoot}`,
+				)).stdout.toString("utf8").trim(),
+			);
+			if (!existsSync(indexPath)) {
+				await runGit(
+					this.runner,
+					this.originalRoot,
+					["apply", "--binary", "--whitespace=nowarn", this.patchPath],
+					`Applying isolated patch to ${this.originalRoot}`,
+				);
+				return true;
+			}
+			await copyFile(indexPath, indexCopy);
+			await runGit(
+				this.runner,
+				this.originalRoot,
+				["add", "-A", "--", "."],
+				`Staging checkout state for isolated merge in ${this.originalRoot}`,
+				undefined,
+				{ GIT_INDEX_FILE: indexCopy },
+			);
+			await runGit(
+				this.runner,
+				this.originalRoot,
+				["apply", "--binary", "--3way", "--whitespace=nowarn", this.patchPath],
+				`Three-way applying isolated patch to ${this.originalRoot}`,
+				undefined,
+				{ GIT_INDEX_FILE: indexCopy },
+			);
+			return true;
+		} finally {
+			await rm(indexCopy, { force: true }).catch(() => undefined);
+		}
+	}
+
 	/** Return an error string instead of throwing so applied work is never retried. */
 	private async removeAndPrune(): Promise<string | undefined> {
 		try {