pi-crew 0.11.1 → 0.11.4

package/src/runtime/verification/verification-worktree.ts

@@ -66,6 +66,7 @@ export function checkWorktreeSandboxAvailable(cwd: string): { available: true; c
 			cwd,
 			stdio: ["ignore", "pipe", "pipe"],
 			encoding: "utf-8",
+			timeout: 5000,
 		}).trim();
 		if (!toplevel)
 			return {
@@ -77,6 +78,7 @@ export function checkWorktreeSandboxAvailable(cwd: string): { available: true; c
 			cwd,
 			stdio: ["ignore", "pipe", "pipe"],
 			encoding: "utf-8",
+			timeout: 5000,
 		}).trim();
 		if (!commitSha)
 			return {
@@ -92,6 +94,7 @@ export function checkWorktreeSandboxAvailable(cwd: string): { available: true; c
 			cwd,
 			stdio: ["ignore", "pipe", "pipe"],
 			encoding: "utf-8",
+			timeout: 5000,
 		}).trim();
 		if (status.length > 0)
 			return {

package/src/runtime/workspace-lock.ts

@@ -187,7 +187,10 @@ function claimLock(lockPath: string, contents: WorkspaceLockContents, staleRecla
 			return true;
 		} catch (error) {
 			const code = (error as NodeJS.ErrnoException).code;
-			if (code !== "EEXIST") throw error;
+			// EEXIST → held. Windows contention can surface as EPERM/EACCES/EBUSY
+			// while another handle has the lock open — same meaning here: not acquired
+			// (caller backs off / queues), never an abort.
+			if (code !== "EEXIST" && code !== "EPERM" && code !== "EACCES" && code !== "EBUSY") throw error;
 			return false;
 		}
 	};

package/src/schema/config-schema.ts

@@ -231,6 +231,20 @@ export const PiTeamsNotificationsConfigSchema = Type.Object(
 		batchWindowMs: Type.Optional(Type.Integer({ minimum: 0 })),
 		quietHours: Type.Optional(Type.String({ pattern: "^\\d{2}:\\d{2}-\\d{2}:\\d{2}$" })),
 		sinkRetentionDays: Type.Optional(Type.Integer({ minimum: 1, maximum: 90 })),
+		// US-030: whole block is `sensitive` (terminal mark) — project config drops
+		// it, so an untrusted repo cannot set a webhook URL or bypass the SSRF
+		// guard via `allowLocalhost`. User config only.
+		webhook: Type.Optional(
+			Type.Object(
+				{
+					url: Type.String({ minLength: 1, pattern: "^https?://" }),
+					enabled: Type.Optional(Type.Boolean()),
+					secret: Type.Optional(Type.String({ minLength: 1 })),
+					allowLocalhost: Type.Optional(Type.Boolean()),
+				},
+				{ additionalProperties: false, sensitive: true },
+			),
+		),
 	},
 	{ additionalProperties: false },
 );

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

@@ -148,6 +148,13 @@ const sharedFields = {
 		}),
 	),
 	taskId: Type.Optional(Type.String({ description: "Task ID for respond action." })),
+	// US-021: the two runs to diff. Items allow "" so model callers that emit
+	// unset strings are filtered at the handler, same policy as runId.
+	runIds: Type.Optional(
+		Type.Array(Type.String({ pattern: "^$|^[A-Za-z0-9_-]+$" }), {
+			description: "The two run IDs to compare: { action: 'compare', runIds: ['team_a', 'team_b'] }.",
+		}),
+	),
 	message: Type.Optional(Type.String({ description: "Message for respond action." })),
 	async: Type.Optional(
 		Type.Boolean({
@@ -277,6 +284,12 @@ const sharedFields = {
 		// Empty-string unset marker accepted (Tier-9: models emit "" when unset).
 		// 0 accepted as "unset/disabled" (models emit 0 for off); still rejects 1-999
 		// as the MISCONFIGURATION GUARD against typo'd silent-abort configs.
+		// Stringified numbers accepted (same pi-ai coercion the sibling budget
+		// params handle): this Union has a Literal("") branch, so pi-ai stringifies
+		// numeric arguments (budgetTotal: 100000 → "100000") and the call died at
+		// schema validation before any coercion could run — found live 2026-09-21
+		// when `team action='goal' budgetTotal=100000` was rejected. Coerced back
+		// to a number by normalizeLooseNumericFields before handlers run.
 		Type.Union(
 			[
 				Type.Literal(""),
@@ -284,6 +297,7 @@ const sharedFields = {
 				Type.Number({
 					minimum: 1000,
 				}),
+				Type.String({ pattern: NUMERIC_STRING_RE }),
 			],
 			{
 				description:
@@ -431,6 +445,7 @@ const MANAGE_ACTIONS = [
 	"import",
 	"imports",
 	"export",
+	"compare",
 ] as const;
 const manageActions = Type.Optional(buildStringEnum(MANAGE_ACTIONS, ACTION_DESCRIPTION));
 
@@ -515,6 +530,8 @@ export interface TeamToolParamsValue {
 	task?: string;
 	singleAgent?: boolean;
 	runId?: string;
+	/** (compare) The two runs to diff: { action: 'compare', runIds: ['team_a', 'team_b'] } (US-021). */
+	runIds?: string[];
 	taskId?: string;
 	message?: string;
 	async?: boolean;

package/src/state/atomic-write.ts

@@ -1122,6 +1122,59 @@ function cancelPendingCoalescedWrite(filePath: string): void {
 	}
 }
 
+/**
+ * F10 / RR-016: path-scoped PUBLIC cancel for callers that DELETE a file whose
+ * coalesced write is still buffered. Without it the pending timer fires after
+ * the unlink and RE-CREATES the file with stale content — the measured
+ * `removeCrewAgent` defect (`agents/<task>/status.json` reappearing with
+ * `status:"running"` after the exit drain, while `agents.json` stayed empty).
+ *
+ * `cancelPendingCoalescedWrite` above already has exactly this semantics for
+ * immediate-write supersession; this export only widens the seam so a deleter
+ * can use it too. Returns true when an entry was pending (and was cancelled).
+ */
+export function cancelPendingCoalescedWriteForPath(filePath: string): boolean {
+	const pending = pendingAtomicWrites.has(filePath);
+	cancelPendingCoalescedWrite(filePath);
+	return pending;
+}
+
+/** @internal Test/diagnostic hook: is a coalesced write pending for this exact path? */
+export function hasPendingCoalescedWrite(filePath: string): boolean {
+	// (kept adjacent for discoverability; pendingCoalescedWriteCount below serves teardown drains)
+	return pendingAtomicWrites.has(filePath);
+}
+
+/** Number of coalesced writes currently pending (test teardown quiesce loops). */
+export function pendingCoalescedWriteCount(): number {
+	return pendingAtomicWrites.size;
+}
+
+/**
+ * Read the buffered (not-yet-flushed) value for `filePath`, if any.
+ *
+ * F06 / RR-017: gives callers a read-after-write view WITHOUT forcing the
+ * pending coalesced write to disk. `readCrewAgents()` previously called
+ * `flushPendingAtomicWrites(agentsPath)` before every read, and since
+ * `upsertCrewAgent` always reads first, EVERY non-terminal upsert destroyed the
+ * coalescing window it had just created (20 progress upserts → 19 agents.json
+ * renames). Overlaying this snapshot on the on-disk content preserves
+ * read-after-write semantics with zero I/O.
+ *
+ * The value is returned by reference, exactly like the flush path stringifies
+ * `entry.value` at flush time — callers must treat it as read-only.
+ */
+export function peekPendingCoalescedWrite<T>(filePath: string): T | undefined {
+	const value = pendingAtomicWrites.get(filePath)?.value;
+	if (value === undefined) return undefined;
+	// RM-01 (2026-09-22): return a DEEP COPY, not a reference. The flush path
+	// stringifies `entry.value` at flush time, so a caller mutating the returned
+	// object would corrupt the not-yet-flushed buffer (a write-then-flush
+	// alias bug). All in-tree payloads are JSON-shaped, so structuredClone is
+	// exact; the only caller is readCrewAgents (bounded per-run record list).
+	return structuredClone(value) as T;
+}
+
 /**
  * Flush every queued coalesced write synchronously. Safe to call any time.
  *

package/src/state/contracts.ts

@@ -142,6 +142,7 @@ export const TEAM_EVENT_TYPES = [
 	"goal.turn_evaluated",
 	"goal.budget_warning",
 	"goal.loop_end",
+	"goal.loop_error",
 	"goal.feedback_steered",
 	"goal.state_changed",
 	// Dynamic workflow events (P2) — script-driven orchestration.
@@ -155,6 +156,114 @@ export const TEAM_EVENT_TYPES = [
 	// RLM/scratchpad adoption metrics (plan I5)
 	"scratchpad.cell",
 	"scratchpad.restored",
+	// ─── 2026-09-17 drift closure ─────────────────────────────────────────────
+	// The remaining types below were ALREADY EMITTED in production but never
+	// registered — they were silent to consumers of TEAM_EVENT_TYPES. The
+	// check:event-types gate also had a detection bug (conditional `type:`
+	// expressions like `type: error ? "task.failed" : ...` were invisible),
+	// which is why this drift accumulated unnoticed. Registered here grouped
+	// by prefix; verified against literal emit sites (see
+	// scripts/check-event-types-registry.mjs and the 2026-09-17 review
+	// verification, §6.3). The gate now runs with --enforce in CI.
+	// Adaptive planning (goal-workflow/adaptive-plan.ts)
+	"adaptive.plan_injected",
+	"adaptive.plan_missing",
+	"adaptive.plan_repaired",
+	"adaptive.plan_repair_failed",
+	// Agent control / group-join / nudge
+	"agent.control.queued",
+	"agent.group_join.acknowledged",
+	"agent.group_join.ack_timeout",
+	"agent.group_join.delivery_reused",
+	"agent.group_join.partial",
+	"agent.group_join.completed",
+	"agent.nudged",
+	// Background-runner lifecycle forensics (async sidecar/runner death, signals)
+	"async.died",
+	"async.exit",
+	"async.interrupt_detected",
+	"async.kill_requested",
+	"async.sigterm_received_graceful_shutdown",
+	"async.watchdog_fired",
+	"background.unregister_worker_failed",
+	// Chain runner
+	"chain.step_completed",
+	// Config
+	"config.warning",
+	// Stale-run reconciliation (stale-reconciler.ts)
+	"crew.run.reconciled_stale",
+	"crew.run.orphan_cancelled",
+	"crew.run.orphan_skip",
+	"crew.run.recovery_blocked",
+	"crew.run.recovery_declined",
+	"crew.run.recovery_skipped",
+	"crew.run.resumed",
+	"crew.task.heartbeat_dead",
+	"crew.task.retry_attempt",
+	// Dynamic workflow resume
+	"dwf.resumed",
+	// Foreground interrupt
+	"foreground.interrupt_requested",
+	// Goal loop (P0/P1) additional outcomes
+	"goal.resumed",
+	"goal.resume_spawn_failed",
+	"goal.stuck",
+	"goal.turn_terminal_status",
+	"goal.verification_compromised",
+	"goal.workspace_lock_failed",
+	// Hook execution trace
+	"hook.executed",
+	// Limits
+	"limits.unbounded",
+	// Mailbox delivery (ack/replay/timeout observable surface)
+	"mailbox.acknowledged",
+	"mailbox.message",
+	"mailbox.replayed",
+	// Recovery
+	"recovery.rerun_task",
+	// Run-level budget/effectiveness/export/lifecycle bookkeeping
+	"run.started",
+	"run.budget_warning",
+	"run.budget_abort",
+	"run.deliverable_warning",
+	"run.effectiveness",
+	"run.exported",
+	"run.forget_requested",
+	"run.goal_achievement",
+	"run.resume_requested",
+	// Runtime/surface resolution
+	"runtime.resolved",
+	"surface.degraded",
+	"surface.requeued",
+	// Task scheduling/steer/budget/fairness bookkeeping
+	"task.attention",
+	"task.claimed",
+	"task.claim_released",
+	"task.coalesced",
+	"task.coalesced_dispatch_start",
+	"task.coalesced_dispatch_end",
+	"task.parallel_start",
+	"task.status_transitioned",
+	"task.reconciled_from_disk",
+	"task.checkpoint_recovered",
+	"task.retry_attempt",
+	"task.budget_fair_share",
+	"task.model_dropped",
+	"task.output_validation",
+	"task.steer_queued",
+	"task.steer_dropped",
+	"task.surface_lost",
+	// Worker lifecycle (surface runtime / broker-side)
+	"worker.heartbeat",
+	"worker.cancelled",
+	"worker.kill_stale",
+	"worker.message",
+	// Workflow phase advance (note: supersedes the legacy `phase.*` names
+	// above, which are kept registered for backward compatibility)
+	"workflow.phase_completed",
+	"workflow.phase_failed",
+	"workflow.phase_guard_blocked",
+	"workflow.preconditions",
 ] as const;
 export type TeamEventType = (typeof TEAM_EVENT_TYPES)[number];
 

package/src/state/coordination/locks.ts

@@ -80,7 +80,11 @@ function isLockHolderAlive(filePath: string): boolean {
  *
  * Returns `{ canSteal: true }` if the lock is stale OR the holder is dead
  * (safe to forcibly remove); `{ canSteal: false }` if it is fresh AND held by
- * a live process (must keep waiting).
+ * a live process (must keep waiting). RR-011 additionally reports
+ * `heldByLiveInProcess: true` when the stored token belongs to a run-lock
+ * acquisition of THIS process that is still inside its critical section — the
+ * async acquire loop then WAITS (timer-based retry) instead of throwing or
+ * stealing.
  *
  * ## EPERM Handling (Accepted Risk)
  *
@@ -105,7 +109,11 @@ function isLockHolderAlive(filePath: string): boolean {
  *
  * See also: SECURITY-ISSUES.md SEC-008 for documented acceptance.
  */
-function readLockSnapshot(filePath: string, staleMs: number, options?: { treatOwnPidAsStealable?: boolean }): { canSteal: boolean } {
+function readLockSnapshot(
+	filePath: string,
+	staleMs: number,
+	options?: { treatOwnPidAsStealable?: boolean; activeHolderTokens?: ReadonlySet<string> },
+): { canSteal: boolean; heldByLiveInProcess: boolean } {
 	const treatOwnPidAsStealable = options?.treatOwnPidAsStealable === true;
 	let stat: fs.Stats | undefined;
 	let raw: string | undefined;
@@ -119,21 +127,23 @@ function readLockSnapshot(filePath: string, staleMs: number, options?: { treatOw
 		// "locked" error.
 		const code = (error as NodeJS.ErrnoException).code;
 		if (code === "ENOENT") {
-			return { canSteal: true };
+			return { canSteal: true, heldByLiveInProcess: false };
 		}
 		// Transient I/O error — be conservative (don't steal, retry the read on
 		// next attempt).
-		return { canSteal: false };
+		return { canSteal: false, heldByLiveInProcess: false };
 	}
 	// Staleness from a single snapshot.
 	let createdAt = parseCreatedAtFromLock(raw);
 	if (createdAt === undefined) createdAt = stat.mtimeMs;
 	const isStale = Date.now() - createdAt > staleMs;
 	let holderPid: number | undefined;
+	let holderToken: string | undefined;
 	let isAlive = true;
 	try {
-		const parsed = JSON.parse(raw) as { pid?: unknown };
+		const parsed = JSON.parse(raw) as { pid?: unknown; token?: unknown };
 		holderPid = typeof parsed.pid === "number" ? parsed.pid : undefined;
+		holderToken = typeof parsed.token === "string" ? parsed.token : undefined;
 	} catch {
 		/* malformed payload — keep isAlive=true */
 	}
@@ -151,9 +161,28 @@ function readLockSnapshot(filePath: string, staleMs: number, options?: { treatOw
 	// (used by withRunLock* which is single-process — a fresh lock with our pid
 	// between acquisitions is just a leftover from a previous call that
 	// releaseOwnLock didn't get to delete yet; safe to steal).
+	//
+	// RR-011 (F02): "our own pid" alone can no longer authorize a steal for the
+	// async run-lock path — a lock CURRENTLY HELD by another async context of
+	// this process also carries our pid while its holder is merely awaiting
+	// inside the critical section. The on-disk token disambiguates: a token in
+	// `activeHolderTokens` (runLockHeldTokens — every live acquisition of this
+	// process registers its token) means the holder is ALIVE in-process → the
+	// own-pid steal branch is suppressed (see acquireLockWithRetryAsync: such a
+	// holder WAITS instead of stealing/throwing). A token-less payload (legacy
+	// lock file) or a token not in the set is a leftover corpse → still stealable,
+	// preserving the anti-CI-flake behaviour the flag was added for.
+	// NOTE (trap, design.md §4.2): comparing the stored token to the CURRENT
+	// acquisition's token would be WRONG — each acquisition mints a fresh
+	// randomUUID, so a live holder's token always differs from ours and the
+	// predicate would steal anyway. Only a lookup into the LIVE-token set is
+	// correct.
 	const isOurOwnHolder = holderPid === process.pid;
+	const holderIsLiveInProcess = holderToken !== undefined && (options?.activeHolderTokens?.has(holderToken) ?? false);
+	const ownPidStealable = treatOwnPidAsStealable && isOurOwnHolder && !holderIsLiveInProcess;
 	return {
-		canSteal: isStale || !isAlive || (treatOwnPidAsStealable && isOurOwnHolder),
+		canSteal: isStale || !isAlive || ownPidStealable,
+		heldByLiveInProcess: holderIsLiveInProcess,
 	};
 }
 
@@ -239,25 +268,82 @@ function timingSafeTokenMatch(a: string, b: string): boolean {
 }
 
 /**
- * Release the lock we (this process) just acquired. Unlike releaseLock, this is
- * used in the `finally` blocks of withRunLock and withRunLockSync so the file was
- * created earlier in the SAME call. Within the same process the new acquire uses
- * a fresh randomUUID token, so token matching would falsely fail and leak the
- * file across releases.
+ * Release the lock we (this process) just acquired. Used in the `finally` blocks
+ * of withRunLock and withRunLockSync, so the file was created earlier in the SAME
+ * call and carries OUR token.
  *
  * LOCK-1 (Round 2): PID-guarded release. Previously this deleted
  * UNCONDITIONALLY — if our critical section exceeded staleMs, another process
  * could steal our lock (overwrite the file with its own pid); our finally would
- * then DELETE THE STEALER's lock, breaking mutual exclusion. We now verify the
- * lock file still records OUR pid before removing; if it records a different pid
- * the lock was stolen and the current holder owns it. Same-process re-acquire is
- * preserved (pid matches → delete). Mirrors the proven pattern in event-log.ts
- * (Round 26, BUG 5).
+ * then DELETE THE STEALER's lock, breaking mutual exclusion. We therefore verify
+ * the lock file still records OUR pid before removing; if it records a different
+ * pid the lock was stolen and the current holder owns it.
+ *
+ * RR-011 (F02): within one process, PID equality no longer identifies "our" lock
+ * — two same-process async holders are distinguished ONLY by token. A finishing
+ * context must not delete another acquisition's lock (verification probe 2: the
+ * lock file was ENOENT while the second holder was still inside its critical
+ * section). So after the pid check, the stored token must also match ours. A
+ * token-less payload (legacy lock file from an older release) keeps the
+ * PID-only behaviour so old files are still cleaned up.
  *
  * Symlink guard is preserved: if a symlink appeared since our writeLockFile, we
  * don't rm it (defense against attacker-planted symlinks).
  */
-export function releaseOwnLock(filePath: string, _token: string): void {
+/**
+ * US-002 (2026-09-22): structured, safe, idempotent sweep of stale run locks.
+ *
+ * Locks whose holder died without releasing (kill -9, crash) previously lingered
+ * until some future acquirer hit the stale-steal path. This gives the
+ * stale-reconciler an explicit pass.
+ *
+ * IMPORTANT — the sweep predicate is STRICTER than acquire-time `canSteal`:
+ * acquire steals on `stale OR holder-dead` (deliberate: a stale lock must not
+ * block a live run forever), but a SWEEP must only remove a lock whose holder is
+ * provably DEAD. Removing a stale-but-live holder's lock would let two processes
+ * enter the critical section. So: stale AND (no pid OR pid dead). A live pid is
+ * never swept, no matter how old.
+ *
+ * Returns the lock files it removed. Idempotent: a second sweep finds nothing.
+ */
+export function sweepStaleLocks(lockFiles: readonly string[], options: RunLockOptions = {}): { removed: string[] } {
+	const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+	const removed: string[] = [];
+	for (const filePath of lockFiles) {
+		try {
+			if (!fs.existsSync(filePath)) continue;
+			if (!isLockStale(filePath, staleMs)) continue; // fresh → leave alone
+			// Stale. Remove ONLY when no live holder owns it.
+			if (isLockHolderAlive(filePath)) continue;
+			fs.rmSync(filePath, { force: true });
+			removed.push(filePath);
+		} catch (error) {
+			logInternalError("locks.sweep-stale", error, `path=${filePath}`);
+		}
+	}
+	return { removed };
+}
+
+/**
+ * US-002: discover every `run.lock` under a runs root
+ * (`<runsRoot>/<runId>/run.lock`), bounded, for sweepStaleLocks. Missing → empty.
+ */
+export function discoverRunLockFiles(runsRoot: string, maxDirs = 500): string[] {
+	try {
+		if (!fs.existsSync(runsRoot)) return [];
+		return fs
+			.readdirSync(runsRoot, { withFileTypes: true })
+			.filter((e) => e.isDirectory())
+			.slice(0, maxDirs)
+			.map((e) => path.join(runsRoot, e.name, "run.lock"))
+			.filter((p) => fs.existsSync(p));
+	} catch (error) {
+		logInternalError("locks.discover-run-locks", error, `runsRoot=${runsRoot}`);
+		return [];
+	}
+}
+
+export function releaseOwnLock(filePath: string, token: string): void {
 	try {
 		const stat = fs.lstatSync(filePath);
 		if (stat.isSymbolicLink()) return;
@@ -266,11 +352,20 @@ export function releaseOwnLock(filePath: string, _token: string): void {
 	}
 	try {
 		const raw = fs.readFileSync(filePath, "utf-8");
-		const holderPid = (JSON.parse(raw) as { pid?: unknown })?.pid;
-		if (holderPid === process.pid) {
-			fs.rmSync(filePath, { force: true });
+		const parsed = JSON.parse(raw) as { pid?: unknown; token?: unknown };
+		const holderPid = parsed.pid;
+		const storedToken = typeof parsed.token === "string" ? parsed.token : undefined;
+		if (holderPid !== process.pid) {
+			// holderPid !== process.pid → lock stolen by another process; do NOT touch.
+			return;
 		}
-		// holderPid !== process.pid → lock stolen by another process; do NOT touch.
+		if (storedToken !== undefined && storedToken !== token) {
+			// RR-011 (F02): same process, different token → the lock now belongs to
+			// another acquisition of THIS process (steal window / superseded holder).
+			// Do not delete it — the current holder owns it.
+			return;
+		}
+		fs.rmSync(filePath, { force: true });
 	} catch (error) {
 		const code = (error as NodeJS.ErrnoException).code;
 		if (code !== "ENOENT") {
@@ -322,6 +417,25 @@ function isLockContention(code: string | undefined): boolean {
 	return code === "EEXIST" || code === "EPERM" || code === "EBUSY";
 }
 
+// RR-011 (F02): tokens of run-lock acquisitions that are CURRENTLY HELD in this
+// process. It answers exactly one question — "is this holder still alive
+// in-process?" — and NOTHING else:
+//   - Re-entrance (bypass) decisions stay in `lockCtx` (per async context). This
+//     set must NEVER be consulted for bypass — that is the H-1 bug class.
+//   - The async steal predicate consults it (via readLockSnapshot's
+//     activeHolderTokens) so a SECOND independent async context can no longer
+//     steal a lock whose holder is merely awaiting inside its critical section.
+//
+// INVARIANT: a token is added synchronously right after a successful acquire
+// (no await between acquire returning and the add) and deleted in the
+// acquisition's `finally` BEFORE releaseOwnLock runs — so a token in this set
+// always corresponds to a live critical section, and a leftover lock file from
+// a finished acquisition (token no longer in the set, or a legacy token-less
+// payload) remains stealable, preserving the CI-flake fix that
+// treatOwnPidAsStealable was added for. If a `finally` were ever skipped, the
+// leaked entry is inert: future lock files always mint a fresh randomUUID.
+const runLockHeldTokens = new Set<string>();
+
 function acquireLockWithRetry(filePath: string, staleMs: number, kind: LockKind = "file"): string {
 	let attempt = 0;
 	const deadline = Date.now() + staleMs * 2;
@@ -381,10 +495,48 @@ async function acquireLockWithRetryAsync(filePath: string, staleMs: number, kind
 			// file still exists with our own pid. Stealing it avoids spurious 'locked'
 			// errors. The sync file-lock path (withFileLockSync) above uses false to
 			// preserve the multi-process safety guarantee.
-			const { canSteal } = readLockSnapshot(filePath, staleMs, { treatOwnPidAsStealable: true });
-			if (!canSteal) {
+			// RR-011 (F02): the steal now consults runLockHeldTokens — a lock whose
+			// stored token belongs to a LIVE acquisition of this process is NOT a
+			// leftover corpse and must not be stolen (that broke async↔async mutual
+			// exclusion: two independent async contexts entered the critical section
+			// together). Token-less legacy files are still stolen (CI-flake fix).
+			const verdict = readLockSnapshot(filePath, staleMs, {
+				treatOwnPidAsStealable: true,
+				activeHolderTokens: runLockHeldTokens,
+			});
+			if (!verdict.canSteal && verdict.heldByLiveInProcess) {
+				// RR-011 (F02): the holder is a LIVE acquisition in THIS process (another
+				// async context awaiting inside its critical section). It releases in its
+				// `finally` on this same event loop — WAIT via a timer (never sleepSync:
+				// blocking the event loop would starve the very holder we are waiting
+				// for, the v0.9.26 deadlock class) and retry the create. The loop deadline
+				// above plus the staleMs check in readLockSnapshot bound the wait, so a
+				// hung holder eventually becomes stale-stealable and this can never
+				// block indefinitely.
+				const delay = Math.min(250, 25 * 2 ** attempt);
+				await sleep(delay);
+				attempt++;
+				continue;
+			}
+			if (!verdict.canSteal) {
 				throw new Error(`Run '${path.basename(filePath)}' is locked by another operation.`);
 			}
+			if (verdict.heldByLiveInProcess) {
+				// Review MAJOR 2: the staleMs backstop is stealing a lock whose holder
+				// is STILL a live acquisition of this process (its critical section
+				// legitimately exceeded staleMs — fsync stalls, loaded machine). The
+				// steal is the documented design (ADR 2026-09-17-run-lock-async-
+				// ownership) but mutual exclusion is about to be violated knowingly,
+				// so it must be observable, never silent — production holders are
+				// ms-scale; seeing this warn means the invariant "critical section <
+				// staleMs" was broken and the budget should be revisited.
+				logInternalError(
+					"locks.steal-live-holder",
+					new Error(`staleMs steal of a lock held by a LIVE in-process acquisition (staleMs=${staleMs})`),
+					filePath,
+					"warn",
+				);
+			}
 			// Stale or dead holder — forcibly remove the lock.
 			try {
 				fs.rmSync(filePath, { force: true });
@@ -622,6 +774,10 @@ export function withRunLockSync<T>(manifest: TeamRunManifest, fn: () => T, optio
 	}
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	const token = acquireLockWithRetry(filePath, staleMs, "run");
+	// RR-011 (F02): register the hold so async contenders of this process see a
+	// LIVE holder (wait) instead of a stealable corpse. Sync here too, keeping the
+	// invariant uniform for every run-lock acquisition of this process.
+	runLockHeldTokens.add(token);
 	const prevHeld = lockCtx.getStore() ?? new Set<string>();
 	const newHeld = new Set(prevHeld);
 	newHeld.add(filePath);
@@ -632,14 +788,11 @@ export function withRunLockSync<T>(manifest: TeamRunManifest, fn: () => T, optio
 		try {
 			return fn();
 		} finally {
-			// FIX (CI flake): releaseLock uses token matching to prevent the
-			// "losing contender wipes winner's lock" race in multi-process scenarios.
-			// But within withRunLockSync/withRunLock (same process), the new acquire
-			// uses a FRESH random token — the previous stored token doesn't match the
-			// current token — and the lock file is never removed. Repeat acquisitions
-			// then keep failing with EEXIST because the file lingers.
-			// Since withRunLock* is always single-process, unconditionally delete
-			// (symlink guard is still applied for safety).
+			// RR-011 (F02): unregister BEFORE releasing (see runLockHeldTokens
+			// invariant) — the token must not linger as "live" once the hold ends.
+			// releaseOwnLock is token-guarded: if our lock was superseded in the
+			// meantime, the current holder's file is left untouched.
+			runLockHeldTokens.delete(token);
 			releaseOwnLock(filePath, token);
 		}
 	});
@@ -654,6 +807,10 @@ export async function withRunLock<T>(manifest: TeamRunManifest, fn: () => Promis
 	}
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	const token = await acquireLockWithRetryAsync(filePath, staleMs, "run");
+	// RR-011 (F02): register the hold IMMEDIATELY (no await between the acquire
+	// returning and this add — otherwise a concurrent contender could observe the
+	// fresh on-disk token as a stealable corpse). Deleted in the finally below.
+	runLockHeldTokens.add(token);
 	const prevHeld = lockCtx.getStore() ?? new Set<string>();
 	const newHeld = new Set(prevHeld);
 	newHeld.add(filePath);
@@ -664,8 +821,9 @@ export async function withRunLock<T>(manifest: TeamRunManifest, fn: () => Promis
 		try {
 			return await fn();
 		} finally {
-			// FIX (CI flake): see withRunLockSync above — use releaseOwnLock for
-			// unconditional deletion of the lock file we created (same process).
+			// RR-011 (F02): see withRunLockSync above — unregister the live token
+			// BEFORE the token-guarded releaseOwnLock (runLockHeldTokens invariant).
+			runLockHeldTokens.delete(token);
 			releaseOwnLock(filePath, token);
 		}
 	});