@zhuxixi/pi-agent-board 0.3.0

package/docs/superpowers/plans/2026-08-21-dashboard-keypress-lag.md

@@ -0,0 +1,366 @@
+# Dashboard Keypress Lag 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:** Eliminate perceptible ↑/↓ selection lag on the dashboard by moving prewarm off the keypress path, skipping artifact loads for archived views, and stopping forced PTY probes (issue #9).
+
+**Architecture:** Three independent fixes: (A) a debounced prewarm scheduler so arrow keys only mutate selection and trigger a render; (B) an archived short-circuit in `listRows` so the 700ms poll (`reconcile()` + `refresh()` + `render()` each call it) stops reading ~10 artifact files per archived view; (C) `ensureHost` no longer forces `ptySupport({refresh:true})`, which spawned a probe process on every keypress when PTY support is broken.
+
+**Tech Stack:** Node 20+, TypeScript (`.ts` UI) + ESM JavaScript (`.mjs` core), `node --test` test runner, no new dependencies.
+
+## Global Constraints
+
+- No new npm dependencies.
+- All commits in this worktree branch `issue-9-dashboard-keypress-lag`; never touch `main` checkout.
+- `git add` per-file; never `git add -A`.
+- Commit messages in English, conventional-commits format, reference `issue #9`.
+- `npm run verify` (typecheck + tests + pack dry-run) must pass before the PR.
+- Core modules are `.mjs` with JSDoc types; UI is `.ts`. Follow existing file conventions.
+
+---
+
+### Task 1: `listRows` archived short-circuit (Fix B)
+
+**Files:**
+- Modify: `src/core/store.mjs` (function `listRows`, around line 220)
+- Test: `test/store.test.mjs` (append new test)
+
+**Interfaces:**
+- Consumes: existing `readMeta(root, viewId)`, `loadRow(root, viewId)` from `src/core/store.mjs`.
+- Produces: unchanged `listRows(root, opts)` signature and return type. Callers (`service.mjs` `reconcile()`/`rows()`/`pruneWarmHosts()`, `dashboard.ts` render) need no changes.
+
+- [ ] **Step 1: Write the safety-net test**
+
+Note: `readJson` swallows missing/corrupt files with a null fallback (`src/core/atomic.mjs`), so the archived short-circuit has no black-box failure mode — pre-fix and post-fix output is identical; the difference is pure IO volume, proven by the Task 4 real-store measurement. This test instead pins the behavioral contract that makes the short-circuit safe: archived views whose artifact files are absent/stale must not break `listRows`, and `includeArchived` semantics stay unchanged.
+
+Append to `test/store.test.mjs` (imports `createView`, `listRows`, `writeMeta`, `P` are already at top; add `rmSync`/`writeFileSync`/`mkdirSync` to the existing `node:fs` import if missing):
+
+```js
+test("listRows tolerates archived views with only meta.json", () => {
+	const root = freshRoot();
+	try {
+		const live = createView(root, { id: "live1", name: "live", cwd: "/r" });
+		for (const id of ["arch1", "arch2"]) {
+			const meta = createView(root, { id, name: id, cwd: "/r" });
+			meta.archived = true;
+			writeMeta(root, meta);
+			// Simulate the worst case the short-circuit must handle: archived view
+			// dirs containing nothing but meta.json (no state/evidence/host files).
+			rmSync(P.viewDir(root, id), { recursive: true, force: true });
+			mkdirSync(P.viewDir(root, id), { recursive: true });
+			writeFileSync(P.metaPath(root, id), JSON.stringify(meta));
+		}
+		const rows = listRows(root);
+		assert.equal(rows.length, 1);
+		assert.equal(rows[0].meta.id, live.id);
+		const all = listRows(root, { includeArchived: true });
+		assert.equal(all.length, 3);
+		assert.equal(all.filter((r) => r.meta.archived).length, 2);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+```
+
+- [ ] **Step 2: Run test to confirm green baseline**
+
+Run: `cd <worktree> && npm install --no-audit --no-fund 2>/dev/null; node --test test/store.test.mjs`
+Expected: PASS pre-fix (safety net — see Step 1 note). This test must stay green after the implementation change.
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `src/core/store.mjs`, change `listRows`:
+
+```js
+export function listRows(root, opts = {}) {
+	const roster = readRoster(root);
+	/** @type {Row[]} */
+	const rows = [];
+	for (const viewId of roster.views) {
+		// Archived short-circuit: archived rows are invisible on the dashboard, so
+		// never pay for their artifact files (state/evidence/host/diagnostics...).
+		// meta.json is the single authoritative source of the archived flag.
+		const meta = readMeta(root, viewId);
+		if (!meta) continue;
+		if (meta.archived && !opts.includeArchived) continue;
+		const row = loadRow(root, viewId);
+		if (!row) continue;
+		if (row.meta.archived && !opts.includeArchived) continue;
+		rows.push(row);
+	}
+	return rows;
+}
+```
+
+(The second archived check is belt-and-suspenders in case `loadRow` re-reads a meta that changed between reads.)
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `node --test test/store.test.mjs`
+Expected: PASS, all tests in file green.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/store.mjs test/store.test.mjs
+git commit -m "perf: skip artifact loading for archived views in listRows (issue #9)"
+```
+
+---
+
+### Task 2: Debounced prewarm off the keypress path (Fix A)
+
+**Files:**
+- Create: `src/core/prewarm-schedule.mjs`
+- Create: `test/prewarm-schedule.test.mjs`
+- Modify: `src/ui/dashboard.ts` (fields near line 127, `moveSelection` ~L237, `refresh` ~L176, `dispose` ~L1086)
+
+**Interfaces:**
+- Produces: `createPrewarmScheduler(prewarm: () => void, delayMs?: number): { schedule(): void; cancel(): void }` — single-flight debounce; repeated `schedule()` within `delayMs` fire `prewarm()` exactly once after the last call; `cancel()` clears the pending timer.
+- Consumes (dashboard.ts): existing private `prewarmSelected()`.
+
+- [ ] **Step 1: Write the failing test**
+
+`test/prewarm-schedule.test.mjs`:
+
+```js
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { createPrewarmScheduler } from "../src/core/prewarm-schedule.mjs";
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+test("rapid schedules fire prewarm once after quiet period", async () => {
+	let fired = 0;
+	const s = createPrewarmScheduler(() => { fired += 1; }, 15);
+	s.schedule();
+	s.schedule();
+	s.schedule();
+	await sleep(5);
+	assert.equal(fired, 0); // still debouncing
+	await sleep(25);
+	assert.equal(fired, 1); // exactly once
+});
+
+test("cancel prevents prewarm entirely", async () => {
+	let fired = 0;
+	const s = createPrewarmScheduler(() => { fired += 1; }, 10);
+	s.schedule();
+	s.cancel();
+	await sleep(30);
+	assert.equal(fired, 0);
+});
+
+test("schedule after cancel works again", async () => {
+	let fired = 0;
+	const s = createPrewarmScheduler(() => { fired += 1; }, 10);
+	s.schedule();
+	s.cancel();
+	s.schedule();
+	await sleep(30);
+	assert.equal(fired, 1);
+});
+
+test("prewarm errors do not crash the scheduler", async () => {
+	let fired = 0;
+	const s = createPrewarmScheduler(() => { fired += 1; throw new Error("boom"); }, 5);
+	s.schedule();
+	await sleep(20);
+	assert.equal(fired, 1);
+	s.schedule();
+	await sleep(20);
+	assert.equal(fired, 2);
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `node --test test/prewarm-schedule.test.mjs`
+Expected: FAIL — cannot find module `../src/core/prewarm-schedule.mjs`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+`src/core/prewarm-schedule.mjs`:
+
+```js
+/**
+ * Single-flight debounce for dashboard prewarm.
+ *
+ * Arrow-key navigation must move the selection and repaint immediately; host
+ * prewarm (which may spawn a PTY host and re-scan rows) is deferred so bursts
+ * of keypresses trigger exactly one prewarm for the final resting selection.
+ */
+
+/**
+ * @param {() => void} prewarm Invoked (with errors swallowed) once scheduling
+ *   goes quiet for `delayMs`. Re-reads current state at fire time.
+ * @param {number} [delayMs=200]
+ * @returns {{ schedule: () => void, cancel: () => void }}
+ */
+export function createPrewarmScheduler(prewarm, delayMs = 200) {
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let timer = null;
+	const fire = () => {
+		timer = null;
+		try {
+			prewarm();
+		} catch {
+			/* prewarm is best-effort; never break navigation */
+		}
+	};
+	return {
+		schedule() {
+			if (timer !== null) clearTimeout(timer);
+			timer = setTimeout(fire, delayMs);
+		},
+		cancel() {
+			if (timer !== null) {
+				clearTimeout(timer);
+				timer = null;
+			}
+		},
+	};
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `node --test test/prewarm-schedule.test.mjs`
+Expected: PASS (4 tests).
+
+- [ ] **Step 5: Wire into DashboardComponent**
+
+In `src/ui/dashboard.ts`:
+
+1. Import: add near the other `../core/` imports:
+   `import { createPrewarmScheduler } from "../core/prewarm-schedule.mjs";`
+2. Add field (near `private prewarmedId: string | null = null;`):
+   `private readonly prewarmScheduler = createPrewarmScheduler(() => this.prewarmSelected(), 200);`
+3. `moveSelection()`: replace `this.prewarmSelected();` with `this.prewarmScheduler.schedule();`
+4. `refresh()` (line ~176): replace `if (this.selectedId && this.selectedId !== previousSelected) this.prewarmSelected();` with `if (this.selectedId && this.selectedId !== previousSelected) this.prewarmScheduler.schedule();`
+5. `prewarmSelected()`: add a mode guard as the first line so a timer firing after the user entered peek/session/launch modes does not prewarm the wrong target:
+   `if (this.mode !== "list" && this.mode !== "select") return;`
+6. `dispose()`: replace the comment-only body with `this.prewarmScheduler.cancel();` (keep the existing comment about poll interval ownership).
+
+- [ ] **Step 6: Typecheck + full tests**
+
+Run: `npx tsc --noEmit && node --test test/*.test.mjs`
+Expected: no type errors; all tests green.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/core/prewarm-schedule.mjs test/prewarm-schedule.test.mjs src/ui/dashboard.ts
+git commit -m "perf: debounce dashboard prewarm off the keypress path (issue #9)"
+```
+
+---
+
+### Task 3: `ensureHost` PTY probe TTL instead of forced refresh (Fix C)
+
+**Files:**
+- Modify: `src/runtime/service.mjs` (`ensureHost`, ~L674: `const pty = ptySupport({ refresh: true });`)
+- Test: `test/service.test.mjs` (append new test)
+
+**Interfaces:**
+- Consumes: existing injected `ptySupport(opts)` option of `createService`; existing test helper `service(root, overrides)` in `test/service.test.mjs`.
+- Produces: unchanged `ensureHost` return contract; only probe option semantics change (default = cached/TTL instead of forced refresh).
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `test/service.test.mjs` (uses `createView`, `writeState`, `readState` imports already present; add `writeFileSync` if not imported):
+
+```js
+test("ensureHost probes PTY support with TTL cache, not forced refresh", () => {
+	const root = freshRoot();
+	try {
+		process.env.AGENT_BOARD_FORCE_PTY = "1";
+		const meta = createView(root, { id: "v1", name: "a", cwd: "/r" });
+		writeFileSync(meta.sessionFile, JSON.stringify({ type: "session", id: "s1", cwd: "/r" }) + "\n");
+		const probeCalls = [];
+		const svc = service(root, {
+			ptySupport: (opts = {}) => { probeCalls.push(opts); return { ok: true }; },
+			launchHost: () => ({ pid: process.pid, configPath: "/no/host-config.json" }),
+		});
+		const res = svc.ensureHost("v1");
+		assert.equal(res.ok, true);
+		assert.ok(probeCalls.length >= 1);
+		for (const opts of probeCalls) {
+			assert.notEqual(opts?.refresh, true, "ensureHost must not force ptySupport refresh");
+		}
+	} finally {
+		delete process.env.AGENT_BOARD_FORCE_PTY;
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `node --test test/service.test.mjs`
+Expected: new test FAILS — `ensureHost` currently calls `ptySupport({ refresh: true })` so `opts.refresh === true`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `src/runtime/service.mjs` `ensureHost`, change:
+
+```js
+const pty = ptySupport({ refresh: true });
+```
+
+to:
+
+```js
+// Default probe semantics: success is cached for the process lifetime and a
+// failed probe retries on a short TTL. Forcing refresh here would spawn a
+// probe process on every keypress-driven prewarm when PTY support is broken.
+const pty = ptySupport();
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `node --test test/service.test.mjs`
+Expected: PASS, all tests in file green.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/runtime/service.mjs test/service.test.mjs
+git commit -m "fix: stop forcing PTY probe refresh on every ensureHost (issue #9)"
+```
+
+---
+
+### Task 4: Full verification + performance evidence
+
+**Files:**
+- No source changes expected (fix-only task; measurement script is throwaway, not committed).
+
+**Interfaces:**
+- Consumes: all previous tasks merged on the branch.
+
+- [ ] **Step 1: Install deps and run full verify**
+
+Run: `cd <worktree> && npm install --no-audit --no-fund && npm run verify`
+Expected: `tsc --noEmit` clean, all 27+ test files pass, `npm pack --dry-run` succeeds.
+
+- [ ] **Step 2: Measure real-store improvement (read-only)**
+
+Run against the user's real store (read-only, no mutation):
+
+```bash
+node --input-type=module -e "
+import { listRows } from './src/core/store.mjs';
+import os from 'node:os'; import path from 'node:path';
+const root = path.join(os.homedir(), '.pi/agent/agent-board');
+listRows(root);
+const t0 = performance.now(); listRows(root); const t1 = performance.now();
+console.log('listRows post-fix:', (t1 - t0).toFixed(1), 'ms');
+"
+```
+
+Expected: ≤ 40ms on the 168-view store (was 180–204ms). Record the number.
+
+- [ ] **Step 3: Report numbers**
+
+Paste before/after into the PR body and as an issue #9 comment. No commit needed for this task.

package/docs/superpowers/specs/2026-08-15-screenlog-gc-design.md

@@ -0,0 +1,105 @@
+# Spec: screen.log Startup GC（startup 回收 ended view 的 screen.log）
+
+- Issue: zhuxixi/pi-agent-board#1
+- Date: 2026-08-15
+- Status: draft（待 review）
+
+## Background（来自调研，证据已评论到 issue）
+
+上游 PR #41（commit `ee3780a`，2026-08-03 合入）已给**写路径**加上界：
+`appendBoundedScreenLog()` 超过 `SCREEN_LOG_MAX_BYTES`（5 MB）时原子 compact 成
+100 KB tail；runner 启动时 `reconcileScreenLog()` 压存量。本机验证（2026-08-15）：
+活跃 view 的 screen.log 最大 3.9 MB，cap 工作正常。
+
+**残留缺口（本 spec 的 scope）**：
+
+1. ended view 的 screen.log 无人回收——`reconcileScreenLog` 只在该 view 的
+   pty-runner 重启时触发；session 结束后 runner 不再运行，文件永久留存。
+   本机 views 目录仍有 1.6 GB 历史存量。
+2. 全仓无 retention/prune/GC 机制（ended view 目录永久保留）。
+3. `SCREEN_LOG_MAX_BYTES` / `SCREEN_LOG_REPLAY_BYTES` 硬编码，不可配。
+
+## Goals
+
+- Dashboard 启动时异步回收：ended 超龄 view 的 `screen.log` 被删除（unlink）。
+- 两个配置项写入 `launch-prefs.json` 即生效：
+  - `screenLogRetentionDays`（默认 7；**0 = 关闭 GC**）
+  - `screenLogMaxSize`（默认 5 MB；透传给 pty-runner 写路径的 cap）
+- 全程容错：GC 任何失败不得影响 dashboard 或 runner。
+
+## Non-goals
+
+- 不做 log 轮转（screen.log → screen.log.1）。写路径已有 cap + tail compact，轮转与其重叠（YAGNI）。
+- 不做压缩（.gz）。
+- 不删整个 view 目录；保留 `meta.json` / `state.json` / `evidence.json` 等 KB 级文件，dashboard 历史行不丢。
+- 不动 job-runner 路径（它不写 screen.log）。
+- 不引入防抖/状态持久化（扫描成本可忽略，每次启动都跑）。
+
+## Design
+
+### 新模块：`src/core/screen-log-gc.mjs`
+
+单一职责，导出 `pruneScreenLogs(root, opts)`：
+
+- 扫描 `<root>/views/view_*/`。
+- 对每个 view，判定清理条件（全部满足才删）：
+  1. `screen.log` 存在且非空；
+  2. view 已结束——`host.json` 的 `endedAt` 非 null（首选依据），
+     或 `host.state !== "alive"`；host.json 缺失/损坏时 fallback 用
+     screen.log 的 mtime 判定年龄；
+  3. 结束时间（或 mtime）早于 `now - retentionDays`。
+- 满足条件 → `unlinkSync(screenLog)`。失败静默（单文件失败不中断整体扫描）。
+- **活跃 view 一律跳过**：runner 持有 `screenLogBytes` 内存计数，外部动活跃
+  文件引入 race；活跃 view 由 `appendBoundedScreenLog` 的 cap 自管。
+- fs 操作沿用 `screen-log.mjs` 的可注入 fs 模式（defaultScreenLogFs），便于单测。
+- 返回统计 `{ scanned, removed, skippedActive, skippedFresh, bytesReclaimed, errors }`，
+  供可选的 diagnostics 记录。
+
+### 触发点：`src/runtime/service.mjs`
+
+- service 初始化时 fire-and-forget 调 `pruneScreenLogs()`（不 await、不阻塞首帧；
+  几百个 view 的 stat 扫描 <10ms，实际删除走 unlink，足够快）。
+- 整个调用包 try/catch，异常静默；可选把统计 append 到 diagnostics.jsonl。
+
+### 配置读取：`launch-prefs.json`
+
+新增两个字段（缺省用默认值，向后兼容旧 prefs 文件）：
+
+| 字段 | 类型 | 默认 | 语义 |
+|---|---|---|---|
+| `screenLogRetentionDays` | number | 7 | ended 超过该天数的 view 清理 screen.log；0 = 关闭 GC |
+| `screenLogMaxSize` | number | 5_000_000 | pty-runner 写路径 cap（字节），透传进 HostConfig → `appendBoundedScreenLog(opts.maxBytes)` |
+
+- 非法值（负数、NaN、非数）回退默认值。
+- `screenLogMaxSize` 传递链路：service 读 prefs → 写入 pty-runner 的 HostConfig
+  JSON → runner `appendBoundedScreenLog(screenLog, data, bytes, { maxBytes })`。
+  `appendBoundedScreenLog` 已支持 `opts.maxBytes`，runner 侧只需读取并透传。
+
+### Error handling
+
+- GC 整体 fire-and-forget + try/catch；单 view 失败跳过继续。
+- host.json 读取失败 → mtime fallback；两者都失败 → 跳过该 view。
+- prefs 读取失败 → 全默认值（不影响现有 launch-prefs 逻辑）。
+
+### Testing
+
+新增 `test/screen-log-gc.test.mjs`（沿用现有 test 风格与可注入 fs）：
+
+1. ended 超龄 view → screen.log 被删，meta/state 等文件保留。
+2. 活跃 view（host.json `state: "alive"` 且 endedAt null）→ 不删。
+3. ended 但未超龄 → 不删。
+4. `screenLogRetentionDays: 0` → 全部不删。
+5. host.json 缺失 → mtime fallback 正确判定。
+6. `screenLogMaxSize` 经 HostConfig 透传到 runner cap（runner 侧单测或链路断言）。
+7. 单文件 unlink 失败不中断其他 view 的清理。
+
+## Data flow
+
+```
+/dashboard 打开
+  └─ service init
+       └─ (async, fire-and-forget) pruneScreenLogs(root, prefs)
+            ├─ scan views/view_*/
+            ├─ per view: ended? aged? → unlink screen.log
+            └─ return stats → (optional) diagnostics.jsonl
+```

package/docs/superpowers/specs/2026-08-16-attach-double-cursor-jiggle-retry-design.md

@@ -0,0 +1,142 @@
+# Issue #2 Spec：attach 双光标 — jiggle 重试直到见到清屏
+
+## 日期
+2026-08-16
+
+## 问题
+attach 后出现双光标（PTY 光标块与编辑器假光标失同步），因为 resize jiggle 在冷启动/streaming 场景下失效，重放脏帧未被清屏自愈。
+
+## 根因（已在 issue 中确认）
+1. `forceChildRedraw()` 发 jiggle 后无确认/重试机制
+2. `forceChildRedrawAfterLiveOutput()` 是 one-shot 补偿，触发后不再触发
+3. 冷启动时 SIGWINCH 被丢弃 / streaming 时 jiggle 被渲染节流合并
+
+## 修复方案：jiggle 重试直到见到清屏
+
+### 设计原则：可测性优先
+把重试逻辑抽成**纯状态机**（不依赖 socket/xterm/timer），`pty-attach.ts` 只做胶水。这样核心逻辑 100% 可单测，验收标准 = 单测全通过。
+
+### 模块拆分
+
+#### 1. 纯逻辑层：`src/core/pty-attach-jiggle-retry.mjs`
+
+**`createJiggleRetryState()`** — 创建重试状态机，返回一个不可变状态对象 + 操作函数集。
+
+状态机接口（纯函数，无副作用）：
+```typescript
+interface JiggleRetryState {
+  /** 当前重试到第几轮（0 = 未开始） */
+  retryIndex: number;
+  /** 是否已检测到清屏 */
+  clearDetected: boolean;
+  /** 是否已停止（见过清屏/超限/手动停止） */
+  stopped: boolean;
+}
+
+/** 退避间隔表 */
+const BACKOFF_MS: readonly number[]; // [120, 500, 1500, 3000]
+
+/** 创建初始状态 */
+function createJiggleRetryState(): JiggleRetryState;
+
+/** 处理一段 output 数据，返回新状态 + 是否检测到清屏 */
+function feedOutput(state: JiggleRetryState, data: string, carry: string): {
+  state: JiggleRetryState;
+  carry: string;       // 更新后的跨 chunk carry
+  clearFound: boolean;
+};
+
+/** 获取下一次重试的延迟（ms），返回 null 表示不再重试 */
+function nextRetryDelay(state: JiggleRetryState): number | null;
+
+/** 推进到下一轮重试 */
+function advanceRetry(state: JiggleRetryState): JiggleRetryState;
+
+/** 手动停止（attach 安定/close） */
+function stopRetry(state: JiggleRetryState): JiggleRetryState;
+
+/** 检测数据中是否包含全清序列 \x1b[2J（处理跨 chunk） */
+function hasFullClearSequence(data: string): boolean;
+```
+
+#### 2. 胶水层：`src/ui/pty-attach.ts` 变更
+
+新增私有字段：
+```typescript
+private jiggleRetryState: JiggleRetryState | null = null;
+private jiggleRetryTimer: ReturnType<typeof setTimeout> | null = null;
+private clearCarry = "";
+```
+
+新增私有方法：
+```typescript
+/** 启动 jiggle 重试链（connect 成功后调用） */
+private startJiggleRetry(): void;
+
+/** 处理 socket output 时检测清屏，命中则取消重试 */
+private checkClearSequence(data: string): void;
+
+/** 安排下一次重试 */
+private scheduleNextJiggle(): void;
+
+/** 取消重试（close 时调用；settle 时故意不取消，见生命周期） */
+private cancelJiggleRetry(): void;
+```
+
+修改点：
+- `connect()` 成功后 → 调 `startJiggleRetry()`
+- `onSocketData()` 处理 output 时 → 调 `checkClearSequence(data)`
+- `close()` → 调 `cancelJiggleRetry()`
+- **移除** `forceChildRedrawAfterLiveOutput()` 和 `forcedRedrawAfterLiveOutput` 字段（被重试链取代）
+
+**设计变更（final review 后，commit 806bf3e）**：`finishAttachTransition()` **不再取消**重试链——settle 取消会让静默冷启动场景下只剩 retry 1 可达（链 ~410ms 就死），正是本 feature 要修的场景。链的自然终止条件：检测到清屏 / 达到 4 次上限 / close()。settle 后的残余 jiggle 只在子端吞掉所有此前 jiggle 时发生（此时画面本就脏），用一次全屏重绘闪烁换自愈是值得的；健康 session 下首个 jiggle 的清屏就会被检测到，链在 settle 前已停。
+
+### 数据流
+```
+connect() → forceChildRedraw() → 发 jiggle → startJiggleRetry()
+                                                    ↓
+onSocketData(output) → checkClearSequence(data)     ↓
+  ↓                        ↓                        ↓
+  ↓                   clearFound? → YES → cancelJiggleRetry()
+  ↓                        ↓ NO                     ↓
+  ↓                   scheduleNextJiggle() ←────────┘
+  ↓                        ↓
+  ↓                   setTimeout(BACKOFF_MS[i]) → forceChildRedraw() → advanceRetry()
+  ↓                        ↓
+  ↓                   (循环直到 clearFound / 超限 / 手动停止)
+  ↓
+finishAttachTransition() / close() → cancelJiggleRetry()
+```
+
+### 测试策略（验收标准）
+
+**文件：`test/pty-attach-jiggle-retry.test.mjs`**
+
+| 测试场景 | 验证点 |
+|----------|--------|
+| 初始状态 | retryIndex=0, clearDetected=false, stopped=false |
+| 输入含完整 `\x1b[2J` | clearFound=true, clearDetected=true |
+| 输入含 `\x1b[2J` + 其他数据 | clearFound=true |
+| 输入无 `\x1b[2J` | clearFound=false, clearDetected=false |
+| 跨 chunk：`\x1b[` + `2J` | 第二次 feed 时 clearFound=true |
+| 跨 chunk：`\x1b` + `[2J` | 第二次 feed 时 clearFound=true |
+| 部分匹配 `\x1b[3J` | clearFound=false |
+| 退避间隔 | nextRetryDelay 依次返回 120/500/1500/3000 |
+| 达到上限 | 第 5 次 nextRetryDelay 返回 null |
+| 见到清屏后 nextRetryDelay | 返回 null（不再重试） |
+| 手动停止后 nextRetryDelay | 返回 null |
+| advanceRetry 推进 | retryIndex 递增 |
+| stopRetry 后置位 | stopped=true |
+
+### 非目标
+- 不改 pi-tui 渲染逻辑
+- 不改 screen.log 重放策略
+- 不做光标失同步检测加固（issue 优先级 2，后续 follow-up）
+- 不改 attach 安定/loading banner 逻辑
+
+### 文件变更
+| 文件 | 变更类型 | 说明 |
+|------|----------|------|
+| `src/core/pty-attach-jiggle-retry.mjs` | 新增 | 纯逻辑状态机 |
+| `src/ui/pty-attach.ts` | 修改 | 集成重试链，移除 one-shot 补偿 |
+| `test/pty-attach-jiggle-retry.test.mjs` | 新增 | 状态机全场景测试 |

package/docs/superpowers/specs/2026-08-21-dashboard-keypress-lag-design.md

@@ -0,0 +1,59 @@
+# Issue #9 Spec — dashboard 方向键卡顿修复
+
+状态:待用户确认
+类型:bug/perf(根因已完成,见 issue #9 正文与调研评论)
+
+## 目标
+
+1. 按方向键的选中移动延迟降到感知阈值内(<16ms):按键处理本身不做磁盘 IO、不 spawn 进程
+2. 轮询周期内主线程同步 IO 阻塞显著下降(目标:单周期 <60ms,当前 ~400ms)
+3. 不改变 attach 预热的行为收益(选中后仍会预热,只是延后)
+
+## 非目标
+
+- store 全面异步化(fs/promises 重写)——不做,风险大收益边际
+- mtime 缓存层——归档短路后若实测仍慢再立项
+- screen.log 体积治理——issue #1 已完成
+- 渲染器/GPU 相关改动——已证实无关
+
+## 设计
+
+### Fix A:按键先响应,prewarm 延迟 + 防抖(src/ui/dashboard.ts)
+
+- `moveSelection()`:只改 `selectedId` 并立刻触发渲染(现有 invalidate 链),移除同步 `prewarmSelected()` 调用
+- `prewarmSelected()` 改为防抖调度:单例 timer,~200ms 无新移动才执行;新按键重置 timer(连续移动只预热最终落点,顺带消除连环 spawn/terminate host)
+- 清理点:`dispose()`、模式切换、组件卸载时 clearTimeout
+
+### Fix B:listRows 归档短路(src/core/store.mjs)
+
+- `listRows(root, opts)`:循环内先 `readMeta()`,若 `meta.archived && !opts.includeArchived` 则 `continue`,不再进入 `loadRow()` 的完整 artifact 加载(state/evidence/host/diagnostics/queue/steering)
+- `loadRow()` 本身不动(单行加载语义保持,service 内部按 id 操作仍走它)
+- 效果预估:artifact 读取从 168 行降到 11 行(本机),单次 listRows ~204ms → ~20-30ms
+- `pruneWarmHosts`、`reconcile()` 内的 listRows 自动受益,无需改动
+
+### Fix C:ensureHost 探测降级为 TTL(src/runtime/service.mjs)
+
+- `ensureHost` 的 `ptySupport({ refresh: true })` 改为默认参数(失败态 2s TTL,成功态进程生命周期缓存)
+- 依据:#37 已确立"成功探测必须缓存、失败探测短 TTL"纪律;refresh:true 在 PTY 故障环境下会造成按键路径每键 spawn
+
+## 决策表
+
+| 决策 | 选择 | 理由 |
+|---|---|---|
+| prewarm 延迟方式 | setTimeout 防抖 200ms | setImmediate 会在同帧渲染前抢跑;200ms 让连续导航只预热落点 |
+| 归档过滤位置 | listRows 内、readMeta 后 | 最小改动点;roster 不存 archived 标志,meta 是唯一权威来源 |
+| 防抖期间用户已 attach | timer 触发时再查模式,非 list/已切换则跳过 | 防止陈旧预热 |
+| evidence 按需加载 | 本期不做 | 归档短路后 11 行 evidence 读取 ~9ms,不构成瓶颈 |
+
+## 测试计划
+
+- 单测(store):临时目录构造 N 个 view,归档行**缺失** state/evidence/host 文件 → `listRows()` 不抛错、只返回非归档行(证明短路生效);`includeArchived: true` 行为不变
+- 单测(dashboard):模拟连续 moveSelection,断言 prewarm 仅在静默 200ms 后触发一次(注入 fake service 计数)
+- 存量测试全绿(`npm test`)
+- 性能验证(文档化,非 CI 断言):本机真实 store 上 listRows 前后耗时对比 + 按键-渲染延迟对比,数据回贴 issue
+
+## 降级/风险
+
+- 防抖延迟 prewarm 200ms:attach 预热收益不受影响(用户从选中到按 enter 远大于 200ms)
+- 归档短路只影响 `listRows`;service 单行路径(`loadRow`)不变,无行为回归面
+- Fix C 唯一语义变化:手动修复 PTY 权限后最多 2s 才重试(原为立即)——可接受

package/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Auto-discovery entry point. Pi loads `<extensions-dir>/<name>/index.ts`, so this
+ * re-exports the real extension from `src/index.ts`. Symlink this repo into
+ * `~/.pi/agent/extensions/agent-board` (or add its path to settings.json `extensions`).
+ */
+export { default } from "./src/index.ts";