@zhuxixi/pi-agent-board 0.3.1 → 0.4.1

package/docs/superpowers/plans/2026-08-22-question-tool-grouping.md

@@ -0,0 +1,211 @@
+# Question/Questionnaire Tool Grouping 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 pi sessions blocked on the `question`/`questionnaire` tools group under "Needs answer" instead of "Running".
+
+**Architecture:** Two minimal changes to `src/core/events.mjs`: (1) extend the private `questionFromArgs` helper to read pi's arg shapes; (2) replace the hardcoded `=== "ask_questions"` name checks with a `QUESTION_TOOL_NAMES` set. All downstream behavior (needs_input state, grouping, summary) already exists via `preservePendingQuestion` and `deriveSummary` — verified in spec section 3.3, nothing else changes.
+
+**Tech Stack:** Node.js (`.mjs` ESM, no deps), `node:test` + `node:assert/strict` for tests.
+
+## Global Constraints
+
+- All code changes confined to `src/core/events.mjs` and `test/events.test.mjs`.
+- No store/schema/type changes; no changes to `finalizeRun`, `projectViewState`, `deriveSummary`, `rows.mjs`, `service.mjs`.
+- Non-interactive (detached) reduction path keeps its current behavior — the `opts.interactive` gate stays.
+- Static name set, no config surface.
+- Commit messages in conventional commits format; stage files individually (`git add <file>`), never `git add -A`.
+- Test command: `node --test test/events.test.mjs`; project gate: `npm run verify`.
+- Work in worktree `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-26-question-tool-grouping`; never touch main.
+
+---
+
+### Task 1: Extend `questionFromArgs` for pi arg shapes
+
+**Files:**
+- Modify: `src/core/events.mjs:229-235`
+- Test: `test/events.test.mjs` (append new test near the ask_questions tests, after line 160)
+
+**Interfaces:**
+- Consumes: nothing new.
+- Produces: `questionFromArgs(args)` (private) returns the first non-empty question text from: `args.question` (string), or `args.questions[]` items' `question` or `prompt` fields; falls back to `"Answer the pending question"`. Task 2's name-recognition relies on this extraction.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `test/events.test.mjs` (after the "interactive questions remain visible..." test):
+
+```js
+test("questionFromArgs extracts pi question/questionnaire arg shapes", () => {
+	// pi `question` tool shape: args.question is a plain string.
+	const s1 = createRunStatus(cfg(), 1, 1000);
+	reduceEvent(s1, {
+		type: "tool_execution_start",
+		toolCallId: "q1",
+		toolName: "ask_questions",
+		args: { question: "Approve the plan?" },
+	}, 2000, { interactive: true });
+	assert.equal(s1.question, "Approve the plan?");
+
+	// pi `questionnaire` tool shape: args.questions[].prompt.
+	const s2 = createRunStatus(cfg(), 1, 1000);
+	reduceEvent(s2, {
+		type: "tool_execution_start",
+		toolCallId: "q1",
+		toolName: "ask_questions",
+		args: { questions: [{ prompt: "Pick the scope?" }] },
+	}, 2000, { interactive: true });
+	assert.equal(s2.question, "Pick the scope?");
+});
+```
+
+Note: the tests route through the reducer with the already-recognized `ask_questions` name because `questionFromArgs` is private and the reducer is the public surface; name recognition for the pi tools lands in Task 2.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `node --test test/events.test.mjs`
+Expected: FAIL — both assertions get `"Answer the pending question"` (the current extractor only reads `questions[].question`).
+
+- [ ] **Step 3: Implement the extractor**
+
+Replace the body of `questionFromArgs` in `src/core/events.mjs` (L229-235):
+
+```js
+function questionFromArgs(args) {
+	if (typeof args?.question === "string" && args.question.trim()) return args.question.trim();
+	for (const item of Array.isArray(args?.questions) ? args.questions : []) {
+		const question = String(item?.question ?? item?.prompt ?? "").trim();
+		if (question) return question;
+	}
+	return "Answer the pending question";
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `node --test test/events.test.mjs`
+Expected: PASS (all 17 existing + 1 new test).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/events.mjs test/events.test.mjs
+git commit -m "fix: support pi question arg shapes in questionFromArgs (issue #26)"
+```
+
+---
+
+### Task 2: Recognize `question`/`questionnaire` as pending-question tools
+
+**Files:**
+- Modify: `src/core/events.mjs:25-27` (insert set), `src/core/events.mjs:83`, `src/core/events.mjs:97`
+- Test: `test/events.test.mjs` (append three tests after the Task 1 test)
+
+**Interfaces:**
+- Consumes: `questionFromArgs` extraction from Task 1.
+- Produces: `QUESTION_TOOL_NAMES` (module-private `Set<string>`). `reduceEvent` treats any interactive tool_execution_start/end whose tool name is in the set as a pending-question event — `upsertPendingQuestion`/`removePendingQuestion` plus the existing `preservePendingQuestion` flow (needs_input state, `currentTool = null`).
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `test/events.test.mjs`:
+
+```js
+test("interactive pi question tool is treated as a pending question", () => {
+	const s = createRunStatus(cfg(), 1, 1000);
+	reduceEvent(s, {
+		type: "tool_execution_start",
+		toolCallId: "q1",
+		toolName: "question",
+		args: { question: "Approve the plan?", options: [{ label: "Yes" }, { label: "No" }] },
+	}, 2000, { interactive: true });
+	assert.equal(s.semanticState, "needs_input");
+	assert.equal(s.question, "Approve the plan?");
+	assert.equal(s.currentTool, null);
+	assert.equal(s.summary, "Approve the plan?");
+	assert.deepEqual(s.pendingQuestions, [{ toolCallId: "q1", question: "Approve the plan?" }]);
+	assert.equal(projectViewState(s, 2100).needsInput, true);
+
+	reduceEvent(s, { type: "tool_execution_end", toolCallId: "q1", toolName: "question", isError: false }, 2400, { interactive: true });
+	assert.equal(s.semanticState, "working");
+	assert.equal(s.question, null);
+	assert.deepEqual(s.pendingQuestions, []);
+});
+
+test("interactive questionnaire tool extracts prompt and clears on end", () => {
+	const s = createRunStatus(cfg(), 1, 1000);
+	reduceEvent(s, {
+		type: "tool_execution_start",
+		toolCallId: "q1",
+		toolName: "questionnaire",
+		args: { questions: [{ prompt: "Pick the scope?" }] },
+	}, 2000, { interactive: true });
+	assert.equal(s.semanticState, "needs_input");
+	assert.equal(s.question, "Pick the scope?");
+	reduceEvent(s, { type: "tool_execution_end", toolCallId: "q1", toolName: "questionnaire", isError: false }, 2400, { interactive: true });
+	assert.equal(s.semanticState, "working");
+});
+
+test("detached question tool keeps legacy currentTool behavior", () => {
+	const s = createRunStatus(cfg(), 1, 1000);
+	reduceEvent(s, { type: "tool_execution_start", toolCallId: "q1", toolName: "question", args: { question: "Approve?" } }, 2000);
+	assert.equal(s.semanticState, "working");
+	assert.equal(s.currentTool.name, "question");
+	assert.deepEqual(s.pendingQuestions, []);
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `node --test test/events.test.mjs`
+Expected: FAIL — question/questionnaire names are not recognized: first test asserts `needs_input` but gets `working` with `currentTool.name === "question"`.
+
+- [ ] **Step 3: Add the name set and wire the two checks**
+
+Insert after the imports at the top of `src/core/events.mjs` (before `createRunStatus`, ~L25):
+
+```js
+/** Tool names whose interactive execution blocks on a user answer. */
+const QUESTION_TOOL_NAMES = new Set(["ask_questions", "question", "questionnaire"]);
+```
+
+Replace L83:
+
+```js
+			if (opts.interactive && QUESTION_TOOL_NAMES.has(name)) {
+```
+
+Replace L97:
+
+```js
+			if (opts.interactive && QUESTION_TOOL_NAMES.has(event.toolName ?? "")) removePendingQuestion(status, event.toolCallId);
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `node --test test/events.test.mjs`
+Expected: PASS (21 tests total: 17 existing + 1 Task 1 + 3 new). Existing `ask_questions` tests must pass unchanged.
+
+- [ ] **Step 5: Full project gate**
+
+Run: `npm run verify`
+Expected: typecheck, all tests, and pack dry-run pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/core/events.mjs test/events.test.mjs
+git commit -m "fix: recognize question/questionnaire tools as pending questions (issue #26)"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- Spec 3.1 (QUESTION_TOOL_NAMES replacing both hardcoded checks) → Task 2 steps 3. ✓
+- Spec 3.2 (questionFromArgs pi shapes: `args.question`, `items[].prompt`, fallback `item.question`) → Task 1 step 3. ✓
+- Spec 3.4 tests 1-4 (question start→needs_input, questionnaire extraction, end→working, detached unchanged) → Task 2 step 1 + Task 1 step 1. ✓
+- Spec 3.3 downstream flow unchanged → asserted via `summary`/`needsInput` in Task 2 test 1; no production code touched outside `events.mjs`. ✓
+
+**Placeholder scan:** every step carries concrete code or exact commands; no TBD/TODO/"similar to". ✓
+
+**Type consistency:** `QUESTION_TOOL_NAMES` used identically in both replace steps; arg fields (`question`, `questions[].prompt`) match the pi extension schemas (`~/.pi/agent/extensions/question.ts`, `questionnaire.ts`). ✓

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

@@ -0,0 +1,131 @@
+# 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 生命周期）。

package/docs/superpowers/specs/2026-08-22-question-tool-grouping-design.md

@@ -0,0 +1,114 @@
+# Spec: Recognize pi `question`/`questionnaire` tools as pending-question sources
+
+- **Issue**: zhuxixi/pi-agent-board#26
+- **Date**: 2026-08-22
+- **Status**: draft — awaiting user confirmation before implementation
+- **Type**: bug fix (event reducer + arg extraction), no data-model change
+
+## 1. Problem
+
+A pi session blocked on the built-in `question` (or `questionnaire`) tool shows a
+"Question" summary but stays in the **RUNNING** group instead of **NEEDS ANSWER**.
+
+Observed 2026-08-22 01:26 on view `view_e809b1a3a2` ("jfox moc密度PR审查与监控"):
+row summary "Question", `semanticState=working`, `pendingQuestions=[]`.
+
+## 2. Root cause
+
+The reducer only recognizes ONE question-tool name — `ask_questions`
+(`src/core/events.mjs` L83/L97). Pi's actual question tools are named
+`question` and `questionnaire` (user extensions:
+`~/.pi/agent/extensions/question.ts`, `questionnaire.ts`).
+
+When `tool_execution_start` arrives with `toolName: "question"`:
+1. Name check fails → `else if (pendingQuestions.length === 0)` branch runs →
+   `semanticState = "working"`, `currentTool.summary = toolSummary("question")` =
+   `capitalize("question")` = `"Question"` (heuristics.mjs default branch).
+2. `preservePendingQuestion` finds no pending question → no-op.
+3. Result: row grouped by `semanticState` = "working" → RUNNING, summary "Question".
+
+Correction to issue body: the "design gap B" claim (pending questions don't affect
+grouping) is **wrong** — `preservePendingQuestion` already sets
+`semanticState = "needs_input"` when `pendingQuestions` is non-empty. The ONLY gap is
+tool-name recognition (plus arg-shape extraction). See research/root-cause.md.
+
+## 3. Design
+
+All changes in `src/core/events.mjs` + tests. No store/schema/type changes.
+
+### 3.1 Question-tool name set
+
+```js
+const QUESTION_TOOL_NAMES = new Set(["ask_questions", "question", "questionnaire"]);
+```
+
+Replace both `name === "ask_questions"` checks (tool_execution_start L83,
+tool_execution_end L97) with `QUESTION_TOOL_NAMES.has(name)` /
+`QUESTION_TOOL_NAMES.has(event.toolName ?? "")`.
+
+Rationale: static set matches the existing hardcoded-name precedent; all three names
+are in the family of pi/agent question tools. A configurable list is deferred (4.2).
+
+### 3.2 `questionFromArgs` — support pi arg shapes
+
+Current: reads `args.questions[].question` (ask_questions shape).
+
+Extend to:
+
+| Tool | Args shape | Extract from |
+|---|---|---|
+| `ask_questions` | `{ questions: [{ question }] }` | `item.question` |
+| `question` (pi) | `{ question: string, options: [...] }` | `args.question` |
+| `questionnaire` (pi) | `{ questions: [{ prompt, options }] }` | `item.prompt`, fallback `item.question` |
+
+Priority in `questions[]` items: `item.question ?? item.prompt`. Keep the
+"Answer the pending question" fallback.
+
+### 3.3 Downstream flow (already correct — verify, don't change)
+
+- `tool_execution_start` (interactive, question tool): `upsertPendingQuestion` →
+  `preservePendingQuestion` → `semanticState = "needs_input"`, `currentTool = null`,
+  `question = first.question`. Row moves to NEEDS ANSWER group; summary shows the
+  question text (deriveSummary: needs_input + question).
+- `tool_execution_end` (interactive, question tool): `removePendingQuestion`,
+  `semanticState = "working"`, `question = null` — back to RUNNING after the answer.
+- Non-interactive (detached worker) path: `opts.interactive` gate unchanged →
+  question tools keep the old generic behavior (no pending-question tracking).
+
+### 3.4 Tests (`test/events.test.mjs`)
+
+Mirror the existing `ask_questions` coverage (L109-160):
+
+1. `tool_execution_start` with `toolName: "question"` (args `{ question: "Approve?" }`),
+   interactive → `pendingQuestions = [{ toolCallId, question: "Approve?" }]`,
+   `semanticState === "needs_input"`, `currentTool === null`, summary = question text.
+2. Same for `toolName: "questionnaire"` with args `{ questions: [{ prompt: "Pick scope" }] }`
+   → extracted question "Pick scope".
+3. `tool_execution_end` with `toolName: "question"` → pendingQuestions empty,
+   `semanticState === "working"`.
+4. Detached (no `interactive`) `question` start → unchanged legacy behavior
+   (`currentTool.name === "question"`, `pendingQuestions = []`).
+
+## 4. Non-goals / deferred
+
+1. No configurable question-tool list (env/config escape hatch). Add later only if a
+   harness with a different question-tool name appears. Keeping the set static avoids
+   new config surface.
+2. No changes to `finalizeRun`, `projectViewState`, `deriveSummary`, or grouping logic.
+3. Non-interactive path behavior unchanged.
+4. No i18n / label changes.
+
+## 5. Edge cases
+
+- Two concurrent question tool calls: keyed by `toolCallId`; first pending question wins
+  display. Unchanged from `ask_questions` behavior.
+- Non-TUI pi question tool returns an error result immediately → start/end pair clears
+  the pending question within the same cycle; transient needs_input is harmless.
+- `agent_start` / `input` events already clear `pendingQuestions` in the foreground
+  path (service.mjs L524-535) — no interaction.
+
+## 6. Verification
+
+- `npm run verify` (project gate) with the new events tests.
+- Manual: start a pi session under the board, have it call the `question` tool →
+  row shows the question text in NEEDS ANSWER group; answer it → row returns to RUNNING.

package/package.json

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

package/src/commands/agent-board.ts

@@ -88,6 +88,7 @@ export async function openDashboard(
 				};
 				const comp = new DashboardComponent(tui, theme as never, keybindings, wrappedDone, {
 					service,
+					root: service.getRoot(),
 					defaultCwd: ctx.cwd,
 					initialSelectedId: options.initialSelectedId,
 					availableModels,

package/src/core/cwd-stats.mjs

@@ -0,0 +1,112 @@
+/**
+ * Persistent cwd usage stats for the launch dialog's directory favorites.
+ *
+ * Counts every successfully dispatched session per cwd, independent of the
+ * view lifecycle (deleting a view does not decrement). The dashboard reads
+ * the ranked list for the cwd picker's favorites mode. Pure node, no Pi imports.
+ */
+import { existsSync } from "node:fs";
+import * as os from "node:os";
+import { atomicWriteJson, readJson } from "./atomic.mjs";
+import * as P from "./paths.mjs";
+import { readMeta, readRoster } from "./store.mjs";
+
+/**
+ * @typedef {Object} CwdStatsEntry
+ * @property {number} count
+ * @property {number} lastUsed  epoch ms, like meta.updatedAt
+ */
+
+/** @returns {{version: number, entries: Record<string, CwdStatsEntry>}} */
+function emptyStats() {
+	return { version: 1, entries: {} };
+}
+
+/** @param {string} root @returns {{version: number, entries: Record<string, CwdStatsEntry>}} */
+export function readCwdStats(root) {
+	const raw = readJson(P.cwdStatsPath(root), null);
+	if (!raw || typeof raw !== "object" || typeof raw.entries !== "object" || raw.entries === null) return emptyStats();
+	/** @type {Record<string, CwdStatsEntry>} */
+	const entries = {};
+	for (const [dir, entry] of Object.entries(raw.entries)) {
+		if (!entry || typeof entry.count !== "number") continue;
+		entries[dir] = {
+			count: Math.max(0, Math.floor(entry.count)),
+			lastUsed: typeof entry.lastUsed === "number" ? entry.lastUsed : 0,
+		};
+	}
+	return { version: 1, entries };
+}
+
+/**
+ * One-time seed: aggregate cwd counts from every roster view's meta.json.
+ * No-op when cwd-stats.json already exists.
+ * @param {string} root
+ */
+export function seedCwdStatsFromViews(root) {
+	if (existsSync(P.cwdStatsPath(root))) return;
+	/** @type {Record<string, CwdStatsEntry>} */
+	const entries = {};
+	for (const viewId of readRoster(root).views ?? []) {
+		const meta = readMeta(root, viewId);
+		const cwd = meta?.cwd;
+		if (!cwd) continue;
+		const lastUsed = typeof meta.updatedAt === "number" ? meta.updatedAt : Date.now();
+		const existing = entries[cwd];
+		if (existing) {
+			existing.count += 1;
+			existing.lastUsed = Math.max(existing.lastUsed, lastUsed);
+		} else {
+			entries[cwd] = { count: 1, lastUsed };
+		}
+	}
+	atomicWriteJson(P.cwdStatsPath(root), { version: 1, entries });
+}
+
+/**
+ * Seed when the stats file is missing; tolerate every failure (dashboard UX
+ * must never break because of stats bookkeeping).
+ * @param {string} root
+ */
+export function ensureCwdStatsSeeded(root) {
+	if (existsSync(P.cwdStatsPath(root))) return;
+	try {
+		seedCwdStatsFromViews(root);
+	} catch {
+		/* best effort */
+	}
+}
+
+/**
+ * Record one successful dispatch for `cwd`. Invalid dirs are ignored.
+ * @param {string} root @param {string} cwd
+ */
+export function recordCwdLaunch(root, cwd) {
+	if (!cwd || !existsSync(cwd)) return;
+	const stats = readCwdStats(root);
+	const existing = stats.entries[cwd] ?? { count: 0, lastUsed: 0 };
+	stats.entries[cwd] = { count: existing.count + 1, lastUsed: Date.now() };
+	atomicWriteJson(P.cwdStatsPath(root), stats);
+}
+
+/**
+ * Ranked candidates: count desc, then lastUsed desc; home appended at the
+ * end when absent so the user's home dir is always one keystroke away.
+ * @param {string} root @param {number=} limit
+ * @returns {Array<{path: string, count: number}>}
+ */
+export function rankedCwdCandidates(root, limit = 8) {
+	const stats = readCwdStats(root);
+	const rows = Object.entries(stats.entries).map(([dir, entry]) => ({
+		path: dir,
+		count: entry.count,
+		lastUsed: entry.lastUsed,
+	}));
+	rows.sort((a, b) => b.count - a.count || b.lastUsed - a.lastUsed);
+	const out = rows.slice(0, Math.max(1, limit)).map(({ path, count }) => ({ path, count }));
+	const home = os.homedir();
+	if (out.some((entry) => entry.path === home)) return out;
+	const homeRow = rows.find((entry) => entry.path === home);
+	out.push(homeRow ? { path: home, count: homeRow.count } : { path: home, count: 0 });
+	return out;
+}

package/src/core/events.mjs

@@ -17,6 +17,9 @@ import { assistantText, detectNeedsInput, toolPath, toolSummary, truncate } from
 
 const PREVIEW_MAX = 240;
 
+/** Tool names whose interactive execution blocks on a user answer. */
+const QUESTION_TOOL_NAMES = new Set(["ask_questions", "question", "questionnaire"]);
+
 /**
  * Build the initial status for a freshly-launched run.
  * @param {RunConfig} config
@@ -80,7 +83,7 @@ export function reduceEvent(status, event, now, opts = {}) {
 			const name = event.toolName ?? event.args?.name ?? "tool";
 			const args = event.args ?? {};
 			status.toolCount += 1;
-			if (opts.interactive && name === "ask_questions") {
+			if (opts.interactive && QUESTION_TOOL_NAMES.has(name)) {
 				upsertPendingQuestion(status, event.toolCallId, questionFromArgs(args));
 			} else if (pendingQuestions(status).length === 0) {
 				status.currentTool = { name, path: toolPath(args), summary: toolSummary(name, args) };
@@ -94,7 +97,7 @@ export function reduceEvent(status, event, now, opts = {}) {
 		}
 		case "tool_execution_end": {
 			if (event.isError) status.error = `Tool ${event.toolName ?? ""} failed`.trim();
-			if (opts.interactive && event.toolName === "ask_questions") removePendingQuestion(status, event.toolCallId);
+			if (opts.interactive && QUESTION_TOOL_NAMES.has(event.toolName ?? "")) removePendingQuestion(status, event.toolCallId);
 			status.currentTool = null;
 			status.semanticState = "working";
 			status.question = null;
@@ -227,8 +230,9 @@ function pendingQuestions(status) {
 }
 
 function questionFromArgs(args) {
+	if (typeof args?.question === "string" && args.question.trim()) return args.question.trim();
 	for (const item of Array.isArray(args?.questions) ? args.questions : []) {
-		const question = String(item?.question ?? "").trim();
+		const question = String(item?.question ?? item?.prompt ?? "").trim();
 		if (question) return question;
 	}
 	return "Answer the pending question";

package/src/core/launch-options.mjs

@@ -315,3 +315,50 @@ function existsDir(dir) {
 		return false;
 	}
 }
+
+/**
+ * Keep only candidates whose path is an existing directory.
+ * @param {CwdCandidate[]} candidates
+ * @returns {CwdCandidate[]}
+ */
+export function existingCwdCandidates(candidates) {
+	return candidates.filter((entry) => existsDir(entry.path));
+}
+
+/**
+ * @typedef {Object} CwdCandidate
+ * @property {string} path
+ * @property {number} count
+ */
+
+/**
+ * Filter ranked cwd candidates by case-insensitive substring match anywhere
+ * in the path (empty query keeps the full ranked list).
+ * @param {CwdCandidate[]} candidates
+ * @param {string} query
+ * @returns {CwdCandidate[]}
+ */
+export function filterCwdCandidates(candidates, query) {
+	const q = String(query ?? "").trim().toLowerCase();
+	if (!q) return candidates;
+	return candidates.filter((entry) => entry.path.toLowerCase().includes(q));
+}
+
+/**
+ * Decide cwd picker mode + suggestions for a query: favorites when the query
+ * is empty or matches ranked candidates, filesystem browse otherwise.
+ * @param {string} query
+ * @param {CwdCandidate[]} ranked
+ * @param {string} baseCwd
+ * @returns {{mode: "favorites"|"browse", suggestions: string[]}}
+ */
+export function nextCwdPickerState(query, ranked, baseCwd) {
+	if (!ranked || ranked.length === 0) {
+		return { mode: "browse", suggestions: listDirectorySuggestions(query, baseCwd) };
+	}
+	const matches = filterCwdCandidates(ranked, query);
+	if (String(query ?? "").trim() === "" || matches.length > 0) {
+		return { mode: "favorites", suggestions: matches.map((entry) => entry.path) };
+	}
+	return { mode: "browse", suggestions: listDirectorySuggestions(query, baseCwd) };
+}