pi-crew 0.9.42 → 0.9.44

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

@@ -0,0 +1,234 @@
+/**
+ * child-pi-spawn.ts — Spawn options + env filtering for child Pi worker processes.
+ *
+ * Extracted from child-pi.ts (H-7 decomposition, step 6). Zero behavior change.
+ *
+ * Responsibilities:
+ *   - BASE_ALLOWLIST: env var names always passed to child workers.
+ *   - buildChildPiSpawnOptions(): pure function that builds SpawnOptions from
+ *     (cwd, env, model). Validates cwd, filters env via allowlist, validates
+ *     NODE_PATH against safe prefixes.
+ *   - assertOnlyControlEnvKeys(): runtime canary that verifies the caller only
+ *     put PI_CREW (prefix) or PI_TEAMS (prefix) keys into the per-call built.env (defense in
+ *     depth against accidental secret leakage).
+ *   - prepareSpawnContext(): pre-spawn helper that builds the spawn command spec
+ *     from buildPiWorkerArgs output, handles the pre-spawn abort check, and
+ *     returns either an immediate-abort result or the spawn context.
+ */
+
+import type { SpawnOptions } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
+import { buildScopedAllowList, sanitizeEnvSecrets } from "../utils/env-filter.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import type { ChildPiRunInput, ChildPiRunResult } from "./child-pi.ts";
+import { buildPiWorkerArgs } from "./pi-args.ts";
+import { getPiSpawnCommand } from "./pi-spawn.ts";
+
+// ── Env allowlist (base set always passed to children) ──────────────────
+// Provider API keys are injected dynamically via buildScopedAllowList() only
+// when a model is assigned to the task (per-task key scoping).
+export const BASE_ALLOWLIST: string[] = [
+	"PATH",
+	"HOME",
+	"USER",
+	"SHELL",
+	"TERM",
+	"LANG",
+	"LC_ALL",
+	"LC_COLLATE",
+	"LC_CTYPE",
+	"LC_MESSAGES",
+	"LC_MONETARY",
+	"LC_NUMERIC",
+	"LC_TIME",
+	"XDG_CONFIG_HOME",
+	"XDG_DATA_HOME",
+	"XDG_CACHE_HOME",
+	"XDG_RUNTIME_DIR",
+	// Windows essentials — see WINDOWS_ESSENTIAL_ENV_VARS (src/utils/env-allowlist.ts).
+	...WINDOWS_ESSENTIAL_ENV_VARS,
+	"NVM_BIN",
+	"NVM_DIR",
+	"NVM_INC",
+	"NODE_DISABLE_COLORS",
+	"NODE_EXTRA_CA_CERTS",
+	"NPM_CONFIG_REGISTRY",
+	"NPM_CONFIG_USERCONFIG",
+	"NPM_CONFIG_GLOBALCONFIG",
+	"PI_CREW_DEPTH",
+];
+
+/**
+ * Build the SpawnOptions for a child Pi worker process. Pure function — does
+ * not call spawn() itself; the caller does that.
+ *
+ * Responsibilities:
+ *   1. Validate cwd (realpath + isDirectory) — fall back to lexical path on ENOENT.
+ *   2. Filter env vars to the allowlist (model-aware provider key scoping).
+ *   3. Validate NODE_PATH against safe prefixes (/opt, /lib, /usr, /home).
+ *   4. Add PI_CREW_PARENT_PID for the child-side parent-guard.
+ */
+export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv, model?: string): SpawnOptions {
+	// SECURITY FIX (Issue #1): Validate cwd before passing to spawn.
+	// If cwd comes from an untrusted source (user input, workspace config), a malicious cwd
+	// could cause the child process to operate in an attacker-controlled directory,
+	// enabling path traversal attacks, unintended file access, or exposure of sensitive paths.
+	// Use realpathSync to resolve any symlinks and verify the path exists and is a directory.
+	let validatedCwd: string;
+	try {
+		validatedCwd = fs.realpathSync(cwd);
+		const stats = fs.statSync(validatedCwd);
+		if (!stats.isDirectory()) {
+			throw new Error(`cwd is not a directory: ${cwd}`);
+		}
+	} catch (error) {
+		// If cwd doesn't exist (ENOENT) and isn't a security concern, fall back
+		// to the lexical path. The child process will create the directory if
+		// needed. Throwing would break tests/callers that pass not-yet-existing
+		// paths and isn't a security issue for the env-filtering behavior this
+		// function is primarily about.
+		if ((error as NodeJS.ErrnoException).code === "ENOENT" && error instanceof Error && error.message.includes("ENOENT")) {
+			validatedCwd = path.resolve(cwd);
+		} else {
+			throw new Error(`Invalid cwd: ${cwd} — ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
+	// Filter out env vars whose keys match secret patterns to avoid leaking credentials to child processes.
+	// IMPORTANT: preserve model provider API keys — they are needed by the child Pi to call the LLM.
+	// Also preserve essential non-secret vars (PATH, HOME, USER, etc.) so the child process can function.
+	// Bug #12 fix: essential env vars (PATH, HOME, etc.) are always preserved so child can find npm/node.
+	//
+	// PER-TASK KEY SCOPING: when a model is provided, only the env keys for that
+	// provider are injected (via buildScopedAllowList). When no model is given,
+	// only BASE_ALLOWLIST system vars pass through — no provider keys leak.
+	const allowList = model ? buildScopedAllowList(BASE_ALLOWLIST, [model]) : BASE_ALLOWLIST;
+	const filteredEnv = sanitizeEnvSecrets(env, { allowList });
+	// FIX: Removed delete workarounds — with explicit allowlist, these vars
+	// are no longer auto-leaked. The wildcard approach was fragile.
+
+	// SECURITY FIX (Issue #1): Validate NODE_PATH to ensure it only contains standard
+	// system locations or legitimate user paths (NVM). NODE_PATH can reveal user
+	// environment information and could theoretically be exploited if it contains
+	// untrusted entries. Only allow paths under standard system directories
+	// (/opt, /lib, /usr) or NVM paths under /home/<user>/.nvm/... which are legitimate
+	// for Node.js module loading in user environments.
+	if (filteredEnv.NODE_PATH) {
+		const validPrefixes = ["/opt/", "/lib/", "/usr/local/", "/usr/", "/home/"];
+		const validPaths = filteredEnv.NODE_PATH.split(":").filter((p) => {
+			return validPrefixes.some((prefix) => p.startsWith(prefix));
+		});
+		if (validPaths.length > 0) {
+			filteredEnv.NODE_PATH = validPaths.join(":");
+		} else {
+			// No standard paths found — remove NODE_PATH entirely to avoid
+			// passing user-specific paths that could reveal environment info.
+			delete filteredEnv.NODE_PATH;
+		}
+	}
+
+	return {
+		cwd: validatedCwd,
+		env: { ...filteredEnv, PI_CREW_PARENT_PID: String(process.pid) },
+		stdio: ["ignore", "pipe", "pipe"], // stdin=ignore: child doesn't wait for input; task comes via CLI args
+		detached: process.platform !== "win32",
+		setsid: true,
+		// NOTE: setsid creates a new session; the child process becomes the session leader
+		// and its parent becomes that session leader (still the team-runner in the same
+		// process group). PI_CREW_PARENT_PID is set before spawn using process.pid (team-runner).
+		// The parent-guard in the child checks direct parent liveness via process.kill(pid, 0) —
+		// it does NOT follow the lineage beyond the direct parent. If the team-runner's parent
+		// (the original pi session) dies, the team-runner becomes an orphan but the child still
+		// sees its direct parent (team-runner) as alive. This is correct for the parent-guard model.
+		windowsHide: true,
+	} as SpawnOptions;
+}
+
+/**
+ * Throw if `built.env` contains keys outside the PI_CREW_ (prefix) / PI_TEAMS_ (prefix) namespaces.
+ * Called right before spawn() as a runtime canary — protects against future
+ * regressions where someone accidentally adds a secret key to built.env.
+ */
+export function assertOnlyControlEnvKeys(builtEnv: Record<string, string | undefined>): void {
+	// Verifies built.env (the per-call env we add on top of process.env) only
+	// contains PI_CREW_*/PI_TEAMS_* control keys. built.env does NOT include
+	// process.env values — those are merged separately via spread and filtered
+	// by the allowlist in buildChildPiSpawnOptions. This assertion guards
+	// against accidental additions to built.env leaking secrets to children.
+	for (const key of Object.keys(builtEnv)) {
+		if (!key.startsWith("PI_CREW_") && !key.startsWith("PI_TEAMS_")) {
+			throw new Error(
+				`SECURITY: built.env contains unexpected key "${key}"; expected only PI_CREW_* or PI_TEAMS_* execution-control vars`,
+			);
+		}
+	}
+}
+
+/** What the spawn site needs to start the child process. */
+export interface SpawnContext {
+	/** The command + args returned by getPiSpawnCommand. */
+	spawnSpec: ReturnType<typeof getPiSpawnCommand>;
+	/** The merged env (process.env + built.env) to pass to spawn(). */
+	mergedEnv: NodeJS.ProcessEnv;
+	/** Temp dir created by buildPiWorkerArgs (caller must clean up after spawn). */
+	tempDir: string | undefined;
+	/** The per-call built.env (control vars only) — for security canary assertions. */
+	builtEnv: Record<string, string | undefined>;
+}
+
+/**
+ * Build the spawn context for a child Pi run: calls buildPiWorkerArgs,
+ * attaches PI_CREW_STEERING_FILE if a steering file is configured, then returns
+ * the spawn command spec + merged env. Does NOT spawn.
+ *
+ * If the parent AbortSignal has already fired, returns an immediate-abort
+ * ChildPiRunResult instead — spawn is then skipped entirely (saves resources).
+ */
+export function prepareSpawnContext(
+	input: ChildPiRunInput,
+	effectiveTask: string,
+): { kind: "ready"; ctx: SpawnContext } | { kind: "aborted"; result: ChildPiRunResult } {
+	const built = buildPiWorkerArgs({
+		task: effectiveTask,
+		agent: input.agent,
+		model: input.model,
+		sessionEnabled: true,
+		maxDepth: input.maxDepth,
+		skillPaths: input.skillPaths,
+		role: input.role,
+	});
+	// Pass steering file path to child for real-time steer injection
+	if (input.steeringFile) built.env.PI_CREW_STEERING_FILE = input.steeringFile;
+	// B5: if the parent already aborted before we spawn, do not start the child
+	// at all. Spawning a doomed process wastes resources, and the abort listener
+	// registered below will not re-fire for an already-aborted signal (so the
+	// child would only be killed later by the response-timeout path). Return a
+	// cancelled-style result immediately.
+	if (input.signal?.aborted) {
+		return {
+			kind: "aborted",
+			result: {
+				exitCode: null,
+				stdout: "",
+				stderr: "",
+				error: "Aborted before spawn (parent AbortSignal already aborted)",
+				aborted: true,
+			},
+		};
+	}
+	const spawnSpec = getPiSpawnCommand(built.args);
+	return {
+		kind: "ready",
+		ctx: {
+			spawnSpec,
+			mergedEnv: { ...process.env, ...built.env },
+			tempDir: built.tempDir,
+			builtEnv: built.env,
+		},
+	};
+}
+
+// Silence unused-import warning for logInternalError if not consumed by future helpers.
+void logInternalError;

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

@@ -0,0 +1,128 @@
+/**
+ * child-pi-steering.ts — Turn-count-based steering controller for child Pi.
+ *
+ * Extracted from child-pi.ts (H-7 decomposition, step 5). Zero behavior change.
+ *
+ * The controller encapsulates the steering state machine:
+ *   - Tracks turn count from `turn_end` events.
+ *   - At `maxTurns`: triggers soft-limit steer (append advisory to steering file).
+ *   - At `maxTurns + graceTurns`: triggers hard abort via killProcessTree.
+ *
+ * The hardAbortInitiated flag prevents the no-response timer from being
+ * restarted after the hard-abort fires (CP-1 fix — see UPGRADE_REVIEW.md).
+ */
+
+import * as fs from "node:fs";
+import { logInternalError } from "../utils/internal-error.ts";
+import { killProcessTree } from "./child-pi-kill.ts";
+
+/** Action emitted by the controller when a `turn_end` event is processed. */
+export type SteeringAction =
+	| { kind: "steer" }
+	| { kind: "hardAbort"; pid: number; child: import("node:child_process").ChildProcess }
+	| { kind: "none" };
+
+/**
+ * State machine for turn-count-based steering.
+ *
+ * Usage:
+ *   const controller = new ChildPiSteeringController(maxTurns, graceTurns);
+ *   // In onJsonEvent, when event.type === "turn_end":
+ *   const action = controller.onTurnEnd(child.pid, child, input.steeringFile);
+ *   if (action.kind === "hardAbort") killProcessTree(action.pid, action.child);
+ *   // In all restartNoResponseTimer sites:
+ *   if (!controller.isHardAbortInitiated()) restartNoResponseTimer();
+ */
+export class ChildPiSteeringController {
+	private turnCount = 0;
+	private softLimitReached = false;
+	private hardAbortInitiatedFlag = false;
+	private readonly maxTurns: number | undefined;
+	private readonly graceTurns: number | undefined;
+
+	constructor(maxTurns: number | undefined, graceTurns: number | undefined) {
+		this.maxTurns = maxTurns;
+		// FIX (Issue #1): Bound graceTurns to prevent the hard abort condition from
+		// never triggering when an arbitrarily large value is passed.
+		this.graceTurns = graceTurns !== undefined && graceTurns > 1000 ? 1000 : graceTurns;
+	}
+
+	/** Called on each `turn_end` event. Returns the action to take (if any). */
+	onTurnEnd(
+		pid: number | undefined,
+		child: import("node:child_process").ChildProcess | undefined,
+		steeringFile: string | undefined,
+	): SteeringAction {
+		this.turnCount += 1;
+		// Soft limit: first turn at or beyond maxTurns → deliver "wrap up" advisory.
+		if (this.maxTurns !== undefined && !this.softLimitReached && this.turnCount >= this.maxTurns) {
+			this.softLimitReached = true;
+			// C8: deliver the "wrap up" advisory by appending to the steering JSONL
+			// file the child polls (PI_CREW_STEERING_FILE). The child is spawned with
+			// stdio:["ignore",...], so child.stdin is null and the old stdin branch was
+			// dead code that only spammed logs on every soft-limit hit. Advisory only —
+			// the hard-abort below at maxTurns + graceTurns is the real enforcement, so
+			// a failed write must NOT kill the worker.
+			if (steeringFile) {
+				try {
+					fs.appendFileSync(
+						steeringFile,
+						JSON.stringify({
+							type: "steer",
+							message: "You have reached your turn limit. Wrap up immediately — provide your final answer now.",
+						}) + "\n",
+						"utf-8",
+					);
+				} catch (err) {
+					logInternalError("child-pi.steer-write-failed", err instanceof Error ? err : new Error(String(err)), `pid=${pid}`);
+				}
+			}
+			return { kind: "steer" };
+		}
+		// Hard abort: turn count reached maxTurns + graceTurns after soft limit was hit.
+		if (this.maxTurns !== undefined && this.softLimitReached && this.turnCount >= this.maxTurns + (this.graceTurns ?? 5)) {
+			// CP-1: escalate to killProcessTree (same as abort/noResponseTimer paths) and
+			// set flag so onJsonEvent stops restarting the no-response timer.
+			this.hardAbortInitiatedFlag = true;
+			if (pid !== undefined && child) {
+				killProcessTree(pid, child);
+				return { kind: "hardAbort", pid, child };
+			}
+			return { kind: "none" };
+		}
+		return { kind: "none" };
+	}
+
+	/**
+	 * Returns true once the hard-abort has been initiated. Callers (onJsonEvent,
+	 * onStdoutLine, stdout/stderr data handlers) should skip restartNoResponseTimer
+	 * when this returns true to avoid masking a SIGTERM-ignoring child.
+	 */
+	isHardAbortInitiated(): boolean {
+		return this.hardAbortInitiatedFlag;
+	}
+
+	/**
+	 * Returns true once the soft-limit steer has been delivered (the worker has
+	 * been notified to wrap up). Used by runChildPi's settle path to distinguish
+	 * a graceful-abort from a parent-abort.
+	 */
+	isSoftLimitReached(): boolean {
+		return this.softLimitReached;
+	}
+
+	/** Current turn count (incremented on each `turn_end` event). */
+	getTurnCount(): number {
+		return this.turnCount;
+	}
+
+	/** Max turns configured (undefined = no limit). */
+	getMaxTurns(): number | undefined {
+		return this.maxTurns;
+	}
+
+	/** Grace turns configured (after soft limit before hard abort). */
+	getGraceTurns(): number | undefined {
+		return this.graceTurns;
+	}
+}

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

@@ -0,0 +1,296 @@
+/**
+ * child-pi-streams.ts — Stdout/stderr line parsing + observation for child Pi.
+ *
+ * Extracted from child-pi.ts (H-7 decomposition, step 4). The code is a verbatim
+ * copy of what lived in child-pi.ts before this extraction — only the imports
+ * were updated to import from child-pi-transcript.ts (compactString,
+ * compactValue, appendTranscript, flushPendingTranscriptWrites) and
+ * child-pi-constants.ts (MAX_*_CHARS, MAX_LINE_BUFFER_BYTES).
+ */
+
+import { logInternalError } from "../utils/internal-error.ts";
+import type { ChildPiRunInput } from "./child-pi.ts";
+import { MAX_ASSISTANT_TEXT_CHARS, MAX_LINE_BUFFER_BYTES, MAX_TOOL_INPUT_CHARS, MAX_TOOL_RESULT_CHARS } from "./child-pi-constants.ts";
+import { appendTranscript, compactString, compactValue, flushPendingTranscriptWrites } from "./child-pi-transcript.ts";
+import { extractText } from "./pi-json-output.ts";
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	return value as Record<string, unknown>;
+}
+
+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, {
+							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;
+}
+
+function compactChildPiEvent(event: unknown): unknown | undefined {
+	const record = asRecord(event);
+	if (!record) return undefined;
+	if (record.type === "message_update") return undefined;
+	if (record.type === "tool_execution_start" || record.type === "tool_execution_end") {
+		return {
+			type: record.type,
+			toolName: record.toolName,
+			args: record.args,
+		};
+	}
+	if (record.type === "tool_result_end" || record.type === "message_end" || record.type === "message") {
+		const message = asRecord(record.message);
+		if (message?.role === "user" || message?.role === "system") return undefined;
+		const content = Array.isArray(message?.content)
+			? message.content.map(compactContentPart).filter((part) => part !== undefined)
+			: undefined;
+		return {
+			type: record.type,
+			...(typeof record.text === "string" ? { text: record.text } : {}),
+			...(message
+				? {
+						message: {
+							role: message.role,
+							...(content ? { content } : {}),
+							usage: message.usage,
+							model: message.model,
+							errorMessage: message.errorMessage,
+							stopReason: message.stopReason,
+						},
+					}
+				: {}),
+			usage: record.usage,
+			model: record.model,
+			provider: record.provider,
+			stopReason: record.stopReason,
+		};
+	}
+	return record.type ? { type: record.type } : undefined;
+}
+
+function displayTextFromCompactEvent(event: unknown): string | undefined {
+	const record = asRecord(event);
+	if (!record) return undefined;
+	if (record.type === "tool_execution_start") {
+		return typeof record.toolName === "string" ? `tool: ${record.toolName}` : "tool started";
+	}
+	if (record.type !== "message" && record.type !== "message_end") return undefined;
+	const message = asRecord(record.message);
+	if (message?.role !== undefined && message.role !== "assistant") return undefined;
+	const content = Array.isArray(message?.content) ? message.content : [];
+	const text = content
+		.flatMap((part) => {
+			const item = asRecord(part);
+			return item?.type === "text" && typeof item.text === "string" ? [item.text] : [];
+		})
+		.join("\n")
+		.trim();
+	return text || (typeof record.text === "string" ? record.text : undefined);
+}
+
+function nonJsonLineResult(line: string): {
+	persistedLine: string;
+	event?: unknown;
+	displayLine?: string;
+	json: boolean;
+} {
+	return { json: false, persistedLine: line, displayLine: line };
+}
+
+function compactChildPiLine(
+	line: string,
+	preParsed?: unknown,
+): {
+	persistedLine: string;
+	event?: unknown;
+	displayLine?: string;
+	json: boolean;
+} {
+	// OPT-PHASE2: when the caller (emitLine) already parsed the line, pass the
+	// result via preParsed to avoid a redundant JSON.parse. Standalone callers
+	// without a preParsed fall back to their own parse+catch (DRY: single
+	// compact+return path for both branches).
+	let parsed: unknown;
+	if (preParsed !== undefined) {
+		parsed = preParsed;
+	} else {
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			return nonJsonLineResult(line);
+		}
+	}
+	const compact = compactChildPiEvent(parsed);
+	return {
+		json: true,
+		event: compact,
+		persistedLine: compact ? JSON.stringify(compact) : "",
+		displayLine: displayTextFromCompactEvent(compact),
+	};
+}
+
+export class ChildPiLineObserver {
+	private buffer = "";
+	private readonly input: ChildPiRunInput;
+	/** F9: bounded ring buffer for RAW assistant-text fragments. Consumers
+	 * (getRawFinalText) only read the last element, but the legacy implementation
+	 * accumulated every fragment unconditionally, which let a verbose/long-running
+	 * worker grow this array linearly with output. We retain the last 2 entries:
+	 * the consumer needs the last; we keep the second-to-last only as a defensive
+	 * fence against a race where a final event arrives just after the consumer
+	 * read (the previous "last" is still the most-recent pre-final text in that
+	 * window). 2 is well below any plausible consumer's "tail-only" need while
+	 * bounding memory. */
+	private static readonly MAX_RAW_TEXT_EVENTS = 2;
+	private readonly rawTextEvents: string[] = [];
+	/** F9: bounded ring buffer for intermediate findings. The downstream digest
+	 * (getIntermediateFindings) slices the last 20, but the array previously grew
+	 * to 1000s of entries. We keep MAX_INTERMEDIATE_DIGEST_LINES + headroom so
+	 * the public API behaviour is preserved (still returns "last 20 lines"). */
+	private static readonly MAX_INTERMEDIATE_FINDINGS = 32;
+	private readonly intermediateFindings: string[] = [];
+
+	constructor(input: ChildPiRunInput) {
+		this.input = input;
+	}
+
+	observe(text: string): void {
+		this.buffer += text;
+		// Cap the buffer to prevent unbounded memory growth when a child process
+		// produces output without newlines (RT-F8). When exceeded, force-flush
+		// the buffer as a single line and log a warning.
+		if (this.buffer.length > MAX_LINE_BUFFER_BYTES) {
+			logInternalError(
+				"child-pi.buffer-overflow",
+				new Error(`Line buffer exceeded ${MAX_LINE_BUFFER_BYTES} bytes; force-flushing`),
+				`bufferLen=${this.buffer.length}`,
+			);
+			const line = this.buffer;
+			this.buffer = "";
+			this.emitLine(line);
+			return;
+		}
+		const lines = this.buffer.split(/\r?\n/);
+		this.buffer = lines.pop() ?? "";
+		for (const line of lines) this.emitLine(line);
+	}
+
+	flush(): Promise<void> {
+		if (this.buffer) {
+			const line = this.buffer;
+			this.buffer = "";
+			this.emitLine(line);
+		}
+		// OPT-06 follow-up: appendTranscript is fire-and-forget async, so the file
+		// may not exist on disk by the time this returns. Drain the module-scoped
+		// transcript batch buffer before resolving so callers that immediately read the
+		// transcript file (e.g. integration tests at phase4-runtime:37/:68/:103
+		// after `await observer.flush()`) see the full content.
+		return flushPendingTranscriptWrites();
+	}
+
+	/** Last non-empty RAW assistant text (mirrors {@link parsePiJsonOutput}'s
+	 *  finalText semantics but uncapped). Undefined when no assistant text was
+	 *  seen by this observer. {@link extractText} already drops empty fragments,
+	 *  so the last entry is the final assistant utterance. */
+	getRawFinalText(): string | undefined {
+		return this.rawTextEvents.length > 0 ? this.rawTextEvents[this.rawTextEvents.length - 1] : undefined;
+	}
+
+	/** #7 hardening: returns a bounded digest of intermediate findings accumulated
+	 *  during the run. This is NOT the final answer — it is a best-effort capture
+	 *  of the last assistant text or tool-result display lines before budget
+	 *  exhaustion. Only populated when getRawFinalText() would return undefined.
+	 *  @param maxChars - maximum total characters to return (default 500). */
+	getIntermediateFindings(maxChars = 500): string {
+		const MAX_INTERMEDIATE_DIGEST_LINES = 20;
+		if (this.intermediateFindings.length === 0) return "";
+		// Take the last N lines and join, then cap.
+		const lines = this.intermediateFindings.slice(-MAX_INTERMEDIATE_DIGEST_LINES);
+		const joined = lines.join("\n");
+		if (joined.length <= maxChars) return joined;
+		// Return the tail within the budget.
+		return joined.slice(-maxChars);
+	}
+
+	private emitLine(line: string): void {
+		if (!line.trim()) return;
+		// OPT-PHASE2: parse the line EXACTLY ONCE. The parsed value feeds both
+		// (a) raw assistant-text extraction for the authoritative result and
+		// (b) compaction for the telemetry transcript — previously each path
+		// called JSON.parse independently (2 parses/line). When the line is not
+		// valid JSON, parsed stays undefined and compactChildPiLine runs its own
+		// catch path to produce the json:false fallback.
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			parsed = undefined;
+		}
+		if (parsed !== undefined) {
+			const rawTexts = extractText(parsed);
+			if (rawTexts.length > 0) {
+				// F9: trim from the front if the push would exceed the cap. Slice's
+				// second arg excludes the index, so this drops the oldest entries
+				// while keeping the freshly pushed tail.
+				this.rawTextEvents.push(...rawTexts);
+				const rawOverflow = this.rawTextEvents.length - ChildPiLineObserver.MAX_RAW_TEXT_EVENTS;
+				if (rawOverflow > 0) this.rawTextEvents.splice(0, rawOverflow);
+				// Also capture raw assistant text as intermediate findings — the last raw
+				// text may be a partial answer before the worker ran out of budget.
+				const last = rawTexts[rawTexts.length - 1];
+				if (last.trim().length > 0) {
+					this.intermediateFindings.push(last.trim());
+					const findingsOverflow = this.intermediateFindings.length - ChildPiLineObserver.MAX_INTERMEDIATE_FINDINGS;
+					if (findingsOverflow > 0) this.intermediateFindings.splice(0, findingsOverflow);
+				}
+			}
+		}
+		// OPT-PHASE2: construct the non-JSON fallback directly when parsing failed,
+		// so a broken line triggers exactly ONE (failed) parse instead of two.
+		const compact = parsed !== undefined ? compactChildPiLine(line, parsed) : nonJsonLineResult(line);
+		if (compact.event !== undefined) {
+			try {
+				this.input.onJsonEvent?.(compact.event);
+			} catch (error) {
+				logInternalError("child-pi.on-json-event", error, `line=${compact.persistedLine ?? compact.displayLine ?? ""}`);
+			}
+		}
+		if (compact.persistedLine) appendTranscript(this.input, compact.persistedLine);
+		if (compact.displayLine?.trim()) {
+			try {
+				this.input.onStdoutLine?.(compact.displayLine);
+			} catch (error) {
+				logInternalError("child-pi.on-stdout-line", error, `line=${compact.displayLine}`);
+			}
+			// #7 hardening: capture display lines (tool results, stdout) as intermediate
+			// findings. This ensures we capture tool output even when no assistant text
+			// is emitted (budget exhausted on tool calls).
+			this.intermediateFindings.push(compact.displayLine!.trim());
+			const findingsOverflow = this.intermediateFindings.length - ChildPiLineObserver.MAX_INTERMEDIATE_FINDINGS;
+			if (findingsOverflow > 0) this.intermediateFindings.splice(0, findingsOverflow);
+		}
+	}
+}