pi-crew 0.11.0 → 0.11.2

package/src/runtime/deadletter.ts

@@ -1,8 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { TeamRunManifest } from "../state/types.ts";
-
 import { logInternalError } from "../utils/internal-error.ts";
+import { projectCrewRoot } from "../utils/paths.ts";
 
 export type DeadletterReason = "max-retries" | "heartbeat-dead" | "manual";
 
@@ -14,12 +14,30 @@ export interface DeadletterEntry {
 	lastError?: string;
 	attemptId?: string;
 	timestamp: string;
+	/** US-003 (2026-09-22): richer schema so the entry is self-sufficient for
+	 * post-mortem AFTER the run dir is pruned (the project-level index below is
+	 * the record that survives; the run-local file dies with the run dir). */
+	agent?: string;
+	role?: string;
+	/** Model-fallback attempt count at give-up time. */
+	modelAttempts?: number;
+	/** Run manifest status at the time of the write. */
+	runStatus?: string;
 }
 
 export function deadletterPath(manifest: TeamRunManifest): string {
 	return path.join(manifest.stateRoot, "deadletter.jsonl");
 }
 
+/**
+ * US-003: project-level dead-letter index, `<projectRoot>/.crew/state/deadletter/<runId>.jsonl`.
+ * Lives OUTSIDE any run dir, so per-run auto-prune (DP-01 keep=10) cannot delete it —
+ * this is the durable out-of-band record for post-mortem analysis.
+ */
+export function deadletterIndexPath(manifest: TeamRunManifest): string {
+	return path.join(projectCrewRoot(manifest.cwd), "state", "deadletter", `${manifest.runId}.jsonl`);
+}
+
 export function appendDeadletter(manifest: TeamRunManifest, entry: DeadletterEntry): void {
 	try {
 		fs.mkdirSync(manifest.stateRoot, { recursive: true });
@@ -27,6 +45,19 @@ export function appendDeadletter(manifest: TeamRunManifest, entry: DeadletterEnt
 	} catch (error) {
 		logInternalError("deadletter.append", error, `taskId=${entry.taskId}`);
 	}
+	// US-003: project-level index (survives run pruning). Best-effort AFTER the
+	// run-local record — appendDeadletter must never throw into the retry path.
+	// Honest deviation from the spec's "atomically (both or neither)" wording:
+	// cross-file atomicity without a journal is not physically possible; the
+	// contract is "both on success, never a caller-visible failure", with each
+	// failure logged via logInternalError.
+	try {
+		const indexPath = deadletterIndexPath(manifest);
+		fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+		fs.appendFileSync(indexPath, `${JSON.stringify({ ...entry, runStatus: entry.runStatus ?? manifest.status })}\n`, "utf-8");
+	} catch (error) {
+		logInternalError("deadletter.index-append", error, `taskId=${entry.taskId}`);
+	}
 }
 
 export function readDeadletter(manifest: TeamRunManifest, maxEntries = 1000): DeadletterEntry[] {
@@ -45,3 +76,14 @@ export function readDeadletter(manifest: TeamRunManifest, maxEntries = 1000): De
 		}
 	});
 }
+
+/**
+ * US-003 AC-3: `handleStatus` surfacing — a Deadletter line, only when entries
+ * exist (silent otherwise; a zero line would be noise on every healthy run).
+ */
+export function deadletterStatusLine(manifest: TeamRunManifest): string | undefined {
+	const entries = readDeadletter(manifest);
+	if (!entries.length) return undefined;
+	const reasons = [...new Set(entries.map((entry) => entry.reason))].join(", ");
+	return `Deadletter: ${entries.length} (${reasons}) — ${deadletterPath(manifest)}`;
+}

package/src/runtime/delegate-spawn.ts

@@ -96,7 +96,11 @@ export function grandchildArtifactsRoot(cwd: string, runId: string, parentTaskId
 }
 
 export async function spawnDelegateGrandchild(input: GrandchildSpawnInput): Promise<GrandchildSpawnResult> {
-	const artifactsRoot = path.join(input.cwd, ".crew", "artifacts", input.runId, input.parentTaskId, "nested", input.subId);
+	// RR-012 F03: single artifacts formula — grandchildArtifactsRoot(input.cwd, …).
+	// input.cwd is the PARENT TASK cwd threaded by the broker (the admitted
+	// worktree in worktree mode), so artifacts land under the admitted cwd —
+	// never under the leader/broker workspace.
+	const artifactsRoot = grandchildArtifactsRoot(input.cwd, input.runId, input.parentTaskId, input.subId);
 	fs.mkdirSync(artifactsRoot, { recursive: true });
 
 	const abort = new AbortController();

package/src/runtime/dispatch-batch.ts

@@ -13,12 +13,14 @@ import type { CrewReliabilityConfig } from "../config/config.ts";
 import { CrewError, ErrorCode } from "../errors.ts";
 import { appendHookEvent, executeHook } from "../hooks/registry.ts";
 import { childCorrelation, withCorrelation } from "../observability/correlation.ts";
+import { TEAM_TERMINAL_RUN_STATUSES } from "../state/contracts.ts";
 import { withRunLockSync } from "../state/coordination/locks.ts";
 import { appendEventAsync, appendEventBuffered } from "../state/event-log/event-log.ts";
 import { loadRunManifestById, saveRunManifest, saveRunTasks, saveRunTasksAsync, updateRunStatus } from "../state/stores/state-store.ts";
 import type { TaskAttemptState, TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import type { WorkflowConfig, WorkflowStep } from "../workflows/workflow-config.ts";
+import { isDelegateShadowTask } from "./broker/delegate/shadow-lifecycle.ts";
 import { readCrewAgents, recordFromTask, saveCrewAgents } from "./crew-agent-records.ts";
 import { appendDeadletter } from "./deadletter.ts";
 import { classifyHeartbeat, DEFAULT_GRADIENT_THRESHOLDS } from "./heartbeat/heartbeat-gradient.ts";
@@ -316,6 +318,26 @@ export function shouldUseRetry(reliability: CrewReliabilityConfig | undefined):
 	return reliability?.autoRetry !== false;
 }
 
+/**
+ * T9d cancel-race fix (2026-09-23, live battery finding 7): a retry attempt must
+ * re-queue ONLY the task's OWN terminal failure (status "failed") while the run is
+ * still active. Previously ANY non-queued/running status was re-queued — including
+ * "cancelled", so a cross-session cancel landing between attempt 1's hard-kill and
+ * attempt 2's start (measured live: cancel 16:46:22.987 → task.started 16:46:23.948,
+ * replacement worker then ran 47s post-cancel) silently resurrected the task.
+ * External terminal decisions (task cancelled/completed, or a terminal RUN manifest)
+ * are respected. Exported for unit testing.
+ */
+export function shouldRequeueForRetry(input: {
+	attempt: number;
+	taskStatus: TeamTaskState["status"];
+	manifestStatus: TeamRunManifest["status"];
+}): boolean {
+	if (input.attempt <= 1) return false;
+	if (TEAM_TERMINAL_RUN_STATUSES.has(input.manifestStatus)) return false;
+	return input.taskStatus === "failed";
+}
+
 function failedTaskFrom(result: { tasks: TeamTaskState[] }, taskId: string): TeamTaskState | undefined {
 	return result.tasks.find((item) => item.id === taskId && item.status === "failed");
 }
@@ -328,6 +350,13 @@ function failedTaskFrom(result: { tasks: TeamTaskState[] }, taskId: string): Tea
 function dagReadyTaskIds(tasks: TeamTaskState[], completedIds: Set<string>): string[] | null {
 	const hasExplicitDeps = tasks.some((t) => t.dependsOn.length > 0);
 	if (!hasExplicitDeps) return null;
+	// RR-012 (adjacent scheduler risk — proven reachable): exclude
+	// delegate-broker shadow records from the DAG. They are managed by the
+	// external grandchild spawner, not this scheduler: (1) as WAVE members a
+	// running shadow would gate dependent waves / trigger markBlocked although
+	// it is never in ctx.pendingUnits; (2) getDagReadyTasks below ignores both
+	// status AND graph, so a queued OR running shadow surfaces as ready.
+	const workflowTasks = tasks.filter((t) => !isDelegateShadowTask(t));
 	// FIX (goal-wrap runtime test): task.dependsOn stores STEP IDs (e.g. "execute"), not
 	// task IDs (e.g. "02_execute"). The DAG scheduler compares deps against completedIds
 	// (which are task IDs), so step-ID deps would never match → dependent tasks stuck blocked
@@ -335,10 +364,10 @@ function dagReadyTaskIds(tasks: TeamTaskState[], completedIds: Set<string>): str
 	// task-graph-scheduler.ts which handles this via stepToTaskId). buildDagExecutionPlan +
 	// getDagReadyTasks then work on consistent task IDs.
 	const stepToTaskId = new Map<string, string>();
-	for (const t of tasks) {
+	for (const t of workflowTasks) {
 		if (t.stepId) stepToTaskId.set(t.stepId, t.id);
 	}
-	const nodes: TaskNode[] = tasks.map((t) => ({
+	const nodes: TaskNode[] = workflowTasks.map((t) => ({
 		id: t.id,
 		dependsOn: t.dependsOn.map((dep) => stepToTaskId.get(dep) ?? dep),
 		phase: t.adaptive?.phase ?? t.stepId,
@@ -410,7 +439,15 @@ export async function selectDispatchBatch(ctx: SchedulerContext): Promise<Schedu
 	// existing task-graph-scheduler when no explicit deps exist (backward compat).
 	const completedIds = new Set(ctx.tasks.filter((t) => t.status === "completed" || t.status === "needs_attention").map((t) => t.id));
 	const dagReady = dagReadyTaskIds(ctx.tasks, completedIds);
-	const readyBeforeFilter = dagReady ?? snapshot.ready;
+	// RR-012 (adjacent scheduler risk — proven reachable): belt-and-braces
+	// selection guard. dagReadyTaskIds already excludes shadow records from the
+	// DAG; this filter also covers the snapshot fallback (a graphed queued
+	// shadow would resolve to queue "ready"). A shadow in a batch makes
+	// findStep() throw ResourceNotFound (task.stepId === undefined) — the run
+	// aborts (pre-warm site) or the record is force-failed by the synthesized
+	// unit error. Shadow records stay visible in snapshots / team status.
+	const shadowTaskIds = new Set(ctx.tasks.filter(isDelegateShadowTask).map((t) => t.id));
+	const readyBeforeFilter = (dagReady ?? snapshot.ready).filter((taskId) => !shadowTaskIds.has(taskId));
 
 	// Workflow phase precondition check (non-blocking: log warnings only).
 	if (ctx.wfMachine.currentPhaseIndex < ctx.wfMachine.phases.length) {
@@ -777,8 +814,25 @@ export async function dispatchBatch(ctx: SchedulerContext, decision: DispatchBat
 					// NOTE: no withRunLock — best-effort only; concurrent writes may cause inconsistency
 					const fresh = loadRunManifestById(ctx.manifest.cwd, ctx.manifest.runId);
 					const freshManifest = fresh?.manifest ?? ctx.manifest;
-					const freshTasks = fresh?.tasks ?? ctx.tasks;
-					const freshTask = freshTasks.find((item) => item.id === task.id) ?? task;
+					let freshTasks = fresh?.tasks ?? ctx.tasks;
+					let freshTask = freshTasks.find((item) => item.id === task.id) ?? task;
+					// US-003 (2026-09-22) — RETRY-NOOP BUG, found while wiring the dead-letter
+					// integration test: a retry (attempt > 1) only happens because OUR previous
+					// attempt THREW — i.e. we ourselves persisted the terminal failure (e.g.
+					// model-exhausted marks the task failed before the throw). The terminal-state
+					// early-return below then treated OUR OWN failure as "nothing to do" and
+					// returned it as SUCCESS: executeWithRetry never re-ran the task, never
+					// exhausted, and the onRetryGivenUp dead-letter never fired — autoRetry was
+					// silently a single attempt for every failure that persists task state.
+					// Fix: on a retry, re-queue OUR OWN terminal failure so the retry actually
+					// re-runs. Attempt 1 keeps the original guard (externally-terminal task =
+					// someone else's decision; external cancellation exits via the signal).
+					// 2026-09-23 (finding 7): re-queue ONLY own failures on an ACTIVE run —
+					// cancelled/completed tasks and terminal manifests must never resurrect.
+					if (shouldRequeueForRetry({ attempt, taskStatus: freshTask.status, manifestStatus: freshManifest.status })) {
+						freshTask = { ...freshTask, status: "queued", error: undefined, finishedAt: undefined };
+						freshTasks = freshTasks.map((item) => (item.id === task.id ? freshTask : item));
+					}
 					if (freshTask.status !== "queued" && freshTask.status !== "running")
 						return {
 							manifest: freshManifest,
@@ -855,6 +909,15 @@ export async function dispatchBatch(ctx: SchedulerContext, decision: DispatchBat
 					},
 					onRetryGivenUp: (attempts, error, info) => {
 						lastAttemptId = info.attemptId;
+						// US-003: aborts are NOT exhaustion — executeWithRetry also fires this
+						// hook on its cancelled exit, which previously deadlettered cancelled
+						// tasks as "max-retries" (false positive; keep the signal high).
+						if (runController.signal.aborted) return;
+						// US-003: richer entry (agent/role/modelAttempts/runStatus) so the
+						// project-level index is self-sufficient after the run dir is pruned.
+						// Prefer the FAILED attempt's final task state over the pre-run snapshot.
+						const failedTask = lastFailed?.tasks.find((item) => item.id === task.id);
+						const deadletterTask = failedTask ?? task;
 						appendDeadletter(ctx.manifest, {
 							runId: ctx.manifest.runId,
 							taskId: task.id,
@@ -863,6 +926,10 @@ export async function dispatchBatch(ctx: SchedulerContext, decision: DispatchBat
 							attemptId: info.attemptId,
 							lastError: error.message,
 							timestamp: new Date().toISOString(),
+							agent: deadletterTask.agent,
+							role: deadletterTask.role,
+							modelAttempts: deadletterTask.modelAttempts?.length,
+							runStatus: ctx.manifest.status,
 						});
 						input.metricRegistry
 							?.counter("crew.task.deadletter_total", "Deadletter triggers by reason")

package/src/runtime/goal-workflow/goal-loop-runner.ts

@@ -23,7 +23,7 @@ import { effectiveRunConfig } from "../../extension/team-tool/config-patch.ts";
 import { appendEventBuffered } from "../../state/event-log/event-log.ts";
 import { registerActiveRun, unregisterActiveRun } from "../../state/stores/active-run-registry.ts";
 import { collectRunMetrics } from "../../state/stores/run-metrics.ts";
-import { createRunManifest, saveRunTasks } from "../../state/stores/state-store.ts";
+import { createRunManifest, loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/stores/state-store.ts";
 import type { GoalLoopState, GoalLoopStatus, GoalVerdict, TeamRunManifest, TeamTaskState } from "../../state/types.ts";
 import type { TeamConfig } from "../../teams/team-config.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
@@ -39,6 +39,17 @@ import { GoalStore } from "./goal-state-store.ts";
 export interface GoalLoopRuntimeDeps {
 	/** Resolve the agent configs reachable from cwd (used for executeTeamRun's agents arg). */
 	discoverAgents: (cwd: string) => AgentConfig[];
+	/**
+	 * SR-01 test seam: override the per-turn config/runtime resolution. When
+	 * provided, it replaces the loadConfig/effectiveRunConfig/resolveCrewRuntime
+	 * chain — a test can throw here to exercise the pre-executeTeamRun failure
+	 * path deterministically (the alternative, monkey-patching modules, is
+	 * flaky). Production never sets it.
+	 */
+	resolveTurnConfig?: (cwd: string) => {
+		executedConfig: ReturnType<typeof effectiveRunConfig>;
+		runtime: Awaited<ReturnType<typeof resolveCrewRuntime>>;
+	};
 }
 
 export interface RunGoalLoopInput {
@@ -657,9 +668,17 @@ export async function runGoalLoop(input: RunGoalLoopInput): Promise<RunGoalLoopR
 				// multi-step workflows (fast-fix, implementation) work correctly. Without these, the
 				// team-runner's DAG scheduler / runtime resolution can throw unhandled rejections on
 				// the second batch, which the background-runner's rejection guard catches → silent exit.
-				const turnConfig = loadConfig(goal.cwd);
-				const turnExecutedConfig = effectiveRunConfig(turnConfig.config, {});
-				const turnRuntime = await resolveCrewRuntime(turnExecutedConfig);
+				let turnExecutedConfig: ReturnType<typeof effectiveRunConfig>;
+				let turnRuntime: Awaited<ReturnType<typeof resolveCrewRuntime>>;
+				if (input.deps.resolveTurnConfig) {
+					const resolved = input.deps.resolveTurnConfig(goal.cwd);
+					turnExecutedConfig = resolved.executedConfig;
+					turnRuntime = resolved.runtime;
+				} else {
+					const turnConfig = loadConfig(goal.cwd);
+					turnExecutedConfig = effectiveRunConfig(turnConfig.config, {});
+					turnRuntime = await resolveCrewRuntime(turnExecutedConfig);
+				}
 				turnResult = await executeTeamRun({
 					manifest: created.manifest,
 					tasks: created.tasks,
@@ -674,6 +693,29 @@ export async function runGoalLoop(input: RunGoalLoopInput): Promise<RunGoalLoopR
 					workspaceId: goal.ownerSessionId ?? goal.cwd,
 					signal,
 				});
+			} catch (error) {
+				// SR-01 (GL-1b part C, 2026-09-22): a throw between turn creation and
+				// executeTeamRun's own try (config resolution, runtime resolution, or
+				// executeTeamRun's PRE-try section) escaped with the turn manifest stuck
+				// at "queued" — a turn that is long dead still reported as in-flight, so
+				// `team status <turnId>` lied and a resume could double-run it. Mark it
+				// failed before re-throwing; the outer catch (GL-1b part B) then persists
+				// lastTurnError at the goal level.
+				//
+				// Guarded on status === "queued" so we never overwrite a status the
+				// executor already set (executeTeamRunCore failures already write failed
+				// themselves — no double-write). Best-effort: a failure to persist must
+				// not mask the original error.
+				const message = error instanceof Error ? error.message : String(error);
+				try {
+					const loaded = loadRunManifestById(goal.cwd, created.manifest.runId);
+					if (loaded && loaded.manifest.status === "queued") {
+						updateRunStatus(loaded.manifest, "failed", `pre-execute failure: ${message}`);
+					}
+				} catch (persistError) {
+					logInternalError("goal-loop.markTurnFailed", persistError, `turnRunId=${created.manifest.runId}`);
+				}
+				throw error;
 			} finally {
 				unregisterActiveRun(created.manifest.runId);
 			}
@@ -689,6 +731,18 @@ export async function runGoalLoop(input: RunGoalLoopInput): Promise<RunGoalLoopR
 			// Previously the loop continued to evaluateGoal on blocked/failed turns, burning maxTurns.
 			const turnStatus = turnResult.manifest.status;
 			if (turnStatus === "blocked" || turnStatus === "failed") {
+				// GL-1b (2026-09-22 diagnosability): the failure reason previously lived
+				// ONLY inside the turn-run dir (manifest.summary + run.failed event) —
+				// auto-prune (keep=10, session start) deletes turn dirs, making blocked
+				// goals undiagnosable afterwards. Persist the reason into the goal state
+				// (never pruned), carry it on the terminal event, and clear the stale
+				// currentRunId — the turn is over.
+				const turnError = turnResult.manifest.summary ?? `turn ${turnIndex} ended ${turnStatus}`;
+				try {
+					goal = store.patch(goal.goalId, { lastTurnError: turnError, currentRunId: undefined }, eventsPath) ?? goal;
+				} catch (error) {
+					logInternalError("goal-loop.persistTurnError", error, `goalId=${goal.goalId}`);
+				}
 				goal = safeSetStatus(store, goal.goalId, "blocked", goal, eventsPath);
 				appendEventBuffered(eventsPath, {
 					type: "goal.turn_terminal_status",
@@ -698,6 +752,7 @@ export async function runGoalLoop(input: RunGoalLoopInput): Promise<RunGoalLoopR
 						turn: turnIndex,
 						turnRunId: created.manifest.runId,
 						turnStatus,
+						reason: turnError,
 					},
 				}).catch((e) => logInternalError("goal-loop.buffered", e, "type=goal.turn_terminal_status"));
 				break;
@@ -805,6 +860,20 @@ export async function runGoalLoop(input: RunGoalLoopInput): Promise<RunGoalLoopR
 		}
 	} catch (error) {
 		logInternalError("goal-loop.run", error, `goalId=${goal.goalId}`);
+		// GL-1b: this catch previously only console-errored (logInternalError) —
+		// loop-level failures left NO persisted trace. Mirror the turn-level fix:
+		// persist the message into the goal state + event log.
+		const loopError = error instanceof Error ? error.message : String(error);
+		try {
+			goal = store.patch(goal.goalId, { lastTurnError: loopError, currentRunId: undefined }, eventsPath) ?? goal;
+		} catch {
+			/* best-effort — status transition below still runs */
+		}
+		appendEventBuffered(eventsPath, {
+			type: "goal.loop_error",
+			runId: manifest.runId,
+			data: { goalId: goal.goalId, error: loopError },
+		}).catch((e) => logInternalError("goal-loop.buffered", e, "type=goal.loop_error"));
 		goal = safeSetStatus(store, goal.goalId, "blocked", goal, eventsPath);
 	} finally {
 		// P1g: release the workspace lock (held since loop start).

package/src/runtime/heartbeat/heartbeat-watcher.ts

@@ -98,6 +98,13 @@ export class HeartbeatWatcher {
 			if (loaded.manifest.status !== "running") continue;
 			for (const task of loaded.tasks) {
 				if (task.status !== "running") continue;
+				// Guest-child tasks (delegate subagents, agent === "delegate") have NO
+				// heartbeat channel: they never write task.heartbeat/agentProgress —
+				// their lifecycle is tracked by delegate.requested/admitted/completed
+				// broker events. Watching them here classified every guest as "dead"
+				// within one poll (52ms after admit, run team_20260926033657_2b6c6d2610b26d9d,
+				// 2026-09-26 battery) and enqueued false "stuck worker" ambients.
+				if (task.agent === "delegate") continue;
 				const key = `${run.runId}:${task.id}`;
 				activeKeys.add(key);
 				this.lastSeen.set(key, now);

package/src/runtime/model/model-fallback.ts

@@ -70,6 +70,20 @@ function modelInfoFromUnknown(value: unknown): AvailableModelInfo | undefined {
 	};
 }
 
+// US-012 (2026-09-22): cache the registry-derived model list. The registry is
+// config/env-derived and invariant per session, but `availableModelInfosFromRegistry`
+// is called on EVERY model resolution / worker spawn (a 4-worker team = 4
+// rebuilds). Keyed on the registry object identity (WeakMap) so a new registry
+// instance (config reload) gets a fresh entry automatically, and invalidated by
+// the getAvailable() array identity so a mutated-in-place list is not served
+// stale. WeakMap → no leak when a session's registry is dropped.
+const registryModelCache = new WeakMap<object, { raw: unknown[]; infos: AvailableModelInfo[] }>();
+
+/** @internal — test introspection. */
+export function __test__registryModelCacheHas(registry: object): boolean {
+	return registryModelCache.has(registry);
+}
+
 export function availableModelInfosFromRegistry(registry: unknown): AvailableModelInfo[] | undefined {
 	if (!registry || typeof registry !== "object" || Array.isArray(registry)) return undefined;
 	const candidate = registry as ModelRegistryLike;
@@ -80,7 +94,13 @@ export function availableModelInfosFromRegistry(registry: unknown): AvailableMod
 				? candidate.getAll()
 				: undefined;
 	if (!Array.isArray(raw)) return undefined;
-	return raw.map(modelInfoFromUnknown).filter((entry): entry is AvailableModelInfo => entry !== undefined);
+	// Serve from cache only when the SAME array instance is returned — a
+	// rebuilt/refreshed list (different identity) must be re-normalized.
+	const cached = registryModelCache.get(registry as object);
+	if (cached && cached.raw === raw) return cached.infos;
+	const infos = raw.map(modelInfoFromUnknown).filter((entry): entry is AvailableModelInfo => entry !== undefined);
+	registryModelCache.set(registry as object, { raw, infos });
+	return infos;
 }
 
 export function modelStringFromUnknown(model: unknown): string | undefined {

package/src/runtime/model/pi-args.ts

@@ -3,7 +3,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentConfig } from "../../agents/agent-config.ts";
 import { atomicWriteFile } from "../../state/atomic-write.ts";
-import { packageRoot, userPiRoot } from "../../utils/paths.ts";
+import { hasRunStateLayout, packageRoot, userPiRoot } from "../../utils/paths.ts";
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 // FIX (2026-07-02): use packageRoot() instead of import.meta.url-relative path.
@@ -629,16 +629,14 @@ export function cleanupLegacyOrphanTempDirs(
 				continue;
 			}
 			if (lstat.isSymbolicLink()) continue;
-			// Skip dirs containing active run state — those are handled by
+			// Skip dirs containing pi-crew run state — those are handled by
 			// reconcileOrphanedTempWorkspaces which has run-state semantics.
-			const crewDir = path.join(dir, ".crew");
-			let crewDirLstat: fs.Stats | undefined;
-			try {
-				crewDirLstat = fs.lstatSync(crewDir);
-			} catch {
-				// doesn't exist
-			}
-			if (crewDirLstat && !crewDirLstat.isSymbolicLink()) continue;
+			// RR-020 Fix 3: recognise BOTH supported layouts — `<dir>/.crew/` and
+			// the `.pi`-based `<dir>/.pi/teams/`. Only `.crew` used to be checked,
+			// so a temp workspace with live `.pi/teams` run state was deleted as
+			// debris. Symlinked layout dirs still do NOT protect the dir (the
+			// scanner keeps rejecting symlinks instead of trusting them).
+			if (hasRunStateLayout(dir)) continue;
 			// Skip dirs currently tracked by this process (defense in depth:
 			// with 8ba270d the Set should never contain /tmp/ paths, but
 			// future code or external callers might).

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

@@ -1,9 +1,10 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_PATHS } from "../../config/defaults.ts";
 import { appendHookEvent, executeHook } from "../../hooks/registry.ts";
 import type { MetricRegistry } from "../../observability/metric-registry.ts";
-import { withRunLockSync } from "../../state/coordination/locks.ts";
+import { discoverRunLockFiles, sweepStaleLocks, 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, saveRunManifest, saveRunTasks, updateRunStatus } from "../../state/stores/state-store.ts";
@@ -757,5 +758,28 @@ export function reconcileAllStaleRuns(
 			}
 		});
 	}
+	// US-002 (2026-09-22): structured stale-lock sweep. Runs after reconciliation
+	// so locks whose holder died (kill -9 / crash) do not linger. The sweep is
+	// strictly safer than acquire-time steal (stale AND holder-dead only), so a
+	// live holder is never disturbed. Best-effort.
+	try {
+		const runsRoots = [
+			path.join(projectCrewRoot(cwd), DEFAULT_PATHS.state.runsSubdir),
+			path.join(userCrewRoot(), DEFAULT_PATHS.state.runsSubdir),
+		];
+		for (const runsRoot of runsRoots) {
+			const { removed } = sweepStaleLocks(discoverRunLockFiles(runsRoot));
+			if (removed.length > 0) {
+				logInternalError(
+					"crash-recovery.sweep-stale-locks",
+					new Error(`swept ${removed.length} stale run lock(s)`),
+					removed.join(", "),
+					"warn",
+				);
+			}
+		}
+	} catch (error) {
+		logInternalError("crash-recovery.sweep-stale-locks", error);
+	}
 	return results;
 }

package/src/runtime/run-worker.ts

@@ -72,7 +72,18 @@ export interface WorkerSpawnInput extends ChildPiRunInput {
 export async function runWorker(input: WorkerSpawnInput): Promise<ChildPiRunResult> {
 	const { cap = true, ...childPiInput } = input;
 	if (cap) {
-		return withWorkerSlot(() => runChildPi(childPiInput));
+		// RR-014 / F15: thread the caller's signal into the slot WAIT itself.
+		// Previously the signal lived only inside childPiInput and was read by
+		// runChildPi AFTER the acquire resolved — a cancelled task queued on a
+		// full pool stayed pending until the slot holder finished (and delayed
+		// every drainPendingUnits awaiting it). Two consistent outcomes:
+		// - abort wins the race → acquire rejects (SemaphoreAbortedError), no
+		//   slot taken, fn never runs;
+		// - grant wins the race → acquire resolves, runChildPi's pre-spawn
+		//   guard (child-pi-spawn.ts B5) sees signal.aborted and returns
+		//   kind "aborted" WITHOUT spawning, and withWorkerSlot's finally
+		//   releases the slot within a microtask.
+		return withWorkerSlot(() => runChildPi(childPiInput), childPiInput.signal);
 	}
 	return runChildPi(childPiInput);
 }

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

@@ -64,11 +64,16 @@ export function __test_resetCap(testCapacity: number): void {
  * Acquire a global worker slot. Resolves immediately if under cap, else queues
  * (FIFO) until a slot frees. MUST be paired with releaseWorkerSlot().
  *
+ * RR-014 / F15: an optional AbortSignal makes the WAIT itself cancellable — a
+ * waiter whose signal fires is removed from the queue eagerly and the acquire
+ * REJECTS (SemaphoreAbortedError) without consuming a slot. Without a signal
+ * the semantics are unchanged.
+ *
  * Used to bound WORKER spawns only. Do NOT route the goal-judge through this
  * (see the RFC MAJ#3 rationale in the module header).
  */
-export async function acquireWorkerSlot(): Promise<void> {
-	await semaphore.acquire();
+export async function acquireWorkerSlot(signal?: AbortSignal): Promise<void> {
+	await semaphore.acquire(signal);
 }
 
 /**
@@ -82,13 +87,15 @@ export function releaseWorkerSlot(): void {
 /**
  * Convenience: acquire a worker slot, run `fn`, and release on completion OR
  * throw. The slot is ALWAYS released — including when `fn` rejects — so a
- * throwing worker never leaks a slot (deadlock prevention).
+ * throwing worker never leaks a slot (deadlock prevention). If `signal` is
+ * provided and fires while WAITING for a slot, the acquire rejects and `fn`
+ * never runs (no slot was taken, so there is nothing to release).
  *
  * Example:
- *   const result = await withWorkerSlot(() => runChildPi(...));
+ *   const result = await withWorkerSlot(() => runChildPi(...), input.signal);
  */
-export async function withWorkerSlot<T>(fn: () => Promise<T>): Promise<T> {
-	await acquireWorkerSlot();
+export async function withWorkerSlot<T>(fn: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+	await acquireWorkerSlot(signal);
 	try {
 		return await fn();
 	} finally {

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

@@ -5,6 +5,7 @@ import { writeArtifact } from "../../state/stores/artifact-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 { appendDeadletter } from "../deadletter.ts";
 import { createWorkerHeartbeat, touchWorkerHeartbeat } from "../heartbeat/worker-heartbeat.ts";
 import type { CrewRuntimeMode } from "../model/runtime-resolver.ts";
 import type { RetryPolicy } from "../recovery/retry-executor.ts";
@@ -196,7 +197,32 @@ export async function runCoalescedTaskGroup(input: CoalescedTaskGroupInput): Pro
 			}
 		};
 		try {
-			const result = useRetry ? await executeWithRetry(runOnce, policy, { signal }) : await runOnce();
+			const result = useRetry
+				? await executeWithRetry(runOnce, policy, {
+						signal,
+						// US-003 (2026-09-22): exhausted retries on the COALESCED path were never
+						// deadlettered — only the singleton path (dispatch-batch) wired
+						// onRetryGivenUp, so an M6 group that burned its whole retry budget left
+						// no post-mortem record once the run dir was pruned. The group shares ONE
+						// worker: the entry is recorded against the group's first task and names
+						// the whole group in the message. Aborts are NOT exhaustion — skip them
+						// (executeWithRetry also fires this hook on the cancelled exit).
+						onRetryGivenUp: (attempts, error) => {
+							if (signal?.aborted) return;
+							appendDeadletter(manifest, {
+								runId: manifest.runId,
+								taskId: firstTask.id,
+								reason: "max-retries",
+								attempts,
+								lastError: `coalesced group (${taskIds.length} task(s): ${taskIds.join(", ")}) — ${error.message}`,
+								timestamp: new Date().toISOString(),
+								agent: agent.name,
+								role: firstTask.role,
+								runStatus: manifest.status,
+							});
+						},
+					})
+				: await runOnce();
 			rawOutput = result.rawFinalText ?? result.stdout ?? "";
 			// RT-5 #1/#2: distinguish cancel from failure. Cancel = run-level
 			// signal aborted OR the child reports cooperative cancellation.