pi-crew 0.11.6 → 0.11.7

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-crew",
-	"version": "0.11.6",
+	"version": "0.11.7",
 	"description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
 	"author": "baphuongna",
 	"license": "MIT",
@@ -8,7 +8,7 @@
 		"access": "public"
 	},
 	"engines": {
-		"node": ">=22.0.0"
+		"node": ">=22.19.0"
 	},
 	"repository": {
 		"type": "git",

package/src/config/config-validation.ts

@@ -77,6 +77,11 @@ const LIMIT_CEILINGS = {
 	// (10_000 turns), which capped the effective timeout at 10s and silently disabled
 	// any larger value (e.g. 300_000 = 5min) via parsePositiveInteger returning undefined.
 	runtimeTaskTimeoutMs: 24 * 60 * 60 * 1000,
+	// Handoff budget (est tokens, chars/4) for the dynamic.dependencyContext
+	// prompt layer. Above the ceiling the budget is treated as the OFF-switch
+	// (untrimmed render), mirroring the render-site semantics in
+	// task-output-context.ts.
+	runtimeHandoffBudgetTokens: 1_000_000,
 	nestingMaxSlots: 64,
 	nestingMaxDepth: 10,
 } as const;
@@ -325,6 +330,21 @@ function parseModelFallbackConfig(value: unknown): CrewRuntimeConfig["modelFallb
 	return Object.values(modelFallback).some((entry) => entry !== undefined) ? modelFallback : undefined;
 }
 
+/**
+ * Handoff budget for the dynamic.dependencyContext prompt layer (est tokens,
+ * chars/4). Deliberately NOT parsePositiveInteger: out-of-range values are
+ * dropped silently (undefined → render site falls back to default 1800)
+ * rather than rejecting the whole runtime block. The ≤0 / >1_000_000
+ * OFF-switch is expressible only via env PI_CREW_HANDOFF_BUDGET_TOKENS
+ * (env bypasses this parse and resolves first); the config schema documents
+ * 1..1_000_000 as the valid range.
+ */
+function parseHandoffBudgetTokens(value: unknown): number | undefined {
+	if (typeof value !== "number" || !Number.isInteger(value)) return undefined;
+	if (value < 1 || value > LIMIT_CEILINGS.runtimeHandoffBudgetTokens) return undefined;
+	return value;
+}
+
 function parseRuntimeConfig(value: unknown): CrewRuntimeConfig | undefined {
 	const obj = asRecord(value);
 	if (!obj) return { inheritContext: true } as CrewRuntimeConfig;
@@ -362,10 +382,18 @@ function parseRuntimeConfig(value: unknown): CrewRuntimeConfig | undefined {
 			return Object.values(parsed).some((v) => v !== undefined) ? parsed : undefined;
 		})(),
 		excludeContextBash: parseWithSchema(Type.Boolean(), obj.excludeContextBash),
+		handoffBudgetTokens: parseHandoffBudgetTokens(obj.handoffBudgetTokens),
 		agentExtensions: parseStringList(obj.agentExtensions),
 		isolationPolicy: parseIsolationPolicy(obj.isolationPolicy),
 		surface: parseSurfacePolicy(obj.surface),
 		modelFallback: parseModelFallbackConfig(obj.modelFallback),
+		// F19-1 discipline: every key declared in types.ts + schema MUST be
+		// emitted here or the config key is dead (runtime.sessionRecovery —
+		// W2/P1-1; runtime.workerTransport — W7/P2-3, experimental;
+		// runtime.hermeticWorkers — R3-19/D5 reversal, hermetic spawns).
+		sessionRecovery: parseWithSchema(Type.Boolean(), obj.sessionRecovery),
+		hermeticWorkers: parseWithSchema(Type.Boolean(), obj.hermeticWorkers),
+		workerTransport: parseWithSchema(Type.Union([Type.Literal("stdio"), Type.Literal("rpc")]), obj.workerTransport),
 	};
 	return Object.values(runtime).some((entry) => entry !== undefined) ? runtime : undefined;
 }

package/src/config/env-vars.ts

@@ -317,6 +317,11 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		name: "PI_CREW_DISABLE_RESULT_READ_CACHE",
 		doc: "'1' bypasses the per-run result-artifact read cache (R10-1 bypass control; task-output-context.ts createResultArtifactReadCache)",
 	},
+	PI_CREW_HANDOFF_BUDGET_TOKENS: {
+		name: "PI_CREW_HANDOFF_BUDGET_TOKENS",
+		parser: "int",
+		doc: "est-token (chars/4) budget for the dynamic.dependencyContext prompt layer; beats runtime.handoffBudgetTokens, default 1800; resolved ≤0 or >1_000_000 disables the trim (task-output-context.ts renderDependencyOutputContext)",
+	},
 	PI_CREW_MOCK_LIVE_SESSION: {
 		name: "PI_CREW_MOCK_LIVE_SESSION",
 		doc: "'success' mocks a successful live-session (live-session-runtime.ts:558, runtime-resolver.ts:38/116)",
@@ -440,6 +445,24 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		name: "PI_CREW_AGENT_EVENTS_PATH",
 		doc: "per-agent events log (<stateRoot>/agents/<taskId>/events.jsonl) written by the surface worker recorder (surface-worker.ts; derived by prepareSurfaceSpawn)",
 	},
+	PI_CREW_SESSION_RECOVERY: {
+		name: "PI_CREW_SESSION_RECOVERY",
+		parser: "boolean",
+		doc: "W2 session-file recovery override for killed workers (exitCode null / killed): '0' disables, '1' forces on — beats ChildPiRunInput.sessionRecovery / runtime.sessionRecovery; default ON (session-recovery.ts:resolveSessionRecoveryEnabled)",
+	},
+	PI_CREW_HERMETIC_WORKERS: {
+		name: "PI_CREW_HERMETIC_WORKERS",
+		parser: "boolean",
+		doc: "R3-19/D5 hermetic worker spawn override: '1' forces --no-extensions on worker argv, '0' restores the old ambient-stack parity (discovered/configured/built-in extensions load); beats BuildPiWorkerArgsInput.hermeticWorkers / runtime.hermeticWorkers; default ON (pi-args.ts:resolveHermeticWorkers). Explicit -e prompt-runtime + agent extensions + --skill flags are unaffected (cli.md:186-191)",
+	},
+	PI_CREW_WORKER_TRANSPORT: {
+		name: "PI_CREW_WORKER_TRANSPORT",
+		doc: "W7 EXPERIMENTAL worker transport gate: 'rpc' selects the prototype RPC frame-client (src/runtime/rpc/) — the run-worker seam currently returns a structured not-implemented result instead of spawning; anything else/unset → default stdio child-pi path (rpc-worker.ts resolveWorkerTransport)",
+	},
+	PI_CREW_RPC_DIALOG_ANSWER: {
+		name: "PI_CREW_RPC_DIALOG_ANSWER",
+		doc: "W7 EXPERIMENTAL dialog auto-answer policy for RPC-mode extension_ui_request dialogs (select/confirm/input/editor): 'cancel' (default) answers {cancelled:true} — universal safe answer; 'block' leaves the server promise pending (debug). Auto-confirm deliberately NOT implemented (security); invalid → 'cancel' (rpc-worker.ts resolveDialogAnswerPolicy)",
+	},
 	PI_CREW_AUTO_EXIT: {
 		name: "PI_CREW_AUTO_EXIT",
 		doc: "'1' → the worker shuts its session down after the final settled turn — spec §5.2 D7 (written by prepareSurfaceSpawn, read by surface-worker.ts)",

package/src/config/types.ts

@@ -65,6 +65,30 @@ export interface CrewRuntimeConfig {
 	 */
 	taskTimeoutMs?: number;
 	inheritContext?: boolean;
+	/**
+	 * W2 (session-file recovery): when a worker dies without a final assistant
+	 * event (exitCode null / killed), tail-replay its session JSONL (written by
+	 * the worker under `<artifactsRoot>/sessions/<taskId>/`) and attach the last
+	 * COMPLETE assistant record to the task result (`recoveredFromSession`).
+	 * Default: enabled. The env var PI_CREW_SESSION_RECOVERY overrides this
+	 * flag in either direction (see session-recovery.ts:resolveSessionRecoveryEnabled).
+	 * Manifest polling is NOT replaced — this only augments the settle-time result.
+	 */
+	sessionRecovery?: boolean;
+	/**
+	 * R3-19/D5 reversal (2026-10-04): hermetic worker spawns — pass
+	 * `--no-extensions` on worker argv. Explicit `-e prompt-runtime` and agent
+	 * `extensions:` still load (cli.md:186-187: "Disables discovered, configured,
+	 * and built-in extensions. Explicit -e paths still load"), and `--skill`
+	 * flags are independent — what gets cut is the ~1.37s/spawn ambient package
+	 * stack (pi-crew host ext + configured packages; probe C §R3b.6: 431ms vs
+	 * 1806ms to first stdout record) plus the ambient tool surface (team/
+	 * crew_agent/Agent host tools + 8 direct-exposure MCP tools).
+	 * Default: true. Env PI_CREW_HERMETIC_WORKERS overrides in either
+	 * direction (pi-args.ts resolveHermeticWorkers). Surface TUI spawns strip
+	 * the flag — panes keep the full interactive session.
+	 */
+	hermeticWorkers?: boolean;
 	promptMode?: "replace" | "append";
 	groupJoin?: "off" | "group" | "smart";
 	groupJoinAckTimeoutMs?: number;
@@ -85,6 +109,29 @@ export interface CrewRuntimeConfig {
 	};
 	/** Mark certain bash commands as excludeFromContext to reduce context tokens. Default: false */
 	excludeContextBash?: boolean;
+	/**
+	 * Est-token budget for the dynamic.dependencyContext prompt layer
+	 * (handoff budget). When the rendered dependency output exceeds this many
+	 * estimated tokens (chars/4 — the same heuristic the prompt breakdown
+	 * uses), dependencies are trimmed IN DECLARATION ORDER: earlier deps keep
+	 * their full output, later ones are downgraded to taskId/role/status + a
+	 * ≤240-char summary head + an artifact pointer
+	 * (`artifacts/<runId>/results/<taskId>.txt`) the worker can `read` back.
+	 * Long sharedRead bodies are dropped the same way. Valid range 1..1_000_000;
+	 * a RESOLVED value ≤0 or >1_000_000 disables the trim entirely
+	 * (off-switch). Env override PI_CREW_HANDOFF_BUDGET_TOKENS beats this
+	 * config. Default: 1800.
+	 */
+	handoffBudgetTokens?: number;
+	/**
+	 * W7 (P2-3) EXPERIMENTAL: transport used to spawn child-pi workers.
+	 * "stdio" (default) — the production print-mode path, unchanged.
+	 * "rpc" — prototype RPC frame-client (src/runtime/rpc/); the run-worker
+	 * seam currently returns a structured not-implemented result instead of
+	 * spawning. Live gate: env PI_CREW_WORKER_TRANSPORT (config→seam plumbing
+	 * is the integration-phase follow-up).
+	 */
+	workerTransport?: "stdio" | "rpc";
 	/**
 	 * Mux-surface policy (mux-surface spec v0.7 §8.1): WHERE worker processes
 	 * live — a pane in tmux/herdr or headless child processes. Surface only

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";
@@ -653,10 +654,11 @@ async function resolvePark(
 }
 
 /** 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",
@@ -1030,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/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.

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

@@ -27,6 +27,16 @@ import { ChildPiLineObserver } from "./child-pi-streams.ts";
 // Phase 2.3: the six timer constructs moved to child-pi-timers.ts (pure motion).
 import { createChildPiTimers } from "./child-pi-timers.ts";
 import { runMockChildPi } from "./mock-fixtures.ts";
+// W2 (session-file recovery): deterministic worker session flags + crash-path
+// tail-replay of the session JSONL (see session-recovery.ts header).
+import {
+	appendWorkerSessionArgs,
+	deriveSessionPaths,
+	recoverLastAssistantFromSession,
+	resolveSessionRecoveryEnabled,
+	type SessionRecoveryInfo,
+	shouldAttemptSessionRecovery,
+} from "./session-recovery.ts";
 
 // ── Re-exports from child-pi-kill.ts (H-7 decomposition step 2) ──
 // killProcessTree is internal (not previously exported) — keep that invariant.
@@ -185,8 +195,18 @@ export interface ChildPiRunInput {
 	inheritContext?: boolean;
 	/** Pass to pi to mark certain commands as context-excluded. Default: false */
 	excludeContextBash?: boolean;
-	/** pi session ID for session naming (aligns with pi-crew run ID) */
+	/** pi session ID for session naming (aligns with pi-crew run ID). W2: now
+	 *  WIRED — flows to `--session-id` (deterministic worker session files for
+	 *  crash-path tail-recovery; see session-recovery.ts). */
 	sessionId?: string;
+	/** W2 (session-file recovery): explicit session directory override. When
+	 *  absent, derived per-worker as `<artifactsRoot>/sessions/<taskId>/` so
+	 *  session JSONL is cleaned up together with run artifacts. */
+	sessionDir?: string;
+	/** W2 (session-file recovery): explicit on/off (runtime.sessionRecovery
+	 *  config). Env PI_CREW_SESSION_RECOVERY overrides in either direction;
+	 * default ON. Only consulted on crash-ish settles (exitCode null / killed). */
+	sessionRecovery?: boolean;
 	/** Path to steering JSONL file for real-time steer injection. */
 	steeringFile?: string;
 	/** Run ID for cleanup tracking */
@@ -197,6 +217,15 @@ export interface ChildPiRunInput {
 	role?: string;
 	/** Team-role thinking override (takes precedence over agent.thinking). */
 	thinkingOverride?: string;
+	/** R3-1: run-static worker header for the --append-system-prompt channel
+	 *  (renderTaskPrompt().stablePrefix). Threaded by child-executor so the
+	 *  Protocol/mailbox/workspace/runtime-context block survives compaction
+	 *  instead of living in the summarizable user-message span. */
+	systemPromptAppend?: string;
+	/** R3-19/D5 (hermetic worker spawns): thread runtime.hermeticWorkers to
+	 *  buildPiWorkerArgs (--no-extensions). Env PI_CREW_HERMETIC_WORKERS
+	 *  overrides either way; default TRUE. */
+	hermeticWorkers?: boolean;
 	/** Root directory for artifacts (used to validate transcriptPath). */
 	artifactsRoot?: string;
 	/** I5: run events JSONL path — threaded to the worker so its scratchpad
@@ -291,6 +320,13 @@ export interface ChildPiRunResult {
 	 *  text) still produce a non-empty result. Consumers should prefer rawFinalText
 	 *  first — this is a last-resort fallback. */
 	intermediateFindings?: string;
+	/** W2 (session-file recovery): present when the worker died WITHOUT a
+	 *  final assistant event (exitCode null / killed) and a COMPLETE assistant
+	 *  record was tail-recovered from the worker's session JSONL (deterministic
+	 *  `--session-id`/`--session-dir` under the run artifacts root). Consumers
+	 *  treat it as a crash-path supplement to rawFinalText — never a replacement
+	 *  for clean-path output, and manifest polling is untouched. */
+	recoveredFromSession?: SessionRecoveryInfo;
 	/**
 	 * MuxSurface A1: present ONLY when the worker booted inside a multiplexer
 	 * pane instead of a stdio pipe (spec §13.1). Downstream (T9 EventLogTailSource,
@@ -371,6 +407,17 @@ function safeLoadSurfaceConfig(cwd: string): PiTeamsConfig {
 	}
 }
 
+/**
+ * D1/D5: flags that apply to HEADLESS worker spawns only. The surface TUI
+ * branch strips them before booting a pane — a pane hosts a full interactive
+ * pi session where the interactive trust prompt must stay available and the
+ * ambient extension stack is part of the human-visible session (task mandate:
+ * worker spawn CHỈ, KHÔNG đụng surface TUI spawn).
+ */
+function stripHeadlessOnlyFlags(args: string[]): string[] {
+	return args.filter((arg) => arg !== "--no-approve" && arg !== "--no-extensions");
+}
+
 /**
  * MuxSurface A1 spawn branch (spec §13.1). Returns a ChildPiRunResult when the
  * worker was booted INSIDE a multiplexer pane (no stdio process is spawned and
@@ -413,7 +460,7 @@ async function trySurfaceBranch(
 			livePaneCount: degradeController ? degradeController.livePaneCount() : (surfaceOpts?.livePaneCount ?? 0),
 			taskId,
 			cwd: input.cwd,
-			piArgs: builtArgs,
+			piArgs: stripHeadlessOnlyFlags(builtArgs),
 			stateRoot: input.eventsPath ? path.dirname(input.eventsPath) : "",
 			baseDir: surfaceOpts?.baseDir,
 			deps: preResolved ? { provider: preResolved } : {},
@@ -684,6 +731,24 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 	const spawnPrep = prepareSpawnContext(brokerSpawn ? { ...input, brokerSpawn } : input, effectiveTask, depthEnv);
 	if (spawnPrep.kind === "aborted") return spawnPrep.result;
 	const { spawnSpec, mergedEnv, tempDir, builtEnv, builtArgs } = spawnPrep.ctx;
+	// W2 (session-file recovery): resolve the worker's deterministic session
+	// identity (per-worker dir under the run artifacts root) and arm it on BOTH
+	// argv views — the headless spawnSpec.args ([script, ...builtArgs]) and the
+	// raw builtArgs (also consumed by the surface branch). prepareSpawnContext
+	// does not forward session identity to the arg builder (ownership boundary
+	// with child-pi-spawn.ts — see the lane report), so this is the in-zone
+	// activation point; appendWorkerSessionArgs is idempotent, making the move
+	// to builder-side forwarding later a zero-diff no-op.
+	const workerSession = deriveSessionPaths(input);
+	const sessionRecoveryEnabled = resolveSessionRecoveryEnabled(input.sessionRecovery);
+	if (workerSession) {
+		try {
+			fs.mkdirSync(workerSession.sessionDir, { recursive: true });
+		} catch {
+			// Unwritable target → spawn proceeds; recovery simply finds no files.
+		}
+		appendWorkerSessionArgs(spawnSpec.args, builtArgs, workerSession);
+	}
 	// MuxSurface A1 (spec §13.1): attempt booting the worker in a mux pane BEFORE
 	// spawning a stdio pipe. Returns a finished result in surface mode (pane exit
 	// awaited) or null → fall through to the classic headless spawn below.
@@ -869,6 +934,22 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				clearPostExitGuard();
 			};
 
+			// W2 (session-file recovery): crash-path augment — when the worker died
+			// WITHOUT a final assistant event (exitCode null / killed), tail-replay
+			// its session JSONL and surface the last COMPLETE assistant record on the
+			// resolved result. Best-effort and deadline-bounded (session-recovery.ts)
+			// so settle can never hang on pathological IO. This AUGMENTS the result —
+			// manifest polling (heartbeat-watcher / detached-run-results) is untouched.
+			const recoverForSettle = async (settleResult: ChildPiRunResult): Promise<SessionRecoveryInfo | undefined> => {
+				if (!workerSession || !sessionRecoveryEnabled) return undefined;
+				if (!shouldAttemptSessionRecovery(settleResult, hardKilled)) return undefined;
+				try {
+					return (await recoverLastAssistantFromSession(workerSession.sessionDir, workerSession.sessionId)) ?? undefined;
+				} catch {
+					return undefined;
+				}
+			};
+
 			const settle = (result: ChildPiRunResult): Promise<void> => {
 				if (settled) return Promise.resolve();
 				settled = true;
@@ -885,7 +966,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				// durable transcript on disk.
 				return lineObserver
 					.flush()
-					.then(() => {
+					.then(async () => {
 						input.signal?.removeEventListener("abort", abort);
 						input.signal?.removeEventListener("abort", onParentAbort);
 						try {
@@ -893,12 +974,16 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 						} catch (error) {
 							cleanupErrors.push(error instanceof Error ? error.message : String(error));
 						}
+						// W2: crash-path session tail-recovery (await BEFORE resolve so the
+						// recovered record rides the same settled result object).
+						const recoveredFromSession = await recoverForSettle(result);
 						// Catch all errors from settle to prevent unhandled rejection from propagating
 						try {
 							resolve({
 								...result,
 								rawFinalText: lineObserver.getRawFinalText(),
 								intermediateFindings: lineObserver.getIntermediateFindings(),
+								...(recoveredFromSession ? { recoveredFromSession } : {}),
 								exitStatus: result.exitStatus ?? {
 									exitCode: result.exitCode,
 									cancelled: abortRequested,
@@ -926,7 +1011,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 							);
 						}
 					})
-					.catch((flushError) => {
+					.catch(async (flushError) => {
 						// Drain failed — log and still resolve so runChildPi doesn't hang.
 						logInternalError(
 							"child-pi.settle-flush-failed",
@@ -940,11 +1025,15 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 						} catch (error) {
 							cleanupErrors.push(error instanceof Error ? error.message : String(error));
 						}
+						// W2: crash-path session tail-recovery — same augment on the
+						// drain-failed path (a torn flush is itself crash-adjacent).
+						const recoveredFromSession = await recoverForSettle(result);
 						try {
 							resolve({
 								...result,
 								rawFinalText: lineObserver.getRawFinalText(),
 								intermediateFindings: lineObserver.getIntermediateFindings(),
+								...(recoveredFromSession ? { recoveredFromSession } : {}),
 								exitStatus: result.exitStatus ?? {
 									exitCode: result.exitCode,
 									cancelled: abortRequested,