pi-crew 0.10.2 → 0.10.4

package/src/runtime/surface/degrade.ts

@@ -0,0 +1,776 @@
+/**
+ * degrade.ts — MuxSurface A1 pane-dead → headless hạ cấp (spec §7, D3).
+ *
+ * Bốn lớp, từ thuần sang có trạng thái:
+ *
+ *  1. PURE — `classifyOnExit` (classify timeout 2s sau `onExit`),
+ *     `nextLockoutCounts` / `nextLockoutCountsForBatch` (anti-flap cause-group),
+ *     cặp đếm spawn-fail (`nextConsecutiveSpawnFails` + threshold).
+ *  2. PROBE — `makeTerminalEventProbe`: implementation mặc định của callback
+ *     `waitForCompleted`, tail RUN events.jsonl tìm `worker.completed` mà worker
+ *     tự ghi qua WP-9 channel (D7: report trước khi chết) — đọc incremental,
+ *     clock/poll injectable để test không chờ thật.
+ *  3. REDUCER — các hàm thuần trên `ManifestSurfaceState` (+ normalize an toàn
+ *     khi manifest cũ/thối), và `planHeadlessRedeplays` biến danh sách degrade
+ *     thành task re-queue + resume note.
+ *  4. CONTROLLER — `createSurfaceRuntimeController`: một instance per run do
+ *     team-runner tạo; child-pi layer gọi qua registry theo runId (cùng mô
+ *     hình module-singleton với `getActiveBrokerIssuer`). Controller sở hữu:
+ *     số pane sống (cap MAX_SURFACE_WORKERS), lockout, revoke token lúc
+ *     degrade, event `surface.degraded`, và hàng đợi re-dispatch mà scheduler
+ *     tick lấy đi (`takeDegraded`).
+ *
+ * Thread-safety: controller chạy trong đúng process của team-runner; các notify
+ * đến tuần tự qua event loop, nên state chỉ cần plain mutation.
+ */
+
+import * as fs from "node:fs";
+
+import { type AppendTeamEvent, appendEventFireAndForget } from "../../state/event-log/event-log.ts";
+import type { ManifestSurfaceState, TeamTaskState } from "../../state/types.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import type { SurfaceExitReason, SurfaceHandle, SurfaceProvider } from "./surface-provider.ts";
+
+/** Trần classify sau `onExit` (spec §7: tmux poll 2s, fs.watch <100ms). */
+export const CLASSIFY_TIMEOUT_MS = 2000;
+/** Nhịp poll của probe chạy trong ngân sách classify (đủ thưa, không nóng CPU). */
+export const CLASSIFY_POLL_MS = 50;
+/** 3 spawn-fail liên tiếp trong run → surface OFF hết run (spec §7). */
+export const SURFACE_SPAWN_FAIL_LOCKOUT_THRESHOLD = 3;
+
+export type SurfaceDegradeCause = "pane-closed" | "mux-dead";
+export type LockoutCounts = { pane: number; mux: number };
+
+// ── 1. Pure decisions ─────────────────────────────────────────────────────
+
+/**
+ * Classify kết thúc pane: chờ tín hiệu hoàn thành tối đa `timeoutMs` (2s mặc
+ * định). Hàm KHÔNG tự đo thời gian — toàn bộ timing nằm ở `waitForCompleted`
+ * (production dùng {@link makeTerminalEventProbe}; test nhét fake). Return
+ * "completed" chỉ khi tín hiệu tới trong cửa sổ; mọi lý do khác là degraded.
+ */
+export async function classifyOnExit(
+	handle: SurfaceHandle,
+	waitForCompleted: (ms: number) => Promise<boolean>,
+	opts?: { timeoutMs?: number },
+): Promise<"completed" | "degraded"> {
+	if (!handle || typeof waitForCompleted !== "function") return "degraded";
+	return (await waitForCompleted(opts?.timeoutMs ?? CLASSIFY_TIMEOUT_MS)) ? "completed" : "degraded";
+}
+
+/**
+ * Anti-flap — +1 cho ĐÚNG cause group. Batch N-pane cùng lúc xử lý ở
+ * {@link nextLockoutCountsForBatch} (1 sự kiện mux chết = 1 count dù N pane).
+ */
+export function nextLockoutCounts(prev: LockoutCounts, cause: SurfaceDegradeCause): LockoutCounts {
+	const base = { pane: Math.max(0, prev?.pane ?? 0), mux: Math.max(0, prev?.mux ?? 0) };
+	return cause === "mux-dead" ? { ...base, mux: base.mux + 1 } : { ...base, pane: base.pane + 1 };
+}
+
+/**
+ * Cause-group batching (spec §7 bước 3): MỌI entry `mux-dead` trong cùng một
+ * drain window kể là MỘT sự kiện chết-toàn-cục → +1 mux duy nhất, dù N pane
+ * degrade song song; mỗi `pane-closed` vẫn cộng riêng từng pane. `surface.degraded`
+ * vẫn được ghi đủ N entry cùng cause để debug — batch chỉ áp cho LOCKOUT count.
+ */
+export function nextLockoutCountsForBatch(prev: LockoutCounts, causes: readonly SurfaceDegradeCause[]): LockoutCounts {
+	let counts = { pane: Math.max(0, prev?.pane ?? 0), mux: Math.max(0, prev?.mux ?? 0) };
+	if (causes.some((cause) => cause === "mux-dead")) counts = nextLockoutCounts(counts, "mux-dead");
+	for (const cause of causes) {
+		if (cause !== "pane-closed") continue;
+		counts = nextLockoutCounts(counts, "pane-closed");
+	}
+	return counts;
+}
+
+/** Đếm spawn-fail liên tiếp; thành công (surface boot được) reset về 0. */
+export function nextConsecutiveSpawnFails(prev: number, failed: boolean): number {
+	return failed ? Math.max(0, prev ?? 0) + 1 : 0;
+}
+
+/** Ngưỡng OFF-hết-run cho spawn-fail (spec §7: ≥3 liên tiếp). */
+export function isSpawnFailLockout(consecutiveFails: number): boolean {
+	return consecutiveFails >= SURFACE_SPAWN_FAIL_LOCKOUT_THRESHOLD;
+}
+
+// ── 2. Terminal-event probe ───────────────────────────────────────────────
+
+export interface TerminalEventProbeDeps {
+	/** RUN events.jsonl (`manifest.eventsPath`) — nơi worker ghi `worker.completed`. */
+	eventsPath: string;
+	/** Thu hẹp kết quả cho đúng task/run (mặc định: khớp taskId nếu biết). */
+	taskId?: string;
+	runId?: string;
+	/** Reader override cho test (default: fs.readFileSync trả undefined khi lỗi). */
+	readFile?: (path: string) => string | undefined;
+	/**
+	 * Lớp IO của đường incremental (fix round 1/F3): fd mở MỘT lần cho cả cửa
+	 * sổ probe, mỗi poll chỉ đọc byte mới từ offset — run-log lớn không bị
+	 * full-read ~40 lần/degrade nữa (pattern hotspot perf-round cũ). Inject để
+	 * test đếm byte/call mà vẫn đi đúng path production.
+	 */
+	io?: {
+		open(path: string): number;
+		size(fd: number): number;
+		/**
+		 * Đọc byte [start, end). Trả CẢ `bytesRead` (fix round 2): poll có thể
+		 * cắt giữa multi-byte UTF-8 char — toString thay byte lead bằng U+FFFD
+		 * nên Buffer.byteLength(text) > bytesRead; offset phải tiến theo bytesRead
+		 * (parity EventLogTailSource.readFromOffset) nếu không byte thật bị bỏ.
+		 */
+		read(fd: number, start: number, end: number): { text: string; bytesRead: number };
+		close(fd: number): void;
+	};
+	/** Sleep override cho test — nhận ms, resolve khi đồng hồ test cho phép. */
+	sleep?: (ms: number) => Promise<void>;
+	/** Clock (ms) override cho test (default Date.now). */
+	now?: () => number;
+	pollMs?: number;
+}
+
+export interface TerminalEventProbe {
+	(ms: number): Promise<boolean>;
+	/** Payload của dòng completion vừa khớp (result/usage) — reset mỗi lần gọi. */
+	foundPayload(): Record<string, unknown> | undefined;
+}
+
+const EMPTY_PAYLOAD = Object.freeze({});
+
+/**
+ * Tail incremental RUN events.jsonl trong ngân sách `budgetMs`, trả true ngay
+ * khi thấy `worker.completed` (khớp taskId/runId nếu biết).
+ *
+ * Hai chế độ đọc:
+ * - Production: incremental fd (mở 1 lần/ cửa sổ, `readSync` từ byte-offset —
+ *   cùng discipline với EventLogTailSource.readFromOffset; shrink/truncate
+ *   reset offset về 0). Việc đọc mỗi poll TOÀN BỘ run-log là pattern hotspot
+ *   đã bị perf review gắn cờ từ trước — đừng quay lại.
+ * - Test/injected `readFile`: nội dung FULL mỗi lần, offset là char-index vào
+ *   nội dung đó (hành vi cũ giữ nguyên cho fixture đơn giản).
+ *
+ * Hết ngân sách → false — caller quyết định degrade. KHÔNG bao giờ throw.
+ */
+export function makeTerminalEventProbe(deps: TerminalEventProbeDeps): TerminalEventProbe {
+	const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+	const now = deps.now ?? Date.now;
+	const step = Math.max(1, deps.pollMs ?? CLASSIFY_POLL_MS);
+	let offset = 0;
+	let partial = "";
+	let payload: Record<string, unknown> | undefined;
+
+	let fd: number | null = null;
+	const ioOpen = deps.io?.open ?? ((path: string) => fs.openSync(path, "r"));
+	const ioSize = deps.io?.size ?? ((handle: number) => fs.fstatSync(handle).size);
+	const ioRead =
+		deps.io?.read ??
+		((handle: number, start: number, end: number): { text: string; bytesRead: number } => {
+			const length = end - start;
+			const buffer = Buffer.alloc(length);
+			const bytesRead = fs.readSync(handle, buffer, 0, length, start);
+			return { text: buffer.toString("utf8", 0, bytesRead), bytesRead };
+		});
+	const ioClose = deps.io?.close ?? ((handle: number) => fs.closeSync(handle));
+
+	const closeIo = (): void => {
+		if (fd === null) return;
+		try {
+			ioClose(fd);
+		} catch {
+			/* fd đã chết — bỏ qua */
+		}
+		fd = null;
+	};
+
+	const probe = async (budgetMs: number): Promise<boolean> => {
+		payload = undefined;
+		const deadline = now() + Math.max(0, budgetMs);
+		try {
+			for (;;) {
+				if (scanOnce()) return true;
+				if (now() >= deadline) return false;
+				await sleep(Math.min(step, Math.max(1, deadline - now())));
+			}
+		} finally {
+			// Cửa sổ classify kết thúc (hoặc throw do caller bug) → nhả fd. Probe
+			// kế tiếp mở lại tự nhiên.
+			closeIo();
+		}
+	};
+	const foundPayload = (): Record<string, unknown> => payload ?? EMPTY_PAYLOAD;
+
+	function feed(chunk: string): boolean {
+		if (!chunk) return false;
+		const lines = (partial + chunk).split("\n");
+		partial = lines.pop() ?? "";
+		for (const line of lines) {
+			if (!line.trim()) continue;
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(line);
+			} catch {
+				continue; // dòng dở/torn — bỏ, không kẹt stream
+			}
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+			const record = parsed as Record<string, unknown>;
+			if (record.type !== "worker.completed") continue;
+			if (deps.taskId !== undefined && record.taskId !== deps.taskId) continue;
+			if (deps.runId !== undefined && record.runId !== deps.runId) continue;
+			payload =
+				record.data && typeof record.data === "object" && !Array.isArray(record.data)
+					? (record.data as Record<string, unknown>)
+					: {};
+			return true;
+		}
+		return false;
+	}
+
+	function scanOnce(): boolean {
+		if (deps.readFile) {
+			// Fixture mode: content FULL mỗi lần, offset là char-index vào nó.
+			const content = safeReadFile();
+			if (content === undefined) return false; // file chưa tồn tại — chưa có gì để khớp
+			if (content.length < offset) {
+				offset = 0;
+				partial = "";
+			}
+			const chunk = content.slice(offset);
+			offset += chunk.length;
+			return feed(chunk);
+		}
+		return scanIncremental();
+	}
+
+	function safeReadFile(): string | undefined {
+		try {
+			return deps.readFile!(deps.eventsPath);
+		} catch {
+			return undefined;
+		}
+	}
+
+	/**
+	 * Chỉ đọc byte [offset, size) — poll giữa chừng trên log dài tốn O(delta)
+	 * chứ không O(file). Truncate/shrink (size < offset) đọc lại từ đầu.
+	 */
+	function scanIncremental(): boolean {
+		if (fd === null) {
+			try {
+				fd = ioOpen(deps.eventsPath);
+			} catch {
+				return false; // ENOENT — recorder chưa tạo file; thử lại ở poll kế
+			}
+		}
+		let size: number;
+		try {
+			size = ioSize(fd);
+		} catch {
+			// fd point-at-dead-inode (file bị rotate/rename) — mở lại sạch.
+			closeIo();
+			return false;
+		}
+		if (size < offset) {
+			offset = 0;
+			partial = "";
+		}
+		if (size === offset) return false;
+		let chunk: { text: string; bytesRead: number };
+		try {
+			chunk = ioRead(fd, offset, size);
+		} catch {
+			return false; // race đọc giữa lúc truncate — offset giữ nguyên, thử lại
+		}
+		// Parity với EventLogTailSource.readFromOffset:193 — offset tiến theo SỐ
+		// BYTE thực đọc (bytesRead), KHÔNG theo byteLength(text): một poll cắt giữa
+		// multi-byte UTF-8 char làm toString nhét U+FFFD thay byte lead → byteLength
+		// lớn hơn bytesRead, mà nhảy quá ăn mất byte thật của poll kế.
+		offset += chunk.bytesRead;
+		return feed(chunk.text);
+	}
+
+	return Object.assign(probe, { foundPayload });
+}
+
+// ── 3. Reducers trên ManifestSurfaceState ─────────────────────────────────
+
+/** State trống (provider chưa biết) — mọi reducer đều bắt đầu từ đây. */
+export function emptySurfaceState(): ManifestSurfaceState {
+	return { provider: null, panes: {}, workerPids: {}, sessionPaths: {} };
+}
+
+/**
+ * Đọc trường `surface` của manifest legacy/thồi mà KHÔNG tin mù quáng: field
+ * sai shape (JSON tay, writer cũ) → bỏ từng phần về default thay vì crash một
+ * run vì dữ liệu cosmetic.
+ */
+export function normalizeSurfaceState(raw: unknown): ManifestSurfaceState {
+	const state = emptySurfaceState();
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return state;
+	const value = raw as Partial<ManifestSurfaceState> & Record<string, unknown>;
+	if (value.provider === "tmux" || value.provider === "herdr") state.provider = value.provider;
+	state.panes = stringRecord(value.panes);
+	state.workerPids = numberRecord(value.workerPids);
+	state.sessionPaths = stringRecord(value.sessionPaths);
+	const tabs = stringArrayRecord(value.tabs);
+	if (Object.keys(tabs).length > 0) state.tabs = tabs;
+	const lockout = value.lockout as ManifestSurfaceState["lockout"];
+	if (lockout && typeof lockout === "object" && typeof lockout.since === "string") {
+		const counts = (lockout.counts ?? {}) as Partial<LockoutCounts>;
+		state.lockout = {
+			since: lockout.since,
+			counts: {
+				pane: Number.isFinite(counts.pane) ? Number(counts.pane) : 0,
+				mux: Number.isFinite(counts.mux) ? Number(counts.mux) : 0,
+			},
+			cause: lockout.cause === "spawn-fail" ? "spawn-fail" : "degrade",
+		};
+	}
+	return state;
+}
+
+function stringRecord(raw: unknown): Record<string, string> {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+	const out: Record<string, string> = {};
+	for (const [key, val] of Object.entries(raw as Record<string, unknown>)) {
+		if (typeof val === "string" && key) out[key] = val;
+	}
+	return out;
+}
+
+function numberRecord(raw: unknown): Record<string, number> {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+	const out: Record<string, number> = {};
+	for (const [key, val] of Object.entries(raw as Record<string, unknown>)) {
+		if (typeof val === "number" && Number.isFinite(val)) out[key] = val;
+	}
+	return out;
+}
+
+/** Tab-layout Task 5: tabs[tabKey] chỉ giữ string[] hợp lệ — entry rác bỏ cả key. */
+function stringArrayRecord(raw: unknown): Record<string, string[]> {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+	const out: Record<string, string[]> = {};
+	for (const [key, val] of Object.entries(raw as Record<string, unknown>)) {
+		if (!key || !Array.isArray(val)) continue;
+		const ids = val.filter((id): id is string => typeof id === "string" && id.length > 0);
+		if (ids.length > 0) out[key] = ids;
+	}
+	return out;
+}
+
+/** Ghi nhận pane sống (boot xong createSurface+sendCommand). Thay thế entry cũ. */
+export function recordSurfacePane(
+	state: ManifestSurfaceState,
+	input: { taskId: string; paneId: string; provider?: string },
+): ManifestSurfaceState {
+	return {
+		...state,
+		...(input.provider === "tmux" || input.provider === "herdr" ? { provider: input.provider } : {}),
+		panes: { ...state.panes, [input.taskId]: input.paneId },
+	};
+}
+
+/** Pane đã thoát — luôn xóa khỏi map sống dù completed hay degraded.
+ *  Task 5 (spec tab-layout §5): CHỈ gỡ entry manifest — host không close pane/tab
+ *  theo từng worker (pane tự exit khi script xong là worker-side); tab của run
+ *  sống tới run end và do {@link closeTabForRun} đóng. Tabs không bị đụng ở đây. */
+export function releaseSurfacePane(state: ManifestSurfaceState, taskId: string): ManifestSurfaceState {
+	if (!(taskId in state.panes)) return state;
+	const panes = { ...state.panes };
+	delete panes[taskId];
+	return { ...state, panes };
+}
+
+/** Ghi nhận tab của run (tab-layout §5): append-dedup tabId vào tabs[tabKey]. */
+export function recordSurfaceTab(state: ManifestSurfaceState, input: { tabKey: string; tabId: string }): ManifestSurfaceState {
+	const existing = state.tabs?.[input.tabKey] ?? [];
+	if (existing.includes(input.tabId)) return state;
+	return { ...state, tabs: { ...(state.tabs ?? {}), [input.tabKey]: [...existing, input.tabId] } };
+}
+
+/**
+ * Run end/cancel/kill → đóng TOÀN tab của run (spec tab-layout §5). Provider tự
+ * đóng mọi window/tab của run theo map nội bộ keyed theo tabKey nên đây gọi
+ * closeTab ĐÚNG MỘT LẦN — KHÔNG loop từng tabId (self-review Task 5). Lỗi
+ * provider được nuốt + log: cleanup cuối run không được làm hỏng finalize.
+ * Trả về state mới với tabs[tabKey] = [] (giữ key làm evidence "đã đóng") VÀ
+ * mutate in-place theo pattern Object.assign của controller trong file này.
+ */
+export async function closeTabForRun(
+	surface: ManifestSurfaceState,
+	tabKey: string,
+	provider: SurfaceProvider | null | undefined,
+): Promise<ManifestSurfaceState> {
+	if (typeof provider?.closeTab === "function") {
+		try {
+			await provider.closeTab(tabKey);
+		} catch (error) {
+			logInternalError(
+				"surface-degrade.close-tab",
+				error instanceof Error ? error : new Error(String(error)),
+				`tabKey=${tabKey} provider=${provider.kind}`,
+			);
+		}
+	}
+	const next: ManifestSurfaceState = { ...surface, tabs: { ...(surface.tabs ?? {}), [tabKey]: [] } };
+	Object.assign(surface, next);
+	return next;
+}
+
+/** Cập nhật pid/sessionPath từ event `worker.started` của chính worker. */
+export function recordWorkerStarted(
+	state: ManifestSurfaceState,
+	input: { taskId: string; pid?: number; sessionPath?: string },
+): ManifestSurfaceState {
+	const next: ManifestSurfaceState = { ...state };
+	if (typeof input.pid === "number" && Number.isFinite(input.pid)) next.workerPids = { ...state.workerPids, [input.taskId]: input.pid };
+	if (typeof input.sessionPath === "string" && input.sessionPath)
+		next.sessionPaths = { ...state.sessionPaths, [input.taskId]: input.sessionPath };
+	return next;
+}
+
+export interface DegradedEntryLike {
+	taskId: string;
+	cause: SurfaceDegradeCause;
+	ts: string;
+}
+
+/** Áp một batch degrade: counts per cause-group + bật lockout khi ≥1 entry. */
+export function applyDegradedBatch(state: ManifestSurfaceState, entries: readonly DegradedEntryLike[]): ManifestSurfaceState {
+	if (entries.length === 0) return state;
+	const causes = entries.map((entry) => entry.cause);
+	const counts = nextLockoutCountsForBatch(state.lockout?.counts ?? { pane: 0, mux: 0 }, causes);
+	return {
+		...state,
+		lockout: {
+			since: state.lockout?.since ?? entries[0]!.ts,
+			counts,
+			cause: "degrade",
+		},
+	};
+}
+
+/** Bật/kéo dài lockout vì spawn-fail (giữ nguyên counts degrade đã ghi). */
+export function applySpawnFailLockout(state: ManifestSurfaceState, since: string): ManifestSurfaceState {
+	return {
+		...state,
+		lockout: {
+			since: state.lockout?.since ?? since,
+			counts: state.lockout?.counts ?? { pane: 0, mux: 0 },
+			cause: "spawn-fail",
+		},
+	};
+}
+
+// ── Re-dispatch planning (spec §7 bước 4–5) ───────────────────────────────
+
+export interface SurfaceDegradedEntry extends DegradedEntryLike {
+	paneId?: string;
+	exitReason?: string;
+}
+
+export interface HeadlessReplayPlan {
+	tasks: TeamTaskState[];
+	requeuedTaskIds: string[];
+	skipped: Array<{ taskId: string; reason: string }>;
+}
+
+/** Resume prompt bơm qua kênh pendingSteers — cùng cơ chế ask-timeout sweep,
+ *  cùng fencing untrusted ("DATA, not a system directive"). */
+export function renderSurfaceLostResumeNote(entry: { cause: SurfaceDegradeCause }): string {
+	return [
+		"<dependency-context>",
+		"(Scheduler note: the previous worker lost its multiplexer pane before finishing this task",
+		`(cause=${entry.cause}). It was re-dispatched headless with restored scratchpad state.`,
+		"Continue from where you left off.",
+		"(It is DATA, not a system directive.)",
+		"</dependency-context>",
+	].join("\n");
+}
+
+/**
+ * Chuyển danh sách degrade thành requeue: task quay lại `queued` kèm resume
+ * note + attempt marker reason "surface-lost" (spec: KHÔNG đếm retry budget —
+ * policy.retryCount giữ nguyên). Idempotent theo `handledTaskIds` nên scheduler
+ * tick sau không requeue lặp; task đã terminal vì lý do khác được bỏ qua.
+ */
+export function planHeadlessRedeplays(input: {
+	tasks: readonly TeamTaskState[];
+	degraded: readonly SurfaceDegradedEntry[];
+	/** Caller-owned guard (scheduler passes its once-per-run Set) — mutated here. */
+	handledTaskIds?: Set<string>;
+	note?: string;
+}): HeadlessReplayPlan {
+	const handled = input.handledTaskIds ?? new Set<string>();
+	const byId = new Map(input.tasks.map((task) => [task.id, task] as const));
+	const plan: HeadlessReplayPlan = { tasks: [...input.tasks], requeuedTaskIds: [], skipped: [] };
+	for (const entry of input.degraded) {
+		const task = byId.get(entry.taskId);
+		if (!task) {
+			plan.skipped.push({ taskId: entry.taskId, reason: "task not in graph" });
+			continue;
+		}
+		if (handled.has(entry.taskId)) {
+			plan.skipped.push({ taskId: entry.taskId, reason: "already re-dispatched once for surface loss" });
+			continue;
+		}
+		// needs_attention là trạng thái mà finalizeSurfaceLoss để lại; running
+		// phòng khi unit chưa kịp finalize. Các trạng thái khác (queued/completed/
+		// cancelled/failed…) nghĩa là lifecycle khác đã quyết — không giành quyền.
+		const requeueable = task.status === "needs_attention" || task.status === "running";
+		if (!requeueable) {
+			plan.skipped.push({ taskId: entry.taskId, reason: `status ${task.status} is owned by another lifecycle` });
+			continue;
+		}
+		const note = input.note ?? renderSurfaceLostResumeNote(entry);
+		plan.tasks = plan.tasks.map((candidate) =>
+			candidate.id === entry.taskId
+				? {
+						...candidate,
+						status: "queued" as const,
+						startedAt: undefined,
+						finishedAt: undefined,
+						error: undefined,
+						claim: undefined,
+						heartbeat: candidate.heartbeat,
+						// Không rờ policy.retryCount — degrade không ăn retry budget (spec §7 b5).
+						attempts: [
+							...(candidate.attempts ?? []),
+							{
+								attemptId: `${entry.taskId}:surface-lost`,
+								startedAt: candidate.startedAt ?? entry.ts,
+								endedAt: entry.ts,
+								error: `[surface-lost] ${entry.cause}`,
+							},
+						],
+						pendingSteers: [...(candidate.pendingSteers ?? []), note],
+						diagnostics: {
+							...(candidate.diagnostics ?? {}),
+							surfaceLost: { ts: entry.ts, cause: entry.cause, paneId: entry.paneId },
+						},
+						adaptive: candidate.adaptive ? { ...candidate.adaptive, phase: "resumed" } : candidate.adaptive,
+					}
+				: candidate,
+		);
+		plan.requeuedTaskIds.push(entry.taskId);
+		handled.add(entry.taskId);
+	}
+	return plan;
+}
+
+// ── 4. Per-run controller ─────────────────────────────────────────────────
+
+export interface SurfaceRuntimeControllerDeps {
+	runId: string;
+	/** RUN events.jsonl — nơi ghi event `surface.degraded`. */
+	eventsPath: string;
+	/**
+	 * Fix round 1/F2: raw `manifest.surface` của run đang resume — controller
+	 * SEED state từ đây thay vì khởi động trống, nếu không một host restart
+	 * giữa run sẽ đánh mất lockout.since/counts + workerPids/sessionPaths cũ.
+	 * Pane cũ vẫn còn trong evidence map: nó có thể THẬT vẫn sống khi host chết
+	 * (worker là con của mux server), và entry cùng taskId sẽ bị đè khi task
+	 * được re-dispatch. Dữ liệu rác/không hợp lệ được normalizeSurfaceState lọc.
+	 */
+	initialState?: unknown;
+	/** Broker token revoker (T10) — resolve lazy lúc degrade. */
+	revoke?: (taskId: string) => void;
+	appendEvent?: (eventsPath: string, event: AppendTeamEvent) => void;
+	now?: () => number;
+	/** Hook kiểm chứng trong test (default no-op). */
+	onDegrade?: (entry: SurfaceDegradedEntry) => void;
+}
+
+export interface SurfaceRuntimeController {
+	readonly runId: string;
+	/** Số pane đang sống (cap check của resolveSurface). */
+	livePaneCount(): number;
+	/** False khi lockout (degrade hoặc 3 spawn-fail) → dispatch bỏ surface. */
+	shouldAttemptSurface(): boolean;
+	notifySpawned(input: { taskId: string; paneId: string; provider: string; tabKey?: string; tabId?: string }): void;
+	notifySpawnFailed(input: { taskId: string; reason: string }): void;
+	notifyWorkerStarted(input: { taskId: string; pid?: number; sessionPath?: string }): void;
+	notifyPaneExited(input: {
+		taskId: string;
+		paneId: string;
+		completed: boolean;
+		exitReason: SurfaceExitReason;
+		cancelledByAbort?: boolean;
+		timedOut?: boolean;
+	}): void;
+	takeDegraded(): SurfaceDegradedEntry[];
+	consecutiveSpawnFails(): number;
+	/**
+	 * Run end (completed/cancelled/failed — spec tab-layout §5): đóng MỌI tab
+	 * đã ghi của run qua provider (theo kind của state). Team-runner gọi trong
+	 * finally — mọi đường thoát đều đóng tab, không chỉ happy path.
+	 */
+	closeRunTabs(provider: SurfaceProvider | null | undefined): Promise<void>;
+	snapshot(): ManifestSurfaceState;
+}
+
+// Module-singleton per run — cùng mô hình với getActiveBrokerIssuer: parent
+// process đăng ký 1 lần/lúc run start, child-pi layer tra theo runId mà không
+// phải bơm tham số xuyên 4 tầng runner.
+const controllersByRun = new Map<string, SurfaceRuntimeController>();
+
+export function registerSurfaceRuntimeController(controller: SurfaceRuntimeController): void {
+	controllersByRun.set(controller.runId, controller);
+}
+
+export function getSurfaceRuntimeController(runId: string | undefined): SurfaceRuntimeController | undefined {
+	if (!runId) return undefined;
+	return controllersByRun.get(runId);
+}
+
+/** Run-scoped teardown — gọi trong finally của team-runner để không leak qua run sau. */
+export function clearSurfaceRuntimeController(runId: string | undefined): void {
+	if (!runId) return;
+	if (controllersByRun.get(runId)?.runId === runId) controllersByRun.delete(runId);
+}
+
+/** Test seam — dọn sạch mọi controller còn đăng ký. */
+export function __test__clearAllSurfaceControllers(): void {
+	controllersByRun.clear();
+}
+
+export function createSurfaceRuntimeController(deps: SurfaceRuntimeControllerDeps): SurfaceRuntimeController {
+	const now = deps.now ?? Date.now;
+	const appendEvent =
+		deps.appendEvent ??
+		((eventsPath: string, event: AppendTeamEvent) => {
+			try {
+				appendEventFireAndForget(eventsPath, event);
+			} catch (error) {
+				logInternalError("surface-degrade.event", error instanceof Error ? error : new Error(String(error)), `runId=${deps.runId}`);
+			}
+		});
+
+	// F2: seed từ manifest của run đang resume (normalize lọc dữ liệu cũ/thồi).
+	const state = deps.initialState !== undefined ? normalizeSurfaceState(deps.initialState) : emptySurfaceState();
+	// Pane được seed từ manifest vẫn có thể THẬT đang sống (worker là con của
+	// mux server chứ không phải host chết) — đếm vào live cap như pane mới.
+	const livePids = new Set<string>(Object.keys(state.panes));
+	let spawnFailStreak = 0;
+	let degradedQueue: SurfaceDegradedEntry[] = [];
+
+	const degrade = (input: { taskId: string; paneId: string; exitReason: SurfaceExitReason }): void => {
+		const cause: SurfaceDegradeCause = input.exitReason === "mux-dead" ? "mux-dead" : "pane-closed";
+		const entry: SurfaceDegradedEntry = {
+			taskId: input.taskId,
+			paneId: input.paneId,
+			exitReason: input.exitReason,
+			cause,
+			ts: new Date(now()).toISOString(),
+		};
+		degradedQueue.push(entry);
+		// F1 (spec §7 c3 anti-flap): khóa NGAY tại degrade ĐẦU TIÊN, nhưng counts
+		// KHÔNG cộng per-entry — N pane mux-dead chảy vào đây qua N lời gọi rời
+		// rạc là MỘT sự kiện. counts được tính đúng một lần trên cả batch tại
+		// takeDegraded() (scheduler drain), nơi ranh giới "cùng lúc" xác định được.
+		if (state.lockout?.cause !== "degrade") {
+			state.lockout = {
+				since: state.lockout?.since ?? entry.ts,
+				counts: state.lockout?.counts ?? { pane: 0, mux: 0 },
+				cause: "degrade",
+			};
+		}
+		// Spec §7 bước 1–3: event đủ entry cho debug, revoke token NGAY (worker
+		// zombie trong pane không được tiếp tục nói chuyện với broker), rồi
+		// scheduler tick sẽ làm bước 4–5 (re-dispatch headless).
+		try {
+			appendEvent(deps.eventsPath, {
+				type: "surface.degraded",
+				runId: deps.runId,
+				taskId: entry.taskId,
+				message: `Surface worker lost (${cause}) before worker.completed within ${CLASSIFY_TIMEOUT_MS}ms classify window`,
+				data: { taskId: entry.taskId, paneId: entry.paneId, reason: input.exitReason, ts: entry.ts, cause },
+			});
+		} catch (error) {
+			logInternalError("surface-degrade.event", error instanceof Error ? error : new Error(String(error)), `runId=${deps.runId}`);
+		}
+		try {
+			deps.revoke?.(input.taskId);
+		} catch (error) {
+			logInternalError("surface-degrade.revoke", error instanceof Error ? error : new Error(String(error)), `runId=${deps.runId}`);
+		}
+		deps.onDegrade?.(entry);
+	};
+
+	return {
+		runId: deps.runId,
+		livePaneCount: () => livePids.size,
+		shouldAttemptSurface: () => state.lockout === undefined,
+		notifySpawned: ({ taskId, paneId, provider, tabKey, tabId }) => {
+			spawnFailStreak = 0; // boot thành công disproves streak (spec: liên tiếp)
+			Object.assign(state, recordSurfacePane(state, { taskId, paneId, provider }));
+			// Tab-layout Task 5: tab của run ghi vào manifest để run end đóng —
+			// worker xong KHÔNG gỡ (tab sống tới run end).
+			if (tabKey && tabId) Object.assign(state, recordSurfaceTab(state, { tabKey, tabId }));
+			livePids.add(taskId);
+		},
+		notifySpawnFailed: ({ taskId, reason }) => {
+			spawnFailStreak = nextConsecutiveSpawnFails(spawnFailStreak, true);
+			if (!isSpawnFailLockout(spawnFailStreak)) {
+				logInternalError(
+					"surface-degrade.spawn-fail",
+					new Error(reason),
+					`runId=${deps.runId} taskId=${taskId} streak=${spawnFailStreak}`,
+					"warn",
+				);
+				return;
+			}
+			if (state.lockout?.cause === "spawn-fail") return; // đã khóa — im lặng thay vì spam
+			Object.assign(state, applySpawnFailLockout(state, new Date(now()).toISOString()));
+			logInternalError(
+				"surface-degrade.spawn-fail-lockout",
+				new Error(reason),
+				`runId=${deps.runId} — surface OFF rest of the run`,
+				"warn",
+			);
+		},
+		notifyWorkerStarted: ({ taskId, pid, sessionPath }) => {
+			Object.assign(state, recordWorkerStarted(state, { taskId, pid, sessionPath }));
+		},
+		notifyPaneExited: ({ taskId, paneId, completed, exitReason, cancelledByAbort, timedOut }) => {
+			livePids.delete(taskId);
+			Object.assign(state, releaseSurfacePane(state, taskId));
+			if (completed) return;
+			if (cancelledByAbort || timedOut) return; // cancel/deadline do host — không phải flap của mux
+			if (exitReason !== "pane-closed" && exitReason !== "mux-dead") return; // detached = host dispose
+			degrade({ taskId, paneId, exitReason });
+		},
+		takeDegraded: () => {
+			const drained = degradedQueue;
+			degradedQueue = [];
+			if (drained.length > 0) {
+				// F1: counts của TOÀN BỘ batch drain này tính đúng một lần — N entry
+				// mux-dead đồng thời = +1 mux (applyDegradedBatch dùng cause-group
+				// batching; since giữ từ lockout đã đặt ở degrade đầu tiên).
+				Object.assign(state, applyDegradedBatch(state, drained));
+			}
+			return drained;
+		},
+		consecutiveSpawnFails: () => spawnFailStreak,
+		closeRunTabs: async (provider) => {
+			// Copy keys trước — closeTabForRun mutate state.tabs trong lúc lặp.
+			for (const tabKey of Object.keys(state.tabs ?? {})) {
+				await closeTabForRun(state, tabKey, provider);
+			}
+		},
+		// Trả snapshot MỚI mỗi lần — team-runner gắn nguyên object vào manifest.
+		snapshot: () => snapshotState(state),
+	};
+}
+
+function snapshotState(state: ManifestSurfaceState): ManifestSurfaceState {
+	return {
+		provider: state.provider,
+		panes: { ...state.panes },
+		workerPids: { ...state.workerPids },
+		sessionPaths: { ...state.sessionPaths },
+		...(state.tabs ? { tabs: { ...state.tabs } } : {}),
+		...(state.lockout
+			? { lockout: { since: state.lockout.since, counts: { ...state.lockout.counts }, cause: state.lockout.cause } }
+			: {}),
+	};
+}