@zhuxixi/pi-agent-board 0.5.0 → 0.5.2

package/docs/superpowers/plans/2026-08-30-readme-v2.md

@@ -0,0 +1,294 @@
+# README v2 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:** Rewrite `README.md` into an accurate, task-oriented English user guide for the current Pi Agent Board package, and correct the stale install command in `VERIFY.md`.
+
+**Architecture:** This is a documentation-only change. `README.md` becomes the primary user-facing guide, organized around installation, first use, dashboard actions, reference behavior, configuration, safety, troubleshooting, and maintainer entry points. `VERIFY.md` receives one supporting-document correction so the linked verification path uses the scoped package name. Source code and `package.json` remain the behavior authority.
+
+**Tech Stack:** Markdown, shell command examples, GitHub/Pi package links, existing Node.js verification scripts.
+
+## Global Constraints
+
+- Keep all user-facing documentation in English; discuss implementation progress in Chinese.
+- Work only in `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-51-readme`; do not touch the main checkout.
+- Use `package.json`, `src/index.ts`, `src/commands/*`, `src/ui/dashboard.ts`, `src/ui/pty-attach.ts`, `src/runtime/service.mjs`, and `src/core/*` as the source of truth.
+- Do not advertise worktree isolation, plan-approval UI, provider-stall detection, or other planned/disabled behavior as shipped.
+- State explicitly that worktree isolation is currently disabled and same-repository concurrent writes require user-managed isolation.
+- Do not list internal child markers such as `AGENT_BOARD_CHILD`, `AGENT_BOARD_VIEW_ID`, or `AGENT_BOARD_HOSTED` as user settings.
+- Do not advertise `AGENT_BOARD_ALLOW_PIPE_FALLBACK` as a normal ambient user toggle because the current service does not pass that ambient variable into the PTY runner configuration.
+- Do not hard-code an unverified test count as a durable README claim; use CI and `npm run verify` as the authority.
+- Do not modify runtime code, PRD/history documents, or the main checkout.
+- Do not commit, push, open a PR, or merge without explicit user permission.
+
+## File Map
+
+- Modify: `README.md` — complete user-first guide and reference.
+- Modify: `VERIFY.md` — one stale scoped-package install command.
+- Create: `docs/superpowers/specs/2026-08-30-readme-v2-design.md` — approved design copied into the worktree.
+- Create: `docs/superpowers/plans/2026-08-30-readme-v2.md` — this implementation plan.
+- Inspect only: `package.json`, `src/index.ts`, `src/commands/agent-board.ts`, `src/commands/bg.ts`, `src/ui/dashboard.ts`, `src/ui/pty-attach.ts`, `src/runtime/service.mjs`, `src/core/rows.mjs`, `src/core/auto-state.mjs`, `src/core/launch-options.mjs`, `src/core/code-refs*.mjs`, `.github/workflows/ci.yml`, and `VERIFY.md`.
+
+---
+
+### Task 1: Rewrite README structure and first-use path
+
+**Files:**
+- Modify: `README.md`
+- Inspect: `package.json`, `src/index.ts`, `src/commands/agent-board.ts`, `src/commands/bg.ts`, `src/ui/dashboard.ts`
+
+**Interfaces:**
+- Consumes: package identity and scripts from `package.json`; registered commands/flag from `src/index.ts` and `src/commands/*`; dashboard behavior from `src/ui/dashboard.ts`.
+- Produces: an English README whose first-use path is Requirements → Install → Quick start → Entry points → Dashboard workflow.
+
+- [ ] **Step 1: Replace the product introduction and requirements sections**
+
+Write the opening around the current value proposition: a full-screen TUI for durable background Pi sessions, global cross-project visibility, dashboard triage, inline reply/evidence, and PTY/JSON fallback. Keep the existing banner, demo, package gallery, and npm links if they remain valid.
+
+Add requirements for Pi, Node.js 20+, working Pi provider authentication, and PTY support for live attach/start-and-attach. State that provider authentication is a Pi prerequisite, not an Agent Board credential setup.
+
+Use this package command exactly:
+
+```bash
+pi install npm:@zhuxixi/pi-agent-board
+```
+
+Do not use the unscoped `pi-agent-board` package name.
+
+- [ ] **Step 2: Add installation alternatives and auth sanity check**
+
+Keep three clearly separated paths:
+
+```bash
+# Published package
+pi install npm:@zhuxixi/pi-agent-board
+
+# Local package checkout
+npm install
+pi install "$(pwd)"
+
+# Development auto-discovery
+ln -s "$(pwd)" ~/.pi/agent/extensions/agent-board
+```
+
+Explain that `pi remove "$(pwd)"` applies to the local path installation, while the development symlink must be removed manually. Include the existing one-shot check and explain that it should end with an assistant `message_end`, then `agent_end`, and exit. Link `VERIFY.md` for the complete diagnostic sequence.
+
+- [ ] **Step 3: Add Quick start and entry-point differences**
+
+Add a five-step first-task flow:
+
+1. Press `i` to enter INSERT mode.
+2. Type a task.
+3. Press `Enter` to open **Start session**.
+4. Review cwd, model, thinking, and action.
+5. Press `Enter` to launch.
+
+Document `/agent-board`, `pi /agent-board`, `pi --agent-board`, and `/bg [prompt]`. State that `pi /agent-board` runs the standalone dashboard path and quitting it shuts down Pi; state that `--agent-board` cannot attach to a managed session and normal `/agent-board` is required for attach. Explain that `/bg` adopts the current interactive session and optionally queues a prompt.
+
+- [ ] **Step 4: Verify the first-use section against source**
+
+Check every command and behavior statement against `src/index.ts`, `src/commands/bg.ts`, `src/commands/agent-board.ts`, and the dashboard input handlers. Confirm that draft Enter opens the launch dialog, empty Enter attaches/resumes, and `i` is required before typing in Normal mode.
+
+Run:
+
+```bash
+grep -nE '/agent-board|/bg|agent-board|INSERT|Start session|Enter|attach' README.md src/index.ts src/commands/*.ts src/ui/dashboard.ts
+```
+
+Expected: all advertised entry points and input transitions have matching source evidence and no unscoped install command appears in the new README.
+
+---
+
+### Task 2: Add dashboard, views, states, filters, and attach reference
+
+**Files:**
+- Modify: `README.md`
+- Inspect: `src/ui/dashboard.ts`, `src/ui/pty-attach.ts`, `src/core/rows.mjs`, `src/core/types.mjs`, `src/runtime/service.mjs`, `src/ui/dashboard-evidence.mjs`
+
+**Interfaces:**
+- Consumes: dashboard modes/key handlers, row state/filter helpers, service fallback behavior, and PTY attach input handling.
+- Produces: view-scoped reference sections that do not imply a key works in every dashboard mode.
+
+- [ ] **Step 1: Document dashboard modes, launch dialog, and destructive actions**
+
+Add Normal vs INSERT behavior, including `/` being literal in INSERT mode. Explain the launch dialog fields: cwd picker with favorites/browse and Tab completion, Pi-scoped model choices, supported thinking levels, and background versus start-and-attach. Mention persisted launch preferences and PTY-dependent start-and-attach fallback.
+
+Document exact actions:
+
+- `d` confirms Done for inactive sessions;
+- manual completion is the default;
+- `Ctrl+X` twice quickly archives/deletes a row;
+- archive removes the row from the board but preserves the Pi session file;
+- `X` removes inactive rows in the selected state;
+- `m` enters batch selection with Space/a/u/d/Ctrl+X.
+
+- [ ] **Step 2: Document view-specific shortcuts and capabilities**
+
+Provide separate tables or subsections for Main list, Peek, Transcript, Evidence/Diagnostics, and PTY attach. Include:
+
+- main-list navigation and actions;
+- `Space` Peek;
+- `r` reply only from Peek/Transcript/Evidence, not the main list; in Peek, it enters reply mode and the user presses Enter again after typing to send;
+- `v` read-only transcript;
+- `e` Evidence/Diagnostics and evidence-preserving diagnostic clear with `x`;
+- attach with Enter/Right/`>`;
+- PTY detach with `Left` when the child input is empty; edited input forwards the key, while a disconnected host can always be exited; `Ctrl+]` is passed through to the child Pi editor;
+- attach scroll keys, mouse selection/copy, link opening, and optional middle-click paste.
+
+State that pending Pi question/questionnaire tools require attach and cannot be answered with inline reply.
+
+- [ ] **Step 3: Document states, grouping, unread, queue, and filters**
+
+Document the exact display labels: Queued, Running, Needs answer, Needs instructions, Done, Failed, and Stopped. Explain semantic state versus process liveness, state/folder grouping, pinned-first stable creation ordering, unread indicators, busy follow-up FIFO queue, `qN`, and `queued:true`.
+
+Document this filter syntax:
+
+```text
+s:running
+review:ready
+diag:stalled
+evidence:error
+queued:true
+steer:awaiting-approval
+```
+
+Explain free-text AND matching over name, summary, and cwd, case-insensitive state aliases, and the limitation that `diag:stalled` consumes persisted diagnostics but does not represent a complete current provider-stall detector.
+
+- [ ] **Step 4: Document evidence, code references, and persistence**
+
+Explain Peek's summary/blocker/latest-output surface, transcript projection, Evidence/Diagnostics contents, durable artifacts, and locally extracted issue/PR badges. Mention optional per-root `providers.json` only as an extension point; do not invent an unverified schema.
+
+Explain that busy replies are queued and drained when the session is ready. Explain the high-level store location `~/.pi/agent/agent-board/` and persistence through reload/restart/worker exit.
+
+- [ ] **Step 5: Verify all advertised shortcuts and states**
+
+Run:
+
+```bash
+grep -nE 'handle(List|Select|Peek|Session|Evidence)Key|renderHelp|renderPtyHelp|Ctrl|ctrl\+|review:ready|diag:stalled|evidence:error|queued:|steer:' src/ui/dashboard.ts src/core/rows.mjs
+```
+
+Compare every README shortcut/filter/state claim with the matching source handler. Remove any claim that only exists in PRD or planning documents.
+
+---
+
+### Task 3: Add configuration, safety, troubleshooting, and maintainer links
+
+**Files:**
+- Modify: `README.md`
+- Inspect: `src/core/auto-state.mjs`, `src/core/title.mjs`, `runner/job-runner.mjs`, `runner/title-runner.mjs`, `src/runtime/service.mjs`, `src/ui/pty-attach.ts`, `src/core/pty-support.mjs`, `src/core/paths.mjs`, `.github/workflows/ci.yml`, `package.json`
+
+**Interfaces:**
+- Consumes: supported environment-variable reads, default values, PTY diagnosis behavior, package scripts, CI checks, and existing documentation links.
+- Produces: a complete user-facing configuration table and explicit limitations/troubleshooting path.
+
+- [ ] **Step 1: Replace the incomplete configuration table**
+
+Document these supported user-facing settings with exact defaults and disable values: `AGENT_BOARD_ROOT`, `AGENT_BOARD_AUTO_STATE`, `AGENT_BOARD_AUTO_STATE_MODEL`, `AGENT_BOARD_AUTO_STATE_NO_DONE`, `AGENT_BOARD_SUMMARY_MODEL`, `AGENT_BOARD_TITLE_MODEL`, `AGENT_BOARD_TITLE_THINKING_LEVEL`, `AGENT_BOARD_CODE_REFS`, `AGENT_BOARD_DISABLE_PTY`, `AGENT_BOARD_FORCE_PTY`, `AGENT_BOARD_ATTACH_MOUSE`, `AGENT_BOARD_ENABLE_MOUSE_SCROLL`, `AGENT_BOARD_WHEEL_LINES`, `AGENT_BOARD_MAX_WARM_HOSTS`, `AGENT_BOARD_WARM_HOST_TTL_MS`, `AGENT_BOARD_ATTACH_NATIVE_PASTE`, `AGENT_BOARD_FORWARD_OSC52`, and `AGENT_BOARD_FORWARD_IMAGES`.
+
+State the important default correctly: `AGENT_BOARD_AUTO_STATE_NO_DONE` unset means the user marks Done manually; `0`, `false`, `off`, or `no` restores automatic Done classification. Explain heuristic fallback for summary/title/state model failures where applicable.
+
+Mention selected `AGENT_VIEW_*` names only as compatibility aliases and prefer `AGENT_BOARD_*` for new setup. Exclude internal child markers and do not present `AGENT_BOARD_ALLOW_PIPE_FALLBACK` as an ambient normal-user setting.
+
+- [ ] **Step 2: Add safety, fallback, and troubleshooting sections**
+
+Prominently state that worktree isolation is currently disabled and not automatically created. Same-repository concurrent sessions can run at the same time, so users must avoid overlapping writes or provide their own isolation.
+
+Explain PTY versus JSON-runner fallback, the start-and-attach degradation, adopted external-session PTY requirement, Windows named-pipe/hidden-console capability, and `!` diagnostics. Add symptom-based troubleshooting for stuck Running/auth, `node-pty unavailable`, slow attach/reconnect, rejected inline reply, and same-repository conflicts.
+
+- [ ] **Step 3: Simplify development, publishing, and further reading**
+
+Keep maintainer sections concise:
+
+```bash
+npm install
+npm run verify
+```
+
+Explain that verify runs typecheck, tests, coverage, and package dry-run. Keep publishing as verify, `npm version patch` (or minor/major), and `npm publish`. Link `VERIFY.md`, `PRD.md`, `PROGRESS.md`, and relevant deeper design material without embedding historical progress or a stale numeric test count.
+
+- [ ] **Step 4: Validate configuration and limitation claims**
+
+Run:
+
+```bash
+git grep -nE 'AGENT_BOARD_[A-Z0-9_]+' -- ':!README.md' ':!coverage/**' ':!node_modules/**'
+grep -nE 'DEFAULT_|AUTO_STATE_NO_DONE|AGENT_BOARD_|node-pty|worktree|windows|verify' README.md package.json src/core/*.mjs src/runtime/*.mjs src/ui/*.ts runner/*.mjs .github/workflows/ci.yml
+```
+
+Expected: each public README variable has a source read and an accurate default; internal markers and unsupported worktree claims are absent.
+
+---
+
+### Task 4: Correct VERIFY.md and run documentation validation
+
+**Files:**
+- Modify: `VERIFY.md`
+- Inspect: `README.md`, `VERIFY.md`, `package.json`, all README link targets
+
+**Interfaces:**
+- Consumes: the README's package/install path and the existing verification checklist.
+- Produces: consistent scoped package installation instructions and validation evidence for the documentation change.
+
+- [ ] **Step 1: Correct the stale published-package command**
+
+Replace only this command in `VERIFY.md`:
+
+```bash
+pi install npm:pi-agent-board
+```
+
+with:
+
+```bash
+pi install npm:@zhuxixi/pi-agent-board
+```
+
+Do not change the verification procedure or historical notes beyond this scoped package correction.
+
+- [ ] **Step 2: Check Markdown links and stale wording**
+
+Run:
+
+```bash
+python - <<'PY'
+from pathlib import Path
+import re
+
+for path in (Path("README.md"), Path("VERIFY.md")):
+    text = path.read_text()
+    for line_no, line in enumerate(text.splitlines(), 1):
+        for target in re.findall(r"\]\(([^)]+)\)", line):
+            if target.startswith(("http://", "https://", "#", "mailto:")):
+                continue
+            candidate = (path.parent / target.split("#", 1)[0]).resolve()
+            if not candidate.exists():
+                raise SystemExit(f"broken link: {path}:{line_no}: {target}")
+print("relative Markdown links: OK")
+PY
+
+grep -RInE 'pi install npm:pi-agent-board|default: enabled|300\+ tests|r.*reply' README.md VERIFY.md || true
+```
+
+Expected: no broken relative links, no stale unscoped package command, no ambiguous auto-done wording, and no stale test-count claim.
+
+- [ ] **Step 3: Run repository verification and inspect the final diff**
+
+Run from the issue worktree:
+
+```bash
+npm run typecheck
+npm test
+npm run pack:dry
+git diff --check
+git diff --stat
+git status --short
+```
+
+Expected: typecheck succeeds, the clean worktree baseline remains 416/416 tests with 0 failures, package dry-run succeeds, `git diff --check` is clean, and the diff contains only the approved spec/plan plus `README.md` and the one-line `VERIFY.md` correction.
+
+Do not include the main checkout's untracked PTY tests in this evidence. Do not claim the main checkout is green while those unrelated tests remain failing.
+
+- [ ] **Step 4: Prepare issue progress and handoff**
+
+Record in the Issue #51 progress comment: the isolated worktree path, the documentation files changed, validation commands and results, any residual source-of-truth caveats, and the fact that no push/PR/merge was performed. Stop before pushing or opening a PR and request explicit user permission.

package/docs/superpowers/plans/2026-09-01-attach-detach-gate-cursor-anchor.md

@@ -0,0 +1,284 @@
+# ← Detach Gate Cursor-Anchor Fix 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:** Fix issue #66 — `←` must detach when the Pi editor line is empty even while the terminal cursor rests on working/output lines (attach / streaming).
+
+**Architecture:** Replace the cursor-line anchor in `PtyAttachComponent.childInputLooksEmpty()` with a bottom-up scan for Pi's inverse-video fake-cursor cell (`ESC[7m`, persists in the xterm buffer across differential frames), with a prompt-glyph fallback and a "treat as empty" escape fallback. Add a pure helper `isProbablyPiInputLine` for glyph detection.
+
+**Tech Stack:** TypeScript (pty-attach.ts, run via `node --experimental-transform-types` in tests), plain ESM (pty-input.mjs), `node:test` runner, @xterm/headless.
+
+**Spec:** `docs/superpowers/specs/2026-09-01-attach-detach-gate-cursor-anchor-design.md`
+
+## Global Constraints
+
+- Coverage gates: lines 85 / funcs 80 / branches 70 (c8, `npm run test:coverage`); Node 22/24 both green (CI).
+- `isProbablyPiInputLine` glyph set must stay identical to `isProbablyEmptyPiInputLine`'s trim charset: `›>┃│|┆╎╏:`.
+- Do not change `ctrl+]` semantics (passes through to Pi since v0.5.1) and do not make `←` unconditionally detach (keeps the edit-protection gate — spec §3).
+- Do not modify `src/core/pty-input.mjs`'s existing `isProbablyEmptyPiInputLine` behavior.
+- All edits inside worktree `WT=.pi/worktrees/issue-66-attach-detach-gate-cursor-anchor`; git ops via `git -C $WT`.
+
+---
+
+### Task 1: Add `isProbablyPiInputLine` pure helper + unit tests
+
+**Files:**
+- Modify: `src/core/pty-input.mjs` (append glyph const + function after existing helper)
+- Test: `test/pty-input.test.mjs`
+
+**Interfaces:**
+- Produces: `export function isProbablyPiInputLine(line: string): boolean` — true iff the line, after trimming leading whitespace, starts with a prompt/continuation glyph.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `test/pty-input.test.mjs` (keep existing tests untouched):
+
+```js
+import { isProbablyEmptyPiInputLine, isProbablyPiInputLine } from "../src/core/pty-input.mjs";
+
+test("isProbablyPiInputLine recognizes Pi prompt / continuation lines", () => {
+	assert.equal(isProbablyPiInputLine("> "), true);
+	assert.equal(isProbablyPiInputLine("  ┃ edit me"), true);
+	assert.equal(isProbablyPiInputLine("  │ second line"), true);
+	assert.equal(isProbablyPiInputLine("› draft"), true);
+});
+
+test("isProbablyPiInputLine rejects content lines and empty lines", () => {
+	assert.equal(isProbablyPiInputLine("chat content"), false);
+	assert.equal(isProbablyPiInputLine("────── ◊◊ ──────"), false);
+	assert.equal(isProbablyPiInputLine(""), false);
+	assert.equal(isProbablyPiInputLine("   "), false);
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `node --test test/pty-input.test.mjs`
+Expected: FAIL — `isProbablyPiInputLine is not a function` (import error).
+
+- [ ] **Step 3: Write minimal implementation**
+
+Append to `src/core/pty-input.mjs` (before `isProbablyEmptyPiInputLine` or after — any top-level position):
+
+```js
+/** Glyphs Pi uses to render editor prompt / continuation lines (`>` main prompt,
+ * `›`/`┃`/`│` and variants in older releases). Must stay in sync with the
+ * trim charset of isProbablyEmptyPiInputLine below. */
+const PROMPT_GLYPHS = "›>┃│|┆╎╏:";
+
+/**
+ * Whether the given terminal line looks like a Pi editor input line: leading
+ * whitespace followed by a prompt/continuation glyph. The attach surface uses
+ * this to locate the editor line inside the buffer instead of trusting the
+ * terminal cursor, which wanders onto output/working lines while Pi streams
+ * (issue #66).
+ * @param {string} line
+ * @returns {boolean}
+ */
+export function isProbablyPiInputLine(line) {
+	const withoutLeftPadding = String(line || "").replace(/^[\s\u00a0]+/u, "");
+	return withoutLeftPadding.length > 0 && PROMPT_GLYPHS.includes(withoutLeftPadding[0]);
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `node --test test/pty-input.test.mjs`
+Expected: PASS (4 tests: 2 existing + 2 new).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add test/pty-input.test.mjs src/core/pty-input.mjs
+git commit -m "feat: add isProbablyPiInputLine helper (issue #66)"
+```
+
+---
+
+### Task 2: Rework `childInputLooksEmpty()` anchor + smoke scenarios
+
+**Files:**
+- Modify: `src/ui/pty-attach.ts` (import line ~8; `childInputLooksEmpty()` ~line 319; add private helper near it)
+- Modify: `test-support/detach-gate-smoke.ts` (scenarios B/B1/B2/B3 + new E)
+- Modify: `test/pty-attach-detach-gate.test.mjs` (assertions)
+
+**Interfaces:**
+- Consumes: `isProbablyPiInputLine` from Task 1; existing `isProbablyEmptyPiInputLine`.
+- Produces: private `findLastInverseCellLine(active): number | null` — bottom-most line index containing an `isInverse()` cell; `null` when none.
+
+- [ ] **Step 1: Write the failing smoke scenarios**
+
+In `test-support/detach-gate-smoke.ts`:
+
+1. Change scenario **B** (line ~76) so the draft line carries a fake cursor, then add B3 (cursor off the empty input line) and E (empty input line without fake cursor). Replace the current B block and append:
+
+```ts
+// B. ← must NOT detach while attached with a draft in the editor line (child
+// is mid-draft and ← is also the editor's cursor-left key). The draft line
+// carries Pi's inverse-video fake cursor (ESC[7m).
+{
+	const { attach, sent, didDetach } = makeAttach();
+	await writeToTerm(attach, "chat content\r\n> \x1b[7m草\x1b[27m稿");
+	(attach as unknown as { connected: boolean }).connected = true;
+	attach.handleInput("\x1b[D");
+	out.leftStaysGatedOnNonEmptyLine = !didDetach() && sent.length === 1 && sent[0].type === "input" && sent[0].data === "\x1b[D";
+	attach.dispose();
+}
+
+// B3. The streaming case from issue #66: the editor line is empty (bottom of
+// the buffer, with its fake cursor) but the terminal cursor rests on the
+// working line because Pi's differential frames only repaint the changed
+// line. The gate must be judged from the fake-cursor line, not the cursor.
+{
+	const { attach, sent, didDetach } = makeAttach();
+	await writeToTerm(attach, "chat content\r\n> \x1b[7m \x1b[27m");
+	await writeToTerm(attach, "\x1b[2;1H⠙ Working...");
+	(attach as unknown as { connected: boolean }).connected = true;
+	attach.handleInput("\x1b[D");
+	out.leftDetachesWhenCursorOffEmptyInputLine = didDetach() && sent.length === 0;
+	attach.dispose();
+}
+
+// E. Empty input line rendered WITHOUT a fake cursor: no inverse cell and no
+// glyph anywhere, and the terminal cursor sits on a non-empty output line.
+// Falls through to the escape fallback — treat as empty, detach.
+{
+	const { attach, sent, didDetach } = makeAttach();
+	await writeToTerm(attach, "chat content\r\n");
+	await writeToTerm(attach, "\x1b[1;1H"); // park the cursor on the non-empty line
+	(attach as unknown as { connected: boolean }).connected = true;
+	attach.handleInput("\x1b[D");
+	out.leftDetachesOnEmptyInputWithoutFakeCursor = didDetach() && sent.length === 0;
+	attach.dispose();
+}
+```
+
+2. Update the B1 header comment (scenario text already fits) and ensure B1 (`────── ◊◊ ──────` garbled buffer) stays as-is — it now asserts escape-on-garbled-buffer.
+
+- [ ] **Step 2: Run smoke to verify new scenarios fail**
+
+Run: `node --experimental-transform-types test-support/detach-gate-smoke.ts`
+Expected: `leftDetachesWhenCursorOffEmptyInputLine` is `false` (old cursor-line anchor reads the Working line) and `leftDetachesOnEmptyInputWithoutFakeCursor` is `false` (old anchor reads last non-empty line `chat content`? — verify output); `leftStaysGatedOnNonEmptyLine` true.
+
+- [ ] **Step 3: Write the implementation**
+
+In `src/ui/pty-attach.ts`:
+
+1. Update import (line ~8):
+
+```ts
+import { isProbablyEmptyPiInputLine, isProbablyPiInputLine } from "../core/pty-input.mjs";
+```
+
+2. Replace the `childInputLooksEmpty()` method (currently ~line 319) and add the helper above it:
+
+```ts
+	/** Bottom-most line whose cells include an inverse-video cell — Pi renders
+	 * its editor cursor as an inverse "fake cursor" (`ESC[7m`), and the cell
+	 * persists in the buffer even while streaming differential frames skip
+	 * repainting the editor line. */
+	private findLastInverseCellLine(active: {
+		baseY: number;
+		length: number;
+		getLine(index: number): BufferLineLike | undefined;
+	}): number | null {
+		for (let y = active.baseY + active.length - 1; y >= active.baseY; y--) {
+			const line = active.getLine(y);
+			if (!line) continue;
+			for (let x = 0; x < line.length; x++) {
+				if (line.getCell(x)?.isInverse()) return y;
+			}
+		}
+		return null;
+	}
+
+	private childInputLooksEmpty(): boolean {
+		if (!this.receivedOutput) return true;
+		const active = this.term.buffer.active;
+		// The terminal cursor is not a reliable anchor for the editor line:
+		// while Pi streams output (or right after attach) the cursor rests on
+		// working/output lines, never the input line, so a genuinely empty
+		// editor was misread as non-empty and ← stopped detaching (issue #66).
+		// Pi's editor line always carries an inverse-video fake-cursor cell,
+		// so anchor on that instead.
+		const fakeCursorLine = this.findLastInverseCellLine(active);
+		if (fakeCursorLine !== null) {
+			const line = active.getLine(fakeCursorLine)?.translateToString(true) ?? "";
+			return isProbablyEmptyPiInputLine(line);
+		}
+		// Fallback: Pi variants that render no fake cursor — look for a
+		// prompt-glyph line.
+		for (let y = active.baseY + active.length - 1; y >= active.baseY; y--) {
+			const line = active.getLine(y)?.translateToString(true) ?? "";
+			if (isProbablyPiInputLine(line)) return isProbablyEmptyPiInputLine(line);
+		}
+		// No editor line recoverable (e.g. a garbled replay buffer): treat the
+		// input as empty — ← is the only detach key left on the attach surface,
+		// so it must always escape rather than trap the user.
+		return true;
+	}
+```
+
+- [ ] **Step 4: Update gate assertions**
+
+In `test/pty-attach-detach-gate.test.mjs`, add to the existing test (after `leftDetachesOnEmptyInput`):
+
+```js
+	assert.equal(parsed.leftDetachesWhenCursorOffEmptyInputLine, true, "← must detach when the editor line is empty even if the cursor sits on a working line");
+	assert.equal(parsed.leftDetachesOnEmptyInputWithoutFakeCursor, true, "← must detach when an empty editor line renders no fake cursor");
+```
+
+- [ ] **Step 5: Run tests to verify pass**
+
+Run: `node --test test/pty-attach-detach-gate.test.mjs test/pty-input.test.mjs`
+Expected: PASS — all gate assertions true, including the three new ones.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/ui/pty-attach.ts test-support/detach-gate-smoke.ts test/pty-attach-detach-gate.test.mjs
+git commit -m "fix: anchor ← detach gate on Pi's fake-cursor line, not terminal cursor (issue #66)"
+```
+
+---
+
+### Task 3: Full regression (A6)
+
+**Files:** none (verification only).
+
+- [ ] **Step 1: Run verify**
+
+Run (in worktree): `npm run verify`
+Expected: typecheck clean; all `node --test test/*.test.mjs` pass (325+ tests, none of the pre-existing ones changed semantics); c8 coverage above gates (lines ≥85 / funcs ≥80 / branches ≥70); `npm pack --dry-run` succeeds.
+
+- [ ] **Step 2: Commit any incidental fixes**
+
+If verify surfaced issues, fix and commit with a message referencing issue #66. Otherwise nothing to commit.
+
+---
+
+### Task 4: Post-implementation manual verification (U1, U2)
+
+**Files:** none (user verification; report back into the PR).
+
+- [ ] **Step 1: U1 — attach-then-←**
+
+1. Start agent-board, attach into an existing pi session (or create a new one).
+2. As soon as the attach surface paints, press `←`.
+Expected: returns to the dashboard immediately, no ↑/↓ or type-then-delete needed.
+
+- [ ] **Step 2: U2 — ← while Pi is thinking**
+
+1. Attach into a session and send a prompt that triggers Pi streaming (`⠹ Working...` animation visible).
+2. While the animation is running, press `←`.
+Expected: returns to the dashboard. (Fails before this fix — the exact reported symptom.)
+
+- [ ] **Step 3: Sanity — ← does not steal the editor's cursor-left**
+
+1. Attach, type a draft in the input box.
+2. Press `←`.
+Expected: cursor moves left inside the draft (key forwarded), NOT detach.
+
+- [ ] **Step 4: Record results**
+
+Write the U1/U2/U3 outcomes into the PR description (or a PR comment) before merge.