pi-crew 0.10.2 → 0.10.4

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

@@ -1,13 +1,23 @@
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
+import * as path from "node:path";
 import type { AgentConfig } from "../../agents/agent-config.ts";
+import { loadConfig } from "../../config/config.ts";
 import { getCrewEnv } from "../../config/env-vars.ts";
+import type { PiTeamsConfig } from "../../config/types.ts";
 import { registerChildProcess, unregisterChildProcess } from "../../extension/crew-cleanup.ts";
 import type { WorkerExitStatus } from "../../state/types.ts";
+import { runEventBus } from "../../ui/run-event-bus.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { redactSecretString } from "../../utils/redaction.ts";
 import { getActiveBrokerIssuer } from "../broker/broker-issuer.ts";
 import { BoundedTail } from "../compaction/compact-stages/bounded-tail.ts";
+import { EventLogTailSource } from "../event-log-tail-source.ts";
+import { bridgeEventFromJsonEvent } from "../event-stream-bridge.ts";
+import { classifyOnExit, getSurfaceRuntimeController, makeTerminalEventProbe } from "../surface/degrade.ts";
+import type { SurfaceGateEnvSnapshot } from "../surface/resolve-surface.ts";
+import type { SurfaceProvider } from "../surface/surface-provider.ts";
+import { prepareSurfaceSpawn, type SurfaceExitInfo, type SurfaceSpawnOutcome, waitForSurfaceExit } from "../surface/surface-spawn.ts";
 import { FINAL_DRAIN_MS, HARD_KILL_MS, POST_EXIT_STDIO_GUARD_MS, RESPONSE_TIMEOUT_MS } from "./child-pi-constants.ts";
 import { clearHardKillTimer, killProcessTree, registerActiveChild, unregisterActiveChild } from "./child-pi-kill.ts";
 import { buildFinalChildPiSpawnOptions, prepareSpawnContext } from "./child-pi-spawn.ts";
@@ -71,10 +81,41 @@ export function redactStderrExcerpt(stderr: string, maxChars: number): string {
 
 /** Structured lifecycle event emitted by child-pi for critical transitions. */
 export interface ChildPiLifecycleEvent {
-	/** Event discriminator. */
-	type: "spawned" | "spawn_error" | "response_timeout" | "final_drain" | "hard_kill" | "exit" | "close";
+	/**
+	 * Event discriminator. `surface_spawned` / `surface_closed` are emitted by
+	 * the MuxSurface spawn branch (spec §13.1) — no stdio process exists, so
+	 * `pid` is absent there and surface fields carry the pane identity.
+	 */
+	type:
+		| "spawned"
+		| "spawn_error"
+		| "response_timeout"
+		| "final_drain"
+		| "hard_kill"
+		| "exit"
+		| "close"
+		| "surface_spawned"
+		| "surface_closed"
+		/** T11 (spec §7): a REAL surface spawn attempt failed → headless fallback
+		 *  + the run-scoped spawn-fail lockout counter (3 consecutive → OFF). */
+		| "surface_spawn_failed"
+		/** FINDING-3 (report 10tier 2026-08-27): a gate rejected surface BEFORE
+		 *  touching the mux (mode-off/async-run/depth/pane-cap/role-not-visible/
+		 *  no-mux). Emitted ONLY when the user opted into surface
+		 *  (visibleAgents non-empty) — default runs stay silent. */
+		| "surface_gate_blocked";
 	/** Process ID when available. */
 	pid?: number;
+	/** Pane id (surface events). */
+	paneId?: string;
+	/** Surface backend kind (surface events). */
+	surfaceKind?: "tmux" | "herdr";
+	/** Why the pane ended / degraded (surface_closed): "pane-closed" | "mux-dead" | "detached". */
+	paneExitReason?: string;
+	/** Which gate rejected surface (surface_gate_blocked): one of the SurfaceGateName values. */
+	gate?: string;
+	/** Env signals the gate saw (surface_gate_blocked) — bounded snapshot, never the whole env. */
+	env?: SurfaceGateEnvSnapshot;
 	/** Exit code for exit/close events. */
 	exitCode?: number | null;
 	/** Error message for error events. */
@@ -116,6 +157,17 @@ export interface ChildPiRunInput {
 	onSpawn?: (pid: number) => void;
 	/** Structured lifecycle events for durable logging (spawn, crash, timeout, kill, exit). */
 	onLifecycleEvent?: (event: ChildPiLifecycleEvent) => void;
+	/** F1 fix (battery 2026-09-10): task-state activity bridge for SURFACE workers.
+	 * Surface workers have no stdout pipe, so onJsonEvent/onStdoutLine never fire
+	 * and task.heartbeat/agentProgress starve - the heartbeat-watcher then flags a
+	 * healthy pane worker dead (~340s) and the stale-reconciler cancels the run
+	 * (observed live: run team_20260910161234, worker productive 7min in pane
+	 * w2:p8Z, 0 task.progress events). This callback receives every event tailed
+	 * from the per-agent recorder log so the CALLER can update task liveness state.
+	 * Contract: the callback MUST NOT append to the per-agent events file being
+	 * tailed (watch->append loop - see event-log-tail-source.ts header); task-state
+	 * persist + run-level task.progress are safe (different files). */
+	onSurfaceActivity?: (event: Record<string, unknown>) => void;
 	maxDepth?: number;
 	finalDrainMs?: number;
 	/** F12: early-exit the drain when stdout has been silent for this many ms
@@ -192,6 +244,28 @@ export interface ChildPiRunInput {
 	/** Base env for depth computation (defaults to process.env). Advanced —
 	 * used with depthOverride by the root-side delegate handler. */
 	env?: NodeJS.ProcessEnv;
+	/**
+	 * MuxSurface A1 (spec §13.1): opt-in/hint for booting this worker in a
+	 * multiplexer pane instead of a stdio pipe. Undefined → the branch still
+	 * consults the discovered project config, which defaults surface OFF
+	 * (`visibleAgents: []`), so behaviour stays headless unless explicitly
+	 * configured. Any failure degrades to the normal headless spawn path (§3
+	 * fail-closed) — NEVER throws.
+	 *
+	 * - `providers`: pre-resolved provider instances — dispatch-owned (team-runner
+	 *   T11 passes its resolved provider + livePaneCount) and test injection.
+	 *   Hard gates (async run / host depth) still apply.
+	 * - `config`: overrides discovered config (tests).
+	 * - `livePaneCount`: panes already live for this run — `MAX_SURFACE_WORKERS`
+	 *     cap check. Defaults 0 until T11 threads manifest state.
+	 * - `baseDir`: launch-script dir override (default getPiTempBase()).
+	 */
+	surface?: {
+		providers?: { tmux?: SurfaceProvider; herdr?: SurfaceProvider };
+		config?: PiTeamsConfig;
+		livePaneCount?: number;
+		baseDir?: string;
+	};
 }
 
 export interface ChildPiRunResult {
@@ -217,6 +291,26 @@ export interface ChildPiRunResult {
 	 *  text) still produce a non-empty result. Consumers should prefer rawFinalText
 	 *  first — this is a last-resort fallback. */
 	intermediateFindings?: string;
+	/**
+	 * MuxSurface A1: present ONLY when the worker booted inside a multiplexer
+	 * pane instead of a stdio pipe (spec §13.1). Downstream (T9 EventLogTailSource,
+	 * T11 degrade) consumes the pane identity; the empty stdout/stderr is EXPECTED
+	 * in surface mode — events arrive through the per-agent event log, not a pipe.
+	 *
+	 * `degraded` is set when classifyOnExit found NO worker.completed within the
+	 * 2s window after the pane died (spec §7 D3) — task-runner hands that to
+	 * finalize as `surfaceLost` instead of reading it as an empty/false result.
+	 */
+	surface?: {
+		kind: "tmux" | "herdr";
+		paneId: string;
+		scriptPath: string;
+		degraded?: {
+			cause: "pane-closed" | "mux-dead";
+			exitReason: string;
+			classifiedAt: string;
+		};
+	};
 }
 
 // Base allowlist of non-provider env vars always passed to child workers.
@@ -259,6 +353,270 @@ function isFinalAssistantEvent(event: unknown): boolean {
 	return !content.some((part) => asRecord(part)?.type === "toolCall");
 }
 
+/**
+ * Discover the project crew config for the surface gate. The discovered config
+ * DEFAULTS surface off (`visibleAgents: []`) — headless unless explicitly opted
+ * in. Any discovery failure → default config (fail-closed §3), never throws.
+ */
+function safeLoadSurfaceConfig(cwd: string): PiTeamsConfig {
+	try {
+		return loadConfig(cwd).config;
+	} catch (error) {
+		logInternalError(
+			"child-pi.surface-config",
+			error instanceof Error ? error : new Error(String(error)),
+			"surface gate uses default (off)",
+		);
+		return {};
+	}
+}
+
+/**
+ * MuxSurface A1 spawn branch (spec §13.1). Returns a ChildPiRunResult when the
+ * worker was booted INSIDE a multiplexer pane (no stdio process is spawned and
+ * completion is awaited through the pane's own lifetime), or null to fall
+ * through to the normal stdio spawn.
+ *
+ * NEVER throws: any preparation failure degrades to null (headless §3).
+ */
+async function trySurfaceBranch(
+	input: ChildPiRunInput,
+	depthEnv: NodeJS.ProcessEnv | undefined,
+	builtArgs: string[],
+	mergedEnv: NodeJS.ProcessEnv,
+	builtEnv: Record<string, string | undefined>,
+	tempDir: string | undefined,
+): Promise<ChildPiRunResult | null> {
+	// A pane needs a task id for its title/event-log path — an anonymous worker
+	// has nothing meaningful to boot there, so stay on the headless road.
+	if (!input.agentId) return null;
+	const surfaceOpts = input.surface;
+	const preResolved = surfaceOpts?.providers?.tmux ?? surfaceOpts?.providers?.herdr;
+	// T11 (spec §7): per-run degrade controller — team-runner owns the policy
+	// (lockout counters, pane cap accounting); this layer only consults it.
+	// Absent controller (delegate spawn outside a team run, unit tests) keeps
+	// today's behavior untouched.
+	const taskId = input.agentId;
+	const degradeController = getSurfaceRuntimeController(input.runId);
+	if (degradeController && !degradeController.shouldAttemptSurface()) return null;
+	const surfaceConfig = surfaceOpts?.config ?? safeLoadSurfaceConfig(input.cwd);
+	let outcome: SurfaceSpawnOutcome;
+	try {
+		outcome = await prepareSurfaceSpawn({
+			// Detection env must be the HOST's base env (depth 0 tier-1), NOT the
+			// child's built env whose PI_CREW_DEPTH is parentDepth+1 — layer-1
+			// guard would misfire on our own tier-1 workers.
+			env: depthEnv ?? process.env,
+			workerEnv: buildFinalChildPiSpawnOptions(input.cwd, mergedEnv, builtEnv, input.model).env as Record<string, string>,
+			config: surfaceConfig,
+			role: input.role ?? input.agent.name,
+			livePaneCount: degradeController ? degradeController.livePaneCount() : (surfaceOpts?.livePaneCount ?? 0),
+			taskId,
+			cwd: input.cwd,
+			piArgs: builtArgs,
+			stateRoot: input.eventsPath ? path.dirname(input.eventsPath) : "",
+			baseDir: surfaceOpts?.baseDir,
+			deps: preResolved ? { provider: preResolved } : {},
+		});
+	} catch (error) {
+		// Defense in depth — prepareSurfaceSpawn is no-throw by contract (§3).
+		logInternalError("child-pi.surface-unexpected", error instanceof Error ? error : new Error(String(error)), `taskId=${taskId}`);
+		return null;
+	}
+	if (outcome.mode !== "surface") {
+		// Spawn-fail ≠ flap (spec §7) but it feeds ITS OWN lockout counter. Only
+		// `attempted` outcomes count — gate/resolve-null rejections are the mux
+		// simply being absent, not the multiplexer misbehaving.
+		if (outcome.mode === "headless" && outcome.attempted) {
+			degradeController?.notifySpawnFailed({ taskId, reason: outcome.reason ?? "surface spawn failed" });
+			input.onLifecycleEvent?.({
+				type: "surface_spawn_failed",
+				surfaceKind: preResolved?.kind,
+				error: outcome.reason,
+				ts: new Date().toISOString(),
+			});
+		}
+		// FINDING-3 (report 10tier 2026-08-27 adjudication): the gate-null path
+		// used to be completely silent — a misconfigured surface run (wrong
+		// visibleAgents, mode typo, …) was indistinguishable from a by-design
+		// headless run in events.jsonl. Emit ONLY when the user opted into
+		// surface (visibleAgents non-empty) so default runs gain zero noise.
+		// The lockout path above stays silent here — its cause already emitted
+		// surface.degraded events on the way to locking.
+		if (outcome.mode === "headless" && outcome.gateRejected) {
+			const visibleAgents = surfaceConfig.runtime?.surface?.visibleAgents ?? [];
+			if (visibleAgents.length > 0) {
+				input.onLifecycleEvent?.({
+					type: "surface_gate_blocked",
+					gate: outcome.gateRejected.gate,
+					error: outcome.gateRejected.reason,
+					env: outcome.gateRejected.env,
+					ts: new Date().toISOString(),
+				});
+			}
+		}
+		return null;
+	}
+
+	const surfaceMeta: NonNullable<ChildPiRunResult["surface"]> = {
+		kind: outcome.kind,
+		paneId: outcome.paneId,
+		scriptPath: outcome.scriptPath,
+	};
+	degradeController?.notifySpawned({
+		taskId,
+		paneId: outcome.paneId,
+		provider: outcome.kind,
+		// Task 5 (tab-layout): tab của run lên controller → manifest surface.tabs
+		// — run end (closeRunTabs) đóng đúng tab, worker xong KHÔNG đóng.
+		...(outcome.tabKey && outcome.tabId ? { tabKey: outcome.tabKey, tabId: outcome.tabId } : {}),
+	});
+	input.onLifecycleEvent?.({
+		type: "surface_spawned",
+		surfaceKind: outcome.kind,
+		paneId: outcome.paneId,
+		ts: new Date().toISOString(),
+	});
+	// T9 (spec §5.3): surface worker không có stdout JSON stream — worker-side
+	// recorder ghi per-agent events.jsonl; host tail file đó và bridge thẳng ra
+	// run event bus cho dashboard/sidebar ("như cũ"). KHÔNG đưa vào
+	// input.onJsonEvent: callback task-runner gọi appendCrewAgentEventBuffered
+	// vào CHÍNH file này (worker đã ghi sẵn) → ghi đôi + vòng tự kích hoạt
+	// watch→append→watch không dừng (xem header event-log-tail-source.ts).
+	const eventSource = outcome.eventsPath ? new EventLogTailSource({ eventsPath: outcome.eventsPath }) : undefined;
+	if (eventSource && input.runId && input.agentId) {
+		const runId = input.runId;
+		const taskId = input.agentId;
+		const controllerForBridge = degradeController;
+		eventSource.onEvent((event) => {
+			// T11: the worker's own `worker.started` self-report carries the pid +
+			// session path that doctor/degrade-resume need (§12.2). Bridge it into
+			// the run-scoped controller BEFORE the dashboard shim — it is the only
+			// host-side consumer of that payload.
+			if ((event as { type?: unknown } | undefined)?.type === "worker.started") {
+				const started = event as { pid?: unknown; sessionPath?: unknown };
+				controllerForBridge?.notifyWorkerStarted({
+					taskId,
+					pid: typeof started.pid === "number" ? started.pid : undefined,
+					sessionPath: typeof started.sessionPath === "string" ? started.sessionPath : undefined,
+				});
+			}
+			const bridgeEvent = bridgeEventFromJsonEvent(runId, taskId, event);
+			if (bridgeEvent) runEventBus.emit({ type: "worker_status", runId, taskId, data: bridgeEvent });
+			// F1 fix (battery 2026-09-10): feed the same tailed event to the task-state
+			// bridge so child-executor can keep task.heartbeat/agentProgress fresh for
+			// surface workers (see ChildPiRunInput.onSurfaceActivity doc).
+			input.onSurfaceActivity?.(event as Record<string, unknown>);
+		});
+	}
+	let exitInfo: SurfaceExitInfo;
+	try {
+		// Pane lifetime IS the worker lifetime in A1: T8's auto-exit closes the
+		// pane at turn end (spec §13.2); cancel closes it here via AbortSignal and
+		// the response deadline force-closes a WEDGED worker (fix round 1/F2 —
+		// parity with headless minimum timeout so a stuck pane cannot hold its
+		// worker slot forever; A1 has no stream-activity signal so this is ONE
+		// hard deadline).
+		exitInfo = await waitForSurfaceExit(outcome, {
+			signal: input.signal,
+			deadlineMs: input.responseTimeoutMs ?? RESPONSE_TIMEOUT_MS,
+		});
+	} finally {
+		eventSource?.close();
+	}
+	// T11 classify (spec §7): D7 report-before-dying means a normally-finishing
+	// worker already wrote `worker.completed` to the RUN event log before its
+	// pane closed, so the probe finds it on the first scan. Nothing within the
+	// 2s window → the worker never finished → the pane death is a DEGRADE and
+	// team-runner re-dispatches this unit headless. Cancel/deadline force-closes
+	// are HOST-initiated — classify is skipped there (never counts as mux flap),
+	// but the pane release itself is reported in EVERY case so the run's live
+	// pane cap stays accurate.
+	let completedPayload: Record<string, unknown> | undefined;
+	if (!exitInfo.cancelledByAbort && !exitInfo.timedOut) {
+		const probe = makeTerminalEventProbe({ eventsPath: input.eventsPath ?? "", taskId, runId: input.runId ?? undefined });
+		const verdict = await classifyOnExit(outcome.handle, probe);
+		const completed = verdict === "completed";
+		if (completed) {
+			const payload = probe.foundPayload();
+			completedPayload = payload && typeof payload.result === "string" && payload.result.trim().length > 0 ? payload : undefined;
+		} else {
+			surfaceMeta.degraded = {
+				cause: exitInfo.reason === "mux-dead" ? "mux-dead" : "pane-closed",
+				exitReason: exitInfo.reason,
+				classifiedAt: new Date().toISOString(),
+			};
+		}
+		degradeController?.notifyPaneExited({
+			taskId,
+			paneId: outcome.paneId,
+			completed,
+			exitReason: exitInfo.reason,
+		});
+	} else {
+		degradeController?.notifyPaneExited({
+			taskId,
+			paneId: outcome.paneId,
+			completed: false,
+			exitReason: exitInfo.reason,
+			cancelledByAbort: exitInfo.cancelledByAbort,
+			timedOut: exitInfo.timedOut,
+		});
+	}
+	// Result text captured from `worker.completed` — WITHOUT it every surface
+	// task would look empty downstream (rawFinalText/stdout are the only result
+	// channels post-execution trusts) and flip to failed via the empty-output
+	// guard even though the worker SUCCEEDED.
+	const surfaceResultText = typeof completedPayload?.result === "string" ? completedPayload.result : "";
+	input.onLifecycleEvent?.({
+		type: "surface_closed",
+		surfaceKind: outcome.kind,
+		paneId: outcome.paneId,
+		paneExitReason: exitInfo.reason,
+		ts: new Date().toISOString(),
+	});
+	// F1: the pane is gone — nothing can still need the prompt/task temp dir.
+	// The headless branch cleans this up in settle(); surface returns early.
+	cleanupTempDir(tempDir);
+	// Empty stdout/stderr is EXPECTED — events flow through the per-agent event
+	// log (worker-side recorder, spec §5.3), not through a pipe we own. The only
+	// text the worker produced surfaces via `worker.completed` (surfaceResultText).
+	return {
+		exitCode: exitInfo.cancelledByAbort || exitInfo.timedOut ? null : 0,
+		stdout: "",
+		stderr: "",
+		...(exitInfo.cancelledByAbort
+			? { error: `Cancelled while running in ${outcome.kind} pane ${outcome.paneId} (${exitInfo.reason})` }
+			: {}),
+		...(exitInfo.timedOut
+			? {
+					error:
+						`Surface worker in ${outcome.kind} pane ${outcome.paneId} produced no completion within ` +
+						`${input.responseTimeoutMs ?? RESPONSE_TIMEOUT_MS}ms response timeout; pane was force-closed.`,
+				}
+			: {}),
+		rawFinalText: surfaceResultText,
+		intermediateFindings: "",
+		...(exitInfo.cancelledByAbort ? { aborted: true } : {}),
+		surface: surfaceMeta,
+		exitStatus: {
+			exitCode: exitInfo.cancelledByAbort || exitInfo.timedOut ? null : 0,
+			cancelled: exitInfo.cancelledByAbort,
+			timedOut: exitInfo.timedOut,
+			killed: false,
+			cleanupErrors: [],
+			finalDrainMs: 0,
+		},
+	};
+}
+
+/**
+ * Test seam — trySurfaceBranch là internal wiring giữa prepareSurfaceSpawn và
+ * lifecycle events (surface_gate_blocked). Mock mode intercepts runChildPi
+ * BEFORE this branch, so unit tests exercise the wiring through this export.
+ */
+export const __test__trySurfaceBranch = trySurfaceBranch;
+
 export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResult> {
 	// Phase 1 (live-session parity): prepend parent context when inheritContext is true.
 	// This mirrors the effectivePrompt logic in live-session-runtime.ts so that
@@ -304,8 +662,8 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 	if (!brokerSpawn && brokerIssuer && input.runId) {
 		try {
 			// ADR-5 §4: thread the child depth so the issuer can contain broker
-			// credentials at depths that may not delegate (depth-2 at default
-			// maxDepth=2 gets NO socket/token — env containment AC).
+			// credentials at depths that may not delegate (a child at the default
+			// maxDepth=4 cap gets NO socket/token — env containment AC).
 			brokerSpawn = await brokerIssuer(input.runId, input.agentId, input.depthOverride);
 		} catch (error) {
 			// H8 (2026-08-10): surface the silent degradation. Previously this
@@ -325,7 +683,12 @@ export async function runChildPi(input: ChildPiRunInput): Promise<ChildPiRunResu
 	}
 	const spawnPrep = prepareSpawnContext(brokerSpawn ? { ...input, brokerSpawn } : input, effectiveTask, depthEnv);
 	if (spawnPrep.kind === "aborted") return spawnPrep.result;
-	const { spawnSpec, mergedEnv, tempDir, builtEnv } = spawnPrep.ctx;
+	const { spawnSpec, mergedEnv, tempDir, builtEnv, builtArgs } = spawnPrep.ctx;
+	// MuxSurface A1 (spec §13.1): attempt booting the worker in a mux pane BEFORE
+	// spawning a stdio pipe. Returns a finished result in surface mode (pane exit
+	// awaited) or null → fall through to the classic headless spawn below.
+	const surfaceResult = await trySurfaceBranch(input, depthEnv, builtArgs, mergedEnv, builtEnv, tempDir);
+	if (surfaceResult) return surfaceResult;
 	try {
 		return await new Promise<ChildPiRunResult>((resolve) => {
 			// Compose the final SpawnOptions: canary + filter + spread are now

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

@@ -98,7 +98,19 @@ export function agentStatusPath(manifest: TeamRunManifest, taskId: string): stri
 }
 
 export function agentEventsPath(manifest: TeamRunManifest, taskId: string): string {
-	return path.join(agentStateDir(manifest, taskId), "events.jsonl");
+	return agentEventsPathForStateRoot(manifest.stateRoot, taskId);
+}
+
+/**
+ * Per-agent events log dưới stateRoot bất kỳ (không cần manifest đầy đủ).
+ * MỘT công thức cho mọi bên: host writers/readers (qua agentEventsPath) và
+ * surface spawn (S2-T7 set PI_CREW_AGENT_EVENTS_PATH, S2-T9 tail) — tất cả
+ * qua safeAgentTaskId, nên taskId chứa ":" (delegate-spawn ids) rơi về CÙNG
+ * file cho cả worker recorder lẫn agent-view. Throw khi phần id sau sanitize
+ * không hợp lệ (assertSafePathId) — caller fail-closed tự xử lý.
+ */
+export function agentEventsPathForStateRoot(stateRoot: string, taskId: string): string {
+	return path.join(stateRoot, "agents", safeAgentTaskId(taskId), "events.jsonl");
 }
 
 export function agentOutputPath(manifest: TeamRunManifest, taskId: string): string {

package/src/runtime/dispatch-batch.ts

@@ -118,7 +118,16 @@ export async function sweepExpiredWaitingTasks(
 	cwd: string,
 	runId: string,
 	now = Date.now(),
+	// PERF (2026-08-24): callers in the scheduler loop already hold a task view
+	// loaded this tick. Check the cheap expiry predicate against it BEFORE
+	// paying stat+parse of manifest.json + tasks.json — the sweep fires on every
+	// unit settle/dispatch and almost always finds nothing expired.
+	hintTasks?: TeamTaskState[],
 ): Promise<WaitingDeadlineSweepResult | undefined> {
+	if (hintTasks) {
+		const hintExpired = hintTasks.some((t) => t.status === "waiting" && t.waiting !== undefined && t.waiting.deadline <= now);
+		if (!hintExpired) return undefined;
+	}
 	const initial = loadRunManifestById(cwd, runId);
 	if (!initial) return undefined;
 	const hasExpired = initial.tasks.some((t) => t.status === "waiting" && t.waiting !== undefined && t.waiting.deadline <= now);
@@ -375,7 +384,9 @@ function dagReadyTaskIds(tasks: TeamTaskState[], completedIds: Set<string>): str
  * Mutates ctx.manifest/ctx.tasks from the sweeps' disk-reloaded results.
  */
 export async function runSchedulerSweeps(ctx: { manifest: TeamRunManifest; tasks: TeamTaskState[] }): Promise<void> {
-	const sweep = await sweepExpiredWaitingTasks(ctx.manifest.cwd, ctx.manifest.runId);
+	// PERF (2026-08-24): pass this tick's task view as the expiry hint — the
+	// sweep then skips the manifest load entirely when nothing is expired.
+	const sweep = await sweepExpiredWaitingTasks(ctx.manifest.cwd, ctx.manifest.runId, Date.now(), ctx.tasks);
 	if (sweep) {
 		ctx.manifest = sweep.manifest;
 		ctx.tasks = sweep.tasks;