pi-crew 0.9.8 → 0.9.10

package/src/extension/team-tool/doctor.ts

@@ -28,27 +28,47 @@ function firstOutputLine(stdout: string | null | undefined, stderr: string | nul
 	return output.split(/\r?\n/).find((line) => line.trim().length > 0)?.trim() ?? "available";
 }
 
+// Round 29 optimization: memoize spawnSync probe results at module level.
+// The probes (git --version, pi --version) are stable for the process
+// lifetime, and spawnSync on a node script can cost 1-2s. Without the
+// cache, each buildTeamDoctorReport() call would pay that cost, and a
+// file with 12 tests would take 20s+ even with empty cwd. The cache is
+// safe: a doctor check is informational, and a stale ok=true would
+// self-correct on the next process restart.
+const commandExistsCache = new Map<string, { ok: boolean; detail: string }>();
 function commandExists(command: string, args: string[]): { ok: boolean; detail: string } {
+	const cacheKey = `${command} ${args.join(" ")}`;
+	const cached = commandExistsCache.get(cacheKey);
+	if (cached) return cached;
+	let result: { ok: boolean; detail: string };
 	try {
 		const output = spawnSync(command, args, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
 		if (output.error) {
-			return { ok: false, detail: output.error.message };
+			result = { ok: false, detail: output.error.message };
+		} else if (output.status !== 0) {
+			result = { ok: false, detail: firstOutputLine(output.stdout, output.stderr) || `status ${output.status}` };
+		} else {
+			result = { ok: true, detail: firstOutputLine(output.stdout, output.stderr) };
 		}
-		if (output.status !== 0) {
-			return { ok: false, detail: firstOutputLine(output.stdout, output.stderr) || `status ${output.status}` };
-		}
-		return { ok: true, detail: firstOutputLine(output.stdout, output.stderr) };
 	} catch (error) {
-		return { ok: false, detail: error instanceof Error ? error.message : String(error) };
+		result = { ok: false, detail: error instanceof Error ? error.message : String(error) };
 	}
+	commandExistsCache.set(cacheKey, result);
+	return result;
 }
 
+let piCommandExistsCache: { ok: boolean; detail: string } | undefined;
 function piCommandExists(): { ok: boolean; detail: string } {
+	if (piCommandExistsCache) return piCommandExistsCache;
 	const spec = getPiSpawnCommand(["--version"]);
 	const output = commandExists(spec.command, spec.args);
-	if (!output.ok) return output;
+	if (!output.ok) {
+		piCommandExistsCache = output;
+		return piCommandExistsCache;
+	}
 	const executable = spec.command === "pi" ? "pi" : `${spec.command} ${spec.args[0] ?? ""}`.trim();
-	return { ok: true, detail: `${output.detail} (${executable})` };
+	piCommandExistsCache = { ok: true, detail: `${output.detail} (${executable})` };
+	return piCommandExistsCache;
 }
 
 function checkWritableDir(dir: string): { ok: boolean; detail: string } {
@@ -119,12 +139,18 @@ export interface TeamDoctorReport {
 }
 
 export function buildTeamDoctorReport(input: TeamDoctorReportInput): TeamDoctorReport {
+	// Discover once — used in both Drift and Discovery sections. Walking the
+	// filesystem 3x (agents/teams/workflows) is the dominant cost of this
+	// function; calling it twice doubles the cost. Round 29 optimization.
+	const discoveredAgentsAll = allAgents(discoverAgents(input.cwd));
+	const discoveredTeamsAll = allTeams(discoverTeams(input.cwd));
+	const discoveredWorkflowsAll = allWorkflows(discoverWorkflows(input.cwd));
 	// Compute drift once — reused in both Drift section and return value
 	const driftResult = detectDrift(
 		{
-			agents: allAgents(discoverAgents(input.cwd)).map((a) => a.name),
-			teams: allTeams(discoverTeams(input.cwd)).map((t) => t.name),
-			workflows: allWorkflows(discoverWorkflows(input.cwd)).map((w) => w.name),
+			agents: discoveredAgentsAll.map((a) => a.name),
+			teams: discoveredTeamsAll.map((t) => t.name),
+			workflows: discoveredWorkflowsAll.map((w) => w.name),
 		},
 		loadConfig(input.cwd).config,
 	);
@@ -153,14 +179,11 @@ export function buildTeamDoctorReport(input: TeamDoctorReportInput): TeamDoctorR
 			];
 		}),
 		section("Discovery", () => {
-			const discoveredAgents = allAgents(discoverAgents(input.cwd));
-			const discoveredTeams = allTeams(discoverTeams(input.cwd));
-			const discoveredWorkflows = allWorkflows(discoverWorkflows(input.cwd));
-			const agentModelHints = discoveredAgents.filter((agent) => agent.model || agent.fallbackModels?.length).length;
+			const agentModelHints = discoveredAgentsAll.filter((agent) => agent.model || agent.fallbackModels?.length).length;
 			return [
-				{ label: "agents", ok: true, detail: `${discoveredAgents.length} discovered` },
-				{ label: "teams", ok: true, detail: `${discoveredTeams.length} discovered` },
-				{ label: "workflows", ok: true, detail: `${discoveredWorkflows.length} discovered` },
+				{ label: "agents", ok: true, detail: `${discoveredAgentsAll.length} discovered` },
+				{ label: "teams", ok: true, detail: `${discoveredTeamsAll.length} discovered` },
+				{ label: "workflows", ok: true, detail: `${discoveredWorkflowsAll.length} discovered` },
 				{ label: "resource model hints", ok: true, detail: `${agentModelHints} agents declare model/fallback preferences` },
 			];
 		}),

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

@@ -1,5 +1,6 @@
 import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
 import type { AgentConfig } from "../agents/agent-config.ts";
@@ -9,9 +10,12 @@ import { getPiSpawnCommand } from "./pi-spawn.ts";
 import { DEFAULT_CHILD_PI } from "../config/defaults.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "./post-exit-stdio-guard.ts";
-import { redactJsonLine } from "../utils/redaction.ts";
+import { redactJsonLine, redactSecretString } from "../utils/redaction.ts";
+import { applyCompactPipeline } from "./compact-pipeline.ts";
+import { TruncationStage, TailCaptureStage } from "./compact-stages/index.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;
@@ -26,12 +30,33 @@ const MAX_COMPACT_CONTENT_CHARS = DEFAULT_CHILD_PI.maxCompactContentChars;
 const activeChildProcesses = new Map<number, ChildProcess>();
 const childHardKillTimers = new Map<number, NodeJS.Timeout>();
 
+/**
+ * SEC-1: Extract a redacted stderr/stdout excerpt for embedding in lifecycle
+ * events and error messages. The in-memory stdout/stderr accumulators receive
+ * RAW worker output (only structurally compacted via compactChildPiEvent —
+ * NOT secret-redacted), so any slice embedded into a persisted event must be
+ * redacted here. Otherwise worker-emitted secrets (API keys, tokens returned
+ * from a tool call) leak through diagnostic logs that bypass artifact-store
+ * redaction.
+ *
+ * Extracted as a single helper (8 call sites were duplicating this) so the
+ * redaction boundary is unit-testable directly. The real spawn error/timeout
+ * paths are integration-level and NOT reachable via PI_TEAMS_MOCK_CHILD_PI
+ * (the mock returns before the lifecycle-event handlers run), so a behavior
+ * test must target this helper rather than the full runChildPi path.
+ */
+export function redactStderrExcerpt(stderr: string, maxChars: number): string {
+	return redactSecretString(stderr.slice(-maxChars));
+}
+
 function appendBoundedTail(current: string, chunk: string, maxBytes = MAX_CAPTURE_BYTES): string {
-	const combined = current + chunk;
-	if (Buffer.byteLength(combined, "utf-8") <= maxBytes) return combined;
-	let tail = combined.slice(Math.max(0, combined.length - maxBytes));
-	while (Buffer.byteLength(tail, "utf-8") > maxBytes) tail = tail.slice(1024);
-	return `[pi-crew captured output truncated to last ${Math.round(maxBytes / 1024)} KiB]\n${tail}`;
+	// Sprint 5: refactored onto TailCaptureStage (P0-A stage-chain). The marker
+	// embeds the cap size in KiB so the caller sees how much was dropped. Stage
+	// construction per call is cheap (4 fields) and avoids caching concerns.
+	return new TailCaptureStage({
+		maxBytes,
+		marker: `[pi-crew captured output truncated to last ${Math.round(maxBytes / 1024)} KiB]`,
+	}).apply(current + chunk);
 }
 
 function clearHardKillTimer(pid: number | undefined): void {
@@ -378,32 +403,56 @@ function appendTranscript(input: ChildPiRunInput, line: string): void {
 	}
 }
 
-function compactString(value: string, maxChars = MAX_COMPACT_CONTENT_CHARS): string {
+export function compactString(
+	value: string,
+	maxChars = MAX_COMPACT_CONTENT_CHARS,
+	opts: { preserveImportant?: boolean } = {},
+): string {
 	if (value.length <= maxChars) return value;
 	// L4: head + tail instead of head-only. Keeps closing markdown structure
 	// (code fences, headings, list tails) instead of dropping them — the old
 	// head-only slice left unclosed ``` fences that downstream parsers and
 	// output-validator.ts flagged as "output may be truncated". Head gets 75%
 	// (opening structure + bulk of content); tail gets 25% (closing structure).
-	const head = Math.floor(maxChars * 0.75);
-	const tail = maxChars - head;
-	return `${value.slice(0, head)}\n...[pi-crew compacted ${value.length - maxChars} chars, head+tail preserved]...\n${value.slice(-tail)}`;
+	// P0-A: compose the value through the stage-chain compression pipeline.
+	// The default pipeline is just [TruncationStage] (single-stage, equivalent
+	// to the pre-P0-A implementation) so plain text with no ANSI / no blank
+	// runs / no consecutive duplicates produces bit-identical output (L4
+	// regression safety). Callers that want noise stripping can opt into
+	// additional stages via the pipeline — but compactString's caller surface
+	// keeps the simple `(value, maxChars, opts)` signature.
+	// P0-B: the TruncationStage scans the middle slice for important diagnostic
+	// lines (error, file:line, HTTP 4xx/5xx, compiler codes) and preserves them
+	// within a 15% slack budget. The `preserveImportant` opt propagates here.
+	const result = applyCompactPipeline(value, [new TruncationStage(maxChars, { preserveImportant: opts.preserveImportant })]);
+	return result.text;
 }
 
-function compactValue(value: unknown): unknown {
+export function compactValue(value: unknown): unknown {
 	if (typeof value === "string") return compactString(value);
-	if (Array.isArray(value)) return value.slice(0, 20).map(compactValue);
+	if (Array.isArray(value)) {
+		// BUG-4: silent .slice(0, 20) lost items 21-50 with no marker.
+		// Append a truncation marker when entries are dropped so downstream
+		// consumers know data was elided (consistent with compactString style).
+		if (value.length > 20) {
+			return [...value.slice(0, 20).map(compactValue), `[pi-crew truncated ${value.length - 20} entries]`];
+		}
+		return value.map(compactValue);
+	}
 	const record = asRecord(value);
 	if (!record) return value;
+	const entries = Object.entries(record);
 	const compacted: Record<string, unknown> = {};
-	for (const [key, entry] of Object.entries(record).slice(0, 20)) compacted[key] = compactValue(entry);
+	for (const [key, entry] of entries.slice(0, 20)) compacted[key] = compactValue(entry);
+	// BUG-4: mark elided object keys so consumers know data was dropped.
+	if (entries.length > 20) compacted["[truncated]"] = `${entries.length - 20} entries`;
 	return compacted;
 }
 
 function compactContentPart(part: unknown): unknown | undefined {
 	const record = asRecord(part);
 	if (!record) return undefined;
-	if (record.type === "text") return { type: "text", text: typeof record.text === "string" ? compactString(record.text, MAX_ASSISTANT_TEXT_CHARS) : "" };
+	if (record.type === "text") return { type: "text", text: typeof record.text === "string" ? compactString(record.text, MAX_ASSISTANT_TEXT_CHARS, { preserveImportant: false }) : "" };
 	if (record.type === "toolCall") return { type: "toolCall", name: record.name, input: compactValue(typeof record.input === "string" ? compactString(record.input, MAX_TOOL_INPUT_CHARS) : record.input) };
 	if (record.type === "toolResult") return { type: "toolResult", name: record.name, content: compactValue(typeof record.content === "string" ? compactString(record.content, MAX_TOOL_RESULT_CHARS) : record.content) };
 	return undefined;
@@ -568,6 +617,55 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			return { exitCode: 0, stdout, stderr: "" };
 		}
 		if (mock === "retryable-failure") return { exitCode: 1, stdout: "", stderr: "[MOCK] rate limit: mock failure" };
+		// E2E fallback-chain fixture: invocation #1 returns a SILENT retryable
+		// failure (exit code 0, no real assistant text, message_end carries a
+		// retryable-pattern errorMessage). Invocation #2+ delegates to the
+		// standard json-success shape. Counter lives in os.tmpdir() keyed by
+		// process.pid + mock name so concurrent test processes don't collide.
+		// The test cleans up the file in its finally block.
+		if (mock === "retryable-failure-then-success") {
+			const counterFile = path.join(os.tmpdir(), `pi-crew-mock-counter-${process.pid}-retryable-failure-then-success`);
+			let count = 0;
+			try {
+				const raw = fs.readFileSync(counterFile, "utf-8");
+				const parsed = Number.parseInt(raw.trim(), 10);
+				if (Number.isFinite(parsed) && parsed >= 0) count = parsed;
+			} catch {
+				// file missing or unreadable — first invocation in this process
+			}
+			count += 1;
+			try {
+				fs.writeFileSync(counterFile, String(count));
+			} catch (error) {
+				logInternalError("child-pi.mock-counter-write", error as Error, `file=${counterFile}`);
+			}
+			if (count === 1) {
+				// Silent retryable failure: exit 0, no real text, message_end
+				// carries errorMessage matching `/provider[_ ]?error/i` so that
+				// `detectRetryableModelFailureFromOutput` surfaces it as an error
+				// and `isRetryableModelFailure` routes the next attempt to the
+				// next candidate model. `stopReason:"error"` (NOT "stop") so
+				// `isFinalAssistantEvent` does NOT prematurely terminate the run.
+				const failureEvent = {
+					type: "message_end",
+					message: {
+						role: "assistant",
+						content: [],
+						errorMessage: "Provider error: api_error",
+						stopReason: "error",
+					},
+				};
+				const stdout = `${JSON.stringify(failureEvent)}\n`;
+				observeStdoutChunk(input, stdout);
+				return { exitCode: 0, stdout, stderr: "" };
+			}
+			// Subsequent invocations: delegate to json-success shape so the
+			// fallback chain's second attempt succeeds and the run completes.
+			const text = `[MOCK] JSON success for ${input.agent.name}`;
+			const stdout = `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`;
+			observeStdoutChunk(input, stdout);
+			return { exitCode: 0, stdout, stderr: "" };
+		}
 		return { exitCode: 1, stdout: "", stderr: `[MOCK] failure: ${mock}` };
 	}
 	const built = buildPiWorkerArgs({ task: effectiveTask, agent: input.agent, model: input.model, sessionEnabled: true, maxDepth: input.maxDepth, skillPaths: input.skillPaths, role: input.role });
@@ -687,7 +785,9 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				noResponseTimer = setTimeout(() => {
 					responseTimeoutHit = true;
 					// Capture stderr at timeout moment for debugging
-					const timeoutStderr = stderr.slice(-1024); // Last 1KB of stderr
+					// SEC-1: redact secrets before embedding in lifecycle event so
+					// worker-emitted secrets (API keys etc.) don't bypass redaction.
+					const timeoutStderr = redactStderrExcerpt(stderr, 1024); // Last 1KB of stderr (redacted, SEC-1)
 					input.onLifecycleEvent?.({ type: "response_timeout", pid: child.pid, error: `No output for ${responseTimeoutMs}ms`, ts: new Date().toISOString(), stderr: timeoutStderr || undefined });
 					killProcessTree(child.pid, child);
 					try {
@@ -903,16 +1003,17 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			});
 			child.on("error", (error) => {
 				// Reject pending operations with process error context
+				// SEC-1: redact stderr secrets embedded in the error message + excerpt.
 				const processError = new Error(
-					`Child Pi process error: ${error.message}. Stderr: ${stderr.slice(-500) || "(none)"}`,
+					`Child Pi process error: ${error.message}. Stderr: ${redactStderrExcerpt(stderr, 500) || "(none)"}`,
 				);
 				rejectPendingOperations(processError);
 				try {
-					input.onLifecycleEvent?.({ type: "spawn_error", pid: child.pid, error: processError.message, ts: new Date().toISOString(), stderrExcerpt: stderr.slice(-500) || undefined });
+					input.onLifecycleEvent?.({ type: "spawn_error", pid: child.pid, error: processError.message, ts: new Date().toISOString(), stderrExcerpt: redactStderrExcerpt(stderr, 500) || undefined });
 				} 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 ? redactStderrExcerpt(stderr, 1000) : undefined }).crashClass } });
 			});
 			child.on("exit", (code, signal) => {
 				if (child.pid) {
@@ -931,7 +1032,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				const exitError = isUnexpectedExit
 					? new Error(
 						`Child Pi process exited unexpectedly (code=${code ?? "null"} signal=${signal ?? "null"}). `
-						+ `Stderr: ${stderr.slice(-1000) || "(none)"}`,
+						+ `Stderr: ${redactStderrExcerpt(stderr, 1000) || "(none)"}`,
 					)
 					: null;
 				if (exitError) {
@@ -947,7 +1048,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 						exitCode: code,
 						ts: new Date().toISOString(),
 						error: exitError?.message,
-						stderrExcerpt: isUnexpectedExit ? stderr.slice(-1000) || undefined : undefined,
+						stderrExcerpt: isUnexpectedExit ? redactStderrExcerpt(stderr, 1000) || undefined : undefined,
 						// Phase-0 diagnostic fields (kept optional — no type change required).
 						...(signal ? { signal } : {}),
 						...(finalDrainArmed || forcedFinalDrain
@@ -987,7 +1088,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				} catch (err) {
 					logInternalError("child-pi.on-lifecycle-event", err, `event=close, pid=${child.pid}`);
 				}
-				const timeoutError = responseTimeoutHit && !stderr.trim() ? { error: `Child Pi produced no new output for ${responseTimeoutMs}ms; process was terminated as unresponsive.` } : responseTimeoutHit && stderr.trim() ? { error: `Child Pi timed out after ${responseTimeoutMs}ms with stderr: ${stderr.slice(-500)}` } : undefined;
+				const timeoutError = responseTimeoutHit && !stderr.trim() ? { error: `Child Pi produced no new output for ${responseTimeoutMs}ms; process was terminated as unresponsive.` } : responseTimeoutHit && stderr.trim() ? { error: `Child Pi timed out after ${responseTimeoutMs}ms with stderr: ${redactStderrExcerpt(stderr, 500)}` } : undefined;
 				// M6 fix: log when forced final drain converts non-zero exit to 0.
 			// This is expected in normal operation (child finished cleanly but linger was killed),
 			// but the telemetry helps detect regressions where crashes are hidden.
@@ -1001,7 +1102,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 ? redactStderrExcerpt(stderr, 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/compact-pipeline.ts

@@ -0,0 +1,56 @@
+/**
+ * Stage-chain compression pipeline (P0-A).
+ *
+ * Composable, monotonic-shrink-safe text compression. Each stage declares an
+ * `id` and an `apply(text): string` method. The pipeline runs stages in
+ * order, applying each stage's output ONLY if it is no longer than the
+ * stage's input. This is the safety property that prevents the family of
+ * bugs the old L4 caveman-shrink refactor surfaced (24/27 artifacts corrupted
+ * with null bytes because a regex-based shrink expanded its input in some
+ * cases — knowledge.md "L4 output-handling"). With the monotonic-shrink gate,
+ * a buggy stage implementation can NEVER cause output growth, and therefore
+ * cannot corrupt downstream structure.
+ *
+ * Ported from Hypa's `src/Hypa.Infrastructure/Compression/GenericOutputCompressor.cs`
+ * (stage loop with `if (next.Length <= text.Length)` gate).
+ */
+
+export interface ICompactStage {
+	/** Stable identifier; surfaced in `PipelineResult.applied` for observability. */
+	readonly id: string;
+	/**
+	 * Transform `text`. MUST be pure (no side effects, deterministic for a
+	 * given input). MAY return the input unchanged when nothing to do — the
+	 * pipeline will skip it via the monotonic-shrink gate regardless, but
+	 * returning the same string keeps `applied` honest.
+	 */
+	apply(text: string): string;
+}
+
+export interface PipelineResult {
+	text: string;
+	/** ids of stages whose output was accepted (shorter-or-equal than their input). */
+	applied: readonly string[];
+}
+
+/**
+ * Run `stages` in order. Each stage is applied only if its output is no
+ * longer than its current input. The pipeline NEVER expands text — if a
+ * stage would expand, it is silently skipped (its id is not added to
+ * `applied`).
+ */
+export function applyCompactPipeline(text: string, stages: readonly ICompactStage[]): PipelineResult {
+	let current = text;
+	const applied: string[] = [];
+	for (const stage of stages) {
+		if (!stage || typeof stage.apply !== "function") continue; // defensive: skip malformed entries
+		const next = stage.apply(current);
+		if (typeof next !== "string") continue; // defensive: skip non-string output
+		if (next.length <= current.length) {
+			current = next;
+			applied.push(stage.id);
+		}
+		// else: stage attempted to expand input — silently drop (monotonic-shrink gate).
+	}
+	return { text: current, applied };
+}

package/src/runtime/compact-stages/ansi-strip-stage.ts

@@ -0,0 +1,25 @@
+/**
+ * AnsiStripStage — strip ANSI CSI escape sequences.
+ *
+ * Matches the common CSI pattern: ESC `[` followed by parameter bytes
+ * (0-9 ; ?), intermediate bytes (space - /), and a final byte (@-~).
+ * Sufficient for the color/cursor codes emitted by npm, cargo, jest, etc.
+ * Does not attempt to handle OSC / DCS / private modes (rare in CLI output
+ * captured into artifacts; can be added later if real-world signal emerges).
+ *
+ * Idempotent (no ANSI in → no change; ANSI in → ANSI out).
+ */
+import type { ICompactStage } from "../compact-pipeline.ts";
+
+// CSI: ESC [ <params 0-9;> <intermediates space-/ > <final @-~>
+const ANSI_CSI_PATTERN = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+
+export class AnsiStripStage implements ICompactStage {
+	readonly id = "ansi-strip";
+	apply(text: string): string {
+		if (text.indexOf("\x1b") === -1) return text; // fast path: no ESC at all
+		return text.replace(ANSI_CSI_PATTERN, "");
+	}
+}
+
+export const ANSI_STRIP_STAGE = new AnsiStripStage();

package/src/runtime/compact-stages/blank-collapse-stage.ts

@@ -0,0 +1,31 @@
+/**
+ * BlankCollapseStage — collapse runs of 3+ consecutive newlines to a single
+ * blank line (i.e., 2 newlines).
+ *
+ * Reduces whitespace noise in long command output (npm install, cargo build,
+ * jest, etc. frequently emit blocks of blank lines between sections). Does
+ * NOT touch 1 or 2 consecutive newlines — those are legitimate paragraph
+ * breaks in prose.
+ *
+ * Idempotent (already-collapsed input → unchanged).
+ */
+import type { ICompactStage } from "../compact-pipeline.ts";
+
+export class BlankCollapseStage implements ICompactStage {
+	readonly id = "blank-collapse";
+	// NOTE: deliberately NOT using parameter-property shorthand here because
+	// Node's --experimental-strip-types does not support it. Field + ctor
+	// assignment is the portable shape.
+	private readonly minConsecutive: number;
+	constructor(minConsecutive = 3) {
+		this.minConsecutive = minConsecutive;
+	}
+	apply(text: string): string {
+		if (this.minConsecutive < 2) return text;
+		// {minConsecutive,} matches minConsecutive or more; replace with "\n\n" (one blank line).
+		const pattern = new RegExp(`\\n{${this.minConsecutive},}`, "g");
+		return text.replace(pattern, "\n\n");
+	}
+}
+
+export const BLANK_COLLAPSE_STAGE = new BlankCollapseStage();

package/src/runtime/compact-stages/deduplicate-stage.ts

@@ -0,0 +1,34 @@
+/**
+ * DeduplicateStage — collapse CONSECUTIVE duplicate lines into one.
+ *
+ * Useful for log output where the same line repeats (retry attempts, poll
+ * loops, etc.). Only collapses CONSECUTIVE duplicates — non-adjacent
+ * repetitions are kept (they may be legitimately repeated later). Does NOT
+ * touch whitespace-only differences.
+ *
+ * Idempotent.
+ *
+ * SAFETY: do NOT enable this stage on assistant prose. "I I I went to the
+ * store" would lose emphasis. compactString's default pipeline does NOT
+ * include this stage for that reason; it is opt-in only.
+ */
+import type { ICompactStage } from "../compact-pipeline.ts";
+
+export class DeduplicateStage implements ICompactStage {
+	readonly id = "deduplicate";
+	apply(text: string): string {
+		if (text.length === 0) return text;
+		const lines = text.split(/\r?\n/);
+		if (lines.length < 2) return text;
+		const out: string[] = [lines[0]!];
+		for (let i = 1; i < lines.length; i++) {
+			const cur = lines[i]!;
+			if (cur !== out[out.length - 1]) out.push(cur);
+		}
+		// Preserve original line ending style: if input used \r\n, restore that.
+		const sep = text.includes("\r\n") ? "\r\n" : "\n";
+		return out.join(sep);
+	}
+}
+
+export const DEDUPLICATE_STAGE = new DeduplicateStage();