pi-crew 0.9.33 → 0.9.35

package/src/runtime/child-pi.ts

@@ -435,11 +435,75 @@ function appendTranscript(input: ChildPiRunInput, line: string): void {
 	// We skip mkdirSync here for security — adding it would create parent
 	// directories during validation, contradicting the original design where
 	// resolveRealContainedPath validates a pre-existing path.
-	const fd = fs.openSync(safePath, fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW | fs.constants.O_CREAT | fs.constants.O_APPEND, 0o600);
+	// Async optimization: use fire-and-forget async write to avoid blocking the event loop.
+	// The caller does not need to await this — transcript writes are best-effort telemetry.
+	// OPT-06 follow-up: we still track the write promise in a module-scoped Set so
+	// lifecycle boundaries (ChildPiLineObserver.flush, runChildPi settle) can drain
+	// them before returning. Without that drain, callers that immediately read the
+	// transcript file post-flush (e.g. integration tests at phase3-runtime:50 and
+	// phase4-runtime:37/:68/:103) would see ENOENT or empty content because the
+	// async file handle had not yet been opened / flushed.
+	trackTranscriptWrite(safePath, line);
+}
+
+/** Async version of appendTranscript — fire-and-forget for non-blocking writes. */
+async function appendTranscriptAsync(safePath: string, line: string): Promise<void> {
+	const content = `${redactJsonLine(line)}\n`;
 	try {
-		fs.writeSync(fd, `${redactJsonLine(line)}\n`, undefined, "utf-8");
-	} finally {
-		fs.closeSync(fd);
+		// Use async file handle for better performance when many writes occur.
+		// O_NOFOLLOW | O_CREAT | O_APPEND ensures security and atomicity.
+		const fd = await fs.promises.open(
+			safePath,
+			fs.constants.O_WRONLY | fs.constants.O_NOFOLLOW | fs.constants.O_CREAT | fs.constants.O_APPEND,
+			0o600,
+		);
+		try {
+			await fd.write(content, undefined, "utf-8");
+		} finally {
+			await fd.close();
+		}
+	} catch (error) {
+		logInternalError("child-pi.transcript-write-failed", error as Error, `path=${safePath}`);
+	}
+}
+
+/**
+ * Module-scoped set of in-flight transcript-write promises. Each call to
+ * {@link trackTranscriptWrite} registers its promise here; the promise
+ * removes itself on completion via `.finally`. Lifecycle boundaries
+ * (ChildPiLineObserver.flush, runChildPi settle) call
+ * {@link flushPendingTranscriptWrites} before returning so callers that
+ * immediately read the transcript file after `runChildPi` / `observer.flush()`
+ * await see the full content (and a non-ENOENT file).
+ *
+ * Module-scoped rather than per-input because all transcript writes for a
+ * given run share the same Node fs event loop and serialise through a single
+ * fs handle per path; one drain per lifecycle boundary is sufficient.
+ */
+const pendingTranscriptWrites: Set<Promise<void>> = new Set();
+
+function trackTranscriptWrite(safePath: string, line: string): void {
+	const p = appendTranscriptAsync(safePath, line).finally(() => {
+		pendingTranscriptWrites.delete(p);
+	});
+	pendingTranscriptWrites.add(p);
+}
+
+/**
+ * Drain all currently-pending transcript writes. Awaits every promise in the
+ * set; if new writes are scheduled during the drain (i.e. the `.finally`
+ * callback has not yet removed them), the loop re-checks `size > 0` and
+ * awaits them too. Idempotent and safe to call concurrently / reentrantly —
+ * each pending promise is tracked exactly once.
+ *
+ * Exported so external callers (e.g. integration tests that construct a
+ * ChildPiLineObserver directly) can drain explicitly if they need to read
+ * the transcript file outside of the observer's lifecycle.
+ */
+export async function flushPendingTranscriptWrites(): Promise<void> {
+	while (pendingTranscriptWrites.size > 0) {
+		const drained = [...pendingTranscriptWrites];
+		await Promise.allSettled(drained);
 	}
 }
 
@@ -632,11 +696,18 @@ export class ChildPiLineObserver {
 		for (const line of lines) this.emitLine(line);
 	}
 
-	flush(): void {
-		if (!this.buffer) return;
-		const line = this.buffer;
-		this.buffer = "";
-		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
+		// pending-write set 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
@@ -715,11 +786,15 @@ export class ChildPiLineObserver {
 	}
 }
 
-/** Mock-only path — real code path reuses a single observer. */
-function observeStdoutChunk(input: ChildPiRunInput, text: string): void {
+/** Mock-only path — real code path reuses a single observer.
+ *  OPT-06 follow-up: returns a Promise so callers can await the transcript
+ *  drain before resolving runChildPi. Without this, mock-mode callers that
+ *  read the transcript file post-run see ENOENT (the async file handle had
+ *  not yet been opened). */
+async function observeStdoutChunk(input: ChildPiRunInput, text: string): Promise<void> {
 	const observer = new ChildPiLineObserver(input);
 	observer.observe(text);
-	observer.flush();
+	await observer.flush();
 }
 
 function asRecord(value: unknown): Record<string, unknown> | undefined {
@@ -779,7 +854,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 		logInternalError("child-pi.mock", new Error(`Mock mode active: ${mock}`), "NOT running real agents");
 		if (mock === "success") {
 			const stdout = `[MOCK] Success for ${input.agent.name}\n`;
-			observeStdoutChunk(input, stdout);
+			await observeStdoutChunk(input, stdout);
 			return { exitCode: 0, stdout, stderr: "" };
 		}
 		if (mock === "json-success" || mock === "adaptive-plan") {
@@ -834,7 +909,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 						})}\nADAPTIVE_PLAN_JSON_END`
 					: `[MOCK] JSON success for ${input.agent.name}`;
 			const stdout = `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`;
-			observeStdoutChunk(input, stdout);
+			await observeStdoutChunk(input, stdout);
 			return { exitCode: 0, stdout, stderr: "" };
 		}
 		if (mock === "retryable-failure")
@@ -882,14 +957,14 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 					},
 				};
 				const stdout = `${JSON.stringify(failureEvent)}\n`;
-				observeStdoutChunk(input, stdout);
+				await observeStdoutChunk(input, stdout);
 				return { exitCode: 0, stdout, stderr: "" };
 			}
 			// Subsequent invocations: delegate to json-success shape so the
 			// fallback chain's second attempt succeeds and the run completes.
 			const text = `[MOCK] JSON success for ${input.agent.name}`;
 			const stdout = `${JSON.stringify({ type: "message", message: { role: "assistant", content: [{ type: "text", text }] } })}\n${JSON.stringify({ type: "message_end", usage: { input: 10, output: 5, cost: 0.001, turns: 1 } })}\n`;
-			observeStdoutChunk(input, stdout);
+			await observeStdoutChunk(input, stdout);
 			return { exitCode: 0, stdout, stderr: "" };
 		}
 		return { exitCode: 1, stdout: "", stderr: `[MOCK] failure: ${mock}` };
@@ -1107,7 +1182,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 							process.kill(child.pid!, 0);
 							// Child still alive — force settle with timeout error.
 							const timeoutErr = `Child Pi produced no new output for ${responseTimeoutMs}ms; killed but did not exit within ${SAFETY_SETTLE_MS}ms (possible zombie).`;
-							settle({
+							void settle({
 								exitCode: null,
 								stdout,
 								stderr,
@@ -1320,46 +1395,106 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				clearPostExitGuard();
 			};
 
-			const settle = (result: ChildPiRunResult): void => {
-				if (settled) return;
+			const settle = (result: ChildPiRunResult): Promise<void> => {
+				if (settled) return Promise.resolve();
 				settled = true;
 				clearChildPiTimeouts();
-				lineObserver.flush();
-				input.signal?.removeEventListener("abort", abort);
-				input.signal?.removeEventListener("abort", onParentAbort);
-				try {
-					cleanupTempDir(built.tempDir);
-				} catch (error) {
-					cleanupErrors.push(error instanceof Error ? error.message : String(error));
-				}
-				// Catch all errors from settle to prevent unhandled rejection from propagating
-				try {
-					resolve({
-						...result,
-						rawFinalText: lineObserver.getRawFinalText(),
-						intermediateFindings: lineObserver.getIntermediateFindings(),
-						exitStatus: result.exitStatus ?? {
-							exitCode: result.exitCode,
-							cancelled: abortRequested,
-							timedOut: responseTimeoutHit,
-							killed: hardKilled,
-							// Phase-0 diagnostic (HB-003a): surface the final-drain race state.
-							// finalDrainArmed lets Phase 1 decide whether a signal-death (exitCode=null)
-							// should be treated as a forced final drain. READ-ONLY for now.
-							...(finalDrainArmed || forcedFinalDrain
-								? {
-										finalDrainArmed,
-										forcedFinalDrain,
-										finalDrainFiredMonotonicMs,
-									}
-								: {}),
-							cleanupErrors,
-							finalDrainMs,
-						},
+				// OPT-06 follow-up: lineObserver.flush() is now async (returns
+				// Promise<void>) and drains the module-scoped pending-write set
+				// before resolving. We must await it before calling `resolve()`
+				// below so callers that read the transcript file post-`runChildPi`
+				// see all written lines. Caller invocations of `settle` from
+				// sync event handlers (`child.on('close'|'exit'|'error')`,
+				// safety timer) use `void settle(...)` — errors are caught and
+				// logged inside, and `resolve()` only fires after the drain
+				// completes, so runChildPi's outer Promise resolves with a
+				// durable transcript on disk.
+				return lineObserver
+					.flush()
+					.then(() => {
+						input.signal?.removeEventListener("abort", abort);
+						input.signal?.removeEventListener("abort", onParentAbort);
+						try {
+							cleanupTempDir(built.tempDir);
+						} catch (error) {
+							cleanupErrors.push(error instanceof Error ? error.message : String(error));
+						}
+						// Catch all errors from settle to prevent unhandled rejection from propagating
+						try {
+							resolve({
+								...result,
+								rawFinalText: lineObserver.getRawFinalText(),
+								intermediateFindings: lineObserver.getIntermediateFindings(),
+								exitStatus: result.exitStatus ?? {
+									exitCode: result.exitCode,
+									cancelled: abortRequested,
+									timedOut: responseTimeoutHit,
+									killed: hardKilled,
+									// Phase-0 diagnostic (HB-003a): surface the final-drain race state.
+									// finalDrainArmed lets Phase 1 decide whether a signal-death (exitCode=null)
+									// should be treated as a forced final drain. READ-ONLY for now.
+									...(finalDrainArmed || forcedFinalDrain
+										? {
+												finalDrainArmed,
+												forcedFinalDrain,
+												finalDrainFiredMonotonicMs,
+											}
+										: {}),
+									cleanupErrors,
+									finalDrainMs,
+								},
+							});
+						} catch (resolveError) {
+							logInternalError(
+								"child-pi.settle-resolve",
+								resolveError,
+								`result=${JSON.stringify({ exitCode: result.exitCode })}`,
+							);
+						}
+					})
+					.catch((flushError) => {
+						// Drain failed — log and still resolve so runChildPi doesn't hang.
+						logInternalError(
+							"child-pi.settle-flush-failed",
+							flushError,
+							`result=${JSON.stringify({ exitCode: result.exitCode })}`,
+						);
+						input.signal?.removeEventListener("abort", abort);
+						input.signal?.removeEventListener("abort", onParentAbort);
+						try {
+							cleanupTempDir(built.tempDir);
+						} catch (error) {
+							cleanupErrors.push(error instanceof Error ? error.message : String(error));
+						}
+						try {
+							resolve({
+								...result,
+								rawFinalText: lineObserver.getRawFinalText(),
+								intermediateFindings: lineObserver.getIntermediateFindings(),
+								exitStatus: result.exitStatus ?? {
+									exitCode: result.exitCode,
+									cancelled: abortRequested,
+									timedOut: responseTimeoutHit,
+									killed: hardKilled,
+									...(finalDrainArmed || forcedFinalDrain
+										? {
+												finalDrainArmed,
+												forcedFinalDrain,
+												finalDrainFiredMonotonicMs,
+											}
+										: {}),
+									cleanupErrors,
+									finalDrainMs,
+								},
+							});
+						} catch (resolveError) {
+							logInternalError(
+								"child-pi.settle-resolve",
+								resolveError,
+								`result=${JSON.stringify({ exitCode: result.exitCode })}`,
+							);
+						}
 					});
-				} catch (resolveError) {
-					logInternalError("child-pi.settle-resolve", resolveError, `result=${JSON.stringify({ exitCode: result.exitCode })}`);
-				}
 			};
 
 			const abort = (): void => {
@@ -1446,7 +1581,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 				} catch (err) {
 					logInternalError("child-pi.on-lifecycle-event", err, `event=error, pid=${child.pid}`);
 				}
-				settle({
+				void settle({
 					exitCode: null,
 					stdout,
 					stderr,
@@ -1585,7 +1720,7 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 					spawnError: undefined,
 					stderrSnippet: stderr ? redactStderrExcerpt(stderr, 1000) : undefined,
 				});
-				settle({
+				void settle({
 					exitCode: finalExitCode,
 					stdout,
 					stderr,

package/src/runtime/live-session-runtime.ts

@@ -5,7 +5,7 @@ import { resolveToolPolicy } from "../agents/agent-config.ts";
 import type { CrewRuntimeConfig } from "../config/config.ts";
 import { loadConfig } from "../config/config.ts";
 import { DEFAULT_LIVE_SESSION } from "../config/defaults.ts";
-import { appendEvent } from "../state/event-log.ts";
+import { appendEvent, appendEventFireAndForget } from "../state/event-log.ts";
 import type { TeamRunManifest, TeamTaskState, UsageState } from "../state/types.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { redactSecrets } from "../utils/redaction.ts";
@@ -151,8 +151,20 @@ type LiveSessionLike = {
 
 function appendTranscript(filePath: string | undefined, event: unknown): void {
 	if (!filePath) return;
-	fs.mkdirSync(path.dirname(filePath), { recursive: true });
-	fs.appendFileSync(filePath, `${JSON.stringify(redactSecrets(event))}\n`, "utf-8");
+	// Fire-and-forget async write to avoid blocking the event loop.
+	// Transcript writes are best-effort telemetry — callers do not need to await.
+	void appendTranscriptAsync(filePath, event);
+}
+
+/** Async version of appendTranscript — fire-and-forget for non-blocking writes. */
+async function appendTranscriptAsync(filePath: string, event: unknown): Promise<void> {
+	try {
+		await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+		const content = `${JSON.stringify(redactSecrets(event))}\n`;
+		await fs.promises.appendFile(filePath, content, "utf-8");
+	} catch (error) {
+		logInternalError("live-session.transcript-write-failed", error as Error, `path=${filePath}`);
+	}
 }
 
 function asRecord(value: unknown): Record<string, unknown> | undefined {
@@ -588,13 +600,20 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 			jsonEvents: 0,
 			error: "createAgentSession export is unavailable.",
 		};
+	// OPT-03: compute yield-enabled flag early to conditionally allocate
+	// collectedJsonEvents — avoids ~1KB array allocation per task when yield
+	// detection is disabled. Pattern mirrors task-runner.ts:165. Uses the same
+	// `enabled !== false` semantics as the late yield-detection block below so
+	// the array is always allocated when (and only when) it will be read.
+	const yieldConfig = input.runtimeConfig?.yield ?? { enabled: DEFAULT_YIELD_CONFIG.enabled };
+	const yieldEnabled = yieldConfig.enabled !== false;
 	let session: LiveSessionLike | undefined;
 	let unsubscribe: (() => void) | undefined;
 	let unsubscribeControlRealtime: (() => void) | undefined;
 	let controlTimer: ReturnType<typeof setInterval> | undefined;
 	let stdout = "";
 	let jsonEvents = 0;
-	const collectedJsonEvents: Record<string, unknown>[] = [];
+	const collectedJsonEvents: Record<string, unknown>[] | undefined = yieldEnabled ? [] : undefined;
 	const maxCollectedJsonEvents = 1000;
 	let yieldResult: YieldResult | undefined;
 
@@ -676,7 +695,9 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 			customTools,
 		});
 		session = created.session;
-		appendEvent(input.manifest.eventsPath, {
+		// P7 (perf): fire-and-forget — return value not needed, blocks the
+		// event loop less than the sync appendEvent under file-lock contention.
+		appendEventFireAndForget(input.manifest.eventsPath, {
 			type: "live-session.session_created",
 			runId: input.manifest.runId,
 			taskId: input.task.id,
@@ -696,7 +717,8 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 			]);
 		} catch (bindError) {
 			const msg = bindError instanceof Error ? bindError.message : String(bindError);
-			appendEvent(input.manifest.eventsPath, {
+			// P7: fire-and-forget — return value not needed.
+			appendEventFireAndForget(input.manifest.eventsPath, {
 				type: "live-session.bind_extensions_error",
 				runId: input.manifest.runId,
 				taskId: input.task.id,
@@ -851,7 +873,7 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 					trackLiveAgentToolEnd(agentId, toolName);
 				}
 				// Phase 1: collect events for yield detection
-				if (event && typeof event === "object" && !Array.isArray(event)) {
+				if (collectedJsonEvents && event && typeof event === "object" && !Array.isArray(event)) {
 					collectedJsonEvents.push(event as Record<string, unknown>);
 					if (collectedJsonEvents.length > maxCollectedJsonEvents)
 						collectedJsonEvents.splice(0, collectedJsonEvents.length - maxCollectedJsonEvents);
@@ -879,7 +901,8 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 
 		// Diagnostic: log prompt size and timing
 		const promptStart = Date.now();
-		appendEvent(input.manifest.eventsPath, {
+		// P7: fire-and-forget — return value not needed.
+		appendEventFireAndForget(input.manifest.eventsPath, {
 			type: "live-session.prompt_start",
 			runId: input.manifest.runId,
 			taskId: input.task.id,
@@ -896,7 +919,8 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 			await promptWithTimeout(session, effectivePrompt, sessionTimeoutMs, "Live-session");
 		} catch (promptError) {
 			const msg = promptError instanceof Error ? promptError.message : String(promptError);
-			appendEvent(input.manifest.eventsPath, {
+			// P7: fire-and-forget — return value not needed.
+			appendEventFireAndForget(input.manifest.eventsPath, {
 				type: "live-session.prompt_error",
 				runId: input.manifest.runId,
 				taskId: input.task.id,
@@ -916,7 +940,8 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 			}
 			throw promptError;
 		}
-		appendEvent(input.manifest.eventsPath, {
+		// P7: fire-and-forget — return value not needed.
+		appendEventFireAndForget(input.manifest.eventsPath, {
 			type: "live-session.prompt_done",
 			runId: input.manifest.runId,
 			taskId: input.task.id,
@@ -930,16 +955,12 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 		// --- Phase 1: Yield enforcement loop ---
 		// After the initial prompt completes, check if the worker called submit_result.
 		// Priority: 1) custom tool callback (G1), 2) JSON event detection (legacy).
-		const yieldConfig = input.runtimeConfig?.yield ?? {
-			enabled: DEFAULT_YIELD_CONFIG.enabled,
-		};
-		const yieldEnabled = yieldConfig.enabled !== false;
 		if (yieldEnabled && session) {
 			// Check custom tool callback first (G1)
 			if (customToolYieldResolved && customToolYieldResult) {
 				yieldResult = customToolYieldResult;
-			} else {
-				// Legacy: detect from JSON events
+			} else if (collectedJsonEvents) {
+				// Legacy: detect from JSON events (only when collection is enabled)
 				const alreadyYielded = hasYieldInOutput(collectedJsonEvents);
 				if (alreadyYielded) {
 					const yieldEvent = collectedJsonEvents.find((e) => isYieldEvent(e));
@@ -970,7 +991,7 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 					// Check again after schema reminder
 					if (customToolYieldResolved && customToolYieldResult) {
 						yieldResult = customToolYieldResult;
-					} else {
+					} else if (collectedJsonEvents) {
 						const newEvents = collectedJsonEvents.slice(-10);
 						if (hasYieldInOutput(newEvents)) {
 							const yieldEvent = newEvents.find((e) => isYieldEvent(e));
@@ -1021,7 +1042,7 @@ export async function runLiveSessionTask(input: LiveSessionSpawnInput): Promise<
 					break;
 				}
 				// Legacy: check JSON events
-				if (hasYieldInOutput(collectedJsonEvents.slice(-10))) {
+				if (collectedJsonEvents && hasYieldInOutput(collectedJsonEvents.slice(-10))) {
 					const yieldEvent = collectedJsonEvents.slice(-10).find((e) => isYieldEvent(e));
 					if (yieldEvent) yieldResult = extractYieldResult(yieldEvent);
 					break;

package/src/runtime/parallel-utils.ts

@@ -43,6 +43,11 @@ export function flattenSteps(steps: RunnerStep[]): RunnerSubagentStep[] {
 }
 
 export async function mapConcurrent<T, R>(items: T[], limit: number, fn: (item: T, i: number) => Promise<R>): Promise<R[]> {
+	// P12 (perf): single-item fast path. Skip the Promise.all + worker-pool
+	// setup when there's exactly one item — just call fn directly. Same return
+	// shape, no concurrency overhead, no micro-task allocation.
+	if (items.length === 1) return [await fn(items[0], 0)];
+	if (items.length === 0) return [];
 	const safeLimit = Math.max(1, Math.floor(limit) || 1);
 	const results: R[] = new Array(items.length);
 	let next = 0;

package/src/runtime/skill-instructions.ts

@@ -20,8 +20,35 @@ const MAX_SKILL_CHARS = 1500;
 const MAX_TOTAL_CHARS = 6000;
 const MAX_SKILL_NAME_CHARS = 80;
 const MAX_SELECTED_SKILLS = 32;
+
+// ── Cache sizing rationale (OPT-05 analysis, 2026-07-13) ───────────────────
+// The package ships 30 SKILL.md files; 11 are referenced by DEFAULT_ROLE_SKILLS.
+// Cache key = `${cwd}:${skillName}`, so a single-cwd run needs ≤30 entries.
+// Multi-cwd scenarios (worktree isolation) multiply this, but rarely exceed 90.
+// 128 provides 4× headroom over the skill count, ~1.4× over a 3-cwd scenario.
+// Memory per entry ≈ 5KB (raw + compacted body), so 128 entries ≈ 640KB — negligible.
+// Conclusion: 128 is well-tuned. Evictions are near-zero in practice.
 const SKILL_CACHE_MAX_ENTRIES = 128;
 
+export interface SkillCacheStats {
+	hits: number;
+	misses: number;
+	evictions: number;
+	currentSize: number;
+	maxEntries: number;
+	/** Computed hit-rate: hits / (hits + misses), 0 when no lookups yet. */
+	hitRate: number;
+}
+
+const skillCacheStats: SkillCacheStats = {
+	hits: 0,
+	misses: 0,
+	evictions: 0,
+	currentSize: 0,
+	maxEntries: SKILL_CACHE_MAX_ENTRIES,
+	hitRate: 0,
+};
+
 const DEFAULT_ROLE_SKILLS: Record<string, string[]> = {
 	explorer: ["read-only-explorer", "context-artifact-hygiene"],
 	analyst: ["read-only-explorer", "requirements-to-task-packet"],
@@ -146,16 +173,43 @@ const skillReadCache = new Map<string, CachedSkillMarkdown>();
 function rememberSkill(key: string, value: CachedSkillMarkdown): CachedSkillMarkdown {
 	if (skillReadCache.has(key)) skillReadCache.delete(key);
 	skillReadCache.set(key, value);
-	while (skillReadCache.size > SKILL_CACHE_MAX_ENTRIES) {
+	while (skillReadCache.size > skillCacheStats.maxEntries) {
 		const oldest = skillReadCache.keys().next().value;
 		if (!oldest) break;
 		skillReadCache.delete(oldest);
+		skillCacheStats.evictions++;
 	}
+	skillCacheStats.currentSize = skillReadCache.size;
 	return value;
 }
 
 export function clearSkillInstructionCache(): void {
 	skillReadCache.clear();
+	skillCacheStats.currentSize = 0;
+}
+
+export function getSkillCacheStats(): SkillCacheStats {
+	const total = skillCacheStats.hits + skillCacheStats.misses;
+	return {
+		...skillCacheStats,
+		currentSize: skillReadCache.size,
+		hitRate: total > 0 ? skillCacheStats.hits / total : 0,
+	};
+}
+
+export function resetSkillCacheStats(): void {
+	skillCacheStats.hits = 0;
+	skillCacheStats.misses = 0;
+	skillCacheStats.evictions = 0;
+	skillCacheStats.currentSize = skillReadCache.size;
+}
+
+/**
+ * Test-only: temporarily override the cache capacity to exercise eviction logic.
+ * Always restore to `SKILL_CACHE_MAX_ENTRIES` after the test.
+ */
+export function _setSkillCacheMaxEntriesForTesting(max: number): void {
+	skillCacheStats.maxEntries = max;
 }
 
 function cachedSkillFresh(value: CachedSkillMarkdown): boolean {
@@ -181,8 +235,13 @@ function readSkillMarkdown(
 	if (!isValidSkillName(name)) return undefined;
 	const cacheKey = `${path.resolve(cwd)}:${name}`;
 	const cached = skillReadCache.get(cacheKey);
-	if (cached && cachedSkillFresh(cached)) return cached;
+	if (cached && cachedSkillFresh(cached)) {
+		skillCacheStats.hits++;
+		return cached;
+	}
 	if (cached) skillReadCache.delete(cacheKey);
+	skillCacheStats.misses++;
+	skillCacheStats.currentSize = skillReadCache.size;
 	for (const entry of candidateSkillDirs(cwd)) {
 		try {
 			const relative = path.join(name, "SKILL.md");

package/src/runtime/stale-reconciler.ts

@@ -74,6 +74,9 @@ function checkResultFile(manifest: TeamRunManifest, tasks: TeamTaskState[]): { f
 		const onlyCancelledOrSkipped = tasks.every((t) => t.status === "cancelled" || t.status === "skipped");
 		manifest.status = hasFailed ? "failed" : onlyCancelledOrSkipped ? "cancelled" : "completed";
 		// Persist manifest status change immediately to make checkResultFile self-contained.
+		// NOTE (OPT-02): Remains sync — reconcileStaleRun → checkResultFile is called from
+		// withRunLockSync in crash-recovery.ts and from sync reconcileOrphanedTempWorkspaces.
+		// Converting to async would require cascading through all callers including sync UI hooks.
 		saveRunManifest(manifest);
 		// Sync agent records even when tasks are already terminal
 		// (e.g., a previous reconcile fixed tasks but crashed before updating agents)
@@ -329,6 +332,8 @@ export function reconcileStaleRun(manifest: TeamRunManifest, tasks: TeamTaskStat
 		// checkResultFile sets manifest.status='completed' and saves it,
 		// but we re-save to ensure the completed status is persisted
 		// before returning (avoids TOCTOU where caller might re-read stale data)
+		// NOTE (OPT-02): Remains sync — reconcileStaleRun is called from withRunLockSync in
+		// crash-recovery.ts and from sync reconcileOrphanedTempWorkspaces; cannot await here.
 		saveRunManifest(manifest);
 		return {
 			runId,