pi-crew 0.9.44 → 0.9.47

package/CHANGELOG.md

@@ -3,6 +3,142 @@
 > **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.47] — Broker Phase 4 gated ON (default-on flip) (2026-07-22)
+
+Flips `broker.enabled` from `false` to `true` as the new default on Linux
++ macOS. Windows users continue to see the broker silently disabled
+(decision doc `2026-07-21-broker-windows-perms.md` — no unix socket on
+native Windows). Three independent kill switches remain available:
+
+1. `broker.enabled: false` in user config
+2. env `PI_CREW_BROKER=0` (beats config=true)
+3. Windows — auto-disabled
+
+### Changes
+
+- **`src/config/defaults.ts`**: `DEFAULT_BROKER.enabled: false` → `true`.
+- **`src/extension/registration/lifecycle-handlers.ts`**: `effectiveEnabled()`
+  now returns `cfg?.enabled !== false` (default-on) instead of
+  `cfg?.enabled === true` (opt-in).
+- **`test/unit/crew-broker-feature-flag.test.ts`**: now asserts
+  `DEFAULT_BROKER.enabled === true` (Phase 4 default-on).
+- **`test/unit/crew-broker-server-gate.test.ts`**: "config flag off" test
+  renamed to "env kill switch (PI_CREW_BROKER=0)" — env is the load-bearing
+  kill switch under default-on.
+- **`docs/decisions/2026-07-22-broker-phase4-gated-on.md`**: new decision
+  doc supersedes the v0.9.46 default-off stance.
+- **Plan templates + workflows** (verifier fix from prior session):
+  `verificationCommand` now `npm run test:critical && npx tsc --noEmit`
+  (97 broker+UI tests in ~20s; well under worker 300s timeout) instead of
+  full `npm test` (>4 min). All 4 verifier workflow prompts updated.
+- **`package.json`**: new `test:critical` script — a curated 14-file subset
+  (97 tests, ~20s) for fast in-loop verification of broker/UI/config changes.
+  Full `npm test` (>4 min) caused verifier workers to hit the 300s
+  `RESPONSE_TIMEOUT_MS` and get SIGKILLed (exit 143).
+- **`skills/real-test-pi-crew/SKILL.md`**: new skill distilling the 8-tier
+  end-to-end verification discipline used to ship the broker Phase-4 rollout
+  (critical tests → 3-path kill-switch proof → typecheck+bundle → bundle md5
+  sync → live TUI probing via tmux/pty → smoke team run). 659 lines, 26
+  sections, 15 triggers. Bundled `scripts/pty_probe.py` (174-line hardened
+  TUI probe with zombie reaping).
+- **`scripts/postinstall.mjs`**: new `copySkills()` step mirrors every
+  `skills/<name>/` dir to `~/.pi/agent/skills/` on install, so pi-crew's
+  skills are available globally (not just inside the pi-crew project).
+  Best-effort, never fails the install.
+
+### Verification
+
+- Default-on: `npm run test:critical` → **97/97 pass in ~15s**.
+- Disabled: `PI_CREW_BROKER=0 npm run test:critical` → **97/97 pass in ~15s**.
+- Explicit-on: `PI_CREW_BROKER=1 npm run test:critical` → **97/97 pass in ~15s**.
+- Typecheck clean. Bundle rebuilt (md5 `d9c8412cb090735239935f5fa6d7b79a`, ~2.68 MB).
+- Live TUI verified via tmux + pty probe (`/team-help` renders, no zombie
+  processes).
+- Smoke team run `team_20260723154250_8955437a182b3f12` (fast-fix): 3/3 PASS,
+  verifier used `test:critical` cache, completed in 386s wall-clock (no hang).
+
+### Rollback
+
+If post-release issues emerge: flip `DEFAULT_BROKER.enabled` back to `false`
+in `src/config/defaults.ts`, rebuild bundle, cut v0.9.48. Users can also
+disable immediately via `broker.enabled: false` or `PI_CREW_BROKER=0`.
+
+## [0.9.46] — UI stability + notification coalescing (2026-07-20)
+
+Three user-facing UI/notification fixes layered on top of the v0.9.45
+remediation, plus CI hygiene. All verified live in a restarted Pi session.
+
+### UI flicker — stop render-path snapshot-cache deletes
+
+The run-snapshot cache has a deliberate stale-while-revalidate design so the
+widget always shows a populated snapshot. That was defeated by three hot-path
+call sites in `lifecycle-handlers.ts` that hard-deleted cache entries; the worst
+ran `invalidate(undefined)` on every ~160ms fallback tick, wiping ALL entries
+→ `activeWidgetRuns` dropped every run to "(loading…)" until the async preload
+rebuilt the cache → continuous flicker across the widget, powerbar, and live
+sidebar/dashboard. (`src/extension/registration/lifecycle-handlers.ts`)
+
+**Fix:** never hard-delete from the render path. A no-runId tick is now a no-op;
+a specific runId calls `refreshIfStale` (stale-while-revalidate); the two
+`fs.watch` change handlers call `refresh` (rebuild-in-place). All three keep the
+entry populated so `get()` never returns `undefined`.
+
+### TUI width-overflow crash — delegate `visibleWidth` to pi-tui
+
+`Rendered line N exceeds terminal width (160 > 159)` killed the host Pi process
+whenever an agent emitted an emoji that pi-crew's hand-maintained `WIDE_RANGES`
+table counted as 1 column but pi-tui (the renderer) counted as 2 (e.g. `⏳`
+U+23F3). pi-crew truncated/padded to its own measure, pi-tui re-measured and
+hard-aborted. This was patched twice before by adding individual codepoints —
+whack-a-mole, since ANY emoji in agent output could trigger it.
+(`src/utils/visual.ts`)
+
+**Definitive fix:** `visibleWidth` now delegates to pi-tui's own `visibleWidth`
+(the function that drives the crash assert). truncate/pad/wrap therefore always
+agree with the renderer; an emoji-width mismatch is structurally impossible. The
+hand-maintained `WIDE_RANGES`/`isWideCodePoint` table is removed.
+
+### Notification coalescing — N drip → 1 consolidated wake-up
+
+Launching N background subagents (no `batch_id`) produced N separate "changed
+state" wake-ups, delivered one-per-turn at turn boundaries; after the leader
+joined them all, redundant per-agent notices kept dripping in over later turns.
+(`src/extension/registration/subagent-manager-setup.ts`)
+
+**Fix (Rule 3):** a debounced coalescer for non-batch completions. Completions
+within an 800ms window (reset on each new arrival) merge into ONE wake-up; each
+is `resultConsumed`-re-checked before emit (Rule 2), so already-joined agents
+are dropped and an all-consumed batch is suppressed entirely. Completions far
+apart (>800ms) still flush separately. The explicit-`batch_id` path (Rule 1,
+BatchBarrier) is unchanged.
+
+### CI hygiene
+
+`biome check --write` applied across the v0.9.45 remediation files (lint +
+format), and two unused test imports were removed — the local remediation
+commits had never been CI-checked; this brings lint + format:check green.
+
+## [0.9.45] — Deep-review 2026-07-20 remediation (all 5 phases, 14 findings)
+
+### ⚠️ BREAKING: custom agent roles default to read-only (FIND-12)
+
+`permissionForRole()` now returns `"read_only"` for unknown/custom agent
+roles instead of the previous permissive `"workspace_write"`. This is a
+security hardening (default-deny) to prevent privilege escalation via
+typo'd or unrecognized agent names.
+
+**Migration:** write-capable roles are now an EXPLICIT allowlist
+(`WRITE_ROLES` in `src/runtime/role-permission.ts`). All shipped
+write-capable roles are listed: `executor`, `writer`, `verifier`,
+`test-engineer`, `agent` (direct-agent default), `cold-verifier`,
+`chain-executor` (chain workflow), and `worker` (goal-loop + dynamic
+workflow). A custom agent role that needs workspace write access
+must be added to `WRITE_ROLES`. Built-in read-only roles (`explorer`,
+`reviewer`, `security-reviewer`, `analyst`, `critic`, `planner`) are
+unaffected. (An earlier draft proposed a `permissions.workspaceWrite`
+agent-config opt-in; it was dropped — unreachable from the call sites.)
+
+
 ## [0.9.44] — 3 flaky CI test fixes (2026-07-19)
 
 Three pre-existing flaky tests in the CI suite have been fixed, completing

package/README.md

@@ -68,6 +68,8 @@ repo: https://github.com/baphuongna/pi-crew
 - **Strict SKILL.md validation** (L3, v0.9.8) — skills with malformed frontmatter (missing/malformed `name`/`description`, type mismatches) now **fail-fast at discovery** with visible diagnostics, instead of silently producing broken behavior at runtime. HYBRID policy: HARD on required fields, SOFT (warn) on unknown props for forward-compat. Surfaced via `buildSkillValidationDiagnostics()`.
 - **Durable event replay** (L1, v0.9.8) — `RunEventBus.onWithReplay()` catches up a re-subscribing dashboard/overlay with events it missed during transient absence (toggle, reconnect), replaying from the durable JSONL log with seq-based dedup. No information loss even if the live subscriber was briefly gone.
 - **Lossless-by-default output handling** (L4, v0.9.8) — worker output thresholds sized from measured data (100% of real outputs fit without compaction); when compaction is unavoidable it keeps head+tail (preserves closing code fences/headings) instead of head-only truncation. No more `[pi-crew compacted N chars]` markers eating the end of a worker's result.
+- **Inter-pi broker** (v0.9.47, default-on) — a Unix-domain-socket message bus that lets concurrently-running Pi sessions pass messages, steering notes, and task-status events to each other. **On by default** on Linux + macOS; auto-disabled on native Windows (no unix socket). Three independent kill switches: `broker.enabled: false` (config), `PI_CREW_BROKER=0` (env, always wins), Windows auto-disable. See [docs/decisions/2026-07-22-broker-phase4-gated-on.md](docs/decisions/2026-07-22-broker-phase4-gated-on.md).
+- **`test:critical` + `real-test-pi-crew` skill** (v0.9.47) — a curated 14-file / 97-test subset (`npm run test:critical`, ~20s) for fast in-loop verification, plus a bundled skill distilling the full 8-tier end-to-end verification discipline (unit → 3-path kill-switch proof → typecheck/bundle → live TUI probing → smoke team run). Prevents the verifier-worker hang that full `npm test` (>4 min) caused against the 300s worker timeout.
 
 ---
 
@@ -282,7 +284,36 @@ The advisory is **informational only** — there is no `force:true` flag needed
 
 - `test/functional/pi-crew-live.test.ts` + `test/functional/pi-crew-live-broad.test.ts` — 16 live integration tests run against the **real pi binary + real LLM provider** (verified after v0.9.42 audit, ~26 commits). Use these when you want to confirm end-to-end behavior, not just unit-level invariants.
 
-## Recent changes (since v0.9.42)
+## Recent changes
+
+### v0.9.47 (2026-07-22): Inter-pi broker Phase 4 (default-on) + verifier-hang fix + verification skill
+
+- **Broker default-on**: `broker.enabled` flipped `false` → `true` on Linux + macOS. The inter-pi broker lets concurrent Pi sessions exchange messages, steering notes, and task-status events over a Unix-domain socket. Three kill switches remain: config `broker.enabled: false`, env `PI_CREW_BROKER=0` (always wins), Windows auto-disable.
+- **Verifier-hang fix**: `npm run test:critical` — a curated 14-file / 97-test subset (~20s) replaces full `npm test` (>4 min) in verifier prompts. The full suite was exceeding the 300s `RESPONSE_TIMEOUT_MS`, killing workers with exit 143. Both plan-templates and all 4 workflow verifier prompts now specify the fast command.
+- **`real-test-pi-crew` skill** (659 lines): distills the 8-tier verification discipline used to ship this release (critical tests → 3-path kill-switch proof → typecheck/bundle → bundle md5 sync → live TUI probing via tmux/pty → smoke team run). Bundled `scripts/pty_probe.py`.
+- **Postinstall `copySkills()`**: `npx pi install .` now mirrors every `skills/<name>/` to `~/.pi/agent/skills/` for global availability.
+- See [CHANGELOG.md](CHANGELOG.md) §0.9.47 and [docs/decisions/2026-07-22-broker-phase4-gated-on.md](docs/decisions/2026-07-22-broker-phase4-gated-on.md).
+
+### v0.9.45 – v0.9.46 (2026-07-20): security + perf remediation, UI stability
+
+- **Custom agent roles default to read-only (FIND-12, breaking):**
+  `permissionForRole()` returns `"read_only"` for unknown roles (was
+  permissive `"workspace_write"`). Write-capable roles are now an explicit
+  allowlist (`WRITE_ROLES`). See `CHANGELOG.md` for the migration.
+- **Mailbox / snapshot-cache / scan perf:** delivery cache + async append
+  (FIND-01/02), `listActive` TTL + mtime-sort strict limit (FIND-03/04),
+  byte-bounded event-log tail-read (FIND-05).
+- **Heartbeat race (FIND-06):** in-flight guard + drain + terminal-safety +
+  late-save repair in the coalesced task group.
+- **UI flicker eliminated:** the render path no longer hard-deletes snapshot
+  entries, so the crew widget / powerbar / live sidebar stay stable (no more
+  "(loading…)" flashing every ~160ms).
+- **Emoji width-overflow crash fixed for good:** `visibleWidth` delegates to
+  pi-tui's own measure, so agent-output emoji can never exceed terminal width.
+- **Background-subagent notifications coalesce:** N near-simultaneous
+  completions now produce ONE consolidated wake-up instead of N drips.
+
+### v0.9.42 – v0.9.44: 4-wave audit + flaky-CI fixes
 
 A 4-wave audit + fix pass was completed (see `UPGRADE_REVIEW.md` for the full 647-line report and `CHANGELOG.md` for the diff):
 
@@ -624,6 +655,9 @@ Your system prompt here.
 
 | Variable | Purpose |
 |----------|---------|
+| `PI_CREW_BROKER=0` | **Disable the inter-pi broker entirely** (always wins over config). Use to opt out of cross-session messaging. |
+| `PI_CREW_BROKER=1` | Explicitly enable the broker (redundant under the v0.9.47 default-on; useful for overriding a config `broker.enabled: false`). |
+| `PI_CREW_BROKER_DIAG_UI=1` | Make the run-dashboard `handleInput` emit a `[PI-CREW-DIAG]` line to stderr per keystroke — for TUI keybinding probes. |
 | `PI_CREW_USE_BUNDLE=1` | Load via bundled `dist/index.mjs` (~5% faster cold-start). Default: strip-types. Requires `npm run build:bundle` to have produced `dist/`. Falls back to strip-types with a one-time warning if the bundle is missing. See `scripts/bench-cold-start.mjs`. |
 | `PI_CREW_EXECUTE_WORKERS=0` | Disable child workers (scaffold mode) |
 | `PI_TEAMS_EXECUTE_WORKERS=0` | Legacy disable flag |
@@ -656,13 +690,14 @@ The watcher is the dev-loop companion to `check:bundle-staleness` (CI gate) —
 ```bash
 cd pi-crew
 npm install          # dependencies
-npm test             # unit + integration tests (~4,800 tests)
+npm test             # unit + integration tests (~6,500 tests)
+npm run test:critical # fast subset: 97 broker/UI tests in ~20s
 npm run typecheck    # tsc --noEmit
 npm run ci           # full CI-equivalent check
 npm pack --dry-run   # package verification
 ```
 
-Stats: **431 source files** (87K lines) · **606 test files** (85K lines) · **~5,860 tests, 0 failures** · **CI: Ubuntu ✅ macOS ✅ Windows ✅**
+Stats: **477 source files** (108K lines) · **682 test files** (~6,500 tests) · **CI: Ubuntu ✅ macOS ✅ Windows ✅**
 
 ---