pi-crew 0.9.55 → 0.9.57

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.
@@ -151,19 +158,33 @@ function scopeBaseRoot(cwd: string): string {
 	return useProjectState(cwd) ? projectCrewRoot(cwd) : userCrewRoot();
 }
 
+// P1-12: the containment verdict (resolveRealContainedPath ancestor walk, ~8-12
+// syscalls) cannot change for a run dir that isn't replaced — memoize positive
+// results per (cwd, runId) with a short TTL. Negatives are NOT cached (so a
+// newly-created run is found promptly). Downstream manifest stat still catches
+// deletions, so a stale positive is harmless.
+const runStateRootCache = new Map<string, { root: string; expiresAt: number }>();
+const RUN_STATE_ROOT_TTL_MS = 10_000;
+const RUN_STATE_ROOT_CACHE_MAX = 256;
+
 function resolveRunStateRoot(cwd: string, runId: string): string | undefined {
 	assertSafePathId("runId", runId);
+	const key = `${cwd}\0${runId}`;
+	const now = Date.now();
+	const cached = runStateRootCache.get(key);
+	if (cached && cached.expiresAt > now) return cached.root;
 	const runsRoot = path.join(scopeBaseRoot(cwd), DEFAULT_PATHS.state.runsSubdir);
 	const scopedPath = resolveContainedRelativePath(runsRoot, runId, "runId");
 	try {
-		// Single atomic validation: resolves through symlinks via realpath,
-		// verifies containment within runsRoot, and throws ENOENT if missing.
-		// Eliminates the TOCTOU window from the previous existsSync + lstatSync
-		// + resolveRealContainedPath sequence.
 		resolveRealContainedPath(runsRoot, runId);
 	} catch {
 		return undefined;
 	}
+	if (runStateRootCache.size >= RUN_STATE_ROOT_CACHE_MAX) {
+		const oldest = runStateRootCache.keys().next().value;
+		if (oldest !== undefined) runStateRootCache.delete(oldest);
+	}
+	runStateRootCache.set(key, { root: scopedPath, expiresAt: now + RUN_STATE_ROOT_TTL_MS });
 	return scopedPath;
 }
 
@@ -410,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);
 
@@ -487,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 {
@@ -498,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 {
@@ -719,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
@@ -799,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 &&
@@ -919,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;
+}

package/src/ui/crew-select-list.ts

@@ -29,7 +29,9 @@ export class CrewSelectList<T = string> {
 		this.selectedIndex = this.items.length ? 0 : -1;
 	}
 
-	invalidate(): void {}
+	invalidate(): void {
+		/* no-op */
+	}
 
 	getSelected(): CrewSelectItem<T> | undefined {
 		return this.selectedIndex >= 0 ? this.items[this.selectedIndex] : undefined;

package/src/ui/dashboard-panes/agents-pane.ts

@@ -1,5 +1,5 @@
 import type { CrewAgentRecord } from "../../runtime/crew-agent-runtime.ts";
-import { type LiveAgentHandle, listLiveAgents, listLiveAgentsByWorkspace } from "../../runtime/live-agent-manager.ts";
+import { type LiveAgentHandle, listLiveAgents, listLiveAgentsByWorkspace } from "../../runtime/live-session/live-agent-manager.ts";
 import { formatCost } from "../../state/usage.ts";
 import { visibleWidth } from "../../utils/visual.ts";
 import { computeLiveDurationMs } from "../live-duration.ts";

package/src/ui/dwf-phase-display.ts

@@ -8,7 +8,7 @@
  * tailed by `run-snapshot-cache.ts`. Non-DWF runs (no `dwf.phase_*` events)
  * yield `null`, so the progress pane stays unchanged for them.
  */
-import type { TeamEvent } from "../state/event-log.ts";
+import type { TeamEvent } from "../state/event-log/event-log.ts";
 
 // ---------------------------------------------------------------------------
 // Types

package/src/ui/heartbeat-aggregator.ts

@@ -1,5 +1,5 @@
 import type { MetricRegistry } from "../observability/metric-registry.ts";
-import { classifyHeartbeat, heartbeatAgeMs } from "../runtime/heartbeat-gradient.ts";
+import { classifyHeartbeat, heartbeatAgeMs } from "../runtime/heartbeat/heartbeat-gradient.ts";
 import type { TeamTaskState } from "../state/types.ts";
 import type { RunUiSnapshot } from "./snapshot-types.ts";