pi-crew 0.9.9 → 0.9.10

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,7 +10,9 @@ 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";
@@ -27,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 {
@@ -379,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;
@@ -569,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 });
@@ -688,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 {
@@ -904,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, 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 } });
+				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) {
@@ -932,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) {
@@ -948,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
@@ -988,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.
@@ -1012,7 +1112,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 					timedOut: responseTimeoutHit,
 					killed: hardKilled,
 					spawnError: undefined,
-					stderrSnippet: stderr ? stderr.slice(-1000) : 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 } });
 			});

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();

package/src/runtime/compact-stages/head-snap-stage.ts

@@ -0,0 +1,57 @@
+/**
+ * HeadSnapStage — keep the first N bytes of the input, optionally snapping to
+ * the last newline within that region for clean line boundaries.
+ *
+ * Distinct from TruncationStage (head + important-middle + tail, P0-B / P0-A):
+ * this stage is pure head-only with optional newline-snap, used by the
+ * iteration-hooks hook-output capture where the goal is "first N bytes
+ * snapped to a clean line" rather than head + tail.
+ *
+ * Use case in pi-crew:
+ *   - `iteration-hooks.ts` truncateToLimit — hook stdout capture capped at
+ *     MAX_STDOUT_BYTES (8KB), snapped to the last newline in the head region
+ *     so partial lines never appear in the captured preview.
+ *
+ * Byte cap (not char cap) to preserve the original memory budget semantic:
+ * the input is converted from Buffer to string once, then this stage ensures
+ * the output never exceeds the byte cap by walking back any partial UTF-8
+ * sequence at the cut boundary.
+ */
+import type { ICompactStage } from "../compact-pipeline.ts";
+
+export interface HeadSnapStageConfig {
+	/** Maximum output size in bytes. */
+	maxBytes: number;
+	/** When true, snap the cut to the last newline within the head region. */
+	snapToNewline?: boolean;
+	/** Optional explicit id; defaults to "head-snap". */
+	id?: string;
+}
+
+export class HeadSnapStage implements ICompactStage {
+	readonly id: string;
+	private readonly maxBytes: number;
+	private readonly snapToNewline: boolean;
+	constructor(config: HeadSnapStageConfig) {
+		if (!Number.isFinite(config.maxBytes) || config.maxBytes <= 0) {
+			throw new Error(`HeadSnapStage: maxBytes must be a positive finite number, got ${config.maxBytes}`);
+		}
+		this.maxBytes = config.maxBytes;
+		this.snapToNewline = config.snapToNewline !== false;
+		this.id = config.id ?? "head-snap";
+	}
+	apply(text: string): string {
+		if (Buffer.byteLength(text, "utf-8") <= this.maxBytes) return text;
+		// Approximate: slice by char count, then walk back any partial UTF-8
+		// sequence to keep byte-length <= maxBytes.
+		let slice = text.slice(0, this.maxBytes);
+		while (Buffer.byteLength(slice, "utf-8") > this.maxBytes) {
+			slice = slice.slice(0, slice.length - 1);
+		}
+		if (this.snapToNewline) {
+			const lastNewline = slice.lastIndexOf("\n");
+			if (lastNewline >= 0) return slice.slice(0, lastNewline);
+		}
+		return slice;
+	}
+}

package/src/runtime/compact-stages/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Barrel re-exports for the compact-stages module.
+ *
+ * Callers import from `../../runtime/compact-stages/index.ts` (or just
+ * `../../runtime/compact-stages/`) rather than reaching into individual
+ * stage files, so internal refactors do not break the public surface.
+ */
+export { AnsiStripStage, ANSI_STRIP_STAGE } from "./ansi-strip-stage.ts";
+export { BlankCollapseStage, BLANK_COLLAPSE_STAGE } from "./blank-collapse-stage.ts";
+export { DeduplicateStage, DEDUPLICATE_STAGE } from "./deduplicate-stage.ts";
+export { TruncationStage, type TruncationMarkerConfig } from "./truncation-stage.ts";
+export { HeadSnapStage, type HeadSnapStageConfig } from "./head-snap-stage.ts";
+export { TailCaptureStage, TAIL_CAPTURE_STREAM_STAGE, type TailCaptureStageConfig } from "./tail-capture-stage.ts";

package/src/runtime/compact-stages/tail-capture-stage.ts

@@ -0,0 +1,72 @@
+/**
+ * TailCaptureStage — keep the last N characters/bytes of the input, prepend
+ * an optional marker when truncation fires.
+ *
+ * Distinct from TruncationStage (head + important-middle + tail, P0-B / P0-A):
+ * this stage is pure tail-capture, used by streaming accumulators that need to
+ * keep the most recent N chars/bytes and drop the oldest. No important-line
+ * preservation, no head — just the tail + optional marker.
+ *
+ * Use cases in pi-crew:
+ *   - `appendBoundedTail` (child-pi.ts) — stdout/stderr streaming accumulator
+ *     with byte cap and a `[pi-crew captured output truncated to last X KiB]`
+ *     marker.
+ *   - `stream-preview.ts` textBuffer — incremental text buffer for the live UI
+ *     preview, char cap, NO marker (the UI shows raw text without a prefix).
+ *
+ * Two cap modes:
+ *   - `maxChars`: character-based cap (UTF-8 safe by definition).
+ *   - `maxBytes`: byte-based cap (legacy, used when memory budget matters
+ *     more than UTF-8 safety). The tail is snapped to the last byte that
+ *     keeps the result ≤ maxBytes to avoid splitting a multi-byte sequence.
+ */
+import type { ICompactStage } from "../compact-pipeline.ts";
+
+export interface TailCaptureStageConfig {
+	/** Character cap (UTF-8 safe). Mutually exclusive with maxBytes. */
+	maxChars?: number;
+	/** Byte cap (legacy, used by streaming accumulators). Mutually exclusive with maxChars. */
+	maxBytes?: number;
+	/** Marker prepended (with a newline separator) when truncation fires. Empty string = no marker. */
+	marker?: string;
+	/** Optional explicit id; defaults to "tail-capture" (or "tail-capture-stream" if maxBytes mode). */
+	id?: string;
+}
+
+export class TailCaptureStage implements ICompactStage {
+	readonly id: string;
+	private readonly maxChars: number | undefined;
+	private readonly maxBytes: number | undefined;
+	private readonly marker: string;
+	constructor(config: TailCaptureStageConfig) {
+		const hasChars = typeof config.maxChars === "number";
+		const hasBytes = typeof config.maxBytes === "number";
+		if (hasChars === hasBytes) {
+			throw new Error(`TailCaptureStage requires exactly one of maxChars or maxBytes (got chars=${config.maxChars} bytes=${config.maxBytes})`);
+		}
+		if (hasChars && (config.maxChars as number) <= 0) throw new Error(`TailCaptureStage: maxChars must be > 0, got ${config.maxChars}`);
+		if (hasBytes && (config.maxBytes as number) <= 0) throw new Error(`TailCaptureStage: maxBytes must be > 0, got ${config.maxBytes}`);
+		this.maxChars = config.maxChars;
+		this.maxBytes = config.maxBytes;
+		this.marker = config.marker ?? "";
+		this.id = config.id ?? (hasBytes ? "tail-capture" : "tail-capture");
+	}
+	apply(text: string): string {
+		if (this.maxBytes !== undefined) {
+			// Byte cap mode — snap tail to a UTF-8 char boundary so the result
+			// never contains a partial multi-byte sequence.
+			if (Buffer.byteLength(text, "utf-8") <= this.maxBytes) return text;
+			let tail = text.slice(Math.max(0, text.length - this.maxBytes));
+			while (Buffer.byteLength(tail, "utf-8") > this.maxBytes) tail = tail.slice(1024);
+			return this.marker ? `${this.marker}\n${tail}` : tail;
+		}
+		// Char cap mode.
+		const max = this.maxChars as number;
+		if (text.length <= max) return text;
+		const tail = text.slice(text.length - max);
+		return this.marker ? `${this.marker}\n${tail}` : tail;
+	}
+}
+
+/** Singleton: char-cap tail capture with no marker (for `stream-preview.ts` textBuffer). */
+export const TAIL_CAPTURE_STREAM_STAGE = new TailCaptureStage({ maxChars: 16_384, id: "tail-capture-stream" });

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

@@ -0,0 +1,71 @@
+/**
+ * TruncationStage — head(75%) + important-middle + tail(25%) compression.
+ *
+ * Wraps the head/tail/important-line split (from P0-B's `important-line-classifier.ts`)
+ * as a pipeline stage so it composes with other stages (ANSI strip, blank
+ * collapse, etc.). When the input is at or below `maxChars`, returns the
+ * input unchanged (idempotent — the pipeline gate then marks this stage as
+ * a no-op).
+ *
+ * Marker wording is parameterized so the SAME stage serves both `compactString`
+ * ("compacted ... chars") and `readIfSmall` ("truncated ... chars") with
+ * their distinct separators. Defaults match `compactString`'s pre-P0-A output
+ * exactly so that callers that do not opt into additional stages get
+ * bit-identical output (L4 backward-compat safety).
+ */
+import type { ICompactStage } from "../compact-pipeline.ts";
+import { splitWithImportantLines } from "../important-line-classifier.ts";
+
+export interface TruncationMarkerConfig {
+	/** "compacted" (compactString default) or "truncated" (readIfSmall default). */
+	verb: "compacted" | "truncated";
+	/** Unit reported in the marker. Both callers currently use "chars" post-Sprint 1. */
+	unit: "chars" | "bytes";
+	/** Newline(s) between `head` and the marker line. compactString uses "\n"; readIfSmall uses "\n\n". */
+	headSeparator: string;
+	/** Newline(s) between the marker (or joined important lines) and `tail`. Both callers use "\n". */
+	tailSeparator: string;
+}
+
+const DEFAULT_MARKER: TruncationMarkerConfig = {
+	verb: "compacted",
+	unit: "chars",
+	headSeparator: "\n",
+	tailSeparator: "\n",
+};
+
+export class TruncationStage implements ICompactStage {
+	readonly id = "truncation";
+	private readonly maxChars: number;
+	private readonly preserveImportant: boolean;
+	private readonly marker: TruncationMarkerConfig;
+	constructor(
+		maxChars: number,
+		opts: { preserveImportant?: boolean; marker?: Partial<TruncationMarkerConfig> } = {},
+	) {
+		if (!Number.isFinite(maxChars) || maxChars <= 0) {
+			throw new Error(`TruncationStage: maxChars must be a positive finite number, got ${maxChars}`);
+		}
+		this.maxChars = maxChars;
+		this.preserveImportant = opts.preserveImportant !== false;
+		this.marker = { ...DEFAULT_MARKER, ...(opts.marker ?? {}) };
+	}
+	apply(text: string): string {
+		if (text.length <= this.maxChars) return text;
+		const { head, tail, importantLines, baseDropped } = splitWithImportantLines(text, this.maxChars, {
+			preserveImportant: this.preserveImportant,
+		});
+		let result: string;
+		if (importantLines.length === 0) {
+			result = `${head}${this.marker.headSeparator}...[pi-crew ${this.marker.verb} ${baseDropped} ${this.marker.unit}, head+tail preserved]...${this.marker.tailSeparator}${tail}`;
+		} else {
+			const joined = importantLines.join("\n");
+			const remaining = text.length - head.length - tail.length - joined.length;
+			result = `${head}${this.marker.headSeparator}...[pi-crew ${this.marker.verb} ${baseDropped} ${this.marker.unit}, head+tail + ${importantLines.length} important lines preserved, ${remaining} ${this.marker.unit} remaining dropped]...\n${joined}${this.marker.tailSeparator}${tail}`;
+		}
+		// Defense-in-depth: this stage's own monotonic-shrink invariant. The
+		// pipeline gate is a SECOND line of defense.
+		if (result.length >= text.length) return text;
+		return result;
+	}
+}

package/src/runtime/handoff-manager.ts

@@ -202,6 +202,16 @@ export class HandoffManager {
 		this.cleanupTimer = setInterval(() => {
 			this.cleanupStaleHandoffs();
 		}, this.options.cleanupIntervalMs);
+		// FIX (BG2 hang): without .unref(), the cleanup interval keeps the Node
+		// event loop alive forever — tests that create HandoffManager without
+		// calling dispose() (e.g. chain-runner.test.ts mock helper that does
+		// `return new HandoffManager()`) leak an interval per test, and the
+		// file-level test never completes because Node waits for all handles
+		// to close. .unref() lets the process exit when nothing else is pending
+		// — this is the standard Node.js pattern for background timers.
+		if (typeof this.cleanupTimer.unref === "function") {
+			this.cleanupTimer.unref();
+		}
 	}
 
 	/**