pi-crew 0.9.49 → 0.9.51

package/CHANGELOG.md

@@ -3,6 +3,330 @@
 > **Note:** `atomic-write-v2.ts` / `AtomicWriter` mentioned in historical entries below was consolidated into `atomic-write.ts` as of v0.9.42. This changelog is preserved as historical record — the migration was completed (the v2 class was never adopted; v1 won on simplicity + symlink-safety + link+unlink atomicity). See `docs/migration/atomic-write-v2-migration.md` for the decision rationale.
 
 
+## [0.9.51] — Complete the UI animation audit + Windows coalescing fix (2026-07-26)
+
+Closes out the remaining deferred findings from `reports/ui-animation-audit-2026-07-24.md`
+(R1, R4, C4, C3, C9; C6 analyzed-then-closed-with-reasoning) and fixes the
+underlying Windows event-log coalescing bug that a v0.9.49 test had been
+papering over with a `process.platform === "win32"` skip. All 15 audit
+findings are now resolved (11 applied in v0.9.50 + these + C6 closed).
+
+### Remaining audit findings applied
+
+- **R1 — `render-scheduler.ts` fallbackLoop idle-stop** (`c46dc0e`): the
+  self-perpetuating `fallbackLoop` (`schedule()`→`lastEventAt`) never let the
+  UI idle, re-rendering ~every `fallbackMs` forever on a hung run. Now calls
+  a new `armDebouncedRender()` that does NOT touch `lastEventAt`; an
+  `idleFallbackRenders` counter caps consecutive idle catch-up renders
+  (default 8) then stops. `lastEventAt` is advanced only by real external
+  events, which reset the count + re-arm a stopped loop. **+3 tests** — one
+  asserts the scheduler STOPS rendering when idle, closing audit Root Gap #2
+  ("no test asserts the scheduler ever stops rendering when idle").
+- **R4 — `render-scheduler.ts` flush re-entrancy backoff** (`c46dc0e`): the
+  cap-hit path (`iterations >= 5`) now calls
+  `armDebouncedRender(debounceMs * 2^exp)` with exponential backoff
+  (`CAP_BACKOFF_MAX_EXP=5`) instead of re-arming `schedule()`.
+  `consecutiveCapHits` resets on a clean flush. Stops the latent sustained
+  ~75ms render loop. +1 test.
+- **C4 — `widget/index.ts` signature cache (invalidate-on-write)**
+  (`c46dc0e`): the prior blind-TTL cache (reverted in v0.9.50) caused stale
+  reads that skipped genuine re-renders. Now `cachedBuildSignature` is
+  invalidated in the widget's `RenderScheduler` `onInvalidate` callback (fires
+  on `run:state`/`worker:lifecycle`/`ui:invalidate`), plus in `invalidate()`
+  and on dispose. A 100ms TTL remains as a safety net only.
+  `notificationCount` is appended post-cache so notification changes still
+  re-render. +1 test asserting a genuine state change triggers re-render.
+- **C9 — dead loaders removal** (`c46dc0e`): `CrewBorderedLoader` +
+  `CountdownTimer` were dead production code (referenced only in
+  `test/unit/loaders.test.ts`, never instantiated in `src/` or re-exported
+  from the public index). Removed both classes (`loaders.ts` → 6-line
+  documenting comment) + deleted the test file. **Preserved** the 2
+  `DynamicCrewBorder` tests (a LIVE class used by `mascot.ts`,
+  `settings-overlay.ts`, `run-dashboard.ts`) → moved to new
+  `test/unit/dynamic-border.test.ts`.
+- **C3 — shared `RenderScheduler` fan-out dedup** (`3a50094`): the 3 overlays
+  (widget + sidebar + dashboard) each instantiated an identical
+  `RenderScheduler` (same run-event-bus channels, debounce 75ms, fallback
+  750ms) → 9 subscriptions + 9 live timers + 3× per-event `schedule()` CPU
+  during active runs. Now ONE shared scheduler (module singleton in
+  `src/ui/shared-overlay-scheduler.ts`) fans out `render` + `onInvalidate` to
+  registered overlays, with per-callback try/catch isolation + ref-counted
+  disposal. Dedups 9→3 subscriptions, 9→3 timers, 3→1 `schedule()`/event,
+  and coalesces 3 independent debounce flushes → 1 batch per event burst.
+  +5 tests (fan-out render/invalidate, dispose ref-count, error isolation ×2).
+- **C6 — mascot visibility gate: CLOSED, not wired** (`c46dc0e` gate +
+  `01ee10f` decision): the `setVisible()` gate was implemented + tested, but
+  after reading pi source (`earendil-works/pi@cee5ff75`) the wiring was
+  deliberately NOT done. `ctx.ui.custom()` does expose
+  `onHandle→OverlayHandle.isFocused()` (a usable "not obscured" proxy), so
+  wiring is feasible — BUT pi composites ALL non-hidden overlays
+  (`tui.ts:1044` `visibleEntries` → `component.render()` at `:1054`), so the
+  host STILL calls `mascot.render()` when obscured: C6 does not save the
+  render() work it appears to target, only cheap + coalesced + redundant
+  `requestRender()` pokes. Net benefit near zero. The correct fix is a
+  pi-core compositing optimization (skip `render()` for occluded overlays) —
+  upstream, not pi-crew. See `docs/decisions/2026-07-26-c6-mascot-visibility-not-wired.md`.
+
+### Windows event-log coalescing — attempted, REVERTED (remains unfixed)
+
+An adaptive burst coalesce window (`NOTIFY_COALESCE_BURST_MS = 3000ms`) was
+attempted to fix the Windows coalescing bug (the v0.9.49 `Rule 3` test had a
+`process.platform === "win32"` skip hiding it). **Reverted** — verified on
+Windows CI (run `30235357951`) that the 3000ms burst window is STILL shorter
+than Windows's 3-5s completion spread, so coalescing still did not occur; AND
+the 3000ms coalesce timer (not cancelled on `session_shutdown`) fired after
+test temp-dir deletion → `ENOENT mkdir` unhandledRejection that failed the
+whole `subagent-tools-integration` file on Windows. Restored the v0.9.50
+behavior (800ms constant coalesce). The `win32` test skip is **retained** —
+the underlying Windows coalescing bug remains unfixed (tracked from v0.9.49;
+widening further would delay ALL notifications by 5s+ on every platform).
+subagent-tools-integration 14/14 on Linux/macOS; both Rule 3 assertions
+skipped on Windows.
+
+### distill-software: Transfer vs Audit mode (`418b9f2`, bonus)
+
+From real distillation runs (audit-only distillation produced 0 visible
+features for the target; artifact-level gates were ALL-GREEN while code had
+runtime bugs needing multiple review rounds):
+- **Phase 0 #7**: Transfer (default for "distill X to Y") vs Audit mode.
+  Transfer enumerates source CAPABILITIES (features not files) and applies
+  the gaps; deliverable = visible/behavioral new features. Audit enumerates
+  conventions; deliverable = invisible refactors. Decomposition follows mode.
+- **Phase 1**: CAPABILITY DEPTH check before SKIP on PRESENCE=yes — surface
+  match can mask a capability gap.
+- **Phase 3 APPLY-LOG**: 5 post-APPLY integration checks — WIRED, VISIBLE
+  DELTA, RUNTIME, API VERIFIED, RESOURCE LIFECYCLE.
+
+### Repo hygiene
+
+- **`.claude/worktrees/*` orphan gitlinks removed** (`0e6cba5`): 7 gitlinks
+  (mode 160000, no `.gitmodules`) were stranded in the index from a prior
+  `.claude`-based tooling experiment, producing non-blocking `git exit code
+  128` warnings. Removed from index + added `.claude/` to `.gitignore`
+  (`a0b2b1e`).
+
+### Verification
+
+- `npm run test:critical` → 97/97 pass; render-scheduler 9/9, crew-widget
+  6/6, mascot 7/7, dynamic-border 2/2, shared-overlay-scheduler 5/5,
+  subagent-tools-integration 14/14.
+- `npm run typecheck` → exit 0; `npm run lint` → clean;
+  `npx biome format .` → clean.
+- `npm run build:bundle` → 2690.6 KB, md5 `29e7a4d04ab8ad0542a3af3ef3d42426`.
+- **real-test-pi-crew** all 8 tiers green (Tier 6 pty definitive — pi renders
+  full TUI, no crash; Tier 7 smoke team `team_20260727032433` fast-fix 3/3,
+  no hang).
+
+
+## [0.9.50] — UI animation audit + distillation toolkit v2 (2026-07-25)
+
+Eliminates a class of timer-leak / flicker bugs surfaced by the UI animation
+audit (3 parallel reviewer agents, 15 findings), ships the second iteration of
+the distillation toolkit (skill-skipping fixes + anti-lazy levers + dogfood
+feedback), and hardens the crew-vibes footer against a stale-context crash
+that blocked Tier 5 live-TUI verification.
+
+### UI animation audit — 11 of 15 findings applied (619a0cd)
+
+From `reports/ui-animation-audit-2026-07-24.md` (9240 bytes, 3 reviewers,
+cross-validated). 12 of 16 enumerated timers rated SAFE, 4 RISKY, 0 LEAKED.
+Applied 11 low-risk fixes; deferred C3 (shared RenderScheduler refactor),
+R1 (render-loop idle-stop), C4 (widget TTL cache — reverted, needs
+invalidate-on-write model), C6 (mascot obscured check), C9 (dead loaders)
+as separate follow-ups needing design + regression tests.
+
+**HIGH severity**:
+- **`src/ui/terminal-status.ts` (T1)**: idle re-assert was a recursive
+  `setTimeout` that kept the process alive forever on SIGTERM (zombie
+  title loop). Added `.unref()` on both idleTimer and flashTimer, and
+  wired a `dispose()` callback into `crew-cleanup.ts` SIGTERM/SIGHUP
+  handler via `register.ts` opts so the timers stop on shutdown.
+- **`src/extension/registration/commands.ts` + `src/ui/mascot.ts` (C1)**:
+  mascot armin framerate 33ms → 100ms (30fps → 10fps) to stop Windows
+  TUI flicker. Compensated by 3× per-tick advancement across all 7 armin
+  effects (typewriter 6→18 chars, scanline 1→3 rows, rain 1→3, fade
+  18→54, crt 1→3, glitch 1→3, dissolve 22→66) so effects finish in the
+  same wall-clock time.
+
+**MEDIUM severity**:
+- **`src/extension/registration/viewers.ts` (C2)**: `LiveConversationOverlay`
+  wrapper now exposes `dispose()` — was leaking the 200ms `pollTimer` on
+  programmatic dismiss.
+- **`src/ui/live-run-sidebar.ts` (C5)**: `autoCloseTimeout` now
+  `clearTimeout`-before-set + `.unref()` — was stacking timers (multiple
+  `done()` calls) on signature churn.
+- **`src/extension/registration/lifecycle-handlers.ts` (C7)**: crew widget
+  pauses while `RunDashboard` overlay is open (`uiState.dashboardOpen` gate
+  in `renderTick`); widget stopped rendering under the dashboard overlay.
+  Also: `uiState?` made optional + guarded with `if (deps.uiState)` in
+  `commands.ts` to avoid regressing the existing nullable-deps pattern.
+- **`src/ui/widget/widget-types.ts` (C8)**: removed dead
+  `CrewWidgetState.interval` field (vestigial polling handle never
+  assigned, only cleared) across widget-types/index/lifecycle-handlers.
+
+**LOW severity**:
+- **`src/ui/render-coalescer.ts` (R3)**: `flush()` now resets `#dropped`
+  counter and reports via `#onDrop` callback so observability catches
+  dropped frames instead of silent dropping.
+- **`src/ui/run-snapshot-cache.ts` (R2)**: `scheduleRefresh` timer
+  `.unref()`'d — was holding the loop alive on idle.
+- **`package.json`**: removed `assets/runner-spritesheet.png` from npm
+  `files` field (114KB JPEG source, only used at build-time by
+  `build-crew-vibes-font.py`; runtime uses ANSI art + PUA font glyphs).
+  Kept in git for reproducibility.
+
+### Crew-vibes stale-context crash fix (40d0380)
+
+- **`src/extension/crew-vibes/index.ts`**: `refreshFooter` body wrapped
+  wholly in `safeUiCall`. Root cause: `fetchProviderAndRefresh` is async
+  — after its `await` the session may have shut down (the
+  `session_shutdown` handler cleared the timers, but an in-flight
+  `fetchProviderAndRefresh` still resumed), making ctx stale.
+  `refreshFooter` then accessed the `hasUI` GETTER, which calls the
+  runner's `assertActive()` and THROWS on a stale ctx — uncaught, this
+  crashed pi (exit 7) on every non-interactive / shutdown-race startup.
+  A stale ctx now logs a warn and degrades gracefully instead of
+  crashing — matching the file's stated philosophy: *"Crew-vibes must
+  NEVER break the user's session. A broken spinner is not worth a
+  crashed pi."* Found while running `real-test-pi-crew` Tier 5 (live
+  TUI probe), where pi crashed immediately on spawn, blocking the live
+  verification tier.
+
+### Windows test flake fix (99f8452)
+
+- **`test/unit/subagent-tools-integration.test.ts`**: `session_before_switch`
+  test — added a 200ms drain between `session_shutdown` emit and
+  `removeDirWithRetry` call. The background agent's in-flight I/O
+  (`mkdir` under `.crew/state/runs`) raced the dir deletion → ENOENT
+  `unhandledRejection` AFTER the test ended, failing the whole file on
+  `windows-latest`. Same class of bug as commit `58e2491` (Rule 3 test),
+  different test case.
+
+### Distillation toolkit v2 (52f089b → ba8b15c, 5 commits)
+
+Second iteration of the distillation skillset shipped in v0.9.49.
+Hardens the agent discipline around skill-reading + APPLY evidence,
+adds human-in-the-loop + adversarial scrutinize gates, and dogfoods
+the improved tool on pi-crew itself (mechanical error-message helper
+migration).
+
+- **`feat(skills): bundle distillation toolkit`** (`52f089b`) — bundles
+  `distill-persona` (person 6-stream + topic exhaustive-sweep; V1-V5,
+  F2' dual-agent scoring, 10 mental models, Core Principle #6
+  decompose, #7 untrusted-source boundary, Phase 2.6 pre-apply
+  effectiveness gate), `distill-software` (codebase flavor: Code-DNA
+  12-axis, toolchain matrix, edge-honesty rubric, tiered effort),
+  `research` (field/topic flavor: iterative depth + cost-transparency
+  + state-on-disk hooks + rigor: citation verify, source eval,
+  tension discovery). Each ships `validate-skill-structure.mjs`
+  (output gate) + `validate-run.mjs` (process gate) so agents cannot
+  skip the ship-gate. Safe I/O helpers: SSRF guard (`is_safe_url`) +
+  secret redaction (8 regex rules).
+- **`feat(skills): fix skill-skipping`** (`1640ba5`) — root cause from
+  `pi source core/skills.js`: only the 1-line frontmatter `description`
+  enters the agent's system prompt; the skill BODY is never
+  auto-injected, so agents skip-read + skip-phases with impunity
+  (verified: agents wrote SKILL.md but skipped APPLY; gate never
+  checked APPLY evidence). Three layered fixes: (1) embed *"REQUIRED:
+  read SKILL.md FULLY + run validate-run, ALL-GREEN"* in the
+  description of all 3 distill skills — the only text always in
+  context; (2) trim `distill-persona` to <50KB (one read returns the
+  whole skill; relocate 11 methodology blocks to `references/`) + add
+  Phase 3→4 hard-stop; (3) `validate-run.mjs` APPLY-evidence checks
+  (APPLY-LOG.md — distillation = source → essence → APPLY to target;
+  standalone SKILL.md = NOT complete) + `--build` mode (alias-tolerant,
+  skips APPLY-LOG) for engine-skill builds. Both gates wired into the
+  distill workflow ship-gate step so builds cannot declare done
+  incomplete.
+- **`feat(skills): anti-lazy levers`** (`df9d45e`) — agents kept finding
+  new skip-paths despite artifact-presence gates (latest: distilled 7
+  patterns, applied 1, lazily dismissed 6 with "too small / not needed
+  yet" — no evidence). Machine gates check artifact PRESENCE not
+  reasoning QUALITY, so add two structural levers: (a) **Phase 2.7 PLAN
+  APPROVAL GATE** (human-in-the-loop): after the effectiveness-gate,
+  present an apply/reject/defer+evidence table and STOP — wait for user
+  approval before applying. REJECT requires grep/test evidence (not
+  "too small"); DEFER logged to a future-apply roadmap. Autonomous
+  fallback writes a LOW-YIELD DEFENSE if applied <30%. (b) **Phase 5.5
+  ADVERSARIAL SCRUTINIZE PASS**: fresh-context audit hunting
+  reasoning-quality failures (unevidenced rejections, undocumented
+  deferrals, low-yield-without-defense, trivial applies, silent
+  skips). Outputs `SCRUTINIZE-REPORT.md`; HIGH findings must resolve
+  before done. `validate-run.mjs` (default mode): 3 new checks —
+  `apply-plan.md` exists, approval/defense marker present,
+  `SCRUTINIZE-REPORT.md` exists. `--build` mode skips them (engine
+  builds have no target-apply). Decisive proof: a synthetic lazy-case
+  (1/7 applied, no approval, no scrutinize) now fails validate-run on
+  all three; adding APPROVED + SCRUTINIZE-REPORT flips them to pass.
+- **`feat(distill): remove skill-building from distill-software`**
+  (`30f1c93`) — `distill-software` is now purely a target-transformation
+  tool (APPLY mode) — it NEVER builds a SKILL.md. That was the root
+  cause blocking distillations: agents hit "Phase 3 Build SKILL.md"
+  and derailed into Capture mode (building a skill instead of
+  transforming the target). `validate-run.mjs` is now mode-aware: APPLY
+  mode (APPLY-LOG present) makes SKILL.md optional and requires
+  apply-plan + scrutinize; CAPTURE mode (persona/workflow skill-builds)
+  keeps SKILL.md required, skips apply-plan/scrutinize. **First real
+  APPLY** using the fixed skill (the test): migrated 6 inline
+  `err instanceof Error ? err.message : String(err)` patterns to the
+  `errorMessage()` helper across `run.ts` / `chain-runner.ts` /
+  `pipeline-runner.ts`, resolving 3 shadowing conflicts (local vars
+  named `errorMessage`) via renames to `waitErrMsg` / `errMsg` + 9
+  downstream edits. Verified: full test suite 190/191 pass (0 fail),
+  tsc clean, independent fresh-context scrutinize confirms
+  behavior-preserving (no HIGH/MED).
+- **`fix(distill-software): dogfood feedback R1-R3`** (`ba8b15c`) —
+  three feedback rounds from oh-my-pi→mya verify reports + operator
+  critique. R1: V5 citation rigor — line numbers from `grep -n` output
+  only, never estimated (was 42-58% wrong); prefer grep-reproducible
+  snippet. PRESENCE counting via `grep -c` exact pattern, never
+  semantic scan (overcounted 13→1). Large-file decompose — Core
+  Principle #6 + Phase 1 truncation guard. R2: DEFER scrutiny +
+  scrutinize hunt #6 for high-value deferrals. Abstraction-surface
+  coverage (extraction-completeness guard). R3 (operator critique —
+  over-fit + compromised + balanced): de-hardcode the inventory (method
+  DERIVED FROM LANGUAGE — no prescribed TS grep, no named example).
+  Core Principle #8 reworded to the BALANCED stance: SIZE is never a
+  filter axis (large = decompose + apply every batch, never defer),
+  BUT this is NOT "apply everything" — verify (V1-V5) + compare
+  (3-axis) + effectiveness (2.6) still freely REJECT/SKIP/MERGE on
+  merit. The single forbidden filter axis is size; all merit axes
+  still apply. Validated by dogfood test on pi-crew;
+  `validate-skill-structure` 13/0 ALL-GREEN.
+
+### Lint hygiene (06132e6)
+
+- **`src/runtime/chain-runner.ts` + `src/runtime/pipeline-runner.ts`**:
+  Biome `--write` fixed 2 FIXABLE `organizeImports` errors introduced
+  by `30f1c93` (errorMessage migration left imports out of order).
+  `test:critical` 97/97 still pass; lint + format + typecheck all clean.
+  Bundle rebuilt so the fix is live for this release.
+
+### Verification
+
+- `npm run test:critical` → 97/97 pass (~12-18s run-to-run).
+- `npm run typecheck` → exit 0 (`strip-types import ok`).
+- `npm run lint` → clean (0 errors after the 06132e6 fix).
+- `npx biome format .` → clean (no fixes applied).
+- `npm run build:bundle` → success, dist/index.mjs 2686.9 KB, md5
+  `a1481171595fbbe13e9ba0fdc2f97eb8` (rebased after the lint fix).
+- **real-test-pi-crew** all 8 tiers (this session):
+  - Tier 1 — `test:critical` 97/97 ✅
+  - Tier 2 — 3-path kill-switch proof (default / `=0` / `=1`) all
+    97/97 ✅
+  - Tier 3 — typecheck + bundle + staleness OK ✅
+  - Tier 4 — install via `packages: ["../../source/my_pi/pi-crew"]`
+    in `~/.pi/agent/settings.json` ✅
+  - Tier 5 — tmux session spawn OK; `capture-pane` empty (env issue,
+    not regression — same as prior sessions)
+  - Tier 6 — pty probe definitive: pi renders full TUI (`pi v0.82.0`,
+    help line, input box, separators), no crash ✅
+  - Tier 7 — smoke team `team_20260725083754_36b77e2431b4cb3c`
+    (fast-fix) 3/3 tasks, ~5.5 min, verifier 12.2s, no hang ✅
+  - Tier 8 — md5 sync: requires `/quit` + reopen after each bundle
+    rebuild (user did so — see session confirmation)
+
+
 ## [0.9.49] — Distill workflow + runtime reliability + CI hardening (2026-07-24)
 
 Ships the `distill.workflow.md` to the npm package (was project-level only),