pi-crew 0.9.68 → 0.10.2

package/src/runtime/run-tracker.ts

@@ -5,21 +5,38 @@ import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { projectCrewRoot } from "../utils/paths.ts";
 import { isFinishedRunStatus } from "./process-status.ts";
 
+export interface RunWaitResult {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	/** True when the waiter was released early by `detachRunPromise` while the
+	 *  run itself keeps executing (see that function). */
+	detached?: boolean;
+}
+
 export interface ActiveRunPromise {
-	promise: Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }>;
-	resolve: (value: { manifest: TeamRunManifest; tasks: TeamTaskState[] }) => void;
+	promise: Promise<RunWaitResult>;
+	resolve: (value: RunWaitResult) => void;
 	reject: (reason: unknown) => void;
 }
 
 const activeRunPromises = new Map<string, ActiveRunPromise>();
 
+/**
+ * Runs whose waiter should be released on its next opportunity.
+ *
+ * A detach request can arrive BEFORE `executeTeamRun` registers its foreground
+ * promise (the tool starts the run and calls `waitForRun` immediately, so a
+ * slow-starting run puts the waiter on the polling path with no promise to
+ * resolve). The flag makes the request path-independent: the polling loop
+ * consumes it just like `detachRunPromise` resolves a registered promise.
+ */
+const detachRequests = new Set<string>();
+
 export function registerRunPromise(runId: string): ActiveRunPromise {
-	let resolve!: (value: { manifest: TeamRunManifest; tasks: TeamTaskState[] }) => void;
+	detachRequests.delete(runId);
+	let resolve!: (value: RunWaitResult) => void;
 	let reject!: (reason: unknown) => void;
-	const promise = new Promise<{
-		manifest: TeamRunManifest;
-		tasks: TeamTaskState[];
-	}>((res, rej) => {
+	const promise = new Promise<RunWaitResult>((res, rej) => {
 		resolve = res;
 		reject = rej;
 	});
@@ -28,7 +45,41 @@ export function registerRunPromise(runId: string): ActiveRunPromise {
 	return entry;
 }
 
-export function resolveRunPromise(runId: string, result: { manifest: TeamRunManifest; tasks: TeamTaskState[] }): void {
+/**
+ * Release a foreground waiter WITHOUT stopping the run.
+ *
+ * A foreground `team run` keeps the parent pi turn streaming for the whole run,
+ * and pi's `switchSession` tears the current session down via
+ * `session.abort()` → `waitForIdle()`. Opening an agent view therefore hung
+ * silently until the run finished. Detaching resolves the tool's `waitForRun`
+ * with the run's current (still-running) state so the tool call returns, the
+ * parent turn can settle, and the session switch lands — `executeTeamRun`
+ * itself keeps going in this process and the async notifier reports completion.
+ *
+ * Returns false only when the run's state cannot be read at all. When no
+ * foreground promise is registered yet (or the waiter is on the polling path),
+ * the request is recorded and consumed by `waitForRun` on its next poll.
+ */
+export function detachRunPromise(runId: string, cwd: string): boolean {
+	const loaded = loadRunManifestById(cwd, runId);
+	if (!loaded) return false;
+	const entry = activeRunPromises.get(runId);
+	if (entry) {
+		activeRunPromises.delete(runId);
+		detachRequests.delete(runId);
+		entry.resolve({ ...loaded, detached: true });
+		return true;
+	}
+	detachRequests.add(runId);
+	return true;
+}
+
+/** True while a detach was requested but no waiter has consumed it yet. */
+export function hasPendingRunDetach(runId: string): boolean {
+	return detachRequests.has(runId);
+}
+
+export function resolveRunPromise(runId: string, result: RunWaitResult): void {
 	const entry = activeRunPromises.get(runId);
 	if (entry) {
 		entry.resolve(result);
@@ -54,15 +105,22 @@ export async function waitForRun(
 	runId: string,
 	cwd: string,
 	options: { timeoutMs?: number; pollIntervalMs?: number } = {},
-): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
+): Promise<RunWaitResult> {
 	const { timeoutMs = 300_000, pollIntervalMs = 500 } = options;
 	const deadline = Date.now() + timeoutMs;
 
+	// A detach requested before this waiter existed applies to it (and is
+	// consumed here, so it can never leak onto a later waiter for the same run).
+	const detachPending = detachRequests.delete(runId);
+
 	// Fast path: already terminal on disk
 	const loaded = loadRunManifestById(cwd, runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency;
 	if (loaded && isFinishedRunStatus(loaded.manifest.status)) {
 		return loaded;
 	}
+	if (detachPending && loaded) {
+		return { ...loaded, detached: true };
+	}
 
 	// Medium path: foreground promise registered in this process
 	const entry = activeRunPromises.get(runId);
@@ -78,9 +136,17 @@ export async function waitForRun(
 		}
 	}
 
-	// Slow path: background run — poll with exponential backoff capped at pollIntervalMs
+	// Slow path: background run — poll with exponential backoff capped at pollIntervalMs.
+	// This path is ALSO taken by a foreground run whose executeTeamRun has not
+	// registered its promise yet (the tool calls waitForRun immediately after
+	// starting the run), so it must honour a pending detach request too —
+	// otherwise opening an agent view can never release the parent turn.
 	let attempt = 0;
 	while (Date.now() < deadline) {
+		if (detachRequests.delete(runId)) {
+			const current = loadRunManifestById(cwd, runId);
+			if (current) return { ...current, detached: true };
+		}
 		if (attempt === 0) {
 			// Early exit: if the run directory doesn't exist, don't waste time polling.
 			// Use projectCrewRoot() to honour the .pi/teams/ fallback for .pi-based
@@ -109,6 +175,7 @@ export function hasActiveRunPromise(runId: string): boolean {
 }
 
 export function clearRunPromisesForTest(): void {
+	detachRequests.clear();
 	for (const entry of activeRunPromises.values()) {
 		entry.reject(new Error("Cleared by test"));
 	}

package/src/runtime/scheduler-context.ts

@@ -0,0 +1,98 @@
+/**
+ * Scheduler context types for the team-run scheduler loop.
+ *
+ * Extracted from team-runner.ts (2026-08, Phase 2.6 maintainability split —
+ * CORE-4 scheduler context, resolves RT-15). Pure type motion: SettledUnit /
+ * PendingUnit / SchedulerContext / SchedulerDecision moved verbatim.
+ */
+
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import type { WorkflowConfig } from "../workflows/workflow-config.ts";
+import type { CrewRuntimeKind } from "./crew-agent-runtime.ts";
+import type { BatchConcurrencyDecision } from "./scheduling/concurrency.ts";
+import type { TaskGraphIndex, TaskGraphSchedulerSnapshot } from "./scheduling/task-graph-scheduler.ts";
+import type { ResultArtifactReadCache } from "./task-output-context.ts";
+// ExecuteTeamRunInput is defined in team-runner.ts — import type ONLY so the
+// type-level team-runner↔scheduler-context reference is erased at runtime
+// (no runtime import cycle; team-runner.ts imports these types back).
+import type { ExecuteTeamRunInput } from "./team-runner.ts";
+import type { WorkflowStateMachine } from "./workflow-state.ts";
+
+/** RT-12: result shape from a settled dispatch unit (pre-created wrapper). */
+export type SettledUnit = {
+	unitKey: string;
+	result: { manifest: TeamRunManifest; tasks: TeamTaskState[] } | undefined;
+	error: Error | undefined;
+};
+
+/**
+ * RT-12: in-flight dispatch unit. `wrapped` is a pre-created wrapper promise
+ * (try/catch → SettledUnit) so mergeUnitResult can Promise.race without
+ * allocating new async closures every loop iteration (O(C) total wrappers
+ * instead of O(C×T) churn).
+ */
+export type PendingUnit = {
+	taskIds: string[];
+	promise: Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }>;
+	wrapped: Promise<SettledUnit>;
+};
+
+// ── CORE-4: SchedulerContext state bag ─────────────────────────────
+// A mutable bag of the closure locals used across executeTeamRunCore.
+// Extracted scheduler functions receive this context and mutate it
+// in-place. This enables incremental extraction of the ~1075-line god
+// function into scheduler/ functions without changing control flow.
+
+/**
+ * Mutable state shared across the team-run scheduler loop.
+ *
+ * Fields mirror the closure locals of `executeTeamRunCore`. Extracted
+ * scheduler functions mutate these fields in-place; the caller keeps the
+ * local variables in sync by assigning back from `ctx` after each call.
+ */
+export interface SchedulerContext {
+	input: ExecuteTeamRunInput;
+	workflow: WorkflowConfig;
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	queueIndex: TaskGraphIndex;
+	wfMachine: WorkflowStateMachine;
+	pendingUnits: Map<string, PendingUnit>;
+	/** Task ids ever dispatched (grows monotonically; never removed). Used by
+	 * terminaliseRunWithDrain to cancel — not skip — tasks that were in-flight
+	 * even after their dispatch unit settled + left pendingUnits (RT-NEW-2 race). */
+	dispatchedTaskIds: Set<string>;
+	runController: AbortController;
+	runtimeKind: CrewRuntimeKind;
+	adaptivePlanInjected: boolean;
+	adaptivePlanMissing: boolean;
+	/** Outcome of the most recent mergeUnitResult call: the settled unit's
+	 * taskIds and the merged result object. Read by the post-merge inline
+	 * logic (cancel-during-exec check + batch summary). Set by extraction 5. */
+	settledMerge: { taskIds: string[]; result: { manifest: TeamRunManifest; tasks: TeamTaskState[] } } | null;
+	/** R10-1: per-run result-artifact read cache (single instance, created in
+	 *  executeTeamRunCore). Shared by closeout aggregation and — via baseInput
+	 *  in dispatch-batch.ts — dependency-context reads in prepareTaskExecutionContext. */
+	resultReadCache: ResultArtifactReadCache;
+}
+
+/**
+ * Discriminated union representing a scheduler sub-function's decision.
+ *
+ * - `continue`: proceed to the next phase of the loop body.
+ * - `return`: short-circuit the loop and return the given result.
+ * - `skip-dispatch`: skip the dispatch phase this iteration (reserved for
+ *   future extractions).
+ */
+export type SchedulerDecision =
+	| { kind: "continue" }
+	| { kind: "return"; result: { manifest: TeamRunManifest; tasks: TeamTaskState[] } }
+	| { kind: "skip-dispatch" }
+	| {
+			kind: "dispatch";
+			batch: TeamTaskState[];
+			concurrency: BatchConcurrencyDecision;
+			snapshot: TaskGraphSchedulerSnapshot;
+			approvalPending: boolean;
+			coalesceEnabled: boolean;
+	  };

package/src/runtime/scheduling/coalesce-tasks.ts

@@ -91,6 +91,11 @@ export function planCoalescedGroups(
 		// doesn't compose in a multi-task worker. These flags set up side
 		// effects per-task that can't be combined.
 		if (step.worktree) continue;
+		// T4/R6 (round-1 P2): spec-carrying steps never coalesce — the coalesced
+		// path bypasses buildTaskPacket/finalizeTaskResult, which would silently
+		// drop the snapshot freeze, the SPEC contract prompt block, and the gate.
+		if (step.specRefs?.length) continue;
+		if (step.specStrict === true) continue;
 		if (step.preStepScript) continue;
 		if (step.verify) continue;
 		if (step.output !== undefined && step.output !== false && step.output !== "") continue;

package/src/runtime/scheduling/global-worker-cap.ts

@@ -22,6 +22,7 @@
  */
 
 import * as os from "node:os";
+import { getCrewEnv } from "../../config/env-vars.ts";
 import { Semaphore } from "./semaphore.ts";
 
 /**
@@ -30,7 +31,7 @@ import { Semaphore } from "./semaphore.ts";
  * rather than silently disabling the cap.
  */
 function resolveCapacity(): number {
-	const env = process.env.PI_CREW_MAX_WORKERS;
+	const env = getCrewEnv("PI_CREW_MAX_WORKERS");
 	if (env !== undefined && env !== "") {
 		const parsed = Number.parseInt(env, 10);
 		if (Number.isFinite(parsed) && parsed > 0) {

package/src/runtime/scheduling/nested-slots.ts

@@ -0,0 +1,70 @@
+/**
+ * Nested-slot budget for delegate-spawned grandchildren (ADR-5 §2, WP-5 step 3).
+ *
+ * Grandchildren NEVER ride the global worker semaphore — a waiting parent
+ * worker keeps holding its own global slot, so ride-along spawn is the
+ * permanent-deadlock shape the repo already records for the judge
+ * (`scheduling/global-worker-cap.ts:14-19` MAJ#3). Instead the root-side
+ * delegate handler draws from THIS separate budget:
+ *
+ *   max = max(1, floor(globalSem / 2))    (or an explicit config override)
+ *
+ * FAIL-FAST, NEVER QUEUE: when the budget is exhausted, `tryAcquire` returns
+ * false immediately — the caller rejects the delegate with a policy message
+ * ("nested spawn budget exhausted; N/M in flight"). No waiting, no queueing.
+ *
+ * The budget is owned by the single root-side delegate handler process, so an
+ * in-memory id-keyed map is the source of truth (no disk state).
+ */
+
+export interface NestedSlotSnapshot {
+	used: number;
+	max: number;
+}
+
+/** Compute the nested-slot budget from the global worker semaphore. */
+export function defaultNestedSlotBudget(globalWorkerSemaphore: number): number {
+	return Math.max(1, Math.floor(globalWorkerSemaphore / 2));
+}
+
+export class NestedSlotBudget {
+	private readonly held = new Set<string>();
+	readonly max: number;
+
+	constructor(globalWorkerSemaphore: number, override?: number) {
+		if (override !== undefined && (!Number.isFinite(override) || override < 1)) {
+			throw new TypeError(`nesting.maxSlots must be a positive integer, got ${String(override)}`);
+		}
+		this.max = override ?? defaultNestedSlotBudget(globalWorkerSemaphore);
+	}
+
+	/**
+	 * Try to reserve one nested slot for the given grandchild id.
+	 * Fail-fast: returns false when the budget is exhausted — the caller MUST
+	 * reject the delegate immediately (never queue).
+	 */
+	tryAcquire(grandchildId: string): boolean {
+		if (this.held.has(grandchildId)) return true; // idempotent re-acquire
+		if (this.held.size >= this.max) return false;
+		this.held.add(grandchildId);
+		return true;
+	}
+
+	/** Release the slot held by a finished/dead grandchild. Idempotent. */
+	release(grandchildId: string): void {
+		this.held.delete(grandchildId);
+	}
+
+	get used(): number {
+		return this.held.size;
+	}
+
+	/** Human-facing status line for policy messages: "N/M in flight". */
+	get statusLine(): string {
+		return `${this.held.size}/${this.max} in flight`;
+	}
+
+	snapshot(): NestedSlotSnapshot {
+		return { used: this.held.size, max: this.max };
+	}
+}

package/src/runtime/scheduling/run-coalesced-task-group.ts

@@ -2,7 +2,7 @@ import type { AgentConfig } from "../../agents/agent-config.ts";
 import type { CrewReliabilityConfig, CrewRuntimeConfig } from "../../config/types.ts";
 import { appendEventAsync } from "../../state/event-log/event-log.ts";
 import { writeArtifact } from "../../state/stores/artifact-store.ts";
-import { saveRunTasksAsync, updateRunStatus } from "../../state/stores/state-store.ts";
+import { loadRunManifestById, saveRunTasksAsync, updateRunStatus } from "../../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
 import type { WorkflowStep } from "../../workflows/workflow-config.ts";
 import { createWorkerHeartbeat, touchWorkerHeartbeat } from "../heartbeat/worker-heartbeat.ts";
@@ -115,17 +115,12 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 			heartbeatInFlight = true;
 			heartbeatPromise = (async () => {
 				try {
-					updatedTasks = updatedTasks.map((t) => {
-						if (!taskIds.includes(t.id)) return t;
-						// FIND-06 belt-and-suspenders: never replace terminal state or its
-						// resultArtifact with a heartbeat-only snapshot.
-						if (t.status === "completed" || t.status === "failed" || t.status === "cancelled") return t;
-						return {
-							...t,
-							heartbeat: touchWorkerHeartbeat(t.heartbeat ?? createWorkerHeartbeat(t.id), { alive: true }),
-						};
-					});
-					await saveRunTasksAsync(manifest, updatedTasks);
+					// R15-3: persist heartbeats for ONLY this group's tasks via a fresh
+					// disk read. The old closure `updatedTasks` is a dispatch-time
+					// snapshot of the FULL task array — a sibling cancelled on disk after
+					// dispatch could be un-cancelled by a late heartbeat save (the map
+					// only mutated group tasks, but the SAVE wrote the whole stale array).
+					await persistGroupHeartbeats(manifest, taskIds);
 				} catch {
 					// Run may have been pruned mid-dispatch — best-effort only.
 				} finally {
@@ -134,9 +129,12 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 					// save was in flight, re-write the (now-terminal) updatedTasks so
 					// our late snapshot cannot leave stale pre-terminal state on disk.
 					// Runs after our own save resolves, so it always lands last.
+					// R15-3: the repair now fresh-reads disk and re-applies ONLY the
+					// group's terminal state — the old full-array write could resurrect
+					// a sibling cancelled on disk (same flaw as the heartbeat save).
 					if (finalWriteStarted) {
 						try {
-							await saveRunTasksAsync(manifest, updatedTasks);
+							await repairGroupTerminalWrite(manifest, taskIds, updatedTasks);
 						} catch {
 							// best-effort repair — same swallow policy as the heartbeat.
 						}
@@ -298,6 +296,59 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 	return { manifest: updatedManifest, tasks: updatedTasks, taskIds, rawOutput, success };
 }
 
+/**
+ * R15-3: heartbeat save scoped to this coalesced group only.
+ *
+ * Previously the heartbeat wrote the dispatch-time closure `updatedTasks` —
+ * the FULL task array including sibling tasks outside this group. A sibling
+ * cancelled on disk after dispatch (external cancel / reconciler) could be
+ * un-cancelled ("resurrected") by a late heartbeat save, because the map only
+ * mutated group tasks but the SAVE wrote the whole stale array. Fix: fresh
+ * re-read tasks from disk (loadRunManifestById — the established fresh-read
+ * pattern used by team-runner) and write back ONLY the group's own task ids
+ * with heartbeats touched; sibling tasks are preserved untouched from the
+ * fresh disk read. Keeps the FIND-06 'never replace terminal state' guard.
+ */
+async function persistGroupHeartbeats(manifest: TeamRunManifest, taskIds: string[]): Promise<void> {
+	const fresh = loadRunManifestById(manifest.cwd, manifest.runId);
+	if (!fresh) return; // run pruned mid-dispatch — best-effort only.
+	const merged = fresh.tasks.map((t) => {
+		if (!taskIds.includes(t.id)) return t; // sibling tasks: preserved untouched.
+		// FIND-06 belt-and-suspenders: never replace terminal state or its
+		// resultArtifact with a heartbeat-only snapshot.
+		if (t.status === "completed" || t.status === "failed" || t.status === "cancelled") return t;
+		return {
+			...t,
+			heartbeat: touchWorkerHeartbeat(t.heartbeat ?? createWorkerHeartbeat(t.id), { alive: true }),
+		};
+	});
+	await saveRunTasksAsync(manifest, merged);
+}
+
+/**
+ * R15-3: FIND-06 P1 repair — re-apply the group's terminal state after a late
+ * heartbeat save may have landed last. Fresh-reads disk so sibling tasks are
+ * preserved untouched; only the group's own terminal state from `updatedTasks`
+ * is re-applied, and a disk-terminal group task is never flipped (same
+ * belt-and-suspenders guard as the heartbeat).
+ */
+async function repairGroupTerminalWrite(manifest: TeamRunManifest, taskIds: string[], updatedTasks: TeamTaskState[]): Promise<void> {
+	const fresh = loadRunManifestById(manifest.cwd, manifest.runId);
+	if (!fresh) return; // run pruned mid-dispatch — best-effort only.
+	const groupById = new Map(updatedTasks.map((t) => [t.id, t] as const));
+	const merged = fresh.tasks.map((t) => {
+		if (!taskIds.includes(t.id)) return t; // sibling tasks: preserved untouched.
+		if (t.status === "completed" || t.status === "failed" || t.status === "cancelled") return t;
+		return groupById.get(t.id) ?? t;
+	});
+	await saveRunTasksAsync(manifest, merged);
+}
+
+/** @internal 3.5 R15-3 test export — exercise the heartbeat/repair writes directly. */
+export const __test__persistGroupHeartbeats = persistGroupHeartbeats;
+/** @internal 3.5 R15-3 test export — exercise the terminal repair write directly. */
+export const __test__repairGroupTerminalWrite = repairGroupTerminalWrite;
+
 async function buildCoalescedPrompt(
 	manifest: TeamRunManifest,
 	step: WorkflowStep,

package/src/runtime/scheduling/task-graph-scheduler.ts

@@ -48,16 +48,6 @@ export function buildTaskGraphIndex(tasks: TeamTaskState[]): TaskGraphIndex {
 	return fresh;
 }
 
-/** Test/diagnostic helper — invalidate the WeakMap-backed index cache. Not
- *  used by production code paths; the WeakMap self-invalidates when a tasks
- *  array goes out of scope. Provided for parity with `clearStablePrefixCache`. */
-export function clearTaskGraphIndexCache(): void {
-	// WeakMap has no `.clear()`; rely on GC. Exposed as a no-op stub so callers
-	// that import `clearStablePrefixCache` (also a no-op stub for symmetry) can
-	// adopt a parallel API if needed in the future. Documented as no-op rather
-	// than removed so the API stays discoverable.
-}
-
 function taskById(tasks: TeamTaskState[]): Map<string, TeamTaskState> {
 	return new Map(tasks.map((task) => [task.id, task]));
 }