pi-crew 0.11.5 → 0.11.7

package/src/prompt/prompt-runtime.ts

@@ -16,6 +16,7 @@ import { pollWorkerInbox } from "./inbox-poll.ts";
 import { createMessageTool, type MessageToolParams as MessageToolInputs, shouldRegisterMessageTool } from "./message-tool.ts";
 import { registerScratchpadLifecycle } from "./scratchpad-lifecycle.ts";
 import { createWorkerActivityTracker, registerSurfaceWorkerLifecycle, trackToolActivity } from "./surface-worker.ts";
+import { createWorkerEventsChannel } from "./worker-events-channel.ts";
 
 export const PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV = "PI_TEAMS_INHERIT_PROJECT_CONTEXT";
 export const PI_TEAMS_INHERIT_SKILLS_ENV = "PI_TEAMS_INHERIT_SKILLS";
@@ -621,10 +622,19 @@ function findAskResponse(manifest: TeamRunManifest, questionId: string): Mailbox
  *  report — best-effort wait.resolve on EVERY terminal path (answered /
  *  timed-out / aborted). A rejected resolve leaves the task parked; the
  *  scheduler's TTL leak-guard (stale-reconciler) is the backstop, so the
- *  failure is logged, never thrown. */
-async function resolvePark(client: AskBrokerClientSurface, taskId: string, questionId: string): Promise<void> {
+ *  failure is logged, never thrown.
+ *  G5 (deep-review 2026-10-01): the terminal outcome rides the resolve frame
+ *  so the broker can emit `task.respond_delivered` ONLY when the worker
+ *  actually picked up the leader's mailbox response ("answered") — a
+ *  timed-out/aborted park was NOT a delivery and must not masquerade as one. */
+async function resolvePark(
+	client: AskBrokerClientSurface,
+	taskId: string,
+	questionId: string,
+	outcome: "answered" | "timed-out" | "aborted",
+): Promise<void> {
 	try {
-		const res = await client.request("wait.resolve", { to: taskId, questionId });
+		const res = await client.request("wait.resolve", { to: taskId, questionId, outcome });
 		if (!res.ok) {
 			logInternalError(
 				"prompt-runtime.ask-wait-resolve",
@@ -644,10 +654,11 @@ async function resolvePark(client: AskBrokerClientSurface, taskId: string, quest
 }
 
 /** ADR item 10: every ask-timeout outcome appends `ask.timedout` to the run's
- *  events.jsonl. The worker cannot rely on PI_CREW_EVENTS_PATH (scratchpad-
- *  gated), but the state store pins eventsPath === <stateRoot>/events.jsonl —
- *  the same invariant child-pi-spawn relies on to derive PI_CREW_STATE_ROOT.
- *  Fire-and-forget: never blocks the tool result. */
+ *  events.jsonl. WP-9 made PI_CREW_EVENTS_PATH unconditional (this comment
+ *  used to say it was scratchpad-gated — stale); this path predates that and
+ *  keeps deriving the file from the state store invariant eventsPath ===
+ *  <stateRoot>/events.jsonl — the same invariant child-pi-spawn relies on to
+ *  derive PI_CREW_STATE_ROOT. Fire-and-forget: never blocks the tool result. */
 function emitAskTimedOutEvent(stateRoot: string, runId: string, taskId: string, questionId: string): void {
 	appendEventFireAndForget(path.join(stateRoot, "events.jsonl"), {
 		type: "ask.timedout",
@@ -774,7 +785,7 @@ export function createAskTool(deps: AskToolDeps = {}): AskToolDefinition {
 				}
 				const waitedMs = now() - startedAt;
 				// Terminal report (ADR item 8): best-effort un-park on EVERY path.
-				await resolvePark(client, taskId, questionId);
+				await resolvePark(client, taskId, questionId, terminal);
 				if (terminal === "answered" && answer) {
 					return {
 						content: [{ type: "text" as const, text: renderAskAnswer(questionId, answer.body) }],
@@ -1021,6 +1032,33 @@ export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
 		void brokerHandle.close().catch(() => undefined);
 	});
 
+	// ── W5 (P2-2): observe worker auto-compaction ──────────────────────────
+	// Auto-compaction inside a worker is otherwise silent from the
+	// orchestrator's view (perf reports only see token jumps). The SDK fires
+	// `session_before_compact` right before the host pi compacts the session
+	// context; this listener OBSERVES ONLY — it returns undefined so the host
+	// proceeds with its own preparation untouched (host analog:
+	// compaction-guard.ts `pi.on("session_before_compact", async () => { return; })`).
+	// NAME DISCIPLINE: this is the SDK's SESSION compaction (host context
+	// summarization) — NOT pi-crew's internal `prepareCompaction` event-log
+	// rotation (event-log-rotation.ts); same word, different mechanism.
+	// Channel discipline (WP-9): createWorkerEventsChannel is registered
+	// unconditionally and self-no-ops without PI_CREW_EVENTS_PATH/
+	// PI_CREW_BROKER_RUN_ID, so a main user session pays nothing. Payload is
+	// scalar-only: branchEntries (large) and signal (AbortSignal) are never
+	// serialized; preparation fields are read defensively (SDK shape evolves).
+	const compactEventsChannel = createWorkerEventsChannel();
+	pi.on("session_before_compact", (event) => {
+		const tokensBefore = (event.preparation as { tokensBefore?: unknown } | undefined)?.tokensBefore;
+		compactEventsChannel.emit("worker.session_before_compact", {
+			reason: event.reason,
+			willRetry: event.willRetry,
+			branchEntryCount: event.branchEntries?.length ?? 0,
+			hasCustomInstructions: typeof event.customInstructions === "string",
+			...(typeof tokensBefore === "number" ? { tokensBefore } : {}),
+		});
+	});
+
 	// ── Task 5 (§15.2): worker inbox pickup ────────────────────────────────
 	// A broker-eligible worker ALSO picks up sibling DMs / group broadcasts
 	// (`kind:"message"` entries addressed to this task in the durable

package/src/runtime/agent-control.ts

@@ -1,6 +1,5 @@
-import { randomUUID } from "node:crypto";
 import type { PiTeamsConfig } from "../config/config.ts";
-import type { ControlReservation, TeamRunManifest } from "../state/types.ts";
+import type { TeamRunManifest } from "../state/types.ts";
 import { appendTaskAttentionEvent } from "./attention-events.ts";
 import { upsertCrewAgent } from "./crew-agent-records.ts";
 import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
@@ -200,16 +199,3 @@ function resetConsecutiveToolFailures(manifest: TeamRunManifest, agent: CrewAgen
 	};
 	upsertCrewAgent(manifest, updated);
 }
-
-/**
- * Reserve a control channel for a task before spawning its worker.
- * This ensures cancel/steer requests can be queued immediately
- * while the worker is still starting up.
- */
-export function reserveControlChannel(taskId: string, runId: string): ControlReservation {
-	return {
-		reservedAt: new Date().toISOString(),
-		controllerId: `ctrl:${taskId}:${randomUUID()}`,
-		acceptsControlEvents: true,
-	};
-}

package/src/runtime/background-runner.ts

@@ -544,6 +544,9 @@ export async function executeBackgroundRun(
 				workflow: wf as import("../workflows/workflow-config.ts").DynamicWorkflowConfig,
 				signal,
 				tokenBudget: wf.maxTokenBudget,
+				// SDD-3 W-C G13: workflow-config override for the agent-call cap
+				// (unset → ctx default; a run is always bounded).
+				maxAgentCalls: wf.maxAgentCalls,
 			});
 			await saveRunManifestAsync(dwfResult.manifest);
 			earlyResult = dwfResult;

package/src/runtime/broker/crew-broker.ts

@@ -54,12 +54,12 @@ import {
 	isRequestObject,
 	parseMsgSendParams,
 	parseWaitRequestParams,
-	parseWaitResolveParams,
 	safeStringify,
 	WAIT_REQUEST_TIMEOUT_SEC_DEFAULT,
 	WAIT_REQUEST_TIMEOUT_SEC_MAX,
 } from "./protocol/request-parsers.ts";
 import { recordWaitPolicyRejection, waitAuthError } from "./protocol/wait-auth.ts";
+import { handleWaitResolve } from "./protocol/wait-resolve.ts";
 import { pushWaitingToForegroundWaiter } from "./wait-push.ts";
 import { WaitStatusCache } from "./wait-status-cache.ts";
 
@@ -1883,110 +1883,19 @@ export class CrewBroker {
 		});
 	}
 
-	/** WP-2/R2: terminal report of the parked `ask` tool — flips the task
-	 *  waiting→running and clears the park coordination state. Scoped to
-	 *  auth + state transition + ask.answered event ONLY (ADR item 6/8):
-	 *  answer DELIVERY is the mailbox respond path (step 6), not this
-	 *  method. A questionId mismatch (or a task that is not parked) is
-	 *  rejected WITHOUT clearing anything — fail-closed. */
+	/** WP-2/R2/R3: wait.resolve handler lives in ./protocol/wait-resolve.ts
+	 *  (moved out for the wc-gate M4 §5 — pure move, no behavior change). */
 	private async handleWaitResolve(conn: ServerConnection, id: string, params: unknown): Promise<void> {
-		if (!conn.runId || !conn.taskId) {
-			this.sendError(conn, id, "auth", "not authed");
-			return;
-		}
-		const authErr = waitAuthError(conn);
-		if (authErr) {
-			this.sendError(conn, id, authErr.code, authErr.message);
-			return;
-		}
-		const parsed = parseWaitResolveParams(params);
-		if (!parsed) {
-			this.sendError(conn, id, "bad-params", "wait.resolve: invalid params");
-			return;
-		}
-		// Server-side identity enforcement (same rule as wait.request).
-		if (parsed.to !== conn.taskId) {
-			this.sendError(conn, id, "forbidden", "wait.resolve: 'to' must match the authenticated task");
-			return;
-		}
-		const cwd = this.options.cwd;
-		if (!cwd) {
-			this.sendError(conn, id, "no-manifest", "broker has no cwd configured");
-			return;
-		}
-		let loaded: NonNullable<ReturnType<typeof loadRunManifestById>>;
-		try {
-			const l = loadRunManifestById(cwd, conn.runId);
-			if (!l) {
-				this.sendError(conn, id, "no-manifest", `run '${conn.runId}' not found`);
-				return;
-			}
-			loaded = l;
-		} catch (err) {
-			this.sendError(conn, id, "no-manifest", (err as Error).message);
-			return;
-		}
-		if (this.options.waitMethodsEnabled !== true) {
-			recordWaitPolicyRejection(loaded.manifest, conn.taskId, "wait.resolve");
-			this.sendError(
-				conn,
-				id,
-				"policy-disabled",
-				"wait.resolve is disabled: broker.waitMethodsEnabled=false (fail-closed; policy.action recorded in events.jsonl)",
-			);
-			return;
-		}
-		const runId = conn.runId;
-		const taskId = conn.taskId;
-		const outcome = withRunLockSync(loaded.manifest, () => {
-			const fresh = loadRunManifestById(loaded.manifest.cwd, runId);
-			if (!fresh) return { code: "no-manifest" as const, message: `run '${runId}' not found` };
-			const task = fresh.tasks.find((t) => t.id === taskId);
-			if (!task) return { code: "no-task" as const, message: `task '${taskId}' not found` };
-			if (task.status !== "waiting" || task.waiting?.questionId !== parsed.questionId) {
-				return {
-					code: "bad-params" as const,
-					message: `wait.resolve: no parked question '${parsed.questionId}' on task '${taskId}'`,
-				};
-			}
-			const updatedTasks = fresh.tasks.map((t) => (t.id === taskId ? { ...t, status: "running" as const, waiting: undefined } : t));
-			// waitState is a single run-level slot: clear it ONLY when it points
-			// at this exact question — never clobber another task's newer park.
-			const waitState = fresh.manifest.waitState;
-			const clearWaitState = waitState !== undefined && waitState.taskId === taskId && waitState.questionId === parsed.questionId;
-			const updatedManifest = {
-				...fresh.manifest,
-				...(clearWaitState ? { waitState: undefined } : {}),
-				updatedAt: new Date().toISOString(),
-			};
-			saveRunTasks(updatedManifest, updatedTasks);
-			saveRunManifest(updatedManifest);
-			return { code: "ok" as const, message: "" };
-		});
-		if (outcome.code !== "ok") {
-			this.sendError(conn, id, outcome.code, outcome.message);
-			return;
-		}
-		const eventsPath = loaded.manifest.eventsPath;
-		void appendEventAsync(eventsPath, {
-			type: "ask.answered",
-			runId,
-			taskId,
-			message: `Question ${parsed.questionId} answered; task resumed.`,
-			data: { questionId: parsed.questionId },
-		}).catch((err) =>
-			logInternalError("crew-broker.wait.ask-answered-event", err instanceof Error ? err : new Error(String(err)), `runId=${runId}`),
-		);
-		void appendEventAsync(eventsPath, {
-			type: "task.resumed",
-			runId,
-			taskId,
-			message: `Task resumed after ask answer (question ${parsed.questionId}).`,
-			data: { questionId: parsed.questionId },
-		}).catch((err) =>
-			logInternalError("crew-broker.wait.task-resumed-event", err instanceof Error ? err : new Error(String(err)), `runId=${runId}`),
+		await handleWaitResolve(
+			conn,
+			id,
+			params,
+			{
+				sendError: (c, i, code, msg) => this.sendError(c, i, code, msg),
+				sendResult: (c, i, r) => this.sendResult(c, i, r),
+			},
+			{ cwd: this.options.cwd, waitMethodsEnabled: this.options.waitMethodsEnabled },
 		);
-		this.sendResult(conn, id, { ok: true, taskId, questionId: parsed.questionId });
 	}
 }
 

package/src/runtime/broker/protocol/request-parsers.ts

@@ -172,6 +172,13 @@ export function parseWaitRequestParams(value: unknown): WaitRequestParams | unde
 export interface WaitResolveParams {
 	to: string;
 	questionId: string;
+	/** G5 (deep-review 2026-10-01): the parked worker's terminal outcome —
+	 *  "answered" = it PICKED UP the leader's mailbox response for this
+	 *  questionId (the only outcome that triggers the broker's
+	 *  task.respond_delivered ack event); "timed-out"/"aborted" resolve the
+	 *  park WITHOUT a delivery claim. Optional + fail-closed: legacy workers
+	 *  that omit it never claim a delivery (no event is emitted). */
+	outcome?: "answered" | "timed-out" | "aborted";
 }
 
 export function parseWaitResolveParams(value: unknown): WaitResolveParams | undefined {
@@ -179,5 +186,6 @@ export function parseWaitResolveParams(value: unknown): WaitResolveParams | unde
 	const v = value as Record<string, unknown>;
 	if (typeof v.to !== "string" || v.to.length === 0 || v.to.length > 256) return undefined;
 	if (typeof v.questionId !== "string" || v.questionId.length === 0 || v.questionId.length > 128) return undefined;
-	return { to: v.to, questionId: v.questionId };
+	if (v.outcome !== undefined && v.outcome !== "answered" && v.outcome !== "timed-out" && v.outcome !== "aborted") return undefined;
+	return { to: v.to, questionId: v.questionId, ...(v.outcome !== undefined ? { outcome: v.outcome } : {}) };
 }

package/src/runtime/broker/protocol/wait-resolve.ts

@@ -0,0 +1,168 @@
+/**
+ * wait-resolve.ts — WP-2/R2 `wait.resolve` broker handler.
+ *
+ * Moved from crew-broker.ts (wc-gate M4 §5, GH #61 release audit 2026-10-02)
+ * — pure move, no behavior change. Terminal report of the parked `ask` tool:
+ * flips the task waiting→running and clears the park coordination state.
+ * Scoped to auth + state transition + ask.answered/task.resumed events +
+ * the G5 respond_delivered ack ONLY (ADR item 6/8): answer DELIVERY is the
+ * mailbox respond path (step 6), not this handler. A questionId mismatch
+ * (or a task that is not parked) is rejected WITHOUT clearing anything —
+ * fail-closed.
+ *
+ * Top-level function so the class method is a 1-line delegation
+ * (same pattern as msg-inbox.ts).
+ */
+
+import { withRunLockSync } from "../../../state/coordination/locks.ts";
+import { appendEventAsync } from "../../../state/event-log/event-log.ts";
+import { loadRunManifestById, saveRunManifest, saveRunTasks } from "../../../state/stores/state-store.ts";
+import { logInternalError } from "../../../utils/internal-error.ts";
+import type { ServerConnection } from "./connection-state.ts";
+import { parseWaitResolveParams } from "./request-parsers.ts";
+import { recordWaitPolicyRejection } from "./wait-auth.ts";
+
+export interface WaitResolveHelpers {
+	sendError(conn: ServerConnection, id: string, code: string, message: string): void;
+	sendResult(conn: ServerConnection, id: string, result: unknown): void;
+}
+
+export interface WaitResolveOptions {
+	/** Broker cwd (run state root). Undefined → no-manifest error. */
+	cwd?: string;
+	/** Fail-closed gate: wait.* methods disabled unless explicitly true. */
+	waitMethodsEnabled?: boolean;
+}
+
+export async function handleWaitResolve(
+	conn: ServerConnection,
+	id: string,
+	params: unknown,
+	helpers: WaitResolveHelpers,
+	options: WaitResolveOptions,
+): Promise<void> {
+	if (!conn.runId || !conn.taskId) {
+		helpers.sendError(conn, id, "auth", "not authed");
+		return;
+	}
+	const parsed = parseWaitResolveParams(params);
+	if (!parsed) {
+		helpers.sendError(conn, id, "bad-params", "wait.resolve: invalid params");
+		return;
+	}
+	// Server-side identity enforcement (same rule as wait.request).
+	if (parsed.to !== conn.taskId) {
+		helpers.sendError(conn, id, "forbidden", "wait.resolve: 'to' must match the authenticated task");
+		return;
+	}
+	if (!options.cwd) {
+		helpers.sendError(conn, id, "no-manifest", "broker has no cwd configured");
+		return;
+	}
+	let loaded: NonNullable<ReturnType<typeof loadRunManifestById>>;
+	try {
+		const l = loadRunManifestById(options.cwd, conn.runId);
+		if (!l) {
+			helpers.sendError(conn, id, "no-manifest", `run '${conn.runId}' not found`);
+			return;
+		}
+		loaded = l;
+	} catch (err) {
+		helpers.sendError(conn, id, "no-manifest", (err as Error).message);
+		return;
+	}
+	if (options.waitMethodsEnabled !== true) {
+		recordWaitPolicyRejection(loaded.manifest, conn.taskId, "wait.resolve");
+		helpers.sendError(
+			conn,
+			id,
+			"policy-disabled",
+			"wait.resolve is disabled: broker.waitMethodsEnabled=false (fail-closed; policy.action recorded in events.jsonl)",
+		);
+		return;
+	}
+	const runId = conn.runId;
+	const taskId = conn.taskId;
+	const outcome = withRunLockSync(loaded.manifest, () => {
+		const fresh = loadRunManifestById(loaded.manifest.cwd, runId);
+		if (!fresh) return { code: "no-manifest" as const, message: `run '${runId}' not found` };
+		const task = fresh.tasks.find((t) => t.id === taskId);
+		if (!task) return { code: "no-task" as const, message: `task '${taskId}' not found` };
+		if (task.status !== "waiting" || task.waiting?.questionId !== parsed.questionId) {
+			return {
+				code: "bad-params" as const,
+				message: `wait.resolve: no parked question '${parsed.questionId}' on task '${taskId}'`,
+			};
+		}
+		const updatedTasks = fresh.tasks.map((t) => (t.id === taskId ? { ...t, status: "running" as const, waiting: undefined } : t));
+		// G5 (deep-review 2026-10-01): capture the liveness pid (heartbeat-first,
+		// checkpoint-fallback — the same source stale-reconciler uses) before
+		// the flip, so respond_delivered records the same worker-pid evidence
+		// its respond_missed twin does root-side.
+		const workerPid = task.heartbeat?.pid ?? task.checkpoint?.childPid;
+		// waitState is a single run-level slot: clear it ONLY when it points
+		// at this exact question — never clobber another task's newer park.
+		const waitState = fresh.manifest.waitState;
+		const clearWaitState = waitState !== undefined && waitState.taskId === taskId && waitState.questionId === parsed.questionId;
+		const updatedManifest = {
+			...fresh.manifest,
+			...(clearWaitState ? { waitState: undefined } : {}),
+			updatedAt: new Date().toISOString(),
+		};
+		saveRunTasks(updatedManifest, updatedTasks);
+		saveRunManifest(updatedManifest);
+		return { code: "ok" as const, message: "", workerPid };
+	});
+	if (outcome.code !== "ok") {
+		helpers.sendError(conn, id, outcome.code, outcome.message);
+		return;
+	}
+	const eventsPath = loaded.manifest.eventsPath;
+	void appendEventAsync(eventsPath, {
+		type: "ask.answered",
+		runId,
+		taskId,
+		message: `Question ${parsed.questionId} answered; task resumed.`,
+		data: { questionId: parsed.questionId },
+	}).catch((err) =>
+		logInternalError("crew-broker.wait.ask-answered-event", err instanceof Error ? err : new Error(String(err)), `runId=${runId}`),
+	);
+	void appendEventAsync(eventsPath, {
+		type: "task.resumed",
+		runId,
+		taskId,
+		message: `Task resumed after ask answer (question ${parsed.questionId}).`,
+		data: { questionId: parsed.questionId },
+	}).catch((err) =>
+		logInternalError("crew-broker.wait.task-resumed-event", err instanceof Error ? err : new Error(String(err)), `runId=${runId}`),
+	);
+	// G5 (deep-review 2026-10-01): respond-delivery ack. wait.resolve fires on
+	// EVERY terminal path (answered/timed-out/aborted) — only the worker-claimed
+	// outcome "answered" is a DELIVERY: the parked ask tool found the
+	// questionId-tagged mailbox response and is resolving the park WITH the
+	// answer in hand (its findAskResponse exact-equality match). A
+	// timed-out/aborted resolve — or a legacy worker that sends no outcome —
+	// never claims a delivery: fail-closed, no event. This ack is the leader's
+	// only confirmation that a mailbox respond reached a live worker instead
+	// of falling into the void; the root-side respond_missed twin covers the
+	// dead-worker branch at write time (extension/team-tool/respond.ts).
+	if (parsed.outcome === "answered") {
+		void appendEventAsync(eventsPath, {
+			type: "task.respond_delivered",
+			runId,
+			taskId,
+			message: `Leader respond delivered: worker acknowledged the mailbox response for question ${parsed.questionId}.`,
+			data: {
+				questionId: parsed.questionId,
+				...(outcome.workerPid !== undefined ? { workerPid: outcome.workerPid } : {}),
+			},
+		}).catch((err) =>
+			logInternalError(
+				"crew-broker.wait.respond-delivered-event",
+				err instanceof Error ? err : new Error(String(err)),
+				`runId=${runId}`,
+			),
+		);
+	}
+	helpers.sendResult(conn, id, { ok: true, taskId, questionId: parsed.questionId });
+}

package/src/runtime/child-pi/child-pi-spawn.ts

@@ -270,10 +270,17 @@ export function prepareSpawnContext(
 		agent: input.agent,
 		model: input.model,
 		sessionEnabled: true,
+		// W2 (P1-1): deterministic session identity so crash-path tail-recovery
+		// can find the worker's session JSONL (see session-recovery.ts). Falls
+		// back to child-pi.ts deriveSessionPaths when unset (idempotent both ways).
+		sessionId: input.sessionId,
+		sessionDir: input.sessionDir,
 		maxDepth: input.maxDepth,
 		skillPaths: input.skillPaths,
 		role: input.role,
 		thinkingOverride: input.thinkingOverride,
+		systemPromptAppend: input.systemPromptAppend,
+		hermeticWorkers: input.hermeticWorkers,
 		// ADR-5 §3: depthOverride is pre-encoded into depthEnv by runChildPi
 		// (parent's record depth as base-env PI_CREW_DEPTH); forward it so the
 		// child env gets parentDepth+1 = the true grandchild depth.
@@ -357,10 +364,11 @@ export function prepareSpawnContext(
 		// F4/S-1: the RAW (unredacted) snapshot must NEVER land in artifactsRoot —
 		// point it at a temp dir; the worker reads it then writeArtifact()
 		// (redact+atomic) is the ONLY writer into artifactsRoot.
-		// R3-1: built.tempDir is only created by buildPiWorkerArgs when the agent
-		// has a systemPrompt OR the task exceeds TASK_ARG_LIMIT — guard against
-		// undefined (resolveRealContainedPath(undefined) would TypeError and crash
-		// spawn). createSafeTempDir auto-tracks the dir for cleanupAllTrackedTempDirs.
+		// R3-1: since G3 (spill-always) buildPiWorkerArgs creates a tempDir for
+		// EVERY spawn (task.md) — the `??` guard stays as pure defense against
+		// future call shapes (resolveRealContainedPath(undefined) would
+		// TypeError and crash spawn). createSafeTempDir auto-tracks the dir for
+		// cleanupAllTrackedTempDirs.
 		const scratchTempDir = built.tempDir ?? createSafeTempDir(getPiTempBase(), "pi-crew-scratchpad-");
 		built.env.PI_CREW_SCRATCHPAD_SNAPSHOT = resolveRealContainedPath(scratchTempDir, `${input.agentId}.snapshot.json`);
 		// Phase 2 crash-resume (D1/D1b/D2): locate the latest snapshot artifact of a