pi-crew 0.10.2 → 0.10.3

package/src/runtime/surface/launch-script.ts

@@ -0,0 +1,172 @@
+/**
+ * launch-script builder — boot script cho tier-1 surface worker (spec §5.2)
+ *
+ * Host không thể spawn TUI worker bằng argv (Pi từ chối flag lạ và `--mode
+ * json -p` là chế độ headless), nên pane chạy `bash <script>`: script export
+ * đầy đủ env worker, cd vào cwd, chạy dòng lệnh pi TUI, rồi tự xóa bằng
+ * `rm -f -- "$0"`. Script là file one-shot tuổi thọ vài giây — TTL registry
+ * dọn script mồ côi (worker chưa kịp chạy đã chết) sau 60s.
+ *
+ * Depth guard lớp 2: builder throw khi NGƯỜI GỌI đang lồng (callerEnv có
+ * PI_CREW_DEPTH > 0; không truyền callerEnv thì fallback đọc env input —
+ * hành vi cũ). Lớp 1 là resolveSurface trả null (spec §3) — lớp 2 bảo vệ
+ * đường gọi trực tiếp builder mà bỏ qua resolveSurface.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { atomicWriteFile } from "../../state/atomic-write.ts";
+import { currentCrewDepth } from "../model/pi-args.ts";
+
+/**
+ * Thrown khi buildLaunchScript nhận env có PI_CREW_DEPTH > 0 — surface panes
+ * là tier-1 only, không pane-in-pane (spec §3/§5.2).
+ */
+export class SurfaceDepthGuardError extends Error {
+	constructor(depth: number) {
+		super(`Refusing to build surface launch script at PI_CREW_DEPTH=${depth}: surface panes are tier-1 only`);
+		this.name = "SurfaceDepthGuardError";
+	}
+}
+
+/** Thrown khi taskId dùng để đặt tên file script không an toàn cho path. */
+export class SurfaceTaskIdError extends Error {
+	constructor(taskId: string) {
+		super(`Refusing to build surface launch script: unsafe taskId ${JSON.stringify(taskId)} — must not contain "/", "\\", NUL or ".."`);
+		this.name = "SurfaceTaskIdError";
+	}
+}
+
+/**
+ * taskId được nối thẳng vào tên file (`pi-crew-launch-{taskId}-{pid}.sh`) —
+ * `/`, `\`, NUL hay `..` trong đó là path traversal ghi file ra ngoài baseDir.
+ * Follow-up bắt buộc từ review Task 5.
+ */
+function assertSafeTaskId(taskId: string): void {
+	if (!taskId || taskId.includes("/") || taskId.includes("\\") || taskId.includes("\0") || taskId.includes("..")) {
+		throw new SurfaceTaskIdError(taskId);
+	}
+}
+
+export interface BuildLaunchScriptInput {
+	taskId: string;
+	/** Env worker cần có trong pane (broker, steering, surface, parent-guard). */
+	env: Record<string, string>;
+	/** Dòng lệnh pi TUI (đã build, không `--mode json -p`). */
+	command: string;
+	/** Working directory của worker (được cd với shell-escape). */
+	cwd: string;
+	/** Thư mục chứa script — dùng getPiTempBase() từ pi-args.ts. */
+	baseDir: string;
+	/**
+	 * Env của NGƯỜI GỌI builder — nguồn duy nhất cho depth guard lớp 2. Khi
+	 * được truyền, guard KHÔNG còn đọc env export nữa vì script worker hợp lệ
+	 * mang PI_CREW_DEPTH=<caller+1> (parity với spawn headless — child-pi-spawn
+	 * luôn set depth con = cha + 1); chỉ người GỌI lồng mới bị chặn.
+	 * Không truyền → hành vi cũ (đọc env input) giữ nguyên cho caller đã có.
+	 */
+	callerEnv?: NodeJS.ProcessEnv;
+}
+
+/** TTL cho launch script (spec §5.2): sweep xóa script cũ hơn 60s. */
+export const LAUNCH_SCRIPT_TTL_MS = 60_000;
+
+/**
+ * Module-level TTL registry — path script → createdAt (epoch ms). Sweep trước
+ * mỗi spawn và khi run kết thúc (caller truyền registry này vào
+ * sweepLaunchScripts). Export cho test và cho caller Task 6.
+ */
+export const launchScriptRegistry = new Map<string, number>();
+
+/**
+ * Shell single-quote escape: bọc giá trị trong '...' và biến nháy đơn thành
+ * '\'' — bên trong single-quote KHÔNG có expansion, nên $(), backtick, $VAR
+ * đều nguyên vẹn.
+ */
+export function shellEscape(value: string): string {
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * Viết launch script ra {baseDir}/pi-crew-launch-{taskId}-{pid}.sh (mode 0600,
+ * symlink-safe qua atomicWriteFile), đăng ký vào TTL registry, trả path.
+ *
+ * Mọi giá trị env và cwd đều qua shellEscape — env chứa token broker, đường
+ * dẫn, và dữ liệu từ task không tin cậy được để raw vào file bash.
+ */
+export function buildLaunchScript(input: BuildLaunchScriptInput): string {
+	assertSafeTaskId(input.taskId);
+	const depth = currentCrewDepth(input.callerEnv ?? input.env);
+	if (depth > 0) throw new SurfaceDepthGuardError(depth);
+
+	// path.resolve (không phải path.join): script path phải ABSOLUTE — `rm -f
+	// -- "$0"` chạy trong pane SAU dòng `cd <cwd>`, nên $0 relative sẽ trỏ sai
+	// chỗ và self-delete thành no-op (T7 obs, fixed ở T14).
+	const scriptPath = path.resolve(input.baseDir, `pi-crew-launch-${input.taskId}-${process.pid}.sh`);
+	const lines: string[] = ["#!/bin/bash"];
+	for (const [key, value] of Object.entries(input.env)) {
+		lines.push(`export ${key}=${shellEscape(value)}`);
+	}
+	lines.push(`cd ${shellEscape(input.cwd)}`);
+	// Self-delete SỚM (fix round 1/F3): script chứa token broker trong env —
+	// thu hẹp secret-on-disk window xuống vài ms thay vì hết life worker. An toàn
+	// vì bash đã mở fd lên file: tiến trình đang chạy đọc tiếp bằng fd dù đường
+	// dẫn biến mất. rm cuối giữ lại như idempotent backstop.
+	lines.push('( rm -f -- "$0" ) &');
+	lines.push(input.command);
+	lines.push('rm -f -- "$0"');
+	atomicWriteFile(scriptPath, `${lines.join("\n")}\n`, { mode: 0o600 });
+	launchScriptRegistry.set(scriptPath, Date.now());
+	return scriptPath;
+}
+
+/**
+ * Xóa mọi entry cũ hơn LAUNCH_SCRIPT_TTL_MS khỏi đĩa và registry, trả số entry
+ * đã dọn. Idempotent: entry mà file đã biến mất (worker tự rm) vẫn bị dọn khỏi
+ * registry; lỗi đĩa không throw — registry vẫn drop để không leak entry.
+ */
+export function sweepLaunchScripts(registry: Map<string, number>, now: number): number {
+	let swept = 0;
+	for (const [scriptPath, createdAt] of [...registry.entries()]) {
+		if (now - createdAt <= LAUNCH_SCRIPT_TTL_MS) continue;
+		try {
+			fs.rmSync(scriptPath, { force: true });
+		} catch {
+			// best-effort — entry vẫn bị drop khỏi registry bên dưới
+		}
+		registry.delete(scriptPath);
+		swept++;
+	}
+	return swept;
+}
+
+/**
+ * Disk sweep cho script mồ côi TỪ PROCESS KHÁC (T12, optional T5): registry chỉ
+ * biết script của process hiện tại — host chết giữa run để lại file chứa token
+ * broker trên đĩa mà không entry nào trỏ tới. Doctor quét {baseDir} theo glob
+ * `pi-crew-launch-*.sh` và xóa file cũ hơn TTL theo mtime. Trả số file đã dọn
+ * (best-effort — lỗi đĩa từng file bị bỏ qua).
+ */
+export function sweepOrphanLaunchScriptFiles(baseDir: string, now: number): number {
+	let swept = 0;
+	let entries: string[];
+	try {
+		entries = fs.readdirSync(baseDir);
+	} catch {
+		return 0; // baseDir không tồn tại/đọc lỗi — không có gì để dọn
+	}
+	for (const name of entries) {
+		if (!/^pi-crew-launch-.*\.sh$/.test(name)) continue;
+		const scriptPath = path.join(baseDir, name);
+		try {
+			const mtimeMs = fs.statSync(scriptPath).mtimeMs;
+			if (now - mtimeMs <= LAUNCH_SCRIPT_TTL_MS) continue;
+			fs.rmSync(scriptPath, { force: true });
+			swept++;
+		} catch {
+			// best-effort — file biến mất giữa readdir và stat/rm thì đã đạt mục tiêu
+		}
+	}
+	return swept;
+}

package/src/runtime/surface/resolve-surface.ts

@@ -0,0 +1,274 @@
+/**
+ * resolveSurface — fail-closed multiplexer detection matrix (spec §3)
+ *
+ * Decides WHERE a tier-1 worker lives: a pane in tmux/herdr, or headless.
+ * Every failed check (missing binary, dead socket, depth, async run, pane
+ * cap, mode) degrades to headless (null). This NEVER throws because a
+ * multiplexer is missing — the current headless code path stays untouched.
+ *
+ * Check order per cell: binary first, env after. tmux beats herdr when both
+ * are present (innermost wins). Forced mode ("tmux"/"herdr") that fails
+ * detect → null, never falls through to the other backend.
+ */
+
+import { execFileSync } from "node:child_process";
+import { Worker } from "node:worker_threads";
+
+import type { PiTeamsConfig } from "../../config/types.ts";
+import { currentCrewDepth } from "../model/pi-args.ts";
+import { createHerdrProvider, herdrSocketPath } from "./herdr-provider.ts";
+import type { SurfaceProvider } from "./surface-provider.ts";
+import { createTmuxProvider } from "./tmux-provider.ts";
+
+/** Hard cap on live surface panes per run (D6). Reaching it → headless. */
+export const MAX_SURFACE_WORKERS = 6;
+
+/** Socket connect timeout for the herdr liveness probe. */
+const HERDR_PING_TIMEOUT_MS = 500;
+
+/** Provider instances keyed by kind — injected so tests stay independent of T3/T4. */
+export interface SurfaceProviders {
+	tmux?: SurfaceProvider;
+	herdr?: SurfaceProvider;
+}
+
+export interface ResolveSurfaceOpts {
+	/** tmux binary to probe (default: PATH lookup of "tmux"). */
+	tmuxBin?: string;
+	/** herdr binary to probe (default: PATH lookup of "herdr"). */
+	herdrBin?: string;
+	/** Synchronous socket liveness probe (default: net.connect with timeout). */
+	pingSocket?: (socketPath: string) => boolean;
+	/** Provider instances to return on successful detection. */
+	providers?: SurfaceProviders;
+}
+
+// Binary availability cache — same shape as hasCommand in amos tmux helpers:
+// `command -v` is a subprocess, so memoize per binary path for the hot path.
+const binaryAvailability = new Map<string, boolean>();
+
+// tmux provider singleton — mọi pane của process này chia sẻ 1 onExit poll
+// interval trong provider, nên resolveSurface phải trả về cùng instance.
+let tmuxProviderSingleton: SurfaceProvider | null = null;
+// herdr provider singleton — tương tự: 1 subscription connection chung.
+let herdrProviderSingleton: SurfaceProvider | null = null;
+
+function hasBinary(bin: string): boolean {
+	const cached = binaryAvailability.get(bin);
+	if (cached !== undefined) return cached;
+	let available = false;
+	try {
+		execFileSync("sh", ["-c", `command -v ${bin}`], { stdio: "ignore" });
+		available = true;
+	} catch {
+		available = false;
+	}
+	binaryAvailability.set(bin, available);
+	return available;
+}
+
+// herdr socket path dùng chung contract từ provider (T4):
+// HERDR_SOCKET_PATH → HERDR_SESSION (sessions/<name>/) → default location.
+
+// The liveness probe runs in a Worker so the main thread can block on
+// Atomics.wait while the worker's event loop drives net.connect to
+// completion. Plain CJS string — no bundler path rewriting needed.
+const PING_WORKER_SRC = `
+const { parentPort, workerData } = require("node:worker_threads");
+const net = require("node:net");
+const flag = new Int32Array(workerData.sab);
+const done = (ok) => {
+  if (Atomics.load(flag, 0) !== 0) return;
+  Atomics.store(flag, 0, ok ? 1 : 2);
+  Atomics.notify(flag, 0);
+};
+try {
+  const socket = net.connect({ path: workerData.socketPath });
+  const timer = setTimeout(() => { socket.destroy(); done(false); }, workerData.timeoutMs);
+  socket.on("connect", () => { clearTimeout(timer); socket.destroy(); done(true); });
+  socket.on("error", () => { clearTimeout(timer); done(false); });
+} catch {
+  done(false);
+}
+parentPort.unref();
+`;
+
+/**
+ * Synchronous unix-socket connect probe. True = something is listening and
+ * accepted the connection. Any failure (missing socket, refusal, timeout,
+ * Worker/Atomics unavailable on this runtime) → false → fail-closed headless.
+ */
+function pingSocketSync(socketPath: string, timeoutMs = HERDR_PING_TIMEOUT_MS): boolean {
+	const sab = new SharedArrayBuffer(4);
+	const flag = new Int32Array(sab);
+	let worker: Worker;
+	try {
+		worker = new Worker(PING_WORKER_SRC, {
+			eval: true,
+			workerData: { socketPath, timeoutMs, sab },
+		});
+		worker.unref();
+	} catch {
+		return false;
+	}
+	try {
+		// +150ms grace for worker startup beyond the connect timeout itself.
+		Atomics.wait(flag, 0, 0, timeoutMs + 150);
+	} catch {
+		return false;
+	} finally {
+		// biome-ignore lint/suspicious/noEmptyBlockStatements: intentional fire-and-forget — a dying worker has nothing left to fail on.
+		void worker.terminate().catch(() => {});
+	}
+	return Atomics.load(flag, 0) === 1;
+}
+
+/**
+ * Gate nào đã từ chối surface — telemetry `worker.surface_gate_blocked`
+ * (FINDING-3, report 10tier 2026-08-27): gate-null path trước đây trả null
+ * câm, khiến "headless vì misconfig" không thể phân biệt với "headless vì
+ * đúng thiết kế" trong events.jsonl.
+ */
+export type SurfaceGateName = "mode-off" | "depth" | "pane-cap" | "role-not-visible" | "no-mux";
+
+/**
+ * Snapshot các tín hiệu env gate đã thấy — có chủ đích KHÔNG dump cả env (secrets).
+ * `asyncRun` chỉ để telemetry (run là async/background), KHÔNG còn là gate nào
+ * cả — kể từ 2026-08-27, surface bỏ hard-gate "async → headless"; pane có hay
+ * không do môi trường quét được + `runtime.surface.*` config quyết.
+ */
+export interface SurfaceGateEnvSnapshot {
+	tmux: boolean;
+	herdrEnv: boolean;
+	asyncRun: boolean;
+	depth: number;
+}
+
+export interface SurfaceGateRejection {
+	gate: SurfaceGateName;
+	/** Human-readable — kể vì sao cell/gate fail (đi thẳng vào events.jsonl). */
+	reason: string;
+	env: SurfaceGateEnvSnapshot;
+}
+
+export interface SurfaceResolution {
+	provider: SurfaceProvider | null;
+	/** Present khi provider null — gate/mux nào đã từ chối và vì sao. */
+	rejection?: SurfaceGateRejection;
+}
+
+export function surfaceGateEnvSnapshot(env: NodeJS.ProcessEnv): SurfaceGateEnvSnapshot {
+	return {
+		tmux: !!env.TMUX,
+		herdrEnv: env.HERDR_ENV === "1",
+		asyncRun: env.PI_CREW_ASYNC_RUN === "1",
+		depth: currentCrewDepth(env),
+	};
+}
+
+/**
+ * Resolve the surface provider for a tier-1 worker, or null for headless.
+ *
+ * Matrix (spec §3), checked in order — first hit wins:
+ *  1. surface.mode "off" → null
+ *  2. PI_CREW_ASYNC_RUN=1 (async run, A1) → null
+ *  3. PI_CREW_DEPTH > 0 (we are a worker/grandchild) → null — no pane-in-pane
+ *  4. livePaneCount >= MAX_SURFACE_WORKERS → null
+ *  5. role not in visibleAgents (exact match; ["*"] = all) → null
+ *  6. auto: TMUX + binary → tmux, else HERDR_ENV + binary + live socket →
+ *     herdr; forced mode only tries its own cell, fail → null
+ *
+ * Providers: tmux dùng createTmuxProvider (T3), herdr dùng
+ * createHerdrProvider (T4) — mỗi kind một singleton để mọi pane của process
+ * này chia sẻ event subscription; injected `opts.providers` thắng cho test.
+ */
+export function resolveSurfaceDetailed(
+	env: NodeJS.ProcessEnv,
+	config: PiTeamsConfig,
+	role: string,
+	livePaneCount: number,
+	opts: ResolveSurfaceOpts = {},
+): SurfaceResolution {
+	const surface = config.runtime?.surface;
+	const mode = surface?.mode ?? "auto";
+	const reject = (gate: SurfaceGateName, reason: string): SurfaceResolution => ({
+		provider: null,
+		rejection: { gate, reason, env: surfaceGateEnvSnapshot(env) },
+	});
+	if (mode === "off") return reject("mode-off", 'runtime.surface.mode is "off"');
+	// Surface panes are tier-1 only — never inside a worker.
+	const hostDepth = currentCrewDepth(env);
+	if (hostDepth > 0) return reject("depth", `host PI_CREW_DEPTH=${hostDepth} > 0 — no pane-in-pane (tier-1 workers only)`);
+	if (livePaneCount >= MAX_SURFACE_WORKERS)
+		return reject("pane-cap", `livePaneCount ${livePaneCount} >= MAX_SURFACE_WORKERS ${MAX_SURFACE_WORKERS}`);
+
+	const visibleAgents = surface?.visibleAgents ?? [];
+	if (!visibleAgents.includes("*") && !visibleAgents.includes(role))
+		return reject("role-not-visible", `role "${role}" not in visibleAgents [${visibleAgents.join(", ")}]`);
+
+	// Per cell: binary first, env after (cheap env read after the cached
+	// subprocess check; the herdr ping — most expensive — runs last).
+	const tmuxBin = opts.tmuxBin ?? "tmux";
+	const herdrBin = opts.herdrBin ?? "herdr";
+	const tmuxWhy = (): string => (!hasBinary(tmuxBin) ? "tmux binary not found" : "TMUX unset");
+	const herdrWhy = (): string =>
+		!hasBinary(herdrBin) ? "herdr binary not found" : env.HERDR_ENV !== "1" ? "HERDR_ENV!=1" : "socket not live";
+	const tmuxCell = (): boolean => hasBinary(tmuxBin) && !!env.TMUX;
+	const herdrCell = (): boolean =>
+		hasBinary(herdrBin) && env.HERDR_ENV === "1" && (opts.pingSocket ?? pingSocketSync)(herdrSocketPath(env));
+
+	let kind: "tmux" | "herdr" | null;
+	if (mode === "tmux") {
+		kind = tmuxCell() ? "tmux" : null;
+	} else if (mode === "herdr") {
+		kind = herdrCell() ? "herdr" : null;
+	} else {
+		// auto — innermost wins: tmux beats herdr when both are present.
+		kind = tmuxCell() ? "tmux" : herdrCell() ? "herdr" : null;
+	}
+	if (kind === null) {
+		const detail = mode === "tmux" ? tmuxWhy() : mode === "herdr" ? herdrWhy() : `tmux: ${tmuxWhy()}; herdr: ${herdrWhy()}`;
+		return reject("no-mux", `mode "${mode}" found no live mux (${detail})`);
+	}
+
+	// Injected providers thắng (test); mặc định dùng provider thật — mỗi kind
+	// một singleton để mọi pane của process này chia sẻ event subscription.
+	const injected = opts.providers?.[kind];
+	if (injected) return { provider: injected };
+	if (kind === "tmux") {
+		tmuxProviderSingleton ??= createTmuxProvider();
+		return { provider: tmuxProviderSingleton };
+	}
+	herdrProviderSingleton ??= createHerdrProvider();
+	return { provider: herdrProviderSingleton };
+}
+
+/** Wrapper giữ contract cũ (provider | null) — dùng resolveSurfaceDetailed khi cần lý do gate. */
+export function resolveSurface(
+	env: NodeJS.ProcessEnv,
+	config: PiTeamsConfig,
+	role: string,
+	livePaneCount: number,
+	opts: ResolveSurfaceOpts = {},
+): SurfaceProvider | null {
+	return resolveSurfaceDetailed(env, config, role, livePaneCount, opts).provider;
+}
+
+/**
+ * Doctor orphan-pane cleanup (T12): provider singleton THEO KIND, không qua gate
+ * matrix §3 — doctor dọn pane mồ côi chứ không spawn worker mới, nên các gate
+ * depth/cap không áp dụng. Caller tự gọi detect() và chỉ close khi mux
+ * còn sống; trả null khi constructor throw (never — nhưng doctor fail-open list-only).
+ */
+export function surfaceProviderForCleanup(kind: "tmux" | "herdr"): SurfaceProvider | null {
+	try {
+		if (kind === "tmux") {
+			tmuxProviderSingleton ??= createTmuxProvider();
+			return tmuxProviderSingleton;
+		}
+		herdrProviderSingleton ??= createHerdrProvider();
+		return herdrProviderSingleton;
+	} catch {
+		return null;
+	}
+}

package/src/runtime/surface/surface-provider.ts

@@ -0,0 +1,129 @@
+/**
+ * SurfaceProvider interface and types (spec §4)
+ *
+ * Defines the abstraction layer for multiplexer-based interactive surfaces (tmux, herdr).
+ * Used by runtime layer to create, attach, read, and close interactive sessions.
+ */
+
+/**
+ * Detection result for a surface provider
+ */
+export interface SurfaceDetection {
+	ok: boolean;
+	kind?: "tmux" | "herdr";
+	reason?: string;
+}
+
+/** Max worker panes per tab trước khi provider mở tab mới (spec tab-layout §5). */
+export const MAX_PANES_PER_TAB = 8;
+
+/**
+ * Hướng split luân phiên theo pane index trong tab (spec tab-layout §4):
+ * chẵn → down (dọc), lẻ → right (ngang) — không dồn một phía.
+ */
+export function splitDirectionFor(index: number): "down" | "right" {
+	return index % 2 === 0 ? "down" : "right";
+}
+
+/**
+ * Options for spawning a new surface.
+ *
+ * `command` is OPTIONAL on purpose: the MuxSurface spawn flow (spec §13.1)
+ * creates the pane FIRST to learn its id, builds the launch script with
+ * PI_CREW_SURFACE_PANE=<real id>, and only then boots the worker through
+ * {@link SurfaceProvider.sendCommand}. Omitting it leaves the pane sitting at
+ * its shell prompt without any keys being sent.
+ */
+export interface SurfaceSpawnOpts {
+	cwd: string;
+	command?: string;
+	title?: string;
+	/** runId — mọi worker của cùng TEAM RUN chia tab (spec tab-layout §3.1). */
+	tabKey?: string;
+	/**
+	 * HINT từ caller (live pane count lúc spawn) — provider KHÔNG dùng field
+	 * này quyết hướng: counter nội bộ paneCount (deferred-commit) mới là chân
+	 * truth vì đó là số pane THẬT đã spawn trong tab.
+	 */
+	splitIndex?: number;
+}
+
+/**
+ * Reason why a surface session ended
+ */
+export type SurfaceExitReason = "pane-closed" | "mux-dead" | "detached";
+
+/**
+ * Handle to an active surface session
+ */
+export interface SurfaceHandle {
+	id: string;
+	kind: "tmux" | "herdr";
+	/**
+	 * Tab/window chứa pane này (tab-layout, spec 2026-08-27 §5) — provider set
+	 * khi spawn trong tab-flow (tabKey có mặt); caller ghi manifest
+	 * `surface.tabs[tabKey]` để run end biết đóng tab nào. Vắng mặt = spawn
+	 * ngoài run (đường legacy) hoặc provider cũ.
+	 */
+	tabId?: string;
+	onExit(cb: (reason: SurfaceExitReason) => void): void;
+	dispose(): void;
+}
+
+/**
+ * Provider interface for multiplexer-based interactive surfaces
+ *
+ * Implementations:
+ * - tmux: Terminal multiplexer (via libtmux)
+ * - herdr: Custom herd-based multiplexer (future)
+ */
+export interface SurfaceProvider {
+	/** Provider kind identifier */
+	kind: "tmux" | "herdr";
+
+	/** Detect if the multiplexer is available and functional */
+	detect(): SurfaceDetection;
+
+	/** Create a new surface session */
+	createSurface(name: string, opts: SurfaceSpawnOpts): Promise<SurfaceHandle>;
+
+	/**
+	 * Send literal text into an existing surface session (as if typed by the
+	 * user, followed by Enter). Both shipped providers implement it — the only
+	 * way the host boots a worker in a pane that was created without a command
+	 * (spec §13.1). Optional on the interface so pre-existing fake providers in
+	 * tests keep compiling; callers treat "absent" as spawn failure and degrade.
+	 */
+	sendCommand?(handle: SurfaceHandle, text: string): Promise<void>;
+
+	/** Attach to an existing surface session (returns null if not found/implemented) */
+	attach(id: string): SurfaceHandle | null;
+
+	/** Read current screen content from surface */
+	readScreen(handle: SurfaceHandle, lines?: number): Promise<string>;
+
+	/** Close/terminate a surface session */
+	closeSurface(handle: SurfaceHandle, opts?: { force?: boolean }): Promise<void>;
+
+	/**
+	 * Đóng TOÀN bộ tab của một run theo tab-key (spec tab-layout §5: tab chỉ
+	 * đóng khi run end/cancel/kill — không đóng theo từng worker). Provider tự
+	 * tra map nội bộ tabKey → windows/tabs của run nên caller gọi ĐÚNG MỘT LẦN
+	 * cho mỗi tabKey, không loop từng tabId. Optional để fake provider cũ
+	 * trong test vẫn compile; idempotent (map trống / tab đã mất → no-op).
+	 */
+	closeTab?(tabKey: string): Promise<void>;
+
+	/**
+	 * Doctor cleanup-by-id (tab-layout Task 6): đóng MỘT tab/window theo id
+	 * đã ghi trong manifest `surface.tabs` — KHÔNG qua map nội bộ tabKey của
+	 * {@link closeTab}, vì doctor chạy ở TIẾN TRÌNH KHÁC host đã spawn (map
+	 * trống ở đó → closeTab luôn no-op). Liveness lấy từ chính mux: trả
+	 * `"gone"` khi mux không còn biết tab (đã tự chết — không có gì để đóng),
+	 * `"closed"` khi doctor đã đóng; throw cho lỗi thật (doctor ghi failure).
+	 * Idempotent; optional để fake provider cũ trong test vẫn compile.
+	 */
+	closeTabById?(tabId: string): Promise<"closed" | "gone">;
+
+	/** rebalance(): void — A2 defer (not implemented in A1) */
+}