pi-crew 0.9.56 → 0.9.57

package/src/state/{jsonl-writer.ts → event-log/jsonl-writer.ts}

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
-import { logInternalError } from "../utils/internal-error.ts";
-import { redactJsonLine } from "../utils/redaction.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { redactJsonLine } from "../../utils/redaction.ts";
 
 export interface DrainableSource {
 	pause(): void;
@@ -35,8 +35,12 @@ export interface JsonlWriter {
 export function createJsonlWriter(filePath: string | undefined, source: DrainableSource, deps: JsonlWriterDeps = {}): JsonlWriter {
 	if (!filePath) {
 		return {
-			writeLine() {},
-			async close() {},
+			writeLine() {
+				/* no-op: null writer */
+			},
+			async close() {
+				/* no-op: null writer */
+			},
 		};
 	}
 
@@ -46,8 +50,12 @@ export function createJsonlWriter(filePath: string | undefined, source: Drainabl
 		stream = createWriteStream(filePath);
 	} catch {
 		return {
-			writeLine() {},
-			async close() {},
+			writeLine() {
+				/* no-op: stream creation failed */
+			},
+			async close() {
+				/* no-op: stream creation failed */
+			},
 		};
 	}
 

package/src/state/hook-instinct-bridge.ts

@@ -6,13 +6,13 @@
 import { crewHooks } from "../runtime/crew-hooks.ts";
 
 // Lazy-initialized store and paths
-let storeInstance: import("./instinct-store.js").InstinctStore | null = null;
+let storeInstance: import("./stores/instinct-store.js").InstinctStore | null = null;
 let pathsInstance: typeof import("../utils/paths.js") | null = null;
 
 async function getStore() {
 	if (!storeInstance) {
 		// LAZY: defer dynamic import of ./instinct-store.js to its call site.
-		const { InstinctStore } = await import("./instinct-store.js");
+		const { InstinctStore } = await import("./stores/instinct-store.js");
 		// LAZY: defer dynamic import of ../utils/paths.js to its call site.
 		const paths = await import("../utils/paths.js");
 		storeInstance = new InstinctStore(paths.projectCrewRoot(process.cwd()));

package/src/state/{active-run-registry.ts → stores/active-run-registry.ts}

@@ -1,13 +1,13 @@
 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 { userCrewRoot } from "../utils/paths.ts";
-import { isSafePathId } from "../utils/safe-paths.ts";
-import { sharedScanCache } from "../utils/scan-cache.ts";
-import { sleepSync } from "../utils/sleep.ts";
-import { atomicWriteJson, isSymlinkSafePath, renameWithRetry } from "./atomic-write.ts";
-import type { TeamRunManifest } from "./types.ts";
+import { DEFAULT_CACHE, DEFAULT_PATHS } from "../../config/defaults.ts";
+import { userCrewRoot } from "../../utils/paths.ts";
+import { isSafePathId } from "../../utils/safe-paths.ts";
+import { sharedScanCache } from "../../utils/scan-cache.ts";
+import { sleepSync } from "../../utils/sleep.ts";
+import { atomicWriteJson, isSymlinkSafePath, renameWithRetry } from "../atomic-write.ts";
+import type { TeamRunManifest } from "../types.ts";
 
 /** Magic bytes prefix for binary registry to prevent deserialization of hostile files. */
 const BINARY_MAGIC = Buffer.from("PICREW2BIN", "utf-8");

package/src/state/{artifact-store.ts → stores/artifact-store.ts}

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { redactSecretString, redactSecrets } from "../utils/redaction.ts";
-import { resolveRealContainedPath } from "../utils/safe-paths.ts";
-import { atomicWriteFile } from "./atomic-write.ts";
-import type { ArtifactDescriptor } from "./types.ts";
+import { redactSecretString, redactSecrets } from "../../utils/redaction.ts";
+import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
+import { atomicWriteFile } from "../atomic-write.ts";
+import type { ArtifactDescriptor } from "../types.ts";
 
 function hashContent(content: string): string {
 	return createHash("sha256").update(content).digest("hex");
@@ -101,6 +101,64 @@ export function cleanupOldArtifacts(artifactsRoot: string, options: ArtifactClea
 	if (!didCleanup) writeCleanupMarker(artifactsRoot, markerFile);
 }
 
+/**
+ * ST-10: Default TTL for "temporary" retention artifacts (1 hour).
+ * Temporary artifacts (progress, notepad) are short-lived and should not
+ * accumulate. One hour balances cleanup aggressiveness with the possibility
+ * that a long-running task writes periodic progress updates.
+ */
+export const TEMPORARY_RETENTION_TTL_MS = 60 * 60 * 1000;
+
+/**
+ * ST-10: Check whether an artifact descriptor indicates the file should be
+ * pruned (expired).
+ *
+ * Enforces:
+ * - `expiresAt`: if set and now ≥ expiresAt → expired.
+ * - `retention: "temporary"`: if createdAt age ≥ temporaryTtlMs → expired.
+ *   ("run" and "project" retentions are handled by run-level prune and the
+ *   age-based {@link cleanupOldArtifacts}, not by this per-descriptor check.)
+ */
+export function isArtifactExpired(desc: ArtifactDescriptor, nowMs: number, temporaryTtlMs: number = TEMPORARY_RETENTION_TTL_MS): boolean {
+	// Explicit expiresAt takes precedence.
+	if (desc.expiresAt) {
+		const expiryMs = Date.parse(desc.expiresAt);
+		if (Number.isFinite(expiryMs) && nowMs >= expiryMs) return true;
+	}
+	// "temporary" retention has a short TTL.
+	if (desc.retention === "temporary" && desc.createdAt) {
+		const createdMs = Date.parse(desc.createdAt);
+		if (Number.isFinite(createdMs) && nowMs - createdMs >= temporaryTtlMs) return true;
+	}
+	return false;
+}
+
+/**
+ * ST-10: Prune expired artifacts by enforcing ArtifactDescriptor.retention/expiresAt.
+ *
+ * Deletes artifact files whose descriptor indicates expiry (expiresAt passed
+ * or temporary-retention TTL exceeded). Returns the count of files deleted.
+ *
+ * Unlike {@link cleanupOldArtifacts} (which is filesystem age-based on raw
+ * files), this operates on artifact *metadata* from the manifest's `artifacts[]`
+ * and deletes specific expired files via their descriptor `path`.
+ */
+export function pruneExpiredArtifacts(descriptors: ArtifactDescriptor[], options?: { now?: number; temporaryTtlMs?: number }): number {
+	const nowMs = options?.now ?? Date.now();
+	const temporaryTtlMs = options?.temporaryTtlMs ?? TEMPORARY_RETENTION_TTL_MS;
+	let deleted = 0;
+	for (const desc of descriptors) {
+		if (!isArtifactExpired(desc, nowMs, temporaryTtlMs)) continue;
+		try {
+			fs.unlinkSync(desc.path);
+			deleted++;
+		} catch {
+			// Best-effort: file may already be removed or path may be stale.
+		}
+	}
+	return deleted;
+}
+
 function resolveInside(baseDir: string, relativePath: string): string {
 	// Check if baseDir is a symlink on every call to prevent symlink attacks
 	try {

package/src/state/{blob-store.ts → stores/blob-store.ts}

@@ -1,9 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { resolveRealContainedPath } from "../utils/safe-paths.ts";
-import { atomicWriteFile, renameWithRetry } from "./atomic-write.ts";
-import { withFileLockSync } from "./locks.ts";
+import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
+import { atomicWriteFile, renameWithRetry } from "../atomic-write.ts";
+import { withFileLockSync } from "../coordination/locks.ts";
 
 const SHA256_HEX = /^[a-f0-9]{64}$/i;
 

package/src/state/{health-store.ts → stores/health-store.ts}

@@ -1,8 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ManifestSummary } from "../runtime/task-health.ts";
-import { computeRunHealth } from "../runtime/task-health.ts";
-import { atomicWriteFile } from "./atomic-write.ts";
+import type { ManifestSummary } from "../../runtime/task-health.ts";
+import { computeRunHealth } from "../../runtime/task-health.ts";
+import { atomicWriteFile } from "../atomic-write.ts";
 
 // Relative to the crew root (`<cwd>/.crew`). BUG A fix (pts/2 hang
 // investigation 2026-06-16): this was `.crew/state/health`, which double-joined

package/src/state/{instinct-store.ts → stores/instinct-store.ts}

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { assertSafePathId } from "../utils/safe-paths.ts";
-import { atomicWriteFile } from "./atomic-write.ts";
+import { assertSafePathId } from "../../utils/safe-paths.ts";
+import { atomicWriteFile } from "../atomic-write.ts";
 
 /**
  * Represents a learned instinct that guides agent behavior.
@@ -272,4 +272,4 @@ export class InstinctStore {
 export {
 	getGlobalStorageDir,
 	getProjectStorageDir,
-} from "../utils/project-detector.ts";
+} from "../../utils/project-detector.ts";

package/src/state/{observation-store.ts → stores/observation-store.ts}

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
-import { logInternalError } from "../utils/internal-error.ts";
-import { atomicWriteJson } from "./atomic-write.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { atomicWriteJson } from "../atomic-write.ts";
 
 // ── Types ────────────────────────────────────────────────────────────────
 

package/src/state/{run-cache.ts → stores/run-cache.ts}

@@ -1,10 +1,10 @@
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { projectCrewRoot } from "../utils/paths.ts";
-import { atomicWriteJson } from "./atomic-write.ts";
-import { withFileLockSync } from "./locks.ts";
-import type { TeamTaskState } from "./types.ts";
+import { projectCrewRoot } from "../../utils/paths.ts";
+import { atomicWriteJson } from "../atomic-write.ts";
+import { withFileLockSync } from "../coordination/locks.ts";
+import type { TeamTaskState } from "../types.ts";
 
 const DEFAULT_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 

package/src/state/{run-graph.ts → stores/run-graph.ts}

@@ -1,9 +1,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { projectCrewRoot } from "../utils/paths.ts";
-import { assertSafePathId } from "../utils/safe-paths.ts";
-import { atomicWriteFile } from "./atomic-write.ts";
-import type { TeamRunManifest, TeamTaskState } from "./types.ts";
+import { projectCrewRoot } from "../../utils/paths.ts";
+import { assertSafePathId } from "../../utils/safe-paths.ts";
+import { atomicWriteFile } from "../atomic-write.ts";
+import type { TeamRunManifest, TeamTaskState } from "../types.ts";
 
 export interface RunGraphNode {
 	id: string;

package/src/state/{run-metrics.ts → stores/run-metrics.ts}

@@ -1,8 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { projectCrewRoot } from "../utils/paths.ts";
-import { assertSafePathId } from "../utils/safe-paths.ts";
-import { atomicWriteJson, readJsonFile } from "./atomic-write.ts";
+import { projectCrewRoot } from "../../utils/paths.ts";
+import { assertSafePathId } from "../../utils/safe-paths.ts";
+import { atomicWriteJson, readJsonFile } from "../atomic-write.ts";
 import { loadRunManifestById } from "./state-store.ts";
 
 /**

package/src/state/{state-store.ts → stores/state-store.ts}

@@ -1,22 +1,29 @@
 import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
-import { DEFAULT_CACHE, DEFAULT_PATHS } from "../config/defaults.ts";
-import { errors } from "../errors.ts";
-import type { TeamConfig } from "../teams/team-config.ts";
-import { createRunId, createTaskId } from "../utils/ids.ts";
-import { logInternalError } from "../utils/internal-error.ts";
-import { findRepoRoot, projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
-import { assertSafePathId, resolveContainedRelativePath, resolveRealContainedPath } from "../utils/safe-paths.ts";
-import { toPiSessionId } from "../utils/session-utils.ts";
-import type { WorkflowConfig } from "../workflows/workflow-config.ts";
+import { DEFAULT_CACHE, DEFAULT_PATHS } from "../../config/defaults.ts";
+import { errors } from "../../errors.ts";
+import type { TeamConfig } from "../../teams/team-config.ts";
+import { createRunId, createTaskId } from "../../utils/ids.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { findRepoRoot, projectCrewRoot, userCrewRoot } from "../../utils/paths.ts";
+import { assertSafePathId, resolveContainedRelativePath, resolveRealContainedPath } from "../../utils/safe-paths.ts";
+import { toPiSessionId } from "../../utils/session-utils.ts";
+import type { WorkflowConfig } from "../../workflows/workflow-config.ts";
+import {
+	atomicWriteJson,
+	atomicWriteJsonAsync,
+	atomicWriteJsonCoalesced,
+	flushPendingAtomicWrites,
+	readJsonFile,
+} from "../atomic-write.ts";
+import { canTransitionRunStatus, isTeamTaskStatus } from "../contracts.ts";
+import { withRunLock, withRunLockSync } from "../coordination/locks.ts";
+import { appendEvent } from "../event-log/event-log.ts";
+import { reconstructTasksFromEvents } from "../event-log/event-reconstructor.ts";
+import type { TeamRunManifest, TeamTaskState } from "../types.ts";
+import { CURRENT_SCHEMA_VERSION, CURRENT_TASKS_SCHEMA_VERSION } from "../types.ts";
 import { unregisterActiveRun } from "./active-run-registry.ts";
-import { atomicWriteJson, atomicWriteJsonAsync, atomicWriteJsonCoalesced, flushPendingAtomicWrites, readJsonFile } from "./atomic-write.ts";
-import { canTransitionRunStatus } from "./contracts.ts";
-import { appendEvent } from "./event-log.ts";
-import { withRunLock, withRunLockSync } from "./locks.ts";
-import type { TeamRunManifest, TeamTaskState } from "./types.ts";
-import { CURRENT_SCHEMA_VERSION } from "./types.ts";
 
 /**
  * stat() the manifest with a brief retry on Windows for the AV-scan window.
@@ -424,7 +431,32 @@ export async function saveRunManifestAsync(manifest: TeamRunManifest): Promise<v
 	});
 }
 
+/**
+ * ST-4: Defense-in-depth guard — refuse to persist an empty tasks array over
+ * a previously non-empty tasks file. Prevents the cascade where a corrupt
+ * tasks.json (→ [] on load via readJsonFile catching SyntaxError) is then
+ * persisted as [], permanently destroying the data. If the on-disk file has
+ * tasks and the incoming array is empty, we log a warning and refuse.
+ *
+ * @returns true if the write should proceed, false if it was refused.
+ */
+function shouldPersistTasks(manifest: TeamRunManifest, tasks: TeamTaskState[]): boolean {
+	if (tasks.length > 0) return true;
+	const existing = extractTaskArray(readJsonFile<unknown>(manifest.tasksPath));
+	if (existing.length > 0) {
+		console.warn(
+			`[state-store] refusing to persist empty tasks over ${existing.length} existing task(s) — possible corrupt-load cascade (runId=${manifest.runId})`,
+		);
+		return false;
+	}
+	return true;
+}
+
 export function saveRunTasks(manifest: TeamRunManifest, tasks: TeamTaskState[]): void {
+	// ST-4: refuse to persist [] over a previously-non-empty tasks file.
+	// Prevents the cascade where a corrupt tasks.json (→ [] on load) is then
+	// persisted as [], permanently destroying the data.
+	if (!shouldPersistTasks(manifest, tasks)) return;
 	// FIX: Invalidate cache BEFORE atomic write to prevent stale cache serving.
 	invalidateRunCache(manifest.stateRoot);
 
@@ -501,6 +533,8 @@ export function saveRunTasks(manifest: TeamRunManifest, tasks: TeamTaskState[]):
  */
 /** @internal */
 export function saveRunTasksCoalesced(manifest: TeamRunManifest, tasks: TeamTaskState[], skipCoalesce: boolean = false): void {
+	// ST-4: refuse to persist [] over a previously-non-empty tasks file.
+	if (!shouldPersistTasks(manifest, tasks)) return;
 	// FIX: Invalidate cache BEFORE atomic write to prevent stale cache serving.
 	invalidateRunCache(manifest.stateRoot);
 	try {
@@ -512,6 +546,8 @@ export function saveRunTasksCoalesced(manifest: TeamRunManifest, tasks: TeamTask
 }
 
 export async function saveRunTasksAsync(manifest: TeamRunManifest, tasks: TeamTaskState[]): Promise<void> {
+	// ST-4: refuse to persist [] over a previously-non-empty tasks file.
+	if (!shouldPersistTasks(manifest, tasks)) return;
 	// FIX: Invalidate cache BEFORE atomic write to prevent stale cache serving.
 	invalidateRunCache(manifest.stateRoot);
 	try {
@@ -733,6 +769,185 @@ async function readJsonFileAsync<T>(filePath: string): Promise<T | undefined> {
 	}
 }
 
+/**
+ * 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.
+ */
+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.
+ */
+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) {
+			console.warn(
+				`[state-store] tasks.json schemaVersion mismatch: expected ${CURRENT_TASKS_SCHEMA_VERSION}, got ${detected}. Run ${runId} may be incompatible.`,
+			);
+		}
+	}
+	return extractTaskArray(parsed);
+}
+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);
+		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);
+		return reconstructed;
+	}
+	return migrateTasksFile(parsed, runId);
+}
+
+/**
+ * ST-4: async twin of {@link loadTasksWithRecovery}.
+ */
+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);
+		return reconstructed;
+	}
+	if (!isRecognizableTasksPayload(parsed)) {
+		quarantineCorruptFile(tasksPath);
+		const reconstructed = reconstructTasksFromEventLog(eventsPath, runId);
+		if (reconstructed.length > 0) await atomicWriteJsonAsync(tasksPath, reconstructed);
+		return reconstructed;
+	}
+	return migrateTasksFile(parsed, runId);
+}
+
 /**
  * Load a run manifest and its tasks by runId.
  * WARNING: This function provides best-effort consistency only. The sentinel-based
@@ -813,7 +1028,7 @@ export function loadRunManifestById(cwd: string, runId: string): { manifest: Tea
 		const freshStat = fs.statSync(manifestPath);
 		manifest = readJsonFile<TeamRunManifest>(manifestPath);
 		const freshTasksStat = fs.existsSync(tasksPath) ? fs.statSync(tasksPath) : undefined;
-		tasks = readJsonFile<TeamTaskState[]>(tasksPath) ?? [];
+		tasks = loadTasksWithRecovery(tasksPath, manifest?.eventsPath ?? path.join(stateRoot, "events.jsonl"), manifest?.runId ?? runId);
 		// If size/mtime didn't change between stat and read, we're consistent.
 		if (
 			freshStat.mtimeMs === manifestStat.mtimeMs &&
@@ -933,7 +1148,11 @@ export async function loadRunManifestByIdAsync(
 		const freshStat = await fs.promises.stat(manifestPath);
 		manifest = await readJsonFileAsync<TeamRunManifest>(manifestPath);
 		const freshTasksStat = await fs.promises.stat(tasksPath).catch(() => undefined);
-		tasks = (await readJsonFileAsync<TeamTaskState[]>(tasksPath)) ?? [];
+		tasks = await loadTasksWithRecoveryAsync(
+			tasksPath,
+			manifest?.eventsPath ?? path.join(stateRoot, "events.jsonl"),
+			manifest?.runId ?? runId,
+		);
 		// If size/mtime didn't change between stat and read, we're consistent.
 		if (
 			freshStat.mtimeMs === manifestStat.mtimeMs &&

package/src/state/types.ts

@@ -1,9 +1,9 @@
-import type { CrashClass } from "../runtime/crash-classification.ts";
 import type { CrewAgentProgress } from "../runtime/crew-agent-runtime.ts";
-import type { WorkerHeartbeatState } from "../runtime/worker-heartbeat.ts";
+import type { WorkerHeartbeatState } from "../runtime/heartbeat/worker-heartbeat.ts";
+import type { CrashClass } from "../runtime/recovery/crash-classification.ts";
 import type { TeamRunStatus, TeamTaskStatus } from "./contracts.ts";
+import type { TaskClaimState } from "./coordination/task-claims.ts";
 import type { CoherenceMark, RolloutEntry } from "./decision-ledger.ts";
-import type { TaskClaimState } from "./task-claims.ts";
 
 export type { TeamRunStatus, TeamTaskStatus } from "./contracts.ts";
 export type { CoherenceMark, CrewAgentProgress, RolloutEntry };
@@ -183,6 +183,30 @@ export interface CrewAttentionEventData {
  */
 export const CURRENT_SCHEMA_VERSION = 1 as const;
 
+/**
+ * ST-9: schemaVersion sentinel for tasks.json (and future goal-state/mailbox
+ * files). Mirrors {@link CURRENT_SCHEMA_VERSION} for the manifest.
+ *
+ * tasks.json has two on-disk shapes:
+ * - v0 (legacy): bare JSON array `TeamTaskState[]` — no schemaVersion.
+ * - v1+ (current): envelope `{ schemaVersion, tasks }` — see {@link TasksFileData}.
+ *
+ * The reader detects the shape, warns on version mismatch, and applies
+ * migration logic in state-store.ts (the structured migration hook).
+ */
+export const CURRENT_TASKS_SCHEMA_VERSION = 1 as const;
+
+/**
+ * ST-9: Versioned envelope for tasks.json on disk.
+ * Writers produce this shape; readers accept it OR the legacy v0 bare array.
+ * `TeamTaskState` is defined later in this module but interface declarations
+ * are type-hoisted so the forward reference is valid.
+ */
+export interface TasksFileData {
+	schemaVersion: typeof CURRENT_TASKS_SCHEMA_VERSION;
+	tasks: TeamTaskState[];
+}
+
 export interface TeamRunManifest {
 	schemaVersion: typeof CURRENT_SCHEMA_VERSION;
 	runId: string;

package/src/ui/component.ts

@@ -0,0 +1,55 @@
+/**
+ * PR-G3 (UI-3) — single shared Component contract for the UI layer.
+ *
+ * Five parallel "Component" shapes previously existed across src/ui/:
+ *
+ *   - `RenderableComponent`        (layout-primitives.ts)
+ *   - `WidgetComponent`            (widget/index.ts)
+ *   - `DashboardComponent`         (run-dashboard.ts)
+ *   - `type Component`             (transcript-viewer.ts)
+ *   - `type Component = Container|Text` (tool-renderers/index.ts)
+ *
+ * They all share the same two core methods (render + invalidate) but could
+ * not be used interchangeably, which blocked polymorphic dispatch and shared
+ * testing. This module names that shared contract so any UI component can be
+ * treated uniformly.
+ *
+ * This is purely additive: every existing component already structurally
+ * satisfies these interfaces (render + invalidate are required everywhere;
+ * handleInput is present on the interactive ones). Adapting the existing
+ * declarations to `extends`/alias these types changes NO runtime behavior —
+ * it only makes the relationship explicit and compiler-enforced.
+ *
+ * Note: @earendil-works/pi-tui also declares a `Component` interface with the
+ * same render+invalidate core (plus an optional handleInput). `CrewComponent`
+ * is a structural supertype of it, so pi-tui components opt in automatically.
+ */
+
+/** Minimum shared contract every UI component satisfies. */
+export interface CrewComponent {
+	/**
+	 * Drop cached render state so the next `render` recomputes from fresh data.
+	 * Called on theme changes, resize, or any state mutation that invalidates
+	 * previously produced lines.
+	 */
+	invalidate(): void;
+	/**
+	 * Produce rendered lines for the given terminal width.
+	 * @param width - available terminal width in cells
+	 * @returns one string per output row (already padded/ANSI-colored)
+	 */
+	render(width: number): string[];
+}
+
+/**
+ * A component that also accepts raw key/input data. Interactive viewers
+ * (RunDashboard, DurableTranscriptViewer) and overlays (ConfirmOverlay,
+ * MailboxDetailOverlay, AgentPickerOverlay) implement this; purely
+ * presentational components (Container, Text, Spacer, Box) do not.
+ */
+export interface InteractiveComponent extends CrewComponent {
+	/** Optional stable id (used by overlay stacks for lookup/debug). */
+	id?: string;
+	/** Consume a raw input chunk (a keypress escape sequence). */
+	handleInput(data: string): void;
+}