pi-crew 0.9.8 → 0.9.10

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/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)";
+	}
+}

package/src/runtime/custom-tools/irc-tool.ts

@@ -14,7 +14,7 @@
 
 import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "@sinclair/typebox";
-import { listLiveAgents, sendIrcMessage, broadcastIrcMessage } from "../live-agent-manager.ts";
+import { listLiveAgents, sendIrcMessage, broadcastIrcMessage, respondAsBackground } from "../live-agent-manager.ts";
 import type { IrcMessage } from "../live-irc.ts";
 
 const IrcParams = Type.Object({
@@ -37,7 +37,7 @@ const IrcParams = Type.Object({
 	),
 	awaitReply: Type.Optional(
 		Type.Boolean({
-			description: "Wait for a reply (default: true for DM, false for broadcast). Not yet supported — messages are fire-and-forget.",
+			description: "Wait for a prose reply (default: true for DM, false for broadcast). For DMs the recipient receives the message as a non-blocking background turn and its reply is returned to the caller. Broadcast always ignores this flag.",
 		}),
 	),
 });
@@ -64,6 +64,8 @@ interface IrcDetails {
 	delivered?: string[];
 	notFound?: string[];
 	peers?: Array<{ id: string; status: string }>;
+	/** Replies received from recipients (awaitReply DM path). */
+	replies?: Array<{ from: string; text: string }>;
 	error?: string;
 }
 
@@ -130,10 +132,10 @@ function executeList(selfId: string): { content: Array<{ type: "text"; text: str
 	};
 }
 
-function executeSend(
+async function executeSend(
 	selfId: string,
 	params: IrcParams,
-): { content: Array<{ type: "text"; text: string }>; details: IrcDetails } {
+): Promise<{ content: Array<{ type: "text"; text: string }>; details: IrcDetails }> {
 	const to = params.to?.trim();
 	const message = params.message?.trim();
 
@@ -156,23 +158,52 @@ function executeSend(
 		};
 	}
 
+	// awaitReply defaults to true for DMs, false for broadcast. Broadcast
+	// always ignores the flag (fire-and-forget) — there is no single sender
+	// to receive a correlated reply from.
+	const isBroadcast = to === "all";
+	const wantsReply = !isBroadcast && (params.awaitReply ?? true);
+
 	const ircMessage: IrcMessage = {
 		from: selfId,
 		to,
 		content: message,
 		timestamp: new Date().toISOString(),
-		awaitReply: params.awaitReply,
+		awaitReply: wantsReply,
 	};
 
 	const notFound: string[] = [];
 	const delivered: string[] = [];
+	const replies: Array<{ from: string; text: string }> = [];
 
 	try {
-		if (to === "all") {
+		if (isBroadcast) {
+			// Broadcast: always fire-and-forget regardless of awaitReply.
 			const recipients = broadcastIrcMessage(selfId, ircMessage);
 			delivered.push(...recipients);
+		} else if (wantsReply) {
+			// DM with reply: use the non-blocking side-channel.
+			const agents = listLiveAgents();
+			const target = agents.find((a) => a.agentId === to);
+			if (!target || (target.status !== "running" && target.status !== "queued")) {
+				notFound.push(to);
+			} else {
+				const result = await respondAsBackground(to, selfId, message, { awaitReply: true });
+				if (result.ok) {
+					delivered.push(to);
+					if (result.replyContent) replies.push({ from: to, text: result.replyContent });
+				} else if (result.timedOut) {
+					// Message was delivered (non-blocking), but no reply in time.
+					delivered.push(to);
+					replies.push({ from: to, text: `(no reply — timed out)` });
+				} else {
+					// Delivery channel unavailable or cancelled.
+					if (result.error === "cancelled") delivered.push(to);
+					else notFound.push(to);
+				}
+			}
 		} else {
-			// DM to specific agent
+			// DM fire-and-forget (awaitReply explicitly false).
 			const agents = listLiveAgents();
 			const target = agents.find((a) => a.agentId === to);
 			if (!target || (target.status !== "running" && target.status !== "queued")) {
@@ -197,6 +228,14 @@ function executeSend(
 	} else {
 		lines.push("No recipients received the message.");
 	}
+	if (replies.length > 0) {
+		lines.push("");
+		lines.push("## Replies");
+		for (const reply of replies) {
+			lines.push(`### ${reply.from}`);
+			lines.push(reply.text);
+		}
+	}
 	if (notFound.length > 0) {
 		lines.push(`Unknown / unavailable peers: ${notFound.join(", ")}`);
 	}
@@ -209,6 +248,7 @@ function executeSend(
 			to,
 			delivered: delivered.length > 0 ? delivered : undefined,
 			notFound: notFound.length > 0 ? notFound : undefined,
+			replies: replies.length > 0 ? replies : undefined,
 		},
 	};
 }

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();
+		}
 	}
 
 	/**