@huseynsnmz/pi-board 0.15.3 → 0.16.0

package/docs/superpowers/plans/2026-10-23-issue-229-vim-jkl.md

@@ -1,449 +0,0 @@
-# Vim-style j/k/l Board Keys 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:** Bind `j`/`k` navigation and `l` attach in the board's list/select/peek/evidence modes so vim users' muscle memory works, without touching text-input modes or the `h` = Hold contract (issue #229).
-
-**Architecture:** Pure additive key branches in the five per-mode handlers of `src/ui/dashboard.ts`, reusing the exact code paths of the arrow keys (`moveSelection`, `peekStep`, `attachSelected`, `attachPeek`); copy sync in the `?` help overlay, the NORMAL/SELECT hint lines, and the four README view tables. Behavior is verified by a `test-support` probe driving the public `handleInput()` with fake service/done injection.
-
-**Tech Stack:** TypeScript (runtime), `node --test` + `--experimental-transform-types` probes (test).
-
-**Spec:** `docs/superpowers/specs/2026-10-23-issue-229-vim-jkl-design.md` (acceptance IDs A1–A9, U1–U2 referenced below)
-
-## Global Constraints
-
-- Tabs for indentation; English comments and commit messages (AGENTS.md).
-- Tests use `node:test` with `assert/strict`; probes run via `node --experimental-transform-types` and live in `test-support/` (excluded from tsconfig).
-- Conventional commit subjects `feat`/`fix`/`...` with `(issue #229)` reference; PR number appended at merge time.
-- `npm run verify` (typecheck + perf gate + tests + coverage thresholds lines 85 / funcs 80 / branches 70 + pack:dry) must pass before the PR.
-- `j`/`k` inherit **wrap-around** semantics via `moveSelection`/`peekStep` — do NOT implement clamp (spec D2).
-- `h` = Hold (PR #151 contract), dispatch/filter/rename/reply stay literal — off-limits (spec D4/D6).
-- Worktree discipline: all edits under `/home/elling/work/git-repo/pi-agent-board/.pi/worktrees/issue-229-vim-jkl-board-list` (= `$WT`), git via `git -C $WT`.
-
-## Review Focus
-
-1. **Uppercase `J`/`K`/`L` stay unbound** — list mode still shows the printable fallback toast for them. Expected: unchanged current behavior, pinned by a probe assertion (Task 1, Step 1).
-2. **`l` on a busy row** (`hostActive=false && agentBusy=true`) must take the same `confirm-stop-first` branch as `→`, not attach directly. Pinned by the `busyL` probe segment (Task 1, Step 1).
-3. **Help rows got longer** — at 80 cols `renderCenteredBox` clips (existing fallback, `dashboard.ts:1846`); full wording must be visible at 120 cols. Pinned by the render assertions (Task 2, Step 1).
-4. **`j`/`k` in select mode trigger `prewarmScheduler.schedule()`** — inherited `moveSelection` side effect, select is in the `prewarmSelected` allow-list, no behavior change. No test; reviewers confirm no new coupling.
-5. **Bracketed paste containing `j`/`k`/`l` must not move the selection** (multi-byte paste string never equals a single-byte key). Pinned by the paste segment (Task 1, Step 1).
-
----
-
-### Task 1: Key bindings in the five mode handlers
-
-**Files:**
-- Create: `test-support/vim-keys-wrap.ts`
-- Create: `test/dashboard-vim-keys.test.mjs`
-- Modify: `src/ui/dashboard.ts` (handleListKey :359, handleSelectKey :400, handlePeekKey :427, handleEvidenceKey :484 — line refs are main @ 759d659)
-
-**Interfaces:**
-- Consumes: existing `moveSelection(delta)`, `peekStep(delta)`, `attachSelected()`, `attachPeek()`, `planDashboardAttach` (src/ui/dashboard-decisions.mjs:34).
-- Produces: no new symbols; later tasks rely on the probe's `out.copy` field added in Task 2.
-
-**Spec acceptance IDs:** A1, A2, A3, A4, A5, A6, A9 (+ Review Focus 1, 2, 5). Spec D3 dead-code cleanup folded in (Step 4).
-
-- [ ] **Step 1: Write the failing probe and test**
-
-Create `test-support/vim-keys-wrap.ts`:
-
-```ts
-// Vim-keys probe: drive j/k/l through the public handleInput() across modes
-// and report observations as JSON (issue #229, spec A1-A9 + review-focus pins).
-// Run via `node --experimental-transform-types`. Not typechecked.
-import { mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { createService } from "../src/runtime/service.mjs";
-import { createView } from "../src/core/store.mjs";
-import { DashboardComponent } from "../src/ui/dashboard.ts";
-
-const root = mkdtempSync(join(tmpdir(), "agentview-vim-keys-"));
-createView(root, { id: "v1", name: "one", cwd: root });
-createView(root, { id: "v2", name: "two", cwd: root });
-createView(root, { id: "v3", name: "three", cwd: root });
-
-const service = createService({
-	root,
-	runnerScript: "/no/runner.mjs",
-	piCommand: "pi",
-	piArgsPrefix: [],
-	defaultCwd: root,
-	launch: () => ({ pid: null, configPath: "/no/config.json" }),
-	launchHost: () => ({ pid: null, configPath: "/no/host-config.json" }),
-	launchTitle: () => ({ pid: null, configPath: "/no/title-config.json" }),
-});
-
-const tui = { terminal: { rows: 24, cols: 80, columns: 80, write: () => {} }, requestRender: () => {} };
-const theme = { fg: (_c, t) => t, bold: (t) => t, bg: (_c, t) => t };
-const doneCalls = [];
-const dash = new DashboardComponent(tui, theme, {}, (r) => doneCalls.push(r), {
-	service, root, defaultCwd: root,
-	availableModels: [], currentModel: null, currentThinkingLevel: "off",
-});
-
-// TS-private is runtime-accessible; read white-box state for assertions.
-const ids = dash.orderedIds;
-const out = { ids, list: [], select: [], peek: [], attach: [], negative: [], scroll: [], text: {}, notices: [], busyL: null };
-
-// A1: list j/k == arrow keys (wrap at both ends); j must not pop the INSERT toast.
-dash.handleInput("j"); out.list.push(dash.selectedId);
-out.notices.push(dash.inputNotice === null);
-dash.handleInput("j"); out.list.push(dash.selectedId);
-dash.handleInput("j"); out.list.push(dash.selectedId); // wrap last -> first
-dash.handleInput("k"); out.list.push(dash.selectedId); // wrap first -> last
-// RF1: uppercase J stays on the printable fallback (current behavior pinned).
-dash.handleInput("J"); out.notices.push(dash.inputNotice !== null);
-// RF5: bracketed paste containing j/k/l must not move the selection.
-dash.handleInput("\x1b[200~jkl\x1b[201~"); out.list.push(dash.selectedId);
-
-// A2: select mode j/k move the selection (wrap).
-dash.mode = "select"; dash.selectedId = ids[0];
-dash.handleInput("j"); out.select.push(dash.selectedId);
-dash.handleInput("k"); out.select.push(dash.selectedId);
-dash.handleInput("k"); out.select.push(dash.selectedId); // wrap first -> last
-
-// A9 negative: select "l" must not attach / leave the mode.
-const doneBeforeSelect = doneCalls.length;
-dash.handleInput("l");
-out.negative.push(["select-l", dash.mode, doneCalls.length - doneBeforeSelect]);
-dash.mode = "list";
-
-// A3: peek j/k == peekStep (wrap).
-dash.mode = "peek"; dash.peekId = ids[0]; dash.selectedId = ids[0];
-dash.handleInput("j"); out.peek.push(dash.peekId);
-dash.handleInput("k"); out.peek.push(dash.peekId);
-dash.handleInput("k"); out.peek.push(dash.peekId); // wrap first -> last
-
-// A4: l attaches in list / peek / evidence (non-busy rows -> direct done).
-dash.mode = "list"; dash.selectedId = ids[0];
-dash.handleInput("l"); out.attach.push(doneCalls.at(-1));
-dash.mode = "peek"; dash.peekId = ids[1]; dash.selectedId = ids[1];
-dash.handleInput("l"); out.attach.push(doneCalls.at(-1));
-dash.mode = "evidence"; dash.selectedId = ids[2];
-dash.handleInput("l"); out.attach.push(doneCalls.at(-1));
-
-// A9 negative: session "l" must not attach / leave the mode.
-dash.mode = "session"; dash.selectedId = ids[0];
-const doneBeforeSession = doneCalls.length;
-dash.handleInput("l");
-out.negative.push(["session-l", dash.mode, doneCalls.length - doneBeforeSession]);
-
-// A6: session / evidence j/k still scroll (regression guard).
-dash.mode = "session";
-dash.handleInput("j"); out.scroll.push(dash.sessionScrollTop);
-dash.handleInput("k"); out.scroll.push(dash.sessionScrollTop);
-dash.mode = "evidence";
-dash.handleInput("j"); out.scroll.push(dash.evidenceScrollTop);
-dash.handleInput("k"); out.scroll.push(dash.evidenceScrollTop);
-
-// A5: text modes keep j/k/l literal.
-for (const m of ["dispatch", "filter", "rename", "reply"]) {
-	dash.mode = m; dash.input = "";
-	dash.handleInput("j"); dash.handleInput("k"); dash.handleInput("l");
-	out.text[m] = dash.input;
-}
-dash.mode = "list"; dash.input = "";
-
-// RF2: busy row + l -> confirm branch (same as →), not a direct attach.
-const busyService = {
-	rows: () => [{
-		meta: { id: "b1", name: "busy", cwd: "/", sessionFile: "/s/b1.jsonl" },
-		state: { semanticState: "working", processState: "alive", pendingQuestions: [] },
-		alive: true, hostAlive: false, hostActive: false, hostReady: false, host: null,
-	}],
-	reconcile: async () => 0,
-};
-const done2 = [];
-const dash2 = new DashboardComponent(tui, theme, {}, (r) => done2.push(r), {
-	service: busyService, root, defaultCwd: root,
-	availableModels: [], currentModel: null, currentThinkingLevel: "off",
-});
-dash2.selectedId = "b1";
-dash2.handleInput("l");
-out.busyL = { mode: dash2.mode, done: done2.length, prompt: dash2.pending?.prompt ?? null };
-dash2.dispose();
-
-dash.dispose();
-console.log(JSON.stringify(out));
-```
-
-Create `test/dashboard-vim-keys.test.mjs`:
-
-```js
-import assert from "node:assert/strict";
-import { execFileSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { join } from "node:path";
-import test from "node:test";
-
-const ROOT_DIR = fileURLToPath(new URL("../", import.meta.url));
-const PROBE = join(ROOT_DIR, "test-support", "vim-keys-wrap.ts");
-
-test("vim j/k/l bindings mirror the arrow keys across board modes (issue #229)", () => {
-	const out = JSON.parse(execFileSync(process.execPath, ["--experimental-transform-types", PROBE], { encoding: "utf8", timeout: 30_000 }));
-	const { ids } = out;
-	assert.equal(ids.length, 3, "probe must see 3 rows");
-	// A1: list j/k wrap like the arrows; j/k never pop the INSERT toast.
-	assert.deepEqual(out.list, [ids[1], ids[2], ids[0], ids[2], ids[2]], "j down x2, wrap; k wrap; paste no-move");
-	assert.deepEqual(out.notices, [true, true], "j: no INSERT toast; J: keeps the printable fallback");
-	// A2: select mode j/k move (wrap).
-	assert.deepEqual(out.select, [ids[1], ids[0], ids[2]]);
-	// A3: peek j/k step (wrap).
-	assert.deepEqual(out.peek, [ids[1], ids[0], ids[2]]);
-	// A4: l attaches in list / peek / evidence.
-	assert.deepEqual(out.attach.map((r) => [r.action, r.viewId, r.stopFirst]), [
-		["attach", ids[0], false],
-		["attach", ids[1], false],
-		["attach", ids[2], false],
-	]);
-	// A9: l stays unbound in select / session.
-	assert.deepEqual(out.negative, [["select-l", "select", 0], ["session-l", "session", 0]]);
-	// A6: session / evidence j/k still scroll.
-	assert.deepEqual(out.scroll, [1, 0, 1, 0]);
-	// A5: text modes keep j/k/l literal.
-	for (const m of ["dispatch", "filter", "rename", "reply"]) assert.equal(out.text[m], "jkl", m);
-	// RF2: busy row + l -> confirm branch, no direct attach.
-	assert.equal(out.busyL.mode, "confirm");
-	assert.equal(out.busyL.done, 0);
-	assert.match(out.busyL.prompt, /Interrupt and attach/);
-});
-```
-
-- [ ] **Step 2: Run the test to verify it fails**
-
-Run: `cd $WT && node --test test/dashboard-vim-keys.test.mjs`
-Expected: FAIL — list assertion shows `j` does not move the selection (falls into the printable fallback instead).
-
-- [ ] **Step 3: Implement the key bindings**
-
-In `src/ui/dashboard.ts`:
-
-`handleListKey` — extend the three branches:
-
-```ts
-		if (matchesKey(data, Key.up) || data === "k") return void this.moveSelection(-1);
-		if (matchesKey(data, Key.down) || data === "j") return void this.moveSelection(1);
-		if (matchesKey(data, Key.right) || data === ">" || data === "l") return this.attachSelected();
-```
-
-`handleSelectKey`:
-
-```ts
-		if (matchesKey(data, Key.up) || data === "k") return void this.moveSelection(-1);
-		if (matchesKey(data, Key.down) || data === "j") return void this.moveSelection(1);
-```
-
-`handlePeekKey`:
-
-```ts
-		if (matchesKey(data, Key.right) || data === ">" || data === "l") return this.attachPeek();
-		// ...
-		if (matchesKey(data, Key.up) || data === "k") {
-			this.peekStep(-1);
-			return;
-		}
-		if (matchesKey(data, Key.down) || data === "j") {
-			this.peekStep(1);
-			return;
-		}
-```
-
-`handleEvidenceKey`:
-
-```ts
-		if (data === "a" || matchesKey(data, Key.enter) || matchesKey(data, Key.right) || data === "l") return this.attachSelected();
-```
-
-- [ ] **Step 4: Run the test to verify it passes, then remove the dead duplicate lines (spec D3)**
-
-Run: `cd $WT && node --test test/dashboard-vim-keys.test.mjs`
-Expected: PASS.
-
-Then in `handleListKey` delete the duplicated lines (zero behavior change, re-run the test after):
-
-```ts
-		if (data === "d") return this.confirmDone();
-		if (data === "d") return this.confirmDone();   // DELETE this duplicate
-```
-```ts
-		if (matchesKey(data, Key.ctrl("x"))) return this.handleDeleteKey();
-		if (matchesKey(data, Key.ctrl("x"))) return this.handleDeleteKey();   // DELETE this duplicate
-```
-
-Run: `cd $WT && node --test test/dashboard-vim-keys.test.mjs test/dashboard-delete-key.test.mjs test/dashboard-hold-key.test.mjs`
-Expected: all PASS (no regression in the neighboring key paths).
-
-- [ ] **Step 5: Typecheck and commit**
-
-Run: `cd $WT && npm run typecheck && node --test test/dashboard-navigation.test.mjs` (existing wrap test still passes)
-Then:
-
-```bash
-git -C $WT add test-support/vim-keys-wrap.ts test/dashboard-vim-keys.test.mjs src/ui/dashboard.ts
-git -C $WT commit -m "feat(ui): vim-style j/k navigation and l attach in board modes (issue #229)"
-```
-
----
-
-### Task 2: Help overlay and hint-line copy
-
-**Files:**
-- Modify: `test-support/vim-keys-wrap.ts` (append render segment)
-- Modify: `test/dashboard-vim-keys.test.mjs` (append A7 test)
-- Modify: `src/ui/dashboard.ts` (renderHelp rows :1701-1729, listHints :1342-1364)
-
-**Interfaces:**
-- Consumes: Task 1's probe file and `dash.render(width): string[]` (public, :1212).
-- Produces: probe `out.copy = { help120, listRender, selectRender, help80Lines }`.
-
-**Spec acceptance IDs:** A7 (+ Review Focus 3). Covers spec §4 items 1-3 including the D5 doc-debt rows.
-
-- [ ] **Step 1: Extend the probe with render capture and write the failing A7 test**
-
-Append before `dash.dispose();` in `test-support/vim-keys-wrap.ts`:
-
-```ts
-// A7: help overlay + hint lines copy.
-dash.mode = "help"; dash.helpReturnMode = "list";
-const help120 = dash.render(120).join("\n");
-const help80 = dash.render(80); // must not throw; renderCenteredBox clips
-dash.mode = "list";
-const listRender = dash.render(120).join("\n");
-dash.mode = "select";
-const selectRender = dash.render(120).join("\n");
-dash.mode = "list";
-out.copy = { help120, listRender, selectRender, help80Lines: help80.length };
-```
-
-Append to `test/dashboard-vim-keys.test.mjs`:
-
-```js
-test("help overlay and hint lines document j/k/l (issue #229 A7)", () => {
-	const out = JSON.parse(execFileSync(process.execPath, ["--experimental-transform-types", PROBE], { encoding: "utf8", timeout: 30_000 }));
-	const { help120, listRender, selectRender, help80Lines } = out.copy;
-	assert.match(help120, /↑\/↓ or j\/k/);
-	assert.match(help120, /→ \/ > \/ l/);
-	assert.match(help120, /In select.*j\/k/);
-	assert.match(help120, /In peek.*↑↓\/j\/k/);
-	assert.match(help120, /In peek.*→\/l attach/);
-	assert.match(help120, /In session.*↑↓\/j\/k scroll/);
-	assert.match(help120, /In evidence.*↑↓\/j\/k scroll/);
-	assert.match(help120, /In evidence.*→\/l attach/);
-	// Negative: stale pre-change wording is gone from every row that named bare arrows.
-	assert.doesNotMatch(help120, /In peek.*· ↑↓ adjacent/);
-	assert.doesNotMatch(help120, /In session.*· ↑↓ scroll/);
-	assert.doesNotMatch(help120, /In evidence.*· ↑↓ scroll/);
-	assert.match(listRender, /→\/l attach/);
-	assert.match(selectRender, /↑↓\/j\/k move/);
-	assert.ok(help80Lines > 0, "80-col help render must not throw (RF3)");
-});
-```
-
-- [ ] **Step 2: Run the test to verify it fails**
-
-Run: `cd $WT && node --test test/dashboard-vim-keys.test.mjs`
-Expected: FAIL — `↑/↓ or j/k` not found in the help render.
-
-- [ ] **Step 3: Update the help overlay rows and hint lines**
-
-In `renderHelp` (`src/ui/dashboard.ts:1701-1729`), change these rows:
-
-```ts
-			["↑/↓ or j/k", "Normal: move selection; Insert: move cursor"],
-			["→ / > / l", "Attach to the selected real Pi session"],
-			["In select", "j/k move · a select all · u clear · d move done · ctrl+x delete · esc cancel"],
-			["In peek", "→/l attach · v transcript · e evidence · r reply · ↑↓/j/k adjacent"],
-			["In session", "← back · ↑↓/j/k scroll · e evidence · enter attach · r reply"],
-			["In evidence", "← back · ↑↓/j/k scroll · →/l attach · r reply · v transcript · x clear diag"],
-```
-
-(Note the trailing `x clear diag` — shortened from `x clear diagnostics` so the longer row stays readable; `renderCenteredBox` clips at narrow widths regardless, RF3.)
-
-In `listHints` (:1342-1364): SELECT branch gains `"↑↓/j/k move"` as the first hint after the count/unread spread; NORMAL row changes `"→ attach"` to `"→/l attach"`.
-
-- [ ] **Step 4: Run the tests to verify they pass**
-
-Run: `cd $WT && node --test test/dashboard-vim-keys.test.mjs`
-Expected: PASS (both tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git -C $WT add test-support/vim-keys-wrap.ts test/dashboard-vim-keys.test.mjs src/ui/dashboard.ts
-git -C $WT commit -m "docs(ui): document j/k/l in help overlay and hint lines (issue #229)"
-```
-
----
-
-### Task 3: README key tables and full verification gate
-
-**Files:**
-- Modify: `README.md` (Main list table, Peek table, Transcript table, Evidence table)
-
-**Interfaces:**
-- Consumes: Task 1/2 behavior as implemented.
-- Produces: docs matching behavior; A8 green run.
-
-**Spec acceptance IDs:** A8 (+ U2 groundwork — the tables are what U2 checks against).
-
-- [ ] **Step 1: Update the four README tables**
-
-In `README.md`:
-
-Main list table:
-- `| `Up` / `Down` | Move the selection. |` → `| `Up` / `Down` / `j` / `k` | Move the selection. |`
-- `| `Right` / `>` | Attach to the selected session. |` → `| `Right` / `>` / `l` | Attach to the selected session. |`
-
-Peek table:
-- `| `a`, `Right`, or `>` | Attach to the session. |` → `| `a`, `Right`, `>`, or `l` | Attach to the session. |`
-- `| `Up` / `Down` | Move to the previous or next session. |` → `| `Up` / `Down` / `j` / `k` | Move to the previous or next session. |`
-
-Transcript table:
-- `| `Up` / `Down` | Scroll one line. |` → `| `Up` / `Down` / `j` / `k` | Scroll one line. |`
-
-Evidence table:
-- `| `Up` / `Down` | Scroll one line. |` → `| `Up` / `Down` / `j` / `k` | Scroll one line. |`
-- `| `Enter`, `a`, or `Right` | Attach to the session. |` → `| `Enter`, `a`, `Right`, or `l` | Attach to the session. |`
-
-- [ ] **Step 2: Run the full verification gate**
-
-Run: `cd $WT && npm run verify`
-Expected: PASS — typecheck, perf gate, all tests, coverage thresholds (lines 85 / funcs 80 / branches 70), pack:dry.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git -C $WT add README.md
-git -C $WT commit -m "docs: document j/k/l keys in the README view tables (issue #229)"
-```
-
----
-
-### Task 4: Post-implementation manual verification (pre-merge, by user)
-
-**Spec acceptance IDs:** U1, U2. No code changes; this task is the executable checklist.
-
-- [ ] **Step 1: U1 — real dashboard feel**
-
-Deploy prelude (prevents loading stale code): `pi list` to record the current install source (this machine: `git:github.com/zhuxixi/pi-agent-board`) → `pi remove <that source>` → `pi install /home/elling/work/git-repo/pi-agent-board/.pi/worktrees/issue-229-vim-jkl-board-list` → `pi /agent-board`.
-
-Checklist: ① `j`/`k` walk list rows incl. wrap at both ends ② `j` no longer pops the INSERT toast ③ `l` attaches the selected session ④ after detach, `?` shows the new bindings (incl. the evidence row's `→/l attach`) ⑤ in INSERT mode `j`/`k`/`l` stay literal characters.
-
-Cleanup: `pi remove /home/elling/work/git-repo/pi-agent-board/.pi/worktrees/issue-229-vim-jkl-board-list` → reinstall the recorded original source.
-
-- [ ] **Step 2: U2 — README vs behavior**
-
-Walk the four README tables row by row against the live dashboard; every listed key works, no key is missing.
-
-- [ ] **Step 3: Record results**
-
-Comment the U1/U2 outcomes on issue #229 before merge. If any item fails or cannot run, mark it `pending` — do not claim full acceptance.
-
----
-
-## Self-Review Notes
-
-- **Spec coverage:** §3 bindings → Task 1; §4 copy items 1-3 → Task 2, items 4-5 → Task 3; D3 dead-code → Task 1 Step 4; A1-A9 → Task 1/2; A8 → Task 3; U1/U2 → Task 4. Every acceptance ID has a task; every task cites IDs.
-- **Placeholder scan:** none — all code and commands are concrete.
-- **Type consistency:** probe field names (`out.list/select/peek/attach/negative/scroll/text/notices/busyL/copy`) match between the probe and both tests; `DashboardResult` shape `{action, viewId, stopFirst}` matches `src/ui/dashboard.ts:58`.

package/docs/superpowers/plans/2026-10-23-issue-232-attach-bg-only-cells.md

@@ -1,153 +0,0 @@
-# Attach Background-Only Cells 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 `lineToAnsi()` from trimming cells that carry only a non-default background, so full-screen TUIs (nvim, lazygit, htop) keep their theme background in the attach view.
-
-**Architecture:** The per-line scan in `lineToAnsi()` already walks every cell; it gains a `lastBg` cursor (last cell with `!isBgDefault()`), and the render bound becomes `renderEnd = max(last, lastBg)`. The main loop, the empty-line guard, and the cursor-past-content check all switch from `last` to `renderEnd`. Default-background screens keep the existing cheap path (`""` for blank lines, no padding). A component-level smoke fixture drives a real `@xterm/headless` terminal through `PtyAttachComponent.render()` and asserts the emitted ANSI.
-
-**Tech Stack:** TypeScript (`src/ui`), Node 22/24 `node:test`, `node --experimental-transform-types` fixtures, `@xterm/headless`.
-
-**Spec:** `docs/superpowers/specs/2026-10-23-issue-232-attach-bg-only-cells-design.md`
-
-**Worktree:** `/home/elling/work/git-repo/pi-agent-board/.pi/worktrees/issue-232-attach-bg-only-cells` — every path below is relative to it; never edit the main checkout.
-
-## Global Constraints
-
-- Tabs for indentation; English comments; conventional commit subjects (`fix(attach): …`) with `(#232)` only on the PR title.
-- Do not change selection/copy semantics, OSC-8 link handling, mouse handling, or the wide-char skip (`getWidth() === 0`).
-- Padding must never be emitted for default-background cells — the cheap path for ordinary shells stays byte-identical.
-- `git add <explicit files>` only; never `git add -A`.
-- `npm run verify` (typecheck + perf + test + coverage + pack:dry) is the gate before claiming done.
-- Fixture cells that must be background-only are produced **only** by erase sequences (`\x1b[K` / `\x1b[2J`) under an active bg; literal spaces keep `getChars()` non-empty and make the test pass on unpatched code (spec A8).
-
-## Review Focus
-
-1. **Blank painted line** — all cells `getChars() === ""`, `isBgDefault() === false`; the line must render as an SGR run plus padding, not `""`. → A1.
-2. **Trailing paint after content** — characters end at col 1, paint starts at col 40; cols 2–39 stay default, 40–79 painted. → A2.
-3. **Default-background regression** — plain text screens still serialize blank lines to `""` (no padding, no SGR). → A3.
-4. **Wide chars** — `中` (cols 0–1, continuation cell skipped) followed by painted erase cells; display width must stay 80 with 78 padding spaces. → A4.
-5. **Cursor inside the padded region** — exactly one `CURSOR_MARKER` and one inverse block, no double block. → A5.
-6. **Selection over padding** — padded cells inside a selection render inverse (`7`); copied text is unaffected. → A9.
-
----
-
-### Task 1: Fixture and failing tests (red)
-
-**Files:**
-- Create: `test-support/attach-bg-paint-smoke.ts`
-- Create: `test/pty-attach-bg-paint.test.mjs`
-
-**Interfaces:**
-- Consumes: `PtyAttachComponent` (`src/ui/pty-attach.ts:162`), constructor `(tui, theme, keybindings, done, opts)`; `render(width: number): string[]` returns `[header, ...body(rows-2), footer]`.
-- Produces: JSON on stdout from the fixture:
-
-```ts
-{
-  blankPainted: string[];   // 10 body lines, whole screen erased with bg #1e1e2e
-  contentPainted: string[]; // one row: "AB" + 38 default spaces + 40 painted cells
-  plain: string[];          // ordinary text screen (default bg)
-  wide: string[];           // "中" + 78 painted cells
-  cursor: string[];         // painted blank row, cursor visible at col 30
-  selection: string[];      // painted blank row, selection cols 20–60
-}
-```
-
-- [ ] **Step 1: Write the fixture.** Model it on `test-support/hyperlink-cell-smoke.ts` (stub `tui` with `terminal: { rows: 12, cols: 80, columns: 80, write: () => {} }`, identity `theme`, `socketPath: "/no/such/socket"`, `dispose()` in `finally`). Cast the component to expose `term`, `receivedOutput`, `finishAttachTransition`, and `selection`.
-
-  Per scenario:
-  - `blankPainted`: `\x1b[48;2;30;30;46m\x1b[2J` then `\x1b[?25l` (hide cursor).
-  - `contentPainted`: default-bg rows, then `AB\x1b[41G\x1b[48;2;30;30;46m\x1b[K` on one row; hide cursor.
-  - `plain`: `hello\r\nworld` only; hide cursor.
-  - `wide`: `中\x1b[48;2;30;30;46m\x1b[K`; hide cursor.
-  - `cursor`: painted blank row (`\x1b[48;2;30;30;46m\x1b[2J`), then park the cursor visibly at row 5 col 30 via `\x1b[6;31H`; do **not** send `\x1b[?25l`.
-  - `selection`: painted blank screen; set the private `selection = { anchor: { line: 5, col: 20 }, focus: { line: 5, col: 60 } }` (type `MouseSelection`, `src/ui/pty-attach.ts:159`) before `finishAttachTransition()`.
-
-  Return `attach.render(80).slice(1, -1)` per scenario (the component's body lines; height comes from `tui.terminal.rows - 2`).
-
-- [ ] **Step 2: Write the assertions** in `test/pty-attach-bg-paint.test.mjs`, spawning the fixture with `execFileSync(process.execPath, ["--experimental-transform-types", FIXTURE], { encoding: "utf8", timeout: 30_000 })` exactly like `test/pty-attach-hyperlinks.test.mjs`:
-  - A1: every `blankPainted` line is non-empty and includes `48;2;30;30;46`.
-  - A2: the `contentPainted` line containing `AB` has exactly 38 spaces before the next SGR, and the paint run covers 40 cells.
-  - A3: in `plain`, the blank body lines are exactly `""`.
-  - A4: the `wide` line contains `中`, ends with 78 spaces plus `\x1b[0m`, and has display width 80.
-  - A5: the cursor row contains exactly one `\x1b_pi:c\x07` and one `\x1b[7m \x1b[0m`.
-  - A9: the selection row contains an SGR that includes `7` (e.g. `\x1b[0;7;`) inside the padded region.
-
-- [ ] **Step 3: Run the tests and record the red output.**
-
-```bash
-node --test test/pty-attach-bg-paint.test.mjs
-```
-
-Expected: A1, A2, A4, A5, A9 fail against the unpatched `lineToAnsi` (blank painted lines are `""`, padding absent). A3 passes. Save the output — it is the A8 "red" evidence for the PR description.
-
----
-
-### Task 2: Patch `lineToAnsi()` (green)
-
-**Files:**
-- Modify: `src/ui/pty-attach.ts` (`lineToAnsi`, `:1962-2026`)
-
-**Interfaces:**
-- Consumes: `BufferCellLike.isBgDefault()` (`:142`), already on the interface.
-- Produces: no signature change.
-
-- [ ] **Step 1: Add the painted-extent scan (C1).** After the `if (!line)` early return, declare `let lastBg = -1;`, and inside the scan loop add `if (!cell.isBgDefault()) lastBg = x;` after the `getChars()` check. Compute `const renderEnd = Math.max(last, lastBg);` and make the empty-line guard test `renderEnd < 0`.
-
-- [ ] **Step 2: Render through the painted extent (C2).** Change the main loop bound to `x <= renderEnd`.
-
-- [ ] **Step 3: Fix the cursor bound (C3).** Change the post-loop check to `cursor!.col > renderEnd` and update the adjacent comment to say "painted region" rather than "line content".
-
-- [ ] **Step 4: Add the explanatory comment** above `lastBg` (English): full-screen TUIs paint an explicit theme bg over empty regions; trimming at the last character drops it and lets the host terminal's default bg show through (issue #232). Keep it to 3–4 lines.
-
-- [ ] **Step 5: Run the new tests.**
-
-```bash
-node --test test/pty-attach-bg-paint.test.mjs
-```
-
-Expected: all pass, including A3 (plain screen unchanged).
-
-- [ ] **Step 6: Commit.**
-
-```bash
-git add src/ui/pty-attach.ts test-support/attach-bg-paint-smoke.ts test/pty-attach-bg-paint.test.mjs
-git commit -m "fix(attach): render cells that only carry a background (#232)"
-```
-
----
-
-### Task 3: Red-green mutation proof (A8)
-
-- [ ] **Step 1:** Temporarily change the main loop bound back to `x <= last` (leave `renderEnd` in place).
-- [ ] **Step 2:** Run `node --test test/pty-attach-bg-paint.test.mjs`; expect A1/A2/A4 to fail.
-- [ ] **Step 3:** Restore `x <= renderEnd`; re-run; expect all pass.
-- [ ] **Step 4:** Record both outputs (commands + failure names) for the PR description. Do not commit the reverted state.
-
----
-
-### Task 4: Full gate
-
-- [ ] **Step 1:** `npm run typecheck` → exit 0 (A6; note `test-support/` is outside `tsconfig`, so fixture types surface through Task 1 instead).
-- [ ] **Step 2:** `npm run verify` → typecheck + perf gate + full suite + coverage thresholds (lines 85 / funcs 80 / branches 70) + pack dry-run (A7).
-
----
-
-### Task 5: Manual acceptance (U1, after the PR branch is installable)
-
-- [ ] **Step 1:** Confirm the worktree HEAD equals the PR head (`git log -1`).
-- [ ] **Step 2:** `npm install` in the worktree; load the checkout with `pi install "$(pwd)"`; **restart pi**.
-- [ ] **Step 3:** `/agent-board` → attach to an nvim session with catppuccin-mocha; observe the empty buffer area (`#1e1e2e`) and the cursorline (highlight spans the full row).
-- [ ] **Step 4:** `pi remove "$(pwd)"`; report the observation in the PR/issue.
-
----
-
-## Acceptance traceability
-
-| Spec ID | Plan task |
-| --- | --- |
-| A1, A2, A3, A4, A5, A9 | Task 1 (red) + Task 2 Step 5 (green) |
-| A8 | Task 3 (+ Task 1 Step 3 red output) |
-| A6 | Task 4 Step 1 |
-| A7 | Task 4 Step 2 |
-| U1 | Task 5 |