pi-crew 0.9.11 → 0.9.13

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## [v0.9.13] — chain feature + raw worker output + anti-zombie hardening (2026-06-29)
+
+Context/compaction efficiency work + a live `chain` feature that wires previously-dead code, plus two root-cause zombie fixes. The unifying theme: **deliver the right context efficiently and never leave orphaned state behind.**
+
+### Features
+
+- **Section-aware knowledge injection** (`knowledge-injection.ts`) — `.crew/knowledge.md` is no longer injected as a uniform head-only block. CONVENTIONS sections (always-relevant: Code Style, Environment, Architecture, Testing, Release Process) are injected in full; SESSION-LOG sections (per-version post-mortems, incidents) are IDF-scored against the task/goal and budget-capped (5 KB), drop-whole with a head-slice fallback and a section-index recovery net. Cuts knowledge-token waste for trivial tasks (a `team action='run'` with a trivial goal went from ~4 000 tokens of mostly-irrelevant session-log noise to ~2 095 tokens of conventions + matching session-log) without starving architecture-relevant tasks. Backward compatible: `readKnowledge(cwd)` with no query keeps the legacy head-only path. Verified live (post-restart research run): worker knowledge dropped from ~4 000 tokens (95 % session-log noise) to ~2 095 tokens, with the synthesized Architecture reference present.
+
+- **Live `chain` feature** (`team action='run', chain='"a" -> "b" -> "c"'`) — `ChainRunner` was complete and unit-tested but had ZERO production callers. Each step now runs a REAL team run via an injected `handleRun`, with handoff context (including the previous step's output text) passed forward through a `# Previous Steps in This Chain` block prepended to the step's goal. This also makes `enrichContextFromHandoffs`'s honesty markers (`__chainHistoryNotes`) reachable in production. See `src/extension/team-tool/{chain-dispatch,chain-executor}.ts`.
+
+### Bug fixes
+
+- **Raw worker result + dependency-context tee recovery (output)** — `results/<id>.txt` was 16 K-capped at child-pi stream-parse time (`compactContentPart` caps assistant text at `MAX_ASSISTANT_TEXT_CHARS`), and the dependency-context path re-read the same capped text circularly (no tee, unlike sharedReads). Now: (a) `ChildPiLineObserver` captures the RAW final assistant text before the transcript's compaction, and `task-runner` writes it as the authoritative `results/<id>.txt` (monotonic-safe fallback to transcript-derived `finalText`); the transcript stays 16 K-capped (telemetry memory bound unchanged). (b) `collectDependencyOutputContext` now uses `readIfSmallWithTee` (matching sharedReads) and `renderDependencyOutputContext` surfaces the `Full output (if you need the missing middle): <path>` hint, breaking the circular re-read. Verified live: a research run's analyst result went from a 16 K-capped file with a `[pi-crew compacted N chars]` marker to a 33 KB RAW file with zero data-loss markers; the downstream writer received 33 K of raw dependency context. Tracing in `research-findings/output-handling-deep-dive.md`.
+
+- **Truncated-content recovery hints** — truncation markers in knowledge (`knowledge-injection.ts`), agent memory (`agent-memory.ts`), and dependency output now embed the absolute path + a `read`-tool hint so workers can recover the dropped tail instead of silently losing it. Tee threshold lowered 2× → 1.25× (`TEE_THRESHOLD_MULTIPLIER`) so the 32–64 KB band gets a recovery path. Live-session system prompt no longer duplicates the MEMORY block (it was already injected via `renderTaskPrompt().full`).
+
+- **background-runner watchdog (anti-zombie processes)** — the keepAlive interval (`setInterval(()=>{}, 5000)`, no `unref`) cleared only in `runCleanup`, so a hung team run (stuck child Pi, deadlocked lock, or a test that spawns a run without cleanup) left the process alive indefinitely. The existing parent-guard only fires when the parent DIES; here the parent hung too, so it never fired. Fix: a watchdog timer alongside keepAlive aborts via the shared `AbortController` (propagates → child-pi → kills child processes) and force-exits after a 15 s grace if the abort does not propagate. Default 2 h (generous for legitimate long runs); override via `PI_CREW_MAX_RUN_MS`. Verified live: normal run exits cleanly (watchdog cleared, 0 `watchdog_fired` events); isolated hang fires at exactly `MAX` ms.
+
+- **Test state isolation (anti-zombie UI rows)** — `useProjectState(cwd)` returns `findRepoRoot(cwd) !== undefined`, and `scopeBaseRoot` falls back to the EXTENSION-GLOBAL state dir (`~/.pi/agent/extensions/pi-crew/state/runs/`) when cwd is NOT a git repo. Tests that create a tmpdir WITHOUT `git init` and call `createRunManifest`/`writeRunFixture`/`createRunPaths` were leaking run records into that global dir — the one the crew widget reads — creating persistent fake-agent rows after every test run. Fix: the shared `createTrackedTempDir` helper and `state-store.test.ts`'s `makeResolvedTempDir` now create a `.git` marker dir so records land in `<tmpdir>/.crew/` (auto-cleaned). Protects all current and future callers. Verified: state-store + cov + chain-executor tests left global state 2 → 2 (zero leak).
+
+### Docs
+
+- **README** — removed 182 lines of version-by-version highlights (v0.9.0 → v0.9.12, v0.8.x, v0.7.0) that duplicated CHANGELOG.md. README now flows intro → `## Features` straight. Version tags remain only where they qualify a feature (e.g. `(L4, v0.9.8)`) — useful for deciding whether to upgrade.
+
+### Stats
+
+29 files changed · ~2 498 insertions / ~189 deletions across 7 commits.
+
+### Verification
+
+- `npx tsc --noEmit`: clean.
+- 44/44 new + modified unit tests pass (`raw-final-text`, `dependency-tee`, `chain-executor`, `chain-handoff-markers`, `background-runner-watchdog`).
+- Live (post-restart): chain 2-step run produced enriched step-2 goal with step 1's output; raw worker result verified end-to-end (33 KB analyst result, 0 markers); watchdog verified on normal path (clean exit) + hang path (fires at MAX ms).
+
+## [v0.9.12] — TUI UI/UX polish (21 findings) (2026-06-27)
+
+Comprehensive TUI UX review of pi-crew's UI layer (`src/ui/` + `src/utils/visual.ts`). 21 findings (5×P1, 10×P2, 6×P3), all addressed. Full review with evidence-backed file:line citations: `research-findings/pi-crew-uiux-review.md`.
+
+### Bug fixes
+
+- **F-3 (P1)** — `src/ui/live-conversation-overlay.ts`: local `pad` used `s.length` (counted ANSI escape bytes) and `content.slice` (UTF-16 units) → border drift on every colored or CJK line. Replaced with `pad`/`truncate` from `utils/visual.ts` (reference impl: `transcript-viewer.ts`).
+- **F-1 / F-2 / V-3 (P1/P2)** — `src/ui/status-colors.ts` (new shared `colorizeStatusGlyphs()`): unified status-glyph colorization covers ⏳ (waiting), ⚠ (needs_attention), and the braille spinner range ⠁–⣿ — the two most attention-demanding states were previously uncolored. Replaces duplicated per-module glyph maps/regexes in `widget-renderer.ts`, `live-run-sidebar.ts`, and `run-dashboard.ts`.
+- **L-1 (P1)** — `src/ui/run-dashboard.ts`: windowed run list with `scrollOffset`; selection can no longer escape the rendered 8-row window. ↓ past row 7 previously hid the highlight and Enter acted on an invisible run. Brute-force verified for 0–30 runs.
+- **L-2 (P1)** — cancellation/failure reason now shown in default detail row (`run-dashboard.ts`) and `live-run-sidebar.ts`. Previously rendered only in `progress-pane` (pane `2`). `cancellation-pane.ts` wired in via `summarizeTerminalReason()` (D-1).
+- **V-1 (P2)** — tabular-aligned numeric metrics across `run-dashboard` footer, `dashboard-panes/agents-pane.ts`, and `widget/widget-formatters.ts` via width-aware `alignMetric` (visibleWidth-based). Eliminates per-tick column jitter on transitions like 9.9s→10.0s and 950→1.0k.
+- **F-5 (P2)** — `src/runtime/process-status.ts`: `ERROR_VISIBILITY_GRACE_MS = 10 * 60_000` (was the 8s `COMPLETED_VISIBILITY_GRACE_MS` shared with completed runs). Failed/cancelled runs now linger 10 min in the crew widget — the run-level header (✗ team/workflow · X/Y agents) is the "one-line trace". Successful completions still vanish in 8s.
+- **K-1 (P2)** — new `src/ui/overlays/help-overlay.ts`: `?` opens the HelpOverlay rendering `BINDINGS[]` grouped by scope. ~16/20 keybindings were previously undiscoverable (no `?` cheatsheet existed). Header hint updated.
+- **F-6 (P2)** — `src/ui/live-run-sidebar.ts`: auto-close countdown moved inside the bordered box (was rendered below the bottom border).
+- **V-2 (P2)** — `src/ui/crew-footer.ts`, `src/ui/crew-select-list.ts`: dropped ASCII `'...'` 3rd arg from `truncate(...)` so they use the default `'…'` (U+2026) consistently with the rest of the UI. Test updated.
+- **L-3 / L-4 / L-5 (P2/P3)** — width-aware `runLabel` keeps the goal visible (the most meaningful field); widget prioritizes running > queued > waiting with `finishedSlots` so finished rows only fill leftover budget and never push a live agent's activity line off-screen; run-list separator unified to ` · `.
+- **F-4 / F-7 (P2/P3)** — stale-snapshot hint in the default dashboard view when manifest reads are flaky; actionable empty/error states (no more "Dashboard error — see logs").
+- **T-1 (P3)** — `src/utils/visual.ts`: ZWJ (`U+200D`) removed from `WIDE_RANGES` (now correctly width-0; was inflating compound-emoji width and over-truncating).
+- **T-2 (P3)** — `src/ui/widget/index.ts`: debounced (~120ms) SIGWINCH + stdout-resize listener busts the render cache and requests a repaint. Guarded against double-registration across widget reinstalls.
+- **D-1 (P3)** — `src/ui/dashboard-panes/cancellation-pane.ts` wired in via `summarizeTerminalReason()` (was dead-imported by `test/unit/cancellation-pane.test.ts`, so kept and given a real consumer instead of deleted).
+
+### Shortcut collision fix
+
+- **Extension-load warning**: `alt+d` collided with `tui.editor.deleteWordForward` (verified in pi-tui `TUI_KEYBINDINGS`). Pi resolved in favor of the extension, *stripping* the editor's delete-word-forward binding. Moved dashboard shortcut to **`alt+c`** (mnemonic: **C**rew — verified free against the full built-in `alt+` keymap: occupied letters are `b, d, f, v, y`).
+- **Test guard hardened**: `test/unit/crew-shortcuts.test.ts` collision set now includes the editor keys (`alt+b/d/f/y`, `alt+backspace`, `alt+delete`). The previous set was incomplete (`alt+v, alt+enter, alt+arrows` only), which is why the bug slipped past tests. This class of regression is now caught at test time.
+
+### Decisions (deviations from the initial review)
+
+- **K-3 `KEY_RESERVED`**: NOT dead code — consumed by `test/unit/keybinding-map.parity.test.ts:29,185-203` and `test/manual/l2-keybinding-dispatch-smoke.mjs`. Corrected the misleading "dead code" doc instead of deleting (deleting would have broken the parity test).
+- **K-2 `alt+m` / `alt+t`**: blocked — mailbox overlay is run-scoped (requires a runId; reached via the dashboard); `team-status` is a text command (`handleTeamTool({action:"status"})`), not an overlay opener. `alt+d → dashboard` is the only wired shortcut.
+- **F-5 location**: fixed at the correct layer (`process-status.ts` run-level grace) rather than the report's suggested `widget-renderer.ts` agent-row linger; the run-level header line is the right "one-line trace" per the finding.
+
+### Verification
+
+- `npx tsc --noEmit` + `npm run typecheck`: 0 errors (incl. strip-types import smoke).
+- Focused UI cluster: **74/74 pass** across 8 suites — `crew-shortcuts` (incl. strengthened collision assertion), `crew-footer` (incl. renamed V-2 test), `keybinding-map parity`, `cancellation-pane`, `process-status ×3`, `agents-pane-cost`.
+- Full suite baseline (before this batch): 5642 / 5639 pass / 0 fail. Two post-change full runs hit `ETIMEDOUT` on `spawnSync` inside integration child-spawn tests (`worktree-run`, `cleanup-full-flow`) under load (0 assertion failures — environmental flake). To be reconfirmed against CI.
+
 ## [v0.9.11] — Per-run lock path for background-runner (parallel-spawn race) (2026-06-27)
 
 Bug caught by an E2E parallel-spawn test in this session, NOT by unit tests (which cannot spawn multiple real processes). Independent of the F1-F5/redaction batches.

package/README.md

@@ -39,141 +39,7 @@ npm: pi-crew
 repo: https://github.com/baphuongna/pi-crew
 ```
 
-**v0.9.4 / v0.9.5 / v0.9.8 / v0.9.9**: See [CHANGELOG.md](CHANGELOG.md).
-
-### Highlights (v0.6.4 → v0.9.9)
-
-A long arc of **trust, cliff-resilience, and robustness** work. Principle: *build
-trust and cliff-resilience, stay lean, delete before adding.*
-
-#### v0.9.5 — fix "team run hangs forever at 25%" (2026-06-23)
-Two coupled runtime bugs caused recurring "run stuck at 25% (1/4)" failures
-across 4+ consecutive review/fast-fix runs. The combined symptom: scheduler
-appears to stop responding right after the first task (explorer) finishes, no
-progress to task 2, and `team action='status'` returns "Run not found" with
-**no diagnostic trail** to investigate. Manual `kill` of the parent `pi`
-process was the only workaround.
-
-- **🩹 Bug X (proximate cause)** — `purgeStaleActiveRunIndex`
-  (`src/runtime/crash-recovery.ts`) destroyed a run's `stateRoot` based on a
-  **frozen** `entry.updatedAt` (set once at registration, never refreshed).
-  Any long-running legitimate async run (≥5 min) whose worker had exited
-  lost its entire durable state. `saveRunTasks()` then silently no-op'd on
-  the missing dir, and the workflow could never advance. Fix: corroborate
-  liveness via the on-disk `manifest.updatedAt` AND the team-level
-  `heartbeat.json`; keep `stateRoot` on cancel so runs stay queryable and
-  resumable.
-- **🩹 Bug Y (root cause — why the scheduler died in the first place)** —
-  `src/runtime/background-runner.ts` redirected only `console.log` /
-  `console.error` to the log file. The first post-detach `console.debug`
-  call from `team-runner.ts:242` (inside `mergeTaskUpdatesPreservingTerminal`
-  → "Skipping stale merge") hit the disconnected stdout pipe → unhandled
-  `EPIPE` → process exit. Prior investigators concluded (incorrectly) that
-  the cause was a native crash, because diagnostic `[DIAG]` handlers never
-  fired on the EPIPE. Fix: extend the console redirect to `console.debug` /
-  `console.warn`, and wrap `fs.writeSync` in try-catch so any log-write
-  failure can never crash the scheduler.
-- **🧪 Regression coverage** — 7 new tests: 3 in
-  `test/unit/crash-recovery-purge-liveness.test.ts` (fresh-manifest-kept,
-  orphan-cancelled-preserved, fresh-heartbeat-kept) + 4 in
-  `test/unit/background-runner-console-redirect.test.ts` (drift-detector
-  pattern that exercises undefined / valid / EBADF / post-toggle logFd).
-- **📖 See [CHANGELOG.md](CHANGELOG.md) for full details**, including
-  why prior attempts to diagnose the hang kept destroying the only
-  evidence (Bug X nuked the stateRoot before anyone could read the EPIPE
-  crash in Bug Y).
-
-> **Recovering a stuck run from v0.9.4 or earlier:** the `stateRoot` for
-> those runs is already gone. Re-dispatch the workflow — new runs are
-> fully protected.
-
-#### v0.9.4 — macOS CI fixture (2026-06-23)
-- **🧪 BSD-vs-GNU grep fix** — benchmark test fixtures used
-  `grep --help` (exits 0 on GNU/Linux, exits 2 on BSD/macOS). Switched
-  the exit-0 fixture to `echo ok`; the not-in-allowlist fixture is now
-  `ls`. CI matrix is now green on all 3 OSes.
-- **📌 Process note** — this release re-commits to: **tag/publish ONLY
-  after the full OS matrix CI is green.** v0.9.3 was published mid-CI-run
-  (the macOS job hadn't finished); the package itself was correct (the
-  broken file is test-only and not shipped), but the repo CI went red.
-  v0.9.4 restores green CI. v0.9.5 follows the same discipline.
-
-#### v0.9.0 — goal loops + dynamic workflows (2026-06-18)
-Two new features, both modeled on Claude Code, built on a shared `runKind`
-background-dispatch discriminator.
-
-- **🎯 Autonomous goal loops** — `team action='goal'` runs a self-directed
-  multi-turn loop: a **worker** does a turn, a separate **LLM judge**
-  (capability-locked, no tools) evaluates the transcript + verification against
-  the objective, and on "not-achieved" the reason is fed into the next turn's
-  prompt. Stops on `achieved` / `maxTurns` / budget / `BLOCKED:` / user `stop`.
-  See [docs/goals.md](docs/goals.md).
-- **📜 Dynamic workflows (`.dwf.ts`)** — author orchestration as a TypeScript
-  script (JS loops/branch/cross-review) instead of a static step list. Runs in
-  the background, spawns subagents via `ctx.agent()`/`ctx.fanOut()`, holds
-  intermediate results in JS variables, and only `ctx.setResult()` reaches the
-  main context. `workflow-create`/`-delete` are ACE-gated (`confirm:true`,
-  user-confirmed). See [docs/dynamic-workflows.md](docs/dynamic-workflows.md).
-- **🛡️ Goal-wrap** (RFC v0.5 vision) — apply the goal completion-guarantee to
-  existing builtin workflows (`implementation`, `fast-fix`, `default`) via
-  per-workflow `.crew/config.json` toggle. Single-step workflows goal-wrap
-  end-to-end; multi-step workflows auto-downgrade to a normal team-run because
-  they crash non-deterministically under the V8/libuv event-loop (see [Known
-  limitations](#known-limitations)).
-- **🔐 Phase 1 integrity hardening** (P1a–P1g) — verification bookend snapshots,
-  anti-oscillation (`stuck` non-terminal + resumable), budget enforcement
-  (required or explicit opt-out), nonce-token feedback sanitization, secret
-  redaction at artifact-write (O(n) fix), global worker cap + workspace lock
-  (O_EXCL, startTime-safe). B2 confused-deputy (auto-detecting verification
-  commands) refused — user must declare verification explicitly.
-- **🧪 Phase 1.5 fast-follow** — opt-in mitigation toggles for residual risks:
-  `PI_CREW_VERIFICATION_SANITIZE_ENV=1` (strip provider secrets from the
-  verification subprocess), `PI_CREW_VERIFICATION_WORKTREE=1` (run verification
-  in a pristine git worktree at the T_snap commit SHA),
-  `PI_CREW_BG_REPORT_ON_FATAL=1` (V8 diagnostic report on fatal).
-- **🐛 TDZ fix** (Phase 1.5 #4) — live `team action='run' workflow='<dynamic>'`
-  was failing with a misleading "must export a default async function" error.
-  Root cause was a Temporal Dead Zone race in `team-tool/run.ts` when loaded via
-  the full Pi extension pipeline (`index.ts → … → run.ts`). Fixed by
-  `let`→`var` on the latch + lazy dynamic imports at call sites.
-
-#### v0.8.x — hardening & reliability (2026-06-17)
-- **🛠️ Split-scope install fix (v0.8.11)** — `team` runs no longer crash with
-  `Cannot find module '@earendil-works/pi-coding-agent'` when pi-crew and pi
-  live in separate node_modules trees (the default for `pi install`). New
-  `src/runtime/peer-dep.ts` resolves the ESM-only peer dep across 6 strategies.
-- **🔄 Model fallback on transient 5xx (v0.8.11)** — a hard-down provider
-  (`500 api_error "unknown error"`) now triggers the configured fallback
-  model instead of aborting the run. `isRetryableModelFailure` extended.
-- **🧊 Cold-start race eliminated (v0.8.6 → v0.8.10)** — under tsx, concurrent
-  subagent spawns raced module instantiation (`existsSync` / `CREW_README` /
-  `effectiveRunConfig` / `validateWorkflowForTeam`). Fixed graph-wide: warm at
-  registration + gate at spawn boundaries + per-site latches. 6/6 repro clean.
-- **🔒 Cross-project leak fixed (v0.8.8)** — ambient status / compaction no
-  longer bleed foreign-project runs into the current session. Cwd-scope
-  barrier (`isInProjectScope`), version-independent.
-- **🩺 Doctor runtime-warmup status (v0.8.7)** — `team doctor` shows whether
-  the module-graph warmup fired.
-- **🔍 Cold-verifier agent (v0.8.4)** — adversarial cross-check that re-derives
-  claims WITHOUT trusting prior analysis, catching confirmation bias.
-- **⚡ Per-write validator (v0.8.5)** — zero-cost `JSON.parse` on every
-  `write`/`edit`, appends a `🔴` blocker on malformed files.
-- **🎨 Terminal status (v0.8.3)** — tab title + Ghostty native progress bar.
-- **🧠 Skill confidence revived (v0.8.2)** — `adjustConfidence()` was dead
-  code; the effectiveness system now actually learns.
-- **🔧 Tool-restriction unification (v0.8.0)** — single `resolveToolPolicy`
-  across both spawn paths.
-- **🎯 F6/F1 interop granularity (v0.7.9)** — 7 skill roots, `.pi/agents/`
-  tier, tool wildcards, `excludeExtensions` denylist.
-
-#### v0.7.0 — Phase 0 + Phase 1 roadmap
-- **🛡️ Compaction resilience (O10)** — in-flight runs survive auto-compact.
-- **💰 Cost visibility (O1)** — per-role token + cost attribution.
-- **✋ Plan-level HITL (O5)** — `requirePlanApproval` gates any workflow.
-- **🧠 Cross-run memory (O4)** — `.crew/knowledge.md` injected every run.
-- **🎯 Single-agent cliff hedge** — `team plan singleAgent=true`.
 
----
 
 ## Features
 
@@ -697,7 +563,7 @@ npm run ci           # full CI-equivalent check
 npm pack --dry-run   # package verification
 ```
 
-Stats: **366 source files** (70K lines) · **506 test files** (66K lines) · **4,792 tests, 0 failures** · **CI: Ubuntu ✅ macOS ✅ Windows ✅**
+Stats: **431 source files** (87K lines) · **606 test files** (85K lines) · **~5,860 tests, 0 failures** · **CI: Ubuntu ✅ macOS ✅ Windows ✅**
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/extension/crew-shortcuts.ts

@@ -6,9 +6,25 @@
  * built-in keymap (see analysis of pi-tui core/keybindings defaults):
  *
  *   alt+s → open the pi-crew settings overlay (config + theme picker)
+ *   alt+c → open the pi-crew run dashboard overlay (mnemonic: **C**rew)
  *
- * `alt+<letter>` combos are safe: Pi only binds `alt+v`, `alt+enter`, and the
- * alt+arrow navigation keys. `alt+s` is mnemonic (settings) and free.
+ * OCCUPIED alt+ keys in the built-in keymap (must NOT reuse — verified against
+ * pi-tui TUI_KEYBINDINGS + pi core keybindings.js):
+ *   alt+b (cursor word left)   alt+f (cursor word right)
+ *   alt+d (delete word forward) alt+y (yank pop)
+ *   alt+v (paste)              alt+s (crew settings — this module)
+ *   alt+enter / alt+up/down/left/right / alt+backspace / alt+delete
+ * Free alt+<letter> keys include: a, c, e, g, h, i, j, k, l, m, n, o, p, q,
+ * r, t, u, w, x, z.
+ *
+ * NOTE: an earlier revision used `alt+d` for the dashboard; that collided
+ * with `tui.editor.deleteWordForward` and Pi's conflict detector stripped the
+ * editor binding. `alt+c` is free AND mnemonic.
+ *
+ * NOTE: alt+m (mailbox) and alt+t (status) were considered but are NOT wired
+ * — the mailbox overlay is run-scoped (requires a runId; reached via the
+ * dashboard) and there is no standalone status overlay (status is a text
+ * command). See the K-2 note accompanying openTeamDashboard in commands.ts.
  *
  * Shortcuts are guarded by `hasUI` so they never fire in print/RPC mode, and
  * by the optional `registerShortcut` API so older Pi versions degrade
@@ -39,6 +55,17 @@ const CREW_SHORTCUTS: ReadonlyArray<ShortcutRegistration> = [
 			await openTeamSettingsOverlay(ctx);
 		},
 	},
+	{
+		key: "alt+c",
+		description: "pi-crew: open run dashboard (Crew)",
+		// Lazy-import so the heavy UI module chain (RunDashboard etc.) is only
+		// loaded on first use, not at extension load.
+		handler: async (ctx) => {
+		// LAZY: defer dynamic import of ./registration/commands.ts to its call site.
+			const { openTeamDashboard } = await import("./registration/commands.ts");
+			await openTeamDashboard(ctx);
+		},
+	},
 ];
 
 /**

package/src/extension/knowledge-injection.ts

@@ -9,6 +9,16 @@
  * Philosophy (Round 6 stress-test): radically downsized. Just a Markdown
  * file the user can edit, surfaced into every run. No vector DB, no
  * embeddings, no graph. Simple = trustworthy.
+ *
+ * B2 section-aware injection (2026-06-28): knowledge.md splits cleanly into
+ * CONVENTIONS (always-relevant: Code Style, Environment, Architecture,
+ * Testing, Release Process — ~2.5KB) and SESSION-LOG (per-version post-
+ * mortems, incidents, fix detail — ~29KB, rarely relevant). Conventions
+ * are ALWAYS injected; session-log sections are injected on-demand via
+ * header-token IDF scoring against the task/goal, capped at
+ * MAX_SESSION_LOG_BYTES. Non-matched session-log is summarized as a section
+ * index with a `read` path-hint so the worker can recover any omitted topic.
+ * Design doc: research-findings/b2-section-aware-design.md.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -17,20 +27,179 @@ import { projectCrewRoot } from "../utils/paths.ts";
 
 /** The knowledge file, relative to the project crew root. */
 export const KNOWLEDGE_FILENAME = "knowledge.md";
-/** Cap injected knowledge to avoid unbounded system-prompt growth. */
-const MAX_KNOWLEDGE_BYTES = 16_000;
+
+/**
+ * Session-log injection cap (B2). Conventions are always injected in full;
+ * matched session-log sections are capped here to bound total prompt size.
+ * Sized so 2-3 typical sections (~1-2.5KB each) fit, while the largest single
+ * outlier (v0.9.10 IN PROGRESS, ~7KB) is excluded from a full-match scenario.
+ */
+const MAX_SESSION_LOG_BYTES = 5_000;
+
+/**
+ * Relevance context for section-aware injection. When omitted (or when goal/
+ * taskText are both absent), injection falls back to conventions-only — no
+ * IDF computation, no session-log body. This keeps callers without query
+ * context (main-session hook, legacy tests) stable.
+ */
+export interface KnowledgeQuery {
+	/** The team run goal (broad topic signal). */
+	goal?: string;
+	/** The step/task instruction text (narrow topic signal). */
+	taskText?: string;
+	/** The worker role (reserved for future role-floor/boost; not scored yet). */
+	role?: string;
+}
+
+/**
+ * Headers of sections always treated as CONVENTIONS (universal project rules).
+ * Anything NOT matching these (after the convention run) is SESSION-LOG.
+ * Header-matching is prefix + case-insensitive against the H2 title.
+ */
+const CONVENTION_HEADERS = ["Code Style", "Environment", "Architecture", "Testing", "Release Process"];
 
 /** Resolve the knowledge file path for a cwd (may not exist yet). */
 export function knowledgePath(cwd: string): string {
 	return path.join(projectCrewRoot(cwd), KNOWLEDGE_FILENAME);
 }
 
-/** Read knowledge content, truncated to a safe size. "" if absent/empty. */
-export function readKnowledge(cwd: string): string {
+interface KnowledgeSection {
+	/** H2 header text (without leading `## `). */
+	header: string;
+	/** Full section body including the `## ` header line. */
+	body: string;
+	/** Header tokens (lowercased, stopword-filtered) for IDF scoring. */
+	headerTokens: Set<string>;
+}
+
+const STOPWORDS = new Set([
+	"the", "a", "an", "is", "are", "of", "to", "in", "for", "and", "or", "not",
+	"with", "this", "that", "it", "be", "on", "at", "by", "do", "does", "how",
+	"what", "when", "from", "fix", "fixes", "fixed", "v0", "v1", "released",
+	"progress", "uncommitted", "not", "pushed", "published", "session", "post",
+]);
+
+/** Tokenize header text into a Set of lowercased non-stopword tokens. */
+function tokenizeHeader(header: string): Set<string> {
+	const tokens = new Set<string>();
+	for (const raw of header.toLowerCase().split(/[^a-z0-9.]+/)) {
+		// keep dot-paths (e.g. "run.lock", "config.ts") and alphanumerics >= 2 chars
+		const t = raw.replace(/^\.+|\.+$/g, "");
+		if (t.length >= 2 && !STOPWORDS.has(t) && !/^\d+$/.test(t)) tokens.add(t);
+	}
+	return tokens;
+}
+
+/** Parse knowledge.md into (conventions, sessionLog) sections by H2 header. */
+function parseKnowledgeSections(content: string): { conventions: KnowledgeSection[]; sessionLog: KnowledgeSection[] } {
+	const lines = content.split(/\r?\n/);
+	const sections: KnowledgeSection[] = [];
+	let current: { header: string; lines: string[] } | null = null;
+	for (const line of lines) {
+		const m = /^##\s+(.+?)\s*$/.exec(line);
+		if (m) {
+			if (current) sections.push({ header: current.header, body: current.lines.join("\n"), headerTokens: tokenizeHeader(current.header) });
+			current = { header: m[1]!, lines: [line] };
+		} else if (current) {
+			current.lines.push(line);
+		}
+	}
+	if (current) sections.push({ header: current.header, body: current.lines.join("\n"), headerTokens: tokenizeHeader(current.header) });
+
+	// Classify: a section is a CONVENTION if its header starts-with one of the
+	// known convention titles. Once we leave the convention run (first non-
+	// matching H2 after conventions), everything else is SESSION-LOG. This is
+	// self-healing: if knowledge.md is restructured, the classifier adapts.
+	const conventions: KnowledgeSection[] = [];
+	const sessionLog: KnowledgeSection[] = [];
+	let leftConventionRun = false;
+	for (const sec of sections) {
+		const isConvention = !leftConventionRun && CONVENTION_HEADERS.some((c) => sec.header.toLowerCase().startsWith(c.toLowerCase()));
+		if (isConvention) conventions.push(sec);
+		else {
+			leftConventionRun = true;
+			sessionLog.push(sec);
+		}
+	}
+	return { conventions, sessionLog };
+}
+
+/** Compute IDF (inverse document frequency) over session-log header tokens. */
+function computeIdf(sections: KnowledgeSection[]): Map<string, number> {
+	const N = sections.length;
+	const df = new Map<string, number>();
+	for (const s of sections) for (const token of s.headerTokens) df.set(token, (df.get(token) ?? 0) + 1);
+	const idf = new Map<string, number>();
+	for (const [token, freq] of df) idf.set(token, Math.log(N / freq)); // standard IDF; freq >= 1
+	return idf;
+}
+
+/** Tokenize a free-form query (goal/taskText) the same way as headers. */
+function tokenizeQuery(query: string): Set<string> {
+	const tokens = new Set<string>();
+	for (const raw of query.toLowerCase().split(/[^a-z0-9.]+/)) {
+		const t = raw.replace(/^\.+|\.+$/g, "");
+		if (t.length >= 2 && !STOPWORDS.has(t) && !/^\d+$/.test(t)) tokens.add(t);
+	}
+	return tokens;
+}
+
+/** Score a section by summed IDF of query tokens present in its header. */
+function scoreSection(queryTokens: Set<string>, headerTokens: Set<string>, idf: Map<string, number>): number {
+	let score = 0;
+	for (const token of queryTokens) if (headerTokens.has(token)) score += idf.get(token) ?? 0;
+	return score;
+}
+
+/**
+ * Select session-log sections relevant to the query, capped at budgetBytes.
+ * Greedy by descending score (then original order), drop-whole policy with a
+ * head-slice fallback for the single best match if nothing else fits (so a
+ * matched query never returns zero bytes).
+ */
+function selectSessionLog(query: string, sessionLog: KnowledgeSection[], budgetBytes: number): KnowledgeSection[] {
+	if (sessionLog.length === 0 || !query.trim()) return [];
+	const idf = computeIdf(sessionLog);
+	const queryTokens = tokenizeQuery(query);
+	// Match = ANY header-token overlap with the query. IDF still drives RANKING
+	// (rarer overlap ranks first), but a token that happens to appear in every
+	// section (IDF=0) must still count as a match — otherwise a query for a
+	// common-but-relevant keyword (e.g. "redaction") would return nothing.
+	const scored = sessionLog
+		.map((sec, idx) => {
+			const overlap = [...queryTokens].filter((t) => sec.headerTokens.has(t));
+			return { sec, score: overlap.reduce((sum, t) => sum + (idf.get(t) ?? 0), 0), idx, hasOverlap: overlap.length > 0 };
+		})
+		.filter((x) => x.hasOverlap);
+	if (scored.length === 0) return [];
+	scored.sort((a, b) => b.score - a.score || a.idx - b.idx);
+
+	const selected: KnowledgeSection[] = [];
+	let used = 0;
+	let bestMatch: { sec: KnowledgeSection; score: number } | undefined;
+	for (const { sec, score } of scored) {
+		if (score > (bestMatch?.score ?? -1)) bestMatch = { sec, score };
+		if (used + sec.body.length <= budgetBytes) {
+			selected.push(sec);
+			used += sec.body.length;
+		}
+	}
+	// Head-slice fallback: if the best match didn't fit (or nothing fit), inject
+	// a head-sliced copy of the single best match so the query isn't empty.
+	if (selected.length === 0 && bestMatch) {
+		const sliced = bestMatch.sec.body.slice(0, Math.max(0, budgetBytes));
+		selected.push({ ...bestMatch.sec, body: `${sliced}\n\n<!-- section truncated (session-log budget ${budgetBytes} bytes). Full file: use \`read\`. -->` });
+	}
+	return selected;
+}
+
+/** Read knowledge content. "" if absent/empty. */
+export function readKnowledge(cwd: string, query?: KnowledgeQuery): string {
 	try {
 		const p = knowledgePath(cwd);
 		const stat = tryStat(p);
 		if (!stat) {
+			sectionCache.delete(p);
 			knowledgeCache.delete(p);
 			return "";
 		}
@@ -39,14 +208,46 @@ export function readKnowledge(cwd: string): string {
 		// For a run with N workers this is N redundant readFileSync of the same
 		// file. Cache by (mtimeMs, size) and only re-read when the file changes.
 		const cacheKey = `${stat.mtimeMs}:${stat.size}`;
-		const cached = knowledgeCache.get(p);
-		if (cached && cached.key === cacheKey) return cached.content;
-		let content = fs.readFileSync(p, "utf8").trim();
-		if (content.length > MAX_KNOWLEDGE_BYTES) {
-			content = `${content.slice(0, MAX_KNOWLEDGE_BYTES)}\n\n<!-- knowledge.md truncated at ${MAX_KNOWLEDGE_BYTES} bytes -->`;
+
+		// B2: when no query context is provided (main-session hook, legacy
+		// callers, tests), keep the simple head-only path. This preserves the
+		// 4 existing unit tests exactly (they call readKnowledge(cwd)).
+		if (!query || (!query.goal && !query.taskText)) {
+			const cached = knowledgeCache.get(p);
+			if (cached && cached.key === cacheKey) return cached.content;
+			let content = fs.readFileSync(p, "utf8").trim();
+			if (content.length > MAX_KNOWLEDGE_HEAD_BYTES) {
+				content = `${content.slice(0, MAX_KNOWLEDGE_HEAD_BYTES)}\n\n<!-- knowledge.md truncated at ${MAX_KNOWLEDGE_HEAD_BYTES} bytes (head shown). Full file: ${p} — use the \`read\` tool if you need sections beyond the head. -->`;
+			}
+			knowledgeCache.set(p, { key: cacheKey, content });
+			return content;
+		}
+
+		// Section-aware path: cache parsed sections, select per-query.
+		const cachedSections = sectionCache.get(p);
+		let parsed: { conventions: KnowledgeSection[]; sessionLog: KnowledgeSection[] };
+		if (cachedSections && cachedSections.key === cacheKey) {
+			parsed = { conventions: cachedSections.conventions, sessionLog: cachedSections.sessionLog };
+		} else {
+			const content = fs.readFileSync(p, "utf8").trim();
+			parsed = parseKnowledgeSections(content);
+			sectionCache.set(p, { key: cacheKey, conventions: parsed.conventions, sessionLog: parsed.sessionLog });
+		}
+
+		const queryText = [query.goal, query.taskText].filter(Boolean).join(" \n ");
+		const matchedSessionLog = selectSessionLog(queryText, parsed.sessionLog, MAX_SESSION_LOG_BYTES);
+
+		const parts: string[] = [];
+		// Conventions: always full.
+		for (const sec of parsed.conventions) parts.push(sec.body);
+		// Matched session-log (drop-whole, budget-capped).
+		for (const sec of matchedSessionLog) parts.push(sec.body);
+		// Always: section-index of ALL session-log headers (recovery safety net).
+		if (parsed.sessionLog.length > 0) {
+			const indexLines = parsed.sessionLog.map((s) => `  - ${s.header}`);
+			parts.push(`<!-- Session-log sections in knowledge.md (not injected unless matched above — use \`read\` for detail):\n${indexLines.join("\n")}\nFull file: ${p} -->`);
 		}
-		knowledgeCache.set(p, { key: cacheKey, content });
-		return content;
+		return parts.join("\n").trim();
 	} catch {
 		return "";
 	}
@@ -68,9 +269,19 @@ interface CachedKnowledge {
 }
 const knowledgeCache = new Map<string, CachedKnowledge>();
 
+interface CachedSections {
+	key: string;
+	conventions: KnowledgeSection[];
+	sessionLog: KnowledgeSection[];
+}
+const sectionCache = new Map<string, CachedSections>();
+
+/** Head cap for the no-query (legacy / main-session) path. */
+const MAX_KNOWLEDGE_HEAD_BYTES = 2_000;
+
 /** Build the injected prompt fragment (empty if no knowledge). */
-export function buildKnowledgeFragment(cwd: string): string {
-	const content = readKnowledge(cwd);
+export function buildKnowledgeFragment(cwd: string, query?: KnowledgeQuery): string {
+	const content = readKnowledge(cwd, query);
 	if (!content) return "";
 	return [
 		"",
@@ -85,8 +296,18 @@ export function buildKnowledgeFragment(cwd: string): string {
 
 /**
  * Register the knowledge-injection hook. Appends project knowledge to the
- * system prompt on every agent start (main session + each crew worker,
- * since workers are child Pi processes that also fire before_agent_start).
+ * MAIN session's system prompt on `before_agent_start`. This hook does NOT
+ * fire for crew workers: they are spawned with `--no-extensions`, so the
+ * extension layer (and this hook) never loads in their process. Workers
+ * instead receive knowledge via `buildKnowledgeFragment(task.cwd)` injected
+ * into their prompt stablePrefix by `prompt-builder.ts`. Do NOT "fix" this
+ * perceived gap by making the hook reach workers — it would cause
+ * double-injection. (Verified by research workflow 2026-06-28.)
+ *
+ * The hook calls buildKnowledgeFragment(cwd) with NO query — so the main
+ * session gets conventions-only (no session-log noise), which is the right
+ * default for an interactive session that doesn't have a single task focus.
+ * Workers (which DO have a task) use the section-aware path via prompt-builder.
  */
 export function registerKnowledgeInjection(pi: ExtensionAPI): void {
 	pi.on("before_agent_start", (event: BeforeAgentStartEvent) => {