@zhuxixi/pi-agent-board 0.6.0 → 0.6.2

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

@@ -0,0 +1,267 @@
+# claimPid-Blocks-Replace Fix Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Fix issue #99 — an exited/failed host whose `claimPid` (the dashboard process) is still alive must be replaceable, so attach no longer pends to `host start timed out`.
+
+**Architecture:** The fix relaxes one pure decision function (`canReplaceHost` in `src/core/host-coordination.mjs`): the claim role no longer participates in the replacement gate for terminal hosts, because claim protection (a launcher mid-transaction between claim and spawn) only matters while a host is `starting`. The observation helper (`observeHostForReplace` in `src/runtime/service.mjs`) drops its now-unused `claimObservation` field.
+
+**Tech Stack:** Node.js (node:test, node:assert/strict), plain ESM modules, no new dependencies.
+
+**Spec:** `docs/superpowers/specs/2026-09-09-claimpid-blocks-replace-design.md`
+
+## Global Constraints
+
+- Change only the claim-role gate semantics; runner/child unknown observations must still block replacement (spec A2), `launchLeaseActive` must still block (spec A3), non-terminal hosts must still refuse (spec A4).
+- `canReplaceHost` signature loses `claimObservation`; `observeHostForReplace` stops computing it (one fewer `process.kill(pid, 0)` syscall).
+- All existing tests in `test/host-coordination.test.mjs` and `test/host-resolver.test.mjs` must keep passing (no behavioral regressions outside the claim-role gate).
+- `npm run typecheck` must pass (service.mjs is .mjs but the repo runs tsc over TS sources; keep JSDoc types consistent).
+- No changes to pty-runner.mjs, store.mjs, or host.json structure (spec non-goals).
+
+## Acceptance traceability
+
+| Spec ID | Plan coverage |
+|---------|---------------|
+| A1 (exited/failed + live claimPid → replaceable) | Task 1 Step 1 test `canReplaceHost allows replacing a terminal host whose claimPid is still alive` |
+| A2 (runner/child unknown still blocks) | Task 1 Step 1 test `canReplaceHost still refuses unknown runner/child observations` + legacy case 1 of `canReplaceHost refuses unknown observations` |
+| A3 (launchLeaseActive still blocks) | Task 1 Step 1 legacy case 3 of `canReplaceHost refuses unknown observations` |
+| A4 (non-terminal hosts refuse; host null) | Task 1 Step 1 test `canReplaceHost refuses non-terminal hosts and null host` |
+| A5 (foreign/not_started releasable) | Task 1 Step 1 test `canReplaceHost SAFE_TO_RELEASE boundary regression` |
+| A6 (resolver integration: exited + live claimPid → new host) | Task 2 |
+| U1 (real dashboard attach) | Post-implementation manual task (Task 3) |
+
+---
+
+### Task 1: Relax `canReplaceHost` claim-role gate + drop `claimObservation` (A1-A5)
+
+**Files:**
+- Modify: `src/core/host-coordination.mjs:60-80` (canReplaceHost + its JSDoc)
+- Modify: `src/runtime/service.mjs:2006-2013` (observeHostForReplace)
+- Test: `test/host-coordination.test.mjs:30-35`
+
+**Interfaces:**
+- Consumes: `SAFE_TO_RELEASE` set (already defined at `host-coordination.mjs:57`).
+- Produces: `canReplaceHost({ host, runnerObservation, childObservation, launchLeaseActive }) → boolean` — the `claimObservation` parameter is REMOVED. Sole caller `observeHostForReplace` (service.mjs, internal, not exported) stops passing it. Task 2's integration test relies on this behavior only indirectly (through `resolveAttachTarget`), so no signature dependency.
+
+- [ ] **Step 1: Write the failing tests**
+
+In `test/host-coordination.test.mjs`, first EDIT the existing `canReplaceHost refuses unknown observations` test (line 30-35) to drop the `claimObservation` argument from all three assertions (the parameter is being removed):
+
+```js
+test("canReplaceHost refuses unknown observations", () => {
+	const host = { state: "failed" };
+	assert.equal(canReplaceHost({ host, runnerObservation: "unknown", childObservation: "dead", launchLeaseActive: false }), false);
+	assert.equal(canReplaceHost({ host, runnerObservation: "dead", childObservation: "not_started", launchLeaseActive: false }), true);
+	assert.equal(canReplaceHost({ host, runnerObservation: "dead", childObservation: "dead", launchLeaseActive: true }), false);
+});
+```
+
+Then ADD these four tests right after it:
+
+```js
+test("canReplaceHost allows replacing a terminal host whose claimPid is still alive (issue #99)", () => {
+	// The bug: an exited/failed host keeps its claimPid (the dashboard process
+	// that wrote the claim), and a live pid observed as "unknown" used to block
+	// replacement forever — attach pended to "host start timed out". Claim
+	// protection only matters while a claim is mid-transaction (state
+	// "starting"); a terminal host cannot still be being launched.
+	assert.equal(canReplaceHost({ host: { state: "exited" }, runnerObservation: "dead", childObservation: "dead", launchLeaseActive: false }), true);
+	assert.equal(canReplaceHost({ host: { state: "failed" }, runnerObservation: "dead", childObservation: "dead", launchLeaseActive: false }), true);
+});
+
+test("canReplaceHost still refuses unknown runner/child observations (issue #99 conservatism)", () => {
+	assert.equal(canReplaceHost({ host: { state: "exited" }, runnerObservation: "unknown", childObservation: "dead", launchLeaseActive: false }), false);
+	assert.equal(canReplaceHost({ host: { state: "exited" }, runnerObservation: "dead", childObservation: "unknown", launchLeaseActive: false }), false);
+	assert.equal(canReplaceHost({ host: { state: "failed" }, runnerObservation: "unknown", childObservation: "unknown", launchLeaseActive: false }), false);
+});
+
+test("canReplaceHost refuses non-terminal hosts and null host (issue #99)", () => {
+	for (const state of ["starting", "alive", "stopping"]) {
+		assert.equal(canReplaceHost({ host: { state }, runnerObservation: "dead", childObservation: "dead", launchLeaseActive: false }), false, `state ${state} must refuse`);
+	}
+	assert.equal(canReplaceHost({ host: null, runnerObservation: "dead", childObservation: "dead", launchLeaseActive: false }), false);
+});
+
+test("canReplaceHost SAFE_TO_RELEASE boundary regression (issue #99)", () => {
+	assert.equal(canReplaceHost({ host: { state: "exited" }, runnerObservation: "foreign", childObservation: "dead", launchLeaseActive: false }), true, "foreign runner (pid reuse) is releasable");
+	assert.equal(canReplaceHost({ host: { state: "exited" }, runnerObservation: "not_started", childObservation: "not_started", launchLeaseActive: false }), true);
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `node --test test/host-coordination.test.mjs 2>&1 | tail -30`
+Expected: FAIL — the first new test fails (`exited` + dead runner/child returns `false` under the old three-role gate). The edited legacy test fails too: the old implementation ignores the removed `claimObservation` key but still requires `claimObservation` in SAFE_TO_RELEASE via `undefined → not in set → false`… actually with `claimObservation` absent, `SAFE_TO_RELEASE.has(undefined)` is `false`, so case 2 of the legacy test (`"dead"` args → expected `true`) FAILS under the old code. Both failures prove the tests exercise the gate.
+
+- [ ] **Step 3: Implement the relaxation**
+
+In `src/core/host-coordination.mjs`, replace the `canReplaceHost` function (lines ~63-80) with:
+
+```js
+/**
+ * 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,
+ *   launchLeaseActive: boolean,
+ * }} input
+ * @returns {boolean}
+ */
+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)
+	);
+}
+```
+
+In `src/runtime/service.mjs`, edit `observeHostForReplace` (line ~2006) to drop the `claimObservation` line:
+
+```js
+/** @param {import("../core/types.mjs").HostStatus|null} host */
+function observeHostForReplace(host) {
+	return {
+		host,
+		runnerObservation: conservativeObservation(host?.runnerPid ?? null),
+		childObservation: conservativeObservation(host?.childPid ?? null),
+		launchLeaseActive: false,
+	};
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `node --test test/host-coordination.test.mjs 2>&1 | tail -10`
+Expected: PASS — all tests in the file pass (4 new + edited legacy + all untouched).
+
+Run: `node --test test/host-resolver.test.mjs test/host-recovery.test.mjs test/host-crash.test.mjs 2>&1 | tail -10`
+Expected: PASS — no regressions in adjacent host suites.
+
+Run: `npm run typecheck`
+Expected: exit 0.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/host-coordination.mjs src/runtime/service.mjs test/host-coordination.test.mjs
+git commit -m "fix(host): claim role no longer blocks terminal host replacement (#99)"
+```
+
+---
+
+### Task 2: Resolver integration test — exited host + live claimPid attaches via fresh spawn (A6)
+
+**Files:**
+- Test: `test/host-resolver.test.mjs` (add one test after the `resolver finalizes a provably-dead legacy alive host` test, ~line 163)
+
+**Interfaces:**
+- Consumes: existing helpers `freshRoot`, `resolverService`, `healServiceOverrides(probe, spawns)`, `scriptProbe(seq)`, `hostRecord(root, viewId, over)` (defaults `claimPid: process.pid` — exactly the live-claimer shape), `createView` (returns `{ sessionFile, ... }`), and `writeFileSync` (already imported). Task 1's relaxed `canReplaceHost` must be in place — this test verifies the full attach chain (resolver → ensureHost → startHostUnderLease → canReplaceHost → spawn → probe ready).
+- Produces: nothing downstream (terminal verification task).
+
+- [ ] **Step 1: Write the integration test**
+
+Add to `test/host-resolver.test.mjs` after the issue #87 legacy-alive test (~line 163):
+
+```js
+test("resolver replaces an exited host whose claimPid is still alive (issue #99)", async () => {
+	const root = freshRoot();
+	try {
+		const meta = createView(root, { id: "v1", name: "a", cwd: "/r" });
+		writeFileSync(meta.sessionFile, "");
+		// The bug's exact shape: the host ran to completion (exited, exitCode 0,
+		// stopReason child_exit) but its claimPid — the dashboard process that
+		// wrote the claim — is STILL ALIVE (hostRecord defaults claimPid to
+		// process.pid). Before the fix, canReplaceHost saw the live claim as
+		// "unknown" and the resolver pended to "host start timed out".
+		hostRecord(root, "v1", {
+			instanceId: "i1",
+			state: "exited",
+			runnerPid: 999999,
+			childPid: null,
+			endedAt: Date.now(),
+			exitCode: 0,
+			stopReason: "child_exit",
+		});
+		const probe = scriptProbe(["ready"]);
+		const spawns = [];
+		const svc = resolverService(root, healServiceOverrides(probe, spawns));
+		const result = await svc.resolveAttachTarget("v1", { timeoutMs: 2_000 });
+		assert.equal(result.kind, "pty", `must replace the exited host despite the live claimPid: ${JSON.stringify(result)}`);
+		assert.equal(spawns.length, 1, "exactly one fresh claim spawn");
+		assert.notEqual(result.instanceId, "i1", "attaches to the replacement instance");
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+```
+
+- [ ] **Step 2: Sanity-verify the test fails against the pre-fix gate (optional but recommended)**
+
+Temporarily `git stash` the Task 1 commit (`git stash` won't work across commits — instead: `git checkout HEAD~1 -- src/core/host-coordination.mjs src/runtime/service.mjs`), then run:
+
+Run: `node --test --test-name-pattern "issue #99" test/host-resolver.test.mjs 2>&1 | tail -15`
+Expected: the new test FAILS or times out (resolver pends — the pre-fix behavior). Then restore: `git checkout HEAD -- src/core/host-coordination.mjs src/runtime/service.mjs`.
+
+If the timeout makes the run slow, the 2_000 ms timeoutMs bounds it.
+
+- [ ] **Step 3: Run the test against the fix**
+
+Run: `node --test --test-name-pattern "issue #99" test/host-resolver.test.mjs 2>&1 | tail -10`
+Expected: PASS — `kind: "pty"`, exactly one spawn, replacement instanceId.
+
+- [ ] **Step 4: Run the full suite**
+
+Run: `npm test 2>&1 | tail -15`
+Expected: PASS — all suites green, no regressions.
+
+Run: `npm run typecheck`
+Expected: exit 0.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add test/host-resolver.test.mjs
+git commit -m "test(resolver): exited host with live claimPid attaches via fresh spawn (#99)"
+```
+
+---
+
+### Task 3: U1 manual verification (post-implementation, user-executed)
+
+**Files:** none (manual).
+
+**Interfaces:** none.
+
+- [ ] **Step 1: Restart dashboard process** (loads new code — the "immediately effective on existing bad records" property requires restart).
+
+- [ ] **Step 2: Attach view_2472d82627 from the dashboard** — observe: attach enters the session, history renders, no `host start timed out`.
+
+- [ ] **Step 3: Exit the session, attach again** — confirm repeatability.
+
+- [ ] **Step 4: Same check on view_4b667ad75d / view_c038badb30** (the other two exited + live-claimPid views).
+
+- [ ] **Step 5: Record results in the issue** (comment each view's outcome; mark U1 pass/pending in the final report).
+
+---
+
+## Self-Review
+
+**1. Spec coverage:**
+- A1-A5 → Task 1 Step 1 (three new tests + edited legacy test covers A2/A3 cases) ✓
+- A6 → Task 2 ✓
+- U1 → Task 3 ✓
+- 改动文件清单 (spec) → Task 1 + Task 2 files match exactly (host-coordination.mjs, service.mjs, host-coordination.test.mjs, host-resolver.test.mjs) ✓
+- 非目标: no pty-runner/store/host.json changes in any task ✓
+
+**2. Placeholder scan:** no TBD/TODO; every code step has full code; verification commands concrete. ✓
+
+**3. Type consistency:** `canReplaceHost` new signature `{host, runnerObservation, childObservation, launchLeaseActive}` used consistently in Task 1 tests, Task 1 implementation, and matches Task 2's indirect usage (no direct call). `healServiceOverrides(probe, spawns)` helper name matches file. ✓

package/docs/superpowers/specs/2026-09-08-attach-ctrl-left-detach-design.md

@@ -0,0 +1,58 @@
+# issue #89 spec：attach 界面 Ctrl+← detach 和弦
+
+日期：2026-09-08 · 状态：已授权全自动推进（用户 2026-09-08 决策）
+
+## 背景与问题
+
+attach 界面里编辑器非空时 `←` 被判为光标左移转发给 child（#66/#68/#69 门禁链的有意行为），用户不知道要先清空输入才能 `←` 退出，被困后只能 Ctrl+C/D 强退（连带 shutdown child Pi——实录一次事故导致 host 反复冷启动 7 次）。需要一个不与编辑冲突、始终可用的退出和弦。
+
+## 核心设计（issue 已定稿，本 spec 为落地细化）
+
+### D1：Ctrl+← 无条件 detach
+`src/ui/pty-attach.ts` `handleInput`：在 `Key.left` 分支**之前**新增：
+```ts
+if (matchesKey(data, Key.ctrl("left"))) {
+	// Explicit detach chord (issue #89): single ← is gated on editor state
+	// (it doubles as cursor-left in a non-empty draft), so a user with a draft
+	// had no way out. Ctrl+← is unambiguous intent — detach unconditionally,
+	// regardless of editor state or socket liveness (same guarantee as the
+	// disconnected-← escape, issue #48).
+	this.detach();
+	return;
+}
+```
+- 放 Key.left 分支前：确保组合键不被单键分支截获（matchesKey 语义上两者不相交，但顺序防御更稳）；
+- 无条件：和弦语义 = "我要退出"，不需要门禁（门禁防的是误触，组合键无误触）；
+- pi-tui Key 支持现成：keys.js L845-846 legacy（`\x1b[1;5D`）+ kitty 序列均映射 ctrl+left。
+
+### D2：header 提示更新
+- L282：`← detach` → `←/Ctrl+← detach`
+- L298（renderLoading 中心提示）：`← to detach` → `←/Ctrl+← to detach`
+
+### 否决项（issue 已论证，记录防重提）
+- Esc：child 可能跑 vim/nvim，Esc 必须透传；
+- 双击 ←：编辑时连按 ← 移动光标是高频操作，必误触。
+
+## 非目标
+- 不改 ← 单键门禁链任何行为（#66/#68/#69 的判定逻辑保持原样）；
+- 不改其他键位；不改 detach() 本身语义。
+
+## 可测性拆分设计
+
+| 单元 | 性质 | 测法 |
+|---|---|---|
+| Ctrl+← 分支 | 组件 handleInput | 扩建现有 `test-support/detach-gate-smoke.ts` harness（fake tui + send spy + didDetach，#42/#48/#66 同款）：注入 `\x1b[1;5D` 序列 |
+| 文案 | render 输出 | harness 内 render(width) 断言含 "Ctrl+←" |
+
+## 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | Ctrl+← 编辑器非空（draft）时 detach | 自动化（冒烟） | `node --test test/pty-attach-detach-gate.test.mjs` | didDetach() === true（editor_state draft 场景） |
+| A2 | Ctrl+← 编辑器空时 detach | 自动化（冒烟） | 同上 | didDetach() === true |
+| A3 | 单次 ← 门禁链回归 | 自动化（冒烟） | 同上 | 现有 15+ 断言全绿 |
+| A4 | header 文案 | 自动化（冒烟） | 同上 render 输出断言 | 含 "Ctrl+←" |
+| A5 | 全量回归 | 自动化（static/build） | `npm test` + `npm run typecheck` | 618+ 全绿 |
+| U1 | 真实场景 | 用户实测 | 合并后重启 pi：attach 活跃 session，输入几个字 → Ctrl+← | 立即 detach 回 dashboard，child 不受影响 |
+
+U1 需重启 pi，合并后用户执行。

package/docs/superpowers/specs/2026-09-08-dashboard-shrink-repaint-design.md

@@ -0,0 +1,52 @@
+# issue #88 spec：dashboard 花屏修复（首帧全清 + 收缩自愈帧）
+
+日期：2026-09-08 · 状态：已授权全自动推进（用户 2026-09-08 决策）
+
+## 背景与问题
+
+dashboard（pi-tui 全屏 overlay）花屏：行重复、folder 计数错位。根因：pi-tui 差分渲染在 overlay 激活时禁用 clearOnShrink（tui-main-screen.js L315 `!hasOverlayEntries`），且首帧不清屏（"assumes clean screen"）——脏底/收缩残留无任何自愈通道。拖窗口（widthChanged → fullRender(true)）可恢复，证明全清是有效兜底。973d492（v0.3.0）起存在的存量问题。
+
+## 核心设计（单文件：src/ui/dashboard.ts）
+
+### D1：mount 首帧全清
+组件新增 `needsFullClear = true`；首帧 render 时 `this.tui.requestRender(true)`（nextTick 异步，无递归）——下一帧全量重绘，给干净底。
+
+### D2：内容收缩自愈帧
+- `fitToHeight` 记录 pad 前内容行数到实例字段（pad 后行数恒满屏，检测无效——必须用 pad 前值）；
+- `render(width)` 改为包装方法：调原逻辑（改名 `renderLines`）拿 lines → 若 `needsFullClear` 或内容行数较上帧**减少** → `requestRender(true)` → 更新记录 → 返回 lines；
+- 只响应**减少**（增长/同行数由差分正确处理），避免无意义全清。
+
+### 为什么这样安全
+- `requestRender(true)` 经 nextTick 异步执行（tui.js L612-628），render() 内调用不递归；
+- 全清帧被 DECSET 2026 同步输出包裹，支持终端无闪烁；dashboard-render.mjs 注释警告的是"每帧 true"，本设计仅首帧+收缩帧低频触发；
+- 不动 pi-tui 上游、不动差分语义、不动 dashboard-render.mjs。
+
+## 非目标
+- pi-tui 上游修复（node_modules 不可控；且 overlay 禁 clearOnShrink 是有意设计）；
+- 每帧全清（闪烁，明确放弃）；
+- attach 视图（PtyAttachComponent）的渲染问题（不同组件，不在本 issue）。
+
+## 可测性拆分设计
+
+| 单元 | 性质 | 测法 |
+|---|---|---|
+| 首帧/收缩触发逻辑 | 组件 render 包装（.ts） | 子进程冒烟：`test-support/dashboard-shrink-render.ts` 用 --experimental-transform-types 加载组件，fake tui spy + fake deps，render 三帧（首帧/增行/减行）输出 requestRender 调用序列 JSON |
+| 既有差分语义 | dashboard-render.mjs | 现有测试 "dashboard repaint preserves Pi TUI differential render state" 不动（requestDashboardRender 不改成 force） |
+
+冒烟脚本 deps 构造照搬 `test-support/dashboard-refs-render.ts`（同组件既有范式）。
+
+## 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | mount 首帧全清 | 自动化（integration/冒烟） | `node --test test/dashboard-render.test.mjs` | 首帧 render 后 requestRender 收到 [true] |
+| A2 | 收缩帧自愈 | 自动化（integration/冒烟） | 同上 | 减行帧触发 [true]；增行/不变帧不触发 |
+| A3 | 修复在 .ts 层（jiti 可重载） | 自动化（static） | diff 审查 | 运行时代码改动仅在 dashboard.ts（.mjs 无运行时行为变更） |
+| A4 | 全量回归 | 自动化（static/build） | `npm test` + `npm run typecheck` | 617+ 全绿 |
+| U1 | 真实花屏场景 | 用户实测 | 合并后重启 pi：密集创建/删除若干 session（可配合 host 崩溃场景），观察 dashboard | 无行重复/计数错位残留；无需拖窗口恢复 |
+
+U1 需重启 pi（git 包不热重载），合并后用户执行。
+
+## 风险与降级
+- 老终端无同步输出支持时全清帧可见一闪——低频可接受；
+- 若 U1 发现仍有残留场景（如运行期外部写屏非首帧非收缩），后续可加"定时低频全清"兜底，本 spec 不做。

package/docs/superpowers/specs/2026-09-08-legacy-stale-host-recovery-design.md

@@ -0,0 +1,87 @@
+# issue #87 spec：legacy 死 host 安全回收（resolver 自愈）
+
+日期：2026-09-08 · 状态：待用户确认
+
+## 背景与问题
+
+v0.5.x 时代（无 instanceId 协议）的 legacy PTY host，当 runner 进程被异常杀死（SIGKILL / 承载终端关闭）时 host.json 永远停在 `state: "alive"`（或 `"starting"`）。v0.6.0 的 attach resolver 对 legacy host 执行「never recovered」（spec §10.1 保守决策），probe 失败直接 pending，同时 `hostActive`（纯磁盘状态）让 ensureHost 拒绝重新 claim——三层叠加成死锁，attach 永久失败。本机实录 6 个 view 处于该状态。
+
+## 设计目标
+
+resolver 对「pid 可验证已死 + endpoint 不可达」的 legacy host 自动 finalize 为 `exited` 并走正常 ensure/claim 自愈，消除死锁；不满足安全条件时保持现有 pending 行为（不推翻 spec 的保守原意）。
+
+## 核心设计
+
+### D1：纯决策函数 `canFinalizeLegacyHost`（host-coordination.mjs）
+
+```js
+/**
+ * @param {{ host: HostStatus|null, hostPid: number|null, hostPidAlive: boolean,
+ *           probeClassification: string }} input
+ * @returns {boolean}
+ */
+```
+
+返回 true 当且仅当四条件同时成立：
+1. `host.instanceId == null`（legacy）
+2. `host.state ∈ {"starting", "alive"}`（stopping 由既有恢复路径 L907-933 覆盖，不重复处理）
+3. `hostPid != null && hostPidAlive === false` —— pid 已死是核心安全证据；pid 复用只会让 isAlive=true → 走保守分支，方向安全
+4. `probeClassification ∈ {"missing", "stale"}` —— missing=ENOENT（socket/pipe 不存在）；stale=ECONNREFUSED+isSocket（进程死、socket 文件残留）。`unknown`/`occupied`/`starting` 一律不回收
+
+纯函数、零副作用、零注入，真值表可全枚举测试。
+
+### D2：resolver legacy 分支改造（service.mjs `resolveAttachTargetInner`）
+
+- pid 解析复用 loadRow 同款 fallback：`Object.hasOwn(host, "runnerPid") ? host.runnerPid : readHostPid(root, viewId)`（legacy 的 pid 在 host-pid.json 镜像）
+- 现 L963 `else if (legacy) return pending(...)` 改为：
+  - `canFinalizeLegacyHost(...)` 为 true → finalize（见 D3）→ `continue`（下一轮 row 重载 hostActive=false → 走正常 ensure/claim）
+  - 否则保持原 pending（行为不变）
+- `state === "starting"` 的 legacy（L936 `withinGrace` 恒 true 的等死分支）：在 grace 等待分支内同样先查 `canFinalizeLegacyHost`（该分支 probe 已执行，classification 可得），满足即 finalize + continue，不再等 grace 到期
+
+### D3：finalize 动作（service.mjs 内联，写路径唯一）
+
+`writeHost(root, viewId, { ...host, state: "exited", endedAt: now, lastSeenAt: now, error: "legacy host finalized: runner pid dead" })` + `appendDiagnostic({ source: "service", level: "info", code: "legacy_host_finalized", ... })`。
+
+- legacy 无 instanceId，不存在并发 owner，无需 fencing（与新协议 updateOwnedHost 路径区分）；竞态窗口由 host-start lease 串行化兜底（claim 走全新 instanceId，与 exited 记录不冲突）。
+- 选 `exited` 而非 `failed`：进程是正常死亡语义（被外部杀死），failed 在现有代码里语义是"spawn/启动失败"（#86 场景），exited 与 v0.5.x runner 自然退出时写的状态一致，下游（canReplaceHost/ensure）对两者处理相同。
+
+### D4：平台兼容性
+
+不引入任何文件存在性检查（Windows 命名管道 existsSync 不可用，#45）；证据只来自 probe classification（connect+hello 是唯一权威，spec §7.1）+ isAlive（kill(pid,0) 跨平台）。不碰 prewarm keypress 路径（2s TTL 纪律）。
+
+## 非目标（明确排除）
+
+- **升级迁移扫描**（issue 建议 2）：resolver 自愈后功能冗余（下次 attach 自然恢复）；若后续要 dashboard 行状态立刻正确可单开 issue。
+- **UI 兜底提示**（issue 建议 3）：永久 pending 状态被消除后无存在意义。
+- **stopping 状态 legacy**：已有恢复路径覆盖（L907-933 对 instanceId != null 生效；legacy stopping 的 `staleStop` 判定要求 instanceId != null——属现存另一个小缺口，本次不扩范围，记为遗留观察项）。
+
+## 可测性拆分设计
+
+| 单元 | 位置 | 性质 | 测法 |
+|---|---|---|---|
+| `canFinalizeLegacyHost` | host-coordination.mjs 新增导出 | 纯函数 | 真值表单测：4 条件 × 关键组合（全满足/缺 pid/pid 活/unknown/stopping/新协议 host） |
+| pid fallback 解析 | service.mjs resolver 内联（复用 store.readHostPid） | 副作用隔离 | 集成测试造 legacy host.json（无 runnerPid 属性）+ host-pid.json |
+| finalize + 自愈闭环 | service.mjs resolver | 集成 | 注入 scriptProbe(missing) + 死 pid → 断言 host.json 落 exited、diagnostic 写入、resolver 继续 claim 新 host |
+| 保守分支 | 同上 | 集成 | pid 活（用 process.pid）→ 断言 pending 且不写盘 |
+
+测试基建现成：`resolverService` + `scriptProbe` + `aliveHost` fixtures + `instantSleep`（test/host-resolver.test.mjs 模式）。`aliveHost` fixture 需支持造 legacy host（无 instanceId、无 runnerPid 属性 + host-pid.json 镜像），必要时加 `legacyHost` fixture helper。
+
+## 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | canFinalizeLegacyHost 决策正确性 | 自动化（unit） | `node --test test/host-coordination.test.mjs` | 真值表全组合通过 |
+| A2 | legacy alive + pid 死 + missing → 自愈闭环 | 自动化（integration） | `node --test test/host-resolver.test.mjs` | host.json 落 exited、diagnostic 有 legacy_host_finalized、resolver 成功 claim 新 instance |
+| A3 | legacy alive + pid 活 → 不回收 | 自动化（integration） | 同上 | pending 返回、host.json 未被改写 |
+| A4 | legacy starting + pid 死 → 不等 grace 即回收 | 自动化（integration） | 同上 | 不 sleep 到 deadline 即完成回收 + claim |
+| A5 | probe unknown → 不回收 | 自动化（integration） | 同上 | pending、不写盘 |
+| A6 | 全量回归 | 自动化（static/build） | `npm test` + `npm run typecheck` | 568+ 全绿、无新类型错误 |
+| U1 | 本机 6 个真实卡死 legacy view 实测 | 用户实测 | 运行副本 checkout PR 分支 → 重启 pi → board 对卡死 view 按 enter | 全部自动拉起新 host 可正常 attach，无 manual restart 提示 |
+
+U1 必须用户执行（重启 pi 会断开实现 session）。执行时机：PR 合并前。
+
+## 风险与降级
+
+- pid 复用误判方向恒为保守（不回收），不会误杀；
+- finalize 后若 claim 失败（如 PTY 不可用），行为与现有 ensure 失败路径一致（pending + 原因），无新增失败模式；
+- Windows 无 legacy named-pipe 实测环境（U2 类）——设计只依赖平台无关的 probe/isAlive，风险评估为低，最终报告标注未实测。

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 路径行为不变。