pi-cohort 7.4.5 → 7.5.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [7.5.0] - 2026-10-26
+
+### Added
+- `worktreeTeardownHook` and `worktreeTeardownHookTimeoutMs` let consumers clean up external resources before task checkout removal, including setup rollback; failures produce best-effort warnings without changing task results. (#27)
+
+### Fixed
+- The Tests workflow passes on Windows again: the fanout extension-inheritance integration test hands its preload to `--import` as a `file://` URL instead of a bare drive-letter path.
+
 ## [7.4.5] - 2026-10-23
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "7.4.5",
+  "version": "7.5.0",
   "description": "Delegate Pi work to focused child agents: code review, scouting, implementation, parallel audits, saved chains, and background jobs.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/src/runs/background/async-execution.ts

@@ -80,6 +80,8 @@ interface AsyncChainParams {
 	maxSubagentDepth: number;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	worktreeTeardownHook?: string;
+	worktreeTeardownHookTimeoutMs?: number;
 	controlConfig?: ResolvedControlConfig;
 	nestedRoute?: NestedRouteInfo;
 	forwardedFlags?: string[];
@@ -115,6 +117,8 @@ interface AsyncSingleParams {
 	maxSubagentDepth: number;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	worktreeTeardownHook?: string;
+	worktreeTeardownHookTimeoutMs?: number;
 	controlConfig?: ResolvedControlConfig;
 	nestedRoute?: NestedRouteInfo;
 	forwardedFlags?: string[];
@@ -376,6 +380,8 @@ export function executeAsyncChain(
 		maxSubagentDepth,
 		worktreeSetupHook,
 		worktreeSetupHookTimeoutMs,
+		worktreeTeardownHook,
+		worktreeTeardownHookTimeoutMs,
 		controlConfig,
 		nestedRoute,
 		forwardedFlags,
@@ -630,6 +636,8 @@ export function executeAsyncChain(
 				forwardedFlags,
 				worktreeSetupHook,
 				worktreeSetupHookTimeoutMs,
+				worktreeTeardownHook,
+				worktreeTeardownHookTimeoutMs,
 				controlConfig,
 				resultMode,
 				executionBackends: detachedExecutionBackends(ctx.executionBackend),
@@ -748,6 +756,8 @@ export function executeAsyncSingle(
 		maxSubagentDepth,
 		worktreeSetupHook,
 		worktreeSetupHookTimeoutMs,
+		worktreeTeardownHook,
+		worktreeTeardownHookTimeoutMs,
 		controlConfig,
 		nestedRoute,
 		forwardedFlags,
@@ -840,6 +850,8 @@ export function executeAsyncSingle(
 				forwardedFlags,
 				worktreeSetupHook,
 				worktreeSetupHookTimeoutMs,
+				worktreeTeardownHook,
+				worktreeTeardownHookTimeoutMs,
 				controlConfig,
 				resultMode: "single",
 				executionBackends: detachedExecutionBackends(ctx.executionBackend),

package/src/runs/background/subagent-runner.ts

@@ -120,6 +120,8 @@ interface SubagentRunConfig {
 	forwardedFlags?: string[];
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	worktreeTeardownHook?: string;
+	worktreeTeardownHookTimeoutMs?: number;
 	controlConfig?: ResolvedControlConfig;
 	resultMode?: SubagentRunMode;
 	dynamicFanoutMaxItems?: number;
@@ -2133,6 +2135,9 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 						setupHook: config.worktreeSetupHook
 							? { hookPath: config.worktreeSetupHook, timeoutMs: config.worktreeSetupHookTimeoutMs }
 							: undefined,
+						teardownHook: config.worktreeTeardownHook
+							? { hookPath: config.worktreeTeardownHook, timeoutMs: config.worktreeTeardownHookTimeoutMs }
+							: undefined,
 					});
 				} catch (error) {
 					const setupError = error instanceof Error ? error.message : String(error);

package/src/runs/foreground/chain-execution.ts

@@ -420,6 +420,8 @@ interface ChainExecutionParams {
 	nestedRoute?: NestedRouteInfo;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	worktreeTeardownHook?: string;
+	worktreeTeardownHookTimeoutMs?: number;
 	forwardedFlags?: string[];
 }
 
@@ -660,6 +662,9 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 							setupHook: params.worktreeSetupHook
 								? { hookPath: params.worktreeSetupHook, timeoutMs: params.worktreeSetupHookTimeoutMs }
 								: undefined,
+							teardownHook: params.worktreeTeardownHook
+								? { hookPath: params.worktreeTeardownHook, timeoutMs: params.worktreeTeardownHookTimeoutMs }
+								: undefined,
 						});
 					} catch (error) {
 						const message = error instanceof Error ? error.message : String(error);

package/src/runs/foreground/subagent-executor.ts

@@ -665,6 +665,8 @@ async function resumeAsyncRun(input: {
 		maxSubagentDepth: resolveCurrentMaxSubagentDepth(input.deps.config.maxSubagentDepth),
 		worktreeSetupHook: input.deps.config.worktreeSetupHook,
 		worktreeSetupHookTimeoutMs: input.deps.config.worktreeSetupHookTimeoutMs,
+		worktreeTeardownHook: input.deps.config.worktreeTeardownHook,
+		worktreeTeardownHookTimeoutMs: input.deps.config.worktreeTeardownHookTimeoutMs,
 		controlConfig: resolveControlConfig(input.deps.config.control, input.params.control),
 		availableModels,
 		forwardedFlags: input.deps.forwardedFlags,
@@ -1073,6 +1075,8 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			maxSubagentDepth: currentMaxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+			worktreeTeardownHook: deps.config.worktreeTeardownHook,
+			worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 			controlConfig,
 			nestedRoute,
 			forwardedFlags: deps.forwardedFlags,
@@ -1102,6 +1106,8 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			maxSubagentDepth: currentMaxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+			worktreeTeardownHook: deps.config.worktreeTeardownHook,
+			worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 			controlConfig,
 			nestedRoute,
 			forwardedFlags: deps.forwardedFlags,
@@ -1144,6 +1150,8 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			maxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+			worktreeTeardownHook: deps.config.worktreeTeardownHook,
+			worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 			controlConfig,
 			nestedRoute,
 			acceptance: params.acceptance,
@@ -1204,6 +1212,8 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 		maxSubagentDepth: currentMaxSubagentDepth,
 		worktreeSetupHook: deps.config.worktreeSetupHook,
 		worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+		worktreeTeardownHook: deps.config.worktreeTeardownHook,
+		worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 		forwardedFlags: deps.forwardedFlags,
 	});
 
@@ -1237,6 +1247,8 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 			maxSubagentDepth: currentMaxSubagentDepth,
 			worktreeSetupHook: deps.config.worktreeSetupHook,
 			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+			worktreeTeardownHook: deps.config.worktreeTeardownHook,
+			worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 			controlConfig,
 			nestedRoute: data.nestedRoute,
 			forwardedFlags: deps.forwardedFlags,
@@ -1299,6 +1311,8 @@ function createParallelWorktreeSetup(
 	tasks: TaskParam[],
 	setupHook: ExtensionConfig["worktreeSetupHook"],
 	setupHookTimeoutMs: ExtensionConfig["worktreeSetupHookTimeoutMs"],
+	teardownHook: ExtensionConfig["worktreeTeardownHook"],
+	teardownHookTimeoutMs: ExtensionConfig["worktreeTeardownHookTimeoutMs"],
 ): { setup?: WorktreeSetup; errorResult?: AgentToolResult<Details> } {
 	if (!enabled) return {};
 	try {
@@ -1308,6 +1322,9 @@ function createParallelWorktreeSetup(
 				setupHook: setupHook
 					? { hookPath: setupHook, timeoutMs: setupHookTimeoutMs }
 					: undefined,
+				teardownHook: teardownHook
+					? { hookPath: teardownHook, timeoutMs: teardownHookTimeoutMs }
+					: undefined,
 			}),
 		};
 	} catch (error) {
@@ -1691,6 +1708,8 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 				maxSubagentDepth: currentMaxSubagentDepth,
 				worktreeSetupHook: deps.config.worktreeSetupHook,
 				worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+				worktreeTeardownHook: deps.config.worktreeTeardownHook,
+				worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 				controlConfig,
 				forwardedFlags: deps.forwardedFlags,
 			});
@@ -1709,6 +1728,8 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 		tasks,
 		deps.config.worktreeSetupHook,
 		deps.config.worktreeSetupHookTimeoutMs,
+		deps.config.worktreeTeardownHook,
+		deps.config.worktreeTeardownHookTimeoutMs,
 	);
 	if (errorResult) return errorResult;
 
@@ -1952,6 +1973,8 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 				maxSubagentDepth,
 				worktreeSetupHook: deps.config.worktreeSetupHook,
 				worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
+				worktreeTeardownHook: deps.config.worktreeTeardownHook,
+				worktreeTeardownHookTimeoutMs: deps.config.worktreeTeardownHookTimeoutMs,
 				controlConfig,
 				forwardedFlags: deps.forwardedFlags,
 			});

package/src/runs/shared/worktree.ts

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import * as fs from "node:fs";
+import fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
@@ -10,6 +10,8 @@ export interface WorktreeSetup {
 }
 
 interface WorktreeInfo {
+	hookInput: WorktreeSetupHookInput;
+	teardownHook?: ResolvedWorktreeTeardownHook;
 	path: string;
 	agentCwd: string;
 	branch: string;
@@ -41,7 +43,18 @@ interface WorktreeSetupHookConfig {
 	timeoutMs?: number;
 }
 
+interface WorktreeTeardownHookConfig {
+	hookPath: string;
+	timeoutMs?: number;
+}
+
+interface ResolvedWorktreeTeardownHook {
+	hookPath: string;
+	timeoutMs: number;
+}
+
 interface CreateWorktreesOptions {
+	teardownHook?: WorktreeTeardownHookConfig;
 	agents?: string[];
 	setupHook?: WorktreeSetupHookConfig;
 }
@@ -229,6 +242,43 @@ function resolveWorktreeSetupHook(
 	};
 }
 
+function resolveWorktreeTeardownHook(
+	repoRoot: string,
+	config: WorktreeTeardownHookConfig | undefined,
+): ResolvedWorktreeTeardownHook | undefined {
+	if (!config) return undefined;
+	const hookPath = config.hookPath.trim();
+	if (!hookPath) {
+		throw new Error("worktree teardown hook path cannot be empty");
+	}
+
+	const expandedHookPath = hookPath.startsWith("~/") ? path.join(os.homedir(), hookPath.slice(2)) : hookPath;
+	let resolvedPath: string;
+	if (path.isAbsolute(expandedHookPath)) {
+		resolvedPath = expandedHookPath;
+	} else if (expandedHookPath.includes("/") || expandedHookPath.includes("\\")) {
+		resolvedPath = path.resolve(repoRoot, expandedHookPath);
+	} else {
+		throw new Error("worktree teardown hook must be an absolute path or a repo-relative path");
+	}
+
+	if (!fs.existsSync(resolvedPath)) {
+		throw new Error(`worktree teardown hook not found: ${resolvedPath}`);
+	}
+	if (fs.statSync(resolvedPath).isDirectory()) {
+		throw new Error(`worktree teardown hook must be a file, got directory: ${resolvedPath}`);
+	}
+
+	const timeoutMs = config.timeoutMs === undefined ? 30000 : config.timeoutMs;
+	if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+		throw new Error("worktree teardown hook timeout must be an integer greater than 0");
+	}
+	return {
+		hookPath: resolvedPath,
+		timeoutMs: timeoutMs,
+	};
+}
+
 function normalizeSyntheticPath(worktreePath: string, rawPath: string): string {
 	const trimmed = rawPath.trim();
 	if (!trimmed) throw new Error("synthetic path cannot be empty");
@@ -313,6 +363,40 @@ function runWorktreeSetupHook(
 	return [...uniquePaths];
 }
 
+function warnWorktreeCleanup(message: string): void {
+	try { fs.write(2, message + "\n", () => {}); } catch {}
+}
+
+function runWorktreeTeardownHook(
+	hook: ResolvedWorktreeTeardownHook | undefined,
+	input: WorktreeSetupHookInput,
+): void {
+	if (!hook) return;
+	try {
+		const result = spawnSync(hook.hookPath, [], {
+			cwd: input.worktreePath,
+			encoding: "utf-8",
+			input: JSON.stringify(input),
+			timeout: hook.timeoutMs,
+			killSignal: "SIGKILL",
+			shell: false,
+			stdio: ["pipe", "ignore", "pipe"],
+		});
+		let cause: string;
+		if (result.error) {
+			cause = "code" in result.error && result.error.code === "ETIMEDOUT"
+				? `timed out after ${hook.timeoutMs}ms`
+				: result.error.message;
+		} else if (result.status !== 0) {
+			cause = result.signal ? `signal ${result.signal}` : `exit code ${result.status}`;
+		} else return;
+		const stderr = result.stderr?.trim();
+		warnWorktreeCleanup(`worktree teardown hook failed for '${input.worktreePath}': ${cause}${stderr ? `: ${stderr}` : ""}`);
+	} catch (error) {
+		warnWorktreeCleanup(`worktree teardown hook failed for '${input.worktreePath}': ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
 function createSingleWorktree(
 	toplevel: string,
 	cwdRelative: string,
@@ -320,6 +404,7 @@ function createSingleWorktree(
 	index: number,
 	baseCommit: string,
 	setupHook: ResolvedWorktreeSetupHook | undefined,
+	teardownHook: ResolvedWorktreeTeardownHook | undefined,
 	agent: string | undefined,
 ): WorktreeInfo {
 	const branch = buildWorktreeBranch(runId, index);
@@ -331,27 +416,22 @@ function createSingleWorktree(
 	}
 
 	const agentCwd = cwdRelative ? path.join(worktreePath, cwdRelative) : worktreePath;
+	const hookInput: WorktreeSetupHookInput = {
+		version: 1, repoRoot: toplevel, worktreePath, agentCwd, branch, index, runId, baseCommit, agent,
+	};
 	try {
 		const nodeModulesLinked = linkNodeModulesIfPresent(toplevel, worktreePath);
 		const syntheticPaths = nodeModulesLinked ? ["node_modules"] : [];
 
 		if (setupHook) {
-			const hookSyntheticPaths = runWorktreeSetupHook(setupHook, {
-				version: 1,
-				repoRoot: toplevel,
-				worktreePath,
-				agentCwd,
-				branch,
-				index,
-				runId,
-				baseCommit,
-				agent,
-			});
+			const hookSyntheticPaths = runWorktreeSetupHook(setupHook, hookInput);
 			syntheticPaths.push(...hookSyntheticPaths);
 		}
 
 		return {
 			path: worktreePath,
+			hookInput,
+			teardownHook,
 			agentCwd,
 			branch,
 			index,
@@ -359,11 +439,12 @@ function createSingleWorktree(
 			syntheticPaths,
 		};
 	} catch (error) {
-		try { runGitChecked(toplevel, ["worktree", "remove", "--force", worktreePath]); } catch {
-			// Best-effort rollback; preserve the original setup failure.
+		runWorktreeTeardownHook(teardownHook, hookInput);
+		try { runGitChecked(toplevel, ["worktree", "remove", "--force", worktreePath]); } catch (cleanupError) {
+			warnWorktreeCleanup(`worktree remove failed for '${worktreePath}': ${cleanupError}`);
 		}
-		try { runGitChecked(toplevel, ["branch", "-D", branch]); } catch {
-			// Best-effort rollback; preserve the original setup failure.
+		try { runGitChecked(toplevel, ["branch", "-D", branch]); } catch (cleanupError) {
+			warnWorktreeCleanup(`branch -D '${branch}' failed for '${worktreePath}': ${cleanupError}`);
 		}
 		throw error;
 	}
@@ -477,11 +558,12 @@ function writeEmptyPatch(patchPath: string): void {
 }
 
 function cleanupSingleWorktree(repoCwd: string, worktree: WorktreeInfo): void {
-	try { runGitChecked(repoCwd, ["worktree", "remove", "--force", worktree.path]); } catch {
-		// Cleanup is best-effort to avoid masking caller errors.
+	runWorktreeTeardownHook(worktree.teardownHook, worktree.hookInput);
+	try { runGitChecked(repoCwd, ["worktree", "remove", "--force", worktree.path]); } catch (error) {
+		warnWorktreeCleanup(`worktree remove failed for '${worktree.path}': ${error}`);
 	}
-	try { runGitChecked(repoCwd, ["branch", "-D", worktree.branch]); } catch {
-		// Cleanup is best-effort to avoid masking caller errors.
+	try { runGitChecked(repoCwd, ["branch", "-D", worktree.branch]); } catch (error) {
+		warnWorktreeCleanup(`branch -D '${worktree.branch}' failed for '${worktree.path}': ${error}`);
 	}
 }
 
@@ -498,6 +580,7 @@ export function patchPathForDiff(diff: WorktreeDiff): string | undefined {
 export function createWorktrees(cwd: string, runId: string, count: number, options?: CreateWorktreesOptions): WorktreeSetup {
 	const repo = resolveRepoState(cwd);
 	const setupHook = resolveWorktreeSetupHook(repo.toplevel, options?.setupHook);
+	const teardownHook = resolveWorktreeTeardownHook(repo.toplevel, options?.teardownHook);
 	const worktrees: WorktreeInfo[] = [];
 
 	try {
@@ -509,6 +592,7 @@ export function createWorktrees(cwd: string, runId: string, count: number, optio
 				index,
 				repo.baseCommit,
 				setupHook,
+				teardownHook,
 				options?.agents?.[index],
 			));
 		}

package/src/shared/types.ts

@@ -869,6 +869,8 @@ export interface ExtensionConfig {
 	chain?: ExtensionChainConfig;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
+	worktreeTeardownHook?: string;
+	worktreeTeardownHookTimeoutMs?: number;
 	/** Print a roster of discovered subagents/chains into chat at session start. Default: true. */
 	showRosterOnStart?: boolean;
 	/** Forward the parent pi's extension CLI flags (e.g. --no-autofix) into spawned children. Default: true. */