pi-crew 0.9.68 → 0.10.2

package/src/runtime/broker/wait-status-cache.ts

@@ -0,0 +1,157 @@
+/**
+ * wait-status-cache.ts — R10-3: mtime+size-gated load cache for task.waitStatus.
+ *
+ * Problem (docs/refactor-plan.review.md §Round 10, R10-3): the broker's
+ * task.waitStatus poll loop ticks every 200ms per waiter and each tick calls
+ * loadRunManifestById() — stat manifest + stat tasks + (on the state-store
+ * manifest-cache miss, which every write invalidates via generation bump) a
+ * full parse of BOTH manifest.json and tasks.json. With N concurrent waiters
+ * on a busy run that is ~5-10 syscalls × 5 ticks/sec × N.
+ *
+ * Fix: each BROKER INSTANCE holds one WaitStatusCache (Map keyed by runId —
+ * the broker serves a single cwd). Per tick it stats only manifest.json and
+ * tasks.json (via the exact same path derivation loadRunManifestById uses
+ * internally: createRunPaths → scopeBaseRoot(cwd)); the expensive
+ * loadRunManifestById() is invoked only when mtimeMs or size changed. All
+ * waiters on the broker share the entry, so a never-changing run costs ONE
+ * parse total (initial) instead of N×polls.
+ *
+ * Semantics vs the uncached path:
+ *  - Observable behavior is identical: waiters still poll on the same 200ms
+ *    schedule; they just avoid the parse when nothing changed. A status
+ *    change on disk always lands via an atomic rename (new mtime), so the
+ *    next tick re-parses and wakes the waiter within one poll (mtimeMs on
+ *    Linux/macOS has sub-millisecond precision; on FAT-derived filesystems
+ *    with coarse 1-2s mtime granularity staleness is bounded by that
+ *    granularity — the same tradeoff the state-store manifestCache makes).
+ *  - The actual parse is delegated to loadRunManifestById itself, so all of
+ *    its correctness semantics (Windows stat retry, sentinel retry loop,
+ *    STATE-3 quarantine, validateRunManifestPaths containment/symlink
+ *    checks) still run at every reload boundary. Between reloads we serve
+ *    the cached parse, exactly like the in-store manifestCache does.
+ *  - A run whose files are missing gets a 0/0 stamp; while they stay
+ *    missing, ticks return the cached undefined ("no-manifest" error),
+ *    matching the uncached behavior of re-resolving to undefined.
+ *
+ * Memory: entries are evicted when a run's last broker connection closes
+ * (see crew-broker.ts cleanup) and by a hard FIFO cap, so long-lived
+ * brokers cannot grow the Map without bound across runs.
+ */
+
+import * as fs from "node:fs";
+import { createRunPaths, loadRunManifestById } from "../../state/stores/state-store.ts";
+
+/** Shape returned by loadRunManifestById (derived — no duplicate type imports). */
+type LoadedRun = ReturnType<typeof loadRunManifestById>;
+
+/** Loader seam: defaults to the real loadRunManifestById; tests inject a spy. */
+export type WaitStatusLoader = (cwd: string, runId: string) => LoadedRun;
+
+interface WaitStatusCacheEntry {
+	manifestMtimeMs: number;
+	manifestSize: number;
+	tasksMtimeMs: number;
+	tasksSize: number;
+	loaded: LoadedRun;
+}
+
+/** Hard cap so a pathological broker (many runs, no close events) stays bounded. */
+const WAIT_STATUS_CACHE_MAX = 128;
+
+interface StatStamp {
+	manifestMtimeMs: number;
+	manifestSize: number;
+	tasksMtimeMs: number;
+	tasksSize: number;
+}
+
+/** Stat manifest+tasks; a missing/unstattable file is represented as 0/0. */
+function statStamp(manifestPath: string, tasksPath: string): StatStamp {
+	let manifestMtimeMs = 0;
+	let manifestSize = 0;
+	let tasksMtimeMs = 0;
+	let tasksSize = 0;
+	try {
+		const st = fs.statSync(manifestPath);
+		manifestMtimeMs = st.mtimeMs;
+		manifestSize = st.size;
+	} catch {
+		/* missing or transient — treat as 0/0 */
+	}
+	try {
+		const st = fs.statSync(tasksPath);
+		tasksMtimeMs = st.mtimeMs;
+		tasksSize = st.size;
+	} catch {
+		/* missing or transient — treat as 0/0 */
+	}
+	return { manifestMtimeMs, manifestSize, tasksMtimeMs, tasksSize };
+}
+
+function sameStamp(a: StatStamp, b: StatStamp): boolean {
+	return (
+		a.manifestMtimeMs === b.manifestMtimeMs &&
+		a.manifestSize === b.manifestSize &&
+		a.tasksMtimeMs === b.tasksMtimeMs &&
+		a.tasksSize === b.tasksSize
+	);
+}
+
+export class WaitStatusCache {
+	private readonly entries = new Map<string, WaitStatusCacheEntry>();
+	private readonly loader: WaitStatusLoader;
+	private reloadsValue = 0;
+
+	constructor(options: { loader?: WaitStatusLoader } = {}) {
+		this.loader = options.loader ?? loadRunManifestById;
+	}
+
+	/** Diagnostic: number of times the (expensive) loader has been invoked. */
+	get reloads(): number {
+		return this.reloadsValue;
+	}
+
+	/** Diagnostic: number of cached runs. */
+	get size(): number {
+		return this.entries.size;
+	}
+
+	/**
+	 * Stat-gated load. Fast path (stamp unchanged): 2 statSync calls, zero
+	 * parses. Slow path (first sight or changed mtime/size): delegate to the
+	 * loader, then record the POST-load stamp so a concurrent writer that
+	 * landed between our pre-load stat and the parse forces the next tick to
+	 * reload instead of serving a stale entry.
+	 */
+	load(cwd: string, runId: string): LoadedRun {
+		// Same path derivation as resolveRunStateRoot inside
+		// loadRunManifestById (scopeBaseRoot(cwd) + runs subdir + contained
+		// runId) — createRunPaths exposes exactly that derivation publicly.
+		const paths = createRunPaths(cwd, runId);
+		const before = statStamp(paths.manifestPath, paths.tasksPath);
+		const cached = this.entries.get(runId);
+		if (cached && sameStamp(cached, before)) {
+			return cached.loaded;
+		}
+		const loaded = this.loader(cwd, runId);
+		this.reloadsValue += 1;
+		const after = statStamp(paths.manifestPath, paths.tasksPath);
+		if (this.entries.size >= WAIT_STATUS_CACHE_MAX && !this.entries.has(runId)) {
+			// Map preserves insertion order — evict the oldest entry.
+			const oldest = this.entries.keys().next().value;
+			if (oldest !== undefined) this.entries.delete(oldest);
+		}
+		this.entries.set(runId, { ...after, loaded });
+		return loaded;
+	}
+
+	/** Evict one run's entry (called when its last broker connection closes). */
+	delete(runId: string): void {
+		this.entries.delete(runId);
+	}
+
+	/** Drop everything (tests / broker stop). */
+	clear(): void {
+		this.entries.clear();
+	}
+}

package/src/runtime/budget-enforcement.ts

@@ -0,0 +1,281 @@
+/**
+ * Per-task run budget enforcement for the team-run scheduler loop.
+ *
+ * Extracted from team-runner.ts (2026-08, Phase 2.6 maintainability split —
+ * CORE-4 extraction 7 + the RT-NEW-2 terminaliseRunWithDrain/drainPendingUnits
+ * cluster it depends on). Pure code motion: checkPerTaskBudget /
+ * PerTaskBudgetCheckResult / DrainOutcome / drainPendingUnits /
+ * terminaliseRunWithDrain / enforceRunBudget moved verbatim.
+ *
+ * drainPendingUnits + terminaliseRunWithDrain land here (not a separate
+ * shared file) so budget-enforcement.ts stays self-contained and the
+ * team-runner.ts ↔ budget-enforcement.ts import direction stays one-way
+ * (team-runner imports from here; this module never imports from
+ * team-runner.ts — checkPerTaskBudget was moved here for exactly that
+ * reason: enforceRunBudget calls it, and importing it back from
+ * team-runner.ts would create a cycle).
+ */
+import { flushPendingAtomicWrites } from "../state/atomic-write.ts";
+import { withRunLock } from "../state/coordination/locks.ts";
+import { appendEventAsync } from "../state/event-log/event-log.ts";
+import { loadRunManifestById, saveRunManifestAsync, saveRunTasksAsync, updateRunStatus } from "../state/stores/state-store.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { aggregateUsage, formatTokens } from "../state/usage.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import { saveCrewAgents } from "./crew-agent-records.ts";
+import { cancelNonTerminalTasks, markBlocked } from "./dispatch-batch.ts";
+import { isNonTerminalTaskStatus, mergeTaskUpdatesPreservingTerminal } from "./merge-gate.ts";
+import type { SchedulerContext, SchedulerDecision } from "./scheduler-context.ts";
+import { recordsForMaterializedTasks } from "./task-display.ts";
+import { mergeArtifacts } from "./team-runner-artifacts.ts";
+
+/**
+ * Result of a per-task budget check against cumulative run usage.
+ */
+export interface PerTaskBudgetCheckResult {
+	/** Whether the abort threshold was exceeded. */
+	abort: boolean;
+	/** Whether the warning threshold was exceeded. */
+	warning: boolean;
+	/** IDs of tasks that exceeded their fair share (>50% of remaining budget). */
+	fairShareViolators: string[];
+	/** Total tokens used so far. */
+	totalUsed: number;
+}
+
+/**
+ * Check cumulative token usage against per-task budget thresholds.
+ * Returns a structured result — callers decide how to act (warn vs abort).
+ *
+ * Exported for unit testing.
+ */
+export function checkPerTaskBudget(
+	tasks: TeamTaskState[],
+	budgetTotal: number,
+	budgetWarning: number,
+	budgetAbort: number,
+	fairShareFraction = 0.5,
+): PerTaskBudgetCheckResult {
+	const usage = aggregateUsage(tasks);
+	const totalUsed = (usage?.input ?? 0) + (usage?.output ?? 0) + (usage?.cacheWrite ?? 0);
+	const abort = totalUsed >= budgetAbort * budgetTotal;
+	const warning = !abort && totalUsed >= budgetWarning * budgetTotal;
+	// Fair share threshold based on TOTAL budget, not remaining budget.
+	// This ensures a task that consumed 60% of total budget is flagged even
+	// if only 40% remains (40% * 50% = 20% threshold would miss the 60% usage).
+	const fairShareThreshold = budgetTotal * fairShareFraction;
+	const fairShareViolators: string[] = [];
+	for (const task of tasks) {
+		if (!task.usage) continue;
+		const taskTotal = (task.usage.input ?? 0) + (task.usage.output ?? 0) + (task.usage.cacheWrite ?? 0);
+		// Only flag tasks that individually consumed a significant portion of the
+		// budget (>10% of total) AND exceeded the fair share threshold.
+		if (fairShareThreshold > 0 && taskTotal > fairShareThreshold && taskTotal > budgetTotal * 0.1) {
+			fairShareViolators.push(task.id);
+		}
+	}
+	return { abort, warning, fairShareViolators, totalUsed };
+}
+
+/**
+ * Drain in-flight dispatch units (pendingUnits) by aborting the run-scoped
+ * controller and awaiting all settled promises before clearing the map.
+ *
+ * CORE-1 fix: without this, every early-return path inside the main while
+ * loop would abandon pendingUnits — leaving zombie child processes running
+ * with no one listening for their results.
+ *
+ * Exported so unit tests can exercise it directly.
+ */
+/** Settled outcome of a single in-flight dispatch unit promise (returned by drainPendingUnits). */
+export type DrainOutcome = PromiseSettledResult<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }>;
+
+export async function drainPendingUnits<
+	T extends { taskIds: string[]; promise: Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> },
+>(pendingUnits: Map<string, T>, controller?: AbortController): Promise<DrainOutcome[]> {
+	if (pendingUnits.size === 0) return [];
+	controller?.abort();
+	const outcomes = await Promise.allSettled([...pendingUnits.values()].map((p) => p.promise));
+	pendingUnits.clear();
+	return outcomes;
+}
+
+/**
+ * RT-NEW-2: terminalise a run as "failed" while draining in-flight dispatch
+ * units FIRST and merging their settled results under the run lock.
+ *
+ * Extracted verbatim from handleFailedTask (the FIXED reference) so every
+ * abort path behaves identically: drain pendingUnits (abort controller +
+ * await allSettled + clear), merge fulfilled outcomes into manifest/tasks
+ * under withRunLock (flushPendingAtomicWrites + loadRunManifestById +
+ * mergeArtifacts + mergeTaskUpdatesPreservingTerminal + save both), cancel
+ * (not skip) non-settled in-flight tasks so team resume can re-queue them,
+ * then markBlocked the remaining never-dispatched queued tasks.
+ *
+ * Previously enforceRunBudget skipped the drain+merge and called
+ * markBlocked directly — in-flight tasks (still "queued" in ctx.tasks since
+ * streaming dispatch never sets "running") were clobbered to "skipped",
+ * which team resume never re-queues → permanent work loss.
+ */
+export async function terminaliseRunWithDrain(
+	ctx: SchedulerContext,
+	opts: { cancelMessage: string; blockedMessage: string; failedReason: string },
+): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
+	// Ever-dispatched tasks (monotonic set populated at dispatch). Using this
+	// instead of a pendingUnits snapshot closes the RT-NEW-2 race where a task
+	// whose unit settled + left pendingUnits before the abort — but whose task
+	// status isn't terminal yet — would otherwise fall through to markBlocked
+	// and be clobbered to "skipped" (observed CI flake: 02_b skipped on
+	// team-runner-budget-abort-inflight across v0.9.59 / cfd68d06 / 12386af2).
+	const inflightTaskIds = ctx.dispatchedTaskIds;
+	const outcomes = await drainPendingUnits(ctx.pendingUnits, ctx.runController);
+	const validResults: { manifest: TeamRunManifest; tasks: TeamTaskState[] }[] = [];
+	for (const outcome of outcomes) {
+		if (outcome.status === "fulfilled") validResults.push(outcome.value);
+	}
+	if (validResults.length > 0) {
+		// Merge under the run lock — same pattern as mergeUnitResult:
+		// flush pending writes, load disk state, merge artifacts + tasks,
+		// save atomically.
+		const mergeResult = await withRunLock(ctx.manifest, async () => {
+			flushPendingAtomicWrites();
+			const disk = loadRunManifestById(ctx.manifest.cwd, ctx.manifest.runId);
+			const diskManifest = disk?.manifest ?? ctx.manifest;
+			const reconciledArtifacts = mergeArtifacts([
+				...diskManifest.artifacts,
+				...validResults.flatMap((item) => item.manifest.artifacts),
+			]);
+			const resultManifest = updateRunStatus(
+				{ ...diskManifest, artifacts: reconciledArtifacts },
+				"running",
+				"Merged in-flight results during failed-task abort.",
+			);
+			const resultTasks = mergeTaskUpdatesPreservingTerminal(disk?.tasks ?? ctx.tasks, validResults);
+			await saveRunManifestAsync(resultManifest);
+			await saveRunTasksAsync(resultManifest, resultTasks);
+			return { resultManifest, resultTasks };
+		});
+		ctx.manifest = mergeResult.resultManifest;
+		ctx.tasks = mergeResult.resultTasks;
+	}
+	// Cancel in-flight tasks that did NOT settle (e.g. rejected promises)
+	// so team resume CAN re-queue them. markBlocked maps queued→skipped,
+	// which resume never re-queues — work would be lost permanently. Only
+	// cancel tasks that are both in-flight AND still non-terminal (settled
+	// tasks with a terminal status are preserved).
+	ctx.tasks = cancelNonTerminalTasks(
+		ctx.tasks,
+		"cancelled",
+		opts.cancelMessage,
+		(task) => inflightTaskIds.has(task.id) && isNonTerminalTaskStatus(task.status),
+	);
+	// Remaining queued tasks (never dispatched) → skipped (original behavior
+	// preserved for downstream tasks not yet in-flight).
+	ctx.tasks = markBlocked(ctx.tasks, opts.blockedMessage);
+	await saveRunTasksAsync(ctx.manifest, ctx.tasks);
+	saveCrewAgents(ctx.manifest, recordsForMaterializedTasks(ctx.manifest, ctx.tasks, ctx.runtimeKind));
+	ctx.manifest = updateRunStatus(ctx.manifest, "failed", opts.failedReason);
+	return { manifest: ctx.manifest, tasks: ctx.tasks };
+}
+
+/**
+ * CORE-4 extraction 7: enforce per-task run budget after each batch merge.
+ *
+ * When `input.budgetTotal` is set (and not unlimited), checks cumulative usage
+ * against warn/abort thresholds and a fair-share heuristic. On abort, marks all
+ * non-terminal tasks blocked, persists the run as failed, and returns a
+ * `{ kind: "return" }` decision so the caller short-circuits the loop.
+ * Otherwise emits `run.budget_warning` / `task.budget_fair_share` events and
+ * returns null (continue).
+ *
+ * Reads `ctx.input` (budget config). Mutates `ctx.tasks` / `ctx.manifest` only
+ * in the abort path. The caller syncs these locals back after the call.
+ *
+ * @param ctx  The scheduler context.
+ * @returns    `{ kind: "return", result }` on budget abort; `null` otherwise.
+ */
+export async function enforceRunBudget(ctx: SchedulerContext): Promise<SchedulerDecision | null> {
+	const input = ctx.input;
+	const tasks = ctx.tasks;
+	const manifest = ctx.manifest;
+	// Per-task budget enforcement: check cumulative usage after each batch merge.
+	// This prevents a single task from consuming 100% of the budget before
+	// abort triggers (the goal-loop only checks at turn boundaries).
+	if (input.budgetTotal !== undefined && input.budgetTotal > 0 && input.budgetUnlimited !== true) {
+		const warnThreshold = input.budgetWarning ?? 0.8;
+		const abortThreshold = input.budgetAbort ?? 0.95;
+		const budgetCheck = checkPerTaskBudget(tasks, input.budgetTotal, warnThreshold, abortThreshold);
+
+		if (budgetCheck.abort) {
+			const message = `Per-task budget abort threshold exceeded: ${formatTokens(budgetCheck.totalUsed)}/${formatTokens(input.budgetTotal)} (${Math.round((budgetCheck.totalUsed / input.budgetTotal) * 100)}%)`;
+			// ROUND 12: console → logInternalError with explicit "warn" severity
+			// (run-termination event — operator channel; default "debug" is gated).
+			logInternalError("team-runner.budget-abort", new Error(message), `runId=${manifest.runId}`, "warn");
+			await appendEventAsync(manifest.eventsPath, {
+				type: "run.budget_abort",
+				runId: manifest.runId,
+				message,
+				data: {
+					budgetTotal: input.budgetTotal,
+					budgetUsed: budgetCheck.totalUsed,
+					threshold: "abort",
+				},
+			});
+			// RT-NEW-2: drain in-flight units + merge settled results before
+			// terminalising, so in-flight tasks become completed/cancelled (not
+			// skipped). Same shared helper handleFailedTask uses. Run-failed
+			// reason stays the budget message.
+			const result = await terminaliseRunWithDrain(ctx, {
+				cancelMessage: `Cancelled by budget abort: ${message}`,
+				blockedMessage: `Budget abort threshold exceeded: ${message}`,
+				failedReason: message,
+			});
+			return { kind: "return", result };
+		}
+
+		if (budgetCheck.warning) {
+			const message = `Per-task budget warning threshold crossed: ${formatTokens(budgetCheck.totalUsed)}/${formatTokens(input.budgetTotal)} (${Math.round((budgetCheck.totalUsed / input.budgetTotal) * 100)}%)`;
+			// ROUND 12: console → logInternalError, explicit "warn" severity.
+			logInternalError("team-runner.budget-warning", new Error(message), `runId=${manifest.runId}`, "warn");
+			await appendEventAsync(manifest.eventsPath, {
+				type: "run.budget_warning",
+				runId: manifest.runId,
+				message,
+				data: {
+					budgetTotal: input.budgetTotal,
+					budgetUsed: budgetCheck.totalUsed,
+					threshold: "warning",
+				},
+			});
+		}
+
+		// Fair-share warning: flag tasks that consumed >50% of remaining budget
+		// without killing them mid-execution.
+		const fairShareAppends: Promise<void>[] = [];
+		for (const violatorId of budgetCheck.fairShareViolators) {
+			const violator = tasks.find((t) => t.id === violatorId);
+			if (!violator) continue;
+			const taskTotal = (violator.usage?.input ?? 0) + (violator.usage?.output ?? 0) + (violator.usage?.cacheWrite ?? 0);
+			const message = `Task '${violatorId}' consumed ${formatTokens(taskTotal)} (${Math.round((taskTotal / input.budgetTotal) * 100)}% of total budget) — exceeds fair share`;
+			// ROUND 12: console → logInternalError, explicit "warn" severity.
+			logInternalError("team-runner.fair-share", new Error(message), `runId=${manifest.runId} taskId=${violatorId}`, "warn");
+			fairShareAppends.push(
+				appendEventAsync(manifest.eventsPath, {
+					type: "task.budget_fair_share",
+					runId: manifest.runId,
+					taskId: violatorId,
+					message,
+					data: {
+						budgetTotal: input.budgetTotal,
+						taskUsage: taskTotal,
+					},
+				}).then(
+					() => undefined,
+					(error) => logInternalError("team-runner.fair-share-event", error, `taskId=${violatorId}`),
+				),
+			);
+		}
+		await Promise.all(fairShareAppends);
+	}
+	return null;
+}

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

@@ -32,6 +32,14 @@ export const MAX_LINE_BUFFER_BYTES = 1024 * 1024; // 1 MB
 /** Maximum characters for assistant text fragments in compacted events. */
 export const MAX_ASSISTANT_TEXT_CHARS = DEFAULT_CHILD_PI.maxAssistantTextChars;
 
+/**
+ * Maximum characters for reasoning (`thinking`) fragments in compacted events,
+ * and the size cap for the thinking parts in the agent view pane / view
+ * session. Reasoning is display-only (never folded into results or artifacts),
+ * so it gets a tighter cap than full assistant text.
+ */
+export const MAX_THINKING_CHARS = 8 * 1024;
+
 /** Maximum characters for tool-result fragments in compacted events. */
 export const MAX_TOOL_RESULT_CHARS = DEFAULT_CHILD_PI.maxToolResultChars;
 

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

@@ -71,8 +71,9 @@ export const BASE_ALLOWLIST: string[] = [
  *   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 (currently UNUSED —
- *      see note at the PI_CREW_PARENT_PID assignment below).
+ *   4. Add PI_CREW_PARENT_PID for the child-side parent-guard (consumed by the
+ *      reactive zombie-scanner + background-runner parent-guard; unused only by
+ *      the pi dist binary — see note at the PI_CREW_PARENT_PID assignment below).
  */
 export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv, model?: string): SpawnOptions {
 	// SECURITY FIX (Issue #1): Validate cwd before passing to spawn.
@@ -137,11 +138,20 @@ export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv, mo
 		cwd: validatedCwd,
 		env: {
 			...filteredEnv,
-			// PI_CREW_PARENT_PID is set so that child pi workers could theoretically
-			// run a parent-guard (parent-guard.ts). However, as of RT-19/RT-2, this
-			// env var has ZERO consumers: child workers are the external `pi` binary
-			// (@earendil-works/pi-coding-agent) which does NOT read
-			// PI_CREW_PARENT_PID or call startParentGuard (grep of Pi dist = 0 matches).
+			// PI_CREW_PARENT_PID is set so child workers can run a parent-guard
+			// (parent-guard.ts). Consumers (NOT dead):
+			//   1. zombie-scanner.ts:185 — reads PI_CREW_PARENT_PID from
+			//      /proc/<pid>/environ (readProcEnviron) to detect orphaned/zombie
+			//      workers whose leader died.
+			//   2. background-runner.ts:615 — startParentGuard(parentPid)
+			//      self-terminates the orchestrator when its own parent dies.
+			//   3. scratchpad-lifecycle.ts:50,166 — propagates the leader pid into
+			//      scratchpad guest env for guest-zombie detection.
+			// The var is unused ONLY by the external `pi` binary
+			// (@earendil-works/pi-coding-agent): it does NOT read PI_CREW_PARENT_PID
+			// or call startParentGuard (grep of Pi dist = 0 matches), so child-pi
+			// workers cannot self-terminate on leader death — they rely on the
+			// reactive zombie scanner (see docs/decisions/2026-08-14-parent-guard-reactive-scanner.md).
 			// The deeper fix (wiring startParentGuard into the pi worker entry point)
 			// is DEFERRED because workers are an external binary pi-crew doesn't control.
 			//
@@ -158,7 +168,7 @@ export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv, mo
 		// 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),
-		// but see the comment above — child pi workers do NOT actually consume it. The
+		// but see the comment above — the pi worker binary does NOT actually consume it. The
 		// parent-guard model would check direct parent liveness via process.kill(pid, 0),
 		// but this is only implemented in background-runner.ts, not in the worker binary.
 		windowsHide: true,
@@ -246,6 +256,7 @@ export interface SpawnContext {
 export function prepareSpawnContext(
 	input: ChildPiRunInput,
 	effectiveTask: string,
+	depthEnv?: NodeJS.ProcessEnv,
 ): { kind: "ready"; ctx: SpawnContext } | { kind: "aborted"; result: ChildPiRunResult } {
 	const built = buildPiWorkerArgs({
 		task: effectiveTask,
@@ -256,6 +267,10 @@ export function prepareSpawnContext(
 		skillPaths: input.skillPaths,
 		role: input.role,
 		thinkingOverride: input.thinkingOverride,
+		// ADR-5 §3: depthOverride is pre-encoded into depthEnv by runChildPi
+		// (parent's record depth as base-env PI_CREW_DEPTH); forward it so the
+		// child env gets parentDepth+1 = the true grandchild depth.
+		env: depthEnv,
 	});
 	// Pass steering file path to child for real-time steer injection
 	if (input.steeringFile) built.env.PI_CREW_STEERING_FILE = input.steeringFile;
@@ -265,6 +280,31 @@ export function prepareSpawnContext(
 	// assertOnlyControlEnvKeys.
 	if (input.runId) built.env.PI_CREW_BROKER_RUN_ID = input.runId;
 	if (input.agentId) built.env.PI_CREW_BROKER_TASK_ID = input.agentId;
+	// WP-2/R2 (ADR-0 item 2 — P0 env plumbing): UNCONDITIONAL for EVERY role,
+	// read-only (reviewer/security-reviewer/explorer/…) included — the
+	// worker-side `ask` tool + mailbox poll must be reachable by exactly the
+	// roles that cannot write files to unblock themselves. Deliberately NOT
+	// scratchpad-gated: the scratchpad gate below excludes read-only roles by
+	// design (S-6), which would leave the ask tool dead-on-arrival there.
+	// Control-namespace keys → pass assertOnlyControlEnvKeys.
+	built.env.PI_CREW_ASK_ENABLED = "1"; // dormant gate (worker conditional registerTool)
+	// T3/R5 (ADR-5 §1): the worker-side `delegate` tool is registered ONLY for
+	// executor-class roles at depth 1 (read-only roles are spawn-denied
+	// server-side anyway — the env gate is UX/dead-weight hygiene, not the
+	// security boundary; broker admission re-checks role+depth from the task
+	// RECORD). Control-namespace key → assertOnlyControlEnvKeys.
+	const childDepth = Number(built.env.PI_CREW_DEPTH ?? "1");
+	if (childDepth <= 1 && (input.role === "executor" || input.role === "test-engineer")) {
+		built.env.PI_CREW_DELEGATE_ENABLED = "1";
+	}
+	// stateRoot from the spawn manifest: ChildPiRunInput threads
+	// manifest.eventsPath unconditionally (child-executor / background-runner)
+	// and the state store pins eventsPath === <stateRoot>/events.jsonl
+	// (DEFAULT_PATHS.state.eventsFile; the invariant is validated by
+	// state-store.ts + manifest-cache.ts) — dirname(eventsPath) IS the manifest
+	// stateRoot. Absent (non-team spawn) → var stays unset and the ask tool
+	// fast-fails with a structured notice instead of hanging.
+	if (input.eventsPath) built.env.PI_CREW_STATE_ROOT = path.dirname(input.eventsPath);
 	// Phase 0 inter-pi broker: inject socket path + token (control-namespace keys,
 	// safe under assertOnlyControlEnvKeys). Only when the parent broker issued
 	// credentials for this run — i.e. the broker is enabled AND this run is
@@ -275,6 +315,17 @@ export function prepareSpawnContext(
 		built.env.PI_CREW_BROKER_TOKEN = input.brokerSpawn.token;
 		// runId/taskId are threaded unconditionally above (I5); nothing to add here.
 	}
+	// WP-9 (R9): the worker self-reporting channel env is UNCONDITIONAL —
+	// previously scratchpad-gated, which excluded read-only roles by design
+	// (S-6) and left them no reporting path. The bounded channel module
+	// (worker-events-channel.ts) rate-limits + schema-tags worker.* appends.
+	// Control-namespace keys → assertOnlyControlEnvKeys. PI_CREW_TASK_ID is
+	// set here when absent so the channel's events carry their task (the
+	// scratchpad block below sets it first when it runs — same value).
+	if (input.eventsPath) {
+		built.env.PI_CREW_EVENTS_PATH = input.eventsPath;
+		if (input.agentId && !built.env.PI_CREW_TASK_ID) built.env.PI_CREW_TASK_ID = input.agentId;
+	}
 	// Phase 1 scratchpad: opt in the persistent Bun-free JS evaluator (execute
 	// tool) for this worker. Gated by role/agent (S-6 read-only roles never;
 	// F6 agent.scratchpad===false kills). All keys are PI_CREW_* control vars →
@@ -290,12 +341,7 @@ export function prepareSpawnContext(
 			// artifactsRoot after F4/S-1).
 			built.env.PI_CREW_ARTIFACTS_ROOT = input.artifactsRoot;
 		}
-		// I5: thread the run's events path so the worker's scratchpad execute
-		// handler can append fire-and-forget metric events (scratchpad.cell /
-		// scratchpad.restored). Optional — absent in non-team contexts.
-		if (input.eventsPath) {
-			built.env.PI_CREW_EVENTS_PATH = input.eventsPath;
-		} // F4/S-1: the RAW (unredacted) snapshot must NEVER land in artifactsRoot —
+		// F4/S-1: the RAW (unredacted) snapshot must NEVER land in artifactsRoot —
 		// point it at a temp dir; the worker reads it then writeArtifact()
 		// (redact+atomic) is the ONLY writer into artifactsRoot.
 		// R3-1: built.tempDir is only created by buildPiWorkerArgs when the agent

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

@@ -11,7 +11,13 @@
 import { logInternalError } from "../../utils/internal-error.ts";
 import { extractText } from "../output/pi-json-output.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 {
+	MAX_ASSISTANT_TEXT_CHARS,
+	MAX_LINE_BUFFER_BYTES,
+	MAX_THINKING_CHARS,
+	MAX_TOOL_INPUT_CHARS,
+	MAX_TOOL_RESULT_CHARS,
+} from "./child-pi-constants.ts";
 import { appendTranscript, compactString, compactValue, flushPendingTranscriptWrites } from "./child-pi-transcript.ts";
 
 function asRecord(value: unknown): Record<string, unknown> | undefined {
@@ -38,6 +44,20 @@ function compactContentPart(part: unknown): unknown | undefined {
 			name: record.name,
 			input: compactValue(typeof record.input === "string" ? compactString(record.input, MAX_TOOL_INPUT_CHARS) : record.input),
 		};
+	// Reasoning is display-only, but the agent view pane renders the FULL
+	// assistant message (AssistantMessageComponent) — without the thinking
+	// parts the pane would look sparse next to a real pi session. Keep them
+	// capped so a long-thinking model cannot balloon the event log.
+	if (record.type === "thinking")
+		return {
+			type: "thinking",
+			thinking:
+				typeof record.thinking === "string"
+					? compactString(record.thinking, MAX_THINKING_CHARS, {
+							preserveImportant: false,
+						})
+					: "",
+		};
 	if (record.type === "toolResult")
 		return {
 			type: "toolResult",