pi-crew 0.9.8 → 0.9.9

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [v0.9.9] — gajae-code distillation (4 P0) + notification race fix (2026-06-25)
+
+Six changes: four high-impact/low-effort features distilled from researching [Yeachan-Heo/gajae-code](https://github.com/Yeachan-Heo/gajae-code) (full report: `research-findings/gajae-code-distill.md`), plus a fix for a redundant-notification bug the leader directly hit while running that research. Each was calibrated against real pi-crew code — two reported "gaps" turned out to be patterns pi-crew already implements (prompt-level stablePrefix, detached spawning), and four areas where pi-crew is already superior were deliberately left untouched (crash-recovery byte-offset cursor, declarative workflow + semaphores, run-snapshot-cache, event sourcing).
+
+### P0 #1 — Crash classification taxonomy (commit fb8c4a8)
+
+`child-pi.ts` captured stderr/exit codes but never bucketed failure modes. New pure `classifyProcessCrash()` (port of gajae-code's `crash-diagnostics.ts`) maps exits to 9 semantic classes (`clean_exit | non_zero_exit | signal_exit | timeout | cancelled | spawn_error | protocol_exit | native_panic | unknown`) with precedence timeout > cancelled > spawn_error > native_panic > signal. Attached to `WorkerExitStatus` at both settle paths; kill/drain/timeout logic untouched. 30 unit tests.
+
+### P0 #2 — Staleness-aware tool output pruning (commit 13acf37)
+
+The L4 size-based compaction retained every copy of a re-read file until a size threshold tripped. New `tool-output-pruner.ts` (port of gajae-code's `pruning.ts`) drops superseded tool results — same-file re-reads and read-then-edit — **before** they are injected into a downstream worker's prompt via `task-output-context.ts`. Replaces stale content with a digest notice (first/last lines + count for bash/grep/search). OPT-IN via `DEFAULT_PRUNE_CONFIG`; does NOT regress the L4 head+tail(75/25) behavior. 25 unit tests.
+
+### P0 #3 — OwnedProcess abstraction (commit fe3bdde)
+
+Background spawns used `detached:true` but had no unified ownership primitive for guaranteed teardown. New `process-lifecycle.ts` adds `OwnedProcess` (escalating SIGTERM → grace → SIGKILL; Windows `taskkill /F /T /PID` fallback; idempotent `dispose()`; bounded `awaitExit()`; `onExit`) plus `registerResourceOwner()`/`disposeAllOwners()` for non-process resources (timers, sockets, Workers) and root-exit drain reconciliation. **Incremental adoption** — deliberately NOT migrating `child-pi.ts`'s battle-tested `killProcessTree`/post-exit-stdio-guard/hard-kill-timer or `async-runner.ts`'s intentionally-detached background spawns; the primitive is available for future ownership-scoped spawns (MCP/LSP/DAP servers, eval workers). 22 unit tests.
+
+### P0 #4 — IRC reply support, side-channel Q&A (commit 43bcd65)
+
+The `irc-tool` was fire-and-forget despite an `awaitReply` param marked "Not yet supported". New `respondAsBackground()` on `live-agent-manager.ts` delivers a DM to a recipient's session **without blocking its main loop** (`sendCustomMessage({triggerTurn:false})`) and awaits an event-driven, timeout-bounded reply via an in-memory pending-reply registry keyed by correlation id. `awaitReply:true` DMs now route through this side-channel and return reply content; broadcast stays fire-and-forget. Coexists with mailbox.ts's existing file-based reply fields (cross-process). 10 unit tests.
+
+### Notification race fix — Rule 2 + Rule 1 (commits 592d9ea, c22cbb9)
+
+While running the gajae-code research, the leader observed redundant "background subagent changed state" notifications arriving a turn late, after results were already read. Root cause: the completion callback (`SubagentManager.onComplete`) fires from inside the `record.promise` IIFE `finally` block — **before the promise resolves** — so a leader calling `get_subagent_result(wait:true)` sets `resultConsumed=true` only afterward, and the synchronous `if (record.resultConsumed) return` guard always saw `false`. A latent test bug (`assert sentMessages.length === 0` on an array that was unconditionally empty because `sendAgentWakeUp` prefers `sendUserMessage`) masked it.
+
+- **Rule 2** (592d9ea): defer notification emission to a `setTimeout(0)` **macrotask** (not `queueMicrotask` — microtasks queued in the finally run before the promise-resolution microtask), then recheck `resultConsumed` (in-memory `getRecord` + persisted `readPersistedSubagentRecord`) before emitting; suppress if already consumed. Covers all three `onComplete` call sites via the single emit point. Fixed the test assertion to `sentUserMessages` and added two explicit regression tests (notify still fires when leader does NOT pre-consume; notify suppressed when leader pre-consumes via `wait:true`).
+- **Rule 1** (c22cbb9): new `BatchBarrier` registry + optional `batch_id` param on the Agent tool. Background agents sharing a `batch_id` never emit individual notifications; instead each completion is recorded in the barrier and **one consolidated** "All N background subagents in batch \"X\" have finished" notification fires exactly once when every member reaches a terminal state (`blocked` is NOT terminal — a blocked agent resumes later). Verified end-to-end with 1/2/5-agent batches (one with a queued member and staggered 10–25s sleeps): exactly 1 consolidated notification, 0 individual leaks. Composes with Rule 2 (a batched agent whose result was already consumed is still suppressed via the `resultConsumed` recheck). 10 unit tests + 2 integration tests.
+
+Design doc: `research-findings/subagent-notification-race-fix.md`.
+
+### What was NOT adopted (pi-crew already superior)
+
+Crash recovery (`crash-recovery.ts`, 421 lines, byte-offset event-log cursor), declarative workflow + semaphores, `run-snapshot-cache` (disk rebuild, TTL 1500ms), and event sourcing (`readEventsCursor`) are all more sophisticated than gajae-code's equivalents and were left intact.
+
 ## [v0.9.8] — deer-flow learning integration: L1/L2/L3/L4 (2026-06-24)
 
 Four improvements distilled from researching [bytedance/deer-flow](https://github.com/bytedance/deer-flow) and the wider Pi-ecosystem (pi-boomerang, pi-subagents, pi-dynamic-workflows). Each was calibrated against real pi-crew code (the research over-reported gaps — several patterns pi-crew already does *better* than deer-flow) and sized from measured data, not guesses.

package/README.md

@@ -39,9 +39,9 @@ npm: pi-crew
 repo: https://github.com/baphuongna/pi-crew
 ```
 
-**v0.9.4 / v0.9.5 / v0.9.8**: See [CHANGELOG.md](CHANGELOG.md).
+**v0.9.4 / v0.9.5 / v0.9.8 / v0.9.9**: See [CHANGELOG.md](CHANGELOG.md).
 
-### Highlights (v0.6.4 → v0.9.8)
+### Highlights (v0.6.4 → v0.9.9)
 
 A long arc of **trust, cliff-resilience, and robustness** work. Principle: *build
 trust and cliff-resilience, stay lean, delete before adding.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/extension/register.ts

@@ -56,7 +56,11 @@ import { createManifestCache } from "../runtime/manifest-cache.ts";
 import { CrewScheduler } from "../runtime/scheduler.ts";
 import { loadRunManifestById, updateRunStatus } from "../state/state-store.ts";
 import type { TeamRunManifest } from "../state/types.ts";
-import { SubagentManager } from "../subagents/manager.ts";
+import {
+	SubagentManager,
+	readPersistedSubagentRecord,
+} from "../subagents/manager.ts";
+import { BatchBarrier, type BatchMember } from "../runtime/batch-barrier.ts";
 import { terminateActiveChildPiProcesses } from "../subagents/spawn.ts";
 import {
 	type CrewWidgetState,
@@ -635,6 +639,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		!cleanedUp &&
 		currentCtx === ctx &&
 		sessionGeneration === ownerGeneration;
+	const batchBarrier = new BatchBarrier();
 	const subagentManager = new SubagentManager(
 		4,
 		(record) => {
@@ -651,22 +656,90 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 					durationMs: record.durationMs,
 				});
 			}
-			if (!record.background || record.resultConsumed) return;
+			if (!record.background) return;
 			if (!isOwnerSessionCurrent(record.ownerSessionGeneration)) return;
 			if (
-				record.status === "completed" ||
-				record.status === "failed" ||
-				record.status === "cancelled" ||
-				record.status === "blocked" ||
-				record.status === "error"
-			) {
+				record.status !== "completed" &&
+				record.status !== "failed" &&
+				record.status !== "cancelled" &&
+				record.status !== "blocked" &&
+				record.status !== "error"
+			)
+				return;
+			// Rule 2 (consume-race fix): this callback fires from inside the
+			// record.promise IIFE `finally` block — BEFORE the promise resolves,
+			// i.e. before a leader calling `get_subagent_result(wait:true)` can
+			// set resultConsumed=true. The old synchronous guard always saw
+			// resultConsumed=false here. Defer emission to a MACROTASK
+			// (setTimeout, NOT queueMicrotask): macrotasks run only after the
+			// microtask queue drains — which includes the leader's
+			// `await record.promise` continuation that marks resultConsumed=true.
+			// Then recheck in-memory + persisted before emitting.
+			const agentId = record.id;
+			const ownerGen = record.ownerSessionGeneration;
+			const agentStatus = record.status;
+			const agentType = record.type;
+			const agentDescription = record.description;
+			const agentRunId = record.runId;
+			const agentBatchId = record.batchId;
+			setTimeout(() => {
+				if (cleanedUp) return;
+				const fresh = subagentManager.getRecord(agentId);
+				const persisted = currentCtx
+					? readPersistedSubagentRecord(currentCtx.cwd, agentId)
+					: undefined;
+				// Leader already joined the result -> suppress redundant notify.
+				if (fresh?.resultConsumed || persisted?.resultConsumed) return;
+				if (!isOwnerSessionCurrent(fresh?.ownerSessionGeneration ?? ownerGen))
+					return;
+				// Rule 1 (batch coalescing): if this agent belongs to a batch, never
+				// emit an individual notification. Instead record its terminal state
+				// in the barrier; emit ONE consolidated notification only when ALL
+				// members are terminal. Suppressed members wait silently.
+				if (agentBatchId) {
+					const member: BatchMember = {
+						id: agentId,
+						description: agentDescription,
+						type: agentType,
+						status: agentStatus,
+					};
+					const snap = batchBarrier.markTerminal(agentBatchId, member);
+					if (snap.allDone && !snap.notified) {
+						batchBarrier.markNotified(agentBatchId);
+						const roster = snap.terminal
+							.map(
+								(m) =>
+									`- ${m.id} [${m.status}] (${m.type ?? "agent"}): ${m.description ?? ""}`,
+							)
+							.join("\n");
+						const joinInstruction = [
+							`All ${snap.terminal.length} background subagents in batch "${agentBatchId}" have finished.`,
+							"Members:",
+							roster,
+							"",
+							`Call get_subagent_result for each agent_id above, read the outputs, then continue the user's original task.`,
+						].join("\n");
+						sendAgentWakeUp(pi, joinInstruction);
+						notifyOperator({
+							id: `subagent-batch:${agentBatchId}:completed`,
+							severity: "info",
+							source: "subagent-completed",
+							runId: agentRunId,
+							title: `pi-crew batch "${agentBatchId}" complete (${snap.terminal.length} agents).`,
+							body: `Members: ${snap.terminal.map((m) => m.id).join(", ")}`,
+						});
+					}
+					// Either we just emitted the consolidated notify, or we are still
+					// waiting for other members — in both cases do NOT emit individual.
+					return;
+				}
 				const metadata = JSON.stringify(
 					{
-						id: record.id,
-						status: record.status,
-						type: record.type,
-						runId: record.runId,
-						description: record.description,
+						id: agentId,
+						status: agentStatus,
+						type: agentType,
+						runId: agentRunId,
+						description: agentDescription,
 					},
 					null,
 					2,
@@ -677,19 +750,18 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 					"```json",
 					metadata,
 					"```",
-					`Call get_subagent_result with agent_id="${record.id}" now, read the output, then continue the user's original task without waiting for another user prompt.`,
+					`Call get_subagent_result with agent_id="${agentId}" now, read the output, then continue the user's original task without waiting for another user prompt.`,
 				].join("\n");
 				sendAgentWakeUp(pi, joinInstruction);
 				notifyOperator({
-					id: `subagent:${record.id}:${record.status}`,
-					severity:
-						record.status === "completed" ? "info" : "warning",
+					id: `subagent:${agentId}:${agentStatus}`,
+					severity: agentStatus === "completed" ? "info" : "warning",
 					source: "subagent-completed",
-					runId: record.runId,
-					title: `pi-crew subagent ${record.id} ${record.status}.`,
-					body: `Use get_subagent_result with agent_id=${record.id} for output.`,
+					runId: agentRunId,
+					title: `pi-crew subagent ${agentId} ${agentStatus}.`,
+					body: `Use get_subagent_result with agent_id=${agentId} for output.`,
 				});
-			}
+			}, 0);
 		},
 		1000,
 		(event, payload) => {
@@ -2044,6 +2116,7 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		ownerSessionGeneration: captureSessionGeneration,
 		startForegroundRun: (ctx, runner, runId) =>
 			startForegroundRun(ctx as ExtensionContext, runner, runId),
+		batchBarrier,
 	});
 	time("register.tools");
 

package/src/extension/registration/subagent-helpers.ts

@@ -98,5 +98,6 @@ export function __test__subagentSpawnParams(params: Record<string, unknown>, ctx
 		model: typeof params.model === "string" && params.model.trim() ? params.model.trim() : undefined,
 		skill: parseSkillParam(params.skill),
 		maxTurns: typeof params.max_turns === "number" && Number.isFinite(params.max_turns) ? params.max_turns : undefined,
+		batchId: typeof params.batch_id === "string" && params.batch_id.trim() ? params.batch_id.trim() : undefined,
 	};
 }

package/src/extension/registration/subagent-tools.ts

@@ -15,6 +15,7 @@ async function handleTeamTool(params: Parameters<typeof HandleTeamToolFn>[0], ct
 }
 import { checkSubagentSpawnPermission, currentCrewRole } from "../../runtime/role-permission.ts";
 import { readPersistedSubagentRecord, savePersistedSubagentRecord, type SubagentManager, type SubagentSpawnOptions } from "../../subagents/manager.ts";
+import type { BatchBarrier } from "../../runtime/batch-barrier.ts";
 import { loadConfig } from "../../config/config.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { __test__subagentSpawnParams, formatSubagentRecord, readSubagentRunResult, refreshPersistedSubagentRecord, subagentToolResult } from "./subagent-helpers.ts";
@@ -32,6 +33,9 @@ type OnUpdate = (chunk: { content: { type: "text"; text: string }[] }) => void;
 export interface SubagentToolRegistrationOptions {
 	ownerSessionGeneration?: () => number;
 	startForegroundRun?: (ctx: unknown, runner: (signal?: AbortSignal) => Promise<void>, runId?: string) => void;
+	/** Rule 1 batch barrier. When present, agents spawned with a batchId are
+	 * registered here so their completion notifications are coalesced. */
+	batchBarrier?: BatchBarrier;
 }
 
 export function registerSubagentTools(pi: ExtensionAPI, subagentManager: SubagentManager, options: SubagentToolRegistrationOptions = {}): void {
@@ -53,6 +57,7 @@ export function registerSubagentTools(pi: ExtensionAPI, subagentManager: Subagen
 			skill: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String()), Type.Boolean()], { description: "Skill name(s) to inject for this subagent, or false to disable selected/default skills." })),
 			max_turns: Type.Optional(Type.Number({ description: "Reserved for live-session subagents; child-process runtime may ignore this." })),
 			run_in_background: Type.Optional(Type.Boolean({ description: "Run in background and return an agent ID immediately." })),
+			batch_id: Type.Optional(Type.String({ description: "Optional batch grouping id. Background agents sharing the same batch_id receive ONE consolidated completion notification when ALL members finish (instead of N individual notifications). Use this when launching several background agents in one turn and you do not join them immediately. Omit for the default individual-notification behavior." })),
 		}) as never,
 		async execute(_id, params, signal, onUpdate, ctx) {
 			// Diagnostic: detect pre-aborted signal before spawn
@@ -71,6 +76,10 @@ export function registerSubagentTools(pi: ExtensionAPI, subagentManager: Subagen
 			const ctxWithSession = withSessionId(ctx);
 			const runner = async (currentOptions: SubagentSpawnOptions, childSignal?: AbortSignal) => handleTeamTool({ action: "run", agent: currentOptions.type, goal: currentOptions.prompt, model: currentOptions.model, skill: currentOptions.skill, async: currentOptions.background, config: currentOptions.maxTurns ? { runtime: { maxTurns: currentOptions.maxTurns } } : undefined } as TeamToolParamsValue, { ...ctxWithSession, signal: childSignal, ...(options.startForegroundRun ? { startForegroundRun: (runRunner: (sig?: AbortSignal) => Promise<void>, runId?: string) => options.startForegroundRun!(ctxWithSession, runRunner, runId) } : {}) });
 			const record = subagentManager.spawn(spawnOptions, runner, spawnOptions.background ? undefined : signal);
+			// Rule 1: register batch membership so completions can be coalesced.
+			if (spawnOptions.batchId && spawnOptions.background) {
+				options.batchBarrier?.register(spawnOptions.batchId, record.id, { description: record.description, type: record.type });
+			}
 			if (spawnOptions.background || record.status === "queued") {
 				// Phase 1.1a: Terminate turn for background queued — no LLM follow-up needed.
 				// Phase 1.6: Record was terminated for telemetry.

package/src/runtime/batch-barrier.ts

@@ -0,0 +1,145 @@
+/**
+ * BatchBarrier — Rule 1 (no-wait batch grouping).
+ *
+ * When a leader launches several background subagents with the SAME `batchId`
+ * and does NOT join them immediately (`get_subagent_result(wait:true)`), the
+ * completion notifications are coalesced: instead of N individual
+ * "changed state" wake-ups, the leader receives ONE consolidated notification
+ * once ALL members of the batch have reached a terminal state.
+ *
+ * Semantics:
+ * - `register(batchId, agentId)` is called at spawn time (synchronous within a
+ *   leader turn). All members of a batch are therefore known by the time the
+ *   first completion fires (completion is observed via the 1000ms poll loop).
+ * - `markTerminal(batchId, agentId)` returns whether THIS completion made every
+ *   registered member terminal ("allDone"). When allDone, the caller emits a
+ *   single consolidated notification and calls `markNotified`.
+ * - If a member reaches terminal after the batch already notified (late spawn
+ *   edge case), `markTerminal` returns allDone=false for the straggler path is
+ *   NOT covered — but `alreadyNotified` lets the caller suppress stray
+ *   individual notifications once the consolidated one fired.
+ *
+ * Thread-safety: single-threaded JS event loop. No locks needed.
+ */
+
+export interface BatchMember {
+	id: string;
+	description?: string;
+	type?: string;
+	status: string;
+}
+
+export interface BatchSnapshot {
+	batchId: string;
+	members: BatchMember[];
+	terminal: BatchMember[];
+	/** true when every registered member has reached a terminal state. */
+	allDone: boolean;
+	/** true once the consolidated notification has been emitted. */
+	notified: boolean;
+}
+
+const TERMINAL_STATUSES = new Set([
+	"completed",
+	"failed",
+	"cancelled",
+	"error",
+	"stopped",
+]);
+
+export function isTerminalStatus(status: string): boolean {
+	return TERMINAL_STATUSES.has(status);
+}
+
+export class BatchBarrier {
+	private readonly batches = new Map<
+		string,
+		{
+			members: Map<string, BatchMember>;
+			terminal: Map<string, BatchMember>;
+			notified: boolean;
+		}
+	>();
+
+	/** Register a member at spawn time. Idempotent per (batchId, agentId). */
+	register(batchId: string, agentId: string, meta?: { description?: string; type?: string }): void {
+		let batch = this.batches.get(batchId);
+		if (!batch) {
+			batch = { members: new Map(), terminal: new Map(), notified: false };
+			this.batches.set(batchId, batch);
+		}
+		if (!batch.members.has(agentId)) {
+			batch.members.set(agentId, {
+				id: agentId,
+				description: meta?.description,
+				type: meta?.type,
+				status: "running",
+			});
+		}
+	}
+
+	/**
+	 * Record that a member reached a terminal state. Returns the batch snapshot.
+	 * `snapshot.allDone` is true iff every registered member is now terminal.
+	 * If the batch was never seen (defensive edge case), the member is registered
+	 * on-the-fly as a batch-of-one so its terminal state is not silently lost.
+	 */
+	markTerminal(batchId: string, member: BatchMember): BatchSnapshot {
+		let batch = this.batches.get(batchId);
+		if (!batch) {
+			batch = { members: new Map(), terminal: new Map(), notified: false };
+			this.batches.set(batchId, batch);
+		}
+		// Ensure the member is known (auto-register for the defensive case).
+		if (!batch.members.has(member.id)) {
+			batch.members.set(member.id, { ...member, status: member.status });
+		}
+		if (isTerminalStatus(member.status)) {
+			batch.terminal.set(member.id, { ...member });
+			const existing = batch.members.get(member.id);
+			if (existing) batch.members.set(member.id, { ...existing, status: member.status });
+		}
+		const allDone =
+			batch.members.size > 0 &&
+			[...batch.members.keys()].every((id) => batch.terminal.has(id));
+		return {
+			batchId,
+			members: [...batch.members.values()],
+			terminal: [...batch.terminal.values()],
+			allDone,
+			notified: batch.notified,
+		};
+	}
+
+	/** Has the consolidated notification already been emitted for this batch? */
+	alreadyNotified(batchId: string): boolean {
+		return this.batches.get(batchId)?.notified ?? false;
+	}
+
+	/** Mark the consolidated notification as emitted. No-op if already set. */
+	markNotified(batchId: string): void {
+		const batch = this.batches.get(batchId);
+		if (batch) batch.notified = true;
+	}
+
+	/** Read-only snapshot (for tests / debugging). */
+	snapshot(batchId: string): BatchSnapshot | undefined {
+		const batch = this.batches.get(batchId);
+		if (!batch) return undefined;
+		return {
+			batchId,
+			members: [...batch.members.values()],
+			terminal: [...batch.terminal.values()],
+			allDone:
+				batch.members.size > 0 &&
+				[...batch.members.keys()].every((id) => batch.terminal.has(id)),
+			notified: batch.notified,
+		};
+	}
+
+	/** Drop a batch (used on cleanup / test reset). */
+	dispose(batchId?: string): void {
+		if (batchId === undefined) this.batches.clear();
+		else this.batches.delete(batchId);
+	}
+}

package/src/runtime/child-pi.ts

@@ -12,6 +12,7 @@ import { attachPostExitStdioGuard, trySignalChild } from "./post-exit-stdio-guar
 import { redactJsonLine } from "../utils/redaction.ts";
 import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
 import { registerChildProcess, unregisterChildProcess } from "../extension/crew-cleanup.ts";
+import { classifyProcessCrash } from "./crash-classification.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
 
 const POST_EXIT_STDIO_GUARD_MS = DEFAULT_CHILD_PI.postExitStdioGuardMs;
@@ -912,7 +913,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				} catch (err) {
 					logInternalError("child-pi.on-lifecycle-event", err, `event=error, pid=${child.pid}`);
 				}
-				settle({ exitCode: null, stdout, stderr, error: processError.message });
+				settle({ exitCode: null, stdout, stderr, error: processError.message, exitStatus: { exitCode: null, cancelled: abortRequested, timedOut: responseTimeoutHit, killed: false, cleanupErrors, finalDrainMs, crashClass: classifyProcessCrash({ exitCode: null, cancelled: abortRequested, timedOut: responseTimeoutHit, spawnError: error, stderrSnippet: stderr ? stderr.slice(-1000) : undefined }).crashClass } });
 			});
 			child.on("exit", (code, signal) => {
 				if (child.pid) {
@@ -1001,7 +1002,19 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				// is logged, not fatal). The steerError branch is retained for safety in
 				// case a future change reintroduces a fatal steer path.
 				const steerError = steerInjectionFailed ? "Steer injection failed due to stdin backpressure; process killed" : undefined;
-				settle({ exitCode: finalExitCode, stdout, stderr, ...(timeoutError ? { error: timeoutError.error } : {}), ...(steerError ? { error: steerError } : {}), aborted: wasGraceAborted || wasParentAborted, steered: softLimitReached && !wasGraceAborted, exitStatus: { exitCode: finalExitCode, cancelled: abortRequested, timedOut: responseTimeoutHit, killed: hardKilled, cleanupErrors, finalDrainMs } });
+				// P0 crash taxonomy: classify the exit so callers/dashboards can bucket
+				// failure modes (timeout vs cancel vs native panic vs signal …).
+				// The classifier is a pure function; this is the single integration point.
+				const crashClassification = classifyProcessCrash({
+					exitCode: finalExitCode,
+					signal: child.signalCode ?? undefined,
+					cancelled: abortRequested,
+					timedOut: responseTimeoutHit,
+					killed: hardKilled,
+					spawnError: undefined,
+					stderrSnippet: stderr ? stderr.slice(-1000) : undefined,
+				});
+				settle({ exitCode: finalExitCode, stdout, stderr, ...(timeoutError ? { error: timeoutError.error } : {}), ...(steerError ? { error: steerError } : {}), aborted: wasGraceAborted || wasParentAborted, steered: softLimitReached && !wasGraceAborted, exitStatus: { exitCode: finalExitCode, cancelled: abortRequested, timedOut: responseTimeoutHit, killed: hardKilled, cleanupErrors, finalDrainMs, crashClass: crashClassification.crashClass } });
 			});
 		});
 	} finally {

package/src/runtime/crash-classification.ts

@@ -0,0 +1,208 @@
+/**
+ * Crash Classification Taxonomy — pure function for categorizing worker exits.
+ *
+ * Distilled from gajae-code's `debug/crash-diagnostics.ts` (P0 item #1).
+ * Unlike the original, this module is pure: it does NOT write crash reports or
+ * touch the filesystem. The file-I/O layer is intentionally omitted; callers
+ * that want durable crash logs can layer them on top of {@link classifyProcessCrash}.
+ *
+ * The classification precedence (most-significant first) mirrors the
+ * reference implementation:
+ *
+ *   1. timeout          — process was terminated by the response-timeout guard
+ *   2. cancelled        — cooperative cancellation (AbortSignal) triggered exit
+ *   3. spawn_error      — child_process emitted an `error` event before `exit`
+ *   4. native_panic     — stderr indicates a native crash (SIGSEGV / abort / panic)
+ *   5. signal_exit      — the process was terminated by an OS signal
+ *   6. clean_exit       — exit code 0
+ *   7. non_zero_exit    — exit code != 0 (and != null)
+ *   8. protocol_exit    — exit code is null with no signal (protocol/stream
+ *                         ended before a normal exit was observed)
+ *   9. unknown          — defensive fallback (should not occur in practice)
+ *
+ * NOTE on timeout-vs-cancel precedence: when BOTH `timedOut` and `cancelled`
+ * are true, `timeout` wins (the timeout terminated the process). This matches
+ * gajae-code and the existing child-pi.ts response-timeout guard, which fires
+ * the hard kill and is the proximate cause.
+ */
+
+/**
+ * Categorical classification of why a worker process ended.
+ *
+ * @see classifyProcessCrash
+ */
+export type CrashClass =
+	| "clean_exit"
+	| "non_zero_exit"
+	| "signal_exit"
+	| "timeout"
+	| "cancelled"
+	| "spawn_error"
+	| "protocol_exit"
+	| "native_panic"
+	| "unknown";
+
+/**
+ * Inputs to {@link classifyProcessCrash}. All fields are optional/safe-defaulting
+ * so callers can pass a partial view (e.g. just `{ exitCode: 0 }`).
+ *
+ * Field semantics:
+ * - `exitCode`    — the OS exit code, or `null` when no code was observed.
+ * - `signal`      — the terminating signal name (e.g. `"SIGTERM"`) or `null`.
+ * - `cancelled`   — true when cooperative cancellation (AbortSignal) was requested.
+ * - `timedOut`    — true when the response-timeout guard fired (and likely killed).
+ * - `killed`      — true when the parent explicitly killed the child (best-effort).
+ * - `spawnError`  — truthy when the child emitted a spawn/process `error` event.
+ * - `stderrSnippet` — tail of captured stderr, used to detect native panics.
+ */
+export interface CrashClassificationInput {
+	exitCode?: number | null;
+	signal?: string | null;
+	cancelled?: boolean;
+	timedOut?: boolean;
+	killed?: boolean;
+	spawnError?: unknown;
+	stderrSnippet?: string;
+}
+
+/**
+ * Result of classifying an exit. `crashClass` is machine-readable;
+ * `reason` is a human-friendly one-liner suitable for logs/diagnostics.
+ */
+export interface CrashClassification {
+	crashClass: CrashClass;
+	reason: string;
+}
+
+// ── native-panic detection ──────────────────────────────────────────────────
+//
+// We look for a small, well-known set of native-crash signatures in the stderr
+// tail. This is deliberately conservative: false positives would mislabel
+// ordinary non-zero exits as native panics. The patterns are anchored on
+// substrings that do not appear in normal application output.
+
+interface NativePanicSignature {
+	/** Substring to search for (case-insensitive). */
+	pattern: string;
+	/** Human-readable class-specific reason suffix. */
+	label: string;
+}
+
+const NATIVE_PANIC_SIGNATURES: readonly NativePanicSignature[] = [
+	{ pattern: "sigsegv", label: "segmentation fault" },
+	{ pattern: "segfault", label: "segmentation fault" },
+	{ pattern: "segmentation fault", label: "segmentation fault" },
+	{ pattern: "sigabrt", label: "abort signal" },
+	{ pattern: "abort(", label: "abort" },
+	{ pattern: "fatal error", label: "V8/node fatal error" },
+	{ pattern: "panic:", label: "rust/go panic" },
+	{ pattern: "thread '", label: "rust panic (thread context)" },
+	{ pattern: "illegal instruction", label: "illegal instruction" },
+	{ pattern: "double free", label: "heap corruption (double free)" },
+];
+
+/**
+ * If the stderr tail contains a recognizable native-crash signature, return the
+ * matching label; otherwise `null`. Case-insensitive.
+ */
+function detectNativePanic(stderrSnippet: string | undefined): string | null {
+	if (!stderrSnippet) return null;
+	const lower = stderrSnippet.toLowerCase();
+	for (const sig of NATIVE_PANIC_SIGNATURES) {
+		if (lower.includes(sig.pattern)) return sig.label;
+	}
+	return null;
+}
+
+/** Normalize an optional/signal-ish value to `string | null`. */
+function normalizeSignal(signal: string | null | undefined): string | null {
+	return signal ?? null;
+}
+
+/**
+ * Classify a worker exit into a {@link CrashClass}.
+ *
+ * Pure: no I/O, no globals, no side effects. Deterministic given the same input.
+ * Safe to call from any context (including signal handlers).
+ *
+ * @example
+ * classifyProcessCrash({ exitCode: 0 })                       // → clean_exit
+ * classifyProcessCrash({ exitCode: 1 })                       // → non_zero_exit
+ * classifyProcessCrash({ signal: "SIGTERM" })                 // → signal_exit
+ * classifyProcessCrash({ timedOut: true, exitCode: null })    // → timeout
+ * classifyProcessCrash({ cancelled: true, exitCode: null })   // → cancelled
+ * classifyProcessCrash({ spawnError: new Error("ENOENT") })   // → spawn_error
+ * classifyProcessCrash({ exitCode: null })                    // → protocol_exit
+ * classifyProcessCrash({ exitCode: 139, signal: "SIGSEGV" })  // → signal_exit
+ * classifyProcessCrash({ exitCode: 134, stderrSnippet: "abort()" }) // → native_panic
+ */
+export function classifyProcessCrash(input: CrashClassificationInput): CrashClassification {
+	const exitCode = input.exitCode ?? null;
+	const signal = normalizeSignal(input.signal);
+
+	// 1. Timeout takes precedence: the response-timeout guard is the proximate
+	//    cause of death even if cancellation was also requested.
+	if (input.timedOut) {
+		return { crashClass: "timeout", reason: "process timed out (response timeout guard fired)" };
+	}
+
+	// 2. Cooperative cancellation.
+	if (input.cancelled) {
+		return { crashClass: "cancelled", reason: "process was cancelled (abort requested)" };
+	}
+
+	// 3. Spawn error: the child never started or emitted a process error.
+	if (input.spawnError !== undefined && input.spawnError !== null) {
+		return {
+			crashClass: "spawn_error",
+			reason: `spawn error: ${stringifyError(input.spawnError)}`,
+		};
+	}
+
+	// 4. Native panic from stderr (only when we have a signal/abnormal exit —
+	//    never reclassify a clean exit as a panic based on stderr noise).
+	const abnormalExit = signal !== null || (exitCode !== null && exitCode !== 0);
+	if (abnormalExit) {
+		const panic = detectNativePanic(input.stderrSnippet);
+		if (panic !== null) {
+			return { crashClass: "native_panic", reason: `native panic detected: ${panic}` };
+		}
+	}
+
+	// 5. Signal exit.
+	if (signal !== null) {
+		return { crashClass: "signal_exit", reason: `process exited after signal ${signal}` };
+	}
+
+	// 6. Clean exit.
+	if (exitCode === 0) {
+		return { crashClass: "clean_exit", reason: "process exited cleanly" };
+	}
+
+	// 7. Non-zero exit.
+	if (exitCode !== null) {
+		return { crashClass: "non_zero_exit", reason: `process exited with code ${exitCode}` };
+	}
+
+	// 8. Protocol exit: exitCode is null with no signal — the process stream
+	//    ended before a normal exit was observed (e.g. stdio closed unexpectedly).
+	//    If `killed` is true but no signal was recorded, treat as protocol_exit
+	//    (the kill may not have delivered a signal we could capture).
+	if (input.killed) {
+		return { crashClass: "protocol_exit", reason: "process was killed but no signal/exit code was captured" };
+	}
+
+	// 8b. Truly null exitCode with no other context — protocol/stream ended early.
+	return { crashClass: "protocol_exit", reason: "process exited before protocol completion (exit code unknown)" };
+}
+
+/** Render an unknown error value to a short message string. */
+function stringifyError(error: unknown): string {
+	if (error instanceof Error) return error.message || error.name;
+	if (typeof error === "string") return error;
+	try {
+		return String(error);
+	} catch {
+		return "(unstringifiable error)";
+	}
+}