pi-crew 0.9.27 → 0.9.29

package/src/state/atomic-write.ts

@@ -260,32 +260,43 @@ function renameWithLinkSync(tempPath: string, filePath: string, retries = 8): vo
 	let lastError: unknown;
 	for (let attempt = 0; attempt <= retries; attempt++) {
 		try {
-			// Windows: hard links fail with ENOENT when short-name and long-name
-			// path aliases are mixed (e.g. RUNNER~1 vs runneradmin). Use
-			// renameSync which handles this correctly via MoveFileEx.
 			if (process.platform === "win32") {
-				try {
-					fs.unlinkSync(filePath);
-				} catch {
-					/* destination may not exist */
-				}
+				// B9: MoveFileEx (Node's renameSync on Windows) replaces the destination atomically
+				// with MOVEFILE_REPLACE_EXISTING, so no prior unlink is needed. Unlinking first
+				// opened a window where concurrent readers saw ENOENT between the unlink and
+				// the rename. Try rename directly; only fall back to unlink-then-rename for
+				// edge cases (read-only dest / type mismatch / short-long-name alias).
 				try {
 					fs.renameSync(tempPath, filePath);
 					return;
 				} catch (renameError) {
 					lastError = renameError;
-					if (!isRetryableLinkError(renameError) || attempt === retries) break;
+					if (isRetryableLinkError(renameError) && attempt !== retries) {
+						// retryable — loop again after sleep
+					} else {
+						try {
+							fs.unlinkSync(filePath);
+						} catch {
+							/* destination may not exist */
+						}
+						try {
+							fs.renameSync(tempPath, filePath);
+							return;
+						} catch (renameError2) {
+							lastError = renameError2;
+							if (!isRetryableLinkError(renameError2) || attempt === retries) break;
+						}
+					}
 				}
 			} else {
-				// First try to unlink any existing file at destination (hard links don't follow symlinks)
 				try {
 					fs.unlinkSync(filePath);
 				} catch {
 					/* destination may not exist */
 				}
-				// Create hard link - does NOT follow symlinks at filePath
+				// Create hard link — does NOT follow symlinks at filePath
 				fs.linkSync(tempPath, filePath);
-				// Successfully linked - now unlink the temp file
+				// Successfully linked — now unlink the temp file
 				fs.unlinkSync(tempPath);
 				return;
 			}
@@ -305,17 +316,32 @@ async function renameWithLinkAsync(tempPath: string, filePath: string, retries =
 	for (let attempt = 0; attempt <= retries; attempt++) {
 		try {
 			if (process.platform === "win32") {
-				try {
-					await fs.promises.unlink(filePath);
-				} catch {
-					/* destination may not exist */
-				}
+				// B9: MoveFileEx (Node's rename on Windows) replaces the destination atomically
+				// with MOVEFILE_REPLACE_EXISTING, so no prior unlink is needed. Unlinking first
+				// opened a window where concurrent readers saw ENOENT between the unlink and
+				// the rename. Try rename directly; only fall back to unlink-then-rename for
+				// edge cases (read-only dest / type mismatch / short-long-name alias).
 				try {
 					await fs.promises.rename(tempPath, filePath);
 					return;
 				} catch (renameError) {
 					lastError = renameError;
-					if (!isRetryableLinkError(renameError) || attempt === retries) break;
+					if (isRetryableLinkError(renameError) && attempt !== retries) {
+						// retryable — loop again after sleep
+					} else {
+						try {
+							await fs.promises.unlink(filePath);
+						} catch {
+							/* destination may not exist */
+						}
+						try {
+							await fs.promises.rename(tempPath, filePath);
+							return;
+						} catch (renameError2) {
+							lastError = renameError2;
+							if (!isRetryableLinkError(renameError2) || attempt === retries) break;
+						}
+					}
 				}
 			} else {
 				try {
@@ -323,7 +349,9 @@ async function renameWithLinkAsync(tempPath: string, filePath: string, retries =
 				} catch {
 					/* destination may not exist */
 				}
+				// Create hard link — does NOT follow symlinks at filePath
 				await fs.promises.link(tempPath, filePath);
+				// Successfully linked — now unlink the temp file
 				await fs.promises.unlink(tempPath);
 				return;
 			}
@@ -337,7 +365,6 @@ async function renameWithLinkAsync(tempPath: string, filePath: string, retries =
 	}
 	throw lastError;
 }
-
 export function renameWithRetry(
 	tempPath: string,
 	filePath: string,

package/src/state/event-log.ts

@@ -304,6 +304,37 @@ function persistSequence(eventsPath: string, seq: number): void {
 	}
 }
 
+// B7: single in-process monotonic sequence counter per eventsPath. The three
+// append paths — sync appendEvent (withEventLogLockSync file lock), buffered
+// flush (asyncLocks promise chain), and direct appendEventAsync (asyncQueues
+// promise chain) — use DIFFERENT locks, so the old read-sidecar / compute /
+// persist-sidecar sequence logic in nextSequence() raced ACROSS paths and
+// produced duplicate sequence numbers (observed live: distinct events sharing
+// a seq; no data loss — only the counter collided). A single in-process counter
+// makes assignment atomic (JS is single-threaded); persistSequence() keeps the
+// sidecar durable for crash recovery across restarts.
+const seqCounters = new Map<string, number>();
+
+/** Atomically reserve the next sequence number for `eventsPath`. */
+function reserveSequence(eventsPath: string): number {
+	let last = seqCounters.get(eventsPath);
+	if (last === undefined) {
+		// Seed once from the authoritative source (sidecar / cache / file scan).
+		// nextSequence() returns the NEXT seq to assign, so the last assigned is one less.
+		last = nextSequence(eventsPath) - 1;
+	}
+	const next = last + 1;
+	seqCounters.set(eventsPath, next);
+	return next;
+}
+
+/** Keep the in-process counter monotonic w.r.t. an explicitly-provided seq
+ *  (e.g. baseMetadata.seq) so a later auto-assigned seq never collides with it. */
+function advanceSequenceCounter(eventsPath: string, seq: number): void {
+	const last = seqCounters.get(eventsPath);
+	if (last === undefined || seq > last) seqCounters.set(eventsPath, seq);
+}
+
 export function computeEventFingerprint(event: Pick<TeamEvent, "type" | "runId" | "taskId" | "data">): string {
 	return createHash("sha256")
 		.update(
@@ -390,13 +421,22 @@ async function withEventLogLockAsync(eventsPath: string, fn: () => Promise<void>
 	try {
 		await next;
 	} finally {
-		asyncLocks.delete(queueKey);
+		// Compare-and-delete: only remove our entry if it still points at our
+		// promise. With 3+ overlapping callers, an earlier caller's finally would
+		// otherwise delete a later caller's promise, letting the next caller start
+		// immediately (in parallel) -> broken mutual exclusion, duplicate seqs.
+		if (asyncLocks.get(queueKey) === next) {
+			asyncLocks.delete(queueKey);
+		}
 	}
 }
 
 /** Reset event log mode (for testing only). */
 export function resetEventLogMode(): void {
 	asyncQueues.clear();
+	// B7: clear in-process sequence counters alongside async state so tests
+	// don't leak seq state between runs.
+	seqCounters.clear();
 }
 
 /**
@@ -440,8 +480,9 @@ export async function appendEventAsync(eventsPath: string, event: AppendTeamEven
 		let seq: number;
 		if (baseMetadata?.seq !== undefined) {
 			seq = baseMetadata.seq;
+			advanceSequenceCounter(eventsPath, seq);
 		} else {
-			seq = nextSequence(eventsPath);
+			seq = reserveSequence(eventsPath);
 			// NOTE: We do NOT call persistSequence here. It will be called AFTER
 			// successful appendFile below to ensure sidecar is only updated when
 			// the event is actually written.
@@ -588,27 +629,31 @@ export async function appendEventAsync(eventsPath: string, event: AppendTeamEven
 		}
 		return fullEvent;
 	});
-	asyncQueues.set(
-		queueKey,
-		next.then(
-			() => {
+	const tail = next.then(
+		() => {
+			// Compare-and-delete: only remove our entry if it still points at our
+			// tail promise. An older caller deleting unconditionally would wipe a
+			// newer caller's promise, letting the next caller bypass serialization
+			// -> duplicate seqs / interleaved appends.
+			if (asyncQueues.get(queueKey) === tail) {
 				asyncQueues.delete(queueKey);
-			},
-			(error) => {
-				// FIX: Wrap error handler in try-catch to ensure asyncQueues.delete
-				// always runs, even if logging itself throws.
-				try {
-					logInternalError("event-log.async-queue", error, eventsPath);
-				} catch {
-					// logging failed — ensure queue is still cleaned up
-				}
-				// FIX: Reset queue to a resolved state instead of deleting it.
-				// This prevents cascading failures where a single transient error
-				// (e.g., ENOSPC) causes all subsequent events on the same path to fail.
-				asyncQueues.set(queueKey, Promise.resolve());
-			},
-		),
+			}
+		},
+		(error) => {
+			// FIX: Wrap error handler in try-catch to ensure asyncQueues.delete
+			// always runs, even if logging itself throws.
+			try {
+				logInternalError("event-log.async-queue", error, eventsPath);
+			} catch {
+				// logging failed — ensure queue is still cleaned up
+			}
+			// FIX: Reset queue to a resolved state instead of deleting it.
+			// This prevents cascading failures where a single transient error
+			// (e.g., ENOSPC) causes all subsequent events on the same path to fail.
+			asyncQueues.set(queueKey, Promise.resolve());
+		},
 	);
+	asyncQueues.set(queueKey, tail);
 	return next;
 }
 
@@ -658,7 +703,8 @@ async function appendEventBatchInsideLock(eventsPath: string, queue: BufferedApp
 	// in between — every call would see the same file state and return the same
 	// seq, breaking the "unique monotonic seq" contract. The cache update +
 	// persistSequence at the end refreshes the sidecar to the last assigned seq.
-	const startingSeq = queue[0]?.event.metadata?.seq ?? nextSequence(eventsPath);
+	// B7: use reserveSequence for atomic seq assignment across all paths.
+	const startingSeq = queue[0]?.event.metadata?.seq ?? reserveSequence(eventsPath);
 	let nextSeq = startingSeq;
 	const finalized: { item: BufferedAppend; line: string; fullEvent: TeamEvent }[] = [];
 	let lastSeq = 0;
@@ -693,6 +739,8 @@ async function appendEventBatchInsideLock(eventsPath: string, queue: BufferedApp
 		finalized.push({ item, line: `${JSON.stringify(redactSecrets(fullEvent))}\n`, fullEvent });
 		lastSeq = seq;
 	}
+	// B7: advance counter past the entire batch so next reserveSequence returns the correct value.
+	advanceSequenceCounter(eventsPath, lastSeq);
 
 	// Phase 2: single appendFileSync + single fsync + single persistSequence.
 	// Before this fix, each event in the batch triggered its own fsync, which
@@ -745,8 +793,12 @@ async function appendEventBatchInsideLock(eventsPath: string, queue: BufferedApp
 function appendEventInsideLock(eventsPath: string, event: AppendTeamEvent): TeamEvent {
 	fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
 	const baseMetadata = event.metadata;
+	// B7: use reserveSequence for atomic seq assignment across all paths.
+	const explicitSeq = baseMetadata?.seq;
+	const seq = explicitSeq ?? reserveSequence(eventsPath);
+	if (explicitSeq !== undefined) advanceSequenceCounter(eventsPath, seq);
 	let metadata: TeamEventMetadata = {
-		seq: baseMetadata?.seq ?? nextSequence(eventsPath),
+		seq,
 		provenance: baseMetadata?.provenance ?? "team_runner",
 		...(baseMetadata?.parentEventId ? { parentEventId: baseMetadata.parentEventId } : {}),
 		...(baseMetadata?.attemptId ? { attemptId: baseMetadata.attemptId } : {}),
@@ -813,7 +865,8 @@ function appendEventInsideLock(eventsPath: string, event: AppendTeamEvent): Team
 	} catch (error) {
 		logInternalError("event-log.size-check", error, `eventsPath=${eventsPath}`);
 	}
-	const seq = fullEvent.metadata?.seq ?? 0;
+	// seq is already computed above via reserveSequence — reuse it for persist/cache.
+	// const seq declaration removed (B7: seq is now computed before metadata object).
 	if (!skippedDueToSize) {
 		fs.appendFileSync(eventsPath, `${JSON.stringify(redactSecrets(fullEvent))}\n`, "utf-8");
 		// F3a: skip data fsync for non-terminal events. We still call `persistSequence`

package/src/state/mailbox.ts

@@ -463,16 +463,19 @@ export function appendMailboxMessage(
 		replyContent: message.replyContent,
 	};
 	// H2 fix: wrap append in cross-process lock to prevent interleaving on Windows.
+	// B8: rotation (rename + recreate) also runs INSIDE the lock so it is serialized
+	// with appends — otherwise a concurrent append between rename and recreate can
+	// be truncated to an empty file.
 	withEventLogLockSync(mailboxFile(manifest, complete.direction, complete.taskId), () => {
 		fs.appendFileSync(
 			mailboxFile(manifest, complete.direction, complete.taskId),
 			`${JSON.stringify(redactSecrets(complete))}\n`,
 			"utf-8",
 		);
+		// 3.3 — rotate mailbox file if it has grown past 10 MB. Cheap stat check;
+		// rotates at most once per append.
+		rotateMailboxFileIfNeeded(mailboxFile(manifest, complete.direction, complete.taskId));
 	});
-	// 3.3 — rotate mailbox file if it has grown past 10 MB. Cheap stat
-	// check; rotates at most once per append.
-	rotateMailboxFileIfNeeded(mailboxFile(manifest, complete.direction, complete.taskId));
 	// BUGFIX (Round 12 C3): the delivery.json read-modify-write below was
 	// UNLOCKED, so concurrent appendMailboxMessage calls could interleave and
 	// clobber each other's delivery entries (lost-update race). FIX: wrap the

package/src/ui/pi-ui-compat.ts

@@ -46,6 +46,17 @@ export function setExtensionWidget(
 	ctx.ui.setWidget(key, content as never, widgetOptions as WidgetOptions);
 }
 
+type FooterFactory = (tui: unknown, theme: unknown, footerData: unknown) => unknown;
+
+/** Install a custom footer component, or pass `undefined` to restore pi's built-in footer.
+ * No-op when the host UI predates the `setFooter` API. */
+export function setFooter(ctx: UiContext | undefined, factory: FooterFactory | undefined): void {
+	if (!ctx) return;
+	const record = maybeRecord(ctx.ui);
+	const fn = record?.setFooter;
+	if (typeof fn === "function") fn.call(ctx.ui, factory as never);
+}
+
 export function showCustom<T>(ctx: UiContext, factory: CustomFactory<T>, options?: CustomOptions): Promise<T> {
 	const custom = ctx.ui.custom as unknown as GenericCustom;
 	return custom<T>(factory, options);

package/src/utils/conflict-detect.ts

@@ -68,7 +68,11 @@ export function scanConflictLines(lines: readonly string[], firstLineNumber: num
 	} | null = null;
 
 	for (let i = 0; i < lines.length; i++) {
-		const line = lines[i];
+		// Strip a trailing CR so CRLF files (Windows) match markers/separators.
+		// The raw line (with CR) is never needed here; content is collected from
+		// the normalized line so storage stays consistent across LF/CRLF inputs.
+		const rawLine = lines[i];
+		const line = rawLine.charCodeAt(rawLine.length - 1) === 13 /* \r */ ? rawLine.slice(0, -1) : rawLine;
 		const ln = firstLineNumber + i;
 
 		const oursLabel = matchMarker(line, OURS_PREFIX);
@@ -339,7 +343,9 @@ export function parseConflictUri(raw: string): ParsedConflictUri | null {
  * in the file that shift line numbers don't break resolution.
  */
 export function spliceConflict(originalText: string, entry: ConflictEntry, replacement: string): string {
-	const lines = originalText.split("\n");
+	// Preserve the original line ending (CRLF or LF) for a byte-accurate round-trip.
+	const eol = originalText.includes("\r\n") ? "\r\n" : "\n";
+	const lines = originalText.split(/\r?\n/);
 	const expected = buildRecordedRegion(entry);
 	const match = locateRegion(lines, expected, entry.startLine - 1);
 	if (!match) {
@@ -351,7 +357,7 @@ export function spliceConflict(originalText: string, entry: ConflictEntry, repla
 	const trimmed = normalizeTrailingNewline(replacement);
 	const replacementLines = trimmed.split("\n");
 	const next = [...lines.slice(0, match.startIdx), ...replacementLines, ...lines.slice(match.endIdx + 1)];
-	return next.join("\n");
+	return next.join(eol);
 }
 
 /** Reconstruct the recorded marker block as it should appear in the file. */

package/src/utils/paths.ts

@@ -39,7 +39,13 @@ export function packageRoot(): string {
 }
 
 export function userPiRoot(): string {
-	const home = process.env.PI_TEAMS_HOME?.trim() || os.homedir();
+	// F4: a misconfigured PI_TEAMS_HOME can be the literal string "undefined"
+	// (e.g. PI_TEAMS_HOME=$UNSET_VAR in a shell), which would build paths like
+	// "undefined/.pi/agent" relative to cwd and silently create a junk "undefined/"
+	// tree. Treat the literal "undefined" (and empty) as unset and fall back to
+	// os.homedir().
+	const rawHome = process.env.PI_TEAMS_HOME?.trim();
+	const home = rawHome && rawHome !== "undefined" ? rawHome : os.homedir();
 	const resolved = path.join(home, ".pi", "agent");
 
 	// Reject symlinks to prevent confusion attacks where PI_TEAMS_HOME points to

package/src/worktree/cleanup.ts

@@ -131,6 +131,25 @@ export function cleanupRunWorktrees(
 		const branchName = `pi-crew/${manifest.runId}/${sanitizeBranchPart(entry.name)}`;
 		const safeBranchName = sanitizeBranchPart(entry.name);
 		if (dirty) {
+			// C9: preserve dirty worktrees unless explicitly forced. Previously the
+			// dirty branch ALWAYS ran 'git add -A' + commit + remove, staging every
+			// untracked file (incl. potential secrets/build artifacts) into a
+			// recovery branch without consent. force=true keeps the old behavior.
+			if (!options.force) {
+				const safePreserveName = sanitizeFilename(entry.name);
+				const artifact = writeArtifact(manifest.artifactsRoot, {
+					kind: "diff",
+					relativePath: `cleanup/${safePreserveName}.diff`,
+					content: captureDiff(worktreePath),
+					producer: "worktree-cleanup",
+				});
+				result.artifactPaths.push(artifact.path);
+				result.preserved.push({
+					path: worktreePath,
+					reason: "dirty worktree preserved \u2014 pass force=true to auto-commit and remove",
+				});
+				continue;
+			}
 			// Issue 1 fix: check signal before git operations
 			if (options.signal?.aborted) break;
 			// Commit changes to a branch instead of just preserving the worktree

package/src/worktree/worktree-manager.ts

@@ -551,6 +551,100 @@ export function overlaySeedPaths(repoRoot: string, worktreePath: string, seedPat
 	}
 }
 
+/**
+ * Snapshot uncommitted work in a reused worktree to a recovery artifact BEFORE
+ * discarding it, so the data is never silently lost. Captures tracked changes
+ * (git diff HEAD) and inlines untracked file contents so the work can be
+ * recovered via `git apply` / manual restore. Best-effort: a snapshot failure
+ * only logs (it must not block the clean-slate reuse flow).
+ */
+function snapshotDirtyWorktree(manifest: TeamRunManifest, task: TeamTaskState, worktreePath: string, dirtyStatus: string): void {
+	try {
+		const parts: string[] = [
+			`# Worktree recovery snapshot`,
+			`runId: ${manifest.runId}  taskId: ${task.id}  path: ${worktreePath}`,
+			`capturedAt: ${new Date().toISOString()}`,
+			"",
+		];
+		let trackedDiff = "";
+		try {
+			trackedDiff = git(worktreePath, ["diff", "HEAD"]);
+		} catch {
+			trackedDiff = "";
+		}
+		if (trackedDiff.trim()) {
+			parts.push("## Tracked changes (`git diff HEAD`)", "```diff", trackedDiff, "```", "");
+		}
+		for (const line of dirtyStatus.split("\n")) {
+			if (!line.startsWith("?? ")) continue;
+			// Strip the "?? " prefix and surrounding git quotes.
+			const rel = line.slice(3).replace(/^"|"$/g, "");
+			if (!rel) continue;
+			try {
+				const abs = path.join(worktreePath, rel);
+				if (!fs.existsSync(abs) || fs.statSync(abs).isDirectory()) continue;
+				const content = fs.readFileSync(abs, "utf-8");
+				parts.push(`## Untracked file: ${rel}`, "```", content, "```", "");
+			} catch {
+				/* skip unreadable/unstat-able entry */
+			}
+		}
+		writeArtifact(manifest.artifactsRoot, {
+			kind: "diff",
+			relativePath: `worktree-recovery/${task.id}-${Date.now()}.md`,
+			content: parts.join("\n"),
+			producer: "worktree-manager.snapshotDirtyWorktree",
+			retention: "run",
+		});
+	} catch (err) {
+		logInternalError(
+			"worktree.recovery.snapshotFailed",
+			err instanceof Error ? err : new Error(String(err)),
+			`runId=${manifest.runId}, taskId=${task.id}`,
+		);
+	}
+}
+
+/**
+ * Best-effort removal of a just-created worktree + its branch. Used when a
+ * post-creation step (setup hook, node_modules link, seed overlay) fails, so
+ * the run does not leak an orphaned worktree dir + branch that would block the
+ * next run with an "already checked out" error.
+ */
+function cleanupCreatedWorktree(repoRoot: string, worktreePath: string, branch: string): void {
+	try {
+		git(repoRoot, ["worktree", "remove", "--force", worktreePath]);
+	} catch {
+		try {
+			if (fs.existsSync(worktreePath)) fs.rmSync(worktreePath, { recursive: true, force: true });
+		} catch {
+			/* best-effort */
+		}
+	}
+	try {
+		git(repoRoot, ["branch", "-D", branch]);
+	} catch {
+		/* best-effort */
+	}
+}
+
+async function cleanupCreatedWorktreeAsync(repoRoot: string, worktreePath: string, branch: string): Promise<void> {
+	try {
+		await gitAsync(repoRoot, ["worktree", "remove", "--force", worktreePath]);
+	} catch {
+		try {
+			if (fs.existsSync(worktreePath)) fs.rmSync(worktreePath, { recursive: true, force: true });
+		} catch {
+			/* best-effort */
+		}
+	}
+	try {
+		await gitAsync(repoRoot, ["branch", "-D", branch]);
+	} catch {
+		/* best-effort */
+	}
+}
+
 export function prepareTaskWorkspace(manifest: TeamRunManifest, task: TeamTaskState, stepSeedPaths?: string[]): PreparedTaskWorkspace {
 	if (manifest.workspaceMode !== "worktree") return { cwd: task.cwd };
 	const repoRoot = findGitRoot(manifest.cwd);
@@ -626,10 +720,12 @@ export function prepareTaskWorkspace(manifest: TeamRunManifest, task: TeamTaskSt
 		// Check for uncommitted changes from previous run before reusing
 		const dirtyStatus = git(worktreePath, ["status", "--porcelain"]);
 		if (dirtyStatus.trim()) {
-			// Discard uncommitted changes to ensure clean slate for new task
+			// Snapshot uncommitted work to a recovery artifact BEFORE discarding, so the
+			// previous run's changes are never silently destroyed on reuse.
+			snapshotDirtyWorktree(manifest, task, worktreePath, dirtyStatus);
 			logInternalError(
 				"worktree.reused.dirty",
-				new Error(`Discarding uncommitted changes in reused worktree at ${worktreePath}`),
+				new Error(`Discarding uncommitted changes in reused worktree at ${worktreePath} (snapshot saved to artifacts)`),
 				`runId=${manifest.runId}, taskId=${task.id}, dirtyStatus=${dirtyStatus.trim()}`,
 			);
 			git(worktreePath, ["checkout", "--", "."]);
@@ -679,23 +775,30 @@ export function prepareTaskWorkspace(manifest: TeamRunManifest, task: TeamTaskSt
 		}
 		throw error;
 	}
-	const syntheticPaths = runSetupHook(manifest, task, repoRoot, worktreePath, branch);
-	const nodeModulesLinked =
-		loadedConfig.config.worktree?.linkNodeModules === true ? linkNodeModulesIfPresent(repoRoot, worktreePath) : false;
-	// Overlay seed paths from config + step-level seedPaths
-	const globalSeedPaths = loadedConfig.config.worktree?.seedPaths ?? [];
-	const merged = normalizeSeedPaths([...globalSeedPaths, ...(stepSeedPaths ?? [])], repoRoot);
-	if (merged.length > 0) {
-		overlaySeedPaths(repoRoot, worktreePath, merged);
+	try {
+		const syntheticPaths = runSetupHook(manifest, task, repoRoot, worktreePath, branch);
+		const nodeModulesLinked =
+			loadedConfig.config.worktree?.linkNodeModules === true ? linkNodeModulesIfPresent(repoRoot, worktreePath) : false;
+		// Overlay seed paths from config + step-level seedPaths
+		const globalSeedPaths = loadedConfig.config.worktree?.seedPaths ?? [];
+		const merged = normalizeSeedPaths([...globalSeedPaths, ...(stepSeedPaths ?? [])], repoRoot);
+		if (merged.length > 0) {
+			overlaySeedPaths(repoRoot, worktreePath, merged);
+		}
+		return {
+			cwd: worktreePath,
+			worktreePath,
+			branch,
+			reused: false,
+			nodeModulesLinked,
+			syntheticPaths,
+		};
+	} catch (setupError) {
+		// Hook/link/seed failure AFTER worktree+branch creation: clean up to avoid
+		// an orphaned worktree dir + branch that would block the next run.
+		cleanupCreatedWorktree(repoRoot, worktreePath, branch);
+		throw setupError;
 	}
-	return {
-		cwd: worktreePath,
-		worktreePath,
-		branch,
-		reused: false,
-		nodeModulesLinked,
-		syntheticPaths,
-	};
 }
 
 /** Async version of prepareTaskWorkspace — yields the event loop during git operations. */
@@ -766,9 +869,10 @@ export async function prepareTaskWorkspaceAsync(
 		}
 		const dirtyStatus = await gitAsync(worktreePath, ["status", "--porcelain"]);
 		if (dirtyStatus.trim()) {
+			snapshotDirtyWorktree(manifest, task, worktreePath, dirtyStatus);
 			logInternalError(
 				"worktree.reused.dirty",
-				new Error(`Discarding uncommitted changes in reused worktree at ${worktreePath}`),
+				new Error(`Discarding uncommitted changes in reused worktree at ${worktreePath} (snapshot saved to artifacts)`),
 				`runId=${manifest.runId}, taskId=${task.id}, dirtyStatus=${dirtyStatus.trim()}`,
 			);
 			await gitAsync(worktreePath, ["checkout", "--", "."]);
@@ -818,22 +922,29 @@ export async function prepareTaskWorkspaceAsync(
 		}
 		throw error;
 	}
-	const syntheticPaths = runSetupHook(manifest, task, repoRoot, worktreePath, branch);
-	const nodeModulesLinked =
-		loadedConfig.config.worktree?.linkNodeModules === true ? linkNodeModulesIfPresent(repoRoot, worktreePath) : false;
-	const globalSeedPaths = loadedConfig.config.worktree?.seedPaths ?? [];
-	const merged = normalizeSeedPaths([...globalSeedPaths, ...(stepSeedPaths ?? [])], repoRoot);
-	if (merged.length > 0) {
-		overlaySeedPaths(repoRoot, worktreePath, merged);
+	try {
+		const syntheticPaths = runSetupHook(manifest, task, repoRoot, worktreePath, branch);
+		const nodeModulesLinked =
+			loadedConfig.config.worktree?.linkNodeModules === true ? linkNodeModulesIfPresent(repoRoot, worktreePath) : false;
+		const globalSeedPaths = loadedConfig.config.worktree?.seedPaths ?? [];
+		const merged = normalizeSeedPaths([...globalSeedPaths, ...(stepSeedPaths ?? [])], repoRoot);
+		if (merged.length > 0) {
+			overlaySeedPaths(repoRoot, worktreePath, merged);
+		}
+		return {
+			cwd: worktreePath,
+			worktreePath,
+			branch,
+			reused: false,
+			nodeModulesLinked,
+			syntheticPaths,
+		};
+	} catch (setupError) {
+		// Hook/link/seed failure AFTER worktree+branch creation: clean up to avoid
+		// an orphaned worktree dir + branch that would block the next run.
+		await cleanupCreatedWorktreeAsync(repoRoot, worktreePath, branch);
+		throw setupError;
 	}
-	return {
-		cwd: worktreePath,
-		worktreePath,
-		branch,
-		reused: false,
-		nodeModulesLinked,
-		syntheticPaths,
-	};
 }
 
 export function captureWorktreeDiffStat(worktreePath: string): WorktreeDiffStat {