pi-crew 0.11.12 → 0.11.13

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-crew",
-	"version": "0.11.12",
+	"version": "0.11.13",
 	"description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
 	"author": "baphuongna",
 	"license": "MIT",

package/src/extension/team-tool/run-deadline.ts

@@ -22,6 +22,24 @@ export interface RunDeadline {
 /** Fallback deadline when no config or param override is available: 1 hour. */
 export const DEFAULT_RUN_DEADLINE_MS = 3_600_000;
 
+/** Options for resolveRunDeadline. */
+export interface RunDeadlineOptions {
+	/** "abort" (default): arm the deadline timer that ABORTS the controller —
+	 *  deadline expiry cancels the run (direct-await paths: DWF, goal-loop,
+	 *  inline scaffold — the deadline IS the execution bound).
+	 *
+	 *  "watch-only": do NOT arm the abort timer. The deadline bounds only the
+	 *  caller's WATCH (waitForRun timeoutMs). Genuine caller cancels
+	 *  (ctx.signal abort outside a session switch, startForegroundRun callback
+	 *  abort) STILL abort the controller and cancel the run — deadline expiry
+	 *  alone never does. RELIABILITY FIX 2026-10-10 (wave-2 chain incident, run
+	 *  team_20261010045718): the foreground lane's armed timer was aborting
+	 *  executeTeamRun's signal at the 60-minute watch boundary — chain steps
+	 *  reported "partial" AND the still-healthy child run was cancelled. The
+	 *  watch is a timer; the cancel must be a caller decision. */
+	timer?: "abort" | "watch-only";
+}
+
 /**
  * Resolve a unified run deadline with a shared AbortController.
  *
@@ -49,6 +67,7 @@ export function resolveRunDeadline<T extends object>(
 	ctx: Pick<TeamContext, "cwd" | "signal">,
 	params: T,
 	config?: PiTeamsConfig,
+	options?: RunDeadlineOptions,
 ): RunDeadline {
 	const timeoutMs = (params as { timeoutMs?: number }).timeoutMs;
 	const effectiveConfig = config ?? loadConfig(ctx.cwd).config;
@@ -94,8 +113,10 @@ export function resolveRunDeadline<T extends object>(
 	// otherwise every run leaves a dangling 1h timer retaining ctx/params in closure.
 	// Same abort-after-exit guard as above: the timer may fire after workers
 	// already exited and their spawn-signal listeners are gone — Node can throw.
+	// "watch-only" (bug #2 fix): the timer is NOT armed — the deadline bounds the
+	// watch only, so the controller can only be aborted by a real caller cancel.
 	let timer: NodeJS.Timeout | undefined;
-	if (deadlineMs > 0) {
+	if (deadlineMs > 0 && options?.timer !== "watch-only") {
 		timer = setTimeout(() => safeAbort(controller, "run-deadline.timer"), deadlineMs);
 		timer.unref?.();
 	}

package/src/extension/team-tool/run.ts

@@ -71,7 +71,7 @@ import * as path from "node:path";
 import { t } from "../../i18n.ts";
 import { hasAsyncStartMarker } from "../../runtime/async-marker.ts";
 import { checkProcessLiveness, isActiveRunStatus } from "../../runtime/process-status.ts";
-import { registerRunPromise, waitForRun } from "../../runtime/run-tracker.ts";
+import { isWaitForRunTimeoutError, registerRunPromise, waitForRun } from "../../runtime/run-tracker.ts";
 import { collectRunMetrics } from "../../state/stores/run-metrics.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { effectiveRunConfig } from "./config-patch.ts";
@@ -709,7 +709,14 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 	const executeWorkers = runtime.kind !== "scaffold";
 	if (executeWorkers && ctx.startForegroundRun) {
 		// CORE-8: unified deadline — resolves params > config > 1h default.
-		const fgDeadline = resolveRunDeadline(ctx, params, executedConfig);
+		// RELIABILITY FIX 2026-10-10 (bug #2, wave-2 chain incident run
+		// team_20261010045718): the foreground deadline is WATCH-ONLY. The armed
+		// abort timer used to cancel executeTeamRun's signal at the watch
+		// boundary (60m default) — chain steps reported "partial" AND the
+		// still-healthy child run was cancelled. waitForRun's own timeout still
+		// bounds the watch (partial-watch result below); real caller cancels
+		// (ctx.signal / foreground-run callback abort) still cancel the run.
+		const fgDeadline = resolveRunDeadline(ctx, params, executedConfig, { timer: "watch-only" });
 		// F1 register/await race fix (2026-09-12): the waitForRun below runs
 		// immediately after startForegroundRun returns (void), while
 		// executeTeamRunCore registers its promise only after several awaits —
@@ -842,6 +849,35 @@ export async function handleRun(params: TeamToolParamsValue, ctx: TeamContext):
 			});
 		} catch (waitError: unknown) {
 			const waitErrMsg = errorMessage(waitError);
+			// RELIABILITY FIX 2026-10-10 (bug #2): a waitForRun WATCH expiry is NOT a
+			// run failure — with the watch-only deadline the run keeps executing in
+			// the foreground lane (exactly like the detached case) and the async
+			// notifier reports completion later. Report a partial-watch instead of an
+			// error so chain wrappers map the still-running step to "partial"
+			// without anyone reading this as "the run was cancelled/failed".
+			if (isWaitForRunTimeoutError(waitError)) {
+				return result(
+					[
+						`pi-crew run still running (watch window expired): ${updatedManifest.runId}`,
+						`Team: ${team.name}`,
+						`Workflow: ${workflow.name}`,
+						`Watch: ${waitErrMsg} — the run was NOT cancelled and keeps executing.`,
+						"",
+						"You will be notified when the run finishes.",
+						`Check status with: team action=status runId=${updatedManifest.runId}`,
+						`Wait again with: team action=wait runId=${updatedManifest.runId}`,
+						`State: ${updatedManifest.stateRoot}`,
+					].join("\n"),
+					{
+						action: "run",
+						status: "ok",
+						runId: updatedManifest.runId,
+						artifactsRoot: updatedManifest.artifactsRoot,
+						partialWatch: true,
+					},
+					false,
+				);
+			}
 			return result(
 				[
 					`pi-crew run timed out or failed: ${updatedManifest.runId}`,

package/src/extension/team-tool-types.ts

@@ -29,6 +29,10 @@ export interface TeamToolDetails {
 	taskId?: string;
 	questionId?: string;
 	waiting?: boolean;
+	/** RELIABILITY FIX 2026-10-10 (bug #2): set when the foreground run's WATCH
+	 * window expired (waitForRun timeout) — the run itself was NOT cancelled
+	 * and keeps executing; the async notifier reports completion later. */
+	partialWatch?: boolean;
 	/** Structured data for programmatic consumption (e.g. TUI widgets). */
 	data?: Record<string, unknown>;
 }

package/src/extension/team-tool.ts

@@ -493,7 +493,7 @@ async function resumeDynamicWorkflowRun(
 		return result(
 			[
 				`Resumed dynamic-workflow run ${dwfResult.manifest.runId}.`,
-				`Status: ${dwfResult.manifest.status}`,
+				`Status: ${dwfResult.manifest.status} — resumed execution returned`,
 				dwfResult.manifest.summary ? `Result: ${dwfResult.manifest.summary}` : undefined,
 			]
 				.filter((line): line is string => line !== undefined)
@@ -819,6 +819,13 @@ export async function handleResume(params: TeamToolParamsValue, ctx: TeamContext
 					}
 				: task,
 		);
+		// RELIABILITY FIX 2026-10-10 (bug #3): count the tasks actually re-queued at
+		// resume so the result message can report what happened (work re-dispatched
+		// vs "run was already terminal, nothing to resume") instead of a bare
+		// "Status: completed" that reads as "everything finished instantly".
+		const requeuedCount = recovered.tasks.filter(
+			(task) => task.status === "failed" || task.status === "cancelled" || task.status === "skipped" || task.status === "running",
+		).length;
 		saveRunTasks(runtimeManifest, resetTasks);
 		const replay = replayPendingMailboxMessages(runtimeManifest);
 		await appendEventAsync(runtimeManifest.eventsPath, {
@@ -874,6 +881,7 @@ export async function handleResume(params: TeamToolParamsValue, ctx: TeamContext
 			kind: "execute" as const,
 			runtimeManifest: executingManifest,
 			resetTasks,
+			requeuedCount,
 			executeWorkers,
 			resumeSkillOverride,
 			runtime,
@@ -909,12 +917,32 @@ export async function handleResume(params: TeamToolParamsValue, ctx: TeamContext
 		// Finding 8: resume is the legitimate terminal-exit flow.
 		isResume: true,
 	});
+	// RELIABILITY FIX 2026-10-10 (bug #3, wave-2/wave-3 observations): the old
+	// message printed a bare "Status: completed" which read as "the whole run
+	// just finished" even when the resume had re-queued real work that kept
+	// executing. Report the truth: what the resumed execution returned, how
+	// much work was re-queued at resume, and the per-status task breakdown.
+	const statusLine =
+		executed.manifest.status === "completed"
+			? "completed — resumed execution finished (all tasks terminal)"
+			: executed.manifest.status === "running"
+				? "running — resumed dispatch is still executing"
+				: `${executed.manifest.status} — resumed execution ended in this state`;
+	const taskCounts = executed.tasks.reduce<Record<string, number>>((acc, task) => {
+		acc[task.status] = (acc[task.status] ?? 0) + 1;
+		return acc;
+	}, {});
+	const countsText = Object.entries(taskCounts)
+		.map(([status, count]) => `${count} ${status}`)
+		.join(", ");
 	return result(
 		[
 			`Resumed run ${executed.manifest.runId}.`,
-			`Status: ${executed.manifest.status}`,
-			`Tasks: ${executed.tasks.length}`,
+			`Status: ${statusLine}`,
+			`Resumed work: ${decision.requeuedCount} task(s) re-queued${decision.requeuedCount === 0 ? " (run was already terminal — nothing to resume)" : ""}`,
+			`Tasks: ${executed.tasks.length} (${countsText})`,
 			`Artifacts: ${executed.manifest.artifactsRoot}`,
+			`Check live status with: team action=status runId=${executed.manifest.runId}`,
 		].join("\n"),
 		{
 			action: "resume",

package/src/runtime/broker/protocol/lock-busy.ts

@@ -16,7 +16,7 @@
  * Precedent: protocol/request-parsers.ts (M4/WI-4.1 extraction discipline).
  */
 
-import { withRunLockSync } from "../../../state/coordination/locks.ts";
+import { withRunLock, withRunLockSync } from "../../../state/coordination/locks.ts";
 import type { TeamRunManifest } from "../../../state/types.ts";
 
 /** Default bounded retry schedule for run.lock contention (ms). Five
@@ -24,6 +24,19 @@ import type { TeamRunManifest } from "../../../state/types.ts";
  *  detached runner's state flush — without parking the request. */
 export const DEFAULT_LOCK_BUSY_RETRY_DELAYS_MS: readonly number[] = [50, 100, 200, 400, 800];
 
+/** Merge-site busy-retry schedule (ms) — RELIABILITY FIX 2026-10-10
+ *  (run team_20261010100956 incident: background-runner killed by an
+ *  unhandled rejection when mergeUnitResult's withRunLock lost a run.lock
+ *  contention race against a concurrent writer). Longer than the broker
+ *  default above: a merge under contention sits on the scheduler's critical
+ *  path — the run is mid-flight and the settled unit is held in memory — so
+ *  it is worth ~7.9s of back-off (6 attempts) before the busy error is
+ *  allowed to propagate to the run-level error handler. Each attempt itself
+ *  already waits up to staleMs*2 inside acquireLockWithRetryAsync for
+ *  in-process holders; this schedule covers the LIVE FOREIGN holder case,
+ *  which throws immediately. */
+export const MERGE_LOCK_BUSY_RETRY_DELAYS_MS: readonly number[] = [100, 250, 500, 1000, 2000, 4000];
+
 /** Match the exact identity locks.ts throws for a LIVE holder on the
  *  never-steal path (sync acquireLockWithRetry, its async twin, and the
  *  lockCtx fallthrough): `Run '<basename>' is locked by another operation.`
@@ -74,3 +87,36 @@ export async function withRunLockBusyRetry<T>(
 function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+/** Async twin of withRunLockBusyRetry for the scheduler's merge sites
+ *  (merge-loop.ts mergeUnitResult, budget-enforcement.ts
+ *  terminaliseRunWithDrain): run `fn` under the ASYNC withRunLock with a
+ *  bounded busy-retry, notifying `onRetry` before each back-off sleep so the
+ *  call site can log a lock_retry event.
+ *
+ *  Retry safety mirrors the sync twin: the busy throw is raised by the lock
+ *  ACQUIRE before `fn` runs, and every nested state write inside the merge
+ *  bodies is lockCtx-reentrant (same-context nesting never re-acquires), so a
+ *  retry never re-executes a partially-run body. Any NON-busy error
+ *  propagates unchanged — real faults (ENOSPC, EACCES, corruption) keep their
+ *  current fatal path; only the transient contention identity is retried.
+ *  When the schedule is exhausted the busy error is rethrown for the run-level
+ *  handler to classify (bounded — never an infinite loop). */
+export async function withRunLockBusyRetryAsync<T>(
+	manifest: TeamRunManifest,
+	delaysMs: readonly number[],
+	fn: () => Promise<T>,
+	onRetry?: (attempt: number, delayMs: number, error: Error) => void,
+): Promise<T> {
+	for (let attempt = 0; ; attempt++) {
+		try {
+			return await withRunLock(manifest, fn);
+		} catch (error) {
+			if (!isRunLockBusyError(error)) throw error;
+			const delay = delaysMs[attempt];
+			if (delay === undefined) throw error;
+			onRetry?.(attempt + 1, delay, error as Error);
+			await sleep(delay);
+		}
+	}
+}

package/src/runtime/budget-enforcement.ts

@@ -16,12 +16,12 @@
  * team-runner.ts would create a cycle).
  */
 import { flushPendingAtomicWrites } from "../state/atomic-write.ts";
-import { withRunLock } from "../state/coordination/locks.ts";
 import { appendEventAsync } from "../state/event-log/event-log.ts";
 import { loadRunManifestById, saveRunManifestAsync, saveRunTasksAsync, updateRunStatus } from "../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { aggregateUsage, formatTokens } from "../state/usage.ts";
 import { logInternalError } from "../utils/internal-error.ts";
+import { MERGE_LOCK_BUSY_RETRY_DELAYS_MS, withRunLockBusyRetryAsync } from "./broker/protocol/lock-busy.ts";
 import { saveCrewAgents } from "./crew-agent-records.ts";
 import { cancelNonTerminalTasks, markBlocked } from "./dispatch-batch.ts";
 import { isNonTerminalTaskStatus, mergeTaskUpdatesPreservingTerminal } from "./merge-gate.ts";
@@ -136,25 +136,41 @@ export async function terminaliseRunWithDrain(
 	if (validResults.length > 0) {
 		// Merge under the run lock — same pattern as mergeUnitResult:
 		// flush pending writes, load disk state, merge artifacts + tasks,
-		// save atomically.
-		const mergeResult = await withRunLock(ctx.manifest, async () => {
-			flushPendingAtomicWrites();
-			const disk = loadRunManifestById(ctx.manifest.cwd, ctx.manifest.runId);
-			const diskManifest = disk?.manifest ?? ctx.manifest;
-			const reconciledArtifacts = mergeArtifacts([
-				...diskManifest.artifacts,
-				...validResults.flatMap((item) => item.manifest.artifacts),
-			]);
-			const resultManifest = updateRunStatus(
-				{ ...diskManifest, artifacts: reconciledArtifacts },
-				"running",
-				"Merged in-flight results during failed-task abort.",
-			);
-			const resultTasks = mergeTaskUpdatesPreservingTerminal(disk?.tasks ?? ctx.tasks, validResults);
-			await saveRunManifestAsync(resultManifest);
-			await saveRunTasksAsync(resultManifest, resultTasks);
-			return { resultManifest, resultTasks };
-		});
+		// save atomically. RELIABILITY FIX 2026-10-10: bare withRunLock here had
+		// the same contention-fatal flaw as mergeUnitResult (see merge-loop.ts) —
+		// a busy run.lock on this abort path would surface as an unhandled
+		// rejection downstream. Bounded busy-retry + run.lock_retry event now.
+		const mergeResult = await withRunLockBusyRetryAsync(
+			ctx.manifest,
+			MERGE_LOCK_BUSY_RETRY_DELAYS_MS,
+			async () => {
+				flushPendingAtomicWrites();
+				const disk = loadRunManifestById(ctx.manifest.cwd, ctx.manifest.runId);
+				const diskManifest = disk?.manifest ?? ctx.manifest;
+				const reconciledArtifacts = mergeArtifacts([
+					...diskManifest.artifacts,
+					...validResults.flatMap((item) => item.manifest.artifacts),
+				]);
+				const resultManifest = updateRunStatus(
+					{ ...diskManifest, artifacts: reconciledArtifacts },
+					"running",
+					"Merged in-flight results during failed-task abort.",
+				);
+				const resultTasks = mergeTaskUpdatesPreservingTerminal(disk?.tasks ?? ctx.tasks, validResults);
+				await saveRunManifestAsync(resultManifest);
+				await saveRunTasksAsync(resultManifest, resultTasks);
+				return { resultManifest, resultTasks };
+			},
+			(attempt, delayMs, error) => {
+				// Best-effort observability only — a failed event append must not break the retry.
+				appendEventAsync(ctx.manifest.eventsPath, {
+					type: "run.lock_retry",
+					runId: ctx.manifest.runId,
+					message: `run.lock contention during abort drain merge (attempt ${attempt}); retrying in ${delayMs}ms: ${error.message}`,
+					data: { attempt, delayMs, site: "terminaliseRunWithDrain" },
+				}).catch(() => undefined);
+			},
+		);
 		ctx.manifest = mergeResult.resultManifest;
 		ctx.tasks = mergeResult.resultTasks;
 	}

package/src/runtime/merge-loop.ts

@@ -13,10 +13,11 @@
  * keeping it here avoids a merge-loop ↔ finalize-run import cycle.
  */
 import { flushPendingAtomicWrites } from "../state/atomic-write.ts";
-import { withRunLock } from "../state/coordination/locks.ts";
+import { appendEventAsync } from "../state/event-log/event-log.ts";
 import { loadRunManifestById, saveRunManifestAsync, saveRunTasksAsync, updateRunStatus } from "../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { classifyFatalFsError } from "../utils/fs-errno.ts";
+import { MERGE_LOCK_BUSY_RETRY_DELAYS_MS, withRunLockBusyRetryAsync } from "./broker/protocol/lock-busy.ts";
 import { cancelNonTerminalTasks } from "./dispatch-batch.ts";
 import { mergeTaskUpdatesPreservingTerminal } from "./merge-gate.ts";
 import type { SchedulerContext, SchedulerDecision } from "./scheduler-context.ts";
@@ -86,40 +87,67 @@ export async function mergeUnitResult(ctx: SchedulerContext): Promise<SchedulerD
 	// not the arbitrary order in which mapConcurrent returned results.
 	// Read committed manifest from disk inside the lock so artifact merge is based
 	// on committed state, not in-memory state that may differ from disk.
-	const mergeResult = await withRunLock(ctx.manifest, async () => {
-		// NEW-D1: flush any pending coalesced atomic writes before reading from
-		// disk. Without this, a worker's async manifest save (coalesced by
-		// atomic-write) may not be committed yet, causing a lost-update on the
-		// merge read. flushPendingAtomicWrites forces all queued writes to disk.
-		flushPendingAtomicWrites();
-		const disk = loadRunManifestById(ctx.manifest.cwd, ctx.manifest.runId);
-		const diskManifest = disk?.manifest ?? ctx.manifest;
-		const diskArtifacts = diskManifest.artifacts;
-		const reconciledArtifacts = mergeArtifacts([...diskArtifacts, ...validResults.map((item) => item.manifest.artifacts)].flat());
-		// R15-2: only force "running" when the disk manifest is NON-terminal
-		// (queued/planning/running/blocked). If the disk status is already terminal
-		// (cancelled/failed/completed — an external cancel or reconciler write
-		// landing during the batch), PRESERVE that terminal status: forcing
-		// "running" would legally erase it (contracts.ts allows cancelled/failed/
-		// completed → running) and the loop would never observe the disk-terminal
-		// (CANCEL-1/CANCEL-2 only catch worker-reported cancel or signal abort).
-		const mergedBase = { ...diskManifest, artifacts: reconciledArtifacts };
-		const resultManifest = isRunTerminalPreserved(diskManifest.status)
-			? mergedBase
-			: updateRunStatus(mergedBase, "running", "Merged task updates from parallel batch.");
-		// CANCEL-1: use the freshly-loaded disk tasks as the merge base instead
-		// of the in-memory `tasks` closure variable. The in-memory tasks reflect
-		// only team-runner's view; an external cancel (handleCancel, background
-		// race with SIGTERM arriving after cancel wrote but before merge ran)
-		// writes 'cancelled' to disk.tasks — using disk.tasks as base preserves
-		// that cancellation through the merge instead of overwriting it with the
-		// stale in-memory view. disk was loaded inside this lock, so it reflects
-		// the freshest committed state.
-		const resultTasks = mergeTaskUpdatesPreservingTerminal(disk?.tasks ?? ctx.tasks, validResults);
-		await saveRunManifestAsync(resultManifest);
-		await saveRunTasksAsync(resultManifest, resultTasks);
-		return { resultManifest, resultTasks };
-	});
+	// RELIABILITY FIX 2026-10-10 (run team_20261010100956 incident): the merge
+	// used a bare withRunLock. Under run.lock contention (a second writer —
+	// stale reconciler, resumed runner, or a slow ENOSPC-degraded writer —
+	// holding run.lock past the acquire retry budget) withRunLock throws the
+	// plain "Run 'run.lock' is locked by another operation." error, which
+	// escaped executeTeamRun's catch → rejectRunPromise → an UNHANDLED promise
+	// rejection (no waitForRun waiter in background-runner mode) → the runner's
+	// unhandledRejection guard killed the whole runner mid-run. The merge now
+	// retries transient contention with back-off (logging a run.lock_retry
+	// event per attempt); only after the bounded schedule is exhausted does
+	// the busy error propagate for the run-level handler to classify. Non-busy
+	// errors (real faults) keep their existing fatal path — this is NOT a
+	// swallow-all.
+	const mergeResult = await withRunLockBusyRetryAsync(
+		ctx.manifest,
+		MERGE_LOCK_BUSY_RETRY_DELAYS_MS,
+		async () => {
+			// NEW-D1: flush any pending coalesced atomic writes before reading from
+			// disk. Without this, a worker's async manifest save (coalesced by
+			// atomic-write) may not be committed yet, causing a lost-update on the
+			// merge read. flushPendingAtomicWrites forces all queued writes to disk.
+			flushPendingAtomicWrites();
+			const disk = loadRunManifestById(ctx.manifest.cwd, ctx.manifest.runId);
+			const diskManifest = disk?.manifest ?? ctx.manifest;
+			const diskArtifacts = diskManifest.artifacts;
+			const reconciledArtifacts = mergeArtifacts([...diskArtifacts, ...validResults.map((item) => item.manifest.artifacts)].flat());
+			// R15-2: only force "running" when the disk manifest is NON-terminal
+			// (queued/planning/running/blocked). If the disk status is already terminal
+			// (cancelled/failed/completed — an external cancel or reconciler write
+			// landing during the batch), PRESERVE that terminal status: forcing
+			// "running" would legally erase it (contracts.ts allows cancelled/failed/
+			// completed → running) and the loop would never observe the disk-terminal
+			// (CANCEL-1/CANCEL-2 only catch worker-reported cancel or signal abort).
+			const mergedBase = { ...diskManifest, artifacts: reconciledArtifacts };
+			const resultManifest = isRunTerminalPreserved(diskManifest.status)
+				? mergedBase
+				: updateRunStatus(mergedBase, "running", "Merged task updates from parallel batch.");
+			// CANCEL-1: use the freshly-loaded disk tasks as the merge base instead
+			// of the in-memory `tasks` closure variable. The in-memory tasks reflect
+			// only team-runner's view; an external cancel (handleCancel, background
+			// race with SIGTERM arriving after cancel wrote but before merge ran)
+			// writes 'cancelled' to disk.tasks — using disk.tasks as base preserves
+			// that cancellation through the merge instead of overwriting it with the
+			// stale in-memory view. disk was loaded inside this lock, so it reflects
+			// the freshest committed state.
+			const resultTasks = mergeTaskUpdatesPreservingTerminal(disk?.tasks ?? ctx.tasks, validResults);
+			await saveRunManifestAsync(resultManifest);
+			await saveRunTasksAsync(resultManifest, resultTasks);
+			return { resultManifest, resultTasks };
+		},
+		(attempt, delayMs, error) => {
+			// Best-effort observability only — a failed event append (e.g. the same
+			// degraded disk that caused the contention) must not break the retry.
+			appendEventAsync(ctx.manifest.eventsPath, {
+				type: "run.lock_retry",
+				runId: ctx.manifest.runId,
+				message: `run.lock contention during unit merge (attempt ${attempt}); retrying in ${delayMs}ms: ${error.message}`,
+				data: { attempt, delayMs, site: "mergeUnitResult" },
+			}).catch(() => undefined);
+		},
+	);
 	ctx.manifest = mergeResult.resultManifest;
 	ctx.tasks = mergeResult.resultTasks;
 	ctx.settledMerge = { taskIds: completedUnit.taskIds, result: resultToMerge };

package/src/runtime/run-tracker.ts

@@ -67,6 +67,20 @@ export function registerRunPromise(runId: string): ActiveRunPromise {
 		reject = rej;
 	});
 	const entry: ActiveRunPromise = { promise, resolve, reject };
+	// RELIABILITY FIX 2026-10-10 (run team_20261010100956 incident): a run
+	// registered in a process with NO waitForRun waiter (background-runner
+	// mode — the runner awaits executeTeamRun directly, nothing races
+	// entry.promise) and later REJECTED (executeTeamRun's catch calls
+	// rejectRunPromise with the original error) left the rejection unobserved
+	// → Node unhandledRejection → the background-runner's guard aborted the
+	// whole runner AFTER its cleanup had already run (heartbeat stopped →
+	// stale-reconciler mass-cancelled every task). Attaching a no-op rejection
+	// handler marks the promise handled; consumers still observe the rejection
+	// through their own .then/.race attachments — this changes nothing for
+	// foreground waiters, it only stops a waiter-less rejection from killing
+	// the process. Run failures themselves remain fully reported through the
+	// normal executeTeamRun catch path (manifest failed + async.failed event).
+	promise.catch(() => undefined);
 	activeRunPromises.set(runId, entry);
 	return entry;
 }
@@ -128,6 +142,20 @@ export function rejectRunPromise(runId: string, reason: unknown): void {
 	}
 }
 
+/** Identity matcher for waitForRun's timeout error — thrown by BOTH wait
+ *  paths (the promise-race fast path and the polling slow path) as
+ *  `waitForRun timed out after <N>ms`. Callers use it to distinguish "the
+ *  WATCH window expired — the run itself may still be executing" from real
+ *  wait failures (run not found, corrupt state). RELIABILITY FIX 2026-10-10
+ *  (bug #2): a watch expiry must be reported as a partial-watch, never
+ *  conflated with a run failure. Message identity — run-tracker exports no
+ *  error class (plain Error), mirroring lock-busy.ts's matcher precedent. */
+const WAIT_FOR_RUN_TIMEOUT_MESSAGE = /^waitForRun timed out after \d+ms$/;
+
+export function isWaitForRunTimeoutError(error: unknown): boolean {
+	return error instanceof Error && WAIT_FOR_RUN_TIMEOUT_MESSAGE.test(error.message);
+}
+
 function raceRunPromise(entry: ActiveRunPromise, timeoutMs: number, deadline: number): Promise<RunWaitResult> {
 	let timer: ReturnType<typeof setTimeout> | undefined;
 	const remaining = Math.max(0, deadline - Date.now());

package/src/state/contracts.ts

@@ -254,6 +254,11 @@ export const TEAM_EVENT_TYPES = [
 	"run.exported",
 	"run.forget_requested",
 	"run.goal_achievement",
+	// RELIABILITY FIX 2026-10-10 (run team_20261010100956 incident): run.lock
+	// contention observed by a scheduler merge site (mergeUnitResult /
+	// terminaliseRunWithDrain) that is being retried with back-off — diagnostic
+	// only; never transitions run state.
+	"run.lock_retry",
 	"run.resume_requested",
 	// SDD-3 W-C G4 (team-tool.ts handleResume): forced resume of a FOREIGN-owned
 	// run — ownership was bypassed with force:true (liveness was NOT bypassable;