@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

package/packages/board/runner/state-runner.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * Detached auto-state classifier.
+ *
+ * Reads the latest assistant turn from evidence/state, asks a cheap model to classify
+ * the terminal bucket, and updates state.json (and status.json when a run id exists).
+ * Safe best-effort: on model failure it falls back to the same heuristic classifier.
+ */
+import { spawn } from "node:child_process";
+import { readJson } from "../src/core/atomic.mjs";
+import { appendDiagnostic } from "../src/core/diagnostics.mjs";
+import { applyAutoStateToStatus, applyAutoStateToViewState, autoStateEnabled, autoStateFromModelOrHeuristic, autoStateModel, buildAutoStatePrompt, heuristicAutoState, isManualVerdict } from "../src/core/auto-state.mjs";
+import { finalizeEvidence, readEvidence, summarizeEvidence, writeEvidence } from "../src/core/evidence.mjs";
+import { updateCodeRefsFromEvidence } from "../src/core/code-refs-store.mjs";
+import { readState, readStatus, readMeta, writeState, writeStatus } from "../src/core/store.mjs";
+import { sendStateCommand } from "../src/core/coordinator-client.mjs";
+import { commandRejectDiagnostic } from "../src/core/state-commands.mjs";
+
+async function main() {
+	const configPath = process.argv[2];
+	if (!configPath) process.exit(2);
+	/** @type {import("../src/core/types.mjs").AutoStateConfig|null} */
+	const config = readJson(configPath, null);
+	if (!config || !autoStateEnabled()) process.exit(0);
+
+	// Read the view meta once so code-ref extraction reuses it on the evidence write.
+	const meta = readMeta(config.root, config.viewId);
+
+	const state = readState(config.root, config.viewId);
+	if (!state || state.processState === "alive" || state.semanticState === "failed" || state.semanticState === "stopped") process.exit(0);
+	// Cheap pre-check (optimization only): skip a pointless command when the
+	// manual verdict is already materialized. The coordinator's manual_fence
+	// stays the authoritative guard for races after this read.
+	if (isManualVerdict(state)) process.exit(0);
+
+	const evidence = readEvidence(config.root, config.viewId);
+	const latest = latestEvidenceText(evidence) || state.latestAssistantPreview || state.summary || "";
+	if (!latest.trim()) process.exit(0);
+
+	if (state.autoState?.source === "model" && state.autoState.textHash === heuristicAutoState(latest).textHash) process.exit(0);
+
+	const model = autoStateModel();
+	let classification = heuristicAutoState(latest, { lastAgentActivityAt: state.lastAgentActivityAt ?? null });
+	if (model) {
+		const prompt = buildAutoStatePrompt(latest);
+		const out = await runOneShot(
+			config.piCommand,
+			[...config.piArgsPrefix, "--mode", "json", "-p", "--no-session", "--model", model, prompt],
+			{ timeoutMs: 15000, cwd: config.cwd, env: sanitizedEnv() },
+		);
+		classification = autoStateFromModelOrHeuristic(out, latest, { lastAgentActivityAt: state.lastAgentActivityAt ?? null });
+	}
+
+	// Issue #91 (A8 path 2): the classification lands through the View State
+	// Coordinator — the single writer of state.json/status.json. A manual
+	// completion is fenced by the coordinator (manual_fence), so this late pass
+	// can no longer clobber the user's verdict (#46 class). Ambiguous transport
+	// outcomes (timeout / connection_reset) NEVER fall back to a direct write:
+	// the command may already be journaled, and the coordinator's boot replay
+	// is the recovery path.
+	const result = await sendStateCommand(config.root, {
+		type: "state_command",
+		viewId: config.viewId,
+		runId: config.runId ?? null,
+		source: "state-runner",
+		kind: "auto_state_classified",
+		expectedRevision: null,
+		payload: { classification },
+	});
+
+	if (result.status === "applied") {
+		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, code: "auto_state_classified", message: "Auto-state classifier updated row state", details: { kind: classification.kind, confidence: classification.confidence, source: classification.source, reason: classification.reason } });
+	} else if (result.reason !== "coordinator_disabled") {
+		// Unified decided/ambiguous classification (CR r2 issue-3): decided
+		// rejects (manual_fence/stale_run/…) log as info *_skipped — the
+		// coordinator's verdict is authoritative; only genuinely ambiguous
+		// outcomes (timeout/connection_reset) keep the recovery-path warn.
+		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, ...commandRejectDiagnostic("auto_state", "Auto-state classification", result.reason, "otherwise the next classification pass will converge the row"), details: { reason: result.reason } });
+	}
+
+	if (result.reason === "coordinator_disabled") {
+		// Legacy escape hatch (AGENT_BOARD_COORDINATOR=off): pre-coordinator
+		// direct-write behavior, unchanged.
+		let changed = false;
+		if (config.runId) {
+			const status = readStatus(config.root, config.viewId, config.runId);
+			if (status) {
+				changed = applyAutoStateToStatus(status, classification, Date.now()) || changed;
+				status.evidenceSummary = summarizeEvidence(finalizeEvidence(evidence, status, Date.now()));
+				writeStatus(config.root, status);
+			}
+		}
+		const latestState = readState(config.root, config.viewId) ?? state;
+		changed = applyAutoStateToViewState(latestState, classification, Date.now()) || changed;
+		finalizeEvidence(evidence, { semanticState: latestState.semanticState, usage: null }, Date.now());
+		latestState.review = summarizeEvidence(evidence);
+		writeEvidence(config.root, evidence);
+		updateCodeRefsFromEvidence(config.root, config.viewId, evidence, meta);
+		writeState(config.root, latestState);
+		if (changed) {
+			appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, code: "auto_state_classified", message: "Auto-state classifier updated row state", details: { kind: classification.kind, confidence: classification.confidence, source: classification.source, reason: classification.reason } });
+		}
+		process.exit(0);
+	}
+
+	// Evidence pipeline (coordinator-independent) stays direct: finalize the
+	// evidence snapshot from a FRESH state read (reads are not writes — the
+	// coordinator owns state.json/status.json writes, not reads), then persist
+	// the evidence artifacts and code-refs.
+	const postState = readState(config.root, config.viewId);
+	finalizeEvidence(evidence, { semanticState: postState?.semanticState ?? state.semanticState, usage: null }, Date.now());
+	writeEvidence(config.root, evidence);
+	updateCodeRefsFromEvidence(config.root, config.viewId, evidence, meta);
+
+	// Issue #91 PR #2 (Task 4): the evidence mirrors move behind the coordinator
+	// too — one patch_fields command materializes review/evidenceSummary on both
+	// files under a shared materializedRevision (previously two separately
+	// fenced direct writes). The coordinator's generic manual_fence / stale_run
+	// guards are authoritative; ambiguous outcomes (timeout / connection_reset)
+	// NEVER fall back to a direct write — if the command was journaled, boot
+	// replay recovers it, and the next classification pass re-derives mirrors
+	// from the evidence files either way.
+	const mirrorSummary = summarizeEvidence(evidence);
+	const patch = await sendStateCommand(config.root, {
+		type: "state_command",
+		viewId: config.viewId,
+		runId: config.runId ?? null,
+		source: "state-runner",
+		kind: "patch_fields",
+		expectedRevision: null,
+		payload: { state: { review: mirrorSummary }, status: { evidenceSummary: mirrorSummary } },
+	});
+	if (patch.status === "applied") {
+		// Quiet success — mirrors materialized by the coordinator.
+	} else if (patch.reason === "manual_fence" || patch.reason === "stale_run" || patch.reason === "no_change") {
+		// Designed fences — informational: a manual verdict or a newer run owns
+		// the row, or the mirrors already match.
+		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, code: "evidence_mirror_patch_skipped", message: `Evidence mirror patch not applied (${patch.reason})`, details: { reason: patch.reason } });
+	} else {
+		appendDiagnostic(config.root, config.viewId, { source: "service", runId: config.runId, level: "warn", code: "evidence_mirror_patch_ambiguous", message: `Evidence mirror patch outcome unknown (${patch.reason}); if the command was journaled, coordinator replay will recover it; the next classification pass re-derives the mirrors from the evidence files`, details: { reason: patch.reason } });
+	}
+}
+
+/** @param {import("../src/core/types.mjs").EvidenceSnapshot} evidence */
+function latestEvidenceText(evidence) {
+	return evidence.assistantEvidence?.[evidence.assistantEvidence.length - 1]?.text ?? "";
+}
+
+function sanitizedEnv() {
+	const env = { ...process.env };
+	delete env.AGENT_BOARD_CHILD;
+	delete env.AGENT_VIEW_CHILD;
+	delete env.AGENT_BOARD_VIEW_ID;
+	delete env.AGENT_VIEW_VIEW_ID;
+	delete env.AGENT_BOARD_HOSTED;
+	delete env.AGENT_VIEW_HOSTED;
+	// Board-spawned classifier workers must not arm the warm-host sweeper
+	// (they share the board root with real hosts).
+	env.AGENT_BOARD_NO_SWEEP = "1";
+	return env;
+}
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {{ timeoutMs?: number, cwd?: string, env?: NodeJS.ProcessEnv }} [opts]
+ */
+function runOneShot(command, args, opts = {}) {
+	return new Promise((resolve) => {
+		let out = "";
+		let settled = false;
+		const child = spawn(command, args, { cwd: opts.cwd, env: opts.env ?? process.env, stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
+		let buf = "";
+		const finish = () => {
+			if (settled) return;
+			settled = true;
+			resolve(out);
+		};
+		child.stdout.on("data", (c) => {
+			buf += c.toString();
+			const lines = buf.split("\n");
+			buf = lines.pop() ?? "";
+			for (const line of lines) {
+				try {
+					const e = JSON.parse(line);
+					if (e?.type === "message_end" && e.message?.role === "assistant") {
+						for (const b of e.message.content ?? []) if (b.type === "text") out += b.text;
+					}
+				} catch {
+					/* ignore */
+				}
+			}
+		});
+		child.on("close", finish);
+		child.on("error", finish);
+		setTimeout(() => {
+			try { child.kill("SIGKILL"); } catch {}
+			finish();
+		}, opts.timeoutMs ?? 20000).unref?.();
+	});
+}
+
+main().catch(() => process.exit(0));

package/packages/board/runner/title-runner.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Detached title-runner shim.
+ *
+ * Best-effort only: generates a short GPT-4o title from the initial task prompt and updates
+ * the row's meta name if the user has not already renamed it.
+ */
+import { spawn } from "node:child_process";
+import { readJson } from "../src/core/atomic.mjs";
+import { readMeta, writeMeta } from "../src/core/store.mjs";
+import { DEFAULT_TITLE_MODEL, DEFAULT_TITLE_THINKING_LEVEL, normalizeGeneratedTitle, titlePrompt } from "../src/core/title.mjs";
+
+function main() {
+	const configPath = process.argv[2];
+	if (!configPath) process.exit(2);
+	/** @type {import("../src/core/types.mjs").TitleConfig|null} */
+	const config = readJson(configPath, null);
+	if (!config?.viewId || !config.prompt) process.exit(2);
+
+	maybeGenerateTitle(config)
+		.catch(() => {})
+		.finally(() => process.exit(0));
+}
+
+async function maybeGenerateTitle(config) {
+	const configured = process.env.AGENT_BOARD_TITLE_MODEL ?? process.env.AGENT_VIEW_TITLE_MODEL;
+	if (configured === "off") return;
+	const model = configured ?? config.model ?? DEFAULT_TITLE_MODEL;
+	const thinking = process.env.AGENT_BOARD_TITLE_THINKING_LEVEL ?? process.env.AGENT_VIEW_TITLE_THINKING_LEVEL ?? DEFAULT_TITLE_THINKING_LEVEL;
+	const prompt = titlePrompt(config.prompt);
+	const args = [...config.piArgsPrefix, "--mode", "json", "-p", "--no-session", "--model", model];
+	if (thinking && thinking !== "off") args.push("--thinking", thinking);
+	args.push(prompt);
+	const out = await runOneShot(config.piCommand, args, 15000);
+	const title = normalizeGeneratedTitle(out.trim().split("\n").slice(-1)[0]?.trim(), config.fallbackName);
+	if (!title || title === config.fallbackName) return;
+
+	const meta = readMeta(config.root, config.viewId);
+	if (!meta) return;
+	if (meta.name !== config.fallbackName) return;
+	meta.name = title;
+	writeMeta(config.root, meta);
+}
+
+function runOneShot(command, args, timeoutMs = 20000) {
+	return new Promise((resolve) => {
+		let out = "";
+		const child = spawn(command, args, { stdio: ["ignore", "pipe", "ignore"], windowsHide: true, env: { ...process.env, AGENT_BOARD_NO_SWEEP: "1" } });
+		let buf = "";
+		child.stdout.on("data", (c) => {
+			buf += c.toString();
+			const lines = buf.split("\n");
+			buf = lines.pop() ?? "";
+			for (const line of lines) {
+				try {
+					const e = JSON.parse(line);
+					if (e?.type === "message_end" && e.message?.role === "assistant") {
+						for (const b of e.message.content ?? []) {
+							if (b.type === "text") out += b.text;
+						}
+					}
+				} catch {
+					/* ignore */
+				}
+			}
+		});
+		child.on("close", () => resolve(out));
+		child.on("error", () => resolve(""));
+		setTimeout(() => {
+			try {
+				child.kill("SIGKILL");
+			} catch {
+				/* ignore */
+			}
+			resolve(out);
+		}, timeoutMs).unref?.();
+	});
+}
+
+main();

package/packages/board/src/commands/agent-board.ts

@@ -0,0 +1,394 @@
+/**
+ * `/agent-board` command: opens the dashboard, runs its action loop, and attaches through
+ * agent-board PTY hosts for fast switching. `ctx.switchSession` is only a no-PTY fallback.
+ * Also wires dispatch+attach and stale-row recovery on open.
+ */
+import { holdInputListeners } from "../core/hold-input.mjs";
+import { restoreChrome } from "../ui/chrome.ts";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { requestDashboardRender } from "../core/dashboard-render.mjs";
+import { nextVisibleIdAfterRemoval } from "../core/rows.mjs";
+import { createService } from "../runtime/service.mjs";
+import { boardCommands } from "../core/slash-commands.mjs";
+import { planAttachPrelude, planAttachResolved } from "./attach-decision.mjs";
+import { screenLogPath } from "../core/paths.mjs";
+import { appendDiagnostic } from "../core/diagnostics.mjs";
+import { DashboardComponent, type DashboardResult } from "../ui/dashboard.ts";
+import { PtyAttachComponent, type PtyAttachResult } from "../ui/pty-attach.ts";
+
+const POLL_MS = 700;
+
+export interface AgentBoardCommandOptions {
+	root: string;
+	runnerScript: string;
+	ptyRunnerScript?: string;
+	titleRunnerScript?: string;
+	piCommand: string;
+	piArgsPrefix: string[];
+	getThinkingLevel: () => "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+}
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+let addedCommands: () => { name: string; description?: string; source: string }[] = () => [];
+
+export function registerAgentBoardCommand(pi: ExtensionAPI, opts: AgentBoardCommandOptions): void {
+	addedCommands = () => pi.getCommands();
+	pi.registerCommand("agent-board", {
+		description: "Open the background agent-board dashboard",
+		handler: async (args, ctx) => {
+			const attachMatch = /(?:^|\s)--attach\s+(\S+)/.exec(args);
+			const stopFirst = /(^|\s)--stop(\s|$)/.test(args);
+			const service = createService({
+				root: opts.root,
+				runnerScript: opts.runnerScript,
+				ptyRunnerScript: opts.ptyRunnerScript,
+				titleRunnerScript: opts.titleRunnerScript,
+				piCommand: opts.piCommand,
+				piArgsPrefix: opts.piArgsPrefix,
+				defaultCwd: ctx.cwd,
+				// Stale-defaultModel launch guard (issue #90): live list, undefined
+				// when the registry is unavailable so validation conservatively skips.
+				availableModels: () => {
+					try {
+						return ctx.modelRegistry.getAvailable();
+					} catch {
+						return undefined;
+					}
+				},
+			});
+
+			if (!ctx.hasUI) {
+				ctx.ui.notify("The agent-board dashboard requires interactive mode.", "warning");
+				return;
+			}
+
+			if (attachMatch) {
+				const outcome = await attach(ctx, service, opts.root, attachMatch[1], stopFirst);
+				if (outcome.action !== "switched") await dashboardAttachLoop(ctx, service, opts.root, attachMatch[1], opts.getThinkingLevel);
+				return;
+			}
+
+			await dashboardAttachLoop(ctx, service, opts.root, null, opts.getThinkingLevel);
+		},
+	});
+}
+
+export async function openDashboard(
+	ctx: Pick<ExtensionCommandContext, "ui" | "cwd" | "modelRegistry" | "model" | "sessionManager" | "shutdown">,
+	service: ReturnType<typeof createService>,
+	options: {
+		initialSelectedId?: string | null;
+		initialNotice?: string;
+		currentThinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+	} = {},
+): Promise<DashboardResult> {
+	ctx.ui.setWorkingVisible(false);
+	ctx.ui.setHeader(() => ({ render: () => [], invalidate() {} }));
+	ctx.ui.setFooter(() => ({ render: () => [], invalidate() {} }));
+	ctx.ui.setTitle("agent-board");
+	let board: unknown = null;
+	let command: string | null = null;
+	let availableModels: any[] = [];
+	try {
+		availableModels = ctx.modelRegistry.getAvailable();
+	} catch {
+		availableModels = [];
+	}
+	try {
+		const result = await ctx.ui.custom<DashboardResult>(
+			(tui, theme, keybindings, done) => {
+				board = tui;
+				let interval: ReturnType<typeof setInterval> | null = null;
+				const releaseInput = holdInputListeners(tui);
+				const wrappedDone = (result: DashboardResult) => {
+					releaseInput();
+					if (interval) clearInterval(interval);
+					interval = null;
+					done(result);
+				};
+				const comp = new DashboardComponent(tui, theme as never, keybindings, wrappedDone, {
+					service,
+					root: service.getRoot(),
+					defaultCwd: ctx.cwd,
+					currentSessionFile: ctx.sessionManager?.getSessionFile?.() ?? null,
+					initialSelectedId: options.initialSelectedId,
+					initialNotice: options.initialNotice,
+					availableModels,
+					currentModel: ctx.model ?? null,
+					currentThinkingLevel: options.currentThinkingLevel ?? "off",
+					commands: boardCommands(addedCommands()),
+				});
+				interval = setInterval(() => {
+					void service.reconcile().catch(() => {});
+					comp.refresh();
+					requestDashboardRender(tui);
+				}, POLL_MS);
+				const withDispose = comp as DashboardComponent & { dispose: () => void };
+				// Chain the component's own dispose so its cleanup (prewarm scheduler
+				// cancel) still runs; a plain assignment would shadow the prototype method.
+				const origDispose = comp.dispose.bind(comp);
+				withDispose.dispose = () => {
+					origDispose();
+					releaseInput();
+					if (interval) clearInterval(interval);
+					interval = null;
+				};
+				return comp;
+			},
+			{
+				overlay: true,
+				overlayOptions: { anchor: "top-left", width: "100%", maxHeight: "100%", margin: 0 },
+			},
+		);
+		if (result.action === "quit") ctx.shutdown();
+		if (result.action === "command") command = result.text;
+		return result;
+	} finally {
+		restoreChrome(ctx);
+		// A command runs with more than an extension is given, so this goes the way a typed one does.
+		if (command) {
+			ctx.ui.setEditorText(command);
+			setTimeout(() => {
+				const focused = (board as { getFocusedComponent?: () => { handleInput?: (data: string) => void; getExpandedText?: () => string } | null } | null)?.getFocusedComponent?.();
+				// Only if it's the prompt holding the command. Otherwise it's left there to send by hand.
+				if (focused?.getExpandedText?.() === command) focused.handleInput?.("\r");
+			}, 0);
+		}
+	}
+}
+
+type AttachOutcome = { action: "detached" | "closed" | "switched" | "none"; afterDelete?: { nextSelectedId: string | null; notice: string } };
+
+export async function dashboardAttachLoop(
+	ctx: ExtensionCommandContext,
+	service: ReturnType<typeof createService>,
+	root: string,
+	initialSelectedId: string | null,
+	getThinkingLevel?: () => "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max",
+): Promise<void> {
+	let selectedId = initialSelectedId;
+	let again = true;
+	let pendingNotice: string | undefined;
+	while (again) {
+		const currentId = currentViewId(ctx, service);
+		if (currentId) void service.markVisited?.(currentId)?.catch(() => {});
+		void service.reconcile().catch(() => {});
+		const result = await openDashboard(ctx, service, {
+			initialSelectedId: selectedId,
+			currentThinkingLevel: getThinkingLevel?.(),
+			initialNotice: pendingNotice,
+		});
+		pendingNotice = undefined;
+		if (result.action !== "attach") return;
+		// That session is the one on screen behind the board: going back to it is just closing.
+		if (result.viewId === currentId) return;
+		selectedId = result.viewId;
+		const outcome = await attach(ctx, service, root, result.viewId, result.stopFirst);
+		if (outcome.afterDelete) {
+			// Issue #147: land on the neighbor (null -> deleted id -> existing
+			// orderedIds[0] clamp) and show the Deleted notice once.
+			selectedId = outcome.afterDelete.nextSelectedId ?? selectedId;
+			pendingNotice = outcome.afterDelete.notice;
+		}
+		again = outcome.action === "detached" || outcome.action === "closed" || outcome.action === "none";
+	}
+}
+
+async function attach(
+	ctx: ExtensionCommandContext,
+	service: ReturnType<typeof createService>,
+	root: string,
+	viewId: string,
+	stopFirst: boolean,
+): Promise<AttachOutcome> {
+	const row = service.row(viewId);
+	if (!row) {
+		ctx.ui.notify("Session no longer exists.", "warning");
+		return { action: "none" };
+	}
+	const prelude = planAttachPrelude({ rowAlive: row.alive, rowHostActive: row.hostActive, stopFirst });
+	if (prelude.plan === "warn-running") {
+		ctx.ui.notify("Session is still running. Stop it before attaching, or confirm from the dashboard.", "warning");
+		return { action: "none" };
+	}
+	if (prelude.plan === "stop-first") {
+		service.stop(viewId);
+		// Give the runner a moment to terminate the worker and release the session file.
+		await sleep(500);
+	}
+
+	// Single async resolver entry: real probe + bounded recovery decide readiness (issue #70).
+	const plan = planAttachResolved(await service.resolveAttachTarget(viewId));
+	if (plan.plan === "open-pty") {
+		void service.markVisited?.(viewId)?.catch(() => {});
+		const result = await openPtyAttach(ctx, root, row.meta.id, row.meta.name, plan.socketPath);
+		void service.markVisited?.(viewId)?.catch(() => {});
+		if (result.action === "quit") {
+			ctx.shutdown();
+			return { action: "switched" }; // Nothing to come back to.
+		}
+		if (result.action === "delete") {
+			// Issue #147: the component already tore down and exited — archive
+			// here so the host's death is never rendered inside the attach view.
+			// Neighbor and name are computed BEFORE archiving (rows change).
+			const latest = service.row(viewId) ?? row;
+			const name = latest.meta.name;
+			const nextSelectedId = nextVisibleIdAfterRemoval(service.rows(), viewId, Date.now());
+			const res = await service.archive(viewId);
+			if (!res.ok) ctx.ui.notify(res.error ?? "Delete failed", "error");
+			else return { action: "detached", afterDelete: { nextSelectedId, notice: `Deleted "${name}"` } };
+			return { action: "detached" };
+		}
+		return { action: result.action === "closed" ? "closed" : "detached" };
+	}
+	if (plan.plan === "session-switch") {
+		const latest = service.row(viewId) ?? row;
+		if (!existsSync(latest.meta.sessionFile)) {
+			ctx.ui.notify("Session file isn't ready yet — try again once the run has started.", "warning");
+			return { action: "none" };
+		}
+		const name = latest.meta.name;
+		void service.markVisited?.(viewId)?.catch(() => {});
+		const switchingOverlay = await showSwitchingOverlay(ctx, name, "PTY unavailable");
+		const result = await ctx.switchSession(latest.meta.sessionFile, {
+			withSession: async (replaced) => {
+				replaced.ui.notify(`Attached to "${name}". Press ← on empty input to return to agent board.`, "info");
+				installBackToDashboard(replaced, service);
+			},
+		}).finally(() => {
+			try {
+				switchingOverlay?.hide();
+			} catch {}
+		});
+		if (result.cancelled) {
+			ctx.ui.notify("Attach cancelled.", "warning");
+			return { action: "none" };
+		}
+		return { action: "switched" };
+	}
+	if (plan.plan === "notify-pending") {
+		ctx.ui.notify(plan.reason, "info");
+		return { action: "none" };
+	}
+	ctx.ui.notify("Session no longer exists.", "warning");
+	return { action: "none" };
+}
+
+async function openPtyAttach(
+	ctx: ExtensionCommandContext,
+	root: string,
+	viewId: string,
+	name: string,
+	socketPath: string,
+): Promise<PtyAttachResult> {
+	ctx.ui.setWorkingVisible(false);
+	ctx.ui.setHeader(() => ({ render: () => [], invalidate() {} }));
+	ctx.ui.setFooter(() => ({ render: () => [], invalidate() {} }));
+	ctx.ui.setTitle(`agent-board: ${name}`);
+	try {
+		return await ctx.ui.custom<PtyAttachResult>(
+			(tui, theme, keybindings, done) =>
+				new PtyAttachComponent(tui, theme as never, keybindings, done, {
+					socketPath,
+					screenLogPath: root ? screenLogPath(root, viewId) : undefined,
+					title: name,
+					onDiagnostic: root
+						? (event) => {
+								// Best effort, like every other diagnostics writer.
+								try {
+									appendDiagnostic(root, viewId, event as never);
+								} catch {
+									/* diagnostics must never break attach */
+								}
+							}
+						: undefined,
+				}),
+			{
+				overlay: true,
+				overlayOptions: { anchor: "top-left", width: "100%", maxHeight: "100%", margin: 0 },
+			},
+		);
+	} finally {
+		restoreChrome(ctx);
+	}
+}
+
+async function showSwitchingOverlay(ctx: ExtensionCommandContext, name: string, reason: string): Promise<{ hide(): void } | null> {
+	let handle: { hide(): void } | null = null;
+	void ctx.ui.custom<null>(
+		(tui, theme) => ({
+			render(width: number): string[] {
+				const height = tui.terminal?.rows ?? 24;
+				const out = Array.from({ length: Math.max(0, Math.floor(height / 2) - 2) }, () => "");
+				out.push(clipLine(theme.fg("accent", theme.bold(`Switching to "${name}"…`)), width));
+				out.push(clipLine(theme.fg("dim", `Starting fallback session switch (${reason})`), width));
+				while (out.length < height) out.push("");
+				return out;
+			},
+			invalidate() {},
+		}),
+		{
+			overlay: true,
+			overlayOptions: { anchor: "top-left", width: "100%", maxHeight: "100%", margin: 0 },
+			onHandle: (h) => {
+				handle = h;
+			},
+		},
+	);
+	await sleep(50);
+	return handle;
+}
+
+function clipLine(text: string, width: number): string {
+	return truncateToWidth(text, width);
+}
+
+function installBackToDashboard(ctx: ExtensionCommandContext, service: ReturnType<typeof createService>): void {
+	ctx.ui.setStatus("agent-board.back", ctx.ui.theme.fg("muted", "← board"));
+	let opening = false;
+	ctx.ui.onTerminalInput((data: string) => {
+		if (opening || !matchesKey(data, Key.left)) return undefined;
+		// Do not steal normal cursor-left while the user is composing a message.
+		if (ctx.ui.getEditorText().length > 0) return undefined;
+		opening = true;
+		void (async () => {
+			try {
+				let selectedId = currentViewId(ctx, service);
+				while (true) {
+					if (selectedId) void service.markVisited?.(selectedId)?.catch(() => {});
+					void service.reconcile().catch(() => {});
+					const result = await openDashboard(ctx, service, { initialSelectedId: selectedId });
+					if (result.action !== "attach") return;
+					selectedId = result.viewId;
+					const target = service.row(result.viewId);
+					const currentSessionFile = ctx.sessionManager.getSessionFile();
+					if (target && currentSessionFile && samePath(target.meta.sessionFile, currentSessionFile)) {
+						ctx.ui.notify("Already attached to this session.", "info");
+						continue;
+					}
+					const outcome = await attach(ctx, service, service.root, result.viewId, result.stopFirst);
+					if (outcome.action === "switched") return;
+				}
+			} catch (err) {
+				ctx.ui.notify(`Couldn't open agent board: ${err instanceof Error ? err.message : String(err)}`, "error");
+			} finally {
+				opening = false;
+			}
+		})();
+		return { consume: true };
+	});
+}
+
+function currentViewId(ctx: ExtensionCommandContext, service: ReturnType<typeof createService>): string | null {
+	const currentSessionFile = ctx.sessionManager.getSessionFile();
+	if (!currentSessionFile) return null;
+	return service.rows().find((r) => samePath(r.meta.sessionFile, currentSessionFile))?.meta.id ?? null;
+}
+
+function samePath(a: string, b: string): boolean {
+	return resolve(a) === resolve(b);
+}