@huseynsnmz/pi-board 0.15.3 → 0.17.0

package/docs/superpowers/plans/2026-10-28-issue-257-legacy-pty-runner-endpoint-cleanup.md

@@ -1,256 +0,0 @@
-# Issue #257 — Legacy pty-runner endpoint cleanup: Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use subagent-driven-development (recommended) or executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** A legacy PTY runner never deletes an endpoint it no longer owns, while still cleaning up its own on a normal shutdown.
-
-**Architecture:** Inside `legacyMain` only: record `{dev,ino}` at listen, stop calling `server.close()` (libuv unlinks the bind path on handle close — `nodejs/node#19729`), and gate the explicit unlink on the existing pure `ownsEndpoint`. No new pure functions, no protocol change.
-
-**Tech Stack:** Node ESM (`.mjs`), `node:test` + `assert/strict`, existing `pty-runner.integration.test.mjs` fixtures.
-
-**Spec:** `docs/superpowers/specs/2026-10-28-issue-257-legacy-pty-runner-endpoint-cleanup-design.md` (converged after 2 cross-review rounds; findings trail in `~/.github-issue-driven/zhuxixi/pi-agent-board/issue-257/research/`)
-
-## Global Constraints
-
-- POSIX-only behaviour; all new assertions guarded by `process.platform === "win32"` → `t.skip("POSIX AF_UNIX only")`.
-- New test titles MUST be exactly `#257 A<n>: <summary>`; A1's selector anchors on `#257 A1:` because `#257 A1` is a prefix of `#257 A1b`.
-- Do not touch `ownedMain` (out of scope) or the legacy boot-time unlink at `:140-142`.
-- Tabs for indentation; English comments; conventional commit subjects with `(issue #257)`.
-- Local Windows has no WSL/Docker: A1/A1b/A2 show as `skip` locally and execute on Linux CI only. `node --test --test-name-pattern="zzz"` exits 0 — always read the summary line, never the exit code alone.
-
-## Review Focus
-
-- A legacy shutdown after the path was replaced must leave the replacement intact (the bug).
-- A legacy normal shutdown must still remove its own socket (no stale-socket regression).
-- The identity must be captured before `state: "alive"` is published, or `hostReady` is not a barrier.
-- Removing `server.close()` must not change shutdown timing/child handling.
-- win32: no identity is captured; the cleanup degrades to a no-op (named pipes never unlink).
-
----
-
-### Task 1: legacyMain identity + no-close + gated unlink, with the three integration cases
-
-**Files:**
-- Modify: `runner/pty-runner.mjs` (`legacyMain`: identity holder, listen callback at `:409`, `shutdown` at `:503-531`)
-- Test: `test/pty-runner.integration.test.mjs` (append three tests; file already imports `statSync`, `createServer`, `spawn`, `P`, `createView`, `readHost`, `atomicWriteJson`, and has `freshRoot`/`waitFor`/`hostReady`)
-
-**Interfaces:**
-- Consumes: `ownsEndpoint(bound, current)` (already imported at `runner/pty-runner.mjs:20`), `P.controlSocketPath(root, viewId)`, `P.hostConfigPath(root, viewId)`.
-- Produces: nothing exported; `boundSocketIdentity` becomes a `legacyMain`-local variable; diagnostic `coordinator_endpoint_lost` is NOT used here (that is the coordinator path).
-
-- [ ] **Step 1: Write the three failing tests**
-
-Append to `test/pty-runner.integration.test.mjs` (use the exact helper names already in the file):
-
-```js
-/** Shared fixture: boot a legacy runner (host-config WITHOUT instanceId). */
-async function bootLegacyRunner(t, viewId = "v1") {
-	const root = freshRoot();
-	const meta = createView(root, { id: viewId, name: "legacy-endpoint", cwd: process.cwd() });
-	const configPath = P.hostConfigPath(root, viewId);
-	atomicWriteJson(configPath, {
-		root,
-		viewId,
-		sessionFile: meta.sessionFile,
-		cwd: process.cwd(),
-		initialPrompt: null,
-		piCommand: process.execPath,
-		piArgsPrefix: [resolve("test-support/fake-pty-pi.mjs")],
-		model: null,
-		tools: null,
-		env: { AGENT_BOARD_ALLOW_PIPE_FALLBACK: "1" },
-		cols: 80,
-		rows: 24,
-	});
-	const runner = spawn(process.execPath, [resolve("runner/pty-runner.mjs"), configPath], {
-		stdio: ["ignore", "pipe", "pipe"],
-	});
-	runner.stdout.resume();
-	runner.stderr.resume();
-	await waitFor(() => hostReady(root, viewId));
-	return { root, runner, socketPath: P.controlSocketPath(root, viewId) };
-}
-
-function waitExit(child, timeoutMs = 5000) {
-	return new Promise((done) => {
-		if (child.exitCode !== null) return done(child.exitCode);
-		const timer = setTimeout(() => done(null), timeoutMs);
-		child.once("exit", (code) => { clearTimeout(timer); done(code); });
-	});
-}
-
-test("#257 A1: a legacy runner cleans up its own endpoint on SIGTERM", async (t) => {
-	if (process.platform === "win32") return t.skip("POSIX AF_UNIX only");
-	const { root, runner, socketPath } = await bootLegacyRunner(t);
-	try {
-		assert.ok(existsSync(socketPath), "precondition: endpoint exists before SIGTERM");
-		runner.kill("SIGTERM");
-		const code = await waitExit(runner);
-		assert.equal(code, 0, "clean SIGTERM exit");
-		assert.equal(existsSync(socketPath), false, "normal shutdown removes its own endpoint");
-	} finally {
-		if (runner.exitCode === null) runner.kill("SIGKILL");
-		rmSync(root, { recursive: true, force: true });
-	}
-});
-
-test("#257 A1b: a legacy runner exits cleanly when the endpoint is already gone", async (t) => {
-	if (process.platform === "win32") return t.skip("POSIX AF_UNIX only");
-	const { root, runner, socketPath } = await bootLegacyRunner(t);
-	try {
-		assert.ok(existsSync(socketPath), "precondition: endpoint exists");
-		unlinkSync(socketPath);
-		runner.kill("SIGTERM");
-		const code = await waitExit(runner);
-		assert.equal(code, 0, "ENOENT at cleanup must not crash the shutdown");
-	} finally {
-		if (runner.exitCode === null) runner.kill("SIGKILL");
-		rmSync(root, { recursive: true, force: true });
-	}
-});
-
-test("#257 A2: a legacy runner does not unlink a replaced endpoint", async (t) => {
-	if (process.platform === "win32") return t.skip("POSIX AF_UNIX only");
-	const { root, runner, socketPath } = await bootLegacyRunner(t);
-	const standinPath = join(root, `.standin-${process.pid}.sock`);
-	let standin = null;
-	try {
-		assert.ok(existsSync(socketPath), "precondition: endpoint exists");
-		const before = statSync(socketPath).ino;
-		standin = createServer(() => {});
-		await new Promise((ok, fail) => {
-			standin.once("error", fail);
-			standin.listen(standinPath, ok);
-		});
-		renameSync(standinPath, socketPath); // atomic, same filesystem
-		assert.notEqual(statSync(socketPath).ino, before, "stand-in really replaced the inode");
-		runner.kill("SIGTERM");
-		const code = await waitExit(runner);
-		assert.equal(code, 0, "clean SIGTERM exit");
-		assert.ok(existsSync(socketPath), "a legacy runner must not unlink an endpoint it no longer owns");
-	} finally {
-		if (runner.exitCode === null) runner.kill("SIGKILL");
-		if (standin) await new Promise((done) => standin.close(done));
-		rmSync(root, { recursive: true, force: true });
-	}
-});
-```
-
-New imports needed at the top of the file: `unlinkSync`, `renameSync` (add to the `node:fs` import at `:2`).
-
-- [ ] **Step 2: Run them (local: expect skip; Linux CI: expect A2 red)**
-
-Run: `node --test --test-name-pattern="#257 A" test/pty-runner.integration.test.mjs`
-Local Windows: `tests 3 / skipped 3` (documented channel limit). Linux: A1/A1b pass, **A2 fails**
-(`a legacy runner must not unlink an endpoint it no longer owns`) because the old shutdown's
-`server.close()` and unconditional unlink both delete the stand-in. Record the observed
-summary in the ledger either way.
-
-- [ ] **Step 3: Implement the three changes in `legacyMain`**
-
-In `runner/pty-runner.mjs`, inside `legacyMain` (after `let shutdownExitCode = null;`):
-
-```js
-	/** {dev,ino} recorded at bind time; cleanup unlinks only this exact inode. */
-	let boundSocketIdentity = null;
-```
-
-Replace the `server.listen(...)` call at `:409` with:
-
-```js
-	server.listen(socketPath, () => {
-		// Capture the identity BEFORE publishing readiness: "host ready" must imply
-		// "identity recorded", or a shutdown could run with a stale/null identity.
-		if (process.platform !== "win32") {
-			try {
-				const st = statSync(socketPath);
-				boundSocketIdentity = { dev: st.dev, ino: st.ino };
-			} catch { /* without the identity, cleanup degrades to a no-op */ }
-		}
-		update({ socketPath, state: "alive" });
-	});
-```
-
-In `shutdown()`, replace:
-
-```js
-		try { server?.close(); } catch {}
-		try { if (existsSync(socketPath)) unlinkSync(socketPath); } catch {}
-```
-
-with:
-
-```js
-		// Do NOT call server.close() (issue #257, nodejs/node#19729): libuv unlinks the
-		// unix-socket bind path when the listening handle closes, so a shutdown after a
-		// successor bound would delete the successor's endpoint. There is no close here,
-		// so the implicit unlink never runs. Cleanup is explicit and identity-gated below
-		// (the legacy path has no lease, so dev+ino is its only ownership proof).
-		if (process.platform !== "win32" && boundSocketIdentity) {
-			try {
-				const st = statSync(socketPath);
-				if (ownsEndpoint(boundSocketIdentity, { dev: st.dev, ino: st.ino })) {
-					try { unlinkSync(socketPath); } catch { /* best effort */ }
-				}
-			} catch { /* path gone — nothing to clean */ }
-		}
-```
-
-- [ ] **Step 4: Run the cases again**
-
-Run: `node --test --test-name-pattern="#257 A" test/pty-runner.integration.test.mjs`
-Local Windows: `tests 3 / skipped 3` and exit 0 — read the summary, confirm 3 skipped (not 0 tests).
-Linux CI: `tests 3 / pass 3`.
-
-- [ ] **Step 5: Run the existing pty-runner suite for regressions**
-
-Run: `node --test test/pty-runner.integration.test.mjs`
-Local expectation: everything that ran before still passes (the legacy/owned cases that are
-platform-independent). Linux CI: full pass. Any new failure must be understood before commit.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add runner/pty-runner.mjs test/pty-runner.integration.test.mjs
-git commit -m "fix(runner): stop legacy pty-runner from unlinking a replaced endpoint (issue #257)"
-```
-
----
-
-### Task 2: Full verification and local code review
-
-**Files:** none (verification + review); modify only if a gate fails.
-
-**Interfaces:** consumes Task 1.
-
-- [ ] **Step 1: Typecheck**
-
-Run: `npm run typecheck` — exit 0.
-
-- [ ] **Step 2: Targeted suites**
-
-Run: `node --test test/pty-runner.integration.test.mjs test/host-coordination.test.mjs test/locks.test.mjs`
-Local Windows: pass (POSIX cases skip). Linux CI: full pass.
-
-- [ ] **Step 3: Pre-PR gate**
-
-Run: `npm run test:coverage` (Linux CI authoritative; local Windows baseline is not the gate for
-POSIX cases), then `npm run test:perf && npm run pack:dry`, then `npm run verify`. Record actual
-results; a local failure caused by the known Windows platform gap must be named explicitly.
-
-- [ ] **Step 4: Fresh-context local code review**
-
-Dispatch a reviewer over `git diff main...HEAD` with the spec + this plan + the Review Focus
-list; disposition findings (Critical/Important → one fix pass with a failing test first; Minor →
-ledger). Commit only if files change.
-
----
-
-## Task ↔ acceptance traceability
-
-| Spec acceptance ID | Task |
-|---|---|
-| A1, A1b, A2 | Task 1 (Steps 1-6) |
-| A3 | Task 1 Step 5 + Task 2 Step 2 |
-| A4 | Task 2 Step 1 |
-| A5, A6 | Task 2 Step 3 (Linux CI authoritative) |

package/docs/superpowers/plans/2026-11-03-cwd-favorites-full-pool.md

@@ -1,266 +0,0 @@
-# cwd Picker Full-History Search — 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:** Make the launch-dialog cwd picker search the full ranked history instead of the top 8 entries (issue #262).
-
-**Architecture:** Remove the pre-filter truncation at the dashboard wiring layer and make `rankedCwdCandidates` uncapped by default; the picker's pure state machine and the 6-row render window stay unchanged. A TS probe drives the real `handleInput()` path so the truncation regression is pinned at the layer that owned the bug.
-
-**Tech Stack:** Node ESM `.mjs` core + TypeScript TUI (`src/ui/dashboard.ts`), `node:test` + `assert/strict`, Node `--experimental-transform-types` probes.
-
-## Global Constraints
-
-- `rankedCwdCandidates(root, limit = Number.POSITIVE_INFINITY)`: default returns every ranked entry; an explicit numeric `limit` still caps and still appends the home fallback afterwards (existing tests pass `limit = 2`, keep them green).
-- `src/ui/dashboard.ts` `openLaunchPicker` loads the pool with `existingCwdCandidates(rankedCwdCandidates(this.deps.root))` — no `, 8` and no other hard-coded cap.
-- Do not change `filterCwdCandidates`, `nextCwdPickerState`, `listDirectorySuggestions`, `browseTabCompletion`, `existingCwdCandidates`, the 6-row render window, or the ranking rule (count desc → lastUsed desc).
-- Non-goals: symlink directory enumeration in browse mode, fuzzy matching, manual favorites, `cwd-stats.json` format changes.
-- Tabs for indentation; English comments and commit subjects; conventional commit types.
-- Tests use `node:test` + `assert/strict`; acceptance commands are `node --test <file>` and `npm run verify` (typecheck + perf gate + tests + coverage + pack:dry).
-- Work from: `/home/elling/git-repo/github/pi-agent-board/.pi/worktrees/issue-262-cwd-favorites-full-pool`
-
----
-
-### Task 1: Uncapped ranked candidates (core)
-
-**Files:**
-- Modify: `src/core/cwd-stats.mjs:92-108`
-- Test: `test/cwd-stats.test.mjs` (append after the existing `rankedCwdCandidates appends home with its real count when sliced out by limit` test)
-
-**Interfaces:**
-- Consumes: `readCwdStats(root)` (already returns all entries), `os.homedir()`.
-- Produces: `rankedCwdCandidates(root, limit = Number.POSITIVE_INFINITY) -> Array<{path: string, count: number}>` — uncapped by default.
-
-- [ ] **Step 1: Write the failing test**
-
-Append to `test/cwd-stats.test.mjs`:
-
-```js
-test("rankedCwdCandidates defaults to the full history with no 8-entry cap (issue #262)", () => {
-	const root = freshRoot();
-	try {
-		const dirs = Array.from({ length: 10 }, (_, i) => `/dir-${String(i + 1).padStart(2, "0")}`);
-		writeViews(root, dirs.map((dir, i) => [`v${i}`, dir, 1000 - i]));
-		seedCwdStatsFromViews(root);
-		const ranked = rankedCwdCandidates(root);
-		assert.deepEqual(
-			ranked.slice(0, 10),
-			dirs.map((dir) => ({ path: dir, count: 1 })),
-		);
-		assert.equal(ranked.length, 11);
-		assert.deepEqual(ranked[10], { path: os.homedir(), count: 0 });
-	} finally {
-		rmSync(root, { recursive: true, force: true });
-	}
-});
-```
-
-- [ ] **Step 2: Run the test to verify it fails**
-
-Run: `node --test test/cwd-stats.test.mjs`
-Expected: the new test FAILS — `ranked.slice(0, 10)` has only 8 recorded dirs, then the home fallback at index 8 (`ranked.length` is 9, not 11).
-
-- [ ] **Step 3: Change the default limit**
-
-In `src/core/cwd-stats.mjs`, replace the function header and JSDoc:
-
-```js
-/**
- * Ranked candidates: count desc, then lastUsed desc; home appended at the
- * end when absent so the user's home dir is always one keystroke away.
- * `limit` is an optional cap for callers that explicitly want one; the
- * default returns the whole history so the launch picker can search it.
- * @param {string} root @param {number=} limit
- * @returns {Array<{path: string, count: number}>}
- */
-export function rankedCwdCandidates(root, limit = Number.POSITIVE_INFINITY) {
-```
-
-Leave the body unchanged: `rows.slice(0, Math.max(1, limit))` already treats `Infinity` as "no cap".
-
-- [ ] **Step 4: Run the test to verify it passes**
-
-Run: `node --test test/cwd-stats.test.mjs`
-Expected: PASS — all `cwd-stats` tests green, including the existing `limit = 2` cases.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/core/cwd-stats.mjs test/cwd-stats.test.mjs
-git commit -m "fix(cwd): stop capping ranked cwd candidates at 8 (issue #262)"
-```
-
----
-
-### Task 2: Dashboard loads the full pool + picker regression probe
-
-**Files:**
-- Modify: `src/ui/dashboard.ts:755`
-- Create: `test-support/cwd-favorites-pool-probe.ts`
-- Create: `test/dashboard-cwd-favorites-pool.test.mjs`
-- Test: `test/launch-options.test.mjs` (append)
-
-**Interfaces:**
-- Consumes: `rankedCwdCandidates(root)` (uncapped, Task 1), `existingCwdCandidates`, `nextCwdPickerState`, `DashboardComponent.openLaunchPicker`.
-- Produces: no new production API; the dashboard now stores the full existing ranked history in `launch.cwdRanked`.
-
-- [ ] **Step 1: Write the failing integration probe**
-
-Create `test-support/cwd-favorites-pool-probe.ts`:
-
-```ts
-// cwd favorites-pool probe (issue #262): seed more favorites than the legacy
-// 8-entry cap, then type a fragment of the lowest-ranked entry through the
-// public handleInput() path and report the picker state as JSON.
-// Run via `node --experimental-transform-types` (dashboard.ts uses TS
-// parameter properties). Not typechecked (tsconfig excludes test-support).
-import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { createService } from "../src/runtime/service.mjs";
-import { DashboardComponent } from "../src/ui/dashboard.ts";
-
-const root = mkdtempSync(join(tmpdir(), "agentview-cwd-pool-"));
-const entries: Record<string, { count: number; lastUsed: number }> = {};
-for (let i = 1; i <= 9; i++) {
-	const dir = join(root, `rank-${String(i).padStart(2, "0")}`);
-	mkdirSync(dir, { recursive: true });
-	entries[dir] = { count: 100 - i, lastUsed: 1000 - i };
-}
-const target = join(root, "work", "proj", "stability", "alert-automation");
-mkdirSync(target, { recursive: true });
-entries[target] = { count: 1, lastUsed: 1 };
-writeFileSync(join(root, "cwd-stats.json"), JSON.stringify({ version: 1, entries }));
-
-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: string, t: string) => t, bold: (t: string) => t, bg: (_c: string, t: string) => t };
-
-const dash = new DashboardComponent(tui, theme, {}, () => {}, {
-	service,
-	root,
-	defaultCwd: root,
-	availableModels: [],
-	currentModel: null,
-	currentThinkingLevel: "off",
-});
-
-// TS-private is runtime-accessible; input must be non-empty or
-// openLaunchDialog() bails back to list mode and launch stays null.
-dash.input = "go";
-dash.openLaunchDialog();
-dash.openLaunchPicker("cwd", "");
-for (const ch of "aler") dash.handleInput(ch);
-
-const out = { target, mode: dash.launch?.cwdPickerMode, suggestions: dash.launch?.cwdSuggestions };
-dash.dispose();
-console.log(JSON.stringify(out));
-```
-
-Create `test/dashboard-cwd-favorites-pool.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", "cwd-favorites-pool-probe.ts");
-
-test("cwd picker: favorites search covers entries ranked below the old 8-entry cap (issue #262)", () => {
-	// dashboard.ts uses TS parameter properties, which strip-only mode rejects;
-	// --experimental-transform-types handles them (Node 22.7+ / 24).
-	const out = execFileSync(process.execPath, ["--experimental-transform-types", PROBE], {
-		encoding: "utf8",
-		timeout: 30_000,
-	});
-	const r = JSON.parse(out);
-	assert.equal(r.mode, "favorites");
-	assert.deepEqual(r.suggestions, [r.target]);
-});
-```
-
-- [ ] **Step 2: Run the probe test to verify it fails**
-
-Run: `node --test test/dashboard-cwd-favorites-pool.test.mjs`
-Expected: FAIL — `mode` is `"browse"` and `suggestions` is `[]`, because `dashboard.ts:755` still passes `, 8` and the rank-10 target falls outside the pool.
-
-- [ ] **Step 3: Load the full pool in the dashboard**
-
-In `src/ui/dashboard.ts`, inside `openLaunchPicker`, replace:
-
-```ts
-				launch.cwdRanked = existingCwdCandidates(rankedCwdCandidates(this.deps.root, 8));
-```
-
-with:
-
-```ts
-				launch.cwdRanked = existingCwdCandidates(rankedCwdCandidates(this.deps.root));
-```
-
-- [ ] **Step 4: Run the probe test to verify it passes**
-
-Run: `node --test test/dashboard-cwd-favorites-pool.test.mjs`
-Expected: PASS — `mode === "favorites"` and `suggestions === [target]`.
-
-- [ ] **Step 5: Pin the state-machine semantics for long lists**
-
-Append to `test/launch-options.test.mjs`:
-
-```js
-test("nextCwdPickerState searches matches below the 8th ranked entry (issue #262)", () => {
-	const bigRanked = Array.from({ length: 12 }, (_, i) => ({
-		path: `/ranked/dir-${String(i + 1).padStart(2, "0")}`,
-		count: 100 - i,
-	}));
-	const state = nextCwdPickerState("dir-10", bigRanked, "/tmp");
-	assert.equal(state.mode, "favorites");
-	assert.deepEqual(state.suggestions, [bigRanked[9].path]);
-});
-```
-
-- [ ] **Step 6: Run the focused suites**
-
-Run: `node --test test/cwd-stats.test.mjs test/launch-options.test.mjs test/dashboard-cwd-favorites-pool.test.mjs test/dashboard-cwd-tab.test.mjs`
-Expected: PASS — new coverage plus the existing browse/favorites Tab regression (A4).
-
-- [ ] **Step 7: Run the full gate**
-
-Run: `npm run verify`
-Expected: PASS — typecheck, perf gate, full test suite, coverage thresholds, pack:dry.
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add src/ui/dashboard.ts test-support/cwd-favorites-pool-probe.ts test/dashboard-cwd-favorites-pool.test.mjs test/launch-options.test.mjs
-git commit -m "fix(cwd): search the full ranked history in the launch picker (issue #262)"
-```
-
----
-
-## Acceptance Traceability
-
-| Spec ID | Plan task | Verification in this plan |
-| --- | --- | --- |
-| A1 | Task 1 | Step 1–4 (`node --test test/cwd-stats.test.mjs`) |
-| A2 | Task 2 | Step 1–4 (`node --test test/dashboard-cwd-favorites-pool.test.mjs`) |
-| A3 | Task 2 | Step 5 (`node --test test/launch-options.test.mjs`) |
-| A4 | Task 2 | Step 6 (focused suites incl. `test/dashboard-cwd-tab.test.mjs`) |
-| A5 | Task 2 | Step 7 (`npm run verify`) |
-| A6 | Task 1 / Task 2 | Existing corrupt-stats, stale-filter and empty-pool tests re-run in Steps 4 and 6 |
-| U1 | post-merge | Manual TUI run per spec §8 U1 (requires updated install copy; recorded as `pending` until executed) |

package/docs/superpowers/specs/2026-08-15-screenlog-gc-design.md

@@ -1,105 +0,0 @@
-# Spec: screen.log Startup GC（startup 回收 ended view 的 screen.log）
-
-- Issue: zhuxixi/pi-agent-board#1
-- Date: 2026-08-15
-- Status: draft（待 review）
-
-## Background（来自调研，证据已评论到 issue）
-
-上游 PR #41（commit `ee3780a`，2026-08-03 合入）已给**写路径**加上界：
-`appendBoundedScreenLog()` 超过 `SCREEN_LOG_MAX_BYTES`（5 MB）时原子 compact 成
-100 KB tail；runner 启动时 `reconcileScreenLog()` 压存量。本机验证（2026-08-15）：
-活跃 view 的 screen.log 最大 3.9 MB，cap 工作正常。
-
-**残留缺口（本 spec 的 scope）**：
-
-1. ended view 的 screen.log 无人回收——`reconcileScreenLog` 只在该 view 的
-   pty-runner 重启时触发；session 结束后 runner 不再运行，文件永久留存。
-   本机 views 目录仍有 1.6 GB 历史存量。
-2. 全仓无 retention/prune/GC 机制（ended view 目录永久保留）。
-3. `SCREEN_LOG_MAX_BYTES` / `SCREEN_LOG_REPLAY_BYTES` 硬编码，不可配。
-
-## Goals
-
-- Dashboard 启动时异步回收：ended 超龄 view 的 `screen.log` 被删除（unlink）。
-- 两个配置项写入 `launch-prefs.json` 即生效：
-  - `screenLogRetentionDays`（默认 7；**0 = 关闭 GC**）
-  - `screenLogMaxSize`（默认 5 MB；透传给 pty-runner 写路径的 cap）
-- 全程容错：GC 任何失败不得影响 dashboard 或 runner。
-
-## Non-goals
-
-- 不做 log 轮转（screen.log → screen.log.1）。写路径已有 cap + tail compact，轮转与其重叠（YAGNI）。
-- 不做压缩（.gz）。
-- 不删整个 view 目录；保留 `meta.json` / `state.json` / `evidence.json` 等 KB 级文件，dashboard 历史行不丢。
-- 不动 job-runner 路径（它不写 screen.log）。
-- 不引入防抖/状态持久化（扫描成本可忽略，每次启动都跑）。
-
-## Design
-
-### 新模块：`src/core/screen-log-gc.mjs`
-
-单一职责，导出 `pruneScreenLogs(root, opts)`：
-
-- 扫描 `<root>/views/view_*/`。
-- 对每个 view，判定清理条件（全部满足才删）：
-  1. `screen.log` 存在且非空；
-  2. view 已结束——`host.json` 的 `endedAt` 非 null（首选依据），
-     或 `host.state !== "alive"`；host.json 缺失/损坏时 fallback 用
-     screen.log 的 mtime 判定年龄；
-  3. 结束时间（或 mtime）早于 `now - retentionDays`。
-- 满足条件 → `unlinkSync(screenLog)`。失败静默（单文件失败不中断整体扫描）。
-- **活跃 view 一律跳过**：runner 持有 `screenLogBytes` 内存计数，外部动活跃
-  文件引入 race；活跃 view 由 `appendBoundedScreenLog` 的 cap 自管。
-- fs 操作沿用 `screen-log.mjs` 的可注入 fs 模式（defaultScreenLogFs），便于单测。
-- 返回统计 `{ scanned, removed, skippedActive, skippedFresh, bytesReclaimed, errors }`，
-  供可选的 diagnostics 记录。
-
-### 触发点：`src/runtime/service.mjs`
-
-- service 初始化时 fire-and-forget 调 `pruneScreenLogs()`（不 await、不阻塞首帧；
-  几百个 view 的 stat 扫描 <10ms，实际删除走 unlink，足够快）。
-- 整个调用包 try/catch，异常静默；可选把统计 append 到 diagnostics.jsonl。
-
-### 配置读取：`launch-prefs.json`
-
-新增两个字段（缺省用默认值，向后兼容旧 prefs 文件）：
-
-| 字段 | 类型 | 默认 | 语义 |
-|---|---|---|---|
-| `screenLogRetentionDays` | number | 7 | ended 超过该天数的 view 清理 screen.log；0 = 关闭 GC |
-| `screenLogMaxSize` | number | 5_000_000 | pty-runner 写路径 cap（字节），透传进 HostConfig → `appendBoundedScreenLog(opts.maxBytes)` |
-
-- 非法值（负数、NaN、非数）回退默认值。
-- `screenLogMaxSize` 传递链路：service 读 prefs → 写入 pty-runner 的 HostConfig
-  JSON → runner `appendBoundedScreenLog(screenLog, data, bytes, { maxBytes })`。
-  `appendBoundedScreenLog` 已支持 `opts.maxBytes`，runner 侧只需读取并透传。
-
-### Error handling
-
-- GC 整体 fire-and-forget + try/catch；单 view 失败跳过继续。
-- host.json 读取失败 → mtime fallback；两者都失败 → 跳过该 view。
-- prefs 读取失败 → 全默认值（不影响现有 launch-prefs 逻辑）。
-
-### Testing
-
-新增 `test/screen-log-gc.test.mjs`（沿用现有 test 风格与可注入 fs）：
-
-1. ended 超龄 view → screen.log 被删，meta/state 等文件保留。
-2. 活跃 view（host.json `state: "alive"` 且 endedAt null）→ 不删。
-3. ended 但未超龄 → 不删。
-4. `screenLogRetentionDays: 0` → 全部不删。
-5. host.json 缺失 → mtime fallback 正确判定。
-6. `screenLogMaxSize` 经 HostConfig 透传到 runner cap（runner 侧单测或链路断言）。
-7. 单文件 unlink 失败不中断其他 view 的清理。
-
-## Data flow
-
-```
-/dashboard 打开
-  └─ service init
-       └─ (async, fire-and-forget) pruneScreenLogs(root, prefs)
-            ├─ scan views/view_*/
-            ├─ per view: ended? aged? → unlink screen.log
-            └─ return stats → (optional) diagnostics.jsonl
-```