pi-crew 0.9.34 → 0.9.35

package/src/runtime/live-session-runtime.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;
 
@@ -854,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);
@@ -936,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));
@@ -976,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));
@@ -1027,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/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,

package/src/runtime/task-runner/tail-read.ts

@@ -4,10 +4,22 @@ import * as fs from "node:fs";
  * Read the tail of a file, capped at maxBytes.
  * If the file exceeds maxBytes, reads only the last maxBytes and snaps
  * to the nearest newline boundary to avoid partial JSONL lines.
+ *
+ * Falls back to `fallbackContent` when the file is missing OR empty. The
+ * empty-file case matters because `appendTranscript` is fire-and-forget
+ * async in the mock path (commit e316a36) — the file is created on disk
+ * (existsSync returns true) before the actual write completes, so a
+ * subsequent tail-read can observe size=0. Returning "" in that case would
+ * silently drop the mock's stdout, breaking downstream parsers that depend
+ * on a non-empty transcript (e.g. adaptive-plan JSON extraction in
+ * implementation-fanout.test.ts). Falling back to `fallbackContent` keeps
+ * the existing fallback semantics: "if the file isn't usable, use what
+ * the caller already has."
  */
 export function tailReadWithLineSnap(filePath: string, maxBytes: number, fallbackContent: string): string {
 	if (!fs.existsSync(filePath)) return fallbackContent;
 	const stat = fs.statSync(filePath);
+	if (stat.size === 0) return fallbackContent;
 	if (stat.size <= maxBytes) return fs.readFileSync(filePath, "utf-8");
 	const fd = fs.openSync(filePath, "r");
 	try {

package/src/runtime/task-runner.ts

@@ -7,8 +7,8 @@ import { errors } from "../errors.ts";
 import { appendHookEvent, executeHook } from "../hooks/registry.ts";
 import { writeArtifact } from "../state/artifact-store.ts";
 import { appendEventAsync, appendEventBuffered, appendEventFireAndForget } from "../state/event-log.ts";
-import { withRunLockSync } from "../state/locks.ts";
-import { saveRunManifest } from "../state/state-store.ts";
+import { withRunLock } from "../state/locks.ts";
+import { saveRunManifestAsync } from "../state/state-store.ts";
 import { createTaskClaim } from "../state/task-claims.ts";
 import type {
 	ArtifactDescriptor,
@@ -83,6 +83,36 @@ import {
 // Register the submit_result tool handler so subprocess events can extract yield data.
 registerYieldTool();
 
+/** Async helper for writing steering events — fire-and-forget for non-blocking writes. */
+async function appendSteeringAsync(steeringDir: string, taskId: string, steers: string[]): Promise<void> {
+	try {
+		await fs.promises.mkdir(steeringDir, { recursive: true });
+		const steeringPath = `${steeringDir}/${taskId}.jsonl`;
+		const lines = steers
+			.map(
+				(msg) =>
+					JSON.stringify({
+						type: "steer",
+						message: msg,
+						ts: new Date().toISOString(),
+					}) + "\n",
+			)
+			.join("");
+		await fs.promises.appendFile(steeringPath, lines, "utf-8");
+	} catch (error) {
+		logInternalError("task-runner.steering-write-failed", error as Error, `taskId=${taskId}`);
+	}
+}
+
+/** Async helper for writing background logs — fire-and-forget for non-blocking writes. */
+async function appendBackgroundLogAsync(bgLogPath: string, eventLine: string): Promise<void> {
+	try {
+		await fs.promises.appendFile(bgLogPath, `${eventLine}\n`, "utf-8");
+	} catch (error) {
+		logInternalError("task-runner.background-log-write-failed", error as Error, `path=${bgLogPath}`);
+	}
+}
+
 export interface TaskRunnerInput {
 	manifest: TeamRunManifest;
 	tasks: TeamTaskState[];
@@ -413,7 +443,7 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 				// Ensure transcripts/ subdirectory exists before child-pi appends
 				// to it. appendTranscript uses O_APPEND (no mkdir) for security,
 				// so the caller must create the directory.
-				fs.mkdirSync(path.join(manifest.artifactsRoot, "transcripts"), {
+				await fs.promises.mkdir(path.join(manifest.artifactsRoot, "transcripts"), {
 					recursive: true,
 				});
 				const model = attemptModels[i];
@@ -460,18 +490,8 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 							({ task, tasks } = checkpointTask(manifest, tasks, task, "child-spawned", pid));
 							if (task.pendingSteers?.length) {
 								const steeringDir = `${manifest.artifactsRoot}/steering`;
-								fs.mkdirSync(steeringDir, { recursive: true });
-								const steeringPath = `${steeringDir}/${task.id}.jsonl`;
-								for (const msg of task.pendingSteers) {
-									fs.appendFileSync(
-										steeringPath,
-										JSON.stringify({
-											type: "steer",
-											message: msg,
-											ts: new Date().toISOString(),
-										}) + "\n",
-									);
-								}
+								// Fire-and-forget async write for steering events
+								void appendSteeringAsync(steeringDir, task.id, task.pendingSteers);
 								task.pendingSteers = [];
 								tasks = persistSingleTaskUpdate(manifest, tasks, task);
 							}
@@ -533,7 +553,8 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 								const bgLogPath = `${manifest.stateRoot}/background.log`;
 								const eventLine =
 									typeof event === "object" && !Array.isArray(event) ? JSON.stringify(event) : String(event);
-								fs.appendFileSync(bgLogPath, `${eventLine}\n`);
+								// Fire-and-forget async write for background log
+								void appendBackgroundLogAsync(bgLogPath, eventLine);
 							}
 							// Always keep in-memory agentProgress fresh (cheap) so the UI/events see
 							// the latest progress, but THROTTLE the disk persist. Previously this
@@ -1201,9 +1222,9 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		// stale manifest and overwrite this task's freshly-written artifacts, silently
 		// losing them. persistSingleTaskUpdate is re-entrance-safe (runLockHeldByUs guard),
 		// so nesting it inside this lock is a no-op re-acquire, not a deadlock.
-		withRunLockSync(manifest, () => {
-			saveRunManifest(manifest);
-			tasks = persistSingleTaskUpdate(manifest, tasks, task);
+		tasks = await withRunLock(manifest, async () => {
+			await saveRunManifestAsync(manifest);
+			return persistSingleTaskUpdate(manifest, tasks, task);
 		});
 		upsertCrewAgent(manifest, recordFromTask(manifest, task, runtimeKind));
 		// Execute task_result hook before emitting terminal event

package/src/runtime/team-runner.ts

@@ -12,7 +12,7 @@ import { hashArtifactContent as hashContent, writeArtifact } from "../state/arti
 import { appendEvent, appendEventAsync, appendEventBuffered, appendEventFireAndForget, flushEventLogBuffer } from "../state/event-log.ts";
 import { HealthStore } from "../state/health-store.ts";
 import { withRunLock } from "../state/locks.ts";
-import { loadRunManifestById, saveRunManifest, saveRunManifestAsync, saveRunTasksAsync, updateRunStatus } from "../state/state-store.ts";
+import { loadRunManifestById, saveRunManifestAsync, saveRunTasksAsync, updateRunStatus } from "../state/state-store.ts";
 import type { ArtifactDescriptor, PolicyDecision, TaskAttemptState, TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { aggregateUsage, formatTokens, formatUsage } from "../state/usage.ts";
 import type { TeamConfig } from "../teams/team-config.ts";
@@ -20,7 +20,7 @@ import { logInternalError } from "../utils/internal-error.ts";
 import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
 import { checkBranchFreshness } from "../worktree/branch-freshness.ts";
 import { buildSyntheticTerminalEvidence, CrewCancellationError, cancellationReasonFromSignal } from "./cancellation.ts";
-import { buildDispatchUnits, planCoalescedGroups } from "./coalesce-tasks.ts";
+import { buildDispatchUnits, type DispatchUnit, planCoalescedGroups } from "./coalesce-tasks.ts";
 import { resolveBatchConcurrency } from "./concurrency.ts";
 import { readCrewAgents, saveCrewAgents } from "./crew-agent-records.ts";
 import type { CrewRuntimeKind } from "./crew-agent-runtime.ts";
@@ -30,7 +30,6 @@ import { effectivenessPolicyDecision, evaluateRunEffectiveness, formatRunEffecti
 import { applyGoalAchievement, assessGoalAchievement } from "./goal-achievement.ts";
 import { deliverGroupJoin, resolveGroupJoinMode } from "./group-join.ts";
 import { terminateLiveAgentsForRun } from "./live-agent-manager.ts";
-import { mapConcurrent } from "./parallel-utils.ts";
 import { filterReadyByWriteOverlap } from "./path-overlap.ts";
 import { evaluateCrewPolicy, summarizePolicyDecisions } from "./policy-engine.ts";
 import { buildRecoveryLedger, shouldRerunFailedTask } from "./recovery-recipes.ts";
@@ -618,7 +617,7 @@ function isMutatingTask(task: TeamTaskState): boolean {
 	return permissionForRole(task.role) !== "read_only";
 }
 
-function ensurePlanApprovalRequested(manifest: TeamRunManifest, tasks: TeamTaskState[]): TeamRunManifest {
+async function ensurePlanApprovalRequested(manifest: TeamRunManifest, tasks: TeamTaskState[]): Promise<TeamRunManifest> {
 	if (manifest.planApproval) return manifest;
 	const assessTask = tasks.find((task) => task.stepId === "assess" && task.status === "completed");
 	// ROADMAP T1.2: for non-adaptive workflows, fall back to the most recent
@@ -637,7 +636,7 @@ function ensurePlanApprovalRequested(manifest: TeamRunManifest, tasks: TeamTaskS
 			planArtifactPath: planTask?.resultArtifact?.path,
 		},
 	};
-	saveRunManifest(updated);
+	await saveRunManifestAsync(updated);
 	appendEvent(updated.eventsPath, {
 		type: "plan.approval_required",
 		runId: updated.runId,
@@ -745,7 +744,7 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 	if (input.budgetAbort !== undefined) manifest.budgetAbort = input.budgetAbort;
 	if (input.budgetUnlimited !== undefined) manifest.budgetUnlimited = input.budgetUnlimited;
 	if (manifest.budgetTotal !== undefined && manifest.budgetTotal > 0 && !manifest.budgetUnlimited) {
-		saveRunManifest(manifest);
+		await saveRunManifestAsync(manifest);
 	}
 
 	void registerRunPromise(manifest.runId);
@@ -773,7 +772,7 @@ export async function executeTeamRun(input: ExecuteTeamRunInput): Promise<{ mani
 		if (gaApplied.manifest !== result.manifest) {
 			result.manifest = gaApplied.manifest;
 			try {
-				saveRunManifest(result.manifest);
+				await saveRunManifestAsync(result.manifest);
 			} catch (persistError) {
 				logInternalError(
 					"team-runner.goalAchievement.persist",
@@ -948,9 +947,9 @@ async function executeTeamRunCore(
 	const canInjectAdaptivePlan = workflow.name === "implementation";
 	let adaptivePlanInjected = false;
 	let adaptivePlanMissing = false;
-	const attemptAdaptivePlan = () => {
+	const attemptAdaptivePlan = async () => {
 		if (!canInjectAdaptivePlan || adaptivePlanInjected || adaptivePlanMissing) return { injected: false, missing: false };
-		const adaptivePlan = injectAdaptivePlanIfReady({
+		const adaptivePlan = await injectAdaptivePlanIfReady({
 			manifest,
 			tasks,
 			workflow,
@@ -965,7 +964,7 @@ async function executeTeamRunCore(
 			missing: adaptivePlan.missingPlan,
 		};
 	};
-	const initialAdaptive = attemptAdaptivePlan();
+	const initialAdaptive = await attemptAdaptivePlan();
 	if (initialAdaptive.missing) {
 		tasks = markBlocked(tasks, "Adaptive planner did not produce a valid subagent plan.");
 		await saveRunTasksAsync(manifest, tasks);
@@ -973,13 +972,13 @@ async function executeTeamRunCore(
 		return { manifest, tasks };
 	}
 	if (initialAdaptive.injected) {
-		manifest = requiresPlanApproval(workflow, input.runtimeConfig) ? ensurePlanApprovalRequested(manifest, tasks) : manifest;
+		manifest = requiresPlanApproval(workflow, input.runtimeConfig) ? await ensurePlanApprovalRequested(manifest, tasks) : manifest;
 		queueIndex = buildTaskGraphIndex(tasks);
 	} else if (
 		requiresPlanApproval(workflow, input.runtimeConfig) &&
 		(hasPendingMutatingAdaptiveTask(tasks) || hasPendingMutatingTaskAtBoundary(tasks))
 	) {
-		manifest = ensurePlanApprovalRequested(manifest, tasks);
+		manifest = await ensurePlanApprovalRequested(manifest, tasks);
 	}
 	if (manifest.planApproval?.status === "cancelled") {
 		tasks = cancelPlanTasks(tasks, "Plan approval was cancelled.");
@@ -1003,7 +1002,13 @@ async function executeTeamRunCore(
 	);
 	let wfMachine = createWorkflowStateMachine(workflowPhases);
 
-	while (tasks.some((task) => task.status === "queued")) {
+	// ── OPT-01 streaming dispatch: track in-flight dispatch units so a new
+	// task can be dispatched as soon as a slot frees, without waiting for
+	// the entire batch to complete. Each entry maps a unit key (singleton
+	// task ID or coalesced-group ID) to the in-flight promise + member IDs. ──
+	const pendingUnits = new Map<string, { taskIds: string[]; promise: Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> }>();
+
+	while (tasks.some((task) => task.status === "queued") || pendingUnits.size > 0) {
 		if (input.signal?.aborted) {
 			const cancelReason = cancellationReasonFromSignal(input.signal);
 			const message = `${cancelReason.message} (${cancelReason.code})`;
@@ -1202,26 +1207,39 @@ async function executeTeamRunCore(
 				},
 			});
 		}
+		// ── OPT-01 streaming dispatch: exclude tasks already in-flight, limit
+		// new dispatches to available concurrency slots. ──
+		const inFlightTaskIds = new Set<string>();
+		for (const pendingUnit of pendingUnits.values()) {
+			for (const taskId of pendingUnit.taskIds) inFlightTaskIds.add(taskId);
+		}
+		const slotsAvailable = Math.max(0, concurrency.maxConcurrent - pendingUnits.size);
 		const approvalPending = isPlanApprovalPending(manifest);
-		const readyIds = approvalPending ? serializedReady : serializedReady.slice(0, concurrency.selectedCount);
+		const dispatchableReady = serializedReady.filter((id) => !inFlightTaskIds.has(id));
+		const readyIds = approvalPending ? dispatchableReady : dispatchableReady.slice(0, slotsAvailable);
 		const candidateBatch = readyIds
 			.map((id) => tasks.find((task) => task.id === id))
 			.filter((task): task is TeamTaskState => Boolean(task));
 		const readyBatch = approvalPending
-			? candidateBatch.filter((task) => !isMutatingTask(task)).slice(0, concurrency.selectedCount)
+			? candidateBatch.filter((task) => !isMutatingTask(task)).slice(0, slotsAvailable)
 			: candidateBatch;
 		if (readyBatch.length === 0) {
-			if (approvalPending && candidateBatch.some(isMutatingTask)) {
+			if (pendingUnits.size > 0) {
+				// Tasks are in-flight — skip dispatch and proceed to wait phase.
+				// (No return; code falls through to the dispatch section which is
+				// a no-op with an empty readyBatch, then reaches the wait phase.)
+			} else if (approvalPending && candidateBatch.some(isMutatingTask)) {
 				await saveRunTasksAsync(manifest, tasks);
 				saveCrewAgents(manifest, recordsForMaterializedTasks(manifest, tasks, runtimeKind));
 				manifest = updateRunStatus(manifest, "blocked", "Plan approval required before mutating implementation tasks run.");
 				return { manifest, tasks };
+			} else {
+				tasks = markBlocked(tasks, "No ready queued task; dependency graph may be invalid.");
+				await saveRunTasksAsync(manifest, tasks);
+				saveCrewAgents(manifest, recordsForMaterializedTasks(manifest, tasks, runtimeKind));
+				manifest = updateRunStatus(manifest, "blocked", "No ready queued task.");
+				return { manifest, tasks };
 			}
-			tasks = markBlocked(tasks, "No ready queued task; dependency graph may be invalid.");
-			await saveRunTasksAsync(manifest, tasks);
-			saveCrewAgents(manifest, recordsForMaterializedTasks(manifest, tasks, runtimeKind));
-			manifest = updateRunStatus(manifest, "blocked", "No ready queued task.");
-			return { manifest, tasks };
 		}
 
 		// 2.2 caller migration: batch progress is high-frequency informational (M7 wire).
@@ -1311,7 +1329,10 @@ async function executeTeamRunCore(
 			);
 		}
 
-		const results = await mapConcurrent(dispatchUnits, concurrency.selectedCount, async (unit) => {
+		// ── OPT-01 streaming dispatch: dispatch each unit into pendingUnits
+		// instead of awaiting the entire batch via mapConcurrent. Each unit's
+		// promise is stored so we can Promise.race on the next iteration. ──
+		const dispatchUnit = async (unit: DispatchUnit): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> => {
 			// M6 real dispatch path: single worker for N tasks.
 			if (unit.kind === "group") {
 				const groupTasks = unit.group.tasks;
@@ -1533,30 +1554,52 @@ async function executeTeamRunCore(
 					}),
 				);
 			}
-		});
-		if (results.length === 0) {
-			// F1: results is empty ONLY when every ready task was hook-skipped
-			// (batchTasks -> dispatchUnits empty). The skipped tasks are now terminal,
-			// so their downstream dependents become ready on the next iteration.
-			// Re-loop (continue) instead of breaking: breaking would skip those
-			// downstream tasks and fall through to a false-green "completed" run
-			// with queued tasks left behind. Terminates: each skipped task leaves
-			// "queued", so the queued set strictly shrinks; a stuck graph (ready
-			// empty but queued remain) is caught by the readyBatch.length===0
-			// guard above which marks the run "blocked".
-			continue;
-		}
-		// FIX: Filter out undefined entries from partial results when error occurred
-		// during parallel execution. Other workers may have written partial results
-		// before one threw. Results may be partial - some tasks in-flight at error
-		// time will not have entries in the results array.
-		const validResults = results.filter((item): item is NonNullable<typeof item> => item !== undefined);
-		// Guard: if ALL parallel workers threw before returning, validResults is empty.
-		// at(-1)! would crash. Mark the run failed rather than crashing.
-		if (validResults.length === 0) {
-			manifest = updateRunStatus(manifest, "failed", "All parallel tasks failed catastrophically.");
-			return { manifest, tasks };
+		};
+		// ── OPT-01 streaming dispatch: dispatch units into pendingUnits ──
+		for (const unit of dispatchUnits) {
+			const unitKey = unit.kind === "singleton" ? unit.taskId : unit.group.id;
+			const unitTaskIds = unit.kind === "singleton" ? [unit.taskId] : unit.group.tasks.map((t) => t.id);
+			pendingUnits.set(unitKey, {
+				taskIds: unitTaskIds,
+				promise: dispatchUnit(unit),
+			});
 		}
+
+		// ── OPT-01 wait phase: if no units are in-flight (e.g. all ready tasks
+		// were hook-skipped or readyBatch was empty), re-loop to re-evaluate. ──
+		if (pendingUnits.size === 0) continue;
+
+		// Wait for ONE in-flight unit to complete. Promise.race returns as soon
+		// as the first wrapper resolves — others remain pending in pendingUnits
+		// and are re-raced on the next iteration.
+		const settled = await Promise.race(
+			[...pendingUnits.entries()].map(async ([key, pending]) => {
+				try {
+					const result = await pending.promise;
+					return {
+						unitKey: key,
+						result: result as { manifest: TeamRunManifest; tasks: TeamTaskState[] } | undefined,
+						error: undefined as Error | undefined,
+					};
+				} catch (error) {
+					return { unitKey: key, result: undefined, error: error instanceof Error ? error : new Error(String(error)) };
+				}
+			}),
+		);
+		const completedUnit = pendingUnits.get(settled.unitKey)!;
+		pendingUnits.delete(settled.unitKey);
+
+		// Build the single result to merge. On rejection, synthesize a failed
+		// result so the run continues (mirrors the old validResults guard).
+		const resultToMerge: { manifest: TeamRunManifest; tasks: TeamTaskState[] } = settled.result ?? {
+			manifest,
+			tasks: tasks.map((t) =>
+				completedUnit.taskIds.includes(t.id)
+					? { ...t, status: "failed" as const, error: settled.error!.message, finishedAt: new Date().toISOString() }
+					: t,
+			),
+		};
+		const validResults = [resultToMerge];
 		// Reconstruct manifest from the last worker's snapshot. The .artifacts field
 		// is re-merged from both the team-runner's in-memory state and all workers'
 		// snapshots, so artifact writes by task-runner (which individually save manifest
@@ -1722,7 +1765,7 @@ async function executeTeamRunCore(
 			}
 		}
 
-		const cancelledResult = results.find((item) => item.manifest.status === "cancelled");
+		const cancelledResult = resultToMerge.manifest.status === "cancelled" ? resultToMerge : undefined;
 		if (cancelledResult || input.signal?.aborted) {
 			const reason = input.signal?.aborted ? cancellationReasonFromSignal(input.signal) : undefined;
 			const message = reason?.message ?? cancelledResult?.manifest.summary ?? "Run cancelled during task execution.";
@@ -1761,7 +1804,7 @@ async function executeTeamRunCore(
 			return { manifest, tasks: reCancelledTasks };
 		}
 		queueIndex = buildTaskGraphIndex(tasks);
-		const injectedAfterBatch = attemptAdaptivePlan();
+		const injectedAfterBatch = await attemptAdaptivePlan();
 		if (injectedAfterBatch.missing) {
 			tasks = markBlocked(tasks, "Adaptive planner did not produce a valid subagent plan.");
 			await saveRunTasksAsync(manifest, tasks);
@@ -1770,13 +1813,13 @@ async function executeTeamRunCore(
 			return { manifest, tasks };
 		}
 		if (injectedAfterBatch.injected) {
-			manifest = requiresPlanApproval(workflow, input.runtimeConfig) ? ensurePlanApprovalRequested(manifest, tasks) : manifest;
+			manifest = requiresPlanApproval(workflow, input.runtimeConfig) ? await ensurePlanApprovalRequested(manifest, tasks) : manifest;
 			queueIndex = buildTaskGraphIndex(tasks);
 		} else if (
 			requiresPlanApproval(workflow, input.runtimeConfig) &&
 			(hasPendingMutatingAdaptiveTask(tasks) || hasPendingMutatingTaskAtBoundary(tasks))
 		) {
-			manifest = ensurePlanApprovalRequested(manifest, tasks);
+			manifest = await ensurePlanApprovalRequested(manifest, tasks);
 		}
 		if (manifest.planApproval?.status === "cancelled") {
 			tasks = cancelPlanTasks(tasks, "Plan approval was cancelled.");
@@ -1787,17 +1830,17 @@ async function executeTeamRunCore(
 		}
 		await saveRunTasksAsync(manifest, tasks);
 		saveCrewAgents(manifest, recordsForMaterializedTasks(manifest, tasks, runtimeKind));
-		const completedBatch = tasks.filter((t) => batchTasks.some((bt) => bt.id === t.id));
+		const completedBatch = tasks.filter((t) => completedUnit.taskIds.includes(t.id));
 		const batchArtifact = writeArtifact(manifest.artifactsRoot, {
 			kind: "summary",
-			relativePath: `batches/${batchTasks.map((task) => task.id).join("+")}.md`,
+			relativePath: `batches/${completedUnit.taskIds.join("+")}.md`,
 			producer: "team-runner",
 			content: aggregateTaskOutputs(completedBatch, manifest),
 		});
 		const groupDelivery = deliverGroupJoin({
 			manifest,
 			mode: resolveGroupJoinMode(input.runtimeConfig),
-			batch: batchTasks,
+			batch: completedBatch,
 			allTasks: tasks,
 		});
 		manifest = {

package/src/schema/team-tool-schema.ts

@@ -382,6 +382,10 @@ export interface TeamToolParamsValue {
 	cron?: string;
 	interval?: number;
 	once?: string | number;
+
+	// schedule sub-actions (removal/toggle/update of an existing job)
+	subAction?: string;
+	jobId?: string;
 	/** Mark certain bash commands as excludeFromContext to reduce context tokens (default: false). */
 	excludeContextBash?: boolean;
 	/** Total token budget for the run. When set, enables budget tracking (minimum 1000). */

package/src/state/atomic-write.ts

@@ -11,7 +11,11 @@ function hashContent(content: string): string {
 }
 
 const RETRYABLE_RENAME_CODES = new Set(["EPERM", "EBUSY", "EACCES"]);
-const RETRYABLE_LINK_CODES = new Set(["EPERM", "EBUSY", "EACCES", "ENOENT"]);
+// EEXIST is retryable: two concurrent async saves (OPT-02 async saveRunManifest)
+// can race on unlink+link — the second link() hits EEXIST because the first
+// already created the destination. The retry loop unlinks and re-links,
+// resolving the race. Exponential backoff + jitter prevents starvation.
+const RETRYABLE_LINK_CODES = new Set(["EPERM", "EBUSY", "EACCES", "ENOENT", "EEXIST"]);
 
 /**
  * Symlink-safe file write guard (caveman-inspired).