@zhuxixi/pi-agent-board 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@ conventional commits by `scripts/release_helper.mjs`. Entries are
 forward-only: they begin with the first release after this file landed —
 for earlier history, see the git log and the pull-request list.
 
+## [0.10.0] - 2026-10-01
+
+### Features
+
+- **ui**: x then y confirms session deletion (issue #150) (#152)
+- 8th semantic state holding + manual-fence lift on interactive input (issue #145) (#151)
+
+### Fixes
+
+- **ci**: read the dispatch recovery tag from inputs, not the ref name (issue #154) (#156)
+- job-runner boot-window stop loss + dead-run reconcile convergence (issue #153) (#155)
+- **attach**: answer the color-scheme query client-side for attached sessions (issue #148) (#149)
+
+### Changes
+
+- probe knob guard uses the production-default floor, not a jitter-prone absolute bound (issue #95) (#159)
+- flake postmortems, budget audit gate, ladder knobs (issue #95 F3-F4) (#157)
+
+[0.10.0]: https://github.com/zhuxixi/pi-agent-board/compare/v0.9.0...v0.10.0
+
+## [0.9.0] - 2026-09-25
+
+### Features
+
+- **attach**: forward terminal queries to the real terminal — automatic theme works in attach sessions (issue #128) (#138)
+- **attach**: unconditional Ctrl+\ detach key, terminal-independent (issue #126) (#137)
+
+### Fixes
+
+- **runner**: probes leave attachedClients at hello (issue #130) (#142)
+- browse-mode Tab completes and drills down directories in cwd picker (issue #127) (#141)
+
+### Changes
+
+- **release**: orchestrate releases and publish from CI (#144)
+- control-reconcile flaky assertions — windowed recorder + invariant realignment (issue #140) (#143)
+- **attach**: scope A5 mid-stream seq assertion to post-snapshot window (issue #132) (#139)
+
+[0.9.0]: https://github.com/zhuxixi/pi-agent-board/compare/v0.8.0...v0.9.0
+
 ## [0.8.0] - 2026-09-23
 
 ### Features

package/README.md

@@ -93,7 +93,7 @@ From the board:
 - In Peek, press `r` to reply without attaching.
 - Press `v` for a read-only transcript, or `e` for evidence and diagnostics.
 - Press `Enter`, `Right`, or `>` to attach to the real Pi session.
-- In PTY attach mode, press `Ctrl+Left` to return to the board at any time (even mid-draft). `Left` detaches only while the child Pi reports an empty editor; otherwise (draft, or unknown editor state) it is forwarded to the child. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. When the host is disconnected, `Left` always exits.
+- In PTY attach mode, press `Ctrl+Left` to return to the board at any time (even mid-draft), or `Ctrl+\` — the unconditional escape: it detaches regardless of editor state on any terminal that forwards the raw 0x1c byte (raw, kitty, and modifyOtherKeys keyboard modes all work). `Left` detaches only while the child Pi reports an empty editor; otherwise (draft, or unknown editor state) it is forwarded to the child. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. When the host is disconnected, `Left` always exits. `Ctrl+\` caveats: on keyboard layouts where `\` sits on AltGr (e.g. German) the chord may never produce the byte — use `Ctrl+Left` there; in legacy keyboard modes `Ctrl+4` emits the same byte and also detaches; and the key is captured from the child while attached, so the child's own `Ctrl+\` binding (e.g. the vim terminal-mode prefix) is unavailable. Automatic themes also resolve correctly in attach sessions: the child's background probe (OSC 11) and color-scheme change notifications are forwarded to your real terminal, replies flow back to the child when your terminal answers, and attach re-probes the background once when it settles so the theme is right from the first frame. Set `AGENT_BOARD_FORWARD_TERMINAL_QUERIES=0` to disable this (default on); keyboard-protocol negotiation (kitty/DA) is not forwarded — it happens once at child spawn, before attach exists.
 
 ## Dashboard Workflow
 
@@ -114,7 +114,8 @@ Launch preferences are persisted and reused for later sessions. **Start & attach
 Session actions are deliberately confirmation-aware:
 
 - `d` confirms moving an inactive session to **Done**. Manual completion is the default.
-- Press `Ctrl+X` twice quickly to archive/delete the selected row. Archiving removes the row from the board but preserves its underlying Pi session file.
+- `h` toggles the on-hold state (manual verdict — automated writers are fenced).
+- Press `x`, then `y` to confirm deleting the selected row. `Ctrl+X` twice quickly still deletes without confirmation. Archiving removes the row from the board but preserves its underlying Pi session file.
 - `X` archives inactive rows in the selected state; live work is skipped.
 - `m` enters multi-select mode. Use `Space` to toggle rows, `a` to select all visible rows, `u` to clear the selection, `d` to mark inactive rows Done, or `Ctrl+X` to delete selected Done rows.
 
@@ -139,7 +140,9 @@ Shortcuts are scoped to the view where they are available:
 | `Ctrl+T` | Pin or unpin the selected session. |
 | `Ctrl+S` | Stop the selected active session. |
 | `d` | Confirm marking the selected inactive session Done. |
-| `Ctrl+X` twice quickly | Archive/delete the selected row. |
+| `h` | Hold or unhold the selected inactive session. |
+| `x`, then `y` | Archive/delete the selected row (confirmation prompt). |
+| `Ctrl+X` twice quickly | Archive/delete the selected row without confirmation. |
 | `X` | Delete inactive rows in the selected state. |
 | `m` | Enter multi-select mode. |
 | `!` | Open node-pty diagnostics and repair hints. |
@@ -156,6 +159,8 @@ Peek shows the selected session's summary, blocker or question, latest output, a
 | `a`, `Right`, or `>` | Attach to the session. |
 | `v` | Open the read-only transcript. |
 | `e` | Open Evidence / Diagnostics. |
+| `d` | Confirm marking the inactive session Done. |
+| `h` | Hold or unhold the session. |
 | `Up` / `Down` | Move to the previous or next session. |
 | `Esc` | Return to the main list. |
 
@@ -174,6 +179,7 @@ The `v` view is a read-only projection of the durable Pi session JSONL. It does
 | `Enter` or `a` | Attach to the session. |
 | `e` | Open Evidence / Diagnostics. |
 | `d` | Confirm marking the inactive session Done. |
+| `h` | Hold or unhold the session. |
 | `Left` / `Esc` / `<` | Return to the main list. |
 
 ### Evidence / Diagnostics
@@ -192,7 +198,9 @@ The `e` view shows durable session evidence, including changed files, commands a
 
 ### PTY attach
 
-PTY attach opens the real interactive Pi session. `Ctrl+Left` detaches and returns to the board regardless of editor state. `Left` detaches only while the child Pi reports an empty editor; while you are editing text — or when the child's editor state is unknown (e.g. the child extension is missing) — `Left` is forwarded to the Pi editor. A disconnected host can always be exited with `Left`. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. While attached, `PageUp`, `PageDown`, `Home`, `End`, and the mouse wheel scroll local scrollback. Mouse drag or double-click selects and copies text, clicks open detected links, and middle-click paste is available on systems with the required X11 tooling.
+PTY attach opens the real interactive Pi session. `Ctrl+Left` detaches and returns to the board regardless of editor state, and `Ctrl+\` is the unconditional escape — a single raw ASCII byte (0x1c) that terminals forward unchanged in raw mode (kitty CSI-u and modifyOtherKeys encodings included), honored no matter what the child editor reports. `Left` detaches only while the child Pi reports an empty editor; while you are editing text — or when the child's editor state is unknown (e.g. the child extension is missing) — `Left` is forwarded to the Pi editor. A disconnected host can always be exited with `Left`. `Ctrl+]` is not a detach key — it is passed through to the child Pi editor. `Ctrl+\` caveats: on keyboard layouts where `\` sits on AltGr (e.g. German) the chord may never produce the byte — use `Ctrl+Left` there; in legacy keyboard modes `Ctrl+4` emits the same byte and also detaches; and the key is captured from the child while attached, so the child's own `Ctrl+\` binding (e.g. the vim terminal-mode prefix) is unavailable. While attached, `PageUp`, `PageDown`, `Home`, `End`, and the mouse wheel scroll local scrollback. Mouse drag or double-click selects and copies text, clicks open detected links, and middle-click paste is available on systems with the required X11 tooling.
+
+Automatic light/dark themes work in attach sessions too. The child Pi's background-color probe (OSC 11) and its color-scheme change notification switch are forwarded to your real terminal; replies and notifications flow back to the child when your terminal answers — a terminal that never answers keeps the dark fallback. Attach also re-probes the background once when it settles, so the theme is correct from the first frame without re-selecting it in `/settings`. All of this is on by default; set `AGENT_BOARD_FORWARD_TERMINAL_QUERIES=0` to disable it. Not covered: keyboard-protocol negotiation (kitty flags / DA1) is not forwarded — the child negotiates once at spawn, before any attach client exists, and forwarding it would retune the shared real-terminal keyboard stack — so modifier-key encoding can still differ from a directly-run Pi (the modifyOtherKeys fallback applies).
 
 The attach surface can forward terminal clipboard and image/file passthrough sequences. These behaviors can be disabled individually in [Configuration](#configuration). Cold hosts may briefly show a loading/reconnect surface while their PTY becomes ready.
 
@@ -206,6 +214,7 @@ Agent Board separates a session's semantic task state from whether a worker proc
 | **Running** | The session is actively processing. |
 | **Needs answer** | The session is waiting for user input or an answer to a question. |
 | **Needs instructions** | The run ended without being marked complete and needs the next directive. |
+| **On hold** | The user parked this session intentionally (manual verdict, `h` to toggle). Automated writers can't push it to Done; queued follow-ups do not wake it. |
 | **Done** | The user marked the inactive session complete; this is the default completion path. |
 | **Failed** | The worker or host ended with an error. |
 | **Stopped** | The user stopped the active work. |
@@ -216,6 +225,7 @@ Press `/` to enter filter mode. Filter tokens are case-insensitive and can be co
 
 ```text
 s:running
+s:hold
 review:ready
 diag:stalled
 evidence:error
@@ -383,19 +393,17 @@ npm run verify
 
 ## Publishing
 
-Before publishing a release, verify the package, generate the changelog, then bump, and publish — the changelog must be generated **before** `npm version`, because `npm version` commits and tags the bump, which would empty the generation range:
+Releases run through `scripts/release.mjs` and are published by CI when a GitHub Release is created. The flow checks the parts that are easy to get wrong — the changelog range, tag ancestry against `main`, and drift from a late merge — instead of assuming them. See [docs/RELEASE.md](docs/RELEASE.md) for the full process, the one-time npm trusted-publisher setup, and failure recovery.
 
 ```bash
-npm run verify
-npm run changelog -- --dry-run     # preview the next section (version = current + patch)
-npm run changelog -- patch         # inserts the section into CHANGELOG.md
-node scripts/release_helper.mjs verify   # must exit 0: no functional PR missing from the top section
-git add CHANGELOG.md && git commit -m "docs(changelog): <version>"
-npm version patch                  # bumps package.json, commits, and tags vX.Y.Z
-npm publish
+node scripts/release.mjs precheck          # gate: clean main, nothing in flight
+node scripts/release.mjs prepare minor     # changelog + verify + bump + tag + release branch
+node scripts/release.mjs open-pr 0.9.0     # push the branch and tag, open the release PR
+# merge the PR with a merge commit, then:
+node scripts/release.mjs finish 0.9.0      # GitHub Release → CI publishes to npm
 ```
 
-Use `minor`/`major` in both the changelog and `npm version` steps when appropriate. The changelog is generated from conventional commits since the last `vX.Y.Z` tag (`scripts/release_helper.mjs`, ported from the jfox release flow); review the preview before committing. The `verify` step guards against PRs merged after the changelog was generated — rerun it after any late merge and, after removing the stale top section, re-run `npm run changelog -- <bump>` if it reports missing PRs (apply refuses when the section already exists — remove the stale section first). Release notes for the GitHub Release are the top CHANGELOG section. After publishing, users install the scoped package with:
+After publishing, users install the scoped package with:
 
 ```bash
 pi install npm:@zhuxixi/pi-agent-board
@@ -406,6 +414,7 @@ The Pi package gallery uses the `pi.video` and `pi.image` URLs from `package.jso
 ## Further Reading
 
 - [Manual verification](VERIFY.md) — static checks, Pi loading, provider authentication, persistence, and dashboard flows.
+- [Release process](docs/RELEASE.md) — release commands, trusted publishing setup, and failure recovery.
 - [Product requirements](PRD.md) — original product scope and design context.
 - [Progress log](PROGRESS.md) — implementation checkpoints and known environment notes.
 - [Exploration notes](docs/EXPLORATION.md) — Pi API and integration research.

package/VERIFY.md

@@ -82,7 +82,8 @@ Inside pi:
 4. **enter** on an empty input = attach to the selected full session (confirms first if it's still running).
    You're now in the real Pi session; run `/agent-board` again to return.
 5. Other keys: **/** filter (`s:running`, or free text), **Ctrl+R** rename, **Ctrl+T** pin, **Ctrl+S** stop,
-   **Ctrl+X** delete (archives the row, keeps the session file), **?** help, **Esc** clears input / quits when empty.
+   **x** then **y** delete (confirm prompt; archives the row, keeps the session file), **Ctrl+X** ×2 quick delete (no confirm),
+   **?** help, **Esc** clears input / quits when empty.
 
 ## 5. Inspect the durable store on disk
 

package/docs/RELEASE.md

@@ -0,0 +1,148 @@
+# Release process
+
+Releases are driven by `scripts/release.mjs` and published by CI when a GitHub
+Release is created. Four commands and one merge:
+
+```
+precheck  →  prepare <bump>  →  open-pr <version>  →  merge (merge commit!)
+          →  finish <version>  →  .github/workflows/publish.yml publishes to npm
+```
+
+`main` is protected, so a release lands as a pull request — but the npm publish
+is not tied to that PR: it is tied to the GitHub Release, which is created only
+after the PR is merged and the tag is confirmed to be on `main`.
+
+## One-time setup: the npm trusted publisher
+
+`publish.yml` publishes with **trusted publishing** (OIDC), so no `NPM_TOKEN`
+secret is stored in the repository. npm has to be told which workflow may
+publish the package — this is a one-time, per-package web step:
+
+1. Open <https://www.npmjs.com/package/@zhuxixi/pi-agent-board> and sign in as
+   the package owner.
+2. Go to **Settings** → **Trusted Publisher** → **GitHub Actions**.
+3. Fill in: organization `zhuxixi`, repository `pi-agent-board`, workflow
+   filename `publish.yml`, environment left empty.
+4. Save.
+
+Until this is configured, the CI publish step fails with an authentication
+error. Publishing locally (the pre-2026-09 flow, see "Local publish fallback"
+below) still works, because the npm account keeps its normal credentials.
+
+## Commands
+
+### `node scripts/release.mjs precheck`
+
+Read-only gate. Run it before anything else; it fails closed when the tree is
+dirty, `main` is not in sync with `origin/main`, a `release/*` PR is still open,
+the last tag is not an ancestor of `origin/main` (an orphan tag from a past
+squash merge), or there is nothing functional to release.
+
+### `node scripts/release.mjs prepare <patch|minor|major|X.Y.Z> [--dry-run]`
+
+Runs the gate, then:
+
+1. renders the new CHANGELOG section from the conventional commits since the
+   last `v*` tag,
+2. commits it as `docs(changelog): add <version> section`,
+3. runs `npm version <bump>` — one commit plus the annotated `v<version>` tag,
+4. switches to `release/v<version>`.
+
+Nothing leaves the machine. `--dry-run` prints the section and the plan without
+writing anything; review the preview before running it for real. Pick the bump
+the same way as before: features are a `minor`, fixes alone are a `patch`.
+
+### `node scripts/release.mjs open-pr <version> [--dry-run]`
+
+Pushes the release branch and the tag, then opens the PR with the CHANGELOG
+section as its body. The tag is pushed separately because tags are not covered
+by the branch protection rule.
+
+### Merge the PR with a merge commit
+
+**Do not squash the release PR.** `npm version` created the tag on a commit that
+only exists on the release branch; a merge commit brings that commit into
+`main`, a squash does not, and the tag becomes unreachable from `main`
+(`git describe` then misreads the changelog range of the next release). Use the
+**Merge pull request** button, or `gh pr merge --merge`.
+
+### `node scripts/release.mjs finish <version> [--dry-run] [--sync-main]`
+
+Run it after the merge. It fetches, verifies that `v<version>` is an ancestor of
+`origin/main`, re-checks the CHANGELOG against any functional PR merged after the
+bump, and then creates the GitHub Release with the CHANGELOG section as its
+notes. That release is the publish trigger. `--sync-main` also resets a clean
+local `main` to `origin/main`, dropping the local copy of the two release
+commits (they are content-equal to what the merge brought in).
+
+To publish without the orchestration, the underlying commands are
+`gh release create v<version> --title v<version> --notes-file <notes>` where the
+notes are `node scripts/release.mjs notes <version>`.
+
+## What CI does
+
+`.github/workflows/publish.yml` runs on `release: published`, checks out the
+tag, and:
+
+1. asserts npm is at least 11.5.1 (trusted publishing needs it; Node 24 ships
+   a newer one),
+2. asserts the tag equals `package.json`'s version,
+3. runs `npm run typecheck` and `npm test`,
+4. skips the publish when that version is already on npm, and otherwise
+5. runs `npm publish --provenance --access public`.
+
+Provenance means npm records which repository, workflow, and commit built the
+tarball, and shows it on the package page.
+
+## Recovering from a broken release
+
+**Orphan tag** (`finish` refuses with "not an ancestor of origin/main"). The
+release PR was squash-merged. Re-point the tag at the content-equivalent commit
+on `main`, then retry:
+
+```bash
+git fetch origin
+git tag -f v0.9.0 <sha on origin/main with the same content>
+git push origin v0.9.0 --force
+node scripts/release.mjs finish 0.9.0 --sync-main
+```
+
+**CHANGELOG drift** (`finish` refuses with missing PR numbers, or
+`node scripts/release_helper.mjs verify` exits 1). A functional PR merged after
+the changelog section was generated. Add the missing entries to the top section
+in a `docs(changelog)` PR, merge it, then retry — the release notes are read
+again at that point, so the fix is picked up.
+
+**The publish failed** (npm outage, trusted publisher not configured yet).
+Re-run the same tag without recreating the release: Actions → **Publish to
+npm** → **Run workflow** → enter the tag.
+
+**`npm view <package>` returns 404 right after a successful publish.** That is
+the registry's view index lagging, not a failed publish. Compare endpoints: the
+tarball, `/<package>/latest`, and `/-/package/<package>/dist-tags` answer
+immediately while the root document 404s for a few minutes. Wait; re-publishing
+the same version is rejected with a 403 and is never the fix.
+
+**Local publish fallback.** When the trusted publisher is not configured and a
+release cannot wait:
+
+```bash
+npm run verify
+npm publish --registry=https://registry.npmjs.org --access public
+```
+
+The registry must be passed explicitly: this machine defaults to
+`registry.npmmirror.com`. This path skips provenance and the CI checks, so
+prefer fixing the CI path.
+
+## CHANGELOG conventions
+
+`scripts/release_helper.mjs` renders the section from conventional commits in
+the range `<last v* tag>..HEAD`. `feat`/`fix`/`perf` become Features / Fixes /
+Performance, everything else (including `test` and `docs`) lands under Changes,
+merges and `npm version` squash subjects are skipped, and `docs(changelog):`
+subjects are ignored so changelog fixes do not feed back into the verify check.
+
+Every entry carries the PR number parsed from the trailing `(#N)`. `verify`
+fails when a functional commit's PR is missing from the top section — that is
+what keeps a late merge from shipping without release notes.

package/docs/superpowers/plans/2026-09-23-a5-mid-stream-assertion.md

@@ -0,0 +1,25 @@
+# Plan: A5 mid-stream 断言窗口修正（issue #132）
+
+Spec: `docs/superpowers/specs/2026-09-23-a5-mid-stream-assertion-design.md`（commit 5b6ec00）
+Base: main 1e832a1
+
+## Task 1: 断言修正 + stress 验证（A1, A2, A3, A4）
+
+**Files:** `test/terminal-snapshot.integration.test.mjs`（唯一，A5 mid-stream test case 体内，不动 helper/其它用例）
+
+**Changes:**
+1. **D1（A1）**: `:241` 附近——`seqsB` 构造改为窗口限定：`messagesB.filter((m) => m.type === "output" && m.seq >= endB.nextSeq).map((m) => m.seq)`；断言注释补一句为什么（订阅前 legacy 行 seq ≤ snapshotSeq < nextSeq，被过滤——引用 runner/pty-runner.mjs 广播分支行号）
+2. **D2（A2）**: `:227` 的 clientA waitFor 之后，加 `await waitFor(() => messagesB.filter((m) => m.type === "output" && m.seq >= endB.nextSeq).length >= ticks)`——显式等 socket B 追平再断言（沿用文件既有 waitFor 默认——15s，:29；A5-burst 的显式 30s 参数不在本 case）
+3. 断言本体不变（严格连续形态保留——窗口限定后就是纯协议流）
+4. **A3 stress 验证**：在 worktree 里跑 3 轮并行全量 `node --test test/*.test.mjs`（背靠背，高争用）——记录每轮 A5 mid-stream 结果；**若任何一轮 A5 mid-stream 仍失败且错误为 "strictly contiguous"** → 立即回炉报告，不许带病交付；账本 flake（subscribe_terminal / stop-finalize / A5-burst）照常隔离复跑不算回炉条件
+5. **A4**：全量其余断言绿
+
+**Verify:** `node --test test/terminal-snapshot.integration.test.mjs`（定向）+ 3 轮并行全量 + `npm run typecheck`
+
+**Commit:** `test(attach): scope A5 mid-stream seq assertion to post-snapshot window, wait for socket B catch-up explicitly (issue #132)`
+
+## Review 焦点预设
+
+- 窗口下限为什么是 `endB.nextSeq` 而非 `beginB.snapshotSeq + 1`（二者相等，用 nextSeq 更贴近协议游标语义）
+- D2 等待的 30s 天花板来源（文件 waitFor 默认），与 A5-burst 的显式 30s 参数区分
+- stress 3 轮的统计学诚实度（概率验证非根除证明，报告如实记录）