pi-crew 0.11.41 → 0.11.43

package/package.json

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

package/src/runtime/process/zombie-scanner.ts

@@ -97,11 +97,51 @@ export interface ForeignPiProcess {
 	cmd: string;
 }
 
+/** Wave-14 F4 (GAP-3): injectable seam for `scanZombieSubagents`.
+ *
+ *  Every ambient read the scanner performs is replaceable so classification
+ *  tests can drive a SYNTHETIC /proc on every OS (previously 7 tests skipped
+ *  forever on macOS/Windows CI). Defaults preserve behavior EXACTLY — each
+ *  read-site resolves `opts.X ?? <the previous inline expression>` (the same
+ *  injection pattern as reap-group.ts ReapGroupOptions, wave 12b). Production
+ *  callers are no-arg (doctor.ts, orphan-reaper.ts) and see zero change. */
+export interface ZombieScanOptions {
+	/** Platform gate. Default `process.platform`. */
+	platform?: NodeJS.Platform;
+	/** Real uid of the scanner process. Default `tryGetUid` (try/catch around
+	 *  `process.getuid?.()` — undefined on win32). */
+	getuid?: () => number | undefined;
+	/** File reader for /proc paths. Default `fs.readFileSync(p, "utf-8")` with
+	 *  read errors mapped to `undefined` (the previous per-helper catch). */
+	readProcFile?: (p: string) => string | undefined;
+	/** Candidate pid enumeration. Default: readdir of the real `/proc`. */
+	listProcPids?: () => number[];
+	/** Pid liveness probe. Default `isPidAlive` (`process.kill(pid, 0)` with the
+	 *  R7-A2 ESRCH/ENOENT semantics). */
+	pidAlive?: (pid: number) => boolean;
+	/** Scanner's own parent pid — the ancestor-chain starting point. Default
+	 *  `process.ppid`. Injection point for deterministic ancestor tests. */
+	getParentPid?: () => number;
+}
+
+/** Normalized /proc read: `undefined` = unreadable (missing, EPERM, …). */
+type ReadProcFile = (p: string) => string | undefined;
+
+/** Default seam reader — real fs with the previous per-helper catch folded in. */
+const defaultReadProcFile: ReadProcFile = (p) => {
+	try {
+		return fs.readFileSync(p, "utf-8");
+	} catch {
+		return undefined;
+	}
+};
+
 /** Read /proc/<pid>/environ as a key=value record. Returns {} if unreadable. */
-function readProcEnviron(pid: number): Record<string, string> {
+function readProcEnviron(pid: number, read: ReadProcFile = defaultReadProcFile): Record<string, string> {
 	try {
 		// /proc/<pid>/environ is NUL-separated key=value pairs.
-		const raw = fs.readFileSync(`/proc/${pid}/environ`, "utf-8");
+		const raw = read(`/proc/${pid}/environ`);
+		if (raw === undefined) return {};
 		const out: Record<string, string> = {};
 		for (const entry of raw.split("\0")) {
 			const eq = entry.indexOf("=");
@@ -114,9 +154,13 @@ function readProcEnviron(pid: number): Record<string, string> {
 }
 
 /** Read /proc/<pid>/stat to get ppid + starttime + elapsed. Returns undefined if unreadable. */
-function readProcStat(pid: number): { ppid: number; starttime: number | undefined; elapsedSec: number | undefined } | undefined {
+function readProcStat(
+	pid: number,
+	read: ReadProcFile = defaultReadProcFile,
+): { ppid: number; starttime: number | undefined; elapsedSec: number | undefined } | undefined {
 	try {
-		const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf-8");
+		const stat = read(`/proc/${pid}/stat`);
+		if (stat === undefined) return undefined;
 		// stat format: pid (comm) state ppid ... starttime ...
 		// Shared paren-aware cut (proc-stat.ts) — MUST index identically with
 		// surface-spawn's PI_CREW_PARENT_START_TIME capture.
@@ -125,7 +169,7 @@ function readProcStat(pid: number): { ppid: number; starttime: number | undefine
 		const ppid = Number.parseInt(rest[PROC_STAT_PPID_INDEX] ?? "", 10);
 		const starttimeTicksRaw = Number.parseInt(rest[PROC_STAT_STARTTIME_INDEX] ?? "", 10);
 		const starttime = Number.isFinite(starttimeTicksRaw) ? starttimeTicksRaw : undefined;
-		const elapsedSec = computeElapsedSec(starttime);
+		const elapsedSec = computeElapsedSec(starttime, read);
 		return { ppid: Number.isFinite(ppid) ? ppid : 0, starttime, elapsedSec };
 	} catch {
 		return undefined;
@@ -133,9 +177,10 @@ function readProcStat(pid: number): { ppid: number; starttime: number | undefine
 }
 
 /** /proc/uptime first field (seconds since boot); undefined when unreadable. */
-function readUptimeSec(): number | undefined {
+function readUptimeSec(read: ReadProcFile = defaultReadProcFile): number | undefined {
 	try {
-		const uptimeRaw = fs.readFileSync("/proc/uptime", "utf-8");
+		const uptimeRaw = read("/proc/uptime");
+		if (uptimeRaw === undefined) return undefined;
 		const uptimeSec = Number.parseFloat(uptimeRaw.split(" ")[0] ?? "");
 		return Number.isFinite(uptimeSec) ? uptimeSec : undefined;
 	} catch {
@@ -148,22 +193,22 @@ function readUptimeSec(): number | undefined {
  * ticks — boot time = now - uptime, so startedAt = boot + starttime/CLK_TCK.
  * Best-effort ISO string; undefined when /proc/uptime is unavailable.
  */
-function computeStartedAtIso(starttime: number | undefined): string | undefined {
+function computeStartedAtIso(starttime: number | undefined, read: ReadProcFile = defaultReadProcFile): string | undefined {
 	if (starttime === undefined || !Number.isFinite(starttime)) return undefined;
-	const uptimeSec = readUptimeSec();
+	const uptimeSec = readUptimeSec(read);
 	if (uptimeSec === undefined) return undefined;
 	const bootMs = Date.now() - uptimeSec * 1000;
 	return new Date(bootMs + (starttime / 100) * 1000).toISOString();
 }
 
-function computeElapsedSec(starttimeTicks: number | undefined): number | undefined {
+function computeElapsedSec(starttimeTicks: number | undefined, read: ReadProcFile = defaultReadProcFile): number | undefined {
 	if (starttimeTicks === undefined || !Number.isFinite(starttimeTicks)) return undefined;
 	try {
 		// Linux CLK_TCK is virtually always 100 (sysconf(_SC_CLK_TCK)). Reading it
 		// portably from Node requires a native addon; hardcoding 100 matches every
 		// mainstream Linux distro and keeps this dependency-free.
 		const ticksPerSec = 100;
-		const uptimeSec = readUptimeSec();
+		const uptimeSec = readUptimeSec(read);
 		if (uptimeSec === undefined) return undefined;
 		// starttime (ticks since boot) → process age in seconds = uptime - starttime/ticksPerSec.
 		const startAgeSec = starttimeTicks / ticksPerSec;
@@ -188,24 +233,26 @@ function isPidAlive(pid: number): boolean {
 	}
 }
 
-function readProcCmdline(pid: number): string {
-	return readProcCmdlineTokens(pid).join(" ").trim() || `pid ${pid}`;
+function readProcCmdline(pid: number, read: ReadProcFile = defaultReadProcFile): string {
+	return readProcCmdlineTokens(pid, read).join(" ").trim() || `pid ${pid}`;
 }
 
 /** /proc/<pid>/cmdline as argv tokens (NUL-split). Empty array if unreadable. */
-function readProcCmdlineTokens(pid: number): string[] {
+function readProcCmdlineTokens(pid: number, read: ReadProcFile = defaultReadProcFile): string[] {
 	try {
 		// /proc/<pid>/cmdline is NUL-separated argv.
-		const raw = fs.readFileSync(`/proc/${pid}/cmdline`, "utf-8");
+		const raw = read(`/proc/${pid}/cmdline`);
+		if (raw === undefined) return [];
 		return raw.split("\0").filter(Boolean);
 	} catch {
 		return [];
 	}
 }
 
-function readProcRssKb(pid: number): number {
+function readProcRssKb(pid: number, read: ReadProcFile = defaultReadProcFile): number {
 	try {
-		const status = fs.readFileSync(`/proc/${pid}/status`, "utf-8");
+		const status = read(`/proc/${pid}/status`);
+		if (status === undefined) return 0;
 		const match = status.match(/^VmRSS:\s+(\d+)\s+kB/m);
 		return match ? Number.parseInt(match[1] ?? "", 10) : 0;
 	} catch {
@@ -221,8 +268,8 @@ function readProcRssKb(pid: number): number {
  * non-Linux platforms the scanner returns an empty result with a note in
  * `errors` (zombie detection is best-effort; the doctor report still renders).
  */
-function listCandidatePids(): number[] {
-	if (process.platform !== "linux") return [];
+function listCandidatePids(platform: NodeJS.Platform = process.platform): number[] {
+	if (platform !== "linux") return [];
 	const pids: number[] = [];
 	try {
 		for (const entry of fs.readdirSync("/proc")) {
@@ -241,23 +288,30 @@ function listCandidatePids(): number[] {
  * any scan errors. Callers decide what to do with the result; this module
  * has no side effects.
  */
-export function scanZombieSubagents(): ZombieScanResult {
+export function scanZombieSubagents(opts: ZombieScanOptions = {}): ZombieScanResult {
+	// Wave-14 F4: resolve the seam ONCE — every default below is the exact
+	// previous inline expression, so no-arg callers are byte-for-byte behavior
+	// preserved (doctor.ts:990, orphan-reaper.ts:306).
+	const platform = opts.platform ?? process.platform;
+	const read = opts.readProcFile ?? defaultReadProcFile;
+	const pidAlive = opts.pidAlive ?? isPidAlive;
 	const result: ZombieScanResult = { zombies: [], live: [], foreign: [], errors: [] };
-	if (process.platform !== "linux") {
-		result.errors.push("zombie scan is Linux-only (/proc required); skipping on " + process.platform);
+	if (platform !== "linux") {
+		result.errors.push("zombie scan is Linux-only (/proc required); skipping on " + platform);
 		return result;
 	}
 
-	const myUid = tryGetUid();
+	const myUid = (opts.getuid ?? tryGetUid)();
 	// R3-16: self + ancestors are live hosting sessions (main session / crew
 	// host chain) — never reportable as foreign, even when they carry markers.
-	const ancestors = collectAncestorPids();
-	for (const pid of listCandidatePids()) {
+	const ancestors = collectAncestorPids(read, opts.getParentPid);
+	const listPids = opts.listProcPids ?? (() => listCandidatePids(platform));
+	for (const pid of listPids()) {
 		try {
 			// Cheap rejection first: only inspect processes we own (avoid scanning system procs).
-			if (myUid !== undefined && getProcUid(pid) !== myUid) continue;
+			if (myUid !== undefined && getProcUid(pid, read) !== myUid) continue;
 
-			const environ = readProcEnviron(pid);
+			const environ = readProcEnviron(pid, read);
 			// AUTHORITATIVE GATE: a process is a pi-crew sub-agent ONLY if it carries
 			// PI_CREW_KIND=subagent. The user's main session never sets this, so it can
 			// never be matched — this is the fix for accidentally killing main sessions.
@@ -271,18 +325,18 @@ export function scanZombieSubagents(): ZombieScanResult {
 				// them (pi-crew also scrubs these markers from worker env).
 				const hasPiMarker = environ.AI_AGENT === "pi" || environ.PI_CODING_AGENT === "true";
 				if (hasPiMarker && pid !== process.pid && !ancestors.has(pid)) {
-					const tokens = readProcCmdlineTokens(pid);
+					const tokens = readProcCmdlineTokens(pid, read);
 					if (looksLikePiBinary(tokens)) {
-						const foreignStat = readProcStat(pid);
+						const foreignStat = readProcStat(pid, read);
 						const ppid = foreignStat?.ppid ?? 0;
 						result.foreign.push({
 							pid,
 							ppid,
-							orphaned: ppid <= 1 || !isPidAlive(ppid),
+							orphaned: ppid <= 1 || !pidAlive(ppid),
 							headless: isHeadlessArgv(tokens),
-							rssKb: readProcRssKb(pid),
+							rssKb: readProcRssKb(pid, read),
 							elapsedSec: foreignStat?.elapsedSec,
-							cmd: readProcCmdline(pid),
+							cmd: readProcCmdline(pid, read),
 						});
 					}
 				}
@@ -290,7 +344,7 @@ export function scanZombieSubagents(): ZombieScanResult {
 			}
 
 			const crewParentPid = Number.parseInt(environ.PI_CREW_PARENT_PID ?? "", 10);
-			const stat = readProcStat(pid);
+			const stat = readProcStat(pid, read);
 			// Surface identity (T12): strict allowlist — an unrelated PI_CREW_SURFACE
 			// value must not half-populate the fields doctor relies on for pane close.
 			const surface = environ.PI_CREW_SURFACE === "tmux" || environ.PI_CREW_SURFACE === "herdr" ? environ.PI_CREW_SURFACE : undefined;
@@ -298,17 +352,17 @@ export function scanZombieSubagents(): ZombieScanResult {
 				pid,
 				ppid: stat?.ppid ?? 0,
 				crewParentPid: Number.isFinite(crewParentPid) ? crewParentPid : 0,
-				parentAlive: Number.isFinite(crewParentPid) && isPidAlive(crewParentPid),
+				parentAlive: Number.isFinite(crewParentPid) && pidAlive(crewParentPid),
 				role: environ.PI_CREW_ROLE,
 				surface,
 				surfacePaneId: environ.PI_CREW_SURFACE_PANE || undefined,
-				rssKb: readProcRssKb(pid),
+				rssKb: readProcRssKb(pid, read),
 				elapsedSec: stat?.elapsedSec,
 				// M-7: starttime (ticks) + derived wall-clock start — pid identity pin
 				// for kill-time PID-reuse checks and prompt-kill triage.
 				starttime: stat?.starttime,
-				startedAt: computeStartedAtIso(stat?.starttime),
-				cmd: readProcCmdline(pid),
+				startedAt: computeStartedAtIso(stat?.starttime, read),
+				cmd: readProcCmdline(pid, read),
 			};
 
 			if (entry.parentAlive) {
@@ -338,10 +392,11 @@ function tryGetUid(): number | undefined {
 	}
 }
 
-function getProcUid(pid: number): number | undefined {
+function getProcUid(pid: number, read: ReadProcFile = defaultReadProcFile): number | undefined {
 	try {
 		// /proc/<pid>/status has Uid: <real> <eff> <sav> <fs>
-		const status = fs.readFileSync(`/proc/${pid}/status`, "utf-8");
+		const status = read(`/proc/${pid}/status`);
+		if (status === undefined) return undefined;
 		const match = status.match(/^Uid:\s+(\d+)/m);
 		return match ? Number.parseInt(match[1] ?? "", 10) : undefined;
 	} catch {
@@ -393,13 +448,13 @@ function isHeadlessArgv(tokens: string[]): boolean {
  * it sit on this chain and carry markers when pi-in-pi). Bounded at 64 hops to
  * survive a hypothetical pid cycle.
  */
-function collectAncestorPids(): Set<number> {
+function collectAncestorPids(read: ReadProcFile = defaultReadProcFile, getParentPid?: () => number): Set<number> {
 	const chain = new Set<number>();
-	let current = process.ppid;
+	let current = getParentPid !== undefined ? getParentPid() : process.ppid;
 	let guard = 0;
 	while (current > 1 && guard++ < 64) {
 		chain.add(current);
-		const stat = readProcStat(current);
+		const stat = readProcStat(current, read);
 		if (!stat || stat.ppid <= 0) break;
 		current = stat.ppid;
 	}

package/src/runtime/process-status.ts

@@ -1,4 +1,4 @@
-import type { TeamRunManifest } from "../state/types.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import type { CrewAgentRecord } from "./crew-agent-runtime.ts";
 
 export { hasAsyncStartMarker } from "./async-marker.ts";
@@ -92,6 +92,33 @@ export function hasRecentAgentActivityEvidence(agent: CrewAgentRecord, now = Dat
 	return Number.isFinite(at) && now - at < livenessMs;
 }
 
+/**
+ * Wave 15 (F1, GAP-0): does any running/waiting task carry FRESH live
+ * evidence — a `heartbeat.lastSeenAt` (with `alive !== false`) or the
+ * `agentProgress.lastActivityAt` fallback — within `ttlMs`? Behavioral
+ * mirror of the watchdog's private helper (foreground-watchdog.ts) and
+ * hasRecentActiveEvidence (stale-reconciler.ts), so watchdog, reconciler
+ * and display stop growing a third divergent private copy. PURE (GAP-4:
+ * the shared display predicates keep their signatures — call sites that
+ * already hold the tasks OR this in). Default TTL 5 min keeps the constant
+ * family aligned (AGENT_ACTIVITY_LIVENESS_MS = TASK_HEARTBEAT_EVIDENCE_MS
+ * = ACTIVE_EVIDENCE_TTL_MS). Undefined/empty/all-terminal ⇒ false.
+ */
+export function hasFreshTaskHeartbeatEvidence(
+	tasks: TeamTaskState[] | undefined,
+	now = Date.now(),
+	ttlMs = AGENT_ACTIVITY_LIVENESS_MS,
+): boolean {
+	if (!Array.isArray(tasks)) return false;
+	return tasks.some((task) => {
+		if (task.status !== "running" && task.status !== "waiting") return false;
+		const heartbeatAt = task.heartbeat?.lastSeenAt ? new Date(task.heartbeat.lastSeenAt).getTime() : Number.NaN;
+		if (task.heartbeat?.alive !== false && Number.isFinite(heartbeatAt) && now - heartbeatAt <= ttlMs) return true;
+		const activityAt = task.agentProgress?.lastActivityAt ? new Date(task.agentProgress.lastActivityAt).getTime() : Number.NaN;
+		return Number.isFinite(activityAt) && now - activityAt <= ttlMs;
+	});
+}
+
 export function isLikelyOrphanedActiveRun(
 	run: TeamRunManifest,
 	agents: CrewAgentRecord[] = [],

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

@@ -1376,6 +1376,48 @@ export function appendEventFireAndForget(eventsPath: string, event: AppendTeamEv
 	appendEventAsync(eventsPath, event).catch((error) => logInternalError("event-log.fire-and-forget", error, eventsPath));
 }
 
+/**
+ * Wave-14 F1 (GAP-0): await a run's in-flight event-log writers.
+ *
+ * Safe to call from tests before removing a run state dir: awaits all
+ * in-flight async appends for the given events path (all paths when omitted)
+ * and flushes its buffer. No-op when nothing is in flight.
+ *
+ * - With `eventsPath`: awaiting the per-path queue TAIL settles the entire
+ *   write chain (tail-chaining guarantees the tail completes last), then
+ *   flushes that path's buffered tier via the internal `flushOneEventLogBuffer`
+ *   (per-path flush is a simple direct call — no complexity caveat).
+ *   The Map entry may already have self-deleted (compare-and-delete on
+ *   settle) — `?? Promise.resolve()` makes that a clean no-op.
+ * - Without `eventsPath`: awaits every queue tail + `flushEventLogBuffer()`.
+ *
+ * Never throws: a rejected tail is absorbed by `allSettled` (a teardown
+ * helper must never fail because an old write failed — the error-reset path
+ * in appendEventAsync already logs and resets the queue). The buffer flush
+ * is best-effort for the same reason. The MAX_ASYNC_QUEUES (256) cap is
+ * irrelevant here: drain-by-key touches one entry, global drain iterates
+ * whatever currently exists. `drainAsyncQueues` stays private — this is the
+ * public, path-scoped surface.
+ */
+export async function drainEventLogWriters(eventsPath?: string): Promise<void> {
+	if (eventsPath !== undefined) {
+		const tail = asyncQueues.get(eventsPath) ?? Promise.resolve();
+		await Promise.allSettled([tail]);
+		try {
+			await flushOneEventLogBuffer(eventsPath);
+		} catch {
+			/* best-effort — teardown must not fail on a flush error */
+		}
+		return;
+	}
+	await Promise.allSettled([...asyncQueues.values()]);
+	try {
+		await flushEventLogBuffer();
+	} catch {
+		/* best-effort */
+	}
+}
+
 // Auto-flush on process exit so buffered events do not silently leak.
 // Defense-in-depth: SIGTERM/SIGINT use setImmediate so the handler returns
 // immediately and the main thread is not blocked by sync I/O.

package/src/ui/agents-jobs-browser.ts

@@ -49,7 +49,7 @@
  * dashboard overlay, so headless sessions never reach it.
  */
 
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { matchesKey } from "@earendil-works/pi-tui";
@@ -60,13 +60,14 @@ import type { CrewAgentRecord } from "../runtime/crew-agent-runtime.ts";
 import type { LiveAgentHandle } from "../runtime/live-session/live-agent-manager.ts";
 import type { ManifestCache } from "../runtime/manifest-cache.ts";
 import { createManifestCache } from "../runtime/manifest-cache.ts";
-import { isDisplayActiveRun } from "../runtime/process-status.ts";
+import { hasFreshTaskHeartbeatEvidence, isActiveRunStatus, isDisplayActiveRun } from "../runtime/process-status.ts";
 import type { ScheduledJob } from "../runtime/scheduling/scheduler.ts";
 import { surfaceGateEnvSnapshot } from "../runtime/surface/resolve-surface.ts";
 import { getTaskUsage } from "../runtime/usage-tracker.ts";
 import { readJsonFile } from "../state/atomic-write.ts";
 import { loadRunManifestById } from "../state/stores/state-store.ts";
-import type { TeamRunManifest } from "../state/types.ts";
+import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import { readJsonFileCoalesced } from "../utils/file-coalescer.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { formatRelativeTime } from "../utils/relative-time.ts";
 import { pad, sanitizeLine, truncate, visibleWidth } from "../utils/visual.ts";
@@ -202,6 +203,28 @@ function watchAgentTranscriptScript(): string | undefined {
 	return candidates.find((c) => existsSync(c));
 }
 
+/** Tasks-read TTL for the legacy-discovery heartbeat check (coalesced, live-run-sidebar pattern). */
+const LEGACY_TASKS_READ_TTL_MS = 1000;
+
+/**
+ * Wave 15 (F2, GAP-0): coalesced tasks.json read for the legacy-discovery
+ * loop — mirrors run-dashboard/live-run-sidebar's readRunTasks. Returns
+ * undefined on unreadable so a broken tasks.json can NEVER fabricate
+ * liveness evidence (fail-closed).
+ */
+function readLegacyRunTasks(run: TeamRunManifest): TeamTaskState[] | undefined {
+	const parse = (): TeamTaskState[] => {
+		if (!existsSync(run.tasksPath)) return [];
+		const parsed = JSON.parse(readFileSync(run.tasksPath, "utf-8")) as unknown;
+		return Array.isArray(parsed) ? (parsed as TeamTaskState[]) : [];
+	};
+	try {
+		return readJsonFileCoalesced(run.tasksPath, LEGACY_TASKS_READ_TTL_MS, parse);
+	} catch {
+		return undefined;
+	}
+}
+
 /** tok/s for record-based entries (no live handle in this process). */
 function recordTokPerSec(record: CrewAgentRecord, nowMs: number): number | undefined {
 	if (record.status !== "running") return undefined;
@@ -476,7 +499,14 @@ export class AgentsJobsBrowser {
 				if (run.status !== "running" && run.status !== "queued") continue;
 				try {
 					const agents = readCrewAgents(run);
-					if (isDisplayActiveRun(run, agents, nowMs)) runs.push({ run, agents });
+					// Wave 15 (F2, GAP-0): tight heartbeat guard — a legacy-uncovered run
+					// whose manifest froze mid-long-tool stays listed while its task
+					// heartbeats are fresh (this loop already does per-run I/O — one more
+					// coalesced read is in-pattern). Terminal/async runs are never
+					// resurrected (isActiveRunStatus && !run.async).
+					const heartbeatLive =
+						isActiveRunStatus(run.status) && !run.async && hasFreshTaskHeartbeatEvidence(readLegacyRunTasks(run), nowMs);
+					if (isDisplayActiveRun(run, agents, nowMs) || heartbeatLive) runs.push({ run, agents });
 				} catch {
 					/* unreadable — skip */
 				}

package/src/ui/run-dashboard.ts

@@ -10,7 +10,12 @@ import { readCrewAgents } from "../runtime/crew-agent-records.ts";
 import type { CrewAgentRecord } from "../runtime/crew-agent-runtime.ts";
 import { getLiveAgentContextPercent } from "../runtime/live-session/live-agent-manager.ts";
 import { isPlanApprovalPending } from "../runtime/plan-approval.ts";
-import { isActiveRunStatus, isDisplayActiveRun, isLikelyOrphanedActiveRun } from "../runtime/process-status.ts";
+import {
+	hasFreshTaskHeartbeatEvidence,
+	isActiveRunStatus,
+	isDisplayActiveRun,
+	isLikelyOrphanedActiveRun,
+} from "../runtime/process-status.ts";
 import type { ScheduledJob } from "../runtime/scheduling/scheduler.ts";
 import type { TeamRunManifest, TeamTaskState, UsageState } from "../state/types.ts";
 import { aggregateUsage } from "../state/usage.ts";
@@ -363,6 +368,19 @@ function taskForAgent(tasks: TeamTaskState[], agent: CrewAgentRecord): TeamTaskS
 	return tasks.find((task) => task.id === agent.taskId);
 }
 
+/**
+ * Wave 15 (F2, GAP-0): tight heartbeat-liveness guard for ACTIVE display —
+ * mirrors the orphan predicate's own preconditions (active status, non-async)
+ * so a terminal or async run is never resurrected by a heartbeat. A healthy
+ * direct run mid-long-tool freezes manifest `updatedAt` and agent progress
+ * (event-driven writes) but keeps stamping `task.heartbeat.lastSeenAt`, so
+ * fresh evidence means the run is alive. Call sites OR this in ONLY — every
+ * non-stale branch and layout stays untouched.
+ */
+function heartbeatLiveForDisplay(run: TeamRunManifest, tasks: TeamTaskState[] | undefined, now = Date.now()): boolean {
+	return isActiveRunStatus(run.status) && !run.async && hasFreshTaskHeartbeatEvidence(tasks, now);
+}
+
 function modelForTask(task: TeamTaskState | undefined): string | undefined {
 	const attempts = task?.modelAttempts;
 	if (!attempts?.length) return undefined;
@@ -467,7 +485,9 @@ function runLabel(
 	resolve?: SnapshotResolver,
 ): string {
 	const agents = agentsFor(run, snapshotCache, resolve);
-	const stale = isLikelyOrphanedActiveRun(run, agents);
+	// Wave 15 (F2): a stale-manifest verdict is VETOED by fresh task-heartbeat
+	// evidence (lazy read — only consulted when the orphan predicate fires).
+	const stale = isLikelyOrphanedActiveRun(run, agents) && !heartbeatLiveForDisplay(run, readRunTasks(run, snapshotCache, resolve));
 	const running = agents.find((agent) => agent.status === "running");
 	const queued = agents.find((agent) => agent.status === "queued");
 	const step = stale
@@ -523,7 +543,12 @@ function resolveRuns(runs: TeamRunManifest[], snapshotCache?: RunSnapshotCache,
 		const snapshot = resolve ? resolve(run) : snapshotFor(run, snapshotCache);
 		const agents = snapshot?.agents ?? agentsFor(run, snapshotCache, resolve);
 		const displayRun = snapshot?.manifest ?? run;
-		const status: RunStatus = isLikelyOrphanedActiveRun(displayRun, agents) ? "stale" : (displayRun.status as RunStatus);
+		// Wave 15 (F2): fresh task heartbeats veto the "stale" label.
+		const status: RunStatus =
+			isLikelyOrphanedActiveRun(displayRun, agents) &&
+			!heartbeatLiveForDisplay(displayRun, snapshot?.tasks ?? readRunTasks(run, snapshotCache, resolve))
+				? "stale"
+				: (displayRun.status as RunStatus);
 		map.set(run.runId, { manifest: run, snapshot, agents, status });
 	}
 	return map;
@@ -536,12 +561,19 @@ function groupedRuns(
 ): Array<{ label: string; run?: TeamRunManifest }> {
 	const resolved = resolveRuns(runs, snapshotCache, resolve);
 	const rows: Array<{ label: string; run?: TeamRunManifest }> = [];
-	const active = runs.filter((run) =>
-		isDisplayActiveRun(resolved.get(run.runId)?.snapshot?.manifest ?? run, resolved.get(run.runId)?.agents ?? []),
-	);
-	const rest = runs.filter(
-		(run) => !isDisplayActiveRun(resolved.get(run.runId)?.snapshot?.manifest ?? run, resolved.get(run.runId)?.agents ?? []),
-	);
+	// Wave 15 (F2): a run with fresh task-heartbeat evidence stays display-active
+	// even when the manifest froze mid-long-tool (tight guard — never resurrects
+	// terminal/async runs).
+	const displayActive = (run: TeamRunManifest): boolean => {
+		const entry = resolved.get(run.runId);
+		const displayRun = entry?.snapshot?.manifest ?? run;
+		return (
+			isDisplayActiveRun(displayRun, entry?.agents ?? []) ||
+			heartbeatLiveForDisplay(displayRun, entry?.snapshot?.tasks ?? readRunTasks(run, snapshotCache, resolve))
+		);
+	};
+	const active = runs.filter((run) => displayActive(run));
+	const rest = runs.filter((run) => !displayActive(run));
 	if (active.length) rows.push({ label: "Active" }, ...active.map((run) => ({ label: run.runId, run })));
 	if (rest.length) rows.push({ label: "Recent" }, ...rest.map((run) => ({ label: run.runId, run })));
 	return rows;
@@ -754,7 +786,10 @@ export class RunDashboard implements DashboardComponent {
 				const snapshot = resolve ? resolve(run) : snapshotFor(run, this.options.snapshotCache);
 				const displayRun = snapshot?.manifest ?? run;
 				const agents = snapshot?.agents ?? agentsFor(run, this.options.snapshotCache, resolve);
-				const stale = isLikelyOrphanedActiveRun(displayRun, agents);
+				// Wave 15 (F2): fresh task heartbeats veto the "stale" label.
+				const stale =
+					isLikelyOrphanedActiveRun(displayRun, agents) &&
+					!heartbeatLiveForDisplay(displayRun, snapshot?.tasks ?? readRunTasks(run, this.options.snapshotCache, resolve));
 				const status: RunStatus = stale ? "stale" : (displayRun.status as RunStatus);
 				if (status === "running" || agents.some((agent) => agent.status === "running")) hasRunning = true;
 				return snapshot?.signature ?? `${displayRun.runId}:${displayRun.status}:${displayRun.updatedAt}:${status}`;
@@ -963,7 +998,15 @@ export class RunDashboard implements DashboardComponent {
 							const snap = snapshotOnce(rowItem.run);
 							const run = snap?.manifest ?? rowItem.run;
 							const agents = snap?.agents ?? agentsFor(rowItem.run, this.options.snapshotCache, snapshotOnce);
-							const status: RunStatus = isLikelyOrphanedActiveRun(run, agents) ? "stale" : (run.status as RunStatus);
+							// Wave 15 (F2): fresh task heartbeats veto the "stale" label (status line).
+							const status: RunStatus =
+								isLikelyOrphanedActiveRun(run, agents) &&
+								!heartbeatLiveForDisplay(
+									run,
+									snap?.tasks ?? readRunTasks(rowItem.run, this.options.snapshotCache, snapshotOnce),
+								)
+									? "stale"
+									: (run.status as RunStatus);
 							const label = runLabel(run, idx === this.selected, this.options.snapshotCache, budget, snapshotOnce);
 							lines.push(row(applyStatusColor(this.theme, status, label)));
 						}
@@ -977,7 +1020,15 @@ export class RunDashboard implements DashboardComponent {
 							const snap = snapshotOnce(rowItem.run);
 							const run = snap?.manifest ?? rowItem.run;
 							const agents = snap?.agents ?? agentsFor(rowItem.run, this.options.snapshotCache, snapshotOnce);
-							const status: RunStatus = isLikelyOrphanedActiveRun(run, agents) ? "stale" : (run.status as RunStatus);
+							// Wave 15 (F2): fresh task heartbeats veto the "stale" label (windowed status line).
+							const status: RunStatus =
+								isLikelyOrphanedActiveRun(run, agents) &&
+								!heartbeatLiveForDisplay(
+									run,
+									snap?.tasks ?? readRunTasks(rowItem.run, this.options.snapshotCache, snapshotOnce),
+								)
+									? "stale"
+									: (run.status as RunStatus);
 							const label = runLabel(run, gi === this.selected, this.options.snapshotCache, budget, snapshotOnce);
 							lines.push(row(applyStatusColor(this.theme, status, label)));
 						}
@@ -996,8 +1047,12 @@ export class RunDashboard implements DashboardComponent {
 						const snap = snapshotOnce(selectedRun);
 						const r = snap?.manifest ?? selectedRun;
 						const agents = snap?.agents ?? agentsFor(selectedRun, this.options.snapshotCache, snapshotOnce);
-						const statusStr: RunStatus = isLikelyOrphanedActiveRun(r, agents) ? "stale" : (r.status as RunStatus);
 						const selectedTasks = snap?.tasks ?? readRunTasks(r, this.options.snapshotCache, snapshotOnce);
+						// Wave 15 (F2): fresh task heartbeats veto the "stale" label (detail header).
+						const statusStr: RunStatus =
+							isLikelyOrphanedActiveRun(r, agents) && !heartbeatLiveForDisplay(r, selectedTasks)
+								? "stale"
+								: (r.status as RunStatus);
 						lines.push(section("run"));
 						lines.push(row(`${fg("accent", "▸")} ${truncate(sanitizeUntrustedLine(r.goal), budget - 4)}`));
 						// L-2: surface the failure/cancellation reason inline for terminal runs.