@huseynsnmz/pi-board 0.15.3 → 0.16.0

package/docs/superpowers/plans/2026-09-03-detach-gate-glyph-fallback.md

@@ -1,146 +0,0 @@
-# Detach-Gate Tier-2 Glyph Fallback Tightening 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:** Tighten the attach-surface `←` detach gate's tier-2 glyph fallback so content glyph lines (markdown table rows / quotes / drafts) no longer trap the user when `editor_state` is unavailable (issue #69).
-
-**Architecture:** One-line condition change in `PtyAttachComponent.childInputLooksEmpty()` (src/ui/pty-attach.ts): the tier-2 loop now only treats an EMPTY prompt-glyph line as proof of an empty editor (`isProbablyPiInputLine(line) && isProbablyEmptyPiInputLine(line)`), skipping content glyph lines; loop-end escape stays authoritative. Tier-1 (inverse fake-cursor anchor), the `editor_state` authoritative path (#71), and all protocol/public API surfaces are untouched. Behavior is pinned by two new detach-gate smoke scenarios (K1/K2) asserted inside the existing `test/pty-attach-detach-gate.test.mjs` case.
-
-**Tech Stack:** TypeScript (Node `--experimental-transform-types`), node:test, @xterm/headless in-memory smoke harness.
-
-**Spec:** `docs/superpowers/specs/2026-09-03-detach-gate-glyph-fallback-design.md` (accepted 2026-09-03, Option B).
-
-**Acceptance traceability:** Task 1 → A1, A2, A3, A4 (automated). Task 2 → U1, U2 (manual, human-executed after push, before merge). No orphan tasks, no orphan acceptance IDs.
-
-## Global Constraints
-
-- Work only inside this worktree: `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-69-detach-gate-glyph-fallback`. Never edit the main checkout at `/home/elling/git-repo/github/pi-agent-board` (`node_modules` there is only the read-only symlink target).
-- Commit messages: English, conventional commits, suffix `(issue #69)`.
-- Stage files explicitly (`git add <file> ...`); never `git add -A`.
-- Do NOT touch: tier-1 inverse anchor, `editor_state` path (`resolveEditorEmpty`, reporter, runner), README.md, or the pure helpers in `src/core/pty-input.mjs` (spec non-goals).
-- Do NOT extract new pure functions — the tightened tier-2 is constant-true by design; the discriminating tests live at smoke level (spec §4).
-- Every new online-gate smoke scenario MUST pin `connected=true` explicitly before `handleInput` (B-section convention; otherwise the disconnected-escape semantics fire instead of the online gate).
-- `node --test` case count stays 437: the new smoke keys are assertions inside the existing test case in `test/pty-attach-detach-gate.test.mjs`, not new `test()` blocks.
-- Verification commands: `npm test` (expect 437 pass, 0 fail) and `npm run typecheck` (expect 0 errors). Faster smoke-only loop: `node --experimental-transform-types test-support/detach-gate-smoke.ts` (prints a JSON of scenario keys).
-
----
-
-### Task 1: Tighten tier-2 glyph fallback (TDD) — covers A1, A2, A3, A4
-
-**Files:**
-- Modify: `src/ui/pty-attach.ts` (the tier-2 loop inside `childInputLooksEmpty()`, right after the `// Fallback: Pi variants that render no fake cursor` comment, line 359)
-- Test: `test-support/detach-gate-smoke.ts` (insert two scenarios after the J-scenario block, before the `// E2.` comment)
-- Test: `test/pty-attach-detach-gate.test.mjs` (two assertions after the `leftHelloNullResetsStaleEditorState` assertion)
-
-**Interfaces:**
-- Consumes: `isProbablyPiInputLine(line)`, `isProbablyEmptyPiInputLine(line)` from `src/core/pty-input.mjs` (both already imported in `pty-attach.ts`); smoke harness helpers `makeAttach()`, `writeToTerm(attach, data)` (already defined in the smoke file).
-- Produces: smoke output keys `leftDetachesOnTableRowsWithoutFakeCursor` (A1) and `leftDetachesOnContentGlyphFallback` (A2) in the JSON printed by `test-support/detach-gate-smoke.ts`.
-
-- [ ] **Step 1: Write the failing smoke scenarios (A1, A2)**
-
-In `test-support/detach-gate-smoke.ts`, insert these two blocks immediately BEFORE the line starting with `// E2. A terminal at the minimum supported size`:
-
-```ts
-// K1. Issue #69 real-world shape: zero inverse cells anywhere in the buffer,
-// the chat area carries a markdown table row (`│ … │`) and a quote line
-// (`> …`) that isProbablyPiInputLine misreads as a draft-bearing input line,
-// and editor_state never arrives (editorEmpty stays null — child without the
-// reporter). tier-2 must skip content glyph lines and ← must detach: the
-// gate philosophy is "never trap the user" (issues #42/#48).
-{
-	const { attach, sent, didDetach } = makeAttach();
-	await writeToTerm(attach, "chat content\r\n│ Issue #778 │ open │\r\n> quote line\r\n");
-	(attach as unknown as { connected: boolean }).connected = true;
-	attach.handleInput("\x1b[D");
-	out.leftDetachesOnTableRowsWithoutFakeCursor = didDetach() && sent.length === 1 && sent[0].type === "detach";
-	attach.dispose();
-}
-
-// K2. The deliberate flip side of K1 — pair with scenario B: the SAME draft
-// shape (`> draft`) is gated when the fake cursor is present (tier-1, scenario
-// B) but detaches when the buffer carries no inverse cells (tier-2 fallback
-// cannot tell a real draft from a table row; a spurious detach beats a trapped
-// user, and detach never loses the draft — the child session keeps running).
-// This pins the intentional loss of fallback draft protection (issue #69);
-// restoring it needs the mid-term dock-structure anchor, not a revert.
-{
-	const { attach, sent, didDetach } = makeAttach();
-	await writeToTerm(attach, "chat content\r\n> draft\r\n");
-	(attach as unknown as { connected: boolean }).connected = true;
-	attach.handleInput("\x1b[D");
-	out.leftDetachesOnContentGlyphFallback = didDetach() && sent.length === 1 && sent[0].type === "detach";
-	attach.dispose();
-}
-```
-
-In `test/pty-attach-detach-gate.test.mjs`, insert these two assertions immediately AFTER the `assert.equal(parsed.leftHelloNullResetsStaleEditorState, true, ...)` line:
-
-```js
-	assert.equal(parsed.leftDetachesOnTableRowsWithoutFakeCursor, true, "← must detach when a zero-inverse buffer holds only table/quote glyph lines and editor_state is unknown (issue #69)");
-	assert.equal(parsed.leftDetachesOnContentGlyphFallback, true, "← must detach on a content glyph line in the no-fake-cursor fallback — spurious detach beats trapping (issue #69)");
-```
-
-- [ ] **Step 2: Run to verify both fail (A1, A2 red)**
-
-Run: `node --experimental-transform-types test-support/detach-gate-smoke.ts`
-Expected: JSON contains `"leftDetachesOnTableRowsWithoutFakeCursor":false` and `"leftDetachesOnContentGlyphFallback":false` (all pre-existing keys stay `true`).
-
-- [ ] **Step 3: Implement the tier-2 tightening (minimal change)**
-
-In `src/ui/pty-attach.ts`, inside `childInputLooksEmpty()`, replace this exact block:
-
-```ts
-		// 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);
-		}
-```
-
-with:
-
-```ts
-		// Fallback: Pi variants that render no fake cursor — look for an EMPTY
-		// prompt-glyph line. Only an empty glyph line proves an empty editor:
-		// content glyph lines (markdown table rows `│ … │`, quotes `> …`, or a
-		// real draft in a no-fake-cursor Pi variant) cannot be told apart, and
-		// trapping the user is worse than a spurious detach (issue #69) — skip
-		// them and keep scanning; the loop-end escape below stays authoritative.
-		for (let y = active.baseY + active.length - 1; y >= active.baseY; y--) {
-			const line = active.getLine(y)?.translateToString(true) ?? "";
-			if (isProbablyPiInputLine(line) && isProbablyEmptyPiInputLine(line)) return true;
-		}
-```
-
-- [ ] **Step 4: Run smoke to verify the fix (A1, A2 green)**
-
-Run: `node --experimental-transform-types test-support/detach-gate-smoke.ts`
-Expected: EVERY key in the JSON is `true`, including the two new ones.
-
-- [ ] **Step 5: Full automated acceptance (A3, A4)**
-
-Run: `npm test`
-Expected: `pass 437`, `fail 0` (count unchanged — the new keys are assertions inside the existing test case).
-
-Run: `npm run typecheck`
-Expected: exit 0, no output errors.
-
-- [ ] **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: tighten ← detach tier-2 glyph fallback to empty-only lines (issue #69)"
-```
-
-### Task 2: Manual verification U1/U2 (human-executed; after PR branch is pushed, before merge) — covers U1, U2
-
-> Not a subagent task. The controller surfaces this checklist to the human partner at the pre-merge gate.
-
-**Environment:** the running extension copy is the git-source clone at `~/.pi/agent/git/github.com/zhuxixi/pi-agent-board` (currently at 0.5.1 / fac9e91). Steps:
-
-- [ ] **Step 1:** `git -C ~/.pi/agent/git/github.com/zhuxixi/pi-agent-board fetch origin && git -C ~/.pi/agent/git/github.com/zhuxixi/pi-agent-board checkout issue-69-detach-gate-glyph-fallback`
-- [ ] **Step 2:** Restart pi IN ANOTHER TERMINAL (restarting kills the session running this agent — do not run inside the controlling session's pi instance).
-- [ ] **Step 3 (U1):** Open dashboard → attach a warm session whose chat area contains markdown table output (`│ … │` rows) → with an empty input box press `←`. Pass = returns to dashboard, not trapped.
-- [ ] **Step 4 (U2):** In the same or another reporter-active hosted session, type a draft → press `←`. Pass = cursor moves left inside the draft, no detach (same as #67 U3).
-- [ ] **Step 5:** `git -C ~/.pi/agent/git/github.com/zhuxixi/pi-agent-board checkout main` and restart pi to restore the running copy.

package/docs/superpowers/plans/2026-09-04-evidence-outputpreview.md

@@ -1,209 +0,0 @@
-# Evidence outputPreview Extraction 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 `evidence.json` `commands[].outputPreview` storing `[object Object]` for bash tool results by extracting text from pi's `AgentToolResult.content` blocks (issue #41).
-
-**Architecture:** New pure function `toolResultText(result)` in `src/core/heuristics.mjs` (symmetric with existing `assistantText`); `reduceEvidence` bash branch swaps `String(event.result ?? "")` for it. No data-structure changes, no migration.
-
-**Tech Stack:** Node.js ESM, `node:test`, JSDoc types checked by `tsc --noEmit`.
-
-**Spec:** `docs/superpowers/specs/2026-09-04-evidence-outputpreview-design.md` (acceptance IDs A1/A2/A3/U1 referenced below).
-
-## Global Constraints
-
-- All edits under worktree `$WT=/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-41-evidence-outputpreview-object`; git via `git -C $WT` — never touch main checkout.
-- `toolResultText` must stay a pure function with zero side effects; do NOT inline it into `reduceEvidence` (spec §3 hard constraint).
-- Unknown-shaped objects must yield `""`, never `"[object Object]"` (spec D2, #40's 宁可不显示也不错显示 principle).
-- Legacy string `result` must keep passing through unchanged (spec D5).
-- Do NOT change the 500-char truncate, `EvidenceCommand` shape, other tools' branches, or powershell handling (spec §5 non-goals).
-- Stage files individually with `git -C $WT add <file>`; never `git add -A`.
-- Full gate per task end: `npm run verify` (typecheck + test + coverage + pack:dry). Never `npm test -- <file>` (glob expands to full suite anyway).
-
----
-
-### Task 1: `toolResultText` pure function (acceptance: A1)
-
-**Files:**
-- Modify: `src/core/heuristics.mjs` (after `assistantText`, line ~26)
-- Test: `test/heuristics.test.mjs`
-
-**Interfaces:**
-- Produces: `toolResultText(result: any): string` — exported from `src/core/heuristics.mjs`. Task 2 imports it in `src/core/evidence.mjs`.
-- Behavior table (spec D2): `null/undefined → ""`; `string → passthrough`; object with `content` array → text blocks `join("\n")` trimmed; object without content/text → `""`; number/bool → `String()`.
-
-- [ ] **Step 1: Write the failing tests**
-
-Append to `test/heuristics.test.mjs`, and add `toolResultText` to the existing import block from `../src/core/heuristics.mjs`:
-
-```js
-test("toolResultText extracts text blocks from AgentToolResult", () => {
-	const result = {
-		content: [
-			{ type: "text", text: "line1" },
-			{ type: "image", data: "AAAA", mimeType: "image/png" },
-			{ type: "text", text: "line2" },
-		],
-		details: { fullOutputPath: "/tmp/pi-bash-x.log" },
-	};
-	assert.equal(toolResultText(result), "line1\nline2");
-});
-
-test("toolResultText returns empty string for image-only content", () => {
-	assert.equal(toolResultText({ content: [{ type: "image", data: "AAAA", mimeType: "image/png" }] }), "");
-});
-
-test("toolResultText returns empty string for object without content array", () => {
-	assert.equal(toolResultText({ details: {} }), "");
-	assert.equal(toolResultText({}), "");
-});
-
-test("toolResultText passes through plain strings (legacy events)", () => {
-	assert.equal(toolResultText("ok"), "ok");
-});
-
-test("toolResultText handles nullish and scalar inputs", () => {
-	assert.equal(toolResultText(null), "");
-	assert.equal(toolResultText(undefined), "");
-	assert.equal(toolResultText(42), "42");
-	assert.equal(toolResultText(true), "true");
-});
-```
-
-- [ ] **Step 2: Run tests to verify they fail**
-
-Run: `cd $WT && node --test test/heuristics.test.mjs`
-Expected: FAIL — `toolResultText is not defined` / import error.
-
-- [ ] **Step 3: Implement `toolResultText` in `src/core/heuristics.mjs`**
-
-Insert after the existing `assistantText` function:
-
-```js
-/**
- * Extract text from a pi AgentToolResult object
- * ({ content: [{ type: "text", text }, ...], details, ... }), or, defensively,
- * a plain string. Unknown-shaped objects yield "" — never "[object Object]"
- * (issue #41; mirrors pi's own convertToolResultOutput join("\n") semantics).
- * @param {any} result
- * @returns {string}
- */
-export function toolResultText(result) {
-	if (result == null) return "";
-	if (typeof result === "string") return result;
-	if (typeof result !== "object") return String(result);
-	const content = result.content;
-	if (!Array.isArray(content)) return "";
-	return content
-		.filter((b) => b && b.type === "text" && typeof b.text === "string")
-		.map((b) => b.text)
-		.join("\n")
-		.trim();
-}
-```
-
-- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `cd $WT && node --test test/heuristics.test.mjs`
-Expected: PASS (all 5 new tests + pre-existing suite).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git -C $WT add test/heuristics.test.mjs src/core/heuristics.mjs
-git -C $WT commit -m "feat: add toolResultText extractor for AgentToolResult content (issue #41)"
-```
-
----
-
-### Task 2: `reduceEvidence` bash branch uses `toolResultText` (acceptance: A2, A3)
-
-**Files:**
-- Modify: `src/core/evidence.mjs` (import line 2; bash branch line ~196)
-- Test: `test/evidence.test.mjs`
-
-**Interfaces:**
-- Consumes: `toolResultText(result: any): string` from Task 1.
-- Produces: unchanged `EvidenceCommand` shape; `outputPreview` now carries extracted text.
-
-- [ ] **Step 1: Write the failing test (real AgentToolResult shape)**
-
-In `test/evidence.test.mjs`, inside the existing top-level test that builds `snap` (after the current `b1` end event at line ~24), append:
-
-```js
-	reduceEvidence(snap, { type: "tool_execution_end", toolCallId: "b2", toolName: "bash", isError: false, result: { content: [{ type: "text", text: "https://github.com/zhuxixi/pi-agent-board/pull/45" }] } }, 31);
-```
-
-and alongside the existing assertions:
-
-```js
-	assert.equal(snap.commands.find((c) => c.id === "b2").outputPreview, "https://github.com/zhuxixi/pi-agent-board/pull/45");
-```
-
-(The pre-existing `b1` fixture with `result: "ok"` stays untouched — its `outputPreview` passthrough is the D5 regression guard.)
-
-**Assertion ripple:** the new `b2` command raises the command count. In the same test, update the tail assertion:
-
-```js
-	assert.equal(summary.commandCount, 2);
-```
-
-(was `assert.equal(summary.commandCount, 1);`)
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `cd $WT && node --test test/evidence.test.mjs`
-Expected: FAIL — `outputPreview` is `"[object Object]"` instead of the URL.
-
-- [ ] **Step 3: Modify `src/core/evidence.mjs`**
-
-Import line (currently):
-
-```js
-import { assistantText, classifyCommand, toolFileOperation, truncate } from "./heuristics.mjs";
-```
-
-becomes:
-
-```js
-import { assistantText, classifyCommand, toolFileOperation, toolResultText, truncate } from "./heuristics.mjs";
-```
-
-In `reduceEvidence`, `tool_execution_end` → `name === "bash"` branch, replace exactly this line:
-
-```js
-				outputPreview: truncate(String(event.result ?? ""), 500),
-```
-
-with:
-
-```js
-				outputPreview: truncate(toolResultText(event.result), 500),
-```
-
-- [ ] **Step 4: Run tests to verify they pass**
-
-Run: `cd $WT && node --test test/evidence.test.mjs`
-Expected: PASS — new assertion green AND legacy `"ok"` fixture still green (D5).
-
-- [ ] **Step 5: Full verify gate**
-
-Run: `cd $WT && npm run verify`
-Expected: PASS — typecheck, full test suite, coverage, pack:dry all green.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git -C $WT add src/core/evidence.mjs test/evidence.test.mjs
-git -C $WT commit -m "fix: extract evidence outputPreview from AgentToolResult content (issue #41)"
-```
-
----
-
-### Task 3: Post-merge manual verification (acceptance: U1, user-verified)
-
-**Trigger:** after PR merge + board reloads the new extension on next pi session start.
-
-- [ ] **Step 1:** In a real pi session, run a few bash commands (e.g. `gh pr create`, `git log`).
-- [ ] **Step 2:** Inspect `~/.pi/agent/agent-board/views/<view>/evidence.json`.
-- [ ] **Step 3:** Pass criteria: newly recorded bash commands show real output text in `outputPreview` (e.g. the `gh pr create` URL); no new `[object Object]` entries. Record observation result back on issue #41.