@huseynsnmz/pi-board 0.15.3 → 0.16.0

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

@@ -1,142 +0,0 @@
-# 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-attach-coldstart-jiggle-rearm-design.md

@@ -1,110 +0,0 @@
-# Spec：attach 冷启动双光标根治 — jiggle 重试链编排修复（issue #10）
-
-> **历史设计，已被 issue #25 的 shrink-and-hold 及 issue #42 的 G6
-> post-restore verify supersede。** 当前实现和测试以
-> `src/core/pty-attach-jiggle-controller.mjs` 为准。
-
-## 日期
-2026-08-21（v2：评审后修订，补三项编排严谨性修正）
-
-## 问题
-
-d10f21d（issue #2 修复）的 jiggle 重试链在**编排层**有三个不覆盖点，导致冷启动 attach 双光标未根治：
-
-1. **启动时机错位**：链从 socket connect 即启动（start&attach 流程下 = spawn+0.3-0.5s），而冷启动 pi-tui 要 ~5.1-5.2s 才装好 resize 监听（EXP-2 实测 5180/5199/5191ms），链的窗口（connect+0.12~5.12s）全部落在 TUI 不存在的时段，注定空枪。
-2. **jiggle 结构脆弱**：±1 尺寸、shrink→restore 仅隔 40ms。初始 sendResize 在 TUI 启动前白花掉唯一一次真实尺寸变化（120x36→196x39）；后续重试全是围绕已正确尺寸的 ±1 噪声，启动期繁忙事件循环 + pi-tui 16ms 渲染节流可将其合并成净零变化 → 命中也不清屏。
-3. **链断零自愈**：链耗尽即 stopRetry，一次性补偿已被 d10f21d 移除；此后脏屏只能等用户 detach/reattach 或拖窗口。
-
-状态机本身（pty-attach-jiggle-retry.mjs）无 bug，不推翻，只改编排。
-
-## 设计原则
-
-- 沿用"可测性优先"：新增逻辑抽成纯函数/可注入控制器，验收 = 单测 + 一个确定性 E2E。
-- 不碰 runner（它即时应用 resize，无 debounce，无责）。
-- 保留 settle-survive（ADR 202608211244444979 已记录取舍）。
-- 失同步检测兜底**不在本 issue**（→ #11）。
-
-## 方案（四个改动）
-
-### 改动 1：重试链 re-arm — 首个 TUI 帧触发（一次性锁存）
-
-**信号**：子 pi-tui 每帧（含差分帧）以 `\x1b[?2026h`（synchronized output begin）开头；冷启动 boot 期扩展输出不含该序列（EXP-2 screen.log 验证）→ 首个 `\x1b[?2026h` = "TUI 已开始渲染"的可靠信号。
-
-**纯逻辑层**（`src/core/pty-attach-jiggle-retry.mjs` 扩展）：
-
-```typescript
-/** 检测数据中是否含 TUI 帧开始序列（跨 chunk 安全） */
-function hasTuiFrameStart(data: string): boolean; // 查 \x1b[?2026h
-```
-
-**跨 chunk carry 修正（评审修正 #2）**：现有 `CARRY_LEN = 3` 只服务四字节的 `\x1b[2J`；`\x1b[?2026h` 是 8 字节序列，跨 chunk 时会漏检。**carry 统一扩到 7 字节**（两个目标序列的公共前缀都是 `\x1b[`；`tailCarry` 从尾部 7 字节里找最后一个 `\x1b` 起携带，逻辑同构）。feedOutput 返回值增加 `frameStartFound`，与 `clearFound` 共用同一次扫描与 carry。
-
-**编排层**（`src/ui/pty-attach.ts`）：
-- connect 时照旧 `startJiggleRetry()`（保热 attach 现状）。
-- 新增组件字段 `tuiFrameSeen = false`（**一次性锁存，评审修正 #1**）：output 路径检测到首个 `\x1b[?2026h` 且 `!tuiFrameSeen && !clearDetected` 时，置 `tuiFrameSeen = true` 并重置链为新状态机（retryIndex=0、预算计满）。**没有锁存的话 streaming 中每一帧都会 re-arm，退避永远走不完（评审发现的设计缺陷）。**
-- **clear 优先规则（评审修正 #2 附带）**：同一 chunk 同时含 frame-start 与 clear（热 attach 常见：首帧即全清帧）时，先处理 clear（停链），re-arm 判断以"clear 处理后的最新状态"为准，禁止刚成功又被重置。
-- 冷启动效果：TUI 开始渲染的瞬间链重启，第一个 jiggle 必落在活 TUI 上 → ~120ms 内见到 \x1b[2J。
-- 热 attach 效果：首帧几乎与 connect 同时到达，链重置一次后首个 jiggle 立即成功自停；等价于现状。
-
-### 改动 2：退避尾部拉长（与 60s 验收对齐，评审修正 #3）
-
-```typescript
-const BACKOFF_MS = [120, 500, 1500, 3000, 6000, 10000, 15000, 20000]; // 8 次，累计 56.12s
-```
-
-- 依据：jiggle 对健康 session 无害（见到 clear 自停）；长尾部只在前序全失败（画面本就脏）时才走完，代价已在 settle-survive ADR 中接受。
-- **累计窗口必须与"60s 内自愈"验收标准一致（评审修正 #3）**：v1 草案的 ~92s 与验收冲突，修正为 56.12s。
-- 与改动 1 的关系：改动 1 解决"时机"，改动 2 兜底"比 5s 更极端的慢启动/合并丢失"。
-
-### 改动 3：jiggle 抗合并 — restore 延时 40ms → 200ms
-
-- `forceChildRedraw` 的 `redrawTimer` 延时抽为常量 `JIGGLE_RESTORE_MS = 200`。
-- 依据：200ms > pi-tui 16ms 节流一个数量级，启动期繁忙循环也能把 shrink/restore 分成两次独立渲染（各触发一次 fullRender）。
-- 副作用评估：jiggle 只发给子端 PTY，不改本地 xterm 尺寸；settle defer 已覆盖 redraw 窗口；post-settle 残余 jiggle 的闪烁取舍同 ADR。
-- 不采纳的备选：交替幅度 -1/-2（对"基线已正确"场景无效，徒增复杂度）。
-
-### 改动 4：确定性 E2E 测试（验收核心）
-
-编排层抽取：把"timer 调度 + jiggle 发送 + output 喂入"从 PtyAttachComponent 抽成**可注入控制器**（注入 scheduler 与 sendJiggle 回调），组件退化为薄 adapter。控制器可脱离 TUI 单测/E2E。
-
-- `test/pty-attach-jiggle-controller.test.mjs`（单测级）：首帧检测（含跨 chunk 边界切割）、`tuiFrameSeen` 一次性锁存（第二帧不再 re-arm）、clear 优先规则、新退避表累计值、链在见 clear 后自停。
-- `test/pty-attach-cold-start-e2e.test.mjs`：真实 pty-runner（node-pty）+ **stub 子进程**（node 脚本：延迟 8s 才"启动 TUI"——开始发 `\x1b[?2026h` 帧并安装 resize 监听；监听到 resize 且 TUI 已启动时回发 fullRender + `\x1b[2J`）+ 真实控制器。断言 **30s 内检测到 \x1b[2J**。
-  - 反证有效性：stub 延迟 8s > 旧链窗口 5.12s，旧编排在该测试下必失败。
-  - 时长 ~10-15s，可进 `npm test`；如 CI 敏感再拆慢测试脚本。
-
-## 决策表
-
-| 决策点 | 选择 | 理由 |
-|---|---|---|
-| TUI 就绪信号 | `\x1b[?2026h` | 每帧必有；boot 噪声不含（实测）；零成本 |
-| re-arm vs 仅首帧启动 | re-arm（connect 链保留） | 热/冷统一；热路径不变 |
-| re-arm 次数 | 每次连接仅一次（tuiFrameSeen 锁存） | 防 streaming 每帧重置链 |
-| frame-start 与 clear 同 chunk | clear 优先 | 防刚成功又被重置 |
-| restore 延时 | 200ms 常量 | ≫16ms 节流；对 attach 投影无影响 |
-| 退避尾部 | 8 次 / 累计 56.12s | 对齐 60s 验收；健康 session 自停 |
-| E2E 方式 | stub 子进程 + 真 runner + 真控制器 | 确定性、快、可 CI |
-
-## 降级
-
-- pi-tui 若改掉 2026h：re-arm 失效但 connect 链 + 长预算仍在，退化为"比现在好"（文档化注释）。
-- pi-tui 若 fullRender 不再发 \x1b[2J：同 d10f21d 已文档化的退化（链按预算走完即停，不 worse than one-shot）。
-
-## 非目标
-
-- 失同步检测渲染兜底（→ #11）。
-- screen.log 重放无锚点问题（#2 已分析，jiggle 即其解药）。
-- runner / pi-tui 侧改动。
-- 外层 ghost 内容（"[Themes] light-warm" 残留）——独立 cosmetic 问题，不在此列。
-
-## 验收标准
-
-1. 新 E2E 通过（stub 8s 延迟 TUI，30s 内见 \x1b[2J）；且能证明旧编排下失败。
-2. 新增单测通过；既有测试（jiggle-retry 状态机等）不回归；`npm run typecheck` 过。
-3. 人工实机验证：start & attach 冷启动一个重扩展 session，双光标/脏帧在 60s 内自愈，无需 detach/reattach。
-4. 热 session attach 无劣化（首个 jiggle 见 clear 自停，无多余重绘）。
-
-## 评审修订记录（v2）
-
-1. re-arm 必须加一次性锁存 `tuiFrameSeen`（否则 streaming 每帧重置链，退避失效）。
-2. 跨 chunk carry 从 3 字节扩到 7 字节（`\x1b[?2026h` 为 8 字节序列）；同 chunk 含 frame-start+clear 时 clear 优先。
-3. 退避表从 ~92s 收敛为累计 56.12s，与"60s 内自愈"验收标准对齐。

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

@@ -1,59 +0,0 @@
-# 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/docs/superpowers/specs/2026-08-21-issue-14-needs-input-no-auto-done-design.md

@@ -1,109 +0,0 @@
-# Spec: 运行中提问归类 needs_input + 永不自动 done（issue #14）
-
-- Date: 2026-08-21
-- Issue: https://github.com/zhuxixi/pi-agent-board/issues/14
-- Status: design approved by user (2026-08-21 23:49)
-
-## 1. 背景与现状（research 已闭环）
-
-- hosted/foreground 场景的 `ask_questions` 工具提问 → `needs_input` **已实现**（#42, commit 752db70，`preservePendingQuestion()`），测试已覆盖。
-- **Gap A**：自然语言文本提问（`detectNeedsInput` 命中）运行中只写 `status.question`，`semanticState` 仍强制 `working`（`events.mjs` `message_end` 分支）。
-- **Gap B**：detached（job-runner）场景 `ask_questions` 不 track——**用户确认不用管**（headless 不会提问，也回复不了）。非目标。
-- **Gap C**：进程退出后 auto-state（`heuristicAutoState().hasDoneSignal()` + state-runner 模型分类）会把行自动归类 `completed`。`finalizeSemanticState()` 本身不产生 completed。
-
-## 2. 需求
-
-1. 运行中（`processState === "alive"`）session 的**文本提问**也归类为 `needs_input`（面板 input 类型），覆盖 hosted / detached / foreground 全部场景。
-2. **永不自动归类 `completed`（done）**；`completed` 只由用户手动 mark completed 产生。
-
-## 3. 设计决策
-
-| 决策点 | 结论 | 依据 |
-|--------|------|------|
-| 提问检测 | 复用现有 `detectNeedsInput`（保守：结尾问号或短语命中） | 已在 `finalizeRun` 长期使用，行为成熟 |
-| 恢复机制 | 依赖既有 `message_start` / `tool_execution_start` / 无问题 `message_end` 设回 `working` | 天然存在，不加新状态机 |
-| pending 优先 | `preservePendingQuestion()` 保持最后调用，pending 存在时覆盖为 `needs_input` | #42 并行语义不回退 |
-| 不自动 done 的强度 | **彻底**：auto-state 永不产出 done（启发式 + 模型输出均降级为 in_progress/idle） | 用户拍板 |
-| 回退开关 | `AGENT_BOARD_AUTO_STATE_NO_DONE`，默认开（不自动 done）；`0`/`false`/`off` 恢复旧行为 | 保守可回退 |
-| detached 回复路径 | 不改（保持 #42 现状） | 用户确认不用管 |
-| alive guard | 不改（运行中分类全由 events.mjs 负责；auto-state 仅在 run 结束后触发，无运行中调用路径） | 改动面最小 |
-
-## 4. 改动点（文件级）
-
-### 4.1 `src/core/events.mjs` — `reduceEvent()` `message_end` 分支
-
-现状：
-```js
-if (text) {
-    status.latestAssistantPreview = truncate(text, PREVIEW_MAX);
-    const nb = detectNeedsInput(text);
-    status.question = nb.question;
-}
-status.semanticState = "working";
-preservePendingQuestion(status);
-```
-
-改为（仅一行条件）：
-```js
-if (text) {
-    status.latestAssistantPreview = truncate(text, PREVIEW_MAX);
-    const nb = detectNeedsInput(text);
-    status.question = nb.question;
-}
-status.semanticState = nb.needsInput ? "needs_input" : "working";
-preservePendingQuestion(status);
-```
-
-注意 `nb` 需提到 `if (text)` 作用域外（`let nb = { needsInput: false, question: null }` 初始值，空文本时不误判）。
-
-### 4.2 `src/core/auto-state.mjs` — 永不自动 done
-
-1. `autoStateDoneDisabled(env)` 辅助：读 `AGENT_BOARD_AUTO_STATE_NO_DONE`（默认**开**=禁用自动 done）。
-2. `heuristicAutoState()`：`done && !pending` 分支移除；`hasDoneSignal` 命中时返回 `in_progress`（reason 说明"completion detected but auto-done disabled"）。
-3. `parseAutoStateModelOutput()`：解析到 `done` 且开关开 → 降级 `in_progress`；开关关 → 保持 `done`。
-4. `buildAutoStatePrompt()`：开关开时 prompt 只有两态（`needs_input` / `in_progress`），并提示"completed 由用户手动标记"；开关关时恢复原三态 prompt。
-5. `applyAutoStateToStatus()` / `applyAutoStateToViewState()`：guard 增加 `semanticState === "completed"` 直接 return false（**手动完成的 state 不被自动分类覆盖**，现有 guard 只排除 failed/stopped）。
-
-（开关关 = 全部旧行为，保证可回退。）
-
-### 4.3 测试
-
-1. `test/events.test.mjs` 新增：
-   - "message_end 文本以问号结尾 → semanticState=needs_input，question 非空（无 pending 场景）"
-   - "needs_input 后下一条无问题 message_end → 回 working"
-   - "pending question 存在时 message_end 文本无问题 → 仍 needs_input（pending 优先回归）"
-2. `test/auto-state.test.mjs` 更新：
-   - L6-11 模型输出 done → 默认降级 in_progress；开关关 → done（新增开关关用例）
-   - L25 启发式 "Done. Fixed the bug and tests pass." → in_progress
-   - L29-42 applyAutoStateToStatus → 默认 idle（不再 completed）；开关关 → completed（保持旧断言）
-3. 全量 `npm run verify` 绿。
-
-## 5. 验收标准（Success Criteria）
-
-1. 运行中 hosted session，assistant 文本以问题结尾 → 面板归类 input（`needs_input`），glyph ◇，分组进 needs_input。
-2. 运行中 detached session 文本提问 → 同上。
-3. `ask_questions` 工具提问归类 needs_input 不回退（现有测试仍绿）。
-4. 提问后 agent 继续工作（新消息/工具）→ 自动回 working。
-5. run 结束后启发式/模型分类**不产生** completed；行停留在 idle 或 needs_input。
-6. 手动 mark completed 仍可用，且手动完成的 state 不被 auto-state 覆盖。
-7. `AGENT_BOARD_AUTO_STATE_NO_DONE=0` 时恢复旧行为（可自动 done）。
-8. `npm run verify`（typecheck + test + pack dry-run）全绿。
-
-## 6. 非目标
-
-- detached 场景的回复路径改造。
-- auto-state alive guard 放宽（无调用路径，不加死代码）。
-- UI 分组/排序/颜色变化（`semanticState` 已驱动全部显示）。
-- 模型分类器更换或精度调优。
-
-## 7. 风险与缓解
-
-| 风险 | 等级 | 缓解 |
-|------|------|------|
-| 文本提问误报（引用问句） | 低 | 检测器只认结尾问号/短语；下一条消息自动恢复 working |
-| pre-existing flaky 集成测试干扰 verify | 低 | 单文件重跑验证；与本改动无关的失败单独记录 |
-| 模型降级路径缓存 | 低 | prompt 变化 → textHash 变化 → 自动重分类一次，无害 |
-
-## 8. 成功率评估（用户已确认）
-
-核心实现成功率 ~90-95%；残余风险为自然语言边缘判定与 pre-existing flaky 测试。流程保障：TDD → 本地 CR → Zima 单 Bot CR → merge。

package/docs/superpowers/specs/2026-08-22-cwd-favorites-design.md

@@ -1,131 +0,0 @@
-# Spec: Launch 对话框 cwd 常用目录榜（频率排名 + 模糊补全）
-
-- Date: 2026-08-22
-- Status: draft（待 review）
-
-## Background
-
-Ctrl+N 打开 launch 对话框后，`cwd` 字段进入目录选择器，目前只能从 `~` 开始逐层
-浏览 + 输入过滤（`src/core/launch-options.mjs` 的 `listDirectorySuggestions`，
-`src/ui/dashboard.ts` 的 launch picker）。launch-prefs.json 只记忆上一次的 cwd，
-没有「常用目录」概念。
-
-本机现状（2026-08-22 实测）：agent-board 共 177 个 view，cwd 分布高度集中——
-`/home/elling` 107 次、`zima-blue-cli` 20、`jfox` 17、`.pi/agent/extensions` 10、
-`pi-agent-board` 10，其余个位数。用户每次起 session 都要手动浏览目录，重复劳动。
-
-用户需求：按**真实使用频率自动排名**的候选目录榜，用得越多排越前；纯键盘快速
-选择；并且输入时能做**路径补全**（输入 `jfox` → 出现完整路径 → tab/回车补全），
-类似 zsh 的 cd 补全体验。
-
-## Goals
-
-1. 持久化的 cwd 使用统计：每次成功发起 session 时对 cwd 计数 +1；统计独立于
-   session 生命周期（删 view 不减计数）。
-2. 首次使用时从现有 view 的 meta.json 一次性导入计数，立即有榜单数据。
-3. cwd 选择器交互升级：
-   - 打开选择器（未输入）时显示频率榜 Top 8，↑↓ 选 + 回车直接确认；
-   - 输入时先对候选榜做大小写不敏感子串匹配（路径任意部分）；
-   - 有匹配 → 候选模式显示匹配项；无匹配 → 回落现有文件系统浏览（旧能力完整保留）；
-   - tab 把高亮项的完整路径补全进输入框（picker 保持打开，可继续微调），
-     回车最终确认；输入框内容本身就是有效路径时回车直接生效。
-4. 候选行显示 `~` 简写路径 + 使用次数（如 `107×`）。
-
-## Non-goals
-
-- 不做手动收藏/置顶编辑（无配置文件 UI）。
-- 不做模糊 subsequence 匹配（先做子串，不够再升级）。
-- 不改 launch-prefs.json 结构。
-- 不改 launch 对话框的其他字段（model/thinking/action）。
-
-## Design
-
-### 新模块：`src/core/cwd-stats.mjs`
-
-- 新文件 `~/.pi/agent/agent-board/cwd-stats.json`（root 由现有
-  `paths.mjs` 的 `defaultRoot()` 派生，尊重 `$AGENT_BOARD_ROOT`）：
-
-```json
-{
-  "version": 1,
-  "entries": {
-    "/home/elling": { "count": 107, "lastUsed": 1756332000000 }
-  }
-}
-```
-
-- `paths.mjs` 增加 `cwdStatsPath(root)`，风格与 `launchPrefsPath` 一致。
-- 函数：
-  - `readCwdStats(root)`：缺失/损坏 → 返回空 entries（沿用 store.mjs 的容错读风格）。
-  - `seedCwdStatsFromViews(root)`：仅当 cwd-stats.json 不存在时执行；遍历
-    roster 全部 view 的 meta.json，按 cwd 聚合计数，lastUsed 取该 cwd 下 view 的
-    updatedAt 最大值（缺失则用当前时间）；原子写（`atomicWriteJson`）。
-  - `recordCwdLaunch(root, cwd)`：count +1、lastUsed 更新，原子写；cwd 非法
-    （空/不存在）直接忽略。
-  - `rankedCwdCandidates(root, limit)`：count 降序、lastUsed 降序；末尾始终补
-    home 目录兜底（若不在榜内则 count 0 排最后），保证「用户根目录」永远可一键选。
-- 写入用 `src/core/atomic.mjs` 的 `atomicWriteJson`（temp + rename，防并发写坏），
-  与 board 现有 meta.json 写入同款。
-
-### 埋点
-
-- `src/ui/dashboard.ts` 的 `submitDispatch`：`res.ok` 分支内
-  `recordCwdLaunch(root, launchCwd)`，try/catch 尽力而为，失败不影响派发。
-- lazy seed：launch 对话框首次打开（`openLaunchDialog`）时若 cwd-stats.json
-  不存在则调用 `seedCwdStatsFromViews`（同步、一次性、容错）。
-
-### 选择器交互
-
-`LaunchState` 增加字段：
-- `cwdRanked: {path, count}[]`：打开 picker 时由 `rankedCwdCandidates(root, 8)` 生成；
-- `cwdPickerMode: "favorites" | "browse"`：候选模式 / 文件系统浏览模式。
-
-行为规则（`openLaunchPicker("cwd")` 与 `handleLaunchPickerKey`）：
-
-| 输入（cwdQuery） | 模式 | 建议列表 |
-| --- | --- | --- |
-| 空 | favorites | 频率榜 Top 8，首项高亮 |
-| 非空，候选榜有子串匹配（大小写不敏感、路径任意部分） | favorites | 匹配项（保持排名序） |
-| 非空，无匹配 | browse | 现有 `listDirectorySuggestions` 文件系统浏览 |
-
-- 打开 picker 时 cwdQuery 置空（不再 seed 成 `~`）；在 launch 主对话框 cwd 字段上
-  直接打字进入 picker 时，query = 已输入字符（现有 type-to-jump 行为保留）。
-  输入 `~` 等无候选匹配时自然进入 browse 模式，旧浏览能力保留。
-- tab（favorites 模式）：`cwdQuery = 高亮项完整路径`，picker 保持打开；
-  此时输入框即完整路径，回车经现有 `resolveDirectoryValue` 直接生效。
-- 回车（favorites 模式）：选中高亮项。
-- esc：关闭 picker（现有行为）。
-- ↑↓：移动高亮（现有逻辑复用）。
-
-### 渲染
-
-- favorites 模式候选行：`displayPath(value)`（`~` 简写）+ 右侧 dim 次数
-  （`{count}×`）；browse 模式渲染不变。
-- 底部提示区分文案：
-  - favorites：`常用目录 · type to search · tab complete · enter choose · esc back`
-  - browse：现有 `type to filter folders · enter choose · esc back`
-
-## Error handling
-
-- 统计读写全部容错：损坏的 cwd-stats.json 视为空表，永不抛到 UI。
-- seed 与 record 的失败静默忽略（console 调试输出可选）。
-- 榜单为空（无 stats、无 home）时 picker 直接进入 browse 模式，行为与现状一致。
-
-## Testing
-
-- `test/cwd-stats.test.mjs`（新）：seed 从 views 导入、record 累加与 lastUsed、
-  排序（count 优先、lastUsed tie-break）、损坏文件容错、home 兜底、空表行为。
-- 候选匹配逻辑（新函数，放 launch-options.mjs 或 cwd-stats.mjs）：大小写不敏感、
-  路径任意部分匹配、无匹配判定。
-- `test/dashboard-render.test.mjs`：repo 现状无 DashboardComponent 单测 harness，picker
-  渲染断言由 Task 5 手工验收覆盖（路径 + 次数、browse 模式渲染不变）。
-- 所有测试用 tmp dir 作 root（沿 paths.mjs「显式 root 可测」约定）。
-
-## Verification
-
-- 启动后打开 launch 对话框 cwd 选择器：Top 榜应为 `~`（107×）、zima-blue-cli 等，
-  与现有 view 统计一致。
-- 输入 `jfox`：`~/git-repo/github/jfox` 出现在榜中；tab 补全完整路径；回车发起
-  session；再次打开选择器 jfox 计数 +1。
-- 输入 `~`：回落文件系统浏览，旧行为不变。
-- 删除某 view 后计数不变（stats 独立于 view 生命周期）。