pi-crew 0.9.68 → 0.10.2

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

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { atomicWriteJson, atomicWriteJsonCoalesced, flushPendingAtomicWrites, readJsonFile } from "../state/atomic-write.ts";
@@ -143,25 +144,79 @@ function removeStaleAgentsLock(lockPath: string, staleMs: number): boolean {
 		}
 		fs.rmSync(lockPath, { force: true });
 		return true;
-	} catch {
+	} catch (error) {
+		// R17-B1 (HIGH): a bare catch here swallowed parse/stat/rm failures, so the
+		// root cause became invisible after withAgentsLock's 60s "locked" error.
+		logInternalError("crew-agents.remove-stale-lock", error, `lockPath=${lockPath}`, "warn");
 		return false;
 	}
 }
 
+/**
+ * Phase 3.1 (decision α): token-guarded release for the agents-record lock,
+ * mirroring `locks.ts` `releaseLock` semantics — only `rmSync` if the stored
+ * token still matches the token we wrote at acquisition. If the lock was
+ * stolen while our critical section ran (stale-steal replaced the file with a
+ * NEW owner's token), releasing must be a no-op — otherwise we would delete
+ * the new holder's lock and break mutual exclusion (the exact race the
+ * token guard in locks.ts fixes). Missing/corrupt files are handled safely:
+ * ENOENT is a no-op (lock already gone); a symlink is never removed (defense
+ * against attacker-planted symlinks, matching locks.ts); an unreadable/
+ * unparseable payload is treated like locks.ts `releaseLock` (stored token
+ * unknown → remove) so a torn write cannot strand the lock forever — the
+ * 30s stale-steal path remains the backstop for genuinely foreign locks.
+ */
+function releaseAgentsLock(filePath: string, token: string): void {
+	try {
+		const stat = fs.lstatSync(filePath);
+		if (stat.isSymbolicLink()) return;
+	} catch {
+		/* ENOENT — lock already gone, nothing to release */
+	}
+	let stored: string | undefined;
+	try {
+		const raw = fs.readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw) as { token?: unknown };
+		stored = typeof parsed.token === "string" ? parsed.token : undefined;
+	} catch {
+		/* unreadable/corrupt — see doc comment: remove, mirroring locks.ts */
+	}
+	if (stored === undefined || stored === token) {
+		try {
+			fs.rmSync(filePath, { force: true });
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code !== "ENOENT") {
+				logInternalError("crew-agents.release-lock", error, `lockPath=${filePath}`, "warn");
+			}
+		}
+	}
+	// stored !== token → lock stolen by another process; do NOT touch.
+}
+
 function withAgentsLock<T>(manifest: TeamRunManifest, fn: () => T): T {
 	const filePath = agentsLockPath(manifest);
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	// Phase 3.1 (decision α): the agents lock file now carries a randomUUID
+	// `token` (format change explicitly accepted by the plan) so the release
+	// below is token-guarded — a stale-steal by another process can no longer
+	// be released by the wrong owner (previously PID-only release). Mirrors
+	// the `writeLockFile` payload shape in locks.ts ({kind,pid,createdAt,token}
+	// minus `kind`). Generated ONCE per call; only the successful O_EXCL write
+	// persists it, so a single token per acquisition is correct.
+	const token = randomUUID();
 	let attempt = 0;
 	const deadline = Date.now() + AGENTS_LOCK_STALE_MS * 2;
 	while (true) {
 		try {
-			const fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o644);
+			const fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
 			try {
 				fs.writeSync(
 					fd,
 					JSON.stringify({
 						pid: process.pid,
 						createdAt: new Date().toISOString(),
+						token,
 					}),
 				);
 			} finally {
@@ -188,11 +243,8 @@ function withAgentsLock<T>(manifest: TeamRunManifest, fn: () => T): T {
 	try {
 		return fn();
 	} finally {
-		try {
-			fs.rmSync(filePath, { force: true });
-		} catch {
-			/* best-effort */
-		}
+		// Phase 3.1 (decision α): unconditional rmSync → token-guarded release.
+		releaseAgentsLock(filePath, token);
 	}
 }
 
@@ -221,7 +273,10 @@ export function readCrewAgents(manifest: TeamRunManifest): CrewAgentRecord[] {
 	// 2.5: ensure intra-process coalesced writes are visible to subsequent
 	// readers in the same process. Cross-process readers still see the file
 	// after at most one coalesce window (250 ms).
-	flushPendingAtomicWrites();
+	// R10-2: scoped flush — readCrewAgents only reads agents.json, so it must
+	// not drain unrelated coalesced writes (tasks.json of live runs, other
+	// runs' agents.json) process-wide on every read.
+	flushPendingAtomicWrites(agentsPath(manifest));
 	try {
 		const records = readJsonFileCoalesced(
 			agentsPath(manifest),
@@ -236,7 +291,13 @@ export function readCrewAgents(manifest: TeamRunManifest): CrewAgentRecord[] {
 			seen.add(r.id);
 			return true;
 		});
-		if (deduped.length !== records.length) {
+		// R10-7: write back only when the corrected list actually differs from
+		// the current content. A filter() only removes entries, so element
+		// identity + length is an exact (and cheap) change check — deep-equal is
+		// unnecessary, and this eliminates the redundant durable write + lock
+		// churn on unchanged reads.
+		const changed = deduped.length !== records.length || records.some((record, index) => record !== deduped[index]);
+		if (changed) {
 			// Schema mismatch or duplicates detected — save corrected state
 			saveCrewAgents(manifest, deduped);
 		}
@@ -264,7 +325,10 @@ export async function readCrewAgentsAsync(manifest: TeamRunManifest): Promise<Cr
 				seen.add(r.id);
 				return true;
 			});
-			if (deduped.length !== raw.length) {
+			// R10-7: write back only on actual change (element identity + length —
+			// see the sync readCrewAgents path for the reasoning).
+			const changed = deduped.length !== raw.length || raw.some((record, index) => record !== deduped[index]);
+			if (changed) {
 				try {
 					saveCrewAgents(manifest, deduped);
 				} catch {
@@ -295,7 +359,7 @@ export async function readCrewAgentsAsync(manifest: TeamRunManifest): Promise<Cr
 export function saveCrewAgents(manifest: TeamRunManifest, records: CrewAgentRecord[]): void {
 	// P0-3: flush any pending coalesced (best-effort) write first so a stale
 	// debounced progress snapshot can't clobber this durable write.
-	flushPendingAgentWrites();
+	flushPendingAgentWrites(manifest, records);
 	withAgentsLock(manifest, () => {
 		fs.mkdirSync(manifest.stateRoot, { recursive: true });
 		const filePath = agentsPath(manifest);
@@ -430,9 +494,14 @@ export function writeCrewAgentStatusCoalesced(manifest: TeamRunManifest, record:
 	});
 }
 
-/** @internal Flush all coalesced agent writes synchronously. Hook into cleanup paths. */
-function flushPendingAgentWrites(): void {
-	flushPendingAtomicWrites();
+/** @internal Flush coalesced agent-record writes synchronously. Hook into cleanup paths. */
+function flushPendingAgentWrites(manifest: TeamRunManifest, records: CrewAgentRecord[]): void {
+	// R10-2: scope the pre-durable-save flush to the agent-record files this
+	// save can be clobbered by (agents.json + the per-task status.json files).
+	// Unrelated coalesced writes (tasks.json, other runs) stay pending on their
+	// own timers — draining them here only added latency to this path.
+	flushPendingAtomicWrites(agentsPath(manifest));
+	for (const record of records) flushPendingAtomicWrites(agentStatusPath(manifest, record.taskId));
 }
 
 export function readCrewAgentStatus(manifest: TeamRunManifest, taskOrAgentId: string): CrewAgentRecord | undefined {
@@ -528,6 +597,10 @@ function nextAgentEventSeq(filePath: string): number {
 }
 
 export function appendCrewAgentEvent(manifest: TeamRunManifest, taskId: string, event: unknown): void {
+	// Mixed-usage guard: if a buffered batch is pending for this task, land it
+	// first so seq allocation stays monotonic and file order matches seq order
+	// (reader cursors advance by seq in file order).
+	flushCrewAgentRecordBuffer(manifest, taskId);
 	ensureAgentStateDir(manifest, taskId);
 	const filePath = agentStateFile(manifest, taskId, "events.jsonl");
 	const seq = nextAgentEventSeq(filePath);
@@ -617,10 +690,182 @@ export function readCrewAgentEventsCursor(
 
 export function appendCrewAgentOutput(manifest: TeamRunManifest, taskId: string, text: string): void {
 	if (!text.trim()) return;
+	// Mixed-usage guard (see appendCrewAgentEvent): land any pending buffered
+	// lines first so buffered/direct lines never interleave out of order.
+	flushCrewAgentRecordBuffer(manifest, taskId);
 	ensureAgentStateDir(manifest, taskId);
 	fs.appendFileSync(agentStateFile(manifest, taskId, "output.log"), `${redactSecretString(text)}\n`, "utf-8");
 }
 
+// ---------------------------------------------------------------------------
+// R10-5 (Wave 2B item 4): per-task batching for the agent-record append sinks.
+// ---------------------------------------------------------------------------
+// child-executor's hot path previously did, PER CHILD EVENT:
+//   appendCrewAgentEvent  -> nextAgentEventSeq (stat + sidecar read) + appendFileSync
+//   appendCrewAgentOutput -> appendFileSync
+// (~4 syscalls/event after the P1-5 path memo, ×N events/task). The buffered
+// variants below collapse adjacent appends into ONE appendFileSync per flush.
+// Flush triggers: task boundary (child-executor finally), process exit / signal,
+// 32-event cap, or the 250ms window timer — whichever comes first.
+//
+// CRASH-WINDOW TRADEOFF (deliberate, documented): buffering widens the SIGKILL
+// loss window for AGENT PROGRESS events to <=250ms (AGENT_RECORD_BUFFER_WINDOW_MS
+// below) instead of 0. Precedent: the event-log coalescer already accepts a
+// documented 50ms loss window for non-terminal task.progress events; agent
+// events.jsonl/output.log lines are the same class of re-derivable progress
+// telemetry — authoritative terminal state lives in tasks.json/agents.json,
+// which stay on their existing durable/coalesced-atomic paths. Durable
+// artifacts (result.md, steering, run-level events.jsonl) are NOT routed
+// through this buffer.
+//
+// SEQUENCE-NUMBER CORRECTNESS: seqs are RESERVED from nextAgentEventSeq() at
+// the first buffered event and incremented in memory, so buffered events can
+// never collide with each other, and the post-flush seq cache + sidecar are
+// updated with the last reserved seq exactly like a direct append. The direct
+// appendCrewAgentEvent()/appendCrewAgentOutput() flush any pending buffer for
+// the task BEFORE appending, so a mixed buffered/direct caller can neither
+// double-allocate a seq nor land a higher-seq line before lower-seq buffered
+// lines. Within pi-crew a task's sinks have exactly one writer at a time
+// (child-executor OR live-executor, never both), so that guard is
+// defense-in-depth, not a load-bearing lock.
+//
+// v0.9.26 lesson (event-log.ts:237,416-425): this buffer is for the AGENT
+// record sinks ONLY — core run events.jsonl appends must NOT be routed
+// through buffered machinery.
+const AGENT_RECORD_BUFFER_MAX_EVENTS = 32;
+const AGENT_RECORD_BUFFER_WINDOW_MS = 250;
+
+interface AgentRecordBuffer {
+	manifest: TeamRunManifest;
+	taskId: string;
+	events: string[];
+	output: string[];
+	lastReservedSeq: number; // 0 = not yet reserved from disk state
+	timer?: NodeJS.Timeout;
+}
+const agentRecordBuffers = new Map<string, AgentRecordBuffer>();
+
+function agentRecordBufferKey(manifest: TeamRunManifest, taskId: string): string {
+	return `${manifest.stateRoot}\0${safeAgentTaskId(taskId)}`;
+}
+
+function flushAgentRecordBuffer(buffer: AgentRecordBuffer): void {
+	const { manifest, taskId } = buffer;
+	if (buffer.timer) {
+		clearTimeout(buffer.timer);
+		buffer.timer = undefined;
+	}
+	if (buffer.events.length > 0) {
+		const filePath = agentStateFile(manifest, taskId, "events.jsonl");
+		try {
+			fs.appendFileSync(filePath, buffer.events.join(""), "utf-8");
+			// Mirror appendCrewAgentEvent's post-append bookkeeping so subsequent
+			// nextAgentEventSeq calls (direct or buffered) see the reserved seqs.
+			const stat = fs.statSync(filePath);
+			setAgentEventSeqCache(filePath, {
+				size: stat.size,
+				mtimeMs: stat.mtimeMs,
+				seq: buffer.lastReservedSeq,
+			});
+			writeSeqToSidecar(filePath, buffer.lastReservedSeq);
+		} catch (error) {
+			// Best-effort progress telemetry: a fs failure here (e.g. run dir
+			// deleted by prune/forget) must not fail the task; drop the batch.
+			logInternalError("crew-agent-records.buffered-events-flush", error, `filePath=${filePath}`);
+		}
+	}
+	if (buffer.output.length > 0) {
+		try {
+			fs.appendFileSync(agentStateFile(manifest, taskId, "output.log"), buffer.output.join(""), "utf-8");
+		} catch (error) {
+			logInternalError("crew-agent-records.buffered-output-flush", error, `taskId=${taskId}`);
+		}
+	}
+	buffer.events.length = 0;
+	buffer.output.length = 0;
+	buffer.lastReservedSeq = 0;
+	agentRecordBuffers.delete(agentRecordBufferKey(manifest, taskId));
+}
+
+/**
+ * Flush any pending buffered agent-record appends for `taskId` synchronously.
+ * Task-boundary hook — child-executor calls this at attempt completion/failure
+ * and process exit so no buffered line outlives the task.
+ */
+export function flushCrewAgentRecordBuffer(manifest: TeamRunManifest, taskId: string): void {
+	const buffer = agentRecordBuffers.get(agentRecordBufferKey(manifest, taskId));
+	if (buffer) flushAgentRecordBuffer(buffer);
+}
+
+/** @internal Flush ALL buffered agent-record writes (process-exit / signal hook). */
+export function flushAllCrewAgentRecordBuffers(): void {
+	for (const buffer of [...agentRecordBuffers.values()]) flushAgentRecordBuffer(buffer);
+}
+
+export function appendCrewAgentEventBuffered(manifest: TeamRunManifest, taskId: string, event: unknown): void {
+	const filePath = agentStateFile(manifest, taskId, "events.jsonl");
+	const key = agentRecordBufferKey(manifest, taskId);
+	let buffer = agentRecordBuffers.get(key);
+	if (!buffer) {
+		buffer = { manifest, taskId, events: [], output: [], lastReservedSeq: 0 };
+		agentRecordBuffers.set(key, buffer);
+	}
+	if (buffer.lastReservedSeq === 0) {
+		// Reserve the next seq ONCE from the on-disk state; further buffered
+		// events increment in memory (no per-event stat/sidecar read).
+		buffer.lastReservedSeq = nextAgentEventSeq(filePath) - 1;
+	}
+	const seq = ++buffer.lastReservedSeq;
+	buffer.events.push(`${JSON.stringify(redactSecrets({ seq, time: new Date().toISOString(), event }))}\n`);
+	scheduleAgentRecordBufferFlush(buffer);
+}
+
+export function appendCrewAgentOutputBuffered(manifest: TeamRunManifest, taskId: string, text: string): void {
+	if (!text.trim()) return;
+	// Ensure the state dir at BUFFER time (the event variant gets this for free
+	// via agentStateFile): fs.appendFileSync at flush time does NOT create parent
+	// dirs, so an output-only task with no events buffered yet would drop its
+	// whole batch on ENOENT. Memoized (ensuredAgentDirs) — one mkdir per task,
+	// not per line — preserving the R10-5 batching win.
+	ensureAgentStateDir(manifest, taskId);
+	const key = agentRecordBufferKey(manifest, taskId);
+	let buffer = agentRecordBuffers.get(key);
+	if (!buffer) {
+		buffer = { manifest, taskId, events: [], output: [], lastReservedSeq: 0 };
+		agentRecordBuffers.set(key, buffer);
+	}
+	buffer.output.push(`${redactSecretString(text)}\n`);
+	scheduleAgentRecordBufferFlush(buffer);
+}
+
+function scheduleAgentRecordBufferFlush(buffer: AgentRecordBuffer): void {
+	// Cap: flush now so buffer memory and the crash window stay bounded.
+	if (buffer.events.length >= AGENT_RECORD_BUFFER_MAX_EVENTS || buffer.output.length >= AGENT_RECORD_BUFFER_MAX_EVENTS) {
+		flushAgentRecordBuffer(buffer);
+		return;
+	}
+	// Window: a REAL (unref'd) timer enforces the <=250ms loss-window bound even
+	// when no further events arrive (lazy check-on-next-append would not).
+	if (!buffer.timer) {
+		buffer.timer = setTimeout(() => {
+			buffer.timer = undefined;
+			flushAgentRecordBuffer(buffer);
+		}, AGENT_RECORD_BUFFER_WINDOW_MS);
+		buffer.timer.unref();
+	}
+}
+
+// Defense-in-depth (mirrors atomic-write.ts): land buffered agent-record lines
+// on normal process exit and best-effort on termination signals.
+/** @internal Test-only: number of pending buffered agent-record batches. */
+export function __test__agentRecordBufferCount(): number {
+	return agentRecordBuffers.size;
+}
+
+process.on("exit", () => flushAllCrewAgentRecordBuffers());
+process.on("SIGTERM", () => setImmediate(() => flushAllCrewAgentRecordBuffers()));
+process.on("SIGINT", () => setImmediate(() => flushAllCrewAgentRecordBuffers()));
+
 export function emptyCrewAgentProgress(): CrewAgentProgress {
 	return { recentTools: [], recentOutput: [], toolCount: 0 };
 }

package/src/runtime/delegate-spawn.ts

@@ -0,0 +1,148 @@
+/**
+ * delegate-spawn.ts — root-side grandchild spawner for governed nesting
+ * (ADR-5 §1/§2/§6, WP-5 step 5).
+ *
+ * The broker's `delegate.request` handler calls this on an admitted request:
+ * a DIRECT `runChildPi` call-site that never touches the global worker
+ * semaphore (the MAJ#3 anti-deadlock precedent generalized — the nested-slot
+ * budget is managed by the broker handler, not here), with `depthOverride`
+ * from the parent task record, namespaced artifacts, and a timeout-driven
+ * soft cancel (`delegate-timeout`).
+ *
+ * Security review round 1 (T3):
+ * - S1#2: the grandchild's ROLE is threaded so role-based tool restrictions
+ *   apply (`--tools`/`--exclude-tools` from role-tools config) — a
+ *   "read-only" explorer/analyst grandchild must actually be read-only
+ *   (ADR-5 §9's serialization exemption depends on it).
+ * - S1#1: the grandchild authenticates under its OWN subId identity
+ *   (grandchild-scoped broker token pre-minted by the handler) — never the
+ *   parent's task token. Identity fields (`agentId: subId`) match.
+ * - S2#1: namespaced artifacts via the `artifactsRoot` input field (the env
+ *   spread never survived the spawn allowlist).
+ * - S2#3: usage roll-up — message_end usage events are accumulated from the
+ *   child's JSON event stream and reported for the parent-task reconciliation.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentConfig } from "../agents/agent-config.ts";
+import { type ChildPiRunResult, runChildPi } from "./child-pi/child-pi.ts";
+
+export interface GrandchildSpawnInput {
+	cwd: string;
+	runId: string;
+	parentTaskId: string;
+	/** Nested-slot holder id (minted by the broker handler). */
+	subId: string;
+	prompt: string;
+	role: string;
+	model?: string;
+	maxTurns?: number;
+	/** Mandatory default 900 (spawn-policy normalized). */
+	timeoutSec: number;
+	/** Parent-task-record depth + 1 (ADR-5 §3). */
+	depthOverride: number;
+	/** Manifest eventsPath — threads PI_CREW_STATE_ROOT so the grandchild's
+	 *  ask tool + scratchpad metrics work (stateRoot = dirname(eventsPath)). */
+	eventsPath?: string;
+	/** Grandchild-scoped broker credentials (S1#1 — NEVER the parent token). */
+	brokerSpawn?: { socketPath: string; token: string };
+	onSpawn?: (pid: number | null) => void;
+}
+
+export interface GrandchildSpawnResult {
+	ok: boolean;
+	/** Fenced-ish result text (caller fences before mailbox delivery). */
+	resultText: string;
+	/** Usage in tokens for roll-up (input+output+cache summed over
+	 *  message_end events); undefined = unattributed. */
+	usageTokens?: number;
+	timedOut?: boolean;
+}
+
+/** Minimal in-memory agent config for a delegate grandchild role. */
+function agentForRole(role: string): AgentConfig {
+	return {
+		name: role,
+		description: `delegate grandchild (${role})`,
+		source: "builtin",
+		filePath: "",
+		systemPrompt: "",
+	};
+}
+
+/** Sum usage tokens from a message_end JSON event record (S2#3 roll-up). */
+export function usageTokensFromEvent(event: unknown): number | undefined {
+	if (!event || typeof event !== "object" || Array.isArray(event)) return undefined;
+	const record = event as { type?: unknown; usage?: unknown; message?: { usage?: unknown } };
+	if (record.type !== "message_end") return undefined;
+	const usage = (record.usage ?? record.message?.usage) as Record<string, unknown> | undefined;
+	if (!usage || typeof usage !== "object") return undefined;
+	let total = 0;
+	let seen = false;
+	for (const key of ["input", "output", "cacheRead", "cacheWrite"]) {
+		const value = usage[key];
+		if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+			total += value;
+			seen = true;
+		}
+	}
+	return seen ? total : undefined;
+}
+
+/** Namespaced artifacts root: artifacts/<runId>/<parentTaskId>/nested/<subId>/ */
+export function grandchildArtifactsRoot(cwd: string, runId: string, parentTaskId: string, subId: string): string {
+	return path.join(cwd, ".crew", "artifacts", runId, parentTaskId, "nested", subId);
+}
+
+export async function spawnDelegateGrandchild(input: GrandchildSpawnInput): Promise<GrandchildSpawnResult> {
+	const artifactsRoot = path.join(input.cwd, ".crew", "artifacts", input.runId, input.parentTaskId, "nested", input.subId);
+	fs.mkdirSync(artifactsRoot, { recursive: true });
+
+	const abort = new AbortController();
+	const timer = setTimeout(() => abort.abort(), input.timeoutSec * 1000);
+	timer.unref?.();
+
+	// S2#3: accumulate grandchild usage from message_end events.
+	let usageTokens: number | undefined;
+	const onJsonEvent = (event: unknown): void => {
+		const tokens = usageTokensFromEvent(event);
+		if (tokens !== undefined) usageTokens = (usageTokens ?? 0) + tokens;
+	};
+
+	try {
+		const result: ChildPiRunResult = await runChildPi({
+			cwd: input.cwd,
+			task: input.prompt,
+			agent: agentForRole(input.role),
+			// S1#2: thread the role so role-based tool restrictions apply.
+			role: input.role,
+			...(input.model !== undefined ? { model: input.model } : {}),
+			...(input.maxTurns !== undefined ? { maxTurns: input.maxTurns } : {}),
+			depthOverride: input.depthOverride,
+			runId: input.runId,
+			// S1#1: the grandchild carries its OWN identity + credentials —
+			// never the parent's task token.
+			agentId: input.subId,
+			...(input.brokerSpawn ? { brokerSpawn: input.brokerSpawn } : {}),
+			...(input.eventsPath ? { eventsPath: input.eventsPath } : {}),
+			// S2#1: namespaced artifacts via the typed field.
+			artifactsRoot,
+			signal: abort.signal,
+			onJsonEvent,
+			onSpawn: input.onSpawn,
+		});
+		const ok = result.exitCode === 0;
+		const text = (result.rawFinalText ?? result.stdout ?? "").trim() || (ok ? "" : result.stderr.trim());
+		return { ok, resultText: text, ...(usageTokens !== undefined ? { usageTokens } : {}) };
+	} catch (error) {
+		const timedOut = abort.signal.aborted;
+		return {
+			ok: false,
+			timedOut,
+			resultText: timedOut ? "[delegate timed out]" : `delegate spawn failed: ${(error as Error).message}`,
+		};
+	} finally {
+		clearTimeout(timer);
+	}
+}

package/src/runtime/detached-run-results.ts

@@ -0,0 +1,90 @@
+/**
+ * Result delivery for runs detached by an agent-view switch.
+ *
+ * Opening an agent view mid-run releases the foreground waiter (see
+ * `detachRunPromise`), so the parent turn settles with a "detached" tool
+ * result and the run keeps executing. Without this module the run's FINAL
+ * result would never reach the conversation: the async notifier only toasts,
+ * and its toast is suppressed while a view session is active (different
+ * session id) or when the run finished before the operator returned to main.
+ *
+ * The registry is in-process; a pending result is parked while an agent view is
+ * open so the worker's own view session never receives the parent's report.
+ */
+import { loadRunManifestById } from "../state/stores/state-store.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { isFinishedRunStatus } from "./process-status.ts";
+
+interface DetachedRun {
+	runId: string;
+	cwd: string;
+}
+
+const detachedRuns = new Map<string, DetachedRun>();
+
+/** Record a run whose foreground waiter was released by a view switch. */
+export function markRunDetached(runId: string, cwd: string): void {
+	if (!runId || !cwd) return;
+	detachedRuns.set(runId, { runId, cwd });
+}
+
+/** Cheap guard for hot paths (render tick): nothing to do when empty. */
+export function hasDetachedRuns(): boolean {
+	return detachedRuns.size > 0;
+}
+
+export function forgetDetachedRun(runId: string): void {
+	detachedRuns.delete(runId);
+}
+
+export function clearDetachedRunsForTest(): void {
+	detachedRuns.clear();
+}
+
+/** Human-readable completion summary for a detached run. */
+export function formatDetachedRunResult(manifest: TeamRunManifest, tasks: TeamTaskState[]): string {
+	const lines = [
+		`pi-crew run ${manifest.status}: ${manifest.runId} (${manifest.team}/${manifest.workflow ?? "none"})`,
+		`Goal: ${manifest.goal}`,
+		"",
+		"This run was detached when you opened an agent view; it finished in the background.",
+	];
+	if (tasks.length > 0) {
+		lines.push("", "Tasks:");
+		for (const task of tasks) {
+			const detail = task.error ? ` — ${task.error}` : "";
+			lines.push(`  • ${task.id} (${task.role ?? "?"}): ${task.status}${detail}`);
+		}
+	}
+	if (manifest.artifactsRoot) lines.push("", `Artifacts: ${manifest.artifactsRoot}`);
+	lines.push(`State: ${manifest.stateRoot}`);
+	return lines.join("\n");
+}
+
+/**
+ * Results of finished detached runs that may be shown in the CURRENT session.
+ * Entries are NOT removed: the caller drops each one with `forgetDetachedRun`
+ * only after the delivery actually succeeded, so a failed send retries on the
+ * next tick instead of losing the run's outcome.
+ *
+ * Gating is by "am I inside an agent view", not by session id: the report must
+ * never land inside a worker's view session, but matching the owner's id is too
+ * brittle (the main session can be replaced/renamed while the view is open, and
+ * the registry is per pi process anyway, so any non-view session here IS the
+ * operator's own).
+ */
+export function peekFinishedDetachedRunResults(options: { inViewSession?: boolean } = {}): { runId: string; text: string }[] {
+	if (detachedRuns.size === 0 || options.inViewSession) return [];
+	const ready: { runId: string; text: string }[] = [];
+	for (const entry of [...detachedRuns.values()]) {
+		const loaded = loadRunManifestById(entry.cwd, entry.runId);
+		if (!loaded) {
+			// Run state vanished (pruned/deleted) — nothing left to report.
+			detachedRuns.delete(entry.runId);
+			continue;
+		}
+		if (!isFinishedRunStatus(loaded.manifest.status)) continue;
+		ready.push({ runId: entry.runId, text: formatDetachedRunResult(loaded.manifest, loaded.tasks) });
+	}
+	return ready;
+}

package/src/runtime/deterministic-ast.ts

@@ -18,6 +18,7 @@
  */
 
 import { parse } from "acorn";
+import { getCrewEnv } from "../config/env-vars.ts";
 
 const NONDETERMINISM_ERROR =
 	"Workflow scripts must be deterministic: Date.now()/Math.random()/new Date() are unavailable. These introduce non-reproducible behavior across runs. Use ctx.vars for cached state, or pass a fixed seed via ctx.setArgs(). To bypass this check (escape hatch), set PI_CREW_DWF_SKIP_DETERMINISM_CHECK=1.";
@@ -57,7 +58,7 @@ export function assertDeterministicScript(script: string): void {
  * (e.g. randomized benchmark scripts).
  */
 export function isDeterminismCheckEnabled(): boolean {
-	return process.env.PI_CREW_DWF_SKIP_DETERMINISM_CHECK !== "1";
+	return getCrewEnv("PI_CREW_DWF_SKIP_DETERMINISM_CHECK") !== "1";
 }
 
 // ---------------------------------------------------------------------------