@zhuxixi/pi-agent-board 0.5.2 → 0.6.0

package/scripts/release_helper.mjs

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+/**
+ * Conventional-commit driven CHANGELOG helper (port of the jfox release
+ * helper, adapted to this repo's Node stack and `vX.Y.Z` tags).
+ *
+ * Modes:
+ *   node scripts/release_helper.mjs [--dry-run] [patch|minor|major|X.Y.Z]
+ *     Compute the next version (default patch) from package.json, parse
+ *     conventional commits since the last `v*` tag, and print a JSON result
+ *     with a `changelog_preview`. Without --dry-run, also insert the section
+ *     at the top of CHANGELOG.md.
+ *   node scripts/release_helper.mjs verify
+ *     Check that every functional commit (feat/fix/refactor/docs/perf) in
+ *     `last v* tag..HEAD` has its trailing (#N) present in the CHANGELOG top
+ *     section. Exits 1 with a missing list when the changelog has drifted
+ *     (e.g. a PR merged after the section was generated).
+ *
+ * The pure functions below are exported for unit tests; the CLI layer is the
+ * only place that touches git or the filesystem.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const PACKAGE_JSON = join(REPO_ROOT, "package.json");
+const CHANGELOG_MD = join(REPO_ROOT, "CHANGELOG.md");
+const REPO_URL = "https://github.com/zhuxixi/pi-agent-board";
+const COMPARE_BASE = `${REPO_URL}/compare`;
+
+/** Conventional commit subject: type[(scope)][!]: message [(#N)] */
+const CONVENTIONAL_RE =
+	/^(feat|fix|perf|refactor|docs|chore|test)(?:\(([^)]*)\))?!?:\s+(.+?)(?:\s+\(#(\d+)\))?$/;
+/** Version-squash subjects produced by `npm version` PRs, e.g. `0.5.2 (#74)`. */
+const VERSION_SQUASH_RE = /^\d+\.\d+\.\d+(?:[-.][\w.]+)?\s*\(#\d+\)$/;
+/** Functional whitelist for verify (CHANGELOG-worthy types). */
+const FUNCTIONAL_TYPES = new Set(["feat", "fix", "refactor", "docs", "perf"]);
+
+/**
+ * Parse commit subject lines into changelog entries.
+ * @param {Iterable<string>} lines
+ * @returns {Array<{type: string, scope: string, message: string, pr: number|null}>}
+ */
+export function parseCommitLines(lines) {
+	const entries = [];
+	const seen = new Set();
+	for (const raw of lines) {
+		const s = String(raw ?? "").trim();
+		if (!s) continue;
+		if (VERSION_SQUASH_RE.test(s)) continue;
+		if (/bump\s+version/i.test(s)) continue;
+		if (s.startsWith("Merge ")) continue;
+		const m = s.match(CONVENTIONAL_RE);
+		const prTail = s.match(/\(#(\d+)\)\s*$/);
+		const entry = m
+			? { type: m[1], scope: m[2] || "", message: m[3].trim(), pr: m[4] ? Number(m[4]) : null }
+			: { type: "other", scope: "", message: s, pr: prTail ? Number(prTail[1]) : null };
+		const key = `${entry.type}|${entry.scope}|${entry.message}`;
+		if (seen.has(key)) continue;
+		seen.add(key);
+		entries.push(entry);
+	}
+	return entries;
+}
+
+/**
+ * Render one changelog section for a version.
+ * @param {{version: string, date: string, entries: Array<{type: string, scope: string, message: string, pr: number|null}>, prevTag?: string|null}} opts
+ * @returns {string}
+ */
+export function generateChangelog({ version, date, entries, prevTag = null }) {
+	const groups = [
+		["Features", (e) => e.type === "feat"],
+		["Fixes", (e) => e.type === "fix"],
+		["Performance", (e) => e.type === "perf"],
+		["Changes", (e) => e.type !== "feat" && e.type !== "fix" && e.type !== "perf"],
+	];
+	const lines = [`## [${version}] - ${date}`, ""];
+	for (const [title, keep] of groups) {
+		const group = entries.filter(keep);
+		if (group.length === 0) continue;
+		lines.push(`### ${title}`, "");
+		for (const e of group) {
+			const scope = e.scope ? `**${e.scope}**: ` : "";
+			const pr = e.pr ? ` (#${e.pr})` : "";
+			lines.push(`- ${scope}${e.message}${pr}`);
+		}
+		lines.push("");
+	}
+	const prev = prevTag ? prevTag.replace(/^v/, "") : null;
+	if (prev) lines.push(`[${version}]: ${COMPARE_BASE}/v${prev}...v${version}`);
+	return lines.join("\n");
+}
+
+/**
+ * PR numbers referenced inside the first `## [...]` section of a CHANGELOG.
+ * @param {string} text
+ * @returns {Set<number>}
+ */
+export function changelogTopPrs(text) {
+	// Split before each `## [` heading and take the first real section — the
+	// JS port of jfox's regex uses split because Python's \Z (absolute end)
+	// has no JS equivalent and a `$` lookahead matches zero-width.
+	const sections = String(text ?? "").split(/(?=^##\s*\[)/m);
+	const first = sections.find((s) => /^##\s*\[/.test(s));
+	const section = first ?? String(text ?? "");
+	return new Set([...section.matchAll(/\(#(\d+)\)/g)].map((x) => Number(x[1])));
+}
+
+/**
+ * Filter subject lines down to functional (CHANGELOG-worthy) commits:
+ * conventional whitelist types, skipping merges, version squashes, and
+ * `docs(changelog)` maintenance commits (their PRs fix the changelog itself
+ * and must not feed back into verify — infinite loop guard, jfox #333).
+ * @param {Iterable<string>} lines
+ * @returns {string[]}
+ */
+export function functionalLines(lines) {
+	const out = [];
+	for (const raw of lines) {
+		const s = String(raw ?? "").trim();
+		if (!s || VERSION_SQUASH_RE.test(s) || /bump\s+version/i.test(s)) continue;
+		if (s.startsWith("Merge ")) continue;
+		const m = s.match(/^(\w+)(?:\(([^)]*)\))?!?:/);
+		if (!m) continue;
+		if (!FUNCTIONAL_TYPES.has(m[1].toLowerCase())) continue;
+		if (m[1].toLowerCase() === "docs" && (m[2] || "").toLowerCase().includes("changelog")) continue;
+		out.push(s);
+	}
+	return out;
+}
+
+/**
+ * Pure verify: functional commit lines vs CHANGELOG text.
+ * @param {{lines: Iterable<string>, changelogText: string}} input
+ * @returns {{ok: boolean, missing: number[], extra: number[], functionalCommits: number}}
+ */
+export function verifyFrom({ lines, changelogText }) {
+	const funcPrs = new Set();
+	for (const s of functionalLines(lines)) {
+		const m = s.match(/\(#(\d+)\)\s*$/);
+		if (m) funcPrs.add(Number(m[1]));
+	}
+	const clPrs = changelogTopPrs(changelogText);
+	const missing = [...funcPrs].filter((n) => !clPrs.has(n)).sort((a, b) => a - b);
+	const extra = [...clPrs].filter((n) => !funcPrs.has(n)).sort((a, b) => a - b);
+	return { ok: missing.length === 0, missing, extra, functionalCommits: funcPrs.size };
+}
+
+/**
+ * Whether the CHANGELOG already has a section for this exact version
+ * (apply idempotency guard — a re-apply must not duplicate the heading).
+ * @param {string} existing
+ * @param {string} version
+ * @returns {boolean}
+ */
+export function hasSection(existing, version) {
+	const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	return new RegExp(`^##\\s*\\[${escaped}]`, "m").test(String(existing ?? ""));
+}
+
+/**
+ * Insert a rendered section above the first existing `## ` heading (or append
+ * after the header when none exists yet).
+ * @param {string} existing
+ * @param {string} section
+ * @returns {string}
+ */
+export function insertSection(existing, section) {
+	const content = String(existing ?? "");
+	const insertAt = content.indexOf("\n## ");
+	if (insertAt === -1) return `${content.replace(/\s*$/, "")}\n\n${section}\n`;
+	return `${content.slice(0, insertAt + 1)}${section}\n\n${content.slice(insertAt + 1)}`;
+}
+
+/** @returns {string|null} latest `v*` tag, null when the repo has none, throws on git errors (fail-closed) */
+function lastTag(root = REPO_ROOT) {
+	const tag = gitOut(["tag", "--list", "v*"], root);
+	const tags = tag.split("\n").map((s) => s.trim()).filter(Boolean);
+	if (tags.length === 0) return null;
+	return gitOut(["describe", "--tags", "--abbrev=0", "--match", "v*"], root).trim() || null;
+}
+
+/** @param {string[]} args @param {string} root @returns {string} */
+function gitOut(args, root) {
+	return execFileSync("git", args, { cwd: root, encoding: "utf8" });
+}
+
+/** @returns {string[]} commit subjects in `lastTag..HEAD` (or all when no tag); throws on git errors */
+function commitSubjects(tag, root = REPO_ROOT) {
+	const range = tag ? `${tag}..HEAD` : "HEAD";
+	return execFileSync("git", ["log", range, "--format=%s"], { cwd: root, encoding: "utf8" })
+		.split("\n")
+		.map((s) => s.trim())
+		.filter(Boolean);
+}
+
+/** @returns {string} current version from package.json */
+function currentVersion() {
+	const pkg = JSON.parse(readFileSync(PACKAGE_JSON, "utf8"));
+	if (!/^\d+\.\d+\.\d+$/.test(pkg.version ?? "")) throw new Error(`package.json has no semver version: ${pkg.version}`);
+	return pkg.version;
+}
+
+/** @param {string} arg @param {string} current */
+export function nextVersion(arg, current) {
+	const cur = current.split(".").map(Number);
+	if (arg === "major") return `${cur[0] + 1}.0.0`;
+	if (arg === "minor") return `${cur[0]}.${cur[1] + 1}.0`;
+	if (arg === "patch") return `${cur[0]}.${cur[1]}.${cur[2] + 1}`;
+	if (/^\d+\.\d+\.\d+$/.test(arg)) {
+		// Component-wise compare — lexicographic join(".") misorders "0.10.0" vs "0.5.2".
+		const parts = arg.split(".").map(Number);
+		for (let i = 0; i < 3; i++) {
+			if (parts[i] !== cur[i]) {
+				if (parts[i] < cur[i]) throw new Error(`version ${arg} is not greater than current ${current}`);
+				break;
+			}
+		}
+		if (arg === current) throw new Error(`version ${arg} is not greater than current ${current}`);
+		return arg;
+	}
+	throw new Error(`invalid version or bump type: ${arg} (expected patch/minor/major or X.Y.Z)`);
+}
+
+function main(argv) {
+	if (argv[0] === "verify") {
+		let result;
+		try {
+			const tag = lastTag();
+			const lines = tag ? commitSubjects(tag) : [];
+			const changelogText = existsSync(CHANGELOG_MD) ? readFileSync(CHANGELOG_MD, "utf8") : "";
+			result = verifyFrom({ lines, changelogText });
+			result.lastTag = tag;
+		} catch (err) {
+			// Fail-closed: a git/filesystem failure must block the release, not pass it.
+			result = { ok: false, error: String(err?.message ?? err), missing: [], extra: [], functionalCommits: 0, lastTag: null };
+		}
+		console.log(JSON.stringify(result));
+		process.exitCode = result.ok ? 0 : 1;
+		return;
+	}
+	const dryRun = argv.includes("--dry-run");
+	const versionArg = argv.find((a) => !a.startsWith("--")) ?? "patch";
+	try {
+	const current = currentVersion();
+	const version = nextVersion(versionArg, current);
+	const tag = lastTag();
+	const entries = parseCommitLines(tag ? commitSubjects(tag) : commitSubjects(null));
+	const date = new Date().toISOString().slice(0, 10);
+	const changelogPreview = generateChangelog({ version, date, entries, prevTag: tag });
+	const result = {
+		current_version: current,
+		new_version: version,
+		last_tag: tag,
+		changelog_summary: `${entries.filter((e) => e.type === "feat").length} features, ${entries.filter((e) => e.type === "fix").length} fixes, ${entries.filter((e) => !["feat", "fix"].includes(e.type)).length} changes`,
+		changelog_preview: changelogPreview,
+	};
+	if (!dryRun) {
+		const existing = existsSync(CHANGELOG_MD) ? readFileSync(CHANGELOG_MD, "utf8") : "# Changelog\n";
+		if (hasSection(existing, version)) {
+			throw new Error(`CHANGELOG.md already has a [${version}] section; remove the stale section before re-applying`);
+		}
+		writeFileSync(CHANGELOG_MD, insertSection(existing, changelogPreview));
+		result.files_modified = ["CHANGELOG.md"];
+	}
+	console.log(JSON.stringify(result, null, 1));
+	} catch (err) {
+		console.log(JSON.stringify({ error: String(err?.message ?? err) }));
+		process.exitCode = 1;
+	}
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+	main(process.argv.slice(2));
+}

package/src/commands/agent-board.ts

@@ -9,6 +9,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 import { requestDashboardRender } from "../core/dashboard-render.mjs";
 import { createService } from "../runtime/service.mjs";
+import { planAttachPrelude, planAttachResolved } from "./attach-decision.mjs";
 import { screenLogPath } from "../core/paths.mjs";
 import { DashboardComponent, type DashboardResult } from "../ui/dashboard.js";
 import { PtyAttachComponent, type PtyAttachResult } from "../ui/pty-attach.js";
@@ -161,54 +162,56 @@ async function attach(
 		ctx.ui.notify("Session no longer exists.", "warning");
 		return { action: "none" };
 	}
-	if (stopFirst && row.alive && !row.hostAlive) {
+	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);
-	} else if (row.alive && !row.hostAlive) {
-		ctx.ui.notify("Session is still running. Stop it before attaching, or confirm from the dashboard.", "warning");
-		return { action: "none" };
 	}
 
-	const target = service.attachTarget(viewId);
-	if (target.kind === "pty" && target.socketPath) {
+	// Single async resolver entry: real probe + bounded recovery decide readiness (issue #70).
+	const plan = planAttachResolved(await service.resolveAttachTarget(viewId));
+	if (plan.plan === "open-pty") {
 		service.markVisited?.(viewId);
-		const result = await openPtyAttach(ctx, root, row.meta.id, row.meta.name, target.socketPath);
+		const result = await openPtyAttach(ctx, root, row.meta.id, row.meta.name, plan.socketPath);
 		service.markVisited?.(viewId);
 		return { action: result.action === "closed" ? "closed" : "detached" };
 	}
-
-	const ensured = service.ensureHost(viewId);
-	if (ensured.ok && ensured.socketPath) {
+	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;
 		service.markVisited?.(viewId);
-		const result = await openPtyAttach(ctx, root, row.meta.id, row.meta.name, ensured.socketPath);
-		service.markVisited?.(viewId);
-		return { action: result.action === "closed" ? "closed" : "detached" };
-	}
-
-	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 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" };
 	}
-	const name = latest.meta.name;
-	service.markVisited?.(viewId);
-	const switchingOverlay = await showSwitchingOverlay(ctx, name, ensured.fallbackReason ?? ensured.error ?? "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");
+	if (plan.plan === "notify-pending") {
+		ctx.ui.notify(plan.reason, "info");
 		return { action: "none" };
 	}
-	return { action: "switched" };
+	ctx.ui.notify("Session no longer exists.", "warning");
+	return { action: "none" };
 }
 
 async function openPtyAttach(

package/src/commands/attach-decision.mjs

@@ -0,0 +1,66 @@
+/**
+ * Attach decision tables for the agent-board attach flow (issue #70).
+ *
+ * Pure mapping functions extracted from the two near-duplicate attach()
+ * implementations (src/commands/attach-flow.ts and the private copy in
+ * src/commands/agent-board.ts) so the branching contract is node-testable.
+ * Both TS files consume these for their prelude and resolver-result
+ * branching; they must stay free of I/O, service calls, and UI.
+ */
+
+/** Default message surfaced when the resolver reports pending without a reason. */
+export const ATTACH_PENDING_DEFAULT_MESSAGE = "Session host is starting — try again shortly.";
+
+/**
+ * Prelude facts as observed from a dashboard row.
+ * @typedef {{ rowAlive: boolean, rowHostActive: boolean, stopFirst: boolean }} AttachPreludeFacts
+ */
+
+/**
+ * Map the attach prelude guards to a plan.
+ *
+ * The prelude only guards live JSON-runner rows (alive with no host claim):
+ * a row with an active host (starting/alive/stopping) passes straight
+ * through to the async resolver — attaching must not block or warn while a
+ * host is starting (issue #70).
+ *
+ * @param {AttachPreludeFacts} facts
+ * @returns {{ plan: "warn-running" } | { plan: "stop-first" } | { plan: "proceed" }}
+ */
+export function planAttachPrelude({ rowAlive, rowHostActive, stopFirst }) {
+	if (rowAlive && !rowHostActive) {
+		return stopFirst ? { plan: "stop-first" } : { plan: "warn-running" };
+	}
+	return { plan: "proceed" };
+}
+
+/**
+ * Map a `resolveAttachTarget()` result to the attach action plan.
+ *
+ * `socketPath` is typed `string | null` upstream; a pty resolution without a
+ * usable path is a transient resolver inconsistency and maps to
+ * notify-pending (retry later) rather than a misleading "missing".
+ *
+ * @param {{ kind: "pty", socketPath: string | null, sessionFile?: string, instanceId?: string | null } |
+ *          { kind: "session", sessionFile: string } |
+ *          { kind: "pending", sessionFile?: string, reason?: string } |
+ *          { kind: "missing" }} resolved
+ * @returns {{ plan: "open-pty", socketPath: string } |
+ *           { plan: "session-switch", sessionFile: string } |
+ *           { plan: "notify-pending", reason: string } |
+ *           { plan: "notify-missing" }}
+ */
+export function planAttachResolved(resolved) {
+	switch (resolved?.kind) {
+		case "pty":
+			return resolved.socketPath != null
+				? { plan: "open-pty", socketPath: resolved.socketPath }
+				: { plan: "notify-pending", reason: ATTACH_PENDING_DEFAULT_MESSAGE };
+		case "session":
+			return { plan: "session-switch", sessionFile: resolved.sessionFile };
+		case "pending":
+			return { plan: "notify-pending", reason: resolved.reason ?? ATTACH_PENDING_DEFAULT_MESSAGE };
+		default:
+			return { plan: "notify-missing" };
+	}
+}

package/src/commands/attach-flow.ts

@@ -1,14 +1,17 @@
 /**
  * Reusable attach-flow helpers shared by the `agent-board` and `bg` commands.
  *
- * These are pure logic extractions — no runtime behaviour changes. Every
- * function here was previously private in agent-board.ts.
+ * Pure helpers (paths, prompts, current-view lookup) plus the resolver-driven
+ * attach flow: since issue #70 the attach path calls the async
+ * `resolveAttachTarget()` once and plans via `attach-decision.mjs`, instead of
+ * the old attachTarget-hint → ensureHost double path.
  */
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 import { createService } from "../runtime/service.mjs";
+import { planAttachPrelude, planAttachResolved } from "./attach-decision.mjs";
 import { screenLogPath } from "../core/paths.mjs";
 import { PtyAttachComponent, type PtyAttachResult } from "../ui/pty-attach.js";
 import type { DashboardResult } from "../ui/dashboard.js";
@@ -99,8 +102,10 @@ export function samePath(a: string, b: string): boolean {
 }
 
 /**
- * Attach to an agent session, preferring PTY if available and falling back to
- * a session-switch overlay.
+ * Attach to an agent session through the single async resolver entry point.
+ * PTY readiness is decided by `resolveAttachTarget()` (real connect + hello
+ * probe, with bounded recovery); this function only maps its result to UI
+ * actions (issue #70 — no more attachTarget-hint → ensureHost double path).
  */
 export async function attach(
 	ctx: ExtensionCommandContext,
@@ -114,54 +119,55 @@ export async function attach(
 		ctx.ui.notify("Session no longer exists.", "warning");
 		return { action: "none" };
 	}
-	if (stopFirst && row.alive && !row.hostAlive) {
+	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);
-	} else if (row.alive && !row.hostAlive) {
-		ctx.ui.notify("Session is still running. Stop it before attaching, or confirm from the dashboard.", "warning");
-		return { action: "none" };
 	}
 
-	const target = service.attachTarget(viewId);
-	if (target.kind === "pty" && target.socketPath) {
+	const plan = planAttachResolved(await service.resolveAttachTarget(viewId));
+	if (plan.plan === "open-pty") {
 		service.markVisited?.(viewId);
-		const result = await openPtyAttach(ctx, root, row.meta.id, row.meta.name, target.socketPath);
+		const result = await openPtyAttach(ctx, root, row.meta.id, row.meta.name, plan.socketPath);
 		service.markVisited?.(viewId);
 		return { action: result.action === "closed" ? "closed" : "detached" };
 	}
-
-	const ensured = service.ensureHost(viewId);
-	if (ensured.ok && ensured.socketPath) {
+	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;
 		service.markVisited?.(viewId);
-		const result = await openPtyAttach(ctx, root, row.meta.id, row.meta.name, ensured.socketPath);
-		service.markVisited?.(viewId);
-		return { action: result.action === "closed" ? "closed" : "detached" };
-	}
-
-	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 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, openDashboardFn);
+			},
+		}).finally(() => {
+			try {
+				switchingOverlay?.hide();
+			} catch {}
+		});
+		if (result.cancelled) {
+			ctx.ui.notify("Attach cancelled.", "warning");
+			return { action: "none" };
+		}
+		return { action: "switched" };
 	}
-	const name = latest.meta.name;
-	service.markVisited?.(viewId);
-	const switchingOverlay = await showSwitchingOverlay(ctx, name, ensured.fallbackReason ?? ensured.error ?? "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, openDashboardFn);
-		},
-	}).finally(() => {
-		try {
-			switchingOverlay?.hide();
-		} catch {}
-	});
-	if (result.cancelled) {
-		ctx.ui.notify("Attach cancelled.", "warning");
+	if (plan.plan === "notify-pending") {
+		ctx.ui.notify(plan.reason, "info");
 		return { action: "none" };
 	}
-	return { action: "switched" };
+	ctx.ui.notify("Session no longer exists.", "warning");
+	return { action: "none" };
 }
 
 /**