2026.07.27 - Phase 1: Pi 0.82 Compatibility and Toolchain Cleanup

biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.5.2/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.5/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",

docs/superpowers/plans/2026-07-27-stepfun-credits-compact-insights-phase-1-pi-082-upgrade.md

@@ -1,114 +1,200 @@
-# Phase 1: Pi 0.82.0 Upgrade Implementation Plan
+# Phase 1: Pi 0.82 Compatibility and Toolchain Cleanup 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.
 
-**Parent plan:** `docs/superpowers/plans/2026-07-27-stepfun-credits-compact-insights-refactor.md`
+**Goal:** Complete the Pi 0.82 dependency baseline by making the existing Biome 2.5.5 and Vitest 4.1.10 upgrades pass the project quality gate without changing application behavior.
+
+**Architecture:** Keep the current dependency metadata: `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` remain declared as `^0.82.0` and resolve to 0.82.1 in the lockfile. Apply only behavior-preserving lint fixes in the overlay width calculation and runtime utility tests, and remove the unused test-only lint override.
 
-**Goal:** Upgrade the project to `@earendil-works/pi-coding-agent` 0.82.0 and `@earendil-works/pi-tui` 0.82.0 without changing application behavior.
+**Tech Stack:** pnpm, TypeScript 6, Node.js 24.15.0, Pi 0.82.x, Vitest 4.1.10, Biome 2.5.5.
 
-**Architecture:** This phase changes only dependency metadata. It establishes the exact Pi API baseline used by all later provider and TUI phases.
+---
 
-**Tech Stack:** pnpm, TypeScript 6, Node.js 24, Pi 0.82.0.
+**Parent plan:** `docs/superpowers/plans/2026-07-27-stepfun-credits-compact-insights-refactor.md`
 
-**Phase dependency:** The parent design specification must be approved before execution.
+**Current baseline:** The branch already contains the Pi, Biome, and Vitest dependency upgrades. Direct Pi packages report 0.82.1 from the `^0.82.0` ranges; typecheck and all 247 tests pass. The remaining blocker is Biome’s one warning and two errors.
 
-**Usable result:** The unchanged extension installs, typechecks, and passes its existing test suite against Pi 0.82.0. This phase can be released independently as a dependency-only maintenance update.
+**Usable result:** The unchanged extension passes `pnpm check` under Node 24.15.0. This phase remains independent of StepFun behavior, Insights behavior, and all later feature work.
 
-**Out of scope:** StepFun behavior, Insights behavior, README content, screenshots, and unrelated dependency updates.
+**Out of scope:** Dependency version changes, public API changes, StepFun behavior, Insights behavior, README content, screenshots, and unrelated refactoring.
 
 ---
 
-### Task 1: Pin the Pi packages to the 0.82 line
+### Task 1: Resolve the Biome 2.5.5 diagnostics
 
 **Files:**
-- Modify: `package.json`
-- Modify: `pnpm-lock.yaml`
+- Modify: `biome.json`
+- Modify: `src/tui/overlay-render.ts`
+- Modify: `tests/runtime-utilities.test.ts`
 
-- [ ] **Step 1: Record the current dependency state**
+- [ ] **Step 1: Reproduce the current quality-gate failure**
 
 Run:
 
 ```sh
-pnpm list @earendil-works/pi-coding-agent @earendil-works/pi-tui --depth 0
+mise exec node@24.15.0 -- pnpm check
 ```
 
-Expected before the change: both packages report `0.80.3`.
+Expected before the edits: Biome reports the non-null assertion at `src/tui/overlay-render.ts:113` and unsafe optional chaining at `tests/runtime-utilities.test.ts:23` and `tests/runtime-utilities.test.ts:38`; TypeScript and Vitest are not reached by the combined command.
 
-- [ ] **Step 2: Update both Pi development dependencies**
+- [ ] **Step 2: Remove the unused test-only lint override**
 
-Run:
+Replace `biome.json` with:
 
-```sh
-pnpm add -D '@earendil-works/pi-coding-agent@0.82.0' '@earendil-works/pi-tui@0.82.0'
+```json
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.5/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": false,
+    "includes": ["src/**/*.ts", "tests/**/*.ts", "!**/node_modules"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended"
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}
 ```
 
-Expected: `package.json` contains:
+The override is unnecessary because the test suite contains no non-null assertions; keep Biome’s recommended rules enabled for all project files.
 
-```json
-"@earendil-works/pi-coding-agent": "^0.82.0",
-"@earendil-works/pi-tui": "^0.82.0"
+- [ ] **Step 3: Replace the overlay width assertion with a bounds-safe reduction**
+
+In `src/tui/overlay-render.ts`, replace:
+
+```ts
+let total = 0;
+for (let i = s; i < e; i += 1) total += widths[i]!;
+```
+
+with:
+
+```ts
+let total = widths.slice(s, e).reduce((sum, width) => sum + width, 0);
+```
+
+Leave the gap, indicator, and return calculations unchanged. The existing callers pass tab-derived bounds, so the reduction preserves the rendered width while removing the assertion.
+
+- [ ] **Step 4: Narrow the mocked fetch signals in the timeout tests**
+
+In the `"aborts after timeout expires"` test, replace the callback body with:
+
+```ts
+deps.fetch = vi.fn(async (_url, init) => {
+  const signal = init?.signal;
+  if (!signal) throw new Error("fetch signal missing");
+  await new Promise((_, reject) => {
+    signal.addEventListener("abort", () =>
+      reject(new DOMException("aborted", "AbortError")),
+    );
+  });
+  return new Response();
+});
+```
+
+In the `"respects external signal"` test, replace the callback with:
+
+```ts
+deps.fetch = vi.fn(async (_url, init) => {
+  const signal = init?.signal;
+  if (!signal) throw new Error("fetch signal missing");
+  signal.throwIfAborted();
+  return new Response();
+});
 ```
 
-Expected: the importer and package snapshots in `pnpm-lock.yaml` resolve both packages to exactly `0.82.0`.
+The explicit guard preserves the test’s expectation that `fetchWithTimeout` supplies an abort signal and removes unsafe optional chaining.
 
-- [ ] **Step 3: Verify only intended dependency metadata changed**
+- [ ] **Step 5: Run the focused regression tests**
 
 Run:
 
 ```sh
-git diff -- package.json pnpm-lock.yaml
+mise exec node@24.15.0 -- pnpm exec vitest run tests/overlay-render.test.ts tests/runtime-utilities.test.ts
 ```
 
-Expected: the two Pi package specifications and their transitive lockfile entries change; no unrelated direct dependency changes appear.
+Expected: all tests in both files pass.
 
-- [ ] **Step 4: Verify the installed versions**
+- [ ] **Step 6: Run Biome against the changed files**
 
 Run:
 
 ```sh
-pnpm list @earendil-works/pi-coding-agent @earendil-works/pi-tui --depth 0
+mise exec node@24.15.0 -- pnpm exec biome lint biome.json src/tui/overlay-render.ts tests/runtime-utilities.test.ts
 ```
 
-Expected: both direct dependencies report `0.82.0`.
+Expected: no errors, warnings, or fixes requested.
 
-- [ ] **Step 5: Verify the existing code against Pi 0.82.0**
+- [ ] **Step 7: Commit the lint compatibility fixes**
 
 Run:
 
 ```sh
-pnpm typecheck
-pnpm test
+git add biome.json src/tui/overlay-render.ts tests/runtime-utilities.test.ts
+git commit -m "fix: satisfy Biome 2.5.5 lint rules"
 ```
 
-Expected: both commands PASS with no TypeScript diagnostics or failed tests. Do not add compatibility shims unless the typecheck exposes a concrete 0.82.0 API change.
+Expected: the commit contains only the lint configuration cleanup and the behavior-preserving source/test edits.
+
+### Phase verification
 
-- [ ] **Step 6: Commit the atomic upgrade**
+- [ ] **Step 1: Run the complete quality gate**
+
+Run:
 
 ```sh
-git add package.json pnpm-lock.yaml
-git commit -m "chore: update Pi dependencies to 0.82.0"
+mise exec node@24.15.0 -- pnpm check
 ```
 
----
+Expected: Biome lint, TypeScript typecheck, and all 247 Vitest tests pass.
 
-### Phase verification
+- [ ] **Step 2: Confirm the dependency baseline was not changed**
 
-- [ ] Run the project quality gate:
+Run:
 
 ```sh
-pnpm check
+mise exec node@24.15.0 -- pnpm list @earendil-works/pi-coding-agent @earendil-works/pi-tui --depth 0
+git diff HEAD^ -- package.json pnpm-lock.yaml
 ```
 
-Expected: Biome lint, TypeScript typecheck, and Vitest all PASS.
+Expected: both direct Pi packages report 0.82.1; the lint-fix commit contains no dependency metadata changes.
+
+- [ ] **Step 3: Verify the final worktree**
 
-- [ ] Verify the phase diff and commit:
+Run:
 
 ```sh
 git status --short
 git diff --check
 git log -1 --oneline
 ```
 
-Expected: no uncommitted Phase 1 files, no whitespace errors, and the latest commit is `chore: update Pi dependencies to 0.82.0`.
+Expected: no uncommitted files, no whitespace errors, and the latest commit is `fix: satisfy Biome 2.5.5 lint rules`.
 
-**Stop here.** Phase 2 starts from this passing Pi 0.82.0 baseline.
+**Stop here.** Phase 2 starts from this passing Pi 0.82.x and toolchain baseline.

package.json

@@ -48,13 +48,13 @@
     "README.md"
   ],
   "devDependencies": {
-    "@biomejs/biome": "^2.5.2",
-    "@earendil-works/pi-coding-agent": "^0.80.3",
-    "@earendil-works/pi-tui": "^0.80.3",
+    "@biomejs/biome": "^2.5.5",
+    "@earendil-works/pi-coding-agent": "^0.82.0",
+    "@earendil-works/pi-tui": "^0.82.0",
     "@types/node": "^26.1.0",
     "typebox": "^1.3.3",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",