pi-crew 0.10.2 → 0.10.3

package/src/runtime/task-runner/retrieval-orchestrator.ts

@@ -1,18 +1,17 @@
 /**
- * M3: Iterative file-retrieval orchestrator.
+ * M3: File-retrieval orchestrator.
  *
- * Pattern: workers progressively discover relevant context files
- * (e.g. "which source file handles X?") using ripgrep-driven keyword
- * search + the existing context-retrieval.ts scoring/convergence
- * helpers. Max 3 cycles, fall back to in-memory heuristic when
- * ripgrep is not available (e.g. minimal Windows CI runners).
+ * Pattern: workers discover relevant context files (e.g. "which
+ * source file handles X?") using ripgrep-driven keyword search + the
+ * existing context-retrieval.ts scoring/convergence helpers. Single
+ * discovery pass (perf round 3), fall back to in-memory heuristic
+ * when ripgrep is not available (e.g. minimal Windows CI runners).
  *
  * Signal flow:
  *   renderTaskPrompt (in prompt-builder.ts)
  *     → runRetrievalCycle(task, goal, cwd)
- *       → cycle 1: rg --files, then score each file
- *       → cycle 2: refine query, rg --json for keyword filter
- *       → cycle 3: same; if !shouldContinue, stop early
+ *       → single pass: rg --files, then score each file (deduped
+ *         by absolute path)
  *     → returns top-N files (5..10)
  *   renderTaskPrompt injects "Suggested files to read (top-N by
  *   retrieval score):" section before final prompt assembly.
@@ -24,10 +23,7 @@ import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import type { RelevanceEvaluation } from "./context-retrieval.ts";
-import { hasConverged, scoreRelevance, shouldContinue } from "./context-retrieval.ts";
-
-/** Max retrieval cycles per prompt render. Matches context-retrieval.MAX_CYCLES. */
-export const MAX_CYCLES = 3;
+import { hasConverged, scoreRelevance } from "./context-retrieval.ts";
 
 /** Hard cap on suggested files injected into the worker prompt. */
 export const MAX_SUGGESTED_FILES = 10;
@@ -36,7 +32,104 @@ export const MAX_SUGGESTED_FILES = 10;
 export const MIN_SUGGESTED_FILES = 5;
 
 /** Stopwords dropped during keyword tokenization (lowercase comparison). */
-const STOPWORDS: ReadonlySet<string> = new Set(["the", "a", "an", "and", "or", "to", "of", "in", "for", "on", "is", "are", "be", "with"]);
+// PERF round 3: expanded from 14 function words to the common verb/pronoun/
+// filler set. These multiply the scoring cost (keywords × files × passes)
+// and essentially never appear in code file paths. Deliberately KEPT OUT:
+// domain words that DO match paths — test, cache, prompt, tool, spec,
+// artifact names like "smoke" — check the keep-assertions in R3-3 before adding.
+const STOPWORDS: ReadonlySet<string> = new Set([
+	"the",
+	"a",
+	"an",
+	"and",
+	"or",
+	"to",
+	"of",
+	"in",
+	"for",
+	"on",
+	"is",
+	"are",
+	"be",
+	"with",
+	"this",
+	"that",
+	"these",
+	"those",
+	"then",
+	"than",
+	"so",
+	"if",
+	"but",
+	"not",
+	"no",
+	"yes",
+	"it",
+	"its",
+	"they",
+	"them",
+	"their",
+	"we",
+	"you",
+	"your",
+	"us",
+	"our",
+	"i",
+	"was",
+	"were",
+	"been",
+	"has",
+	"have",
+	"had",
+	"will",
+	"would",
+	"can",
+	"could",
+	"should",
+	"may",
+	"might",
+	"must",
+	"shall",
+	"do",
+	"does",
+	"did",
+	"done",
+	"find",
+	"found",
+	"look",
+	"run", // 'run' — generic verb, false-positives every *runner* path (see R3-3)
+	"likely",
+	"please",
+	"just",
+	"only",
+	"also",
+	"into",
+	"from",
+	"when",
+	"what",
+	"which",
+	"where",
+	"how",
+	"all",
+	"any",
+	"some",
+	"there",
+	"here",
+	"report",
+	"reports",
+	"exact",
+	"once",
+	"twice",
+	"things",
+	"thing",
+	"stuff",
+	"make",
+	"makes",
+	"made",
+	"use",
+	"using",
+	"used",
+]);
 
 /** File extensions considered relevant for retrieval. */
 const RELEVANT_EXTS: ReadonlySet<string> = new Set([
@@ -68,6 +161,37 @@ interface RipgrepAvailable {
 
 let cachedRgCheck: RipgrepAvailable | undefined;
 
+/**
+ * PERF round 3: per-cwd cache of the rg discovery result (relative paths,
+ * post RELEVANT_EXTS filter). Tasks in one run share the cwd but differ in
+ * step.task keywords, so the stableIOCache in prompt-builder.ts misses per
+ * task — this cache keeps the expensive part (rg spawn + 77k-line parse)
+ * at once per cwd per minute instead of once per task. Fallback walk is
+ * NOT cached (its result depends on keywords). Size-capped, insertion-
+ * order eviction, same TTL family as stableIOCache (60s).
+ */
+const DISCOVERED_TTL_MS = 60_000;
+const DISCOVERED_CACHE_MAX = 32;
+const discoveredCache = new Map<string, { files: string[]; at: number }>();
+
+function getCachedDiscovered(cwd: string): string[] | undefined {
+	const hit = discoveredCache.get(cwd);
+	if (hit && Date.now() - hit.at < DISCOVERED_TTL_MS) {
+		// shared cached array — treat as read-only
+		return hit.files;
+	}
+	return undefined;
+}
+
+function storeDiscovered(cwd: string, files: string[]): void {
+	discoveredCache.set(cwd, { files, at: Date.now() });
+	while (discoveredCache.size > DISCOVERED_CACHE_MAX) {
+		const oldest = discoveredCache.keys().next().value;
+		if (oldest === undefined) break;
+		discoveredCache.delete(oldest);
+	}
+}
+
 /**
  * Detect ripgrep availability once per process. Uses `rg --version` and
  * catches ENOENT or non-zero exit. Cached so the cost (one spawn) is
@@ -113,6 +237,11 @@ export function __test_resetRipgrepCache(): void {
 	cachedRgCheck = undefined;
 }
 
+/** @internal Test-only: reset the discovery cache. */
+export function __test_resetDiscoveredCache(): void {
+	discoveredCache.clear();
+}
+
 /**
  * Tokenize a task + goal string into lowercase keywords, dropping
  * stopwords. Single-letter tokens and pure-punctuation tokens are
@@ -272,9 +401,9 @@ async function walkFilesFallback(cwd: string, keywords: string[]): Promise<Array
 }
 
 /**
- * Iterate up to MAX_CYCLES times. Each cycle: discover files, score
- * them, check convergence. Stop early on convergence or when
- * shouldContinue returns false.
+ * Single discovery pass (perf round 3): discover files once, score
+ * them path-only, dedupe by absolute path, check convergence on the
+ * deduped evaluation set.
  */
 export async function runRetrievalCycle(task: string, goal: string, cwd: string): Promise<RetrievalResult> {
 	const keywords = tokenizeQuery(task, goal);
@@ -284,55 +413,61 @@ export async function runRetrievalCycle(task: string, goal: string, cwd: string)
 	const rg = await detectRipgrep();
 	const useRg = rg.available;
 	let usedFallback = !useRg;
-	const evaluations: RelevanceEvaluation[] = [];
-	let cycle = 0;
-	let converged = false;
-	for (; cycle < MAX_CYCLES; cycle++) {
-		let discovered: string[] = [];
-		try {
-			if (useRg) {
-				// Cycle 0: enumerate all relevant files via `rg --files`.
-				// Later cycles: filter by keywords via `rg --files | rg pattern`.
-				// We use the simpler `rg --files` + filter strategy because
-				// `rg --json` parsing adds complexity for marginal gain.
-				// `rg --files` respects .gitignore by default; we add an
-				// explicit -g '!node_modules' and -g '!.git' to be safe on
-				// repos that don't ignore them.
+	// PERF round 3 (2026-08-26): single discovery pass. The previous loop ran
+	// up to MAX_CYCLES=3 iterations, but each iteration re-ran `rg --files`
+	// (identical output ~0.36s/spawn on my_pi) and re-scored the identical
+	// ~57k-file set: path-only scoring (content always "") cannot reach
+	// HIGH_RELEVANCE_THRESHOLD=0.7 (observed max 0.64), so hasConverged was
+	// always false and the loop ran unconditionally — 3× CPU for a zero
+	// result delta (measured 7055ms → 1980ms cold on the my_pi monorepo,
+	// full-length real-run goal — see docs/real-test/reports/perf-round3-probe.md).
+	let discovered: string[] = [];
+	try {
+		if (useRg) {
+			const cached = getCachedDiscovered(cwd);
+			if (cached) {
+				discovered = cached;
+			} else {
+				// `rg --files` respects .gitignore by default; explicit -g guards
+				// repos that don't ignore them (comment moved from the loop body).
 				const stdout = await runRipgrep(["--files", "-g", "!node_modules", "-g", "!.git", cwd], cwd);
 				discovered = stdout
 					.split("\n")
 					.map((p) => p.trim())
 					.filter((p) => p && RELEVANT_EXTS.has(path.extname(p).toLowerCase()))
 					.map((p) => path.relative(cwd, p));
-			} else {
-				discovered = (await walkFilesFallback(cwd, keywords)).map((f) => f.path);
+				storeDiscovered(cwd, discovered);
 			}
-		} catch {
-			// rg errored mid-run — switch to fallback for this cycle.
-			usedFallback = true;
+		} else {
 			discovered = (await walkFilesFallback(cwd, keywords)).map((f) => f.path);
 		}
-		// Score each discovered file. Path-only scoring (no file read) so
-		// we don't slow down prompt building for hundreds of files.
-		const seenInThisCycle = new Set<string>();
-		for (const relPath of discovered) {
-			if (seenInThisCycle.has(relPath)) continue;
-			seenInThisCycle.add(relPath);
-			const absPath = path.isAbsolute(relPath) ? relPath : path.join(cwd, relPath);
-			const score = scoreRelevance(absPath, "", keywords);
-			if (score > 0) {
-				evaluations.push({
-					path: absPath,
-					relevance: score,
-					reason: reasonFor(absPath, keywords),
-					missingContext: [],
-				});
-			}
+	} catch {
+		// rg errored mid-run — switch to fallback for this pass.
+		usedFallback = true;
+		discovered = (await walkFilesFallback(cwd, keywords)).map((f) => f.path);
+	}
+	// Score each discovered file. Path-only scoring (no file read) so
+	// we don't slow down prompt building for hundreds of files.
+	// PERF round 3: dedupe by ABSOLUTE path — the multi-cycle accumulation
+	// previously pushed the same evaluation once per cycle, so the top-10
+	// could contain the same file up to 3 times (observed on
+	// team_20260826002634: task-output-context-dep-cache.test.ts ×3).
+	const byPath = new Map<string, RelevanceEvaluation>();
+	for (const relPath of discovered) {
+		const absPath = path.isAbsolute(relPath) ? relPath : path.join(cwd, relPath);
+		if (byPath.has(absPath)) continue;
+		const score = scoreRelevance(absPath, "", keywords);
+		if (score > 0) {
+			byPath.set(absPath, {
+				path: absPath,
+				relevance: score,
+				reason: reasonFor(absPath, keywords),
+				missingContext: [],
+			});
 		}
-		converged = hasConverged(evaluations);
-		if (converged) break;
-		if (!shouldContinue(evaluations, cycle)) break;
 	}
+	const evaluations = [...byPath.values()];
+	const converged = hasConverged(evaluations);
 	// Sort by score desc, take top N (5..10).
 	evaluations.sort((a, b) => b.relevance - a.relevance);
 	const cap = Math.min(MAX_SUGGESTED_FILES, Math.max(MIN_SUGGESTED_FILES, evaluations.length));
@@ -341,7 +476,7 @@ export async function runRetrievalCycle(task: string, goal: string, cwd: string)
 		score: e.relevance,
 		reason: e.reason,
 	}));
-	return { files: top, cycles: cycle, converged, usedFallback };
+	return { files: top, cycles: 1, converged, usedFallback };
 }
 
 /**

package/src/runtime/task-runner/state-helpers.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { loadConfig } from "../../config/config.ts";
 import { flushPendingAtomicWrites } from "../../state/atomic-write.ts";
 import { withRunLockSync } from "../../state/coordination/locks.ts";
 import { loadRunManifestById, saveRunTasksCoalesced } from "../../state/stores/state-store.ts";
@@ -30,7 +31,11 @@ export function updateTask(tasks: TeamTaskState[], updated: TeamTaskState): Team
  * SIGKILL in that window loses the terminal update and crash recovery
  * would see "running" in tasks.json while events.jsonl already shows
  * "completed". For non-terminal transitions (heartbeat, progress) the
- * default buffered write is fine and matches prior behavior.
+ * default buffered write is fine and matches prior behavior. With the
+ * opt-in `persistence.skipTasksFsync` flag (default off), non-terminal
+ * checkpoints stay in the 50ms coalesce window but drop ONLY the fsync
+ * (durability "best-effort") — tasks.json is reconstructible from the
+ * fsync'd event log, so a crash loses at most the un-flushed tail.
  *
  * @param checkpointPhase - Optional checkpoint phase to include in the task state alongside the update.
  */
@@ -41,22 +46,16 @@ export function persistSingleTaskUpdate(
 	checkpointPhase?: TaskCheckpointState["phase"],
 	skipCoalesce: boolean = false,
 ): TeamTaskState[] {
-	// H5 (2026-08-10): lowered from 100 → 10. Each retry does
-	// flushPendingAtomicWrites (global) + loadRunManifestById (stat + parse)
-	// + statSync, ~5ms each. Every attempt now loads from disk (BUG-028);
-	// retries only fire under real contention from best-effort writers that
-	// don't hold the run lock (async-notifier, crash-recovery). If 10 retries
-	// cannot converge, the system is in a pathological state where 100 would
-	// not help either — the explicit error below surfaces it instead of
-	// blocking the event loop for 500ms.
+	// H5 (2026-08-10): lowered from 100 → 10. Each retry does a scoped
+	// flushPendingAtomicWrites(tasksPath) + loadRunManifestById (stat + parse;
+	// the manifest half is typically served from the manifest cache after the
+	// Task 12 reuse) + statSync, ~5ms each. Every attempt now loads from disk
+	// (BUG-028); retries only fire under real contention from best-effort
+	// writers that don't hold the run lock (async-notifier, crash-recovery).
+	// If 10 retries cannot converge, the system is in a pathological state
+	// where 100 would not help either — the explicit error below surfaces it
+	// instead of blocking the event loop for 500ms.
 	const MAX_CAS_ATTEMPTS = 10;
-	let baseMtime = 0;
-	try {
-		baseMtime = fs.statSync(manifest.tasksPath).mtimeMs;
-	} catch {
-		// File doesn't exist yet — baseMtime=0 means "anything is fine"
-		baseMtime = 0;
-	}
 
 	let merged: TeamTaskState[] | undefined;
 
@@ -74,15 +73,25 @@ export function persistSingleTaskUpdate(
 	try {
 		return withRunLockSync(manifest, () => {
 			for (let attempt = 0; attempt < MAX_CAS_ATTEMPTS; attempt++) {
-				// F4: persistSingleTaskUpdate now uses saveRunTasksCoalesced below
-				// (50ms debounce window). Read-modify-write loops are unsafe under
-				// coalescing — a parallel writer's buffered write is invisible to
-				// loadRunManifestById until it actually lands. Force any pending
-				// coalesced writes to flush first so this read sees the latest
-				// durable state. Without this guard, a parallel writer could
-				// overwrite our buffered write between our load and our (async)
-				// fsync, silently losing the intermediate update.
-				flushPendingAtomicWrites();
+				// PERF (2026-08-24): scoped flush — only force OUR tasks.json pending
+				// write to land. The old argument-less call drained every pending
+				// coalesced write process-wide (other runs, agents.json 250ms window)
+				// on every persist (~30x/s), defeating coalescing globally. The F4
+				// invariant only needs tasks.json durable before this read.
+				flushPendingAtomicWrites(manifest.tasksPath);
+				// PERF (2026-08-24): capture the CAS baseline INSIDE the lock, after
+				// the flush, immediately before the load. The old pre-lock stat almost
+				// always disagreed with the in-lock stat under 10 parallel writers
+				// (mtime moved between function entry and lock acquisition), forcing
+				// 2+ full flush+load cycles per call. In-lock capture makes retry mean
+				// exactly: "a cross-process writer committed between our load and our
+				// pre-write stat" — the only race the CAS can actually catch.
+				let baseMtime: number;
+				try {
+					baseMtime = fs.statSync(manifest.tasksPath).mtimeMs;
+				} catch {
+					baseMtime = 0;
+				}
 				// BUG-028 (2026-08-16): ALWAYS load the committed tasks from disk
 				// inside the lock — never trust fallbackTasks on attempt 0. The
 				// old F4 perf shortcut assumed "the caller already obtained the
@@ -95,8 +104,9 @@ export function persistSingleTaskUpdate(
 				// (siblings still "running") over disk where siblings were already
 				// terminal — resurrecting them and blocking finalize ("task is
 				// still running"). The mtime CAS below cannot catch this: it only
-				// detects writers between the entry stat and the in-lock stat,
-				// i.e. staleness acquired AFTER function entry — not fallback
+				// detects writers between the in-lock baseline stat (captured
+				// after the flush, immediately before the load) and the pre-write
+				// stat, i.e. staleness acquired AFTER that baseline — not fallback
 				// staleness that predates it. Loading disk here makes sibling
 				// state authoritative (matching mergeUnitResult / bug-027 policy)
 				// while `updated` still wins for THIS task via updateTask.
@@ -121,8 +131,8 @@ export function persistSingleTaskUpdate(
 				}
 
 				if (currentMtime !== baseMtime) {
-					// Another writer committed — their update is in latest, re-merge on top
-					baseMtime = currentMtime;
+					// Another writer committed between our in-lock baseline and this
+					// stat — retry; the next iteration recaptures the baseline fresh.
 					continue;
 				}
 
@@ -148,7 +158,21 @@ export function persistSingleTaskUpdate(
 				// ST-7: terminal transitions (skipCoalesce=true) bypass the 50ms
 				// coalesce window so a SIGKILL after the persist completes cannot
 				// leave tasks.json stale with a non-terminal status.
-				saveRunTasksCoalesced(manifest, merged, skipCoalesce);
+				// PERF round 2, Task 3 (opt-in, default off): for NON-terminal
+				// checkpoints — and ONLY when persistence.skipTasksFsync is true —
+				// KEEP the 50ms coalesce window (the RMW grouping benefit) and drop
+				// ONLY durability: the coalesced entry stores "best-effort" and the
+				// flush forwards it to atomicWriteFile (no data/parent-dir fsync).
+				// tasks.json is reconstructible from the fsync'd event log, so the
+				// crash tail is at most the in-flight checkpoint. Terminal
+				// transitions (skipCoalesce=true) always stay full-durability — the
+				// flag never touches that path.
+				const skipTasksFsync = !skipCoalesce && loadConfig().config.persistence?.skipTasksFsync === true;
+				if (skipTasksFsync) {
+					saveRunTasksCoalesced(manifest, merged, false, "best-effort");
+				} else {
+					saveRunTasksCoalesced(manifest, merged, skipCoalesce);
+				}
 			} catch (err) {
 				logInternalError("persistSingleTaskUpdate", err, undefined, "error");
 				throw err;

package/src/runtime/task-runner.ts

@@ -118,7 +118,9 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 		const skillArtifact = ctx.skillArtifact;
 		const coordinationArtifact = ctx.coordinationArtifact;
 
-		let resultArtifact: ArtifactDescriptor;
+		// MuxSurface degrade path returns NO result artifact — undefined until a
+		// branch produces one (finalizeTaskResult's surfaceLost branch ignores it).
+		let resultArtifact: ArtifactDescriptor | undefined;
 		let logArtifact: ArtifactDescriptor | undefined;
 		let transcriptArtifact: ArtifactDescriptor | undefined;
 		let exitCode: number | null = 0;
@@ -138,7 +140,7 @@ export async function runTeamTask(input: TaskRunnerInput): Promise<{ manifest: T
 			const child = await runChildProcessTask(ctx);
 			task = ctx.task;
 			tasks = ctx.tasks;
-			resultArtifact = child.resultArtifact;
+			resultArtifact = child.resultArtifact ?? resultArtifact;
 			logArtifact = child.logArtifact;
 			transcriptArtifact = child.transcriptArtifact;
 			exitCode = child.exitCode;

package/src/runtime/team-runner.ts

@@ -258,7 +258,22 @@ export {
 // Re-export the test-only helpers so existing test imports still resolve.
 export { __test__mergeTaskUpdates, __test__shouldMergeTaskUpdate } from "./merge-gate.ts";
 
+import { getActiveBrokerRevoker } from "./broker/broker-issuer.ts";
 import { injectAdaptivePlanIfReady, isAdaptiveWorkflow } from "./goal-workflow/adaptive-plan.ts";
+// MuxSurface A1 (spec §7 D3 + §8.3): run-scoped surface-degrade controller —
+// child-pi layer notifies spawn/exit/degrade through the registry keyed by
+// runId; this runner owns policy (lockout), persistence (manifest.surface) and
+// the headless re-dispatch of degraded units.
+import {
+	clearSurfaceRuntimeController,
+	createSurfaceRuntimeController,
+	normalizeSurfaceState,
+	planHeadlessRedeplays,
+	registerSurfaceRuntimeController,
+} from "./surface/degrade.ts";
+// Task 5 (tab-layout §5): run end đóng toàn tab của run qua provider singleton
+// cùng instance mà spawn đã dùng (map tab nội bộ sống trong provider).
+import { surfaceProviderForCleanup } from "./surface/resolve-surface.ts";
 
 // formatTaskProgress / runEffectivenessLines / scratchpadSummaryLines /
 // lastProgressContentHash / writeProgress moved to ./finalize-run.ts (2026-08
@@ -862,6 +877,32 @@ async function executeTeamRunCore(
 	// task-output-context.ts.
 	const resultReadCache = createResultArtifactReadCache();
 
+	// ── MuxSurface A1 (spec §7 D3): per-run degrade controller ─────────────
+	// Owned here because only this runner may mutate manifest/tasks/events; the
+	// child-pi surface branch reaches it through the registry keyed by runId.
+	// Broker token revocation resolves lazily AT degrade time (the broker can
+	// start mid-run on the first credential request).
+	const surfaceController = createSurfaceRuntimeController({
+		runId: manifest.runId,
+		eventsPath: manifest.eventsPath,
+		// F2 (fix round 1): resume sau host restart phải kế thừa lockout +
+		// workerPids/sessionPaths/panes đã ghi trên manifest, nếu không evidence
+		// của nửa đầu run bị mất khi controller mới khởi động trống.
+		initialState: manifest.surface,
+		revoke: (taskId) => getActiveBrokerRevoker()?.(taskId),
+	});
+	registerSurfaceRuntimeController(surfaceController);
+	// Re-dispatch-once guard: a degraded task is replayed headless exactly once
+	// per run — repeated loss lands in needs_attention for a human instead of a
+	// mux-flap respawn loop (spec §7 anti-flap).
+	const surfaceLossHandled = new Set<string>();
+	// Pure merge of the controller snapshot onto ANY manifest view (callers pass
+	// either the closure local or ctx.manifest so the freshest state wins).
+	const attachSurfaceSnapshot = (target: TeamRunManifest): TeamRunManifest => ({
+		...target,
+		surface: normalizeSurfaceState(surfaceController.snapshot()),
+	});
+
 	// CORE-4: scheduler context — mutable state bag for extracted scheduler
 	// functions. Fields are synced from closure locals at the top of each
 	// loop iteration; extracted functions mutate ctx in-place.
@@ -984,6 +1025,33 @@ async function executeTeamRunCore(
 			// (cancel-during-exec check + batch summary artifact).
 			const { taskIds: settledTaskIds, result: resultToMerge } = ctx.settledMerge!;
 
+			// ── MuxSurface A1 (spec §7 steps 4–5): drain degrades → re-dispatch
+			// headless. Runs BEFORE phase advance so a degraded task is `queued`
+			// again while the scheduler still sees this tick's state, and before
+			// handleFailedTask can ever observe needs_attention leftovers.
+			const surfaceDegraded = surfaceController.takeDegraded();
+			if (surfaceDegraded.length > 0) {
+				const replay = planHeadlessRedeplays({
+					tasks: ctx.tasks,
+					degraded: surfaceDegraded,
+					handledTaskIds: surfaceLossHandled,
+				});
+				ctx.tasks = replay.tasks;
+				tasks = ctx.tasks;
+				if (replay.requeuedTaskIds.length > 0) {
+					await appendEventAsync(manifest.eventsPath, {
+						type: "surface.requeued",
+						runId: manifest.runId,
+						message: `Re-dispatched ${replay.requeuedTaskIds.length} surface-degraded task(s) headless: ${replay.requeuedTaskIds.join(", ")}`,
+						data: {
+							taskIds: replay.requeuedTaskIds,
+							skipped: replay.skipped,
+							resumeComponents: ["rendered-prompt", "scratchpad-restore", "pendingSteers-replay", "resume-note"],
+						},
+					});
+				}
+			}
+
 			// CORE-4 extraction 6: workflow phase advance. ctx.wfMachine is
 			// already synced from the top-of-loop sync (RT-15);
 			// advanceWorkflowPhases advances phases whose tasks are all terminal,
@@ -1089,6 +1157,11 @@ async function executeTeamRunCore(
 					...(groupDelivery?.artifact ? [groupDelivery.artifact] : []),
 				]),
 			};
+			// MuxSurface A1 (§8.3): persist the run-scoped pane/pid/lockout snapshot
+			// with the batch manifest write — panes recorded this tick become
+			// visible to doctor/zombie-sweep and a crash mid-run leaves at most
+			// one tick of stale pane records.
+			manifest = attachSurfaceSnapshot(manifest);
 			manifest = writeProgress(manifest, tasks, "team-runner", input.executeWorkers, input.runtimeConfig);
 			await saveRunManifestAsync(manifest);
 		}
@@ -1098,11 +1171,39 @@ async function executeTeamRunCore(
 		// + health snapshot, performs the joint atomic manifest+tasks save, and
 		// returns the terminal { manifest, tasks } result. Sync the locals back
 		// from ctx so the finally block observes consistent state.
+		// Last degrade drain: a pane that died during the closeout still gets its
+		// headless replay attempt if any scheduler work remains, else it stays
+		// needs_attention for resume — never silently dropped from the manifest.
+		const finalDegraded = surfaceController.takeDegraded();
+		if (finalDegraded.length > 0) {
+			const finalReplay = planHeadlessRedeplays({
+				tasks: ctx.tasks,
+				degraded: finalDegraded,
+				handledTaskIds: surfaceLossHandled,
+			});
+			ctx.tasks = finalReplay.tasks;
+		}
+		ctx.manifest = attachSurfaceSnapshot(ctx.manifest);
 		const finalResult = await finalizeRun(ctx);
 		manifest = ctx.manifest;
 		tasks = ctx.tasks;
 		return finalResult;
 	} finally {
+		// Task 5 (tab-layout §5): tab chỉ đóng khi RUN END — mọi đường thoát
+		// (completed/failed/cancelled/throw) đều đóng toàn tab của run qua
+		// provider singleton cùng instance mà spawn đã dùng. Best-effort: lỗi đã
+		// được log bên trong closeTabForRun, teardown không được sập vì mux chết.
+		const surfaceProviderKind = surfaceController.snapshot().provider;
+		if (surfaceProviderKind) {
+			try {
+				await surfaceController.closeRunTabs(surfaceProviderForCleanup(surfaceProviderKind));
+			} catch (error) {
+				logInternalError("team-runner.close-run-tabs", error, `runId=${manifest.runId}`);
+			}
+		}
+		// MuxSurface A1: drop the run's registry entry FIRST — no in-flight
+		// notify after teardown may resurrect policy state into the next run.
+		clearSurfaceRuntimeController(manifest.runId);
 		// #3: drainPendingUnits returns settled outcomes, but the finally block
 		// only needs the drain side-effect (abort + await + clear); the return
 		// value is intentionally unused here.

package/src/schema/config-schema.ts

@@ -95,6 +95,19 @@ export const PiTeamsRuntimeConfigSchema = Type.Object(
 		),
 		excludeContextBash: Type.Optional(Type.Boolean()),
 		agentExtensions: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { sensitive: true })),
+		// Mux-surface policy (spec v0.7 §8.2.4): no sensitive marks — surface
+		// picks where worker processes live, not what they may do.
+		surface: Type.Optional(
+			Type.Object(
+				{
+					mode: Type.Optional(
+						Type.Union([Type.Literal("auto"), Type.Literal("tmux"), Type.Literal("herdr"), Type.Literal("off")]),
+					),
+					visibleAgents: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+				},
+				{ additionalProperties: false },
+			),
+		),
 		isolationPolicy: Type.Optional(
 			Type.Object(
 				{
@@ -341,6 +354,16 @@ export const PiTeamsNestingConfigSchema = Type.Object(
 	{ additionalProperties: false },
 );
 
+/** State-layer persistence schema (perf round 2, Task 3). Opt-in only.
+ *  Does affect write cost, but never correctness: tasks.json is
+ *  reconstructible from the fsync'd event log, so no privilege surface. */
+export const PiTeamsPersistenceConfigSchema = Type.Object(
+	{
+		skipTasksFsync: Type.Optional(Type.Boolean()),
+	},
+	{ additionalProperties: false },
+);
+
 export const PiTeamsConfigSchema = Type.Object(
 	{
 		asyncByDefault: Type.Optional(Type.Boolean({ sensitive: true })),
@@ -365,6 +388,7 @@ export const PiTeamsConfigSchema = Type.Object(
 		ui: Type.Optional(PiTeamsUiConfigSchema),
 		broker: Type.Optional(CrewBrokerConfigSchema),
 		nesting: Type.Optional(PiTeamsNestingConfigSchema),
+		persistence: Type.Optional(PiTeamsPersistenceConfigSchema),
 	},
 	{ additionalProperties: false },
 );