@zhuxixi/pi-agent-board 0.6.0 → 0.6.1

package/docs/superpowers/specs/2026-09-08-spawn-async-error-swallow-design.md

@@ -0,0 +1,56 @@
+# issue #86 spec：spawn 异步 error 兜底（spawnDetached 统一封装）
+
+日期：2026-09-08 · 状态：已授权全自动推进（用户 2026-09-08 决策）
+
+## 背景与问题
+
+`launch.mjs` 4 个启动函数与 `pty-attach.ts openExternalTarget()` 的 spawn 均为 `spawn(...)` + `unref()` 无 `'error'` listener。spawn 启动失败走异步 `'error'` 事件，EventEmitter 无 listener 的 error 直接 throw → uncaughtException → 整个 pi 宿主进程退出。实录：WSL2 上一次 node 二进制瞬时 ENOENT 直接带崩 pi（host.json 已正确落 failed，但进程没活下来走重试）。
+
+## 核心设计
+
+### D1：launch.mjs 新增内部 helper `spawnDetached`
+
+```js
+function spawnDetached(command, args, cwd) {
+    const child = spawn(command, args, { cwd, detached: true, stdio: "ignore", env: process.env, windowsHide: true });
+    child.on("error", () => {});   // 接住异步启动失败；调用方按 pid==null 记 failed，宿主不崩
+    child.unref();
+    return child;
+}
+```
+
+`launchRun` / `launchHost` / `launchTitle` / `launchAutoState` 四处收敛到该 helper。helper 不导出（模块内部实现细节，测试通过公开入口行为验证）。
+
+### D2：openExternalTarget 三分支补 error listener
+
+darwin/win32/其他三分支统一为 `const child = spawn(...); child.on("error", () => {}); child.unref();`。fire-and-forget 语义与返回值不变（打开链接是 best-effort，失败静默）。参照同文件 L847-848 xclip 既有正确模式。
+
+## 非目标
+
+- runner/*.mjs 内的 spawn（跑在分离 runner 进程里，崩了不拖垮 pi，issue 已明确排除）；
+- 顶层 `process.on("uncaughtException")` 兜底（会掩盖未知错误，不引入）；
+- 改变任何返回值/状态机语义。
+
+## 可测性拆分设计
+
+| 单元 | 性质 | 测法 |
+|---|---|---|
+| spawnDetached 异步 error 兜底 | 副作用隔离（仅 child_process） | integration：注入不存在 node 路径，断言返回 pid:null 且进程存活（uncaughtException listener 不触发；node:test 进程崩=测试天然失败） |
+| 4 个公开入口行为不变 | 公开 API | 复用现有 4 测试 + 新增 ENOENT 用例覆盖 launchRun/launchHost/launchTitle/launchAutoState |
+| openExternalTarget | UI 层（c8 阈值外，惯例冒烟保护） | 静态验证 error listener 存在；不单加测试 |
+
+## 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | spawn 失败不带崩进程（4 入口） | 自动化（integration） | `node --test test/launch.test.mjs` | 注入 `/nonexistent/node-ENOENT-test` 后各入口正常返回 pid:null，进程存活 |
+| A2 | 既有行为回归 | 自动化（integration） | `node --test test/launch.test.mjs` | 原 4 测试全绿 |
+| A3 | openExternalTarget error 兜底 | 自动化（static） | 代码审查 + grep 断言 | 三分支均有 error listener |
+| A4 | 全量回归 | 自动化（static/build） | `npm test` + `npm run typecheck` | 568+ 全绿、无类型错误 |
+| U1 | issue 复现脚本对照 | 自动化替代（A1 等价） | issue 自带复现脚本逻辑已并入 A1 | 见 A1 |
+
+U1 说明：issue 的复现脚本本质是"注入坏 node 路径 + uncaughtException 监听"，A1 测试完全等价覆盖，故不需要独立用户实测。无 U 类纯人工项。
+
+## 风险
+
+极低：纯增量兜底，不改成功路径任何行为；失败路径从"进程崩"变为"走既有 pid==null 记 failed 重试路径"。

package/docs/superpowers/specs/2026-09-08-stale-model-attach-guard-design.md

@@ -0,0 +1,79 @@
+# issue #90 spec：defaultModel 失效防护（launch 前校验 + child exit 归因）
+
+日期：2026-09-08 · 状态：已授权全自动推进（用户 2026-09-08 决策）
+
+## 背景与问题
+
+session 创建时记录的 `meta.defaultModel` 失效后（provider 前缀改名/移除），attach 走「launchHost → child --model 失效 → exit 1 → host exited → 再 attach 再 launch」死循环（实录单 view 数百次 launch_host）。且 runner child exit 不写 error 字段（pty-runner.mjs L217），host.json 只有 exitCode:1 无任何归因线索。
+
+## 核心设计
+
+### D1：launch 前模型校验（断死循环）
+
+1. **core 导出匹配函数**（`src/core/launch-options.mjs`）：
+```js
+/**
+ * Whether a stored model reference resolves to a currently-available model.
+ * Same rule as the dashboard launch picker: case-insensitive exact "provider/id".
+ * @param {string|null|undefined} modelRef
+ * @param {Array<{provider: string, id: string}>|undefined|null} availableModels
+ * @returns {boolean} true when modelRef is empty/null (no constraint) or matched.
+ */
+export function modelRefAvailable(modelRef, availableModels)
+```
+`modelRef` 空 → true（无校验对象）；`availableModels` 空/undefined → true（调用方无法判断时保守放行，不制造新阻塞）。
+
+2. **service 注入**：`createService` 新增 `opts.availableModels`（`() => Array<{provider,id}>`，每次调用实时取值；默认 undefined → 跳过校验）。`src/index.ts` serviceFor 与 `src/commands/agent-board.ts` flag 路径注入 `() => ctx.modelRegistry.getAvailable()`（try/catch → undefined，对齐 agent-board.ts L75-79 现有防御模式）。
+
+3. **统一校验 helper**（service.mjs 模块内）：`validateViewModelMeta(meta) → null | string`（null=通过；string=错误消息）。错误消息明确可行动：`Model "X" configured for this session is no longer available — update the view's model or clear defaultModel, then retry attach.`
+
+4. **两个校验点**（service.mjs 仅有的 host spawn 路径）：
+   - `startHostUnderLease`：在 claim 之前校验（首选；若代码结构上 claim 已发生，则落 failed 清理后返回）→ `{ ok: false, error }`；
+   - `adoptClaimedHost`：claim 是既有废弃记录 → 校验失败时 `updateOwnedHost` 落 failed（error 带模型消息）+ 返回 pending。
+   - resolver 链路无需改动：ensureHostImpl 的 `{ ok:false, error }` 走现有 `pending(sessionFile, res.error)` → attach-flow notify 展示（渠道现成）。
+
+5. **dashboard.ts L1738 `findLaunchModelByRef` 改为复用 core 导出**（单一事实源；LaunchModel 结构类型 JSDoc 化）。
+
+### D2：child exit 错误归因（补线索）
+
+1. **纯函数**（`src/core/heuristics.mjs` 新增导出）：`lastVisibleLogLine(text, maxLen = 200)`——strip ANSI（CSI `\x1b\[[0-9;?]*[ -/]*[@-~]` + OSC `\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)` + 杂项转义），按行切分，返回最后一个非空可见行（`\r` 处理：取每行最后一个 `\r` 段），截断 maxLen。空输入/全空 → null。
+2. **runner 接线**（`runner/pty-runner.mjs` child exit 回调 L213-223）：`exitCode != null && exitCode !== 0` 时 best-effort（try/catch 包裹，绝不影响 exit 路径）读 screen.log 尾部 ~8KB（openSync/readSync seek 尾部，不整文件读）→ `lastVisibleLogLine` → 非 null 则 `update({ ..., error })`。exitCode=0 不改 error。
+
+## 非目标
+
+- **失败退避**（issue 建议 2）：D1 已断 spawn 死循环；通用退避需跨 claim 持久计数，复杂度/收益不划算，未来场景再单开；
+- **run 路径模型校验**（launchRun 的 model）：detach run 失败是一次性的，不循环——观察项；
+- **UI 改动**：notify 渠道现成；
+- 自动 fallback 到其他模型：静默换模型会让用户不知 session 行为已变，fail-fast + 明确提示更安全（issue 建议 1 的两个选项中选 fail-fast）。
+
+## 可测性拆分设计
+
+| 单元 | 位置 | 性质 | 测法 |
+|---|---|---|---|
+| `modelRefAvailable` | launch-options.mjs | 纯函数 | 真值表：大小写/null/空列表/部分匹配不匹配 |
+| `validateViewModelMeta` + ensure 路径 | service.mjs | 副作用隔离（注入 availableModels + launchHost spy） | integration：失效模型 → ok:false + launchHost 零调用 + 无 starting claim 残留；有效/null/未注入三对照 |
+| adopt 路径校验 | service.mjs | 同上 | integration：废弃 claim + 失效模型 → 落 failed + 不 spawn |
+| `lastVisibleLogLine` | heuristics.mjs | 纯函数 | 单测：ANSI/OSC/`\r`/空行/截断/空输入 |
+| runner exit 归因 | pty-runner.mjs | 集成 | pty-runner.integration.test.mjs 模式：fake child exit 1 + 预置 screen.log → host.json.error 含错误行；exit 0 → error 不变 |
+
+## 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | modelRefAvailable 匹配规则 | 自动化（unit） | `node --test test/launch-options.test.mjs`（或既有对应文件） | 真值表全过 |
+| A2 | 失效模型 attach 不再 spawn | 自动化（integration） | `node --test test/host-resolver.test.mjs` / service 测试 | ok:false、launchHost spy 零调用、无 starting claim 残留、error 消息含模型名 |
+| A3 | 有效模型/null 模型回归 | 自动化（integration） | 同上 | 正常 launch（claim → spawn） |
+| A4 | 未注入 availableModels 向后兼容 | 自动化（integration） | 同上 | 跳过校验正常 launch |
+| A5 | adopt 路径失效模型 | 自动化（integration） | 同上 | 落 failed + 不 spawn |
+| A6 | lastVisibleLogLine 提取 | 自动化（unit） | heuristics 测试 | ANSI/截断/空行用例全过 |
+| A7 | runner exit≠0 归因 | 自动化（integration） | runner 测试 | host.json.error 含 screen.log 尾部错误行；exit 0 不写 |
+| A8 | 全量回归 | 自动化（static/build） | `npm test` + `npm run typecheck` | 608+ 全绿 |
+| U1 | 真实失效 view 实测 | 用户实测 | 合并后：view_539a5e9e20 恢复失效 defaultModel=glm/glm-5.3 → attach → 观察 notify 与 diagnostics | notify 明确提示模型失效；diagnostics 不再累积 launch_host；改回有效模型后 attach 成功 |
+
+U1 需重启 pi（git 包不热重载），合并后由用户执行并回 issue 记录。
+
+## 风险与降级
+
+- availableModels 为空数组时保守放行（不制造新阻塞）——校验仅在能确定"失效"时拦截；
+- 校验失败路径每次 attach 仅一次文件级操作，无进程开销；
+- D2 全 try/catch best-effort，exit 路径行为不变。

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zhuxixi/pi-agent-board",
-	"version": "0.6.0",
+	"version": "0.6.1",
 	"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

@@ -122,6 +122,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() {} }));