@zhuxixi/pi-agent-board 0.3.0 → 0.3.1

package/docs/superpowers/plans/2026-08-22-rename-state-labels.md

@@ -0,0 +1,182 @@
+# Rename State Labels 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:** Rename dashboard state labels so each waiting state names the user action it waits for: `needs_input` → "Needs answer", `idle` → "Needs instructions", plus header wording "awaiting input" → "needs answer".
+
+**Architecture:** Display-only rename riding the existing label pipeline: `GROUP_LABELS` (group headers, confirm prompts, filter aliases) and `fallbackStatusText` (row summaries) are the two label sources; persisted summaries normalize at render time via `normalizeGenericStatusText` + `GENERIC_STATUS_TEXT` legacy sets, so old rows migrate visually with zero data writes.
+
+**Tech Stack:** Node.js ESM (`.mjs`) core + TypeScript UI file, `node --test` test runner, JSDoc typedefs.
+
+## Global Constraints
+
+- No changes to `SEMANTIC_STATES`, store schemas, state transitions, or classifier internals (issue #14's scope).
+- `GENERIC_STATUS_TEXT` sets only ever GROW — "Needs input", "Idle", "In Progress" must remain recognized legacy texts.
+- Do NOT edit `PRD.md` or `IMPLEMENTATION_PLAN.md` (historical point-in-time docs).
+- Commit messages in English, conventional-commits format; stage files explicitly (never `git add -A`).
+- All work happens in the worktree `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-15-rename-state-labels` (branch `issue-15-rename-state-labels`). Never touch the main checkout.
+- Exact new labels: `"Needs answer"` (needs_input), `"Needs instructions"` (idle), header `"needs answer"` / compact `"answer"`.
+
+---
+
+### Task 1: Core label constants and normalization (types.mjs, derive.mjs)
+
+**Files:**
+- Modify: `src/core/types.mjs:65,70` (`GROUP_LABELS`)
+- Modify: `src/core/derive.mjs:19-20,52-54` (`GENERIC_STATUS_TEXT`, `fallbackStatusText`)
+- Test: `test/derive.test.mjs:92-98`, `test/rows.test.mjs:85-88`
+
+**Interfaces:**
+- Consumes: none (leaf change).
+- Produces: `GROUP_LABELS.needs_input === "Needs answer"`, `GROUP_LABELS.idle === "Needs instructions"`; `fallbackStatusText("needs_input") === "Needs answer"`, `fallbackStatusText("idle") === "Needs instructions"`; `normalizeGenericStatusText` recognizes "Needs input" → needs_input label, {"Idle","In Progress"} → idle label.
+
+- [ ] **Step 1: Update the failing tests**
+
+In `test/derive.test.mjs`, extend the import (line 3) and replace/extend the fallback test:
+
+```js
+import { deriveSummary, fallbackStatusText, finalizeSemanticState, normalizeGenericStatusText } from "../src/core/derive.mjs";
+```
+
+```js
+test("fallbackStatusText", () => {
+	assert.equal(fallbackStatusText("queued"), "Queued");
+	assert.equal(fallbackStatusText("working"), "Running…");
+	assert.equal(fallbackStatusText("needs_input"), "Needs answer");
+	assert.equal(fallbackStatusText("idle"), "Needs instructions");
+});
+
+test("normalizeGenericStatusText maps legacy labels to current ones", () => {
+	assert.equal(normalizeGenericStatusText("idle", "Idle"), "Needs instructions");
+	assert.equal(normalizeGenericStatusText("idle", "In Progress"), "Needs instructions");
+	assert.equal(normalizeGenericStatusText("needs_input", "Needs input"), "Needs answer");
+	assert.equal(normalizeGenericStatusText("idle", "Custom summary"), "Custom summary");
+});
+```
+
+In `test/rows.test.mjs`, replace the existing normalization test (lines 85-88) with:
+
+```js
+test("rowView normalizes generic status labels to current display names", () => {
+	assert.equal(rowView(row("a", "working", { summary: "Working…" }), 0).summary, "Running…");
+	assert.equal(rowView(row("b", "idle", { summary: "Idle" }), 0).summary, "Needs instructions");
+	assert.equal(rowView(row("c", "idle", { summary: "In Progress" }), 0).summary, "Needs instructions");
+	assert.equal(rowView(row("d", "needs_input", { summary: "Needs input" }), 0).summary, "Needs answer");
+});
+```
+
+(`row(id, state, overrides)` is the existing test helper in that file.)
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `cd /home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-15-rename-state-labels && npm ci --no-audit --no-fund && node --test test/derive.test.mjs test/rows.test.mjs`
+Expected: FAIL — fallbackStatusText/rowView assertions return "Needs input"/"In Progress". (Skip `npm ci` if node_modules already exists.)
+
+- [ ] **Step 3: Implement**
+
+`src/core/types.mjs` — in `GROUP_LABELS`:
+
+```js
+needs_input: "Needs answer",
+```
+```js
+idle: "Needs instructions",
+```
+
+`src/core/derive.mjs` — legacy sets (keep old entries, add new):
+
+```js
+needs_input: new Set(["Needs input", "Needs answer"]),
+idle: new Set(["Idle", "In Progress", "Needs instructions"]),
+```
+
+`fallbackStatusText` cases:
+
+```js
+		case "needs_input":
+			return "Needs answer";
+		case "idle":
+			return "Needs instructions";
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `node --test test/derive.test.mjs test/rows.test.mjs`
+Expected: PASS (all tests in both files).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/types.mjs src/core/derive.mjs test/derive.test.mjs test/rows.test.mjs
+git commit -m "feat: rename needs_input/idle labels to Needs answer/Needs instructions (issue #15)"
+```
+
+### Task 2: Call-site labels and header wording (service.mjs, dashboard.ts, README)
+
+**Files:**
+- Modify: `src/runtime/service.mjs:961` (reconciled-host summary)
+- Modify: `src/ui/dashboard.ts:926` (compat-guard blank state summary), `src/ui/dashboard.ts:1757` (header stage part)
+- Modify: `README.md:65` (state list)
+- Test: none new — grep-confirmed zero test assertions on these exact strings; suite must stay green.
+
+**Interfaces:**
+- Consumes: Task 1 label values (only literals here; no imports of the strings).
+- Produces: none.
+
+- [ ] **Step 1: Edit the four call sites**
+
+`src/runtime/service.mjs` (~L961, inside `reconcile()`):
+```js
+s.summary = failed ? "Failed (PTY host exited)" : "Needs instructions";
+```
+
+`src/ui/dashboard.ts` (~L926, blank-state compat guard):
+```js
+			summary: "Needs instructions",
+```
+
+`src/ui/dashboard.ts` (~L1757, `headerStageSummary`):
+```js
+		headerStagePart(theme, "needs_input", counts.needs, compact ? "answer" : "needs answer"),
+```
+
+`README.md` (L65):
+```markdown
+- Watch rows move through `Queued`, `Running`, `Needs answer`, `Needs instructions`, `Done`, `Failed`, and `Stopped`.
+```
+
+- [ ] **Step 2: Run the full suite and typecheck**
+
+Run: `npm test && npm run typecheck`
+Expected: PASS — `node --test test/*.test.mjs` all green, `tsc --noEmit` clean.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/runtime/service.mjs src/ui/dashboard.ts README.md
+git commit -m "feat: apply Needs answer/Needs instructions wording to service, header, and README (issue #15)"
+```
+
+### Task 3: Full verification gate
+
+**Files:**
+- Modify: none (verification only; fix and amend-with-new-commit if anything fails).
+
+**Interfaces:**
+- Consumes: Tasks 1-2.
+- Produces: verified branch ready for review.
+
+- [ ] **Step 1: Run the project's standard gate**
+
+Run: `npm run verify`
+Expected: typecheck + full test suite + pack:dry all pass.
+
+- [ ] **Step 2: Sweep for stale label strings**
+
+Run: `grep -rn '"In Progress"' src/ README.md; grep -rn 'awaiting input' src/`
+Expected: "In Progress" appears ONLY in `src/core/derive.mjs` legacy set; "awaiting input" zero hits.
+
+- [ ] **Step 3: Confirm clean tree**
+
+Run: `git status --short && git log --oneline main..HEAD`
+Expected: clean tree; commits = spec + task 1 + task 2.

package/docs/superpowers/plans/2026-08-22-stable-list-order.md

@@ -0,0 +1,51 @@
+# Stable List Order 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:** Make the dashboard list order stable — rows must never reshuffle while sessions are running, so the cursor never loses its target (issue #20).
+
+**Architecture:** Replace activity-time sort keys with fixed creation-time keys. `lastActivityAt` stays in `RowView` for the "3s ago" display only, never for ordering. Rows sort by `pinned desc → createdAt asc → id asc`; folders sort by `pinned desc → min(createdAt) asc → name asc`, so a folder's position is anchored by its first-created row and doesn't jump when any row inside gets busy. New sessions append at the bottom (createdAt ascending).
+
+**Tech Stack:** Node 20+, ESM JavaScript (`.mjs` core), `node --test` test runner, no new dependencies.
+
+## Global Constraints
+
+- No new npm dependencies.
+- All commits in this worktree branch `issue-20-stable-list-order`; never touch `main` checkout.
+- `git add` per-file; never `git add -A`.
+- Commit messages in English, conventional-commits format, reference `issue #20`.
+- `npm run verify` (typecheck + tests + pack dry-run) must pass before the PR.
+
+---
+
+### Task 1: Stable row sort in `sortRowViews`
+
+**Files:**
+- Modify: `src/core/rows.mjs` (function `sortRowViews`)
+- Test: `test/rows.test.mjs`
+
+- [x] Add `createdAt` to `RowView` typedef and `rowView()` output (fallback `meta.updatedAt ?? 0`).
+- [x] Change sort keys to `pinned desc → createdAt asc → id asc`.
+- [x] Update `groupRows` doc comment ("pinned first, then creation order").
+- [x] Rewrite `groupRows sorts pinned first then recent` test → creation order, plus new regression test `groupRows ignores activity recency so order stays stable`.
+
+### Task 2: Stable folder sort in `groupRowsByFolder`
+
+**Files:**
+- Modify: `src/core/rows.mjs` (function `groupRowsByFolder`)
+- Test: `test/rows.test.mjs`
+
+- [x] Folder key `lastActivityAt` → `createdAt`, computed as `Math.min` over folder rows (first-created row anchors the folder).
+- [x] Folder sort keys → `pinned desc → createdAt asc → name asc`; update JSDoc return type.
+- [x] Update `groupRowsByFolder nests rows by folder inside each stage` expectations, plus new regression test `groupRowsByFolder keeps folder order stable regardless of activity`.
+
+### Task 3: Verify
+
+- [x] `node --test test/rows.test.mjs` — 18 pass.
+- [x] `npm run verify` — typecheck + full suite (200 pass) + pack dry-run.
+
+## Non-goals
+
+- Display of relative age ("3s ago") unchanged — still activity-based.
+- State-group order (`GROUP_ORDER`) unchanged — already fixed.
+- No reordering of the roster on disk; ordering is a pure view-model concern.

package/docs/superpowers/specs/2026-08-21-attach-coldstart-jiggle-rearm-design.md

@@ -0,0 +1,106 @@
+# Spec：attach 冷启动双光标根治 — jiggle 重试链编排修复（issue #10）
+
+## 日期
+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-issue-14-needs-input-no-auto-done-design.md

@@ -0,0 +1,109 @@
+# 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-rename-state-labels-design.md

@@ -0,0 +1,80 @@
+# Spec: Rename state labels — needs_input → "Needs answer", idle → "Needs instructions"
+
+- **Issue**: zhuxixi/pi-agent-board#15
+- **Date**: 2026-08-22
+- **Status**: approved (2026-08-22) — implemented on branch issue-15-rename-state-labels
+- **Type**: display-only rename, no data-model change
+
+## 1. Problem
+
+Dashboard semantic-state labels mislead. `idle` shows as "In Progress" but means *run ended, nothing asked, not confidently done* — the opposite of active work implied next to "Running". `needs_input` shows as "Needs input" but its distinct user action is *answering an explicit question*. The header collides lexically: needs_input counts read "awaiting input" while idle rows group under "In Progress".
+
+History (research): upstream `5c67518` renamed idle "Idle" → "In Progress" and introduced the legacy-text normalization mechanism; `99691e1` later made idle the auto-state classifier's "ended but not done" bucket, at which point the label started systematically misleading. Issue #14 (open) will make idle the default terminal bucket, increasing exposure.
+
+## 2. Goals
+
+- Each waiting state's label names the user action it waits for:
+  - `needs_input` → **"Needs answer"** — agent asked a question; it needs your reply.
+  - `idle` → **"Needs instructions"** — run ended cleanly; it needs your next directive (follow-up, new task, or mark-done).
+- Header needs_input stage reads "needs answer" (compact "answer") — no "awaiting" wording for needs_input, so "awaiting"-family ambiguity disappears.
+- Persisted rows display the new labels with zero migration.
+
+## 3. Non-goals
+
+- No changes to `SEMANTIC_STATES` internal names, store schemas (`meta.json`/`state.json`/`status.json`), state transitions, or the auto-state classifier internals — that is issue #14's scope.
+- No changes to historical docs (`PRD.md`, `IMPLEMENTATION_PLAN.md`) — they are point-in-time records.
+- No i18n layer.
+
+## 4. Design
+
+### 4.1 Label sources (code changes)
+
+| File | Change |
+|---|---|
+| `src/core/types.mjs` | `GROUP_LABELS.needs_input: "Needs input"` → `"Needs answer"`; `GROUP_LABELS.idle: "In Progress"` → `"Needs instructions"` |
+| `src/core/derive.mjs` | `fallbackStatusText("needs_input")` → `"Needs answer"`; `fallbackStatusText("idle")` → `"Needs instructions"` |
+| `src/runtime/service.mjs` (~L961) | reconciled-host summary `"In Progress"` → `"Needs instructions"` |
+| `src/ui/dashboard.ts` (~L926) | placeholder row summary `"In Progress"` → `"Needs instructions"` |
+| `src/ui/dashboard.ts` (~L1755) | headerStageSummary needs_input part: `"awaiting input"`/`"awaiting"` → `"needs answer"`/`"answer"` |
+| `README.md` (L65) | state list: `Needs answer`, `Needs instructions` |
+
+Stage headers render via `renderStageHeader` → `label.toUpperCase()`: displays "NEEDS ANSWER" / "NEEDS INSTRUCTIONS".
+
+### 4.2 Backward compatibility (reuse the 5c67518 pattern)
+
+`GENERIC_STATUS_TEXT` in `derive.mjs` is the recognized-legacy set consumed by `normalizeGenericStatusText(state, text)`, which `rowView()` (`rows.mjs`) applies at render time. Extend the sets; never shrink them:
+
+```js
+needs_input: new Set(["Needs input", "Needs answer"]),
+idle: new Set(["Idle", "In Progress", "Needs instructions"]),
+```
+
+Effect: rows persisted with any historical generic summary ("Idle", "In Progress", "Needs input") auto-display the current label. Non-generic summaries (real question text, error text) pass through untouched. No data migration, no store write.
+
+### 4.3 Auto-following surfaces (verify only)
+
+- Delete-confirm prompt and notices use `GROUP_LABELS[state].toLowerCase()` → "delete 3 needs instructions sessions?" (grammar acceptable).
+- Filter aliases (`rows.mjs`) = `[stateName, GROUP_LABELS[state]]` → "needs answer", "idle", "needs instructions" match; "in progress" stops matching (accepted; state name "idle" still matches).
+- Peek panel and header counts render derived values only.
+
+### 4.4 Tests
+
+Update string expectations:
+- `test/derive.test.mjs:96-97` — fallbackStatusText for both states.
+- `test/rows.test.mjs:87` — rowView normalization (legacy "Idle" → "Needs instructions").
+- `test/service.test.mjs` (~L334) — summary assertions touching "Needs input".
+
+Add normalization coverage:
+- legacy "In Progress" → "Needs instructions"; legacy "Needs input" → "Needs answer" (render-level, via rowView).
+- New fallback values appear for fresh runs.
+
+## 5. Error handling / edge cases
+
+- Old dashboard process + new code reading same store: summaries normalize on read; safe.
+- Rows whose summary was manually set to a non-generic string: untouched (pass-through preserved).
+- Classifier (`auto-state.mjs`) and steering prompts use internal kind names (`needs_input`/`in_progress`/`done`), not display labels — unaffected.
+
+## 6. Verification
+
+- `npm run verify` (project's standard gate) with updated tests.
+- Manual: open dashboard with pre-existing rows carrying old summaries → group headers and row summaries show new labels; header shows "needs answer".

package/package.json

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

package/runner/job-runner.mjs

@@ -13,14 +13,14 @@ import { fileURLToPath } from "node:url";
 import { appendLine, readJson } from "../src/core/atomic.mjs";
 import { createRunStatus, finalizeRun, projectViewState, reduceEvent } from "../src/core/events.mjs";
 import { encodePromptForCliArg } from "../src/core/prompt-transport.mjs";
-import { applyAutoStateToStatus, autoStateEnabled, autoStateFromModelOrHeuristic, autoStateModel, buildAutoStatePrompt, heuristicAutoState } from "../src/core/auto-state.mjs";
+import { applyAutoStateToStatus, autoStateEnabled, autoStateFromModelOrHeuristic, autoStateModel, buildAutoStatePrompt, heuristicAutoState, isManualCompletion } from "../src/core/auto-state.mjs";
 import { appendDiagnostic } from "../src/core/diagnostics.mjs";
 import { emptyEvidenceSnapshot, finalizeEvidence, reduceEvidence, summarizeEvidence, writeEvidence, writeRunEvidence } from "../src/core/evidence.mjs";
 import { claimNextFollowUp, completeFollowUp, releaseFollowUp } from "../src/core/follow-up-queue.mjs";
 import { newRunId } from "../src/core/ids.mjs";
 import { launchRun } from "../src/core/launch.mjs";
 import * as P from "../src/core/paths.mjs";
-import { readState, writeState, writeStatus } from "../src/core/store.mjs";
+import { readState, readStatus, writeState, writeStatus } from "../src/core/store.mjs";
 import { readSteering, recordPlanReady } from "../src/core/steering.mjs";
 import { buildApprovePlanPrompt, buildPlanChangesPrompt, buildPlanRequestPrompt } from "../src/core/steering-prompts.mjs";
 
@@ -102,6 +102,19 @@ function main() {
 		dirty = false;
 	};
 
+	/**
+	 * Persist only if the user hasn't marked the row done manually since the last
+	 * persist. projectViewState() overwrites the row state unconditionally, so a
+	 * post-exit model pass must never persist its stale in-memory status over a
+	 * fresh manual completion.
+	 */
+	const persistUnlessManual = (force = false) => {
+		const latestView = readState(root, viewId);
+		if (isManualCompletion(latestView)) return false;
+		persist(force);
+		return true;
+	};
+
 	const scheduleFlush = () => {
 		if (flushTimer) {
 			dirty = true;
@@ -206,12 +219,12 @@ function main() {
 				if (changed) {
 					finalizeEvidence(evidence, status, Date.now());
 					status.evidenceSummary = summarizeEvidence(evidence);
-					persist(true);
+					persistUnlessManual(true);
 				}
 				return maybeModelSummary(config, status);
 			})
 			.then((changed) => {
-				if (changed) persist(true);
+				if (changed) persistUnlessManual(true);
 			})
 			.catch(() => {})
 			.finally(() => {
@@ -333,6 +346,13 @@ async function maybeModelAutoState(config, status, evidence) {
 		[...config.piArgsPrefix, "--mode", "json", "-p", "--no-session", "--model", model, prompt],
 		15000,
 	);
+	// Fresh read: the user may have marked the row done manually during the model
+	// call. completeView clears autoState in both state.json and status.json, so a
+	// manual completion is detectable here; applying the classification to the stale
+	// in-memory status would clobber the user's verdict.
+	const fresh = readStatus(config.root, config.viewId, config.runId);
+	if (!fresh || isManualCompletion(fresh)) return false;
+	Object.assign(status, fresh);
 	const classification = autoStateFromModelOrHeuristic(out, latest, { lastAgentActivityAt: status.lastAgentActivityAt ?? null });
 	const changed = applyAutoStateToStatus(status, classification, Date.now());
 	if (changed) {
@@ -366,6 +386,10 @@ async function maybeModelSummary(config, status) {
 		[...config.piArgsPrefix, "--mode", "json", "-p", "--no-session", "--model", model, prompt],
 		15000,
 	);
+	// The user may have marked the row done manually during the summary call.
+	// Updating the stale status and letting the caller persist would clobber the
+	// manual completion, so bail out before touching the in-memory status.
+	if (isManualCompletion(readState(config.root, config.viewId))) return false;
 	const text = out.trim().split("\n").slice(-1)[0]?.trim();
 	if (text) {
 		status.summary = text.replace(/^["']|["']$/g, "").slice(0, 80);