@huseynsnmz/pi-board 0.15.3 → 0.17.0

package/docs/superpowers/plans/2026-10-26-issue-245-key-hints-doc-sync.md

@@ -1,244 +0,0 @@
-# Key-Hint Doc Sync 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:** Sync three stale key hints with the bindings already implemented in `src/ui/dashboard.ts` (issue #245): the peek footer's key list, the README Peek/Transcript tables' missing `!`, and the README's undocumented multi-select keys.
-
-**Architecture:** One string literal in `renderPeek` plus three README edits; one render assertion added to the existing `test-support/vim-keys-wrap.ts` probe so the peek footer cannot drift again. No handler logic, no new files, no new test infrastructure.
-
-**Tech Stack:** TypeScript (runtime), `node --test` + `--experimental-transform-types` probe (test), Markdown (docs).
-
-**Spec:** `docs/superpowers/specs/2026-10-26-issue-245-key-hints-doc-sync-design.md` (decisions D1–D5; spec §6 option **A** — multi-select gets its own 9-row table — confirmed by the user)
-
-## Global Constraints
-
-- Tabs for indentation in `.ts`; English comments and commit messages.
-- **Do not touch any handler logic** (spec D5): no changes to `handleListKey` / `handleSelectKey` / `handlePeekKey` / `handleSessionKey` / `handleEvidenceKey`.
-- **Do not touch the `?` help overlay or the NORMAL/SELECT hint lines** — they are already correct (spec D5).
-- The multi-select table is **exactly 9 rows**, one per `handleSelectKey` binding, including `?` and `!` (spec D3, hardened by cross-review R1-D1).
-- Do **not** add a `!` row to the Evidence table: `handleEvidenceKey` has no `!` binding (spec §7).
-- `npm run verify` must pass before the PR (AGENTS.md).
-- Worktree discipline: every path under `/home/elling/work/git-repo/pi-agent-board/.pi/worktrees/issue-245-key-hints-doc-sync` (= `$WT`); git via `git -C $WT`. Branch `issue-245-key-hints-doc-sync`, commit subjects end with `(issue #245)` **and** the PR-number suffix `(#N)` once known.
-
-## Review Focus
-
-These are the conditions the spec implies but no task's tests can cover; each is pinned in the task noted.
-
-1. **Peek footer is the last line of `renderPeek`, and `fitToHeight` slices the tail** (`src/ui/dashboard.ts:1280`). A tall peek body silently truncates the footer, making the new assertion fail for the wrong reason. Pinned by the `rows` bump in Task 1, Step 1 (cross-review R1-D3).
-2. **The multi-select table count** — 9 rows, not 7. Dropping `?`/`!` re-creates the very debt this issue fixes. Pinned by Task 2, Step 3's `rg` count check (cross-review R1-D1).
-3. **The Evidence table must still have no `!` row.** Pinned by Task 2, Step 3's negative check.
-4. **`README.md:120`'s prose must not duplicate the new table's content** — it should point at the table instead. Pinned by Task 2, Step 4 (manual read).
-
----
-
-### Task 1: Peek footer copy + render assertion
-
-**Files:**
-- Modify: `src/ui/dashboard.ts` (`renderPeek` footer, currently line 1543 — locate by the string `↑↓ prev/next · →/> attach`)
-- Modify: `test-support/vim-keys-wrap.ts` (`out.copy` block, currently lines ~119-140)
-- Modify: `test/dashboard-vim-keys.test.mjs` (A7 test, currently lines 38-63)
-
-**Interfaces:**
-- Consumes: existing `renderPeek(width)` and the probe's white-box `dash.mode` / `dash.peekId` / `dash.selectedId` handles (already used at `vim-keys-wrap.ts:100-110`).
-- Produces: probe field `out.copy.peekRender` (string) that Task 3's verification relies on indirectly.
-
-**Spec acceptance IDs:** A1, A2, A3, A4 (+ Review Focus 1).
-
-- [ ] **Step 1: Add the failing assertion and the probe capture**
-
-In `test-support/vim-keys-wrap.ts`, inside the `out.copy` block, after the `evidenceRender` capture and before `dash.mode = "list";`, add:
-
-```ts
-// Peek footer: raise the height first — fitToHeight slices the tail, and the
-// footer is renderPeek's last line (cross-review R1-D3).
-tui.terminal.rows = 40;
-dash.mode = "peek"; dash.peekId = ids[0]; dash.selectedId = ids[0];
-const peekRender = dash.render(120).join("\n");
-tui.terminal.rows = 24;
-```
-
-and extend the `out.copy` initializer on the following line to include `peekRender`:
-
-```ts
-out.copy = { help120, listRender, selectRender, sessionRender, evidenceRender, peekRender, help80Lines: help80.length };
-```
-
-In `test/dashboard-vim-keys.test.mjs`, in the A7 test: add `peekRender` to the destructuring line, and append before the closing `});`:
-
-```js
-	// #245 A1/A3: the peek footer advertises j/k and l, and the old wording is gone.
-	assert.match(peekRender, /↑↓\/j\/k prev\/next/);
-	assert.match(peekRender, /→\/l attach/);
-	assert.doesNotMatch(peekRender, /↑↓ prev\/next · →\/> attach/);
-```
-
-- [ ] **Step 2: Run the test to verify it fails**
-
-Run: `cd $WT && node --test test/dashboard-vim-keys.test.mjs`
-Expected: FAIL — `/↑↓\/j\/k prev\/next/` does not match, because the footer still reads `↑↓ prev/next`.
-
-- [ ] **Step 3: Change the footer copy**
-
-In `src/ui/dashboard.ts`, `renderPeek`'s else-branch (currently line 1543), replace:
-
-```ts
-			out.push(clip(t.fg("dim", "↑↓ prev/next · →/> attach · d done · v transcript · e evidence · r reply · esc back"), width));
-```
-
-with:
-
-```ts
-			out.push(clip(t.fg("dim", "↑↓/j/k prev/next · →/l attach · d done · v transcript · e evidence · r reply · esc back"), width));
-```
-
-(Matches the `↑↓/j/k … · →/l …` house style that #237 established for the session/evidence footers at `:1565` / `:1600`.)
-
-- [ ] **Step 4: Run the test to verify it passes**
-
-Run: `cd $WT && node --test test/dashboard-vim-keys.test.mjs`
-Expected: PASS — both tests, including the three new assertions.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git -C $WT add src/ui/dashboard.ts test-support/vim-keys-wrap.ts test/dashboard-vim-keys.test.mjs
-git -C $WT commit -m "docs(ui): advertise j/k and l in the peek footer (issue #245)"
-```
-
----
-
-### Task 2: README — `!` rows and the multi-select table
-
-**Files:**
-- Modify: `README.md` (multi-select prose `:120`; Peek table `:152-167`; Transcript table `:169-183`; new `### Multi-select` section after the Main list table)
-
-**Interfaces:**
-- Consumes: Task 1's copy as the source of truth for the peek footer wording (the README Peek table must not contradict it).
-- Produces: the documentation surface Task 3's U1 checklist walks.
-
-**Spec acceptance IDs:** U1 (the `!` rows + 9-row table), Review Focus 2, 3, 4.
-
-- [ ] **Step 1: Add `!` to the Peek table**
-
-In `README.md`'s Peek table, insert after the `h` row and before the `Up` / `Down` / `j` / `k` row:
-
-```markdown
-| `!` | Open node-pty diagnostics and repair hints. |
-```
-
-- [ ] **Step 2: Add `!` to the Transcript table**
-
-In the Transcript table, insert after the `h` row and before the `Left` / `Esc` / `<` row:
-
-```markdown
-| `!` | Open node-pty diagnostics and repair hints. |
-```
-
-(Wording is copied verbatim from the Main list table's `!` row so the same feature reads the same everywhere.)
-
-- [ ] **Step 3: Add the `### Multi-select` section**
-
-Insert this section immediately after the Main list table and before `### Peek`:
-
-```markdown
-### Multi-select
-
-Press `m` in the main list to act on several sessions at once.
-
-| Key | Action |
-| --- | --- |
-| `Up` / `Down` / `j` / `k` | Move the selection. |
-| `Space` | Toggle the current row. |
-| `a` | Select all visible rows. |
-| `u` | Clear the selection. |
-| `d` | Confirm marking the selected inactive rows Done. |
-| `Ctrl+X` | Delete the selected Done rows (confirmation prompt). |
-| `m` / `Esc` / `Ctrl+C` | Leave multi-select mode. |
-| `?` | Open the help overlay. |
-| `!` | Open node-pty diagnostics and repair hints. |
-```
-
-- [ ] **Step 4: Point the prose at the new table instead of duplicating it**
-
-Replace the existing `README.md:120` line:
-
-```markdown
-- `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.
-```
-
-with:
-
-```markdown
-- `m` enters multi-select mode; see [Multi-select](#multi-select) for its keys.
-```
-
-- [ ] **Step 5: Verify the tables by counting, not by eye**
-
-Run each check and confirm the stated output:
-
-```bash
-cd $WT
-# 9 rows in the multi-select table (excluding header + separator)
-sed -n '/^### Multi-select/,/^### Peek/p' README.md | grep -c '^| `'
-# expect: 9
-# `!` documented four times: main list, multi-select, peek, transcript — and NOT in evidence
-grep -c '^| `!`' README.md
-# expect: 4
-sed -n '/^### Evidence/,/^### PTY attach/p' README.md | grep -c '^| `!`'
-# expect: 0
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git -C $WT add README.md
-git -C $WT commit -m "docs: document ! and multi-select keys in the README (issue #245)"
-```
-
----
-
-### Task 3: Full gate + manual verification checklist
-
-**Files:** none modified — this task runs the gate and records results.
-
-**Interfaces:**
-- Consumes: Tasks 1–2.
-- Produces: the A5 evidence and the U1/U2 record posted to issue #245.
-
-**Spec acceptance IDs:** A5, U1, U2.
-
-- [ ] **Step 1: Run the full verification gate**
-
-Run: `cd $WT && npm run verify`
-Expected: PASS — typecheck, perf gate, all tests (currently 1404: 1401 pass / 3 opt-in skips), coverage thresholds (lines 85 / funcs 80 / branches 70), `pack:dry`.
-
-- [ ] **Step 2: Re-read the diff for the spec's non-goals**
-
-Run: `cd $WT && git diff --stat main...HEAD && git diff main...HEAD -- src/ui/dashboard.ts`
-Expected: `src/ui/dashboard.ts` shows **exactly one changed line** (the peek footer). If any handler, the help overlay, or the NORMAL/SELECT hint lines appear in the diff, revert that hunk — it violates spec D5.
-
-- [ ] **Step 3: U1 — walk the README against the live dashboard (after merge)**
-
-Deploy prelude (spec R1-D2): merge the PR, `git pull` on the main checkout, restart pi (the local checkout loads via auto-discovery, README "Development auto-discovery"), then `pi /agent-board`. Note: the `!` bindings themselves already ship in v0.13.0, so steps ① and ② can be sanity-checked on an older install — only the README text must be the merged version.
-
-① Open Peek, press `!`, confirm the node-pty diagnostics view opens.
-② Open the transcript (`v`), press `!`, same.
-③ Enter multi-select (`m`) and walk all 9 rows of the new table: movement (`↑`/`↓`/`j`/`k`), `Space` toggle, `a`, `u`, `d`, `Ctrl+X`, `m`/`Esc`/`Ctrl+C` exit, `?`, `!`.
-
-- [ ] **Step 4: U2 — the peek footer on screen (after merge)**
-
-`space` to open Peek; read the footer.
-Expected: `↑↓/j/k prev/next · →/l attach · d done · v transcript · e evidence · r reply · esc back`.
-
-- [ ] **Step 5: Record results on issue #245**
-
-Post the A5 command + result, then the U1/U2 observations. If any U item cannot run yet, mark it `pending` — do not claim full acceptance.
-
----
-
-## Self-Review Notes
-
-- **Spec coverage:** D1 → Task 1; D2 → Task 2 Steps 1-2; D3 → Task 2 Steps 3-4 (option A, 9 rows); D4 → Task 1 Step 1; D5 → Task 3 Step 2's revert check. A1/A3 → Task 1; A2 → Task 1 Steps 2/4; A4 → Task 3 Step 1; A5 → Task 3 Step 1; U1/U2 → Task 3 Steps 3-5. Every acceptance ID has an owning task; no task lacks an ID.
-- **Placeholder scan:** none — every step carries the literal text to write or the exact command with its expected output.
-- **Type consistency:** `peekRender` is named identically in the probe (`out.copy.peekRender`), the test destructuring, and the assertions.
-- **Unresolved spec item:** §6 asked A vs B; the user chose **A**, recorded in `authorization.md` (`Scope: design-approved (D3 = option A…)`). The plan implements A only.

package/docs/superpowers/plans/2026-10-27-issue-172-fullscreen-selection-clear.md

@@ -1,344 +0,0 @@
-# Fullscreen selection highlight clear — 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:** In the fullscreen attach view, drop pi-tui's text selection as soon as copy-on-release has run, so the inverse-video highlight does not outlive the copy (issue #172).
-
-**Architecture:** Reuse the existing #174 deferred hook (`handleMouse` → `process.nextTick` after a left `release`/`click`) to read pi's final selection, mirror it into X11 PRIMARY as today, then clear pi's selection via a feature-detected private method and request one repaint. The predicate that schedules the hook becomes env-free; the kill switch stays where it already lives (`writePrimarySelection`). The clear is gated on `getCopyOnSelect() !== false` so users who disabled copy-on-select keep their selection for `Ctrl+X`.
-
-**Tech Stack:** TypeScript component (`src/ui/pty-attach.ts`), a pure decision predicate in `src/core/pty-scroll.mjs`, `node:test` unit tests, a component-level scenario harness with a fake fullscreen TUI and a PATH-stubbed `xclip`.
-
-## Global Constraints
-
-- Spec: `docs/superpowers/specs/2026-10-27-issue-172-fullscreen-selection-clear-design.md` (v3).
-- `clearTextSelection()` is private in pi-tui's typings → always feature-detect; degrade, never throw.
-- `resetTextSelection()` must not be used (it clears `lastClick` and would break double-click word / triple-click line selection).
-- Regular/legacy mode is out of scope (issue #250); do not touch `handleLocalMouseEvent`.
-- Tabs for indentation, English comments, conventional commit subjects, no `git add -A`.
-
----
-
-### Task 1: Replace the mirror predicate with an env-free selection-end predicate
-
-**Files:**
-- Modify: `src/core/pty-scroll.mjs:271-282`
-- Test: `test/pty-scroll.test.mjs:20`, `test/pty-scroll.test.mjs:244-262`
-
-**Interfaces:**
-- Produces: `isFullscreenSelectionEnd(event) → boolean` (exported from `src/core/pty-scroll.mjs`).
-- Removes: `shouldMirrorSelectionToPrimary(event, { nativePasteEnabled })`.
-
-- [ ] **Step 1: Update the unit test first**
-
-In `test/pty-scroll.test.mjs` replace the import name and the test block:
-
-```js
-test("isFullscreenSelectionEnd: only the left button's release/click ends a fullscreen selection", () => {
-	assert.equal(isFullscreenSelectionEnd(ev("release", "left")), true);
-	assert.equal(isFullscreenSelectionEnd(ev("click", "left")), true);
-	const cases = [
-		["press", "left"],
-		["move", "left"],
-		["drag", "left"],
-		["wheel", "left"],
-		["release", "middle"],
-		["release", "right"],
-		["release", "none"],
-		["click", "middle"],
-		["click", "none"],
-		["press", "middle"],
-	];
-	for (const [type, button] of cases) {
-		assert.equal(isFullscreenSelectionEnd(ev(type, button)), false, `${type}/${button}`);
-	}
-});
-```
-
-- [ ] **Step 2: Run the test to verify it fails**
-
-Run: `node --test test/pty-scroll.test.mjs`
-Expected: FAIL — `isFullscreenSelectionEnd is not a function`.
-
-- [ ] **Step 3: Replace the helper**
-
-```js
-/**
- * Issue #174 (B2) / #172: whether a normalized mouse event ends a fullscreen text
- * selection gesture the attach overlay must settle — mirror the selection into X11
- * PRIMARY (#174) and drop pi's highlight once copy-on-select has run (#172). Only
- * release/click of the left button ends a selection in TuiAltScreen; pi owns the
- * gesture, so the overlay observes without consuming. Pure: the native-paste kill
- * switch is applied by writePrimarySelection, not here.
- */
-export function isFullscreenSelectionEnd(event) {
-	return (event.type === "release" || event.type === "click") && event.button === "left";
-}
-```
-
-- [ ] **Step 4: Run the test to verify it passes**
-
-Run: `node --test test/pty-scroll.test.mjs`
-Expected: PASS (all cases, no import errors).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/core/pty-scroll.mjs test/pty-scroll.test.mjs
-git commit -m "refactor(attach): selection-end predicate for fullscreen settle (issue #172)"
-```
-
----
-
-### Task 2: Clear pi's selection in the deferred settle hook
-
-**Files:**
-- Modify: `src/ui/pty-attach.ts:17` (import), `:521-530` (schedule branch), `:1376-1381` (settle method)
-- Test: `test-support/pty-attach-selection-mirror-scenario.ts`, `test/pty-attach-selection-mirror.test.mjs`
-
-**Interfaces:**
-- Consumes: `isFullscreenSelectionEnd(event)` from Task 1.
-- Produces: `private settleFullscreenSelection(nativePasteEnabled: boolean): void`; type `FullscreenSelectionHost`.
-
-- [ ] **Step 1: Extend the scenario with clear hooks and cases**
-
-In `test-support/pty-attach-selection-mirror-scenario.ts`:
-
-1. Add module-level knobs next to `selectionText`:
-
-```ts
-let copyOnSelect = true;
-let clearAvailable = true;
-let clearCalls = 0;
-```
-
-2. Give the fake TUI the two new members (the conditional spread must be inside the object literal):
-
-```ts
-	const tui = {
-		mode: "fullscreen",
-		getActiveSelectionText: () => selectionText,
-		getCopyOnSelect: () => copyOnSelect,
-		...(clearAvailable
-			? {
-					clearTextSelection: () => {
-						clearCalls += 1;
-						selectionText = undefined; // prove read-before-clear: a wrong order yields no PRIMARY write
-					},
-				}
-			: {}),
-		terminal: { rows: 24, cols: 80, columns: 80, write: () => {} },
-		requestRender: () => {},
-	};
-```
-
-3. Add result fields and one reset helper:
-
-```ts
-	releaseClears: -1,
-	clickClears: -1,
-	emptyClears: -1,
-	killSwitchClears: -1,
-	nonEndingClears: -1,
-	copyOnSelectOffWrites: -1,
-	copyOnSelectOffClears: -1,
-	fallbackError: null as string | null,
-	fallbackWrites: -1,
-```
-
-```ts
-const resetFixture = (text: string | undefined = "mirror-fixture-text") => {
-	selectionText = text;
-	copyOnSelect = true;
-	clearAvailable = true;
-	clearCalls = 0;
-};
-```
-
-4. Call `resetFixture()` at the start of every existing case, and record the clear deltas:
-
-- case 1 (release): `result.releaseClears = clearCalls;`
-- case 2 (click): `result.clickClears = clearCalls;`
-- case 3 (empty): set `resetFixture(undefined)`, then `result.emptyClears = clearCalls;`
-- case 4 (kill switch): `resetFixture()`, then `result.killSwitchClears = clearCalls;`
-- case 5 (press/move): `resetFixture()`, then `result.nonEndingClears = clearCalls;`
-- new case 6 (`copyOnSelect = false`): `resetFixture(); copyOnSelect = false;` handle release; assert writes 1 and clears 0.
-- new case 7 (no `clearTextSelection`): `resetFixture(); clearAvailable = false;` wrap the call in try/catch, capture `fallbackError`, and record `fallbackWrites`.
-
-5. The middle-click paste case stays last and must also call `resetFixture()`.
-
-- [ ] **Step 2: Run the scenario test to verify it fails**
-
-Run: `node --test test/pty-attach-selection-mirror.test.mjs`
-Expected: FAIL on the new assertions (`releaseClears` is 0, because the component never clears yet).
-
-- [ ] **Step 3: Wire the component**
-
-Import (line 17): replace `shouldMirrorSelectionToPrimary` with `isFullscreenSelectionEnd`.
-
-Replace the schedule branch:
-
-```ts
-		const nativePasteEnabled = process.env.AGENT_BOARD_ATTACH_NATIVE_PASTE !== "0";
-		if (isFullscreenSelectionEnd(event)) {
-			// Observe only — pi's fullscreen selection keeps the event. Overlays are
-			// dispatched before TuiAltScreen finalizes (and copies) the selection for
-			// this event, so settling must run deferred (issue #174).
-			process.nextTick(() => this.settleFullscreenSelection(nativePasteEnabled));
-			return undefined;
-		}
-```
-
-Add the structural type near the other top-level types in the file:
-
-```ts
-/** The pi-tui members the attach view reads without a public typing contract:
- * getActiveSelectionText/clearTextSelection are private in TuiAltScreen's d.ts
- * (runtime-reachable), getCopyOnSelect is public. All are feature-detected. */
-interface FullscreenSelectionHost {
-	getActiveSelectionText?: () => string | undefined;
-	getCopyOnSelect?: () => boolean;
-	clearTextSelection?: () => void;
-}
-```
-
-Rename `mirrorFullscreenSelectionToPrimary` to `settleFullscreenSelection` and extend it:
-
-```ts
-	/** Issue #174 (B2) + #172: a selection gesture ended inside this overlay and pi has
-	 * finalized (and copied) its selection. Mirror the text into X11 PRIMARY so
-	 * middle-click paste closes the loop, then drop pi's selection so the inverse-video
-	 * highlight does not outlive the copy. Clearing is skipped when copy-on-select is
-	 * off (the user copies later with pi's Ctrl+X) and when the pi-tui method is absent
-	 * (older/newer runtime) — that degrades to the previous behaviour instead of
-	 * throwing. clearTextSelection preserves pi's multi-click history; resetTextSelection
-	 * would reset lastClick and break double-click word / triple-click line selection. */
-	private settleFullscreenSelection(nativePasteEnabled: boolean): void {
-		if (this.closed) return;
-		const alt = this.tui as FullscreenSelectionHost;
-		const text = alt.getActiveSelectionText?.();
-		if (typeof text !== "string" || text.length === 0) return;
-		if (nativePasteEnabled) this.writePrimarySelection(text);
-		if (alt.getCopyOnSelect?.() === false) return;
-		if (typeof alt.clearTextSelection !== "function") return;
-		alt.clearTextSelection();
-		this.scheduleRender();
-	}
-```
-
-- [ ] **Step 4: Update the test assertions**
-
-In `test/pty-attach-selection-mirror.test.mjs`, keep every existing assertion and add:
-
-```js
-	assert.equal(parsed.releaseClears, 1, "the highlight must be cleared once the copy has run");
-	assert.equal(parsed.clickClears, 1, "a click ending with a live selection clears too");
-	assert.equal(parsed.emptyClears, 0, "an empty selection must not clear");
-	assert.equal(parsed.killSwitchClears, 1, "the highlight clear is not governed by NATIVE_PASTE");
-	assert.equal(parsed.nonEndingClears, 0, "press/move must not clear");
-	assert.equal(parsed.copyOnSelectOffWrites, 1, "the PRIMARY mirror still runs with copy-on-select off");
-	assert.equal(parsed.copyOnSelectOffClears, 0, "copy-on-select off keeps the selection for Ctrl+X");
-	assert.equal(parsed.fallbackError, null, "a missing clearTextSelection must not throw");
-	assert.equal(parsed.fallbackWrites, 1, "the PRIMARY mirror still runs without the clear method");
-```
-
-- [ ] **Step 5: Run the scenario test to verify it passes**
-
-Run: `node --test test/pty-attach-selection-mirror.test.mjs`
-Expected: PASS.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/ui/pty-attach.ts test-support/pty-attach-selection-mirror-scenario.ts test/pty-attach-selection-mirror.test.mjs
-git commit -m "fix(attach): clear the fullscreen selection highlight after copy-on-release (issue #172)"
-```
-
----
-
-### Task 2b: Guard the settle against the next gesture (local CR F1/F3/F4)
-
-**Files:**
-- Modify: `src/ui/pty-attach.ts` (field + `handleMouse` bump + serial check)
-- Test: `test-support/pty-attach-selection-mirror-scenario.ts`, `test/pty-attach-selection-mirror.test.mjs`, `test/pty-scroll.test.mjs`
-
-**Interfaces:**
-- Produces: `private selectionGestureSerial = 0` (bumped on left press).
-
-- [ ] **Step 1: Add the failing scenario case**
-
-```ts
-	// 8. A release and the next left press coalesced into one tick (pi-tui emits batched
-	// reports synchronously): the queued settle must not read/clear the new gesture.
-	await withComponent(undefined, async (c) => {
-		resetFixture();
-		const before = writes().length;
-		(c as any).handleMouse(leftEvent("release"));
-		(c as any).handleMouse({ ...leftEvent("press"), x: 9, screenX: 9 });
-		await sleep(80);
-		result.coalescedWrites = writes().length - before;
-		result.coalescedClears = clearCalls;
-	});
-```
-
-Also pin the deferral in case 1: `result.releaseSyncWrites = writes().length - before;` immediately after `handleMouse` returns.
-
-- [ ] **Step 2: Run the scenario test to verify it fails**
-
-Run: `node --test test/pty-attach-selection-mirror.test.mjs`
-Expected: FAIL — `coalescedWrites` is 1 (the queued settle mirrored the new gesture).
-
-- [ ] **Step 3: Implement the guard**
-
-Field next to `private selection`:
-
-```ts
-private selectionGestureSerial = 0;
-```
-
-In `handleMouse`, before the settle branch:
-
-```ts
-if (event.type === "press" && event.button === "left") this.selectionGestureSerial += 1;
-```
-
-In the settle branch, capture and compare:
-
-```ts
-const serial = this.selectionGestureSerial;
-process.nextTick(() => {
-	if (serial !== this.selectionGestureSerial) return;
-	this.settleFullscreenSelection(nativePasteEnabled);
-});
-```
-
-- [ ] **Step 4: Complete the predicate table (F4) and fix the import order (F5)**
-
-Add `["click", "right"]` to the false-cases list in `test/pty-scroll.test.mjs` and move `isFullscreenSelectionEnd` into alphabetical position.
-
-- [ ] **Step 5: Run the tests to verify they pass**
-
-Run: `node --test test/pty-scroll.test.mjs test/pty-attach-selection-mirror.test.mjs`
-Expected: PASS (35 tests).
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/ui/pty-attach.ts test-support/pty-attach-selection-mirror-scenario.ts test/pty-attach-selection-mirror.test.mjs test/pty-scroll.test.mjs
-git commit -m "fix(attach): keep a queued settle from consuming the next gesture (issue #172)"
-```
-
----
-
-### Task 3: Full verification
-
-**Files:** none.
-
-- [ ] **Step 1: Run the repository gate**
-
-Run: `npm run verify`
-Expected: typecheck, perf gate, tests, coverage thresholds, pack:dry all pass.
-
-- [ ] **Step 2: Confirm no scope drift**
-
-Run: `git diff --stat origin/main`
-Expected: only the spec, the plan, `src/ui/pty-attach.ts`, `src/core/pty-scroll.mjs`, `test/pty-scroll.test.mjs`, `test-support/pty-attach-selection-mirror-scenario.ts`, `test/pty-attach-selection-mirror.test.mjs`. `handleLocalMouseEvent` and `test-support/pty-attach-legacy-drag-scenario.ts` untouched.