pi-crew 0.9.67 → 0.10.1

package/src/runtime/plan-replan.ts

@@ -0,0 +1,151 @@
+/**
+ * T2/R4 (ADR-4 §4) — re-plan sweep: dropped-item soft-cancel.
+ *
+ * Every scheduler tick (selectDispatchBatch, after the ask-deadline sweep)
+ * checks the CURRENT plan revision for `dropped` items and reconciles their
+ * tasks:
+ *  - QUEUED tasks are cancelled outright (never dispatched — the re-plan
+ *    removed their reason to exist).
+ *  - RUNNING / WAITING / NEEDS_ATTENTION tasks get a SOFT cancel: a wrap-up
+ *    advisory appended to the worker's steering file (the same JSONL contract
+ *    as `team steer` and the ChildPiSteeringController soft limit — advisory
+ *    first, the existing maxTurns+grace machinery stays the hard enforcement).
+ *    `task.replanDroppedAt` stamps the advisory as issued (exactly-once across
+ *    ticks) and doubles as the terminal marker "cancelled-by-replan".
+ *  - A `plan.item.dropped` event is appended per affected task.
+ *
+ * Reload+persist discipline mirrors sweepExpiredWaitingTasks: best-effort
+ * reload, all mutations under withRunLockSync with a fresh in-lock reload,
+ * save only when something changed. Never throws into the scheduler tick —
+ * failures are logged and the sweep returns undefined (next tick retries).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { withRunLockSync } from "../state/coordination/locks.ts";
+import { appendEvent } from "../state/event-log/event-log.ts";
+import { getCurrentPlanRecord } from "../state/stores/plan-store.ts";
+import { loadRunManifestById, saveRunManifest, saveRunTasks } from "../state/stores/state-store.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+
+export interface DroppedPlanSweepResult {
+	manifest: TeamRunManifest;
+	tasks: TeamTaskState[];
+	cancelledTaskIds: string[];
+	advisedTaskIds: string[];
+}
+
+const WRAP_UP_ADVISORY =
+	"Plan item dropped by a newer plan revision (re-plan). Wrap up immediately — provide your best final answer now; this task will not be continued.";
+
+function appendSteeringAdvisory(manifest: TeamRunManifest, taskId: string): boolean {
+	try {
+		const steeringDir = path.join(manifest.artifactsRoot, "steering");
+		fs.mkdirSync(steeringDir, { recursive: true });
+		const safePath = resolveRealContainedPath(steeringDir, `${taskId}.jsonl`);
+		// Same 256KB growth cap as the steer tool (subagent-tools.ts) — refuse
+		// loudly rather than poisoning the next incarnation's first poll.
+		try {
+			if (fs.statSync(safePath).size > 256 * 1024) {
+				logInternalError("plan-replan.steer-refused-too-large", new Error("steering file over cap"), `taskId=${taskId}`);
+				return false;
+			}
+		} catch {
+			/* no file yet — fine */
+		}
+		fs.appendFileSync(
+			safePath,
+			`${JSON.stringify({ type: "steer", message: WRAP_UP_ADVISORY, ts: new Date().toISOString() })}\n`,
+			"utf-8",
+		);
+		return true;
+	} catch (error) {
+		logInternalError("plan-replan.steer-write-failed", error instanceof Error ? error : new Error(String(error)), `taskId=${taskId}`);
+		return false;
+	}
+}
+
+/**
+ * Takes the scheduler's IN-MEMORY manifest+tasks (selectDispatchBatch already
+ * holds both) — NO disk load on the no-op path. The per-tick cost for runs
+ * without plan-linked tasks is one array scan; plans.json is only read when a
+ * task carries planItem, and the reload+persist below only runs when an
+ * affected task actually exists.
+ */
+export function sweepDroppedPlanItems(initialManifest: TeamRunManifest, initialTasks: TeamTaskState[]): DroppedPlanSweepResult | undefined {
+	// Cheap exits FIRST (no I/O): no plan-linked tasks at all.
+	if (!initialTasks.some((t) => t.planItem)) return undefined;
+	const record = getCurrentPlanRecord(initialManifest);
+	if (!record) return undefined;
+	const dropped = new Set(record.items.filter((i) => i.status === "dropped").map((i) => i.id));
+	if (dropped.size === 0) return undefined;
+	if (!initialTasks.some((t) => t.planItem && dropped.has(t.planItem))) return undefined;
+
+	const cwd = initialManifest.cwd;
+	const runId = initialManifest.runId;
+	const cancelledTaskIds: string[] = [];
+	const advisedTaskIds: string[] = [];
+	try {
+		const outcome = withRunLockSync(initialManifest, () => {
+			const fresh = loadRunManifestById(cwd, runId); // in-lock consistent read
+			if (!fresh) return null;
+			const freshRecord = getCurrentPlanRecord(fresh.manifest);
+			if (!freshRecord) return null;
+			const freshDropped = new Set(freshRecord.items.filter((i) => i.status === "dropped").map((i) => i.id));
+			if (freshDropped.size === 0) return null;
+			let tasks = fresh.tasks;
+			let changed = false;
+			for (const task of fresh.tasks) {
+				if (!task.planItem || !freshDropped.has(task.planItem)) continue;
+				if (task.status === "queued") {
+					// Never dispatched — cancel outright.
+					tasks = tasks.map((t) =>
+						t.id === task.id
+							? {
+									...t,
+									status: "cancelled" as const,
+									finishedAt: new Date().toISOString(),
+									error: "Plan item dropped by re-plan.",
+								}
+							: t,
+					);
+					cancelledTaskIds.push(task.id);
+					appendEvent(fresh.manifest.eventsPath, {
+						type: "plan.item.dropped",
+						runId,
+						taskId: task.id,
+						message: `Task ${task.id} cancelled: plan item '${task.planItem}' dropped by re-plan v${freshRecord.version}.`,
+						data: { itemId: task.planItem, planId: freshRecord.id, planVersion: freshRecord.version },
+					});
+					changed = true;
+				} else if (
+					(task.status === "running" || task.status === "waiting" || task.status === "needs_attention") &&
+					!task.replanDroppedAt
+				) {
+					// In flight — advisory once; maxTurns+grace stays the hard stop.
+					if (!appendSteeringAdvisory(fresh.manifest, task.id)) continue;
+					tasks = tasks.map((t) => (t.id === task.id ? { ...t, replanDroppedAt: new Date().toISOString() } : t));
+					advisedTaskIds.push(task.id);
+					appendEvent(fresh.manifest.eventsPath, {
+						type: "plan.item.dropped",
+						runId,
+						taskId: task.id,
+						message: `Wrap-up advisory delivered to ${task.id}: plan item '${task.planItem}' dropped by re-plan v${freshRecord.version}.`,
+						data: { itemId: task.planItem, planId: freshRecord.id, planVersion: freshRecord.version, softCancel: true },
+					});
+					changed = true;
+				}
+			}
+			if (!changed) return { manifest: fresh.manifest, tasks: fresh.tasks, cancelledTaskIds, advisedTaskIds };
+			saveRunTasks(fresh.manifest, tasks);
+			const manifest = { ...fresh.manifest, updatedAt: new Date().toISOString() };
+			saveRunManifest(manifest);
+			return { manifest, tasks, cancelledTaskIds, advisedTaskIds };
+		});
+		return outcome ?? undefined;
+	} catch (error) {
+		logInternalError("plan-replan.sweep-failed", error instanceof Error ? error : new Error(String(error)), `runId=${runId}`);
+		return undefined;
+	}
+}

package/src/runtime/recovery/checkpoint.ts

@@ -166,13 +166,6 @@ export function getCheckpointStore(stateRoot: string): CheckpointStore {
 	return _stores.get(stateRoot)!;
 }
 
-/**
- * Clear all checkpoint stores (for testing).
- */
-export function clearCheckpointStores(): void {
-	_stores.clear();
-}
-
 /**
  * Save a checkpoint during agent execution.
  */
@@ -219,17 +212,6 @@ export function loadCheckpoint(runId: string, taskId: string, cwd?: string): Che
 	return store.load(runId, taskId);
 }
 
-/**
- * Delete a checkpoint after successful completion.
- */
-export function clearCheckpoint(runId: string, taskId: string, cwd?: string): void {
-	assertSafePathId("runId", runId);
-	assertSafePathId("taskId", taskId);
-	const stateRoot = path.join(projectCrewRoot(cwd ?? process.cwd()), "state", "runs", runId);
-	const store = getCheckpointStore(stateRoot);
-	store.delete(runId, taskId);
-}
-
 /**
  * Check if a checkpoint exists for a task.
  */

package/src/runtime/recovery/crash-recovery.ts

@@ -6,7 +6,7 @@ import type { MetricRegistry } from "../../observability/metric-registry.ts";
 import { withRunLockSync } from "../../state/coordination/locks.ts";
 import { appendEvent, scanSequence } from "../../state/event-log/event-log.ts";
 import { readActiveRunRegistry, unregisterActiveRun } from "../../state/stores/active-run-registry.ts";
-import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/stores/state-store.ts";
+import { loadRunManifestById, saveRunManifest, saveRunTasks, updateRunStatus } from "../../state/stores/state-store.ts";
 import type { TeamTaskState } from "../../state/types.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import { projectCrewRoot, userCrewRoot } from "../../utils/paths.ts";
@@ -17,7 +17,7 @@ import { isWorkerHeartbeatStale } from "../heartbeat/worker-heartbeat.ts";
 import { terminateLiveAgentsForRun } from "../live-session/live-agent-manager.ts";
 import type { ManifestCache } from "../manifest-cache.ts";
 import { checkProcessLiveness } from "../process-status.ts";
-import { isPlanApprovalPending, type ReconcileResult, reconcileStaleRun } from "../stale-reconciler.ts";
+import { isIntentionalWait, isPlanApprovalPendingEffective, type ReconcileResult, reconcileStaleRun } from "../stale-reconciler.ts";
 
 export interface RecoveryPlan {
 	runId: string;
@@ -114,7 +114,10 @@ export function detectInterruptedRuns(
 	for (const manifest of manifestCache.list(50)) {
 		if (manifest.status !== "running" && manifest.status !== "blocked") continue;
 		// Preserve runs intentionally blocked on plan approval — not crashes.
-		if (isPlanApprovalPending(manifest)) continue;
+		// B1 battery 2026-08-18 (case b): generalized to isIntentionalWait — a run
+		// parked on an ask answer is equally intentional and must not be auto-resumed
+		// out from under its parked worker.
+		if (isIntentionalWait(manifest)) continue;
 		if (manifest.async?.pid !== undefined && checkProcessLiveness(manifest.async.pid).alive) continue;
 		// Skip runs owned by the current live session — a live session B must NOT
 		// detect session A's still-running run as interrupted.
@@ -142,54 +145,87 @@ export async function applyRecoveryPlan(plan: RecoveryPlan, ctx: Pick<ExtensionC
 		runId: plan.runId,
 		cwd: ctx.cwd,
 	});
-	appendHookEvent(loaded.manifest, hookReport);
-	if (hookReport.outcome === "block") {
-		appendEvent(loaded.manifest.eventsPath, {
-			type: "crew.run.recovery_blocked",
+
+	// R14-4: the hook await above is an arbitrary async gap — a concurrent writer
+	// may have completed/cancelled the run in the meantime. Re-read inside the
+	// lock and derive every write from the FRESH snapshot; never reset a run that
+	// reached a terminal status.
+	withRunLockSync(loaded.manifest, () => {
+		const fresh = loadRunManifestById(ctx.cwd, plan.runId); // NOTE: inside withRunLockSync - consistent read
+		if (!fresh) throw new Error(`Run '${plan.runId}' not found.`);
+		if (fresh.manifest.status === "completed" || fresh.manifest.status === "failed" || fresh.manifest.status === "cancelled") {
+			// Run reached a terminal status while the recovery hook was running —
+			// do NOT reset it (no task reset, no status change).
+			appendEvent(fresh.manifest.eventsPath, {
+				type: "crew.run.recovery_skipped",
+				runId: plan.runId,
+				message: `Recovery skipped: run is already '${fresh.manifest.status}'`,
+				data: { status: fresh.manifest.status },
+			});
+			return;
+		}
+		appendHookEvent(fresh.manifest, hookReport);
+		if (hookReport.outcome === "block") {
+			appendEvent(fresh.manifest.eventsPath, {
+				type: "crew.run.recovery_blocked",
+				runId: plan.runId,
+				message: `Recovery blocked by hook: ${hookReport.reason ?? "run_recovery hook blocked the operation."}`,
+				data: { hookOutcome: "block", reason: hookReport.reason },
+			});
+			return;
+		}
+
+		const reset = new Set(plan.resumableTasks);
+		const tasks = fresh.tasks.map((task) =>
+			reset.has(task.id)
+				? {
+						...task,
+						status: "queued" as const,
+						startedAt: undefined,
+						finishedAt: undefined,
+						error: undefined,
+						heartbeat: undefined,
+						// WP-2/R2 (ADR-0 item 9): a requeued task must not resume parked
+						// state — drop any stale ask-park marker along with the other
+						// per-attempt transient fields. Tasks NOT reset (e.g. a task parked
+						// in `waiting`) pass through untouched, marker intact; the marker's
+						// deadline is then owned by the scheduler tick (dispatch-batch).
+						waiting: undefined,
+					}
+				: task,
+		);
+		saveRunTasks(fresh.manifest, tasks);
+		appendEvent(fresh.manifest.eventsPath, {
+			type: "crew.run.resumed",
 			runId: plan.runId,
-			message: `Recovery blocked by hook: ${hookReport.reason ?? "run_recovery hook blocked the operation."}`,
-			data: { hookOutcome: "block", reason: hookReport.reason },
+			message: `Recovered ${plan.resumableTasks.length} interrupted task(s).`,
+			data: {
+				recoveredFromSeq: plan.lastEventSeq,
+				resumableTasks: plan.resumableTasks,
+			},
 		});
-		return;
-	}
-
-	const reset = new Set(plan.resumableTasks);
-	const tasks = loaded.tasks.map((task) =>
-		reset.has(task.id)
-			? {
-					...task,
-					status: "queued" as const,
-					startedAt: undefined,
-					finishedAt: undefined,
-					error: undefined,
-					heartbeat: undefined,
-				}
-			: task,
-	);
-	saveRunTasks(loaded.manifest, tasks);
-	appendEvent(loaded.manifest.eventsPath, {
-		type: "crew.run.resumed",
-		runId: plan.runId,
-		message: `Recovered ${plan.resumableTasks.length} interrupted task(s).`,
-		data: {
-			recoveredFromSeq: plan.lastEventSeq,
-			resumableTasks: plan.resumableTasks,
-		},
+		registry?.counter("crew.run.count", "Total runs by status").inc({ status: "resumed" });
 	});
-	registry?.counter("crew.run.count", "Total runs by status").inc({ status: "resumed" });
 }
 
 export function declineRecoveryPlan(plan: RecoveryPlan, ctx: Pick<ExtensionContext, "cwd">): void {
 	const loaded = loadRunManifestById(ctx.cwd, plan.runId); // NOTE: no withRunLock - best-effort only; concurrent writes may cause inconsistency
 	if (!loaded) throw new Error(`Run '${plan.runId}' not found.`);
-	// Log the event first — if appendEvent fails, state remains consistent.
-	appendEvent(loaded.manifest.eventsPath, {
-		type: "crew.run.recovery_declined",
-		runId: plan.runId,
-		message: "Interrupted run was not resumed.",
-		data: { recoveredFromSeq: plan.lastEventSeq },
+	// R14-4: re-read inside the lock so the decline decision applies to the
+	// on-disk state, not the best-effort snapshot read above. Kept SYNC —
+	// withRunLockSync is the sync lock variant.
+	withRunLockSync(loaded.manifest, () => {
+		const fresh = loadRunManifestById(ctx.cwd, plan.runId); // NOTE: inside withRunLockSync - consistent read
+		if (!fresh) return;
+		// Log the event first — if appendEvent fails, state remains consistent.
+		appendEvent(fresh.manifest.eventsPath, {
+			type: "crew.run.recovery_declined",
+			runId: plan.runId,
+			message: "Interrupted run was not resumed.",
+			data: { recoveredFromSeq: plan.lastEventSeq },
+		});
+		updateRunStatus(fresh.manifest, "cancelled", "interrupted-not-resumed");
 	});
-	updateRunStatus(loaded.manifest, "cancelled", "interrupted-not-resumed");
 }
 
 /**
@@ -224,9 +260,14 @@ export function cancelOrphanedRuns(
 	// Phase 1: Scan project-level manifests via manifestCache
 	for (const manifest of manifestCache.list(50)) {
 		if (manifest.status !== "running" && manifest.status !== "blocked") continue;
-		// Preserve plan-approval-blocked runs — they belong to their owner and are
-		// waiting on a human decision, not orphaned by a dead owner process.
-		if (isPlanApprovalPending(manifest)) {
+		// B1 battery 2026-08-18 (case b): preserve runs intentionally blocked on a
+		// HUMAN DECISION — plan approval (pre-v2 semantics) OR a pending ask answer
+		// within the waiting TTL (ADR-0 item 9: "not crashes and must not be
+		// stale-repaired or cancelled by reconciliation"). Live proof: a resumed
+		// run parked on ask (worker alive, waitState set, parked workers do NOT
+		// heartbeat) was orphan-cancelled 5m18s into a 10-minute park by a THIRD
+		// session's startup scan because the predicate only knew plan approval.
+		if (isIntentionalWait(manifest)) {
 			skipped.push(manifest.runId);
 			continue;
 		}
@@ -293,6 +334,14 @@ export function cancelOrphanedRuns(
 			});
 
 			saveRunTasks(fresh.manifest, repairedTasks);
+			// B1 battery 2026-08-18 (case b leak fix): a cancelled run must not keep
+			// its waitState pointer — observed live: orphan-cancel left waitState set,
+			// shielding the dead run from staleness repair for the full 24h TTL.
+			if (fresh.manifest.waitState) {
+				const cleared = { ...fresh.manifest, waitState: undefined, updatedAt: new Date(now).toISOString() };
+				saveRunManifest(cleared);
+				fresh.manifest = cleared;
+			}
 			for (const task of repairedTasks) {
 				try {
 					upsertCrewAgent(fresh.manifest, recordFromTask(fresh.manifest, task, "scaffold"));
@@ -655,7 +704,7 @@ export function reconcileAllStaleRuns(
 			// Belt-and-suspenders: reconcileStaleRun itself guards this, but the run
 			// may have flipped to blocked+plan-approval between cache-list and lock
 			// acquisition — re-check the freshest manifest under the lock.
-			if (isPlanApprovalPending(fresh.manifest)) {
+			if (isPlanApprovalPendingEffective(fresh.manifest)) {
 				results.push({
 					runId,
 					verdict: "blocked_awaiting_approval",

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 };
+	}
+}