@huseynsnmz/pi-board 0.15.3 → 0.16.0

package/docs/superpowers/specs/2026-10-20-issue-221-ask-user-question-design.md

@@ -1,270 +0,0 @@
-# Root-cause report / Spec: recognize `ask_user_question` as a pending-question tool
-
-Drafted: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-20T22:10:00+08:00
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-20T22:24:00+08:00 — folded in R1-D1..D5
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-21T22:10:00+08:00 — emitter identified and installed locally; U1 deployment path corrected from npm release to the git-install clone
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-21T22:22:00+08:00 — R2-D1 reference precision (blocked-event emit site)
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-21T22:15:00+08:00 — user chose the hybrid guard (name OR questionnaire arg shape); design, acceptance matrix, risks and testability split updated
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-21T22:35:00+08:00 — R3-D1..D3 (deliverables list, superseded decision row, no-id fallback boundary)
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-21T22:52:00+08:00 — local-CR: shape bound wording matches the implementation (empty question string still matches)
-
-- **Issue**: zhuxixi/pi-agent-board#221
-- **Date**: 2026-10-20
-- **Status**: draft — awaiting cross-review and user confirmation
-- **Type**: bug fix (event-reducer allow-list + regression test); no data-model, schema, or UI change
-
-## 1. Problem
-
-A pi-style session blocked on a tool named `ask_user_question` stays in the **RUNNING**
-group with the row summary `Ask_user_question`. It never reaches the **Needs answer**
-group (`needs_input`, amber).
-
-Reproduced at reducer level on `main` (9a197f4):
-
-```
-actual  ask_user_question → semanticState=working, summary="Ask_user_question",
-                            pendingQuestions=[], question=null,
-                            currentTool={name:"ask_user_question"}, needsInput=false
-control question          → semanticState=needs_input, summary="Which approach?", needsInput=true
-```
-
-Evidence trail: `issue-221/research/root-cause.md`, issue comment 6292835562.
-
-## 2. Root cause
-
-`src/core/events.mjs:21` defines an exact-membership allow-list:
-
-```js
-const QUESTION_TOOL_NAMES = new Set(["ask_questions", "question", "questionnaire"]);
-```
-
-Both gates are exact membership — `events.mjs:86` (`tool_execution_start`) and
-`events.mjs:100` (`tool_execution_end`). `ask_user_question` misses both, so
-`tool_execution_start` takes the generic branch (`currentTool` set, `semanticState =
-"working"`), `preservePendingQuestion()` has nothing to promote, and `deriveSummary()`
-falls back to `capitalize(name)`.
-
-`questionFromArgs()` (`events.mjs:232`) already handles the arg shape
-(`args.questions[].question`) — no extraction change is needed.
-
-**Emitter (confirmed 2026-10-21)**: `ask_user_question` is registered by the pi extension
-`@juicesharp/rpiv-ask-user-question` — `ask-user-question.ts:84`
-(`ASK_USER_QUESTION_TOOL_NAME = "ask_user_question"`), registered at `:455-459`. It is not a
-pi 1.3.0 built-in (pi ships no question tool; `question`/`questionnaire` come from
-`pi-question-tool`). The extension is now installed on this machine: v2.13.9,
-`~/.pi/agent/settings.json:90`, `~/.pi/agent/npm/node_modules/@juicesharp/rpiv-ask-user-question`,
-and the tool is live in the session after `/reload` (session tool list contains
-`question`, `questionnaire`, `ask_user_question`). Its arg schema
-(`{ questions: [{ question, header, options, multiSelect }] }`) is exactly what
-`questionFromArgs` already reads.
-
-The defect stands regardless of the emitter: any unrecognized question-tool name silently
-degrades grouping.
-
-## 3. Design
-
-### 3.1 Detection: name allow-list OR questionnaire arg shape
-
-```js
-/** Tool names whose interactive execution blocks on a user answer. */
-const QUESTION_TOOL_NAMES = new Set(["ask_questions", "question", "questionnaire", "ask_user_question"]);
-
-/** Questionnaire args shared by pi/Claude-Code style question tools. */
-function isQuestionArgShape(args) {
-	const questions = Array.isArray(args?.questions) ? args.questions : null;
-	return Boolean(questions && questions.length > 0 && typeof questions[0]?.question === "string");
-}
-
-function isQuestionToolCall(name, args) {
-	return QUESTION_TOOL_NAMES.has(name) || isQuestionArgShape(args);
-}
-```
-
-Why both: the name set keeps the known tools working even with empty args
-(`ask_questions` is exercised with `args: {}` at `test/events.test.mjs:137`), while the shape
-check survives a renamed or newly packaged question tool as long as it keeps the
-`questions[0].question` schema. Neither replaces the other.
-
-**End gate becomes name-agnostic**: `tool_execution_end` carries no `args`, so a
-shape-matched start cannot be recognized at end time. Replace
-`opts.interactive && QUESTION_TOOL_NAMES.has(event.toolName ?? "")` with
-`opts.interactive` and let `removePendingQuestion(status, event.toolCallId)` filter by call
-id (it is already a no-op when the id is not pending). Tool-call ids are unique per call, so
-this cannot clear someone else's question.
-
-The guarantee is exact for real worker events, which always carry `toolCallId`
-(`pi` dist `agent-session` emits `{toolCallId,toolName,result,isError}`). The pre-existing
-no-id fallback (`events.mjs:242/250` map a missing id to the literal `"ask_questions"`) is
-unchanged; a malformed event without an id could therefore clear a pending entry that also
-lacked one. That path is unreachable from the real event stream and is left as-is.
-
-No other module reads question-tool names (`rg ask_questions src/` → only `events.mjs`).
-
-### 3.2 Regression guard
-
-Two new reducer tests in `test/events.test.mjs`, next to the existing
-`interactive pi question tool …` test:
-
-**Test A — name path (`ask_user_question`), pinned to the literal name**
-
-- interactive start → `needs_input`, summary/question = first question text,
-  `pendingQuestions` length 1, `currentTool === null`, `projectViewState().needsInput === true`;
-- interactive end for the same `toolCallId` → `working`, `question === null`,
-  `pendingQuestions === []`;
-- detached reduction (no `interactive`) → `working`, `currentTool.name === "ask_user_question"`,
-  `pendingQuestions === []`.
-
-**Test B — shape path (unknown name), plus the negative guard**
-
-- interactive start with `toolName: "mystery_questionnaire"` and
-  `args: { questions: [{ question: "Ship it?", header: "Release", options: [{ label: "Yes" }] }] }`
-  → `needs_input`, question `"Ship it?"`, one pending entry;
-- interactive end with the **same unknown name** → `working`, cleared (proves the end gate is
-  call-id based, not name based);
-- negative cases that must stay `working` with an empty `pendingQuestions`:
-  `{ questions: [] }`, `{ questions: "nope" }`, and a non-question tool (`bash`).
-
-The literal name in Test A plus the unknown-name case in Test B are the guards: dropping the
-name or the shape check fails `npm test` instead of silently regressing the dashboard.
-
-### 3.3 Alternatives considered
-
-| Alternative | Verdict | Reason |
-|---|---|---|
-| Arg-shape detection instead of a name set | Rejected | `ask_questions` is exercised with `args: {}` (`test/events.test.mjs:135`) and must still be `needs_input`; shape alone cannot cover it. |
-| Hybrid (`set OR questions[] shape`) at drafting | Rejected, then superseded | Drafting-time verdict was to keep the diff minimal; the user gate on 2026-10-21 chose the hybrid, so this row is history only — the authoritative decision is the Adopted row below. |
-| Configurable allow-list | Rejected | No config surface exists for reducer behavior; over-engineering for a one-name gap. |
-| Export the set for tests | Rejected | The reducer is the public surface; tests already drive it directly. Exporting a private constant adds API for no gain. |
-| Upstream `rpiv:ask-user:blocked` event instead of name detection | Rejected | Constant defined at `events.ts:38`, emitted at `ask-user-question.ts:64` (`pi.events.emit`) — an in-process bus event on the extension host. The board consumes JSON-mode worker stdout, which never carries pi bus events, so the channel is unreachable. |
-| Name set OR arg-shape fallback | **Adopted** (user decision, 2026-10-21) | Survives a rename or a newly packaged question tool as long as the schema stays `questions[0].question`. Cost: any interactive tool with that exact shape is treated as a pending question; bounded by requiring a non-empty `questions[0].question` string and by the `opts.interactive` gate. |
-
-### 3.4 Data flow (unchanged, verified)
-
-| Step | Location | Result |
-|---|---|---|
-| interactive start, name in set OR questionnaire shape | `events.mjs:86` → `upsertPendingQuestion` → `preservePendingQuestion` | `needs_input`, `currentTool=null`, `question` = first question |
-| summary | `derive.mjs:103` | question text wins over tool name |
-| projection | `events.mjs:209` | `needsInput: true` |
-| interactive end | `events.mjs:100` → `removePendingQuestion` (by call id) | back to `working`, `question=null` |
-| inline reply while pending | `src/ui/dashboard.ts:2054 isAgentBusy` + `README.md:167/299` | reply rejected; answer via attach (pre-existing contract, now also applies to this name) |
-| detached start/end | `opts.interactive` gate | unchanged `currentTool` behavior |
-
-## 4. Acceptance matrix
-
-| ID | Feature point | Verification | Concrete check | Pass criteria |
-|----|---------------|--------------|----------------|---------------|
-| A1 | `ask_user_question` start is treated as a pending question | automated (unit) | `npm test` — new test in `test/events.test.mjs` | `semanticState==="needs_input"`, `summary`/`question` equal `"Which approach?"`, `pendingQuestions.length===1`, `currentTool===null`, `projectViewState(s).needsInput===true` |
-| A2 | `ask_user_question` end clears the pending question | automated (unit) | same test | `semanticState==="working"`, `question===null`, `pendingQuestions` empty |
-| A3 | Detached reduction keeps legacy behavior | automated (unit) | same test (no `interactive` opt) | `semanticState==="working"`, `currentTool.name==="ask_user_question"`, `pendingQuestions` empty |
-| A4 | No regression for the existing three names | automated (unit) | `npm test` (existing tests at `test/events.test.mjs:109/135/163/206/220`) | all pass unchanged |
-| A5 | Shape fallback: unknown tool name with questionnaire args becomes a pending question | automated (unit) | Test B in `test/events.test.mjs` | `semanticState==="needs_input"`, question `"Ship it?"`, `pendingQuestions.length===1`, `currentTool===null` |
-| A6 | End gate clears shape-matched calls without a name match | automated (unit) | Test B — `tool_execution_end` with the same unknown `toolName`/`toolCallId` | `semanticState==="working"`, `question===null`, `pendingQuestions` empty |
-| A7 | Misleading args do not trigger the shape fallback | automated (unit) | Test B negative cases: `{questions: []}`, `{questions: "nope"}`, and `bash` | `semanticState==="working"`, `pendingQuestions` empty in all three |
-| A8 | Repo-level static gate stays green | automated (static) | `npm run typecheck` | exit 0. Note: `tsconfig.json:9` sets `checkJs:false`, so this gate covers the `.ts` surface and is a repo regression check, not proof of this `.mjs` change; A1–A7 are the real proof |
-| U1 | A real board session blocked on `ask_user_question` renders under Needs answer | user test | see §5 | row under **Needs answer** with the question text as summary; end of call returns it to RUNNING |
-
-Full gate: `npm run verify` (typecheck + perf gate + tests + coverage thresholds + pack dry-run).
-
-Failure branches: A2/A6 assert clear-on-end, A3 asserts detached stays generic, A7 asserts the
-false-positive guard. No error path is added by this change, so no error-path item is owed.
-
-## 5. User test (U1) — steps and timing
-
-Now executable on this machine: the emitter is installed (`@juicesharp/rpiv-ask-user-question`
-2.13.9) and the tool is live after `/reload`. The remaining precondition is the **board code**
-itself — the board process loads from the git-install clone, not from this working checkout and
-not from npm:
-
-- `pi list` → `git:github.com/zhuxixi/pi-agent-board` at
-  `~/.pi/agent/git/github.com/zhuxixi/pi-agent-board` (`~/.pi/agent/settings.json:85`), HEAD
-  `9a197f4` (= `main` at drafting time). That clone currently has a dirty `package-lock.json`
-  (4 deleted `"peer": true` lines), which must be discarded before pulling.
-
-Timing: after the fix merges to `main`.
-
-1. Update the clone the board actually loads, then restart the board/Pi:
-   `cd ~/.pi/agent/git/github.com/zhuxixi/pi-agent-board && git checkout -- package-lock.json && git pull`
-   (or re-run `pi install git:github.com/zhuxixi/pi-agent-board`); confirm
-   `git log -1 --oneline` is the merged commit.
-2. Restart Pi / the board service (an already-running pi process keeps the old extension code).
-3. Dispatch a board session whose prompt forces a decision, so the model calls
-   `ask_user_question` with `questions[0].question` containing a short decision question
-   (e.g. "Which approach?"). The extension is user-level, so every session sees the tool.
-4. Open the dashboard, then answer via attach.
-
-Expected observation: the row sits under **Needs answer** (amber) with the question text as
-its summary, `pendingQuestions` holds one entry, inline reply is refused (pre-existing
-contract); after answering, the row returns to **RUNNING**.
-
-If the merge has not happened by completion time, U1 is reported as `pending` (not passed);
-A1–A5 still prove the reducer contract.
-
-## 6. Non-goals
-
-- No change to `detectNeedsInput()` text heuristics or `message_end` classification.
-- The shape fallback does **not** apply to detached (non-interactive) runs: headless sessions
-  cannot answer, so they keep `currentTool` display.
-- No rename of the `"ask_questions"` fallback ids in `upsertPendingQuestion` /
-  `removePendingQuestion` (`events.mjs:242/250`).
-- No config surface or UI affordance for arbitrary question-tool names.
-- No change to attach/reply/answer transport; only reducer classification changes.
-
-## 7. Risks and boundaries
-
-- **False positive (accepted)**: any interactive tool whose args are
-  `{ questions: [{ question: <string> }] }` is treated as a pending question, even if it is
-  not asking the user. Bounded by the `opts.interactive` gate and by requiring the first
-  `question` to be a string; an empty or whitespace-only string still matches and falls back
-  to the generic "Answer the pending question" text, exactly like the name-set path. No
-  installed extension is known to declare that shape for a non-question purpose today
-  (research §4), but absence over third-party code is not provable, so the guard is the bound
-  itself, not a completeness claim.
-- **End gate is now name-agnostic**: every interactive `tool_execution_end` calls
-  `removePendingQuestion(id)`. For real worker events (which always carry `toolCallId`) ids are
-  unique per call, so this clears the matching entry or does nothing; it cannot clear another
-  call's question (covered by A6 and by the existing multi-question test at
-  `test/events.test.mjs:135`). The legacy no-id fallback is unchanged and is documented in §3.1
-  as the only way a cross-clear could occur.
-- **Shape fallback is a heuristic**: a tool that renames its `questions` payload field
-  (e.g. to `prompts`) still regresses. Accepted; a schema change is a protocol change, not a
-  rename, and cannot be absorbed by a reducer heuristic.
-- **Detached runs** are unaffected — headless sessions cannot answer, so they must keep
-  `currentTool` display.
-- **Only JSON-mode worker events reach the reducer.** The extension's own
-  `rpiv:ask-user:blocked` bus event is in-process and never appears in worker stdout, so the
-  board cannot rely on it.
-- **Inline reply is rejected while the question is pending** (`README.md:167/299`,
-  `src/ui/dashboard.ts:2054 isAgentBusy`). This is pre-existing behavior for pending
-  questions and now applies to `ask_user_question` rows too; answer via attach. Expected,
-  not a regression.
-
-## 8. Testability split
-
-The reducer is already a pure-function seam: `createRunStatus(config, pid, now)` builds
-state, `reduceEvent(status, event, now, opts)` mutates it, `projectViewState(status, now)`
-projects it. Two new module-private pure helpers carry the new logic —
-`isQuestionArgShape(args)` and `isQuestionToolCall(name, args)` — and are driven through
-`reduceEvent`, the public surface, exactly like the existing `questionFromArgs` (which is
-also private and tested through the reducer).
-
-Planned split:
-
-| Unit | Purity | Test seam |
-|---|---|---|
-| `isQuestionArgShape(args)` | pure, no I/O | via `reduceEvent` start events (Test B positives/negatives) |
-| `isQuestionToolCall(name, args)` | pure, no I/O | via `reduceEvent`; name path in Test A, shape path in Test B |
-| start handler branch | side-effect-free over `RunStatus` | `reduceEvent` + `projectViewState` assertions |
-| end handler (call-id removal) | side-effect-free over `RunStatus` | `reduceEvent` end events (Test A, Test B, existing multi-question test) |
-
-Test boundary: `test/events.test.mjs` only. No export is added to `src/core/events.mjs`;
-the helpers stay private and are covered through the reducer, matching the existing pattern.
-
-## 9. Deliverables
-
-- `src/core/events.mjs` — add `ask_user_question` to `QUESTION_TOOL_NAMES`; add the private
-  `isQuestionArgShape(args)` / `isQuestionToolCall(name, args)` helpers; gate
-  `tool_execution_start` on `isQuestionToolCall`; make `tool_execution_end` clear by
-  `toolCallId` under `opts.interactive` only.
-- `test/events.test.mjs` — Test A (name path) and Test B (shape path + negative guards).
-- `docs/superpowers/specs/2026-10-20-issue-221-ask-user-question-design.md` — this design,
-  committed with the fix (repo precedent: #213/#214/#215 each ship their spec with the PR).

package/docs/superpowers/specs/2026-10-22-issue-225-monotonic-foreground-state-design.md

@@ -1,225 +0,0 @@
-# Root-cause report / Spec: monotonic foreground state rebuild (stale "Needs answer")
-
-Drafted: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-22T23:50:00+08:00
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-23T00:05:00+08:00 — folded in R1-G1..G3 and R1-D1..D4
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-23T00:20:00+08:00 — R2-D1..D3 (A4 clock pin, timestamp-bound wording, forget wiring acceptance)
-
-- **Issue**: zhuxixi/pi-agent-board#225
-- **Date**: 2026-10-22
-- **Status**: draft — awaiting cross-review and user confirmation
-- **Type**: bug fix (foreground state mirroring); no reducer, schema, or UI change
-
-## 1. Problem
-
-A foreground row that transiently becomes `needs_input` can stay in **Needs answer** for
-the rest of the turn after the question is answered. Live evidence (issue #225):
-
-```
-22:56:21  needs_input  pending=[call_.../1]
-22:56:44  working      pending=[]          ← tool_execution_end cleared it
-22:56:44  needs_input  pending=[call_.../1] ← stale projection re-applied
-22:57:04  idle         pending=[]          ← agent_end finally rewrote it
-```
-
-The reducer is correct (#221); the resurrection happens in the foreground mirror.
-
-## 2. Root cause
-
-1. `syncRowEvent` (`src/runtime/service.mjs:1533`) rebuilds status from disk on every
-   event: `statusFromRow(row)` (`:1535`).
-2. `statusFromRow` (`:814-843`) copies `semanticState` / `summary` / `question` /
-   `pendingQuestions` but **not `updatedAt`**, so the rebuild has no freshness signal.
-3. `writeForegroundState` (`:854-880`) stamps a new `updatedAt` through
-   `projectViewState(status, Date.now(), …)`, and every caller fires it as
-   `void writeForegroundState(...)` (`:1571`, `:1629`). Two events can therefore have two
-   `sync_foreground` commands in flight, and the older projection can materialize last.
-4. The next event reduces onto that stale status (it cannot tell it is stale) and writes it
-   back; the pending entry survives until `agent_end` finalizes the row.
-5. `foregroundPreviewCache` (#113) restores only `latestAssistantPreview` and
-   `lastAgentActivityAt`, keyed on `lastAgentActivityAt` — tool events never stamp that
-   field, so question state is uncovered.
-
-Additional constraint: `mark_completed` / `mark_holding` / `patch_fields`
-(`src/core/state-commands.mjs`) do **not** stamp `state.updatedAt`, so a timestamp-only
-guard could resurrect a pre-verdict projection over a manual verdict. The manual-verdict
-fence (`isManualVerdict`) must gate the adoption.
-
-## 3. Design
-
-### 3.1 New pure module: `src/core/foreground-projection-cache.mjs`
-
-Module-level shared instance, same rationale as `foreground-preview-cache` (service
-instances are created per call, so a per-instance cache is discarded between events).
-
-The cache stores a **status-shaped snapshot**, not the `ViewState` projection: the
-projection calls the active tool `latestTool`, while `RunStatus` calls it `currentTool` with
-a `summary` (`src/core/events.mjs:225`, `src/runtime/service.mjs:826`). Storing the status
-keeps the whitelist aligned with `RunStatus` and avoids an implicit shape mapping.
-
-```js
-createForegroundProjectionCache(): {
-  nextStamp(viewId): number              // strictly increasing per view
-  remember(viewId, status, stamp): void  // snapshot the whitelisted fields
-  adopt(viewId, status): boolean         // copy the snapshot when strictly newer
-  forget(viewId): boolean
-  clear(): void
-  size(): number
-}
-```
-
-- `nextStamp(viewId)` returns `max(Date.now(), lastStamp(viewId) + 1)`. Using it for
-  `projectViewState`'s `now` argument makes every foreground `updatedAt` strictly increasing
-  per view, so two events in the same millisecond can never tie and an older projection can
-  never outrank a newer one inside this process.
-- `remember` snapshots this whitelist from the status:
-  `semanticState`, `processState`, `summary`, `currentTool`, `question`,
-  `pendingQuestions`, `error`, `lastActivityAt`, `latestAssistantPreview`,
-  `lastAgentActivityAt`, plus the `stamp`. Nested values (`currentTool`,
-  `pendingQuestions`) are cloned **on remember**, so a later mutation of the caller's status
-  cannot leak into the cache.
-- `adopt(viewId, status)` compares `entry.stamp` with `status.updatedAt ?? 0`. Only a
-  strictly newer entry is adopted; it copies the same whitelist (cloning nested values
-  again, so `adopt` → caller mutation → second `adopt` is stable) and sets
-  `status.updatedAt = entry.stamp`. Returns whether anything changed.
-- Nothing else (evidence `review`, `diagnostics`, `autoState`, `lastVisitedAt`, `steering`,
-  `followUps`) is touched — those have their own writers and freshness rules.
-
-### 3.2 Wiring in `src/runtime/service.mjs`
-
-| Point | Change |
-|---|---|
-| `statusFromRow` (`:814`) | add `updatedAt: typeof s.updatedAt === "number" ? s.updatedAt : 0` (in-memory freshness only; `RunStatus` gains an optional `updatedAt` typedef in `src/core/types.mjs`) |
-| `writeForegroundState` (`:854`) | `const stamp = foregroundProjectionCache.nextStamp(row.meta.id)`; pass `stamp` instead of `Date.now()` to `projectViewState`; then `foregroundProjectionCache.remember(row.meta.id, status, stamp)` |
-| `syncRowEvent` (`:1540`) | after the preview backfill: `foregroundProjectionCache.adopt(row.meta.id, status)` before `reduceEvent` |
-| cache eviction (`:775`, `:2131`) | call `foregroundProjectionCache.forget(viewId)` next to the existing `foregroundPreviewCache.forget(viewId)` |
-
-`row` is loaded from disk at the event entry (`rowForSession` → `loadRow`), before any
-`await`, so `row.state` is as fresh as `readState(root, viewId)` at that point.
-
-The preview cache stays as-is: its #113 semantics (gap-fill when the timestamp ties) are
-still useful, and folding it into the new cache is a separate refactor (non-goal).
-
-### 3.3 Why not serialize the writes (issue option 2)
-
-A module-level write queue would fix the ordering at the source, but it adds a new failure
-mode (one stalled coordinator round trip blocks every later event) and needs its own
-backoff/timeout policy. The monotonic rebuild fixes the *read* side, so it also covers
-future writers (dashboard patches, reconcile) and any out-of-order arrival that is not a
-`sync_foreground` command. Option 2 remains a possible follow-up, not this fix.
-
-### 3.4 Manual verdicts (boundary, no new fence)
-
-Adoption is a pure comparison: adopt only when `entry.stamp > status.updatedAt`. Because
-`nextStamp` can run ahead of the wall clock during a sub-millisecond burst, a writer that
-stamps with a bare `Date.now()` *can* compare older than the cache — the timestamp does not
-order against every writer.
-
-Manual verdicts do not rely on that comparison. Under the coordinator, `mark_completed` /
-`mark_holding` writes are materialized without stamping `updatedAt`
-(`state-commands.mjs:288-334`), and any later `sync_foreground` from `service` is rejected
-with `manual_fence` (`state-commands.mjs:282-285`). In coordinator-disabled mode the direct
-writers (`completeViewDirect`, `holdViewDirect`, `archiveStateDirect`, reconcile) *do* stamp
-`Date.now()`, but that path already lets a foreground event overwrite the semantic state
-through `reduceEvent` today, independent of this cache, so adoption adds no new way to
-resurrect a verdict. No extra fence is added; the existing `manual_fence` and the
-`agent_end` branch fence remain the protections, and A5 pins the observable behavior.
-
-### 3.5 Data flow after the change
-
-| Event | Behavior |
-|---|---|
-| start question | `reduceEvent` → `needs_input`; write uses stamp S1 and remembers it |
-| end question | rebuild from disk (maybe stale) → adopt if cache is newer → `reduceEvent` clears pending → write uses S2 > S1 |
-| subsequent tool event | rebuild carries S2 → adopt is a no-op (equal) → `reduceEvent` keeps `working`; never resurrects `needs_input` |
-| dashboard write | disk `updatedAt` is newer than the cache → nothing adopted |
-| agent_end | finalize as today |
-
-## 4. Acceptance matrix
-
-| ID | Feature point | Verification | Concrete check | Pass criteria |
-|----|---------------|--------------|----------------|---------------|
-| A1 | `remember`/`adopt` respect strict freshness | automated (unit) | `test/foreground-projection-cache.test.mjs` | newer stamp adopted (`true`); equal and older stamps not adopted (`false`), status unchanged |
-| A2 | Whitelist copy is exact and isolated | automated (unit) | same file | all whitelisted fields copied; non-whitelisted untouched; mutating `status.pendingQuestions[0]` after `adopt` does not change a second `adopt`; mutating the status after `remember` does not change the stored snapshot |
-| A3 | `nextStamp` is strictly increasing per view | automated (unit) | same file | two calls in a row return `b > a`, even when `Date.now()` is stubbed to a constant; different view ids do not share the counter |
-| A4 | Out-of-order materialization no longer resurrects `needs_input` | automated (integration) | `test/service.test.mjs`, coordinator disabled, `Date.now` pinned to a constant for the whole test so the pre-fix same-millisecond tie is deterministic: question start → capture `state.json` (its `updatedAt` is the start stamp) → question end → `writeState(captured snapshot)` (an older stamp) → `tool_execution_start` for `bash` | persisted state is `working`, `pendingQuestions` empty, `needsInput` false. Pre-fix this asserts `needs_input` (the disk rebuild wins the tie), post-fix the monotonic stamp adopts the newer cached status |
-| A5 | A manual verdict survives a foreground event | automated (integration) | `test/service.test.mjs`: seed the projection cache with an accepted-but-unmaterialized beat, write `completed` + `autoState: null` with an older `updatedAt`, then a `tool_execution_start` that adopts the cached snapshot | persisted state stays `completed` (coordinator answers `manual_fence`). Pins the fence, not adoption isolation — adoption has no independent observable there |
-| A6 | `forget` drops the entry and is wired into archive | automated (unit + integration) | cache test: `remember` → `forget` → `adopt` false; `test/service.test.mjs`: `archiveByState` on a remembered view | `adopt` returns `false` after `forget`; after archiving, `foregroundProjectionCache.size()` no longer counts that view |
-| A7 | Existing foreground behavior unchanged | automated (unit/integration) | `npm test` (existing `syncForegroundEvent` and preview-cache tests) | all pass |
-| A8 | Repo static gate | automated (static) | `npm run typecheck` | exit 0 (`checkJs:false`, so this is a repo regression gate, not proof of the `.mjs` change) |
-| U1 | Live: answering a question returns the row to RUNNING before the turn ends | user test | see §5 | row leaves **Needs answer** within ~1s of the answer and stays RUNNING until the turn ends |
-
-Full gate: `npm run verify` (typecheck + perf + tests + coverage thresholds + pack dry-run).
-
-Failure branches: A1/A2 assert the negative side (equal/older stamps are not adopted, nested
-values cannot leak), A5 asserts the manual-verdict boundary, A6 asserts cache eviction. No
-new error path is introduced.
-
-## 5. User test (U1)
-
-Executable after merge, on this machine (the board clone at
-`~/.pi/agent/git/github.com/zhuxixi/pi-agent-board` is updated to the merged commit and Pi
-restarted):
-
-1. In a session, trigger a question (`ask_user_question` or `question`).
-2. Watch the row enter **Needs answer**; answer it in the dashboard/attach.
-3. Keep watching for the rest of the turn.
-
-Expected: the row returns to **RUNNING** within about a second of the answer — not at
-`agent_end`. Repeat with a nested call (question asked from inside `codemode`) to exercise
-the wider window.
-
-If the environment cannot be updated at completion time, U1 is reported as `pending`.
-
-## 6. Non-goals
-
-- No change to `reduceEvent`, `deriveSummary`, or the question-tool detection (#221 is done).
-- No serialization of `sync_foreground` writes (issue option 2) and no coordinator changes.
-- No removal or rewrite of `foreground-preview-cache.mjs` (#113 behavior preserved).
-- No changes to manual verdicts, auto-state classification, or evidence/diagnostics writes.
-
-## 7. Risks and boundaries
-
-- **Clock ties**: prevented inside this process by `nextStamp` (strictly increasing per
-  view). Ties are still possible with a *different* writer (another Pi process) whose
-  `Date.now()` equals ours; then neither side is "strictly newer" and the disk value wins,
-  which is the pre-existing behavior. Cross-process ordering is not guaranteed.
-- **Cross-process writers**: another Pi process mirroring the same view writes its own
-  `updatedAt`; this cache only protects against out-of-order writes from *this* process.
-  Outside the supported single-host model; documented, not fixed.
-- **In-process writers with a bare `Date.now()`**: the auto-state classifier
-  (`applyAutoStateToViewState`, `src/core/auto-state.mjs:254`) stamps a wall-clock
-  `updatedAt`, which can compare older than a cache stamp that ran ahead within the same
-  millisecond. A late foreground tool event would then adopt the pre-classification
-  snapshot — but such an event already clobbers the classification through `reduceEvent`
-  today (it sets `working` and `alive`), so this is not a new resurrection path.
-- **Manual verdicts**: protected by the coordinator's `manual_fence` and the `agent_end`
-  branch fence, not by timestamps. Coordinator materialization does not stamp `updatedAt`
-  for verdict writes; coordinator-disabled direct writers do stamp `Date.now()`, which can
-  compare older than a cache stamp that ran ahead of the clock — that path is not ordered by
-  this cache (see §3.4, A5).
-- **Memory**: one small object per view, evicted with the existing `forget` sites.
-
-## 8. Testability split
-
-| Unit | Purity | Test seam |
-|---|---|---|
-| `createForegroundProjectionCache()` (`nextStamp` / `remember` / `adopt` / `forget`) | pure (Map in/out, tested with a stubbed clock) | direct unit tests (`test/foreground-projection-cache.test.mjs`) |
-| `statusFromRow` `updatedAt` passthrough | pure | exercised through `syncForegroundEvent` (A4) |
-| adoption in `syncRowEvent` | side-effect-free call + thin I/O shell | `syncForegroundEvent` with coordinator disabled (A4), deterministic `writeState` between events; A5 uses the tracked coordinator |
-| stamp assignment in `writeForegroundState` | pure call inside the existing shell | A4 (the repro fails without monotonic stamps: the stale snapshot would tie) |
-| write-side `remember` | pure call inside the existing shell | A4 (the repro fails without it) |
-
-Test boundary: new pure module tests + additions to `test/service.test.mjs`; no new exports
-from the service.
-
-## 9. Deliverables
-
-- `src/core/foreground-projection-cache.mjs` — new pure module.
-- `src/runtime/service.mjs` — `statusFromRow` `updatedAt`; `nextStamp` + `remember` in
-  `writeForegroundState`; `adopt` in `syncRowEvent`; `forget` at the eviction sites.
-- `src/core/types.mjs` — optional `updatedAt` on the `RunStatus` typedef (in-memory
-  freshness field).
-- `test/foreground-projection-cache.test.mjs` — new unit tests (A1–A3, A6).
-- `test/service.test.mjs` — A4/A5 integration tests.
-- `docs/superpowers/specs/2026-10-22-issue-225-monotonic-foreground-state-design.md` — this
-  design, committed with the fix.