pi-crew 0.9.68 → 0.10.2

package/src/state/event-log/sequence-cache.ts

@@ -0,0 +1,373 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { errors } from "../../errors.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { sleepSync } from "../../utils/sleep.ts";
+import { atomicWriteFile } from "../atomic-write.ts";
+import type { TeamEvent } from "./event-log.ts";
+
+export const sequenceCache = new Map<string, { size: number; mtimeMs: number; seq: number; lastAccessMs: number }>();
+export const MAX_SEQUENCE_CACHE_ENTRIES = 256;
+
+export function evictOldestSequenceCacheEntries(): void {
+	// FIX: Evict by lastAccessMs (access time), not insertion order.
+	// Frequently accessed entries should be retained even if older.
+	const toEvict = Math.ceil(MAX_SEQUENCE_CACHE_ENTRIES / 2);
+	// Sort entries by lastAccessMs ascending (oldest first)
+	const entries = [...sequenceCache.entries()].sort((a, b) => a[1].lastAccessMs - b[1].lastAccessMs);
+	// Evict the oldest half
+	for (let i = 0; i < toEvict && i < entries.length; i++) {
+		sequenceCache.delete(entries[i][0]);
+	}
+}
+
+/** @internal — exported for sequence-cache LRU testing (Round 19). */
+export function __test__sequenceCacheSize(): number {
+	return sequenceCache.size;
+}
+
+/** @internal — seed an entry into the sequence cache for testing. */
+export function __test__seedSequenceCache(eventsPath: string, lastAccessMs: number): void {
+	sequenceCache.set(eventsPath, {
+		size: 1,
+		mtimeMs: 0,
+		seq: 0,
+		lastAccessMs,
+	});
+}
+
+/** @internal — expose eviction for testing. */
+export function __test__evictOldestSequenceCacheEntries(): void {
+	evictOldestSequenceCacheEntries();
+}
+
+/** @internal — clear the sequence cache. */
+export function __test__clearSequenceCache(): void {
+	sequenceCache.clear();
+}
+
+/** @internal — clear the in-process seqCounters Map so nextSequence seeds
+ *  fresh from the sidecar/file (simulates a process restart for testing). */
+export function __test__clearSeqCounters(): void {
+	seqCounters.clear();
+}
+
+/** @internal — the raw nextSequence for testing (forces re-seed from disk
+ *  by requiring the caller to have already cleared both caches). */
+export function __test__nextSequence(eventsPath: string): number {
+	return nextSequence(eventsPath);
+}
+
+/** @internal — the max sequence cache entries bound. */
+export const MAX_SEQUENCE_CACHE_ENTRIES_VALUE = MAX_SEQUENCE_CACHE_ENTRIES;
+
+export function sequencePath(eventsPath: string): string {
+	return `${eventsPath}.seq`;
+}
+
+function parseSequence(raw: string): number | undefined {
+	const value = Number.parseInt(raw.trim(), 10);
+	return Number.isInteger(value) && value >= 0 ? value : undefined;
+}
+
+export function scanSequence(eventsPath: string): number {
+	if (!fs.existsSync(eventsPath)) return 0;
+	let max = 0;
+	let skipped = 0;
+	for (const line of fs.readFileSync(eventsPath, "utf-8").split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			const event = JSON.parse(line) as TeamEvent;
+			max = Math.max(max, event.metadata?.seq ?? 0);
+		} catch {
+			skipped++;
+		}
+	}
+	if (skipped > 0) {
+		logInternalError("event-log.scanSequence.corrupt_lines", undefined, `${eventsPath}: skipped ${skipped} corrupt line(s)`);
+	}
+	return max;
+}
+
+function readStoredSequence(eventsPath: string): number | undefined {
+	try {
+		return parseSequence(fs.readFileSync(sequencePath(eventsPath), "utf-8"));
+	} catch {
+		return undefined;
+	}
+}
+
+function nextSequence(eventsPath: string): number {
+	if (!fs.existsSync(eventsPath)) return 1;
+	const stat = fs.statSync(eventsPath);
+	const cached = sequenceCache.get(eventsPath);
+	if (cached && cached.size === stat.size && cached.mtimeMs === stat.mtimeMs) {
+		return cached.seq + 1;
+	}
+	// FIX: Trust the sidecar seq file if it exists and the file is non-empty.
+	// Explicitly check for file shrinkage (stat.size < cached.size) to trigger
+	// re-scan when rotation or compaction has occurred.
+	const stored = readStoredSequence(eventsPath);
+	const fileShrunk = cached && stat.size < cached.size;
+	if (stored !== undefined && !fileShrunk) {
+		// Trust the sidecar, but guard against a REGRESSED sidecar (e.g. the
+		// async path persisted a lower seq, rolling the sidecar back below the
+		// file's true max). Take max with a full scan so a regressed sidecar
+		// cannot produce a duplicate sequence number (EL-1 regression guard).
+		// NOTE (ST-12): a full scan here is acceptable because all three append
+		// paths now allocate seqs via reserveSequence/reserveSequenceUnderLock
+		// (ST-5: re-read sidecar under lock + max with in-process counter);
+		// nextSequence is only consulted for seeding/test helpers, NOT on the
+		// production append path. ST-12's perf goal (avoid 4MB scan on first
+		// append) is therefore met by ST-5 at the reserveSequence layer.
+		const fileMax = scanSequence(eventsPath);
+		const safeSeq = Math.max(stored, fileMax);
+		sequenceCache.set(eventsPath, {
+			size: stat.size,
+			mtimeMs: stat.mtimeMs,
+			seq: safeSeq,
+			lastAccessMs: Date.now(),
+		});
+		return safeSeq + 1;
+	}
+	const current = scanSequence(eventsPath);
+	sequenceCache.set(eventsPath, {
+		size: stat.size,
+		mtimeMs: stat.mtimeMs,
+		seq: current,
+		lastAccessMs: Date.now(),
+	});
+	persistSequence(eventsPath, current);
+	return current + 1;
+}
+
+function persistSequence(eventsPath: string, seq: number): void {
+	try {
+		// P0-4: the .seq sidecar is disposable (event-reconstructor tolerates an
+		// inconsistent tail); best-effort avoids 2 fsyncs per event append.
+		atomicWriteFile(sequencePath(eventsPath), String(seq), { durability: "best-effort" });
+	} catch (error) {
+		logInternalError("event-log.persist-sequence-file", error, `eventsPath=${eventsPath}`);
+	}
+}
+
+// R16-B1 (Phase 3.6): THIRD lock namespace `${eventsPath}.seqlock` — a tiny
+// cross-process lock that serializes ONLY the .seq sidecar read-compute-write
+// in reserveSequenceUnderLock. Empirically justified by Round 17: 3000 events
+// across 2 processes on the same eventsPath produced 527 duplicate seq values
+// (75% duplicate events) because the sync family (.mkdirlock) and async family
+// (.alock) are DISJOINT lock namespaces that both trust the sidecar with no
+// mutual exclusion (read sidecar=N → both reserve N+1).
+//
+// Lock-ordering contract (Round 18 Part C): L1(run) → L2(event-log family:
+// .mkdirlock/.alock) → L3(.seqlock). The .seqlock is a PURE-SYNC, SHORT
+// critical section (sidecar read + counter update + best-effort persist —
+// ~2 atomic writes). NEVER acquire L1/L2 while holding L3.
+//
+// Do NOT naively merge .mkdirlock+.alock instead — that reintroduces the
+// v0.9.26 sleepSync-vs-async-timer deadlock (see the withEventLogLockAsync
+// docblock): the sync retry loop's sleepSync starves the async path's
+// event-loop-dependent acquire. The family split is intentional; .seqlock
+// closes the seq race WITHOUT coupling the two families' retry loops.
+//
+// Two acquire wrappers share ONE lock dir + pid file:
+//   - withSeqLock:      sync acquire (sleepSync backoff) — ALL families.
+//   - withSeqLockAsync:  thin alias of withSeqLock (see below).
+// Bounds are tighter than the family locks because the section is tiny:
+// timeout 2s / stale 1s / retry 5ms. NOTE: staleMs MUST be < timeoutMs — a
+// crashed holder leaves the lock dir behind, and the acquirer must get the
+// chance to stale-steal it BEFORE its own timeout throws (observed flake:
+// mailbox-api symlink test, killed scaffold holder → 2s spin → throw). The
+// 1s staleness is still ~1000x the sub-millisecond critical section; the only
+// theoretical over-run is a missing-.seq sidecar forcing scanSequence over a
+// multi-MB file, which is far below 1s at the 4MB rotation threshold.
+const SEQ_LOCK_TIMEOUT_MS = 2000;
+const SEQ_LOCK_STALE_MS = 1000;
+const SEQ_LOCK_RETRY_MS = 5;
+
+function seqLockPath(eventsPath: string): string {
+	return `${eventsPath}.seqlock`;
+}
+
+function reserveSequenceLocked(eventsPath: string, count: number): number {
+	let stored = readStoredSequence(eventsPath);
+	if (stored === undefined) {
+		stored = scanSequence(eventsPath);
+	}
+	const inProcess = seqCounters.get(eventsPath) ?? 0;
+	const last = Math.max(stored, inProcess);
+	const start = last + 1;
+	seqCounters.set(eventsPath, start + count - 1);
+	enforceSeqCountersCap();
+	// R16-B1: advance-on-reserve. The sidecar MUST be persisted INSIDE the
+	// .seqlock — persisting only after the append would leave the window where
+	// two processes in different family locks both read sidecar=N and both
+	// reserve N+1 (the exact Round-17-confirmed race). Inverting the old
+	// "persist only after successful append" ordering (see the sync :persist
+	// and async :persist comments) is strictly safer: a failed append after
+	// reservation yields a seq GAP, never a duplicate, and the
+	// event-reconstructor already tolerates a sidecar ahead of the data
+	// (lossless recovery ignores appends beyond the claimed seq — F3a).
+	persistSequence(eventsPath, start + count - 1);
+	return start;
+}
+
+function withSeqLock<T>(eventsPath: string, fn: () => T): T {
+	const lockDir = seqLockPath(eventsPath);
+	const pidFile = path.join(lockDir, "pid");
+	const start = Date.now();
+	let acquired = false;
+	while (!acquired) {
+		try {
+			fs.mkdirSync(lockDir);
+			try {
+				// P0-4: the lock pid file is disposable stale-lock state; best-effort.
+				atomicWriteFile(pidFile, String(process.pid), { durability: "best-effort" });
+			} catch {
+				/* best-effort */
+			}
+			acquired = true;
+		} catch {
+			// Stale detection: mtime-first (handles crash between mkdir and pidFile).
+			try {
+				if (Date.now() - fs.statSync(lockDir).mtimeMs > SEQ_LOCK_STALE_MS) {
+					fs.rmSync(lockDir, { recursive: true, force: true });
+					continue;
+				}
+			} catch {
+				/* dir vanished — let loop retry */
+			}
+			if (Date.now() - start > SEQ_LOCK_TIMEOUT_MS) {
+				throw errors.eventLogLockTimeout(eventsPath, SEQ_LOCK_TIMEOUT_MS);
+			}
+			sleepSync(SEQ_LOCK_RETRY_MS);
+		}
+	}
+	try {
+		return fn();
+	} finally {
+		// PID-guarded release: don't delete a stealer's dir if fn exceeded staleMs.
+		try {
+			if (fs.readFileSync(pidFile, "utf-8").trim() === String(process.pid)) {
+				fs.rmSync(lockDir, { recursive: true, force: true });
+			}
+		} catch {
+			/* lock stolen or already gone — do not touch */
+		}
+	}
+}
+
+async function withSeqLockAsync<T>(eventsPath: string, fn: () => T): Promise<T> {
+	// DELIBERATELY delegates to the SYNC acquire — this is NOT a v0.9.26
+	// repeat. The v0.9.26 deadlock was the async family AWAITING a lock whose
+	// in-process holder needed event-loop iterations (promise-chain family
+	// lock) while the sync path sleepSync-spinned. Here the ENTIRE
+	// acquire+body+release is one synchronous block with no internal awaits,
+	// so within one process (single JS thread) the lock can never be held
+	// across an await — in-process sync-vs-async contention is IMPOSSIBLE,
+	// and a spin only ever waits on ANOTHER PROCESS (sub-millisecond section,
+	// stale-steal at 1s). An earlier draft gave this wrapper its own
+	// `await sleep` backoff; that REINTRODUCED starvation: a sync spinner's
+	// sleepSync blocked the loop while the in-process async holder's
+	// `await`-based release could never run (mailbox-api 30s timeout flake).
+	return withSeqLock(eventsPath, fn);
+}
+
+/** Monotonic sidecar persist under the .seqlock (L2→L3). Used where a value
+ *  is persisted OUTSIDE reservation (e.g. batch lastSeq after the fact) so a
+ *  lower explicit seq can never REGRESS the sidecar below values another
+ *  process may have already reserved. Writes max(stored, inProcess, seq). */
+export function persistSequenceMonotonic(eventsPath: string, seq: number): void {
+	withSeqLock(eventsPath, () => {
+		const stored = readStoredSequence(eventsPath) ?? 0;
+		const inProcess = seqCounters.get(eventsPath) ?? 0;
+		const value = Math.max(stored, inProcess, seq);
+		if (value !== stored) persistSequence(eventsPath, value);
+	});
+}
+
+// B7: single in-process monotonic sequence counter per eventsPath. The three
+// append paths — sync appendEvent (withEventLogLockSync file lock), buffered
+// flush (asyncLocks promise chain), and direct appendEventAsync (asyncQueues
+// promise chain) — use DIFFERENT locks, so the old read-sidecar / compute /
+// persist-sidecar sequence logic in nextSequence() raced ACROSS paths and
+// produced duplicate sequence numbers (observed live: distinct events sharing
+// a seq; no data loss — only the counter collided). A single in-process counter
+// makes assignment atomic (JS is single-threaded); persistSequence() keeps the
+// sidecar durable for crash recovery across restarts.
+export const seqCounters = new Map<string, number>();
+// H6 (2026-08-10): FIFO cap — mirrors appendCounters (APPEND_COUNTER_MAX_ENTRIES = 256)
+// and agentEventSeqCache (cap at :434). Without this, a long-lived parent pi process
+// that observes many runs (dev sessions with hundreds of background runs over a week)
+// accumulates one entry per distinct eventsPath forever. Eviction is safe: the next
+// append re-seeds from the `.seq` sidecar via reserveSequenceUnderLock.
+const SEQ_COUNTERS_MAX_ENTRIES = 256;
+
+/** Atomically reserve the next sequence number for `eventsPath`.
+ *
+ *  ST-5 (v0.9.56): previously this seeded the in-process `seqCounters` counter
+ *  ONCE per process (reading the `.seq` sidecar a single time via
+ *  `nextSequence`) and then served every subsequent call purely from that
+ *  process-local counter. Two processes that both seeded before either had
+ *  persisted ended up sharing the same counter base -> duplicate sequence
+ *  numbers -> `sinceSeq` streaming readers silently dropped the second event.
+ *  The async path was already fixed via `reserveSequenceUnderLock` (which
+ *  re-reads the sidecar every call); the sync (`appendEvent`) and buffered
+ *  (`appendEventBatchInsideLock`) paths were NOT.
+ *
+ *  Now ALL three append paths share one body: re-read the authoritative `.seq`
+ *  sidecar on EVERY call and take `max(sidecar, inProcess)` so a counter that
+ *  lags behind a sidecar advanced by another process can never assign a
+ *  regressed (duplicate) seq. Every call site already holds a cross-process
+ *  file lock (`withEventLogLockSync` for sync/buffered, `withEventLogLockAsync`
+ *  for async), so the sidecar re-read is race-free within each lock class.
+ *
+ *  R16-B1/R17 CORRECTION (Phase 3.6): the claim above — "race-free within
+ *  each lock class" — is TRUE but INSUFFICIENT: the sync (.mkdirlock) and
+ *  async (.alock) families are DISJOINT cross-process namespaces, so a sync
+ *  appender in one process and an async appender in another still both read
+ *  sidecar=N and both reserve N+1. Round 17 proved this empirically (527 dup
+ *  seq / 75% dup events over 3000 events across 2 processes). reserveSequence
+ *  UnderLock now additionally wraps the sidecar read-compute-write in the
+ *  shared `.seqlock` (L3) and persists ADVANCE-ON-RESERVE inside it, so no
+ *  two processes can ever reserve the same seq regardless of lock family. */
+export function reserveSequence(eventsPath: string, count = 1): number {
+	return reserveSequenceUnderLock(eventsPath, count);
+}
+
+/** Keep the in-process counter monotonic w.r.t. an explicitly-provided seq
+ *  (e.g. baseMetadata.seq) so a later auto-assigned seq never collides with it. */
+export function advanceSequenceCounter(eventsPath: string, seq: number): void {
+	const last = seqCounters.get(eventsPath);
+	if (last === undefined || seq > last) {
+		seqCounters.set(eventsPath, seq);
+		enforceSeqCountersCap();
+	}
+}
+
+/** H6: FIFO eviction when the seqCounters map exceeds its bounded size. */
+function enforceSeqCountersCap(): void {
+	if (seqCounters.size > SEQ_COUNTERS_MAX_ENTRIES) {
+		const oldest = seqCounters.keys().next().value;
+		if (oldest !== undefined) seqCounters.delete(oldest);
+	}
+}
+
+/** C-01: Reserve sequence INSIDE the cross-process lock. Reads the authoritative
+ *  sidecar (.seq file) for the last seq persisted by ANY process, ensuring
+ *  cross-process uniqueness. Falls back to scanSequence if no sidecar exists.
+ *  The in-process seqCounters is kept monotonic via Math.max for defensive
+ *  consistency with any in-process sequencing that hasn't been persisted yet.
+ *  R16-B1 (Phase 3.6): the body now runs under the shared `.seqlock` (L3,
+ *  acquired L2→L3) and persists the reserved end value inside it
+ *  (advance-on-reserve) — see reserveSequenceLocked for the rationale.
+ *  `count` lets the buffered batch reserve a contiguous range in one acquire.
+ *  Callers on the async family use reserveSequenceUnderLockAsync (same lock
+ *  dir, async acquire backoff — never sleepSync on the event loop). */
+function reserveSequenceUnderLock(eventsPath: string, count = 1): number {
+	return withSeqLock(eventsPath, () => reserveSequenceLocked(eventsPath, count));
+}
+
+export async function reserveSequenceUnderLockAsync(eventsPath: string, count = 1): Promise<number> {
+	return withSeqLockAsync(eventsPath, () => reserveSequenceLocked(eventsPath, count));
+}

package/src/state/event-log/worker-atomic-writer.ts

@@ -25,6 +25,7 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 import { Worker } from "node:worker_threads";
+import { getCrewEnv } from "../../config/env-vars.ts";
 
 const require = createRequire(import.meta.url);
 
@@ -163,7 +164,7 @@ function dispatch(kind: "write" | "mkdir" | "append", payload: Record<string, un
 
 /** Whether the worker writer is enabled (env var opt-in). */
 export function isWorkerAtomicWriterEnabled(): boolean {
-	return process.env.PI_CREW_WORKER_ATOMIC_WRITER === "1" || process.env.PI_TEAMS_WORKER_ATOMIC_WRITER === "1";
+	return getCrewEnv("PI_CREW_WORKER_ATOMIC_WRITER") === "1" || getCrewEnv("PI_TEAMS_WORKER_ATOMIC_WRITER") === "1";
 }
 
 /** Atomic-write a file via the worker thread. Sync fs ops inside worker. */

package/src/state/stores/active-run-registry.ts

@@ -2,6 +2,7 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { DEFAULT_CACHE, DEFAULT_PATHS } from "../../config/defaults.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
 import { userCrewRoot } from "../../utils/paths.ts";
 import { isSafePathId } from "../../utils/safe-paths.ts";
 import { sharedScanCache } from "../../utils/scan-cache.ts";
@@ -68,7 +69,7 @@ function withRegistryLock<T>(fn: () => T): T {
 	const deadline = Date.now() + 10_000;
 	while (true) {
 		try {
-			const fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o644);
+			const fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
 			try {
 				fs.writeSync(
 					fd,
@@ -371,7 +372,7 @@ export function registerActiveRun(manifest: TeamRunManifest): void {
 
 export function unregisterActiveRun(runId: string): void {
 	if (!isSafePathId(runId)) {
-		console.warn(`unregisterActiveRun: invalid runId ignored: ${runId}`);
+		logInternalError("active-run-registry", new Error(`unregisterActiveRun: invalid runId ignored: ${runId}`), undefined, "warn");
 		return;
 	}
 	withRegistryLock(() => {

package/src/state/stores/manifest-io.ts

@@ -0,0 +1,237 @@
+/**
+ * Manifest/tasks load paths with corruption recovery and quarantine
+ * (ST-4, ST-9, STATE-3). Extracted verbatim from state-store.ts (Phase 2.5
+ * god-file decomposition — pure code motion, no behavior change).
+ *
+ * Import direction is one-way: state-store.ts imports from this module;
+ * this module does NOT import values from state-store.ts.
+ */
+import * as fs from "node:fs";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { atomicWriteJson, atomicWriteJsonAsync } from "../atomic-write.ts";
+import { isTeamTaskStatus } from "../contracts.ts";
+import { reconstructTasksFromEvents } from "../event-log/event-reconstructor.ts";
+import type { TeamRunManifest, TeamTaskState } from "../types.ts";
+import { CURRENT_TASKS_SCHEMA_VERSION } from "../types.ts";
+
+/**
+ * ST-4: Rename a corrupt file to a quarantine path (`.corrupt-<ts>`) so it is
+ * preserved for debugging but no longer read as the primary source of truth.
+ */
+/** @internal — Phase 2.5 split: also used by state-store.ts (loadRunManifestById loaders). */
+export function quarantineCorruptFile(filePath: string): void {
+	try {
+		fs.renameSync(filePath, `${filePath}.corrupt-${Date.now()}`);
+	} catch {
+		// Best-effort — if rename fails (file already gone, permission, etc.),
+		// we still proceed with reconstruction from the event log.
+	}
+}
+
+/**
+ * ST-4: Convert event-reconstructor output into TeamTaskState[].
+ * Reconstructed tasks carry lifecycle data (id, status, timing) from the
+ * event log; auxiliary fields (role, agent, title) are filled with defaults
+ * since they are not present in lifecycle events.
+ */
+function reconstructTasksFromEventLog(eventsPath: string, runId: string): TeamTaskState[] {
+	try {
+		const result = reconstructTasksFromEvents(eventsPath);
+		const tasks: TeamTaskState[] = [];
+		for (const [, rt] of result.tasks) {
+			tasks.push({
+				id: rt.id,
+				runId,
+				role: "unknown",
+				agent: "unknown",
+				title: "reconstructed from events",
+				status: isTeamTaskStatus(rt.status) ? rt.status : "queued",
+				dependsOn: [],
+				cwd: "",
+				startedAt: rt.startedAt,
+				finishedAt: rt.finishedAt,
+				error: rt.error,
+				segment: rt.segment,
+				diagnostics: rt.diagnostics,
+				metrics: rt.metrics,
+			});
+		}
+		return tasks;
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * ST-4: Load tasks.json with corruption recovery (sync path).
+ *
+ * Distinguishes:
+ * - ENOENT / ENOTDIR → legitimate empty → [] (NOT quarantined).
+ * - SyntaxError (parse failure) → corrupt → quarantine `.corrupt-<ts>` AND
+ *   reconstruct from events.jsonl. If reconstruction yields tasks, persist
+ *   them so subsequent loads see a valid file.
+ * - Non-array JSON (e.g. `{}`) → corrupt → same as SyntaxError.
+ * - Valid array → return as-is.
+ */
+
+/**
+ * ST-9: Extract the task array from a tasks.json payload.
+ *
+ * Accepts both the v0 legacy bare-array format and the v1+ envelope
+ * `{ schemaVersion, tasks }`. Returns [] for unrecognized shapes.
+ */
+/** @internal — Phase 2.5 split: also used by state-store.ts (shouldPersistTasks). */
+export function extractTaskArray(raw: unknown): TeamTaskState[] {
+	if (Array.isArray(raw)) return raw as TeamTaskState[];
+	if (raw !== null && typeof raw === "object" && "tasks" in raw) {
+		const envelope = raw as { tasks?: unknown };
+		if (Array.isArray(envelope.tasks)) return envelope.tasks as TeamTaskState[];
+	}
+	return [];
+}
+
+/**
+ * ST-9: Whether `parsed` is a recognizable tasks.json shape (v0 bare array
+ * or v1+ envelope). Used to distinguish legitimate formats from corruption.
+ */
+function isRecognizableTasksPayload(parsed: unknown): boolean {
+	if (Array.isArray(parsed)) return true;
+	if (parsed !== null && typeof parsed === "object" && "tasks" in parsed) {
+		return Array.isArray((parsed as { tasks?: unknown }).tasks);
+	}
+	return false;
+}
+
+/**
+ * ST-9: Version-check + migration hook for tasks.json.
+ *
+ * tasks.json has two on-disk shapes:
+ * - v0 (current): bare JSON array `TeamTaskState[]` — what saveRunTasks*
+ *   write today (backward-compatible; no schemaVersion envelope).
+ * - v1+ (future): envelope `{ schemaVersion: number, tasks: TeamTaskState[] }`
+ *   — read-supported defensively for a future write-side switch.
+ *
+ * This detects the shape and returns the task array. v0 needs NO migration
+ * (it IS the current write format). For v1+ envelopes, a schemaVersion
+ * mismatch warns (mirroring the manifest check). Future breaking changes
+ * add real migration logic here.
+ */
+function migrateTasksFile(parsed: unknown, runId: string): TeamTaskState[] {
+	// v0 current: bare array (no schemaVersion envelope) — what writers produce.
+	if (Array.isArray(parsed)) {
+		// v0 bare array is the CURRENT write format (saveRunTasks* write the
+		// array directly, by design — backward compat). Nothing to migrate:
+		// return as-is. (v1+ envelope read-support below is defensive, for a
+		// future write-side switch.) Do NOT warn here — it would fire for 100%
+		// of runs on every load and flood the UI on startup.
+		return parsed as TeamTaskState[];
+	}
+	// v1+ envelope: { schemaVersion, tasks }.
+	if (parsed !== null && typeof parsed === "object" && "tasks" in parsed) {
+		const envelope = parsed as { schemaVersion?: unknown; tasks?: unknown };
+		const detected = typeof envelope.schemaVersion === "number" ? envelope.schemaVersion : 0;
+		if (detected !== CURRENT_TASKS_SCHEMA_VERSION) {
+			logInternalError(
+				"state-store",
+				new Error(
+					`tasks.json schemaVersion mismatch: expected ${CURRENT_TASKS_SCHEMA_VERSION}, got ${detected}. Run ${runId} may be incompatible.`,
+				),
+				undefined,
+				"warn",
+			);
+		}
+	}
+	return extractTaskArray(parsed);
+}
+export function loadTasksWithRecovery(tasksPath: string, eventsPath: string, runId: string): TeamTaskState[] {
+	let content: string;
+	try {
+		content = fs.readFileSync(tasksPath, "utf-8");
+	} catch {
+		// ENOENT / ENOTDIR / other read errors → empty (retry loop handles
+		// transient instability; ENOENT is a legitimate empty run).
+		return [];
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(content);
+	} catch {
+		// SyntaxError — corrupt file.
+		quarantineCorruptFile(tasksPath);
+		const reconstructed = reconstructTasksFromEventLog(eventsPath, runId);
+		if (reconstructed.length > 0) atomicWriteJson(tasksPath, reconstructed, { compact: true });
+		return reconstructed;
+	}
+	if (!isRecognizableTasksPayload(parsed)) {
+		// Neither v0 bare array nor v1+ envelope (e.g. `{}`) — corrupt.
+		quarantineCorruptFile(tasksPath);
+		const reconstructed = reconstructTasksFromEventLog(eventsPath, runId);
+		if (reconstructed.length > 0) atomicWriteJson(tasksPath, reconstructed, { compact: true });
+		return reconstructed;
+	}
+	return migrateTasksFile(parsed, runId);
+}
+
+/**
+ * STATE-3: Load manifest.json with corruption quarantine (sync). Distinguishes:
+ * - ENOENT / read error → undefined (legitimate missing run — NOT quarantined).
+ * - SyntaxError (unparseable) → CORRUPT → quarantine `.corrupt-<ts>` + log + undefined.
+ *   Manifest CANNOT be reconstructed from events.jsonl (run.created only carries
+ *   {team, workflow}), so quarantine + visible log is the recovery — do NOT attempt
+ *   reconstruction (unlike loadTasksWithRecovery). This prevents a corrupt manifest
+ *   from silently making a run invisible (STATE-3).
+ */
+export function loadManifestWithRecovery(manifestPath: string, runId: string): TeamRunManifest | undefined {
+	let content: string;
+	try {
+		content = fs.readFileSync(manifestPath, "utf-8");
+	} catch {
+		// ENOENT / ENOTDIR / other read error → legitimate missing run.
+		return undefined;
+	}
+	try {
+		return JSON.parse(content) as TeamRunManifest;
+	} catch {
+		// SyntaxError → corrupt manifest. Quarantine (preserve for diagnosis) + log,
+		// then treat as missing. Do NOT reconstruct (infeasible from events).
+		quarantineCorruptFile(manifestPath);
+		logInternalError(
+			"state-store",
+			new Error(
+				`STATE-3: manifest.json for run ${runId} is corrupt (unparseable) — quarantined to ${manifestPath}.corrupt-*. Run is now treated as missing. Preserve the .corrupt-* file for diagnosis.`,
+			),
+			undefined,
+			"error",
+		);
+		return undefined;
+	}
+}
+
+/**
+ * ST-4: async twin of {@link loadTasksWithRecovery}.
+ */
+/** @internal — Phase 2.5 split: async twin used by state-store.ts (loadRunManifestByIdAsync). */
+export async function loadTasksWithRecoveryAsync(tasksPath: string, eventsPath: string, runId: string): Promise<TeamTaskState[]> {
+	let content: string;
+	try {
+		content = await fs.promises.readFile(tasksPath, "utf-8");
+	} catch {
+		return [];
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(content);
+	} catch {
+		quarantineCorruptFile(tasksPath);
+		const reconstructed = reconstructTasksFromEventLog(eventsPath, runId);
+		if (reconstructed.length > 0) await atomicWriteJsonAsync(tasksPath, reconstructed, { compact: true });
+		return reconstructed;
+	}
+	if (!isRecognizableTasksPayload(parsed)) {
+		quarantineCorruptFile(tasksPath);
+		const reconstructed = reconstructTasksFromEventLog(eventsPath, runId);
+		if (reconstructed.length > 0) await atomicWriteJsonAsync(tasksPath, reconstructed, { compact: true });
+		return reconstructed;
+	}
+	return migrateTasksFile(parsed, runId);
+}