@zhuxixi/pi-agent-board 0.12.0 → 0.12.1

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.12.1] - 2026-10-20
+
+### Fixes
+
+- **release**: collapse repeated trailing PR refs in CHANGELOG entries (#218)
+- **attach**: keep the Alt modifier on the forwarded wheel report (#216)
+- **attach**: stop the reply guard swallowing kitty/modifyOtherKeys PageDown (#215)
+
+### Changes
+
+- **attach**: tidy the mouse-enable helper placement and comment indent (#209)
+
+[0.12.1]: https://github.com/zhuxixi/pi-agent-board/compare/v0.12.0...v0.12.1
+
 ## [0.12.0] - 2026-10-19
 
 ### Features

package/docs/superpowers/plans/2026-10-19-issue-213-reply-guard-csi-key.md

@@ -0,0 +1,257 @@
+# reply guard CSI-key collision — 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:** Stop the reply guard from swallowing kitty/modifyOtherKeys PageDown (`\x1b[6;<mods>u` / `\x1b[6;<mods>~`) while keeping every genuine cell-size reply fragment armed.
+
+**Architecture:** One new pure predicate in `src/core/terminal-reply-guard.mjs`: a *complete* CSI key sequence is user input and must be classified before the `REPLY_HEADS` prefix loop. Every fragment shape the guard protects today has no `u`/`~` terminator, so the predicate cannot weaken #170's protection.
+
+**Tech Stack:** ESM `.mjs` core module, `node:test` + `assert/strict`, TypeScript component (unchanged), `@earendil-works/pi-tui` (unchanged).
+
+**Spec:** `docs/superpowers/specs/2026-10-19-issue-213-reply-guard-csi-key-design.md`
+
+## Global Constraints
+
+- Tabs for indentation; English comments and commit messages (repo AGENTS.md).
+- No new dependencies.
+- `npm run verify` must pass on CI (typecheck + perf gate + tests + coverage + pack dry-run). Locally only the targeted suites plus `typecheck`/`pack:dry` are authoritative — this Windows host has a pre-existing ~72-test baseline failure set that also fails on `main`.
+- New test names carry the `#213-` prefix (spec §6 "验收 ID 作用域") to avoid colliding with the `A1:`/`A2:`/… names already in `test/terminal-reply-guard.test.mjs`.
+- Do not change `REPLY_HEADS`, the absorption window (250 ms / 64 bytes), or the kill switch.
+
+## Review Focus
+
+- **A genuine cell-size fragment that looks like a key** — `\x1b[6;` and `\x1b[6;24` (no terminator) must still `reply-head` and arm; only `u`/`~`-terminated sequences are keys.
+- **A complete reply that looks like a key** — `\x1b[6;24;80t` must still be `reply-complete`/drop (DROP_SHAPES runs first).
+- **Other kitty functional keys that share a head prefix** — `\x1b[6;1:2;65u` (alternate keys) must also be treated as a key, which is why the predicate is `(?:[;:]\d+)*` and not the narrower form in the issue text.
+- **A key that arrives while the guard is armed** — an armed window must not swallow it silently; the state machine's `armed + other` path drops the stale buffer and passes the event.
+- **Plain text right after a key** — forwarding must stay byte-exact (no duplication, no reordering).
+
+---
+
+### Task 1: Classify complete CSI keys before the head prefixes
+
+**Files:**
+- Modify: `src/core/terminal-reply-guard.mjs` (add `CSI_KEY_SEQUENCE` near the other shape constants, and one branch in `classifyReplyEvent`)
+- Test: `test/terminal-reply-guard.test.mjs`
+
+**Interfaces:**
+- Produces: `classifyReplyEvent(data)` now returns `{ kind: "other" }` for `CSI <num>[;<mod>[:<event>][;<alt>]]{u,~}`. No exported symbol changes.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `test/terminal-reply-guard.test.mjs`:
+
+```js
+// Issue #213: kitty / modifyOtherKeys PageDown shares the cell-size head prefix.
+test("#213-A1: a complete CSI key sequence is user input, never a reply head", () => {
+	for (const seq of ["\x1b[6;1u", "\x1b[6;5u", "\x1b[6;1:2u", "\x1b[6;1:2;65u", "\x1b[6;5~", "\x1b[6;2~"]) {
+		assert.deepEqual(classifyReplyEvent(seq), { kind: "other" }, `${JSON.stringify(seq)} must be a key`);
+	}
+});
+
+test("#213-A2: neighbouring keys are unaffected", () => {
+	for (const seq of ["\x1b[5;1u", "\x1b[5;5~", "\x1b[57422u", "\x1b[57421u", "\x1b[3;5~"]) {
+		assert.deepEqual(classifyReplyEvent(seq), { kind: "other" }, `${JSON.stringify(seq)} must stay a key`);
+	}
+});
+
+test("#213-A3: genuine cell-size fragments still arm", () => {
+	for (const seq of ["\x1b[6;", "\x1b[6;24"]) {
+		assert.deepEqual(classifyReplyEvent(seq), { kind: "reply-head", family: "cell-size" });
+	}
+});
+
+test("#213-A4: a complete cell-size reply still drops", () => {
+	assert.deepEqual(classifyReplyEvent("\x1b[6;24;80t"), { kind: "reply-complete", family: "cell-size", action: "drop" });
+});
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `node --test test/terminal-reply-guard.test.mjs`
+Expected: FAIL — `#213-A1` reports `{ kind: "reply-head", family: "cell-size" }` for `\x1b[6;1u` / `\x1b[6;5~`.
+
+- [ ] **Step 3: Implement the predicate**
+
+In `src/core/terminal-reply-guard.mjs`, next to `REPLY_HEADS`:
+
+```js
+// Issue #213: kitty keyboard protocol keys that carry a modifier use the legacy
+// functional-key encoding `CSI <num>;<mods>u`, and PageDown's legacy number IS 6
+// (`\x1b[6;1u` = no modifier, mods field is bitmask+1). modifyOtherKeys uses the same
+// prefix with `~` (`\x1b[6;5~`). Both therefore share the cell-size head prefix
+// (`\x1b[6;`), which used to arm the guard and swallow the key — asymmetric with
+// PageUp (key number 5) and invisible to the previous tests.
+//
+// A COMPLETE CSI key is user input, never a reply fragment: check it before the head
+// prefixes. Only the terminator decides — geniune cell-size fragments (`\x1b[6;`,
+// `\x1b[6;24`) carry no `u`/`~` and still arm below. `(?:[;:]\d+)*` also covers the
+// alternate-key form (`\x1b[6;1:2;65u`), which a narrower `(?:;\d+)?(?::\d+)?` misses.
+const CSI_KEY_SEQUENCE = /^\x1b\[\d+(?:[;:]\d+)*[u~]$/;
+```
+
+and in `classifyReplyEvent`, after the `FORWARD_SHAPES` loop and **before** the `REPLY_HEADS` loop:
+
+```js
+	// Issue #213: a complete CSI key wins over the head prefixes (see CSI_KEY_SEQUENCE).
+	if (CSI_KEY_SEQUENCE.test(data)) return { kind: "other" };
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `node --test test/terminal-reply-guard.test.mjs test/pty-scroll.test.mjs`
+Expected: PASS (the four new tests plus the existing 15).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/terminal-reply-guard.mjs test/terminal-reply-guard.test.mjs
+git commit -m "fix(attach): classify complete CSI keys before the reply-guard head prefixes (issue #213)"
+```
+
+---
+
+### Task 2: Prove the key actually reaches the child
+
+**Files:**
+- Modify: `test-support/attach-reply-guard-smoke.ts` (new case + result fields)
+- Modify: `test/pty-attach-reply-guard.test.mjs` (assertions)
+
+**Interfaces:**
+- Consumes: `classifyReplyEvent` behaviour from Task 1 through the real `PtyAttachComponent.handleInput`.
+- Produces: `out.guardedPageDown: string[]`, `out.guardedPageDownThenText: string[]` in the smoke's JSON.
+
+- [ ] **Step 1: Write the failing assertions**
+
+In `test/pty-attach-reply-guard.test.mjs`:
+
+```js
+assert.deepEqual(parsed.guardedPageDown, ["\x1b[6;1u", "\x1b[6;5~"], "kitty and modifyOtherKeys PageDown must be forwarded to the child, not swallowed");
+assert.deepEqual(parsed.guardedPageDownThenText, ["\x1b[6;1u", "x"], "text after a key must still be forwarded verbatim");
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test test/pty-attach-reply-guard.test.mjs`
+Expected: FAIL — `parsed.guardedPageDown` is `undefined`.
+
+- [ ] **Step 3: Implement the smoke case**
+
+In `test-support/attach-reply-guard-smoke.ts`, next to the existing `guardedFragments` case:
+
+```ts
+	// Issue #213: a complete CSI key must reach the child, not the absorption window.
+	f.attach.handleInput("\x1b[6;1u");
+	f.attach.handleInput("\x1b[6;5~");
+	out.guardedPageDown = [...f.sent];
+
+	// …and the bytes that follow a key are still forwarded verbatim.
+	f.attach.handleInput("\x1b[6;1u");
+	f.attach.handleInput("x");
+	out.guardedPageDownThenText = [...f.sent];
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `node --test test/pty-attach-reply-guard.test.mjs`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add test-support/attach-reply-guard-smoke.ts test/pty-attach-reply-guard.test.mjs
+git commit -m "test(attach): pin that kitty PageDown reaches the child through the reply guard (issue #213)"
+```
+
+---
+
+### Task 3: Retire the pinned invariant in the docs
+
+**Files:**
+- Modify: `src/core/terminal-reply-guard.mjs` (module header comment)
+- Modify: `docs/superpowers/specs/2026-10-14-issue-170-attach-reply-guard-design.md` (§3.3 design-points list)
+
+**Interfaces:**
+- Consumes: nothing at runtime; produces the text the A8 static check greps for.
+
+- [ ] **Step 1: Update the module header**
+
+In the `terminal-reply-guard.mjs` header, extend the paragraph that lists what arms a window with:
+
+```
+ * Issue #213: `\x1b[6;` is NOT a "can never be a key" prefix — kitty's functional-key
+ * encoding puts PageDown at `CSI 6;<mods>u` (and modifyOtherKeys at `\x1b[6;<mods>~`).
+ * The rule is therefore "a COMPLETE CSI key sequence (`u`/`~` terminated) beats the head
+ * prefixes", not "these prefixes are never keys". Fragments without a terminator still arm.
+```
+
+- [ ] **Step 2: Append the correction to the #170 design doc**
+
+In `docs/superpowers/specs/2026-10-14-issue-170-attach-reply-guard-design.md`, at the end of the §3.3 design-points list (do NOT rewrite L106 — append):
+
+```markdown
+7. **修正（issue #213）**：上一条「`ESC[6;` 永不可能是按键前缀」已被推翻 —— kitty 功能键编码
+   把 PageDown 放在 `CSI 6;<mods>u`（modifyOtherKeys 为 `\x1b[6;<mods>~`），与 cell-size 的
+   `ESC[6;` 共享前缀。现行规则是「**完整 CSI 键序列（以 `u`/`~` 终结）优先于 head 前缀**」，
+   不带终结符的片段仍然武装。实现见 `CSI_KEY_SEQUENCE`。
+```
+
+- [ ] **Step 3: Verify the A8 greps**
+
+Run:
+```bash
+grep -n "complete CSI key" src/core/terminal-reply-guard.mjs
+grep -n "完整 CSI 键序列优先.*#213" docs/superpowers/specs/2026-10-14-issue-170-attach-reply-guard-design.md
+grep -c "can never be a key" src/core/terminal-reply-guard.mjs
+```
+Expected: the first two each match at least once (the first inside the module header, not inside a function body); the third prints 0.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/core/terminal-reply-guard.mjs docs/superpowers/specs/2026-10-14-issue-170-attach-reply-guard-design.md
+git commit -m "docs(attach): retire the 'ESC[6; is never a key' invariant (issue #213)"
+```
+
+---
+
+### Task 4: Full gate
+
+**Files:** none (verification only).
+
+- [ ] **Step 1: Type/static checks**
+
+Run: `npm run typecheck && npm run pack:dry`
+Expected: both clean.
+
+- [ ] **Step 2: Targeted suites**
+
+Run: `node --test test/terminal-reply-guard.test.mjs test/pty-attach-reply-guard.test.mjs test/pty-scroll.test.mjs test/pty-attach-wheel.test.mjs`
+Expected: all green.
+
+- [ ] **Step 3: Baseline comparison**
+
+Run: `node --test test/pty-attach-*.test.mjs` and compare the failing set against the known Windows-host baseline (same set as on `main`; no new names).
+Expected: no new failures.
+
+- [ ] **Step 4: Commit**
+
+Nothing to commit — this task is the gate the PR description cites.
+
+---
+
+### Task 5: Manual verification (U1)
+
+**Files:** none.
+
+- [ ] **Step 1: Load the fix into a real pi**
+
+Per spec §6.1: `pi install "$(pwd)"` (README.md:54) or symlink the worktree to
+`~/.pi/agent/extensions/agent-board`, **not** the `~/.pi/agent/git/...` cache clone.
+
+- [ ] **Step 2: Restart pi completely** and open a new attach session.
+
+- [ ] **Step 3: Press PageDown in the attach view** (WezTerm + pi fullscreen).
+Expected: the panel scrolls one page backwards, mirroring PageUp; no swallowed key.
+
+- [ ] **Step 4: Record the outcome** in the issue (pass/fail + observed behaviour).

package/docs/superpowers/plans/2026-10-19-issue-214-attach-forward-alt-modifier.md

@@ -0,0 +1,202 @@
+# attach forward Alt modifier — 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:** Preserve the Alt modifier when the attach view forwards a wheel notch to a fullscreen child, so Alt+wheel keeps its 5× accelerator.
+
+**Architecture:** `encodeWheelReport` gains an optional `alt` flag that sets SGR bit 3 (`+8`); `forwardWheelToChild` passes `event.alt === true` through. Nothing else changes — the local scroll path never rebuilds the report.
+
+**Tech Stack:** ESM `.mjs` pure helper, TypeScript component shell, `node:test` + `assert/strict`.
+
+**Spec:** `docs/superpowers/specs/2026-10-19-issue-214-attach-forward-alt-modifier-design.md`
+
+## Global Constraints
+
+- Tabs for indentation; English comments and commit messages (repo AGENTS.md).
+- No new dependencies.
+- Local `npm run verify` cannot go green on this Windows host (pre-existing ~72-test baseline that also fails on `main`); the authoritative local gates are the targeted suites plus `npm run typecheck` and `npm run pack:dry`. CI is the final gate.
+- `alt` must be compared strictly (`=== true`), never by truthiness: a stray `1`/`"yes"` must not set bit 3.
+- Do not touch the local scroll path, the reply guard, or the input classifier.
+
+## Review Focus
+
+- **A truthy non-boolean `alt`** — `alt: 1` and `alt: "yes"` must NOT set bit 3, because the component passes `event.alt === true` (an older pi-tui could hand over something unexpected).
+- **Plain wheel parity** — with no Alt, the encoded report must stay byte-identical to today's (`\x1b[<64;…M` / `\x1b[<65;…M`); the existing #198/#205 assertions must keep passing untouched.
+- **The forward hop is the only seam** — the legacy regular-mode path forwards the raw SGR unchanged and already carries Alt; a change that also rewrote that path would be a scope violation.
+- **Down direction** — `alt + down` is `73`, not `72`; an implementation that ORs the bit onto a fixed 64 would break down-scroll.
+- **Child-side consumption** — the byte must decode as `button & 8 !== 0` under pi-tui's `parseWheelEvent`; `72`/`73` satisfy that and `64`/`65` do not.
+
+---
+
+### Task 1: Encode the Alt bit in `encodeWheelReport`
+
+**Files:**
+- Modify: `src/core/pty-scroll.mjs` (`encodeWheelReport`, ~L370)
+- Test: `test/pty-scroll.test.mjs`
+
+**Interfaces:**
+- Produces: `encodeWheelReport(direction: "up"|"down", { col?: number, row?: number, alt?: boolean }) -> string`. Default `alt: false` keeps every existing call site identical.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `test/pty-scroll.test.mjs`:
+
+```js
+// Issue #214: Alt is SGR bit 3 (value 8); the child's pi-tui reads it to apply the
+// 5x wheel multiplier, so the forward hop must not strip it.
+test("#214-A1: Alt+wheel-up encodes button 72", () => {
+	assert.equal(encodeWheelReport("up", { col: 5, row: 3, alt: true }), "\x1b[<72;5;3M");
+});
+
+test("#214-A2: Alt+wheel-down encodes button 73", () => {
+	assert.equal(encodeWheelReport("down", { col: 5, row: 3, alt: true }), "\x1b[<73;5;3M");
+});
+
+test("#214-A3: without a strict boolean true, bit 3 stays clear", () => {
+	for (const alt of [false, undefined, null, 0, 1, "yes"]) {
+		assert.equal(encodeWheelReport("up", { col: 5, row: 3, alt }), "\x1b[<64;5;3M", `alt=${String(alt)} must not set bit 3`);
+		assert.equal(encodeWheelReport("down", { col: 5, row: 3, alt }), "\x1b[<65;5;3M", `alt=${String(alt)} must not set bit 3`);
+	}
+});
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `node --test test/pty-scroll.test.mjs`
+Expected: FAIL — `#214-A1` gets `\x1b[<64;5;3M` instead of `72`.
+
+- [ ] **Step 3: Implement**
+
+```js
+export function encodeWheelReport(direction, { col, row, alt = false } = {}) {
+	const base = direction === "up" ? 64 : 65;
+	// Issue #214: SGR bit 3 (value 8) is Alt. pi-tui multiplies by 5 when it is set,
+	// so the forward hop must carry it. Strict comparison: a truthy non-boolean must
+	// not flip the bit.
+	const button = alt === true ? base + 8 : base;
+	const cell = (v) => (Number.isFinite(v) ? Math.max(1, Math.floor(v)) : 1);
+	return `\x1b[<${button};${cell(col)};${cell(row)}M`;
+}
+```
+
+Keep the existing JSDoc's description of the direction/coordinates; add one line about `alt`.
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run: `node --test test/pty-scroll.test.mjs`
+Expected: PASS (three new tests plus the existing suite).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/pty-scroll.mjs test/pty-scroll.test.mjs
+git commit -m "feat(attach): carry the Alt modifier in the forwarded wheel report (issue #214)"
+```
+
+---
+
+### Task 2: Pass `event.alt` through the forward hop
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts` (`forwardWheelToChild`, ~L1477)
+- Modify: `test-support/pty-attach-wheel-fallback-scenario.ts` (new alt round)
+- Modify: `test/pty-attach-wheel-fallback.test.mjs` (new assertions)
+
+**Interfaces:**
+- Consumes: `encodeWheelReport(…, { alt })` from Task 1.
+- Produces: scenario result fields `forwardedAltUp` / `forwardedAltDown`.
+
+- [ ] **Step 1: Write the failing assertion**
+
+In `test/pty-attach-wheel-fallback.test.mjs`, after the existing plain-wheel assertions (which must stay untouched):
+
+```js
+assert.equal(parsed.forwardedAltUp, "\x1b[<72;4;3M", "Alt+wheel-up must reach the child as button 72");
+assert.equal(parsed.forwardedAltDown, "\x1b[<73;4;3M", "Alt+wheel-down must reach the child as button 73");
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `node --test test/pty-attach-wheel-fallback.test.mjs`
+Expected: FAIL — `parsed.forwardedAltUp` is `undefined`.
+
+- [ ] **Step 3: Implement**
+
+In `src/ui/pty-attach.ts` `forwardWheelToChild`, add the flag:
+
+```ts
+			data: encodeWheelReport(linesUp > 0 ? "up" : "down", {
+				col: clampInt(event.x + 1, 1, this.cols),
+				row: clampInt(event.y, 1, Math.max(1, this.bodyHeight())),
+				// Issue #214: the overlay already received the Alt bit from pi-tui; carry it
+				// into the synthesized report so the child keeps its 5x wheel accelerator.
+				alt: event.alt === true,
+			}),
+```
+
+In `test-support/pty-attach-wheel-fallback-scenario.ts`, add one more round using the existing `mouseBase` (do not modify the existing rounds, whose assertions are #198's regression pins):
+
+```ts
+	// Issue #214: Alt must survive the forward hop.
+	let beforeAlt = forwardedInputs().length;
+	(component as any).handleMouse({ ...wheelEvent(-3), alt: true });
+	if (await waitFor(() => forwardedInputs().length > beforeAlt, 3000)) {
+		result.forwardedAltUp = forwardedInputs().at(-1) ?? null;
+	}
+	beforeAlt = forwardedInputs().length;
+	(component as any).handleMouse({ ...wheelEvent(2), alt: true });
+	if (await waitFor(() => forwardedInputs().length > beforeAlt, 3000)) {
+		result.forwardedAltDown = forwardedInputs().at(-1) ?? null;
+	}
+```
+
+Declare both fields in the scenario's `result` object (`null as string | null`).
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `node --test test/pty-attach-wheel-fallback.test.mjs`
+Expected: PASS — the two new assertions and every existing #198 assertion.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ui/pty-attach.ts test-support/pty-attach-wheel-fallback-scenario.ts test/pty-attach-wheel-fallback.test.mjs
+git commit -m "fix(attach): forward the Alt modifier on the wheel hop (issue #214)"
+```
+
+---
+
+### Task 3: Regression gate
+
+**Files:** none.
+
+- [ ] **Step 1: Targeted suites**
+
+Run: `node --test test/pty-scroll.test.mjs test/pty-attach-wheel-fallback.test.mjs test/pty-attach-wheel.test.mjs test/pty-attach-frame-overflow.test.mjs test/pty-attach-alt-wheel.test.mjs test/pty-attach-mouse-mode.test.mjs test/terminal-reply-guard.test.mjs`
+Expected: all green.
+
+- [ ] **Step 2: Static gates**
+
+Run: `npm run typecheck && npm run pack:dry`
+Expected: both clean.
+
+- [ ] **Step 3: Baseline comparison**
+
+Run: `node --test test/pty-attach-*.test.mjs` and compare the failing set against the known Windows-host baseline. Expected: no new names.
+
+---
+
+### Task 4: Manual verification (U1)
+
+**Files:** none.
+
+- [ ] **Step 1: Load this checkout into pi**
+
+`pi install "$(pwd)"` (README.md:54) or symlink to `~/.pi/agent/extensions/agent-board` — **not** the `~/.pi/agent/git/...` cache clone.
+
+- [ ] **Step 2: Restart pi completely**, open a new attach session on a fullscreen child.
+
+- [ ] **Step 3: Hold Alt and roll one wheel notch** in the attach view.
+Expected: the child scrolls 5 lines, matching the behaviour outside attach.
+
+- [ ] **Step 4: Record the outcome** in the issue.

package/docs/superpowers/specs/2026-10-14-issue-170-attach-reply-guard-design.md

@@ -111,6 +111,11 @@ export function createReplyGuard({ windowMs = REPLY_GUARD_WINDOW_MS, maxAbsorbBy
 
 6. **近失形状的归属**（R2-D3）：完整但参数为空的 DA（`ESC[?c`）按完成形状处理（drop）；不完整前缀（`ESC[?1;`、`ESC[6;`、`ESC[6;24;80`、`ESC]11;`、`ESC P`）一律武装（swallow）；未知第三值的 997 报告按 forward 家族整条转发。这三类由 A1/A4 的「近失形状」清单锁死，不得靠实现者自由发挥。
 
+7. **修正（issue #213）**：第 1 条「`ESC[6;` 永不可能是按键前缀」已被推翻 —— kitty 功能键编码
+   把 PageDown 放在 `CSI 6;<mods>u`（modifyOtherKeys 为 `\x1b[6;<mods>~`），与 cell-size 的
+   `ESC[6;` 共享前缀。「完整 CSI 键序列优先」（#213）是现行规则：以 `u`/`~` 终结的完整键序列
+   先于 head 前缀判定，不带终结符的片段仍然武装。实现见 `CSI_KEY_SEQUENCE`。
+
 ### 3.4 接线点
 
 `src/ui/pty-attach.ts` 的 `handleInput(data)` **最前面**（在既有 mouse/key 拦截之前）：

package/docs/superpowers/specs/2026-10-19-issue-213-reply-guard-csi-key-design.md

@@ -0,0 +1,165 @@
+Drafted: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T12:40:00+08:00
+Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T13:05:00+08:00 — 第 1 轮复核处置（R1-G1/G2/G3 + D1/D2/D3）
+Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T13:15:00+08:00 — 第 2 轮复核处置（R2-G1 + D1/D2/D3）
+Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T13:25:00+08:00 — 第 3 轮复核处置（收敛轮，R3-D1/D2/D3 细化）
+Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T14:20:00+08:00 — 代码评审批次修复（A8③ 空转 grep、REPLY_HEADS 注释未改、armed 路径未覆盖）
+
+# issue #213 根因报告与修复设计：reply guard 的 cell-size 前缀吞掉 kitty 编码的 PageDown
+
+仓库：zhuxixi/pi-agent-board · 基线：`origin/main` @ `ef4317f`
+
+## 1. 症状
+
+`v0.12.0` + WezTerm 20240203 + pi fullscreen 1.3.0 → `/agent-board` → attach：
+
+| 键 | 结果 |
+| --- | --- |
+| `PageUp` | 正常（本地滚动 / 转发） |
+| `PageDown` | **完全无反应** |
+| 鼠标滚轮 | 正常 |
+
+不对称本身就是线索：两个键在 `handleKeyInput` 里走**完全相同**的
+`tryScrollBy(±pageSize)` → `send()` 兜底，所以差异只能出在更上游的输入分类层。
+
+## 2. 根因
+
+`src/core/terminal-reply-guard.mjs` 的 `REPLY_HEADS` 含：
+
+```js
+{ family: "cell-size", prefix: "\x1b[6;" }
+```
+
+本意是吸收被拆碎的 XTWINOPS cell-size 回复（`CSI 6;<rows>;<cols>t`）。
+但 **PageDown 的 legacy 功能键编号正是 6**：kitty 键盘协议下带修饰键的 PageDown 编码为
+`CSI 6;<mod>u`（`\x1b[6;1u`），modifyOtherKeys 回退下为 `CSI 6;<mod>~`（`\x1b[6;5~`）。
+两者都以 `\x1b[6;` 开头 → `classifyReplyEvent` 判成 `reply-head` → guard 进入 armed
+→ 250ms/64 字节吸收窗口把按键吞掉。PageUp 的编号是 5（`\x1b[5;1u`），永不命中，所以不受影响。
+
+附带发现的**文档与代码矛盾**：`REPLY_HEADS` 上方的注释写着
+「Deliberately absent: … `\x1b[5`/`\x1b[6` (PageUp/PageDown heads)」，
+但列表里实际存在 `\x1b[6;` —— 注释想表达的是"不吸收 `\x1b[6` 开头的裸键位"，
+实现却用了一个更宽的前缀，正是这条矛盾掩盖了本次冲突。
+
+引入点：`2148360 fix(attach): stop terminal reply fragments leaking into the attached child's input (#194)`。
+
+## 3. 证据（对仓库当前代码实测）
+
+```
+"\x1b[6;1u"     → { kind: "reply-head", family: "cell-size" }   ❌ PageDown 被吞
+"\x1b[6;5~"     → { kind: "reply-head", family: "cell-size" }   ❌ modifyOtherKeys PageDown 被吞
+"\x1b[5;1u"     → { kind: "other" }                             ✓ PageUp
+"\x1b[6~"       → { kind: "other" }                             ✓ 无修饰的 legacy PageDown
+"\x1b[57422u"   → { kind: "other" }                             ✓ kitty codepoint 形式
+"\x1b[6;"       → { kind: "reply-head", family: "cell-size" }   ✓ 真 fragment 仍 arm
+"\x1b[6;24"     → { kind: "reply-head", family: "cell-size" }   ✓
+"\x1b[6;24;80t" → { kind: "reply-complete", action: "drop" }    ✓
+```
+
+现有测试（15 个 `test()` / 63 条 assert，全绿）**没有覆盖** `\x1b[6;<mod>u` / `\x1b[6;<mod>~` 形态 —— 这是回归缺口。
+`test/terminal-reply-guard.test.mjs:58` 只测了裸 `\x1b[5~` / `\x1b[6~`，
+`:96` 测了 `\x1b[6;` 仍需 arm。
+
+## 4. 修复
+
+**在 head 前缀之前**识别"完整的 CSI 键序列"：真 cell-size fragment 没有 `u`/`~` 终结符，
+所以完整键序列可以安全地判成用户输入。
+
+```js
+// Kitty / modifyOtherKeys keys: `CSI <num>[;<mod>…]{u,~}`. PageDown's legacy number
+// is 6, which shares the `\x1b[6;` prefix with the cell-size reply head.
+const CSI_KEY_SEQUENCE = /^\x1b\[\d+(?:[;:]\d+)*[u~]$/;
+
+export function classifyReplyEvent(data) {
+    …DROP/FORWARD 判定不变…
+    // A COMPLETE CSI key is user input, never a reply fragment.
+    if (CSI_KEY_SEQUENCE.test(data)) return { kind: "other" };
+    for (const head of REPLY_HEADS) { … }
+    …
+}
+```
+
+**正则比 issue 原文更宽一点**：issue 给的 `/^\x1b\[\d+(?:;\d+)?(?::\d+)?[u~]$/` 覆盖不了
+kitty 的"交替键"编码 `\x1b[6;1:2;65u`（`;65` 在主修饰符之后），会重新落回 reply-head。
+`(?:[;:]\d+)*` 覆盖全部 `CSI <num>;[<mod>[:<event>][;<alternate>]]u` 形态。
+
+保持不变的行为：
+
+- `\x1b[6;`、`\x1b[6;24`（无终结符）→ 仍然 `reply-head`（arm）
+- `\x1b[6;24;80t` → 仍然 `reply-complete` drop（DROP_SHAPES 命中在前）
+- 其余 `REPLY_HEADS`（`\x1b[?`、`\x1b[>`、`\x1bP`、`\x1b]1`、`\x1b]4`）无键位冲突，不动
+
+顺带修掉 `REPLY_HEADS` 上方与新语义矛盾的注释（说明 `\x1b[6;` 只能靠"完整键序列优先"来消解冲突）。
+
+### 4.1 推翻既有设计文档的 pinned 不变式（R1-G3）
+
+`docs/superpowers/specs/2026-10-14-issue-170-attach-reply-guard-design.md:106` 钉死了：
+
+> 窗口只由 `reply-head` 武装，只有「**永不可能是按键/鼠标编码前缀**」的形状才武装：
+> `ESC[?`、`ESC[>`、**`ESC[6;`**、`ESC P`、`ESC]1`、`ESC]4`。
+
+本次根因正是这条论断的反例：kitty 功能键编号形态 `ESC[6;1u`（PageDown）打破「永不可能是按键前缀」。
+因此本修复**显式推翻**该不变式，替换为：
+
+> 完整 CSI 键序列（`CSI <num>[;<mod>[:<event>][;<alt>]]{u,~}`）优先于 head 前缀判定；
+> 只有**不带** `u`/`~` 终结符的片段才按 head 武装。
+
+同步要求（实现阶段必做）：
+
+- **改掉 `REPLY_HEADS` 上方那段与新语义矛盾的注释**（源码 :76-79，「can never be a key/mouse/paste
+  encoding」「Deliberately absent: … `[5`/`[6`（PageUp/PageDown heads）」）：不得再出现
+  绝对断言，改为说明「完整键序列优先，只有不带终结符的片段才武装」。
+  模块 header 用**英文**写同一条规则（`complete CSI key sequence … beats the head prefixes`），
+  中文仅在 #170 文档里作为跨引用出现。
+- 在 #170 设计文档 §3.3 的「设计要点」清单里补上「完整 CSI 键序列优先于 head 前缀」这一新类别，
+  并把 L106 的论断标注为已被 #213 修正（追加而非改写历史）
+- #170 文档 L112 与 A4 清单里「`ESC[6;` 必须武装」仍然成立（本修复只对**完整**键序列例外）
+
+## 5. 边界与风险
+
+| 风险 | 说明 / 缓解 |
+| --- | --- |
+| 真 cell-size 回复被误判成键 | 不可能：cell-size 以 `t` 结尾，不带 `u`/`~` |
+| kitty 其他功能键（`\x1b[5;1u` 等） | 本就未被 head 命中，行为不变 |
+| modifyOtherKeys 其他键（`\x1b[3;5~`） | 不命中 `\x1b[6;`，行为不变 |
+| 极少数终端把 PageDown 编码成 `\x1b[6;`（截断） | 仍会 arm 并吞掉；这是 issue #170 的保护方向，保留 |
+| 安全方向 | 修复只是让**用户按键**更早地判定为非回复；不会让回复碎片更容易漏进子会话 |
+
+## 6. 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+| --- | --- | --- | --- | --- |
+| A1 | kitty/modifyOtherKeys PageDown 判为键 | 自动化（unit） | `test/terminal-reply-guard.test.mjs`：`\x1b[6;1u`、`\x1b[6;5u`、`\x1b[6;1:2u`、`\x1b[6;1:2;65u`、`\x1b[6;5~` | 全部 `{ kind: "other" }` |
+| A2 | PageUp 与其他键不受影响 | 自动化（unit） | 同文件：`\x1b[5;1u`、`\x1b[5;5~`、`\x1b[57422u`、`\x1b[57421u`、`\x1b[3;5~` | 全部 `{ kind: "other" }` |
+| A3 | 真 cell-size fragment 仍 arm | 自动化（unit） | 同文件：`\x1b[6;`、`\x1b[6;24` | 均 `{ kind: "reply-head", family: "cell-size" }` |
+| A4 | 完整 cell-size 回复仍 drop | 自动化（unit） | 同文件：`\x1b[6;24;80t` | `{ kind: "reply-complete", family: "cell-size", action: "drop" }` |
+| A5 | guard 状态机不回归 | 自动化（unit） | 现有 `terminal-reply-guard` 全部用例 | 全绿 |
+| A6 | attach 按键真的转发到子会话（不被 guard 吞） | 自动化（integration） | `test-support/attach-reply-guard-smoke.ts` 新增：`handleInput("")` / `handleInput("[6;5~")` 后 `sent` 含该字节；断言归 `test/pty-attach-reply-guard.test.mjs` | `sent` 收到完整键序列；且随后的普通文本仍正常转发 |
+| A7 | 语法/静态检查 | 自动化（static） | `npm run typecheck`（`tsconfig` 对 `.mjs` 是 `allowJs` + `checkJs:false`，只做语法解析）+ `npm run pack:dry` | 均通过 |
+| A8 | §4.1 的文档同步真的落地 | 自动化（static） | 三条独立 grep，全部锚定**英文** marker（源码是英文注释，中文只出现在 #170 文档）：① `grep -c "complete CSI key" src/core/terminal-reply-guard.mjs`（≥1，且位于模块顶部注释区）；② `grep -n "完整 CSI 键序列优先.*#213" docs/superpowers/specs/2026-10-14-issue-170-attach-reply-guard-design.md`（≥1）；③ `grep -c "can never be a key" src/core/terminal-reply-guard.mjs`（**必须为 0** —— 旧的绝对断言已删除） | ①② ≥1、③ ==0 |
+| U1 | 真实终端 PageDown | 用户实测 | 见 §6.1 三步前置 + WezTerm + pi fullscreen → attach → 按 PageDown | 面板按页向后滚动（或转发给子会话），与 PageUp 对称 |
+
+### 6.1 U1 执行时机与部署前置
+
+仓库加载补丁 checkout 的方式见 `README.md:54`（`pi install "$(pwd)"`）或 `README.md:68`（symlink 到
+`~/.pi/agent/extensions/agent-board`）。U1 必须在以下三步之后执行，否则测的是旧代码：
+
+1. 用上述任一方式把**当前 worktree/checkout** 加载到 pi（不是 `~/.pi/agent/git/...` 的缓存克隆）
+2. 完整重启 pi（模块缓存不会热更新），并新开一个 attach 会话
+3. 时机：本地 `npm run typecheck` + 目标套件全绿之后、合并之前
+
+> **验收 ID 作用域**：#213 的 `A1–A8` 仅指本 issue。新增测试名一律带 `#213-` 前缀
+> （如 `test("#213-A1: kitty PageDown is a key, not a reply head")`），
+> 因为 `test/terminal-reply-guard.test.mjs` 里已有 #170 遗留的 `A1:`/`A2:`/… 测试名，
+> 直接用 `--test-name-pattern="A1"` 会同时命中两套语义不同的用例。
+
+## 7. 可测性拆分设计
+
+- **判定逻辑已经是纯函数**（`classifyReplyEvent`），零改动地单测；本次只新增一个正则常量。
+- 测试边界：`test/terminal-reply-guard.test.mjs` 覆盖 A1–A5（纯函数层）；`test-support/attach-reply-guard-smoke.ts` + `test/pty-attach-reply-guard.test.mjs` 覆盖 A6（真实 `PtyAttachComponent.handleInput` → `sent` 转发，只替换 socket）。`test/pty-scroll.test.mjs` 与本次改动无关，不作为护栏。
+- 正则常量导出与否：**不导出**（内部实现细节），测试通过 `classifyReplyEvent` 的公开行为验证，避免把实现形状钉进测试。
+
+## 8. 非目标
+
+- 不改变 guard 的吸收窗口（250ms / 64 字节）与 kill switch 语义
+- 不改动其他 `REPLY_HEADS` 条目
+- 不处理 `PageUp`/`PageDown` 在 legacy 路径的行为差异（本就正常）

package/docs/superpowers/specs/2026-10-19-issue-214-attach-forward-alt-modifier-design.md

@@ -0,0 +1,131 @@
+Drafted: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T13:58:00+08:00
+Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-19T14:10:00+08:00 — 第 1 轮复核处置（收敛轮，R1-D1..D4 细化）
+
+# issue #214 根因报告与修复设计：attach 转发丢 Alt 修饰位，Alt+滚轮退化为 1 行
+
+仓库：zhuxixi/pi-agent-board · 基线：`origin/main` @ `64bca89`
+
+## 1. 症状
+
+pi fullscreen 1.3.0 + WezTerm，在 attach 一个 fullscreen 子会话时：
+
+| 手势 | 正常 fullscreen | attach 内 |
+| --- | --- | --- |
+| 滚轮 | 1 notch = 加速后的行数 | 相同（转发给子会话） |
+| **Alt + 滚轮** | **5×**（`ALT_WHEEL_SCROLL_MULTIPLIER = 5`） | **1×** —— Alt 被静默丢弃 |
+
+其余滚轮行为（普通滚轮、PageUp/PageDown、本地 scrollback）都正常。
+
+## 2. 根因
+
+fullscreen 子会话的滚轮走**转发**路径（alternate buffer 无 scrollback，见 #185/#198/#199/#205）。该路径**从零重建** SGR 报告，只保留方向：
+
+`src/ui/pty-attach.ts:1477`：
+
+```ts
+private forwardWheelToChild(linesUp: number, event: TuiMouseEvent): void {
+    this.send({
+        type: "input",
+        data: encodeWheelReport(linesUp > 0 ? "up" : "down", {
+            col: clampInt(event.x + 1, 1, this.cols),
+            row: clampInt(event.y, 1, Math.max(1, this.bodyHeight())),
+            // ← event.alt 没有传
+        }),
+    });
+}
+```
+
+`src/core/pty-scroll.mjs:370`：
+
+```js
+export function encodeWheelReport(direction, { col, row } = {}) {
+    const button = direction === "up" ? 64 : 65;   // 永远不置 SGR bit 3 (值 8 = Alt)
+    ...
+}
+```
+
+真实终端用 SGR **bit 3（值 8）** 表示 Alt：Alt+wheel-up = `72 = 64 + 8`，Alt+wheel-down = `73 = 65 + 8`。
+子会话的 pi-tui 正是读这一位来决定 5× 加速
+（`@earendil-works/pi-tui/dist/tui-alt-screen.js` `handleViewportInput`）：
+
+```js
+const wheelDelta = wheelEvent.direction * ((wheelEvent.button & 8) !== 0 ? lines * ALT_WHEEL_SCROLL_MULTIPLIER : lines);
+```
+
+attach 覆盖层**本来就拿到了** Alt：pi-tui 的 `TuiMouseEvent` 带 `alt: boolean`（`createMouseEvent` 里 `alt: (button & 8) !== 0`）。它只是没被传下去。
+
+## 3. 证据（对仓库当前代码实测）
+
+```
+encodeWheelReport("up",   {col:5,row:3})            → "\x1b[<64;5;3M"
+encodeWheelReport("up",   {col:5,row:3,alt:true})   → "\x1b[<64;5;3M"   ❌ alt 被忽略（应为 72）
+encodeWheelReport("down", {col:5,row:3,alt:true})   → "\x1b[<65;5;3M"   ❌（应为 73）
+```
+
+子会话侧对照：
+
+| 子会话收到的报告 | 结果 |
+| --- | --- |
+| `\x1b[<64;5;3M`（plain） | 1× |
+| `\x1b[<72;5;3M`（Alt+up，**当前永远收不到**） | 5× |
+| `\x1b[<65;5;3M`（plain） | 1× |
+| `\x1b[<73;5;3M`（Alt+down，**当前永远收不到**） | 5× |
+
+## 4. 修复
+
+把覆盖层的 `alt` 透传进编码器，置 SGR bit 3：
+
+`src/core/pty-scroll.mjs`：
+
+```js
+export function encodeWheelReport(direction, { col, row, alt = false } = {}) {
+	const base = direction === "up" ? 64 : 65;
+	const button = alt === true ? base + 8 : base;
+	const cell = (v) => (Number.isFinite(v) ? Math.max(1, Math.floor(v)) : 1);
+	return `\x1b[<${button};${cell(col)};${cell(row)}M`;
+}
+```
+
+`src/ui/pty-attach.ts` `forwardWheelToChild`：在参数对象里补 `alt: event.alt === true`。
+
+## 5. 边界与风险
+
+| 风险 | 说明 / 缓解 |
+| --- | --- |
+| 影响本地滚动 | 不影响：本地路径用 `wheelDelta`（外层 pi 已加速的值），不经 `encodeWheelReport` |
+| 影响 legacy regular-mode 路径 | 不影响：该路径（`handleMouseInputChunk`，`src/ui/pty-attach.ts:1110`）把原始 SGR `raw` **原样**转发，从不重建报告，因此天然保留 alt 位，本次不动它 |
+| `event.alt` 缺失（老 pi-tui） | `alt = false` 默认值兜底；`=== true` 显式比较，`undefined` 不会误开位 |
+| Alt 被终端吞掉 | 不在本次范围：终端若不发 Alt 位，覆盖层也拿不到；本次只保证"拿到就转发" |
+| shift / ctrl 修饰位 | **非目标**：pi-tui 只消费 Alt 位做加速，转发其他位不会改变行为却扩大改动面；若将来需要，同一参数可扩展 |
+| 与 #170 reply guard 的交互 | 无关：本次只改出站编码，入站分类不动 |
+| 与 #213 的交互 | 无关：`\x1b[<` 开头是 SGR mouse，不命中 `CSI_KEY_SEQUENCE` 也不命中任何 reply head |
+
+## 6. 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+| --- | --- | --- | --- | --- |
+| A1 | Alt+wheel-up 编码为 72 | 自动化（unit） | `test/pty-scroll.test.mjs`：`encodeWheelReport("up", { col: 5, row: 3, alt: true })` | `"\x1b[<72;5;3M"` |
+| A2 | Alt+wheel-down 编码为 73 | 自动化（unit） | 同上 | `"\x1b[<73;5;3M"` |
+| A3 | 无 Alt 时行为不变，且严格比较（`=== true`） | 自动化（unit） | 同上：`alt: false` / 缺省 / `alt: undefined` / **`alt: 1`** / **`alt: "yes"`**（truthy 非布尔） | 全部为 64 / 65，无一置 bit 3 —— 锁死 `event.alt === true` 的严格比较契约 |
+| A4 | 转发链路真的把 `event.alt` 传下去 | 自动化（integration） | `test-support/pty-attach-wheel-fallback-scenario.ts` 增加 `alt: true` 的 wheel 事件，断言 runner 收到 `\x1b[<72;…M` | 收到的报告含 `72`（up）/ `73`（down） |
+| A5 | 本地滚动路径不受影响 | 自动化（integration） | 既有 `pty-attach-wheel` / `pty-attach-frame-overflow` / `pty-attach-alt-wheel` 套件 | 全绿 |
+| A6 | 静态检查 | 自动化（static） | `npm run typecheck` + `npm run pack:dry` | 通过 |
+| U1 | 真实终端 Alt+滚轮 | 用户实测 | 部署前置见 §6.1；attach 一个 fullscreen 子会话，按住 Alt 滚一格 | 子会话滚动 5 行（与 attach 外一致） |
+
+### 6.1 U1 执行时机与部署前置
+
+1. 用 `pi install "$(pwd)"`（`README.md:54`）或 symlink 到 `~/.pi/agent/extensions/agent-board` 加载**当前 checkout**，而不是 `~/.pi/agent/git/...` 缓存
+2. 完整重启 pi，新开一个 attach 会话
+3. 时机：目标套件全绿之后、合并之前
+
+## 7. 可测性拆分设计
+
+- **编码逻辑是纯函数**（`encodeWheelReport`），签名扩展一个可选参数即可单测；无 I/O。
+- **接线在 `forwardWheelToChild`**（薄壳），只多传一个字段；集成测试落在既有的 `pty-attach-wheel-fallback-scenario.ts`（真实 `Socket.prototype.write` 拦截），与 #198/#205 的断言模式一致。
+- **测试边界**：A1–A3 在 `test/pty-scroll.test.mjs`（纯函数）；A4 在 `test/pty-attach-wheel-fallback.test.mjs` + 对应 scenario；A5 复用既有套件；不新增测试文件。
+
+## 8. 非目标
+
+- 不转发 shift / ctrl 修饰位（见 §5）
+- 不改本地滚动路径的任何行为
+- 不改 reply guard / 输入分类

package/package.json

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

package/scripts/release_helper.mjs

@@ -36,6 +36,31 @@ const CONVENTIONAL_RE =
 const VERSION_SQUASH_RE = /^\d+\.\d+\.\d+(?:[-.][\w.]+)?\s*\(#\d+\)$/;
 /** Functional whitelist for verify (CHANGELOG-worthy types). */
 const FUNCTIONAL_TYPES = new Set(["feat", "fix", "refactor", "docs", "perf"]);
+/** A PR ref sitting at the very end of a subject, e.g. the `(#208)` in `... (#208)`. */
+const TRAILING_PR_RE = /\s*\(#(\d+)\)\s*$/;
+
+/**
+ * Strip trailing PR refs from a subject, keeping the rightmost as the PR.
+ *
+ * GitHub merge/squash subjects can carry the number twice (`... (#208) (#208)`),
+ * and the conventional regex above captures only the last one, leaving the
+ * earlier copy inside the message where the renderer appends a ref again
+ * (issue #218). Refs in the middle of a subject (`... (issue #189) (#196)`) are
+ * not tail refs and stay verbatim.
+ * @param {string} subject
+ * @returns {{message: string, pr: number|null}}
+ */
+export function stripTrailingPrRefs(subject) {
+	let text = String(subject ?? "").trim();
+	let pr = null;
+	for (let m = text.match(TRAILING_PR_RE); m; m = text.match(TRAILING_PR_RE)) {
+		// Rightmost ref wins: GitHub appends its own number after any that the
+		// author already wrote, so the first match is the authoritative one.
+		if (pr === null) pr = Number(m[1]);
+		text = text.slice(0, m.index).trimEnd();
+	}
+	return { message: text, pr };
+}
 
 /**
  * Parse commit subject lines into changelog entries.
@@ -51,12 +76,14 @@ export function parseCommitLines(lines) {
 		if (VERSION_SQUASH_RE.test(s)) continue;
 		if (/bump\s+version/i.test(s)) continue;
 		if (s.startsWith("Merge ")) continue;
-		const m = s.match(CONVENTIONAL_RE);
-		const prTail = s.match(/\(#(\d+)\)\s*$/);
+		const { message: normalized, pr: tailPr } = stripTrailingPrRefs(s);
+		const m = normalized.match(CONVENTIONAL_RE);
 		const entry = m
-			? { type: m[1], scope: m[2] || "", message: m[3].trim(), pr: m[4] ? Number(m[4]) : null }
-			: { type: "other", scope: "", message: s, pr: prTail ? Number(prTail[1]) : null };
-		const key = `${entry.type}|${entry.scope}|${entry.message}`;
+			? { type: m[1], scope: m[2] || "", message: m[3].trim(), pr: tailPr ?? (m[4] ? Number(m[4]) : null) }
+			: { type: "other", scope: "", message: normalized, pr: tailPr };
+		// PR-aware key: two commits with the same text merged under different
+		// PRs must both keep their number (issue #218).
+		const key = `${entry.type}|${entry.scope}|${entry.message}|${entry.pr ?? ""}`;
 		if (seen.has(key)) continue;
 		seen.add(key);
 		entries.push(entry);
@@ -83,8 +110,13 @@ export function generateChangelog({ version, date, entries, prevTag = null }) {
 		lines.push(`### ${title}`, "");
 		for (const e of group) {
 			const scope = e.scope ? `**${e.scope}**: ` : "";
-			const pr = e.pr ? ` (#${e.pr})` : "";
-			lines.push(`- ${scope}${e.message}${pr}`);
+			// Render defensively: an entry handed in with the ref already in its
+			// message (parse-time normalization missed, hand-authored fixtures)
+			// must still emit the number exactly once (issue #218).
+			const { message, pr: embeddedPr } = stripTrailingPrRefs(e.message);
+			const prNumber = e.pr ?? embeddedPr;
+			const pr = prNumber ? ` (#${prNumber})` : "";
+			lines.push(`- ${scope}${message}${pr}`);
 		}
 		lines.push("");
 	}

package/src/core/pty-scroll.mjs

@@ -9,17 +9,6 @@ export const MIN_WHEEL_LINES = 1;
 /** Upper bound for $AGENT_BOARD_WHEEL_LINES. */
 export const MAX_WHEEL_LINES = 50;
 
-/**
- * Resolve how many lines a single mouse-wheel event scrolls in the attach viewport.
- *
- * Reads `AGENT_BOARD_WHEEL_LINES`, clamps it to `[MIN_WHEEL_LINES, MAX_WHEEL_LINES]`,
- * and falls back to `DEFAULT_WHEEL_LINES` when unset, empty, or non-numeric. macOS
- * inertial/momentum scrolling fires a *burst* of wheel events per gesture, so a small
- * value here already scrolls quickly; the previous fixed `5` overshot badly.
- *
- * @param {Record<string, string|undefined>} [env]
- * @returns {number}
- */
 /**
  * Issue #207: the full-screen mouse enable sequence to re-assert, matching pi-tui's own
  * choice. Multiplexers get button-motion only (1000/1002/1004/1006) because any-motion
@@ -43,6 +32,18 @@ export function fullscreenMouseEnableSequence(env = process.env) {
 		: "\x1b[?1000h\x1b[?1002h\x1b[?1003h\x1b[?1004h\x1b[?1006h";
 }
 
+/**
+ * Resolve how many lines a single mouse-wheel event scrolls in the attach viewport.
+ *
+ * Reads `AGENT_BOARD_WHEEL_LINES`, clamps it to `[MIN_WHEEL_LINES, MAX_WHEEL_LINES]`,
+ * and falls back to `DEFAULT_WHEEL_LINES` when unset, empty, or non-numeric. macOS
+ * inertial/momentum scrolling fires a *burst* of wheel events per gesture, so a small
+ * value here already scrolls quickly; the previous fixed `5` overshot badly.
+ *
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {number}
+ */
+
 export function resolveWheelLines(env = process.env) {
 	const raw = String(env.AGENT_BOARD_WHEEL_LINES ?? "").trim();
 	if (!raw) return DEFAULT_WHEEL_LINES;
@@ -362,12 +363,18 @@ export function resolveAttachWheelRoute({ bufferType, wheelLinesUp, mouseEnabled
  * event: the child applies its own wheel acceleration, exactly as it would for
  * a real terminal.
  *
+ * `alt` sets SGR bit 3 (value 8) so the child keeps its Alt+wheel accelerator.
+ *
  * @param {"up"|"down"} direction
- * @param {{col?: number, row?: number}} coords
+ * @param {{col?: number, row?: number, alt?: boolean}} coords
  * @returns {string}
  */
-export function encodeWheelReport(direction, { col, row } = {}) {
-	const button = direction === "up" ? 64 : 65;
+export function encodeWheelReport(direction, { col, row, alt = false } = {}) {
+	const base = direction === "up" ? 64 : 65;
+	// Issue #214: SGR bit 3 (value 8) is Alt. pi-tui multiplies by 5 when it is set,
+	// so the forward hop must carry it. Strict comparison: a truthy non-boolean must
+	// not flip the bit.
+	const button = alt === true ? base + 8 : base;
 	const cell = (v) => (Number.isFinite(v) ? Math.max(1, Math.floor(v)) : 1);
 	return `\x1b[<${button};${cell(col)};${cell(row)}M`;
 }

package/src/core/terminal-reply-guard.mjs

@@ -17,6 +17,12 @@
  * DA/kitty reply is meaningless to it, and forwarding kitty flags would retune
  * the shared real-terminal keyboard stack).
  *
+ * Issue #213: `\x1b[6;` is not proof of a reply — kitty's functional-key encoding puts
+ * PageDown at `CSI 6;<mods>u` (and modifyOtherKeys at `\x1b[6;<mods>~`). The rule is
+ * therefore key-first: a complete CSI key sequence (`u`/`~` terminated) beats the head
+ * prefixes, so the head list is a heuristic rather than an invariant.
+ * Fragments without a terminator still arm.
+ *
  * Pure only: no I/O, no timers, no `process.env`, no pi-tui import. Time is
  * injected by the caller (see `armReplyGuardTimer` in src/ui/pty-attach.ts).
  *
@@ -67,10 +73,11 @@ const FORWARD_SHAPES = [
 	{ family: "osc-color", pattern: /^\x1b\](?:4;[0-9]+|10|11|12);[\s\S]*(?:\x07|\x1b\\)$/ },
 ];
 
-// Prefixes that can only start a reply and can never be a key/mouse/paste
-// encoding — only these arm an absorption window. Deliberately absent: bare
-// `\x1b`, `\x1b[`, `\x1b[5`/`\x1b[6` (PageUp/PageDown heads), `\x1b[<` (SGR
-// mouse), `\x1bO` (SS3).
+// Prefixes that arm an absorption window for a possibly-fragmented reply. These are
+// heuristics, not proofs: `\x1b[6;` also prefixes kitty's PageDown (`CSI 6;<mods>u`,
+// see CSI_KEY_SEQUENCE) and modifyOtherKeys' `\x1b[6;<mods>~`, which is why a COMPLETE
+// CSI key is classified before this list is consulted. Bare `\x1b`, `\x1b[`, `\x1b[<`
+// (SGR mouse) and `\x1bO` (SS3) are deliberately absent.
 const REPLY_HEADS = [
 	{ family: "device-attributes", prefix: "\x1b[?" },
 	{ family: "device-attributes", prefix: "\x1b[>" },
@@ -80,6 +87,19 @@ const REPLY_HEADS = [
 	{ family: "osc-color", prefix: "\x1b]4" },
 ];
 
+// Issue #213: kitty keyboard protocol keys that carry a modifier use the legacy
+// functional-key encoding `CSI <num>;<mods>u`, and PageDown's legacy number IS 6
+// (`\x1b[6;1u` = no modifier, the mods field is bitmask+1). modifyOtherKeys uses the
+// same prefix with `~` (`\x1b[6;5~`). Both therefore share the cell-size head prefix
+// (`\x1b[6;`), which used to arm the guard and swallow the key — asymmetric with
+// PageUp (key number 5) and invisible to the previous tests.
+//
+// A COMPLETE CSI key is user input, never a reply fragment: check it before the head
+// prefixes. Only the terminator decides — genuine cell-size fragments (`\x1b[6;`,
+// `\x1b[6;24`) carry no `u`/`~` and still arm below. `(?:[;:]\d+)*` also covers the
+// alternate-key form (`\x1b[6;1:2;65u`), which a narrower `(?:;\d+)?(?::\d+)?` misses.
+const CSI_KEY_SEQUENCE = /^\x1b\[\d+(?:[;:]\d+)*[u~]$/;
+
 /**
  * Classify one inbound input event. Complete reply shapes win over head
  * prefixes (a complete kitty reply also starts with `\x1b[?`); escape-led
@@ -93,6 +113,8 @@ export function classifyReplyEvent(data) {
 	for (const shape of FORWARD_SHAPES) {
 		if (shape.pattern.test(data)) return { kind: "reply-complete", family: shape.family, action: "forward" };
 	}
+	// Issue #213: a complete CSI key wins over the head prefixes (see CSI_KEY_SEQUENCE).
+	if (CSI_KEY_SEQUENCE.test(data)) return { kind: "other" };
 	for (const head of REPLY_HEADS) {
 		if (data.startsWith(head.prefix)) return { kind: "reply-head", family: head.family };
 	}

package/src/ui/pty-attach.ts

@@ -1480,6 +1480,9 @@ export class PtyAttachComponent implements Component {
 			data: encodeWheelReport(linesUp > 0 ? "up" : "down", {
 				col: clampInt(event.x + 1, 1, this.cols),
 				row: clampInt(event.y, 1, Math.max(1, this.bodyHeight())),
+				// Issue #214: the overlay already received the Alt bit from pi-tui; carry it
+				// into the synthesized report so the child keeps its 5x wheel accelerator.
+				alt: event.alt === true,
 			}),
 		});
 	}
@@ -1537,7 +1540,7 @@ export class PtyAttachComponent implements Component {
 		return Math.max(0, bottom - height);
 	}
 
-		/** Issue #205: lowest buffer line the local viewport may scroll to — the bottom
+	/** Issue #205: lowest buffer line the local viewport may scroll to — the bottom
 	 * minus the rows the runner vouched for as real scrollback. */
 	private scrollFloorStart(height: number): number {
 		const bottom = this.bottomViewportTop(height);