@zhuxixi/pi-agent-board 0.6.0 → 0.6.2

package/docs/superpowers/specs/2026-09-09-claimpid-blocks-replace-design.md

@@ -0,0 +1,147 @@
+# Spec: exited host 的 claimPid 存活导致 attach 永久 pending（issue #99）
+
+## 背景
+
+dashboard 里对已退出的 session 点 attach，永远连不上：attach 一直转圈，最终超时提示 `host start timed out`。实测对象 `view_2472d82627`（host 已正常退出 `state: "exited"`，`exitCode: 0`），同机另有 `view_4b667ad75d`、`view_c038badb30` 两个 view 处于相同状态（exited + claimPid 存活），全部无法 attach。
+
+## 根因
+
+### 触发链条
+
+1. 用户从 dashboard（进程 P）attach session → `claimHost`（`src/core/store.mjs:172`）把 `claimPid` 记为 **dashboard 进程的 pid**（`claimPid: provisionalHost.claimPid ?? null`，即 service 进程 pid）
+2. pi 子进程正常退出（`pty-runner.mjs:262` `child.onExit` → `state: "exited"`）→ **退出路径不清除 claimPid**
+3. dashboard 进程 P 继续存活（用户一直开着 dashboard）
+4. 再次 attach → `startHostUnderLease`（`service.mjs:243`）替换 terminal host 前调 `canReplaceHost(observeHostForReplace(existing))`
+5. `observeHostForReplace`（`service.mjs:2006`）对 claim 角色用 `conservativeObservation(host.claimPid)`：**pid 活着 → `"unknown"`**
+6. `canReplaceHost`（`src/core/host-coordination.mjs:72`）要求 runner / child / claim 三角色都 `SAFE_TO_RELEASE`（`not_started | dead | foreign`），claim 为 `"unknown"` → **返回 false**
+7. → `pendingLaunchResult` → attach 循环等待直到 deadline → `pending(sessionFile, "host start timed out")`
+
+实机验证（node 直接调用 `canReplaceHost`）：
+
+```
+host.state: exited
+runnerPid 1004724 → dead
+childPid null → dead
+claimPid 1003423 → unknown   ← 阻塞点
+canReplaceHost → false
+```
+
+### claimPid 的语义（代码注释 + 测试确认）
+
+- **非 null = "launcher 可能还在 claim 和 spawn 之间"**：保护 mid-transaction，让 ensureHost/adopt 等 grace 窗口（`service.mjs:976` `withinGrace` 判定依赖 `claimPid != null`）
+- **recovery claim 用 `claimPid: null`**（`service.mjs:723-736`）：recovery 事务在 claim 落盘时已完成，spawning 是 adopter 的活；`host-recovery.test.mjs:317` 断言 `recovery claim must not carry a live claimPid`
+- **spawn 失败路径清除 claimPid**（`service.mjs:832, 869`）：failed fenced
+- **正常退出路径不清除** ← 缺口：host 进入 `exited` 后 claimPid 残留，而 claim 保护语义（launcher mid-transaction）在 host 已 terminal 时**不可能成立**（runner 都跑完退出了）
+
+### 为什么是 bug
+
+`canReplaceHost` 的 claim 角色检查在 host 已 terminal 的场景下过度保守。claim 保护只对 `starting` 状态有意义；host 为 `exited/failed` 时，claim 进程不可能还在启动它（启动要么成功——runner 跑过并退出，要么失败——failed fenced 已清 claimPid）。触发条件常见：**dashboard 进程存活 + host exited → 任何从 dashboard 启动又退出的 session 都无法再次 attach**。
+
+## 修复方案（选定：放宽 canReplaceHost 的 claim 角色判定）
+
+### 方案对比
+
+| 方案 | 改动 | 对存量坏记录 | 评价 |
+|------|------|-------------|------|
+| **A. canReplaceHost 放宽 claim 判定** | 纯函数（`host-coordination.mjs`）+ 调用方（`service.mjs`） | **立即生效**（下次 attach 即可替换） | ✅ 选定 |
+| B. terminal 时清除 claimPid | 改 pty-runner 退出路径多处 + recoverHost finalize | 无效（已存在的坏记录不会自动修复，需额外迁移机制） | 改动面大、覆盖不全 |
+| C. conservativeObservation 增加 host 状态感知 | 改观测函数签名（传入 host 状态） | 立即生效 | 污染通用观测函数语义：`conservativeObservation` 的职责是"保守判断单个 pid 是否活着"，让它感知 host 状态会把生命周期决策混进观测层，违背 service.mjs 里观测与决策分离的既有结构 |
+
+### 设计
+
+**1. `canReplaceHost`（`src/core/host-coordination.mjs:72`）判定改为**：host 已 terminal（exited/failed）+ runner/child 均 provably gone + 无 launch lease → 可替换，claim 角色不参与判定。
+
+```js
+export function canReplaceHost({ host, runnerObservation, childObservation, launchLeaseActive }) {
+	if (!host || (host.state !== "exited" && host.state !== "failed")) return false;
+	if (launchLeaseActive) return false;
+	// claim 角色不参与判定：claim 保护语义（launcher mid-transaction）只在 host
+	// 处于 starting 时有意义；host 已 terminal 时 claim 进程不可能还在启动它
+	// （启动要么成功——runner 跑过并退出，要么失败——failed fenced 已清 claimPid）。
+	return (
+		SAFE_TO_RELEASE.has(runnerObservation) &&
+		SAFE_TO_RELEASE.has(childObservation)
+	);
+}
+```
+
+**2. 同步移除 `claimObservation` 参数**（而非保留 unused 参数）：
+
+- `canReplaceHost` 签名从 `{host, runnerObservation, childObservation, claimObservation, launchLeaseActive}` 改为 `{host, runnerObservation, childObservation, launchLeaseActive}`
+- `observeHostForReplace`（`service.mjs:2006`，内部函数不导出）返回值移除 `claimObservation` 字段——少一次 `process.kill(pid, 0)` 系统调用
+- 既有测试用例同步移除 `claimObservation` 参数
+
+**取舍论证**（为什么移除而非保留 unused）：
+
+- `observeHostForReplace` 只有**一个**调用方（`service.mjs:243` 传给 `canReplaceHost`），且该函数是 service.mjs 内部函数不导出——无外部兼容性问题
+- 保留一个不参与判定的参数会让测试产生误导（传 `claimObservation: "unknown"` 的用例看起来期望 false，实际被忽略）
+- 移除后观测层少一次无用的 `isAlive` 系统调用
+
+### 改动文件
+
+| 文件 | 改动 |
+|------|------|
+| `src/core/host-coordination.mjs` | `canReplaceHost` 判定放宽 + 签名移除 `claimObservation` + JSDoc 更新 |
+| `src/runtime/service.mjs` | `observeHostForReplace` 返回值移除 `claimObservation` 字段 |
+| `test/host-coordination.test.mjs` | 既有 3 用例移除 `claimObservation` 参数；新增 A1-A5 用例 |
+| `test/host-resolver.test.mjs` | 新增 A6 集成测试 |
+
+### 安全性论证
+
+| 场景 | 分析 | 结论 |
+|------|------|------|
+| exited + claimPid 活着 | 只可能来自 runner 跑完退出（claim 事务早已完成） | 安全，**修复目标** |
+| failed + claimPid 活着 | runner 崩溃 / child spawn 失败（claim 事务已完成或 failed fenced 已清）；child 存活时 childObservation 仍阻塞 | 安全 |
+| runner 活着 | runnerObservation = "unknown" → 仍阻塞（不受影响） | 保守性保留 |
+| child 活着 | childObservation = "unknown" → 仍阻塞（不受影响） | 保守性保留 |
+| alive/starting host + claimPid 存活 | attach 直接到现有 host（probe ready → 返回 pty），**不经过 canReplaceHost** | 不受影响 |
+| recoverHost 并发 | recoverHost 与 startHostUnderLease 都在 host-start lease 内执行，互斥 | 无竞争 |
+| starting 状态 | canReplaceHost 对非 terminal 直接返回 false（不进入新判定） | 不受影响 |
+
+### 非目标
+
+- 不改 pty-runner 退出路径（方案 B 不做）
+- 不做存量 host.json 迁移/清理（方案 A 对存量记录天然生效）
+- 不改 `conservativeObservation`（其保守语义在 starting 场景仍需要）
+- 不改 dashboard UI、不改 host.json 结构（不加新字段）
+
+## 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | canReplaceHost：exited/failed + runner/child dead + **claimPid 存活** → 可替换（修复点） | 自动化验证（unit） | `node --test test/host-coordination.test.mjs` | 新增用例通过：`{host:{state:"exited"}, runner:"dead", child:"dead", lease:false}` → `true`；`{host:{state:"failed"}, ...}` 同 → `true` |
+| A2 | canReplaceHost：runner/child 任一 unknown 仍阻塞（保守性不破坏） | 自动化验证（unit） | 同上 | `runnerObservation:"unknown"` 或 `childObservation:"unknown"` 时返回 `false` |
+| A3 | canReplaceHost：launchLeaseActive 仍阻塞 | 自动化验证（unit） | 同上 | `launchLeaseActive: true` 时返回 `false`（既有用例回归） |
+| A4 | canReplaceHost：非 terminal host（starting/alive/stopping）仍拒绝 | 自动化验证（unit） | 同上 | 三个状态均返回 `false`（新增断言） |
+| A5 | canReplaceHost：SAFE_TO_RELEASE 边界回归——foreign/not_started → 可替换；host null → false | 自动化验证（unit） | 同上 | `runnerObservation:"foreign"` 或 `childObservation:"not_started"` 时返回 `true`；`host: null` 返回 `false` |
+| A6 | resolver 集成：exited host + 存活 claimPid → attach 启动新 host | 自动化验证（integration） | `node --test test/host-resolver.test.mjs` | 新增用例：构造 exited host 记录（`claimPid: process.pid`，存活），`resolveAttachTarget` 返回 `{kind:"pty"}` 且 spawn 恰好 1 次 |
+| U1 | 真实 dashboard 场景：attach 已退出 session（dashboard 进程存活） | 用户实测 | 见下方步骤 | attach 成功进入 session，历史消息正常显示，无超时提示 |
+
+**U1 实测步骤**：
+
+1. **重启 dashboard 进程**（加载新代码——方案 A 对存量坏记录的"立即生效"以重启为前提）
+2. 打开 dashboard，找到已知坏记录 `view_2472d82627`（issue-225 session，host `state: "exited"` + claimPid 存活）
+3. 点 attach → 观察：成功进入 session、历史消息正常显示、无 `host start timed out` 提示
+4. 退出 session，再 attach，确认可重复
+5. 同法验证 `view_4b667ad75d` / `view_c038badb30`（另两个 exited + claimPid 存活的 view）
+
+## 可测性拆分设计
+
+修复集中在 `canReplaceHost` 一个纯函数（`src/core/host-coordination.mjs`），无副作用、无 I/O，天然可单测：
+
+- **纯函数边界**：`canReplaceHost({host, runnerObservation, childObservation, launchLeaseActive})` → boolean。输入为纯数据快照，输出只依赖输入，不触碰 fs/进程/socket。
+- **观测与决策分离**：`observeHostForReplace`（`service.mjs:2006`）负责进程观测（`conservativeObservation`），`canReplaceHost` 负责决策。修复只动决策层；观测层移除 `claimObservation` 字段是配套清理（少一次无用的 `isAlive` 调用），不改变观测语义。
+- **测试边界**：
+  - `test/host-coordination.test.mjs`：A1-A5 全部在纯函数层覆盖（现有 `canReplaceHost refuses unknown observations` 用例扩展 + 新增用例）
+  - `test/host-resolver.test.mjs`：A6 走现有 `resolverService` + `healServiceOverrides` 基建（真实 ensureHostImpl claim + scripted probe），验证 attach 全链路（resolver → ensureHost → startHostUnderLease → canReplaceHost → spawn）
+
+## 风险与降级
+
+- **行为变化面**：仅放宽"exited/failed host 的替换判定"一个点；starting/alive/stopping 的 host 不经过 `canReplaceHost`；runner/child 存活的 host 仍阻塞。
+- **回归风险**：低。改动为纯函数内一个条件的放宽 + 配套签名清理，A2-A5 保证保守性不破坏。
+- **降级路径**：若 U1 实测发现异常，**revert 本 issue 的 commit 恢复原判定**（claim 角色重新参与判定）。
+
+## 环境
+
+- Linux x64，node v24.13.0，pi-agent-board main（0.6.1）
+- 2026-09-09 实机排查，`view_2472d82627` 现场取证（host.json / diagnostics.jsonl / ps 进程树）

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zhuxixi/pi-agent-board",
-	"version": "0.6.0",
+	"version": "0.6.2",
 	"description": "Agent-board dashboard for Pi: dispatch, monitor, peek/reply, and attach to background Pi sessions.",
 	"type": "module",
 	"main": "./index.ts",

package/runner/pty-runner.mjs

@@ -10,13 +10,14 @@
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { createServer } from "node:net";
-import { existsSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { closeSync, existsSync, fstatSync, openSync, readFileSync, readSync, statSync, unlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { appendLine, readJson } from "../src/core/atomic.mjs";
 import { appendDiagnostic } from "../src/core/diagnostics.mjs";
 import { finalizeHostCrash } from "../src/core/host-crash.mjs";
 import { ownsEndpoint, shouldYieldRunner } from "../src/core/host-coordination.mjs";
+import { lastVisibleLogLine } from "../src/core/heuristics.mjs";
 import { acquireOwnedViewLock } from "../src/core/locks.mjs";
 import * as P from "../src/core/paths.mjs";
 import { appendBoundedScreenLog, reconcileScreenLog } from "../src/core/screen-log.mjs";
@@ -39,6 +40,48 @@ const HEARTBEAT_MS = 1000;
 const HOST_ACK_DEDUP_MAX = 1000;
 /** Max time an owned runner waits to take the per-view host-start lease (issue #70). */
 const HOST_RUNNER_LOCK_WAIT_MS = 5_000;
+/** How much of the screen.log tail to scan when attributing an abnormal child
+ *  exit (issue #90). Tail-only: the log can be 100MB+. */
+const EXIT_LOG_TAIL_BYTES = 8_192;
+
+/** Tail-read the last `maxBytes` of a file without loading it whole.
+ * @param {string} path
+ * @param {number} maxBytes
+ * @returns {string}
+ */
+function readScreenLogTail(path, maxBytes) {
+	let fd;
+	try {
+		fd = openSync(path, "r");
+		const size = fstatSync(fd).size;
+		const start = Math.max(0, size - maxBytes);
+		const length = size - start;
+		const buffer = Buffer.allocUnsafe(length);
+		readSync(fd, buffer, 0, length, start);
+		return buffer.toString("utf8");
+	} finally {
+		try { if (fd != null) closeSync(fd); } catch { /* best effort */ }
+	}
+}
+
+/**
+ * Best-effort error attribution for an abnormal child exit (issue #90): the
+ * child's failure reason (e.g. "Model X not found") exists only in the raw
+ * screen log, so surface its last visible line in host.json.error. Never
+ * throws — this runs on the exit path.
+ * @param {number} exitCode
+ * @param {string} screenLogPath
+ * @returns {{} | { error: string }}
+ */
+function attributedExitError(exitCode, screenLogPath) {
+	if (exitCode === 0) return {};
+	try {
+		const line = lastVisibleLogLine(readScreenLogTail(screenLogPath, EXIT_LOG_TAIL_BYTES));
+		return line ? { error: line } : {};
+	} catch {
+		return {};
+	}
+}
 
 function main() {
 	const configPath = process.argv[2];
@@ -214,7 +257,9 @@ function legacyMain(config) {
 		// After a crash the handler already persisted "failed" and broadcast
 		// exit; this callback must not overwrite that state.
 		if (!crashed) {
-			update({ state: "exited", endedAt: Date.now(), exitCode, childPid: null });
+			// Attribute only a NATURAL abnormal exit (issue #90): after a deliberate
+			// stop (shutdownStarted) the child was killed by us — no error line.
+			update({ state: "exited", endedAt: Date.now(), exitCode, childPid: null, ...(shutdownStarted ? {} : attributedExitError(exitCode, screenLog)) });
 			editorEmpty = null;
 			broadcast({ type: "editor_state", empty: null });
 			broadcast({ type: "exit", exitCode });
@@ -512,6 +557,13 @@ async function ownedMain(config) {
 				readyAt: null,
 				stopRequestedAt: null,
 				stopReason: reason,
+				// Attribute abnormal NATURAL child exits only (issue #90): reason
+				// "child_exit" with a non-zero code. Stops ("signal") and crashes
+				// have their own attribution (stopReason / crash finalize), and a
+				// SIGTERM'd healthy child must not capture a junk error line.
+				...(reason === "child_exit" && cur.error == null
+					? attributedExitError(requestedExitCode ?? exitCode ?? 0, screenLog)
+					: {}),
 			}));
 		}
 		// Endpoint cleanup: only the exact inode this instance bound.

package/src/commands/agent-board.ts

@@ -42,6 +42,15 @@ export function registerAgentBoardCommand(pi: ExtensionAPI, opts: AgentBoardComm
 				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) {

package/src/commands/bg.ts

@@ -40,6 +40,15 @@ async function handleBgCommand(args: string, ctx: ExtensionCommandContext, opts:
 		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;
+			}
+		},
 	});
 	const model = modelRef(ctx.model as any);
 	const adopted = service.adoptSession({

package/src/core/heuristics.mjs

@@ -259,6 +259,41 @@ export function truncate(s, n) {
 	return `${stripLoneSurrogates(str.slice(0, end))}…`;
 }
 
+const OSC_SEQUENCE_RE = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+const CSI_SEQUENCE_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const OTHER_ESCAPE_RE = /\x1b./g;
+
+/**
+ * Last non-empty visible line of a raw terminal log chunk: strips OSC/CSI/ESC
+ * escape sequences, resolves per-line carriage-return overwrites (progress
+ * bars / boot spinners), and returns the final remaining line truncated to
+ * `maxLen`. Used to attribute a failed child's exit reason from screen.log
+ * into host.json (issue #90). Returns null for empty/all-invisible input.
+ * @param {string|null|undefined} text
+ * @param {number} [maxLen]
+ * @returns {string|null}
+ */
+export function lastVisibleLogLine(text, maxLen = 200) {
+	if (!text) return null;
+	const visible = String(text)
+		.replace(OSC_SEQUENCE_RE, "")
+		.replace(CSI_SEQUENCE_RE, "")
+		.replace(OTHER_ESCAPE_RE, "")
+		// A \r directly before \n is a line terminator (CRLF), not an overwrite
+		// marker — normalize it away so the line content survives.
+		.replace(/\r\n/g, "\n");
+	const lines = visible.split("\n");
+	for (let i = lines.length - 1; i >= 0; i--) {
+		// Trailing \r chars are line-terminator junk (PTY ONLCR + the program's own
+		// CRLF stack up as \r\r\n) — drop them, then resolve interior \r overwrites.
+		const cleaned = lines[i].replace(/\r+$/, "");
+		const cr = cleaned.lastIndexOf("\r");
+		const line = (cr >= 0 ? cleaned.slice(cr + 1) : cleaned).trim();
+		if (line) return truncate(line, maxLen);
+	}
+	return null;
+}
+
 /**
  * Compact relative age, e.g. "10s", "2m", "3h", "4d".
  * @param {number} fromMs

package/src/core/host-coordination.mjs

@@ -57,25 +57,27 @@ export function processIdentityState(identity, observed, spawnedAt) {
 const SAFE_TO_RELEASE = new Set(["not_started", "dead", "foreign"]);
 
 /**
- * Whether an exited/failed host can be replaced by a new claim. Every role
- * (runner, child, provisional-claim launcher) must be provably gone; any
- * `unknown` observation or an active launch lease blocks replacement.
+ * Whether an exited/failed host can be replaced by a new claim. The runner and
+ * child roles must be provably gone; any `unknown` observation or an active
+ * launch lease blocks replacement. The claim role does NOT participate: claim
+ * protection (a launcher mid-transaction between claim and spawn) only matters
+ * while the host is `starting`, and this gate only ever sees terminal hosts —
+ * a terminal host cannot still be being launched (issue #99: a live claimPid —
+ * the dashboard process that wrote the claim — must not block re-attach).
  * @param {{
  *   host: HostStatus|null|undefined,
  *   runnerObservation: string,
  *   childObservation: string,
- *   claimObservation: string,
  *   launchLeaseActive: boolean,
  * }} input
  * @returns {boolean}
  */
-export function canReplaceHost({ host, runnerObservation, childObservation, claimObservation, launchLeaseActive }) {
+export function canReplaceHost({ host, runnerObservation, childObservation, launchLeaseActive }) {
 	if (!host || (host.state !== "exited" && host.state !== "failed")) return false;
 	if (launchLeaseActive) return false;
 	return (
 		SAFE_TO_RELEASE.has(runnerObservation) &&
-		SAFE_TO_RELEASE.has(childObservation) &&
-		SAFE_TO_RELEASE.has(claimObservation)
+		SAFE_TO_RELEASE.has(childObservation)
 	);
 }
 
@@ -122,6 +124,29 @@ export function classifyProbeResult(result) {
 	return "starting";
 }
 
+/**
+ * Whether a legacy (pre-instanceId) host record can be safely finalized as
+ * `exited` so the next attach claims a fresh host. Spec §10.1 keeps legacy
+ * hosts unrecovered because their identity is unverifiable — but a provably
+ * dead runner pid IS a certain identity (a reused pid reads alive, which
+ * conservatively lands here as false), and an unreachable endpoint (missing
+ * socket file / refused socket) rules out a merely slow host. All four
+ * conditions must hold at once (issue #87).
+ * @param {{
+ *   host: HostStatus|null|undefined,
+ *   hostPid: number|null|undefined,
+ *   hostPidAlive: boolean,
+ *   probeClassification: string,
+ * }} input
+ * @returns {boolean}
+ */
+export function canFinalizeLegacyHost({ host, hostPid, hostPidAlive, probeClassification }) {
+	if (!host || host.instanceId != null) return false;
+	if (host.state !== "starting" && host.state !== "alive") return false;
+	if (hostPid == null || hostPidAlive) return false;
+	return probeClassification === "missing" || probeClassification === "stale";
+}
+
 /** Host states in which a claim exists and must not be duplicated. */
 const ACTIVE_STATES = new Set(["starting", "alive", "stopping"]);
 

package/src/core/launch-options.mjs

@@ -43,6 +43,23 @@ export function canonicalModelRef(model) {
 	return model ? `${model.provider}/${model.id}` : "";
 }
 
+/**
+ * Whether a stored model reference resolves to a currently-available model.
+ * Same rule as the dashboard launch picker: case-insensitive exact "provider/id".
+ * A null/empty reference is trivially available (no constraint), and an
+ * empty/unavailable model list must not block launches (the caller cannot judge
+ * availability, so the conservative answer is allow — issue #90).
+ * @param {string|null|undefined} modelRef
+ * @param {LaunchModelLike[]|undefined|null} availableModels
+ * @returns {boolean}
+ */
+export function modelRefAvailable(modelRef, availableModels) {
+	const ref = String(modelRef ?? "").trim().toLowerCase();
+	if (!ref) return true;
+	if (!availableModels || availableModels.length === 0) return true;
+	return availableModels.some((model) => `${model.provider}/${model.id}`.toLowerCase() === ref);
+}
+
 /** @param {LaunchModelLike|null|undefined} a @param {LaunchModelLike|null|undefined} b */
 export function sameModel(a, b) {
 	return Boolean(a && b && a.provider === b.provider && a.id === b.id);

package/src/core/launch.mjs

@@ -16,6 +16,34 @@ import { writePid } from "./store.mjs";
 /** @typedef {import("./types.mjs").TitleConfig} TitleConfig */
 /** @typedef {import("./types.mjs").AutoStateConfig} AutoStateConfig */
 
+/**
+ * Spawn a fully detached runner child with async spawn failures made harmless.
+ *
+ * A spawn that fails to start (e.g. a transient ENOENT on the node binary,
+ * issue #86) reports asynchronously via the 'error' event; without a listener
+ * the EventEmitter rethrows it as an uncaughtException and takes down the
+ * whole host Pi process. Callers already handle the failure gracefully via
+ * the pid == null branch (state "failed").
+ * @param {string} command
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {import("node:child_process").ChildProcess}
+ */
+function spawnDetached(command, args, cwd) {
+	const child = spawn(command, args, {
+		cwd,
+		detached: true,
+		stdio: "ignore",
+		env: process.env,
+		// Windows: detached children get their own console window unless
+		// suppressed (CREATE_NO_WINDOW; no-op on POSIX) — issue #49.
+		windowsHide: true,
+	});
+	child.on("error", () => {});
+	child.unref();
+	return child;
+}
+
 /**
  * @param {string} root
  * @param {RunConfig} config
@@ -28,16 +56,7 @@ export function launchRun(root, config, opts) {
 	atomicWriteJson(configPath, config);
 
 	const node = opts.node ?? resolveNode();
-	const child = spawn(node, [opts.runnerScript, configPath], {
-		cwd: config.cwd,
-		detached: true,
-		stdio: "ignore",
-		env: process.env,
-		// Windows: detached children get their own console window unless
-		// suppressed (CREATE_NO_WINDOW; no-op on POSIX) — issue #49.
-		windowsHide: true,
-	});
-	child.unref();
+	const child = spawnDetached(node, [opts.runnerScript, configPath], config.cwd);
 
 	const pid = child.pid ?? null;
 	// Record the *runner/monitor* pid for liveness polling (the worker pid is tracked
@@ -61,14 +80,7 @@ export function launchHost(root, config, opts) {
 	atomicWriteJson(configPath, config);
 
 	const node = opts.node ?? resolveNode();
-	const child = spawn(node, [opts.runnerScript, configPath], {
-		cwd: config.cwd,
-		detached: true,
-		stdio: "ignore",
-		env: process.env,
-		windowsHide: true,
-	});
-	child.unref();
+	const child = spawnDetached(node, [opts.runnerScript, configPath], config.cwd);
 
 	return { pid: child.pid ?? null, configPath };
 }
@@ -86,14 +98,7 @@ export function launchTitle(root, config, opts) {
 	atomicWriteJson(configPath, config);
 
 	const node = opts.node ?? resolveNode();
-	const child = spawn(node, [opts.runnerScript, configPath], {
-		cwd: config.cwd,
-		detached: true,
-		stdio: "ignore",
-		env: process.env,
-		windowsHide: true,
-	});
-	child.unref();
+	const child = spawnDetached(node, [opts.runnerScript, configPath], config.cwd);
 
 	return { pid: child.pid ?? null, configPath };
 }
@@ -111,14 +116,7 @@ export function launchAutoState(root, config, opts) {
 	atomicWriteJson(configPath, config);
 
 	const node = opts.node ?? resolveNode();
-	const child = spawn(node, [opts.runnerScript, configPath], {
-		cwd: config.cwd,
-		detached: true,
-		stdio: "ignore",
-		env: process.env,
-		windowsHide: true,
-	});
-	child.unref();
+	const child = spawnDetached(node, [opts.runnerScript, configPath], config.cwd);
 
 	return { pid: child.pid ?? null, configPath };
 }

package/src/index.ts

@@ -76,8 +76,17 @@ export default function piAgentBoard(pi: ExtensionAPI): void {
 	});
 
 	// Footer status: reconcile stale rows and surface how many need attention.
+	// Live model list for the stale-defaultModel launch guard (issue #90); the
+	// service calls it per validation, and undefined conservatively skips.
+	const availableModelsFor = (ctx: ExtensionContext) => () => {
+		try {
+			return ctx.modelRegistry.getAvailable();
+		} catch {
+			return undefined;
+		}
+	};
 	const serviceFor = (ctx: ExtensionContext) =>
-		createService({ root, runnerScript: RUNNER_SCRIPT, ptyRunnerScript: PTY_RUNNER_SCRIPT, titleRunnerScript: TITLE_RUNNER_SCRIPT, autoStateRunnerScript: AUTO_STATE_RUNNER_SCRIPT, piCommand, piArgsPrefix, defaultCwd: ctx.cwd });
+		createService({ root, runnerScript: RUNNER_SCRIPT, ptyRunnerScript: PTY_RUNNER_SCRIPT, titleRunnerScript: TITLE_RUNNER_SCRIPT, autoStateRunnerScript: AUTO_STATE_RUNNER_SCRIPT, piCommand, piArgsPrefix, defaultCwd: ctx.cwd, availableModels: availableModelsFor(ctx) });
 
 	const updateStatus = (ctx: ExtensionContext) => {
 		try {
@@ -112,7 +121,7 @@ export default function piAgentBoard(pi: ExtensionAPI): void {
 		}
 		updateStatus(ctx);
 		if (event.reason === "startup" && !isHostedChild && pi.getFlag("agent-board") === true && ctx.hasUI) {
-			const service = createService({ root, runnerScript: RUNNER_SCRIPT, ptyRunnerScript: PTY_RUNNER_SCRIPT, titleRunnerScript: TITLE_RUNNER_SCRIPT, autoStateRunnerScript: AUTO_STATE_RUNNER_SCRIPT, piCommand, piArgsPrefix, defaultCwd: ctx.cwd });
+			const service = createService({ root, runnerScript: RUNNER_SCRIPT, ptyRunnerScript: PTY_RUNNER_SCRIPT, titleRunnerScript: TITLE_RUNNER_SCRIPT, autoStateRunnerScript: AUTO_STATE_RUNNER_SCRIPT, piCommand, piArgsPrefix, defaultCwd: ctx.cwd, availableModels: availableModelsFor(ctx) });
 			service.reconcile();
 			ctx.ui.setWorkingVisible(false);
 			ctx.ui.setHeader(() => ({ render: () => [], invalidate() {} }));