pi-subagents 0.40.0 → 0.42.0

package/src/runs/shared/pi-spawn.ts

@@ -70,6 +70,11 @@ function normalizePath(filePath: string): string {
 	return path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
 }
 
+function isStandalonePiExecutable(execPath: string): boolean {
+	const executableName = execPath.split(/[\\/]/).pop();
+	return /^pi(?:\.exe)?$/i.test(executableName ?? "");
+}
+
 export function resolvePiCliScript(
 	deps: PiSpawnDeps = {},
 ): string | undefined {
@@ -141,10 +146,15 @@ export function getPiSpawnCommand(
 		return { command: piBinary, args };
 	}
 
+	const execPath = deps.execPath ?? process.execPath;
+	if (isStandalonePiExecutable(execPath)) {
+		return { command: execPath, args };
+	}
+
 	const piCliPath = resolvePiCliScript(deps);
 	if (piCliPath) {
 		return {
-			command: deps.execPath ?? process.execPath,
+			command: execPath,
 			args: [piCliPath, ...args],
 		};
 	}

package/src/runs/shared/run-history.ts

@@ -176,6 +176,6 @@ export function loadRunsForAgent(agent: string): RunEntry[] {
 
 	return lines
 		.map((line) => { try { return JSON.parse(line) as RunEntry; } catch { return undefined; } })
-		.filter((entry): entry is RunEntry => Boolean(entry) && entry.agent === agent)
+		.filter((entry): entry is RunEntry => entry !== undefined && entry.agent === agent)
 		.reverse();
 }

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -1,7 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { registerNativeSupervisorClient } from "../../intercom/native-supervisor-channel.ts";
+import { decodePermissionRules, permissionDecision, PERMISSION_AUDIT_PATH_ENV, PERMISSION_POLICY_ENV } from "./permissions.ts";
 import { consumeSteerRequestsFromDir, steerAckPathFromDir, writeSteerAckAt, writeSteerCapabilityAt, writeSteerRequestToDir, type SteerRequest } from "../background/control-channel.ts";
 import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_STEER_ACK_DIR_ENV, SUBAGENT_STEER_CAPABILITY_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
 import { RUNTIME_EXTENSION_ACK_EVENT, RUNTIME_EXTENSION_ACK_PATH_ENV, isRuntimeAcknowledgedExtensionId, writeRuntimeAcknowledgedExtensions } from "./runtime-acknowledged-extensions.ts";
@@ -18,6 +19,8 @@ import type { JsonSchemaObject, ResolvedToolBudget, SubagentState } from "../../
 import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
 import { resolveWatchPath } from "../../shared/utils.ts";
 import { registerChildWatchdog } from "../../watchdog/register-child.ts";
+import { CHILD_WATCHDOG_CONFIG_ENV } from "../../watchdog/child-status.ts";
+import { requestWatchdogPermission, type WatchdogPermissionRequest, type WatchdogPermissionResult } from "../../watchdog/permission-arbiter.ts";
 import { SUBAGENT_WATCHDOG_WARNING_TYPE } from "../../watchdog/types.ts";
 import { resolveWaitToolConfig } from "../background/wait-config.ts";
 import { registerWaitTool } from "../background/wait-tool.ts";
@@ -241,6 +244,31 @@ export function formatSteerMessage(request: SteerRequest): string {
 	].join("\n");
 }
 
+export function registerPermissionGate(
+	pi: ExtensionAPI,
+	requestPermission: (request: WatchdogPermissionRequest) => Promise<WatchdogPermissionResult> = requestWatchdogPermission,
+): void {
+	const rules = decodePermissionRules(process.env[PERMISSION_POLICY_ENV]);
+	if (!rules) return;
+	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: { toolName?: string; input?: unknown }, ctx: ExtensionContext) => unknown) => void;
+	onRuntimeEvent("tool_call", async (event, ctx) => {
+		const toolName = typeof event.toolName === "string" ? event.toolName : "tool";
+		const decision = permissionDecision(rules, toolName);
+		if (decision === "allow") return undefined;
+		if (decision === "deny") return { block: true, reason: `Blocked by pi-subagents permission rule: '${toolName}' is denied.` };
+		const result = await requestPermission({
+			ctx,
+			toolName,
+			args: event.input ?? {},
+			rawWatchdogConfig: process.env[CHILD_WATCHDOG_CONFIG_ENV],
+			auditPath: process.env[PERMISSION_AUDIT_PATH_ENV],
+			...(ctx.signal ? { signal: ctx.signal } : {}),
+		});
+		if (result.approved) return undefined;
+		return { block: true, reason: `Blocked by pi-subagents permission rule: ${result.reason}` };
+	});
+}
+
 function registerToolBudget(pi: ExtensionAPI, budget: ResolvedToolBudget | undefined): void {
 	if (!budget) return;
 	let toolCount = 0;
@@ -360,7 +388,7 @@ export function registerSteeringInbox(
 		return undefined;
 	};
 
-	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown) => unknown) => void;
+	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown, ctx?: unknown) => unknown) => void;
 	// Register input before the watcher so an accepted extension input cannot race request dispatch.
 	onRuntimeEvent("input", onInput);
 	onRuntimeEvent("session_start", () => start());
@@ -377,6 +405,7 @@ export function registerSteeringInbox(
 export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 	registerRuntimeExtensionAcknowledgements(pi);
 	registerSteeringInbox(pi);
+	registerPermissionGate(pi);
 	registerToolBudget(pi, decodeToolBudgetEnv(process.env[TOOL_BUDGET_ENV], { allowZero: process.env[TOOL_BUDGET_ZERO_AUTH_ENV] === "1" }));
 	registerChildWatchdog(pi);
 	const waitToolEnabled = resolveWaitToolConfig().enabled;
@@ -408,7 +437,7 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 		nativeSupervisorFallbackRegistered = true;
 		registerNativeSupervisorClient(pi);
 	};
-	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown) => unknown) => void;
+	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown, ctx?: unknown) => unknown) => void;
 	onRuntimeEvent("session_start", (_event: unknown, ctx: unknown) => {
 		const sessionManager = (ctx as { sessionManager?: Parameters<typeof resolveCurrentSessionId>[0] } | undefined)?.sessionManager;
 		waitState.currentSessionId = sessionManager ? resolveCurrentSessionId(sessionManager) : null;
@@ -455,13 +484,15 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
 		});
 	}
 
-	onRuntimeEvent("context", (event: { messages: unknown[] }) => {
+	onRuntimeEvent("context", (event: unknown) => {
+		if (!event || typeof event !== "object" || !("messages" in event) || !Array.isArray(event.messages)) return undefined;
 		const messages = stripParentOnlySubagentMessages(event.messages);
 		if (messages === event.messages) return undefined;
 		return { messages };
 	});
 
-	onRuntimeEvent("before_agent_start", async (event: { systemPrompt: string }) => {
+	onRuntimeEvent("before_agent_start", async (event: unknown) => {
+		if (!event || typeof event !== "object" || !("systemPrompt" in event) || typeof event.systemPrompt !== "string") return undefined;
 		registerNativeSupervisorFallbackOnce();
 		const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
 		if (intercomSessionName && typeof pi.setSessionName === "function") {

package/src/runs/shared/subagent-startup-retry.ts

@@ -1,4 +1,5 @@
 import type { Usage } from "../../shared/types.ts";
+import { formatProcessSignalError } from "./process-signal.ts";
 
 /**
  * Retry delays for child processes that exit before any model or tool activity.
@@ -10,6 +11,8 @@ export const SUBAGENT_STARTUP_RETRY_DELAYS_MS = [250, 750, 1500] as const;
 /** A genuine startup race should fail well before a model request can complete. */
 export const MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS = 2000;
 
+const SIGKILL_PROCESS_SIGNAL_ERROR = formatProcessSignalError("SIGKILL");
+
 export interface SubagentStartupFailureEvidence {
 	exitCode: number | null | undefined;
 	error?: string;
@@ -46,7 +49,7 @@ export function isRetryableSubagentStartupFailure(evidence: SubagentStartupFailu
 	return evidence.exitCode !== undefined
 		&& evidence.exitCode !== null
 		&& evidence.exitCode !== 0
-		&& !evidence.error?.trim()
+		&& (!evidence.error?.trim() || evidence.error === SIGKILL_PROCESS_SIGNAL_ERROR)
 		&& !evidence.finalOutput?.trim()
 		&& evidence.messageCount === 0
 		&& evidence.toolCount === 0
@@ -54,7 +57,7 @@ export function isRetryableSubagentStartupFailure(evidence: SubagentStartupFailu
 		&& evidence.durationMs >= 0
 		&& evidence.durationMs <= MAX_SUBAGENT_STARTUP_FAILURE_DURATION_MS
 		&& evidence.protocolError === undefined
-		&& (evidence.processSignal === undefined || evidence.processSignal === null)
+		&& (evidence.processSignal === undefined || evidence.processSignal === null || evidence.processSignal === "SIGKILL")
 		&& evidence.observedMutationAttempt !== true
 		&& evidence.detached !== true
 		&& evidence.interrupted !== true

package/src/runs/shared/turn-budget.ts

@@ -23,9 +23,10 @@ export function resolveTurnBudgetConfig(
 	return { turnBudget: { maxTurns: budget.maxTurns, graceTurns } };
 }
 
-export function appendTurnBudgetSystemPrompt(systemPrompt: string, budget: ResolvedTurnBudget | undefined): string {
+export function appendTurnBudgetSystemPrompt(systemPrompt: string, budget: { maxTurns: number; graceTurns?: number } | undefined): string {
 	if (!budget) return systemPrompt;
-	const grace = budget.graceTurns === 1 ? "1 additional assistant turn" : `${budget.graceTurns} additional assistant turns`;
+	const graceTurns = budget.graceTurns ?? DEFAULT_TURN_BUDGET_GRACE_TURNS;
+	const grace = graceTurns === 1 ? "1 additional assistant turn" : `${graceTurns} additional assistant turns`;
 	const block = [
 		"## Turn budget",
 		`This child run has a soft budget of ${budget.maxTurns} assistant turn${budget.maxTurns === 1 ? "" : "s"}.`,
@@ -55,8 +56,8 @@ export function formatTurnBudgetOutput(message: string, output: string): string
 		: message;
 }
 
-export function initialTurnBudgetState(budget: ResolvedTurnBudget): TurnBudgetState {
-	return { ...budget, outcome: "within-budget", turnCount: 0 };
+export function initialTurnBudgetState(budget: { maxTurns: number; graceTurns?: number }): TurnBudgetState {
+	return { maxTurns: budget.maxTurns, graceTurns: budget.graceTurns ?? DEFAULT_TURN_BUDGET_GRACE_TURNS, outcome: "within-budget", turnCount: 0 };
 }
 
 export function turnBudgetState(budget: ResolvedTurnBudget, turnCount: number, exceeded: boolean): TurnBudgetState {
@@ -91,8 +92,7 @@ export function turnBudgetDecision(
 	enforceHardLimit = false,
 ): "continue" | "defer" | "abort" {
 	const hardLimit = budget.maxTurns + budget.graceTurns;
-	if (turnCount < hardLimit) return "continue";
+	if (terminalAssistantStop || turnCount < hardLimit) return "continue";
 	if (toolWorkActiveOrStarting && !enforceHardLimit) return "defer";
-	if (turnCount === hardLimit && terminalAssistantStop) return "continue";
 	return "abort";
 }

package/src/runs/shared/worktree.ts

@@ -2,14 +2,16 @@ import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { resolveAuthorityDecision, type AuthorityPolicyConfig } from "../../policy/authority.ts";
 
 export interface WorktreeSetup {
 	cwd: string;
 	worktrees: WorktreeInfo[];
 	baseCommit: string;
+	capturedDiffs?: WorktreeDiff[];
 }
 
-interface WorktreeInfo {
+export interface WorktreeInfo {
 	path: string;
 	agentCwd: string;
 	branch: string;
@@ -36,9 +38,21 @@ export interface WorktreeCleanupTask {
 	branch: string;
 	worktreeRemoved: boolean;
 	branchRemoved: boolean;
+	preserved?: boolean;
+	reason?: string;
 	errors?: string[];
 }
 
+export type WorktreeCleanupIntent =
+	| { kind: "preserve"; capturedDiffs?: WorktreeDiff[]; handoffManifestPath?: string }
+	| {
+		kind: "discard";
+		authorization:
+			| { kind: "policy"; policy?: AuthorityPolicyConfig }
+			| { kind: "confirmed"; policy?: AuthorityPolicyConfig };
+	}
+	| { kind: "setup-rollback" };
+
 export interface WorktreeCleanupReport {
 	state: "complete" | "partial";
 	tasks: WorktreeCleanupTask[];
@@ -121,7 +135,9 @@ function resolveRepoState(cwd: string): RepoState {
 	const cwdRelative = resolveRepoCwdRelative(cwd);
 	const toplevel = runGitChecked(cwd, ["rev-parse", "--show-toplevel"]).trim();
 
-	const status = runGitChecked(toplevel, ["status", "--porcelain"]);
+	// pi-subagents writes durable runtime state under .pi-subagents/ by default;
+	// that state must not make managed isolation unusable for later runs.
+	const status = runGitChecked(toplevel, ["status", "--porcelain", "--", ":!.pi-subagents"]);
 	if (status.trim().length > 0) {
 		throw new Error("worktree isolation requires a clean git working tree. Commit or stash changes first.");
 	}
@@ -515,21 +531,111 @@ function writeEmptyPatch(patchPath: string): void {
 	}
 }
 
-function cleanupSingleWorktree(repoCwd: string, worktree: WorktreeInfo): WorktreeCleanupTask {
+function handoffRecordsPatch(manifestPath: string | undefined, patchPath: string): boolean {
+	if (!manifestPath || !fs.existsSync(manifestPath)) return false;
+	try {
+		const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8")) as {
+			version?: unknown;
+			groups?: Array<{ children?: Array<{ patch?: { path?: unknown; error?: unknown } }> }>;
+		};
+		if (manifest.version !== 1 || !Array.isArray(manifest.groups)) return false;
+		const resolvedPatchPath = path.resolve(patchPath);
+		return manifest.groups.some((group) => Array.isArray(group.children) && group.children.some((child) =>
+			child.patch?.error === undefined
+			&& typeof child.patch?.path === "string"
+			&& path.resolve(child.patch.path) === resolvedPatchPath,
+		));
+	} catch {
+		return false;
+	}
+}
+
+function cleanupSingleWorktree(
+	setup: WorktreeSetup,
+	worktree: WorktreeInfo,
+	intent: WorktreeCleanupIntent,
+): WorktreeCleanupTask {
 	const errors: string[] = [];
 	let worktreeRemoved = false;
 	let branchRemoved = false;
+	if (intent.kind !== "setup-rollback") {
+		try {
+			removeSyntheticPathsBeforeDiff(worktree);
+		} catch (error) {
+			errors.push(`synthetic path cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const status = runGit(worktree.path, ["status", "--porcelain"]);
+		const baseDiff = runGit(worktree.path, ["diff", "--quiet", setup.baseCommit, "--"]);
+		if (status.status !== 0 || (baseDiff.status !== 0 && baseDiff.status !== 1)) {
+			const reason = status.status !== 0
+				? status.stderr.trim() || status.stdout.trim() || "git status failed"
+				: baseDiff.stderr.trim() || baseDiff.stdout.trim() || "git diff check failed";
+			return {
+				index: worktree.index,
+				path: worktree.path,
+				branch: worktree.branch,
+				worktreeRemoved: false,
+				branchRemoved: false,
+				preserved: true,
+				reason: "cleanup safety check failed",
+				errors: [...errors, `cleanup refused: ${reason}`],
+			};
+		}
+		const hasWork = status.stdout.trim().length > 0 || baseDiff.status === 1;
+		if (hasWork && intent.kind === "preserve") {
+			const captured = (intent.capturedDiffs ?? setup.capturedDiffs)?.find((diff) => diff.index === worktree.index);
+			const patchCaptured = captured !== undefined
+				&& captured.error === undefined
+				&& fs.existsSync(captured.patchPath)
+				&& fs.statSync(captured.patchPath).size > 0
+				&& handoffRecordsPatch(intent.handoffManifestPath, captured.patchPath);
+			if (!patchCaptured) {
+				const reason = "worktree contains changes that are not represented by a captured handoff patch";
+				return {
+					index: worktree.index,
+					path: worktree.path,
+					branch: worktree.branch,
+					worktreeRemoved: false,
+					branchRemoved: false,
+					preserved: true,
+					reason,
+					errors: [...errors, `cleanup refused: ${reason}; preserved ${worktree.path}`],
+				};
+			}
+		}
+		if (hasWork && intent.kind === "discard") {
+			const decision = resolveAuthorityDecision({ action: "discardWorktree", policy: intent.authorization.policy });
+			const authorized = decision === "auto" || (decision === "confirm" && intent.authorization.kind === "confirmed");
+			if (!authorized) {
+				const reason = decision === "forbid"
+					? "authority policy forbids worktree discard"
+					: "worktree discard requires explicit user confirmation";
+				return {
+					index: worktree.index,
+					path: worktree.path,
+					branch: worktree.branch,
+					worktreeRemoved: false,
+					branchRemoved: false,
+					preserved: true,
+					reason,
+					errors: [...errors, `cleanup refused: ${reason}; preserved ${worktree.path}`],
+				};
+			}
+		}
+	}
 	try {
-		runGitChecked(repoCwd, ["worktree", "remove", "--force", worktree.path]);
+		runGitChecked(setup.cwd, ["worktree", "remove", "--force", worktree.path]);
 		worktreeRemoved = true;
 	} catch (error) {
 		errors.push(`worktree removal failed: ${error instanceof Error ? error.message : String(error)}`);
 	}
-	try {
-		runGitChecked(repoCwd, ["branch", "-D", worktree.branch]);
-		branchRemoved = true;
-	} catch (error) {
-		errors.push(`branch removal failed: ${error instanceof Error ? error.message : String(error)}`);
+	if (worktreeRemoved) {
+		try {
+			runGitChecked(setup.cwd, ["branch", "-D", worktree.branch]);
+			branchRemoved = true;
+		} catch (error) {
+			errors.push(`branch removal failed: ${error instanceof Error ? error.message : String(error)}`);
+		}
 	}
 	return {
 		index: worktree.index,
@@ -569,7 +675,7 @@ export function createWorktrees(cwd: string, runId: string, count: number, optio
 			cwd: repo.toplevel,
 			worktrees,
 			baseCommit: repo.baseCommit,
-		});
+		}, { kind: "setup-rollback" });
 		throw error;
 	}
 
@@ -602,13 +708,17 @@ export function diffWorktrees(setup: WorktreeSetup, agents: string[], diffsDir:
 		}
 	}
 
+	setup.capturedDiffs = diffs;
 	return diffs;
 }
 
-export function cleanupWorktrees(setup: WorktreeSetup): WorktreeCleanupReport {
+export function cleanupWorktrees(
+	setup: WorktreeSetup,
+	intent: WorktreeCleanupIntent = { kind: "preserve", ...(setup.capturedDiffs ? { capturedDiffs: setup.capturedDiffs } : {}) },
+): WorktreeCleanupReport {
 	const tasks: WorktreeCleanupTask[] = [];
 	for (let index = setup.worktrees.length - 1; index >= 0; index--) {
-		tasks.push(cleanupSingleWorktree(setup.cwd, setup.worktrees[index]!));
+		tasks.push(cleanupSingleWorktree(setup, setup.worktrees[index]!, intent));
 	}
 	tasks.sort((left, right) => left.index - right.index);
 	const errors: string[] = [];

package/src/shared/accessible-dir.ts

@@ -8,18 +8,40 @@ type AccessibleDirOptions = {
 	retryDirectoryErrors?: boolean;
 	retryDelaysMs?: readonly number[];
 	wait?: (delayMs: number) => void;
+	pid?: number;
 };
 
-export function ensureAccessibleDir(dirPath: string, options: AccessibleDirOptions = {}): void {
+export function ensureAccessibleDir(dirPath: string, options: AccessibleDirOptions = {}): string {
 	const fsImpl = options.fs ?? fs;
+	const pid = options.pid ?? process.pid;
 	const retryDirectoryErrors = options.retryDirectoryErrors ?? process.platform === "win32";
 	const retryDelaysMs = retryDirectoryErrors ? options.retryDelaysMs ?? DEFAULT_FILE_SYSTEM_RETRY_DELAYS_MS : [];
 	const wait = options.wait ?? waitForFileSystemRetry;
 
-	runFileSystemOperationWithRetry(() => {
-		fsImpl.mkdirSync(dirPath, { recursive: true });
-	}, { retryDelaysMs, wait });
-	runFileSystemOperationWithRetry(() => {
-		fsImpl.accessSync(dirPath, fs.constants.R_OK | fs.constants.W_OK);
-	}, { retryDelaysMs, wait });
+	const mkdirWithRetry = (target: string): void => {
+		runFileSystemOperationWithRetry(() => {
+			fsImpl.mkdirSync(target, { recursive: true });
+		}, { retryDelaysMs, wait });
+	};
+	const accessWithRetry = (target: string): void => {
+		runFileSystemOperationWithRetry(() => {
+			fsImpl.accessSync(target, fs.constants.R_OK | fs.constants.W_OK);
+		}, { retryDelaysMs, wait });
+	};
+	const fallbackPath = (): string => {
+		const fallback = `${dirPath}-${pid}`;
+		mkdirWithRetry(fallback);
+		accessWithRetry(fallback);
+		return fallback;
+	};
+
+	try {
+		mkdirWithRetry(dirPath);
+		accessWithRetry(dirPath);
+		return dirPath;
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException | undefined)?.code;
+		if (code !== "EPERM" && code !== "EACCES") throw error;
+		return fallbackPath();
+	}
 }

package/src/shared/artifacts.ts

@@ -1,10 +1,135 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { TEMP_ARTIFACTS_DIR, type ArtifactPaths, type ArtifactDirPreference } from "./types.ts";
+import { CHAIN_RUNS_DIR, TEMP_ARTIFACTS_DIR, type ArtifactPaths, type ArtifactDirPreference } from "./types.ts";
 import { getAgentDir } from "./utils.ts";
 const CLEANUP_MARKER_FILE = ".last-cleanup";
 const PROJECT_ARTIFACT_ROOT = ".pi-subagents";
 
+const PROJECT_ARTIFACT_PATHS = [
+	`${PROJECT_ARTIFACT_ROOT}/artifacts/output.md`,
+	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker_input.md`,
+	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker_output.md`,
+	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker.jsonl`,
+	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker_transcript.jsonl`,
+	`${PROJECT_ARTIFACT_ROOT}/artifacts/run_worker_meta.json`,
+	`${PROJECT_ARTIFACT_ROOT}/artifacts/progress/run/progress.md`,
+	`${PROJECT_ARTIFACT_ROOT}/artifacts/outputs/output.md`,
+	`${PROJECT_ARTIFACT_ROOT}/artifacts/outputs/run/output.md`,
+	`${PROJECT_ARTIFACT_ROOT}/chain-runs/run.json`,
+];
+
+function globMatchesPath(pattern: string, filePath: string): boolean {
+	let expression = "^";
+	for (let index = 0; index < pattern.length; index += 1) {
+		const character = pattern[index];
+		if (character === undefined) break;
+		if (character === "*" && pattern[index + 1] === "*") {
+			index += 1;
+			if (pattern[index + 1] === "/") {
+				index += 1;
+				expression += "(?:.*/)?";
+			} else {
+				expression += ".*";
+			}
+		} else if (character === "*") {
+			expression += "[^/]*";
+		} else if (character === "?") {
+			expression += "[^/]";
+		} else if (character === "[") {
+			const end = pattern.indexOf("]", index + 1);
+			if (end === -1) expression += "\\[";
+			else {
+				expression += pattern.slice(index, end + 1);
+				index = end;
+			}
+		} else {
+			expression += character.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+		}
+	}
+	try {
+		return new RegExp(`${expression}$`).test(filePath);
+	} catch {
+		return false;
+	}
+}
+
+function normalizePattern(pattern: string): string {
+	return pattern.replace(/^\.\//, "").replace(/^\//, "").replace(/\/+$/, "");
+}
+
+function patternMatchesArtifactPath(pattern: string, artifactPath: string): boolean {
+	const normalized = normalizePattern(pattern);
+	return normalized === PROJECT_ARTIFACT_ROOT
+		|| normalized === "*"
+		|| artifactPath.startsWith(`${normalized}/`)
+		|| globMatchesPath(normalized, artifactPath);
+}
+
+function patternMatchesProjectArtifacts(pattern: string): boolean {
+	return PROJECT_ARTIFACT_PATHS.some((artifactPath) => patternMatchesArtifactPath(pattern, artifactPath));
+}
+
+function ignoreFileExcludesProjectArtifacts(filePath: string): boolean {
+	if (!fs.existsSync(filePath)) return false;
+	try {
+		const excluded = new Set<string>();
+		for (const rawLine of fs.readFileSync(filePath, "utf-8").split(/\r?\n/)) {
+			const line = rawLine.trim();
+			if (!line || line.startsWith("#")) continue;
+			const negated = line.startsWith("!");
+			const pattern = negated ? line.slice(1) : line;
+			for (const artifactPath of PROJECT_ARTIFACT_PATHS) {
+				if (!patternMatchesArtifactPath(pattern, artifactPath)) continue;
+				if (negated) excluded.delete(artifactPath);
+				else excluded.add(artifactPath);
+			}
+		}
+		return excluded.size === PROJECT_ARTIFACT_PATHS.length;
+	} catch {
+		return false;
+	}
+}
+
+function filesIncludeProjectArtifacts(files: unknown): boolean | undefined {
+	if (!Array.isArray(files)) return undefined;
+	const included = new Set<string>();
+	for (const entry of files) {
+		if (typeof entry !== "string") continue;
+		const negated = entry.startsWith("!");
+		const pattern = negated ? entry.slice(1) : entry;
+		for (const artifactPath of PROJECT_ARTIFACT_PATHS) {
+			if (!patternMatchesArtifactPath(pattern, artifactPath)) continue;
+			if (negated) included.delete(artifactPath);
+			else included.add(artifactPath);
+		}
+	}
+	return included.size > 0;
+}
+
+/** Returns a package-publishing warning when project artifacts can enter npm packages. */
+export function getProjectArtifactPackagingWarning(cwd: string): string | undefined {
+	const packagePath = path.join(cwd, "package.json");
+	if (!fs.existsSync(packagePath)) return undefined;
+
+	let packageJson: Record<string, unknown>;
+	try {
+		const parsed: unknown = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+		packageJson = parsed as Record<string, unknown>;
+	} catch {
+		return undefined;
+	}
+
+	const filesIncludeArtifacts = filesIncludeProjectArtifacts(packageJson.files);
+	if (filesIncludeArtifacts === false) return undefined;
+
+	const npmIgnorePath = path.join(cwd, ".npmignore");
+	const ignorePath = fs.existsSync(npmIgnorePath) ? npmIgnorePath : path.join(cwd, ".gitignore");
+	if (filesIncludeArtifacts === undefined && ignoreFileExcludesProjectArtifacts(ignorePath)) return undefined;
+
+	return "Project-scoped subagent artifacts can be included when this package is published. Add '.pi-subagents/' to .npmignore, restrict package.json files, or set artifactDir to 'session' or 'temp'.";
+}
+
 export function getProjectSubagentsDir(cwd: string): string {
 	return path.join(cwd, PROJECT_ARTIFACT_ROOT);
 }
@@ -17,6 +142,21 @@ export function getProjectChainRunsDir(cwd: string): string {
 	return path.join(getProjectSubagentsDir(cwd), "chain-runs");
 }
 
+export function getChainRunsDir(
+	projectCwd: string,
+	dirPreference: ArtifactDirPreference = "project",
+): string {
+	switch (dirPreference) {
+		case "project":
+			return getProjectChainRunsDir(projectCwd);
+		case "session":
+		case "temp":
+			return CHAIN_RUNS_DIR;
+		default:
+			throw new Error(`Unsupported artifactDir ${JSON.stringify(dirPreference)}; expected "project", "session", or "temp".`);
+	}
+}
+
 export function getArtifactsDir(
 	sessionFile: string | null,
 	projectCwd?: string,
@@ -61,6 +201,7 @@ export function ensureArtifactsDir(dir: string): void {
 }
 
 export function writeArtifact(filePath: string, content: string): void {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	fs.writeFileSync(filePath, content, "utf-8");
 }
 
@@ -78,6 +219,7 @@ export function formatOutputArtifactContent(input: {
 }
 
 export function writeMetadata(filePath: string, metadata: object): void {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	fs.writeFileSync(filePath, JSON.stringify(metadata, null, 2), "utf-8");
 }
 

package/src/shared/fork-context.ts

@@ -77,8 +77,9 @@ function isUnsafeAnthropicThinkingBlock(message: BranchSessionEntry["message"],
 	const isAnthropic = provider === "anthropic" || api === "anthropic-messages" || model.startsWith("anthropic/");
 	if (block.type === "redacted_thinking") return true;
 	if (block.type !== "thinking" || !isAnthropic) return false;
-	const signature = "thinkingSignature" in block ? block.thinkingSignature : "signature" in block ? block.signature : undefined;
-	return block.redacted === true || (typeof signature === "string" && signature.length > 0);
+	const record = block as Record<string, unknown>;
+	const signature = "thinkingSignature" in record ? record.thinkingSignature : "signature" in record ? record.signature : undefined;
+	return record.redacted === true || (typeof signature === "string" && signature.length > 0);
 }
 
 function createEntryId(entries: BranchSessionEntry[]): string {

package/src/shared/launch-contract.ts

@@ -38,6 +38,7 @@ export function projectAgentDefinition(agent: AgentConfig): Record<string, unkno
 		packageName: agent.packageName,
 		filePath: agent.filePath,
 		fileContentDigest: fileDigest(agent.filePath),
+		runner: agent.runner,
 		systemPrompt: agent.systemPrompt,
 		systemPromptMode: agent.systemPromptMode,
 		inheritProjectContext: agent.inheritProjectContext,

package/src/shared/settings.ts

@@ -120,6 +120,16 @@ export interface CheckpointStep {
 	message?: string;
 	phase?: string;
 	label?: string;
+	agent?: string;
+	task?: string;
+	as?: string;
+	output?: string | false;
+	outputMode?: OutputMode;
+	reads?: string[] | false;
+	progress?: boolean;
+	skill?: string | string[] | false;
+	skills?: string[] | false;
+	model?: string;
 }
 
 /** Parallel step: multiple agents running concurrently */