pi-crew 0.9.26 → 0.9.28

package/src/runtime/child-pi.ts

@@ -31,6 +31,18 @@ const MAX_COMPACT_CONTENT_CHARS = DEFAULT_CHILD_PI.maxCompactContentChars;
 const activeChildProcesses = new Map<number, ChildProcess>();
 const childHardKillTimers = new Map<number, NodeJS.Timeout>();
 
+// Periodic cleanup of dead child process entries to prevent memory leaks.
+// If a child process never emits exit/close (zombie), the entry would leak.
+setInterval(() => {
+	for (const [pid, child] of activeChildProcesses) {
+		try {
+			process.kill(pid, 0); // Throws ESRCH if dead
+		} catch {
+			activeChildProcesses.delete(pid);
+		}
+	}
+}, 60_000).unref();
+
 /**
  * SEC-1: Extract a redacted stderr/stdout excerpt for embedding in lifecycle
  * events and error messages. The in-memory stdout/stderr accumulators receive
@@ -176,6 +188,10 @@ export interface ChildPiLifecycleEvent {
 	stderrExcerpt?: string;
 	/** Timestamp (ISO). */
 	ts: string;
+	/** F12: optional cause for `final_drain` events. `"stdout-quiet"` indicates
+	 *  the drain was triggered by the quiet-window early-exit rather than the
+	 *  default 5 s ceiling. Other drain reasons (default) leave this undefined. */
+	reason?: "stdout-quiet";
 	/** Phase-0 diagnostic (HB-003a): the signal that killed the child (when
 	 *  available). Was previously discarded after building the error string. */
 	signal?: string;
@@ -205,6 +221,9 @@ export interface ChildPiRunInput {
 	onLifecycleEvent?: (event: ChildPiLifecycleEvent) => void;
 	maxDepth?: number;
 	finalDrainMs?: number;
+	/** F12: early-exit the drain when stdout has been silent for this many ms
+	 *  after the final assistant event. Set to ≥ finalDrainMs to disable. */
+	finalDrainQuietMs?: number;
 	hardKillMs?: number;
 	responseTimeoutMs?: number;
 	/** Soft limit on assistant turns — inject steer at this count. */
@@ -219,6 +238,8 @@ export interface ChildPiRunInput {
 	excludeContextBash?: boolean;
 	/** pi session ID for session naming (aligns with pi-crew run ID) */
 	sessionId?: string;
+	/** Path to steering JSONL file for real-time steer injection. */
+	steeringFile?: string;
 	/** Run ID for cleanup tracking */
 	runId?: string;
 	/** Agent ID for cleanup tracking */
@@ -298,6 +319,8 @@ const BASE_ALLOWLIST: string[] = [
 	"PI_TEAMS_PI_BIN",
 	"PI_TEAMS_MOCK_CHILD_PI",
 	"PI_CREW_ALLOW_MOCK",
+	"PI_CREW_MAX_OUTPUT",
+	"PI_CREW_STEERING_FILE",
 ];
 
 export function buildChildPiSpawnOptions(cwd: string, env: NodeJS.ProcessEnv, model?: string): SpawnOptions {
@@ -569,17 +592,22 @@ function compactChildPiLine(line: string): {
 export class ChildPiLineObserver {
 	private buffer = "";
 	private readonly input: ChildPiRunInput;
-	/** RAW (uncapped) assistant-text fragments, accumulated in arrival order.
-	 *  Mirrors {@link parsePiJsonOutput}'s textEvents/finalText extraction but
-	 *  operates on the RAW event stream instead of the 16K-compacted transcript.
-	 *  This is the source of the AUTHORITATIVE result.txt; the transcript stays
-	 *  compacted (memory bound). */
+	/** 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[] = [];
-	/** #7 hardening: bounded digest of intermediate findings. When a worker spends
-	 *  its entire budget on tool calls (never emits a final assistant text),
-	 *  getRawFinalText() returns undefined but this digest captures the last
-	 *  display lines (tool results, stdout fragments) before budget exhaustion.
-	 *  Capped at MAX_INTERMEDIATE_DIGEST_LINES so result artifacts stay bounded. */
+	/** 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) {
@@ -633,12 +661,19 @@ export class ChildPiLineObserver {
 			const rawParsed = JSON.parse(line);
 			const rawTexts = extractText(rawParsed);
 			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);
 				}
 			}
 		} catch {
@@ -663,6 +698,8 @@ export class ChildPiLineObserver {
 			// 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);
 		}
 	}
 }
@@ -855,6 +892,8 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 		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;
 	const spawnSpec = getPiSpawnCommand(built.args);
 	try {
 		return await new Promise<ChildPiRunResult>((resolve) => {
@@ -921,6 +960,10 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 			// handler know a drain timer existed even after clearFinalDrainTimers() ran;
 			// spawnMonotonicMs gives us relative timing to distinguish a race from a crash.
 			let finalDrainArmed = false;
+			// F12: monotonic timestamp of the last stdout JSON event (any event —
+			// we want to know when stdout *stopped*, not when the final assistant
+			// event arrived). Updated on every onJsonEvent dispatch.
+			let lastStdoutActivityMonotonicMs = performance.now();
 			let finalDrainFiredMonotonicMs: number | undefined;
 			const spawnMonotonicMs = performance.now();
 			let finalAssistantEventMonotonicMs: number | undefined;
@@ -1141,10 +1184,80 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 						completeOperation(eventOpId);
 						throw err;
 					}
+					// F12: capture monotonic timestamp BEFORE dispatching — any stdout
+					// JSON event counts as activity. This lets the quiet-window
+					// detection measure "time since last byte of stdout" accurately
+					// regardless of what onJsonEvent does.
+					lastStdoutActivityMonotonicMs = performance.now();
 					input.onJsonEvent?.(event);
 					if (!isFinalAssistantEvent(event) || childExited || settled || finalDrainTimer) return;
 					finalAssistantEventMonotonicMs = performance.now();
 					finalDrainArmed = true; // Phase-0 diagnostic: track that a drain timer was created.
+					// F12: alongside the 5 s ceiling timer, start a polling watcher
+					// that fires the drain early if stdout goes quiet for `quietMs`
+					// after the final assistant event. Heavy children that emit a
+					// stopReason=stop message_end and then sit idle will exit in
+					// ~quietMs (default 800 ms) instead of up to up to 5 s. unref() so
+					// the poller never holds the event loop on shutdown.
+					// NOTE: The polling watcher is NOT explicitly cleared on process exit.
+					// This is safe because: (1) it's unref()'d, so it won't prevent exit;
+					// (2) the `settled || childExited` guard at the top prevents firing
+					// after the child has exited; (3) sending SIGTERM to an already-
+					// exiting process is harmless. The `finalDrainQuietMs` config allows
+					// disabling this behavior (set >= finalDrainMs, e.g., 10000).
+					const quietMs = input.finalDrainQuietMs ?? DEFAULT_CHILD_PI.finalDrainQuietMs;
+					if (quietMs < (input.finalDrainMs ?? DEFAULT_CHILD_PI.finalDrainMs)) {
+						const pollHandle = setInterval(() => {
+							if (settled || childExited) {
+								clearInterval(pollHandle);
+								pollHandle.unref();
+								return;
+							}
+							const sinceLast = performance.now() - lastStdoutActivityMonotonicMs;
+							if (sinceLast >= quietMs) {
+								clearInterval(pollHandle);
+								pollHandle.unref();
+								// Trigger the same drain path as the 5 s timer:
+								// mark forced, fire final_drain lifecycle, SIGTERM.
+								forcedFinalDrain = true;
+								finalDrainFiredMonotonicMs = performance.now();
+								input.onLifecycleEvent?.({
+									type: "final_drain",
+									pid: child.pid,
+									ts: new Date().toISOString(),
+									reason: "stdout-quiet",
+								});
+								try {
+									child.kill(process.platform === "win32" ? undefined : "SIGTERM");
+								} catch (error) {
+									logInternalError("child-pi.quiet-drain-term", error, `pid=${child.pid}`);
+								}
+								// Mark for hard kill fallback so the existing timer is
+								// still reaped if it ever fires later.
+								hardKillTimer = setTimeout(() => {
+									if (settled || childExited) return;
+									try {
+										hardKilled = true;
+										input.onLifecycleEvent?.({
+											type: "hard_kill",
+											pid: child.pid,
+											ts: new Date().toISOString(),
+										});
+										child.kill(process.platform === "win32" ? undefined : "SIGKILL");
+									} catch (error) {
+										logInternalError("child-pi.quiet-drain-hard-kill", error, `pid=${child.pid}`);
+									}
+								}, hardKillMs);
+								hardKillTimer.unref();
+								// Cancel the 5 s ceiling so we don't double-fire.
+								if (finalDrainTimer) {
+									clearTimeout(finalDrainTimer);
+									finalDrainTimer = undefined;
+								}
+							}
+						}, 200);
+						pollHandle.unref();
+					}
 					finalDrainTimer = setTimeout(() => {
 						if (settled || childExited) return;
 						forcedFinalDrain = true;

package/src/runtime/crew-agent-records.ts

@@ -338,7 +338,9 @@ export function upsertCrewAgent(manifest: TeamRunManifest, record: CrewAgentReco
 
 export function writeCrewAgentStatus(manifest: TeamRunManifest, record: CrewAgentRecord): void {
 	ensureAgentStateDir(manifest, record.taskId);
-	atomicWriteJson(agentStatusPath(manifest, record.taskId), redactSecrets(record));
+	// F4: terminal agent status (completed/failed/cancelled/blocked) — keep full
+	// durability so the notifier/dashboard health sees the final state immediately.
+	atomicWriteJson(agentStatusPath(manifest, record.taskId), redactSecrets(record), { durability: "full" });
 }
 
 // 2.5 — coalesced variants. Buffer per-agent record + aggregate writes for
@@ -350,14 +352,19 @@ const AGENT_COALESCE_MS = 250;
 export function saveCrewAgentsCoalesced(manifest: TeamRunManifest, records: CrewAgentRecord[]): void {
 	const filePath = agentsPath(manifest);
 	fs.mkdirSync(manifest.stateRoot, { recursive: true });
-	atomicWriteJsonCoalesced(filePath, redactSecrets(records), AGENT_COALESCE_MS);
+	// F4: progress write — best-effort is safe because the terminal
+	// writeCrewAgentStatus above remains durable and the notifier watches the
+	// events.jsonl independently of these JSON files.
+	atomicWriteJsonCoalesced(filePath, redactSecrets(records), AGENT_COALESCE_MS, { durability: "best-effort" });
 	asyncAgentReaderCache.delete(filePath);
 	for (const record of records) writeCrewAgentStatusCoalesced(manifest, record);
 }
 
 export function writeCrewAgentStatusCoalesced(manifest: TeamRunManifest, record: CrewAgentRecord): void {
 	ensureAgentStateDir(manifest, record.taskId);
-	atomicWriteJsonCoalesced(agentStatusPath(manifest, record.taskId), redactSecrets(record), AGENT_COALESCE_MS);
+	atomicWriteJsonCoalesced(agentStatusPath(manifest, record.taskId), redactSecrets(record), AGENT_COALESCE_MS, {
+		durability: "best-effort",
+	});
 }
 
 /** @internal Flush all coalesced agent writes synchronously. Hook into cleanup paths. */

package/src/runtime/pi-args.ts

@@ -360,6 +360,8 @@ export function buildPiWorkerArgs(input: BuildPiWorkerArgsInput): BuildPiWorkerA
 			PI_TEAMS_DEPTH: String(parentDepth + 1),
 			PI_TEAMS_MAX_DEPTH: String(maxDepth),
 			PI_TEAMS_ROLE: input.agent.name,
+			// maxTokens cap for background workers — prompt-runtime reads this to cap API output
+			...(input.agent.maxTokens ? { PI_CREW_MAX_OUTPUT: String(input.agent.maxTokens) } : {}),
 		},
 		tempDir,
 	};

package/src/runtime/retry-executor.ts

@@ -33,7 +33,10 @@ function asError(error: unknown): Error {
 }
 
 function globToRegex(pattern: string): RegExp {
-	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+	const escaped = pattern
+		.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+		.replace(/\*/g, ".*")
+		.replace(/\?/g, ".");
 	return new RegExp(`^${escaped}$`, "i");
 }
 

package/src/runtime/task-runner/state-helpers.ts

@@ -68,12 +68,19 @@ export function persistSingleTaskUpdate(
 				const latest = loadRunManifestById(manifest.cwd, manifest.runId)?.tasks ?? fallbackTasks;
 				merged = updateTask(latest, taskWithCheckpoint);
 
-				// Re-stat to detect concurrent writes
+				// F2: collapsed from 3 redundant statSync calls into 1. The previous
+				// implementation re-checked mtime twice more after load and before
+				// write, but since the code is synchronous and `loadRunManifestById`
+				// holds no I/O-yield between the load and this stat, those re-checks
+				// always returned the same mtime and added nothing. The one CAS below
+				// remains necessary for best-effort writers (async-notifier,
+				// crash-recovery) that don't acquire the run lock.
 				let currentMtime: number;
 				try {
 					currentMtime = fs.statSync(manifest.tasksPath).mtimeMs;
 				} catch {
-					currentMtime = 0;
+					// Run state deleted (prune/forget) — nothing to persist.
+					return fallbackTasks;
 				}
 
 				if (currentMtime !== baseMtime) {
@@ -82,34 +89,6 @@ export function persistSingleTaskUpdate(
 					continue;
 				}
 
-				// No concurrent writer — check that our merged result is based on the
-				// same base we observed (no intermediate writer between our load and check)
-				let recheckMtime: number;
-				try {
-					recheckMtime = fs.statSync(manifest.tasksPath).mtimeMs;
-				} catch {
-					// Run state deleted (prune/forget) — nothing to persist.
-					return fallbackTasks;
-				}
-				if (recheckMtime !== baseMtime) {
-					baseMtime = recheckMtime;
-					continue;
-				}
-
-				// Final pre-write mtime check to catch any concurrent writer that completed
-				// between the recheck and saveRunTasks
-				let preWriteMtime: number;
-				try {
-					preWriteMtime = fs.statSync(manifest.tasksPath).mtimeMs;
-				} catch {
-					preWriteMtime = 0;
-				}
-				if (preWriteMtime !== baseMtime) {
-					// Another writer committed — retry
-					baseMtime = preWriteMtime;
-					continue;
-				}
-
 				break;
 			}
 

package/src/runtime/task-runner.ts

@@ -449,6 +449,7 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 					runId: manifest.runId,
 					agentId: task.id,
 					artifactsRoot: manifest.artifactsRoot,
+					steeringFile: `${manifest.artifactsRoot}/steering/${task.id}.jsonl`,
 					onSpawn: (pid) => {
 						try {
 							({ task, tasks } = checkpointTask(manifest, tasks, task, "child-spawned", pid));

package/src/runtime/team-runner.ts

@@ -171,14 +171,16 @@ export function checkPerTaskBudget(
 	const totalUsed = (usage?.input ?? 0) + (usage?.output ?? 0) + (usage?.cacheWrite ?? 0);
 	const abort = totalUsed >= budgetAbort * budgetTotal;
 	const warning = !abort && totalUsed >= budgetWarning * budgetTotal;
-	const remainingBudget = Math.max(0, budgetTotal - totalUsed);
-	const fairShareThreshold = remainingBudget * fairShareFraction;
+	// 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 of remaining budget.
+		// budget (>10% of total) AND exceeded the fair share threshold.
 		if (fairShareThreshold > 0 && taskTotal > fairShareThreshold && taskTotal > budgetTotal * 0.1) {
 			fairShareViolators.push(task.id);
 		}