pi-crew 0.6.3 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## [0.7.1] — Fix: Auto-Continue After Compaction (2026-06-15)
+
+### Bug Fix
+
+- **`a??`** — **Compaction resilience actually works now.** The v0.7.0 fix (O10) only *appended a resume-directive entry* after compaction, but appending an entry does **not trigger an agent turn** — the session still waited for user input, so the user still had to type "continue". The real root cause: Pi's threshold auto-compaction (`_runAutoCompaction` reason=`threshold` willRetry=`false`) returns `this.agent.hasQueuedMessages()`, which is `false` when nothing is queued → the agent loop ends → Pi waits for input (documented: "NO auto-retry, user continues manually").
+
+  **Fix**: after `session_compact` fires, call `pi.sendUserMessage(continuationPrompt)`. Per Pi's API, `sendUserMessage` *always triggers a turn*. The agent automatically runs a new turn, sees the resume directive, calls `team status`, and continues the in-flight crew task — **zero manual intervention**.
+
+  - `buildContinuationPrompt()`: action-oriented prompt ("Context was compacted while crew tasks were in-flight. Continue the work — do not wait for me.")
+  - `triggerContinuation(pi, ctx, runs)`: fire-and-forget `sendUserMessage`, best-effort error handling
+  - Wired in both the reactive path (`session_compact` handler) and proactive path (`startCompact.onComplete`)
+  - Only fires when in-flight crew runs exist; non-crew compaction unaffected
+  - 6 new unit tests
+
+## [0.7.0] — Long-Term Roadmap: Compaction Resilience, Cost Visibility, Trust Trinity (2026-06-15)
+
+This release implements Phase 0 + Phase 1 of the pi-crew long-term roadmap (a 10-round research synthesis), plus the single-agent cliff hedge. The organizing principle: **build trust and cliff-resilience, stay lean, delete before adding.**
+
+### Highlights
+
+- **🛡️ Compaction resilience (O10)** — the #1 user pain ("after auto-compact, the task stops midway") is fixed. pi-crew now detects in-flight runs, injects an explicit resume directive into the compaction summary, and re-attaches after compaction. Tasks survive context compaction.
+- **💰 Cost visibility (O1)** — `team summary <runId>` now shows a full cost report with per-role attribution and token breakdown. Multi-agent's #1 barrier is cost; now it's visible.
+- **✋ Plan-level HITL for any workflow (O5)** — plan approval was locked to the `implementation` workflow; now any workflow honors `config.runtime.requirePlanApproval`, gating at the read-only→mutating (plan→execute) boundary.
+- **🧠 Cross-run memory (O4)** — `.crew/knowledge.md` is auto-read and injected into every agent's system prompt. pi-crew "gets better the longer you use it." Radically downsized (~80 LOC) replacement for the deleted MemoryStore.
+- **🎯 Single-agent cliff hedge (T0.5/T2.2)** — any workflow can be composed into a single sequential prompt (`team plan singleAgent=true`). Proves pi-crew's mission survives even if multi-agent is obsoleted by 1M+ token models.
+- **🧹 2,335 LOC of dead code removed** — grep-verified unused BudgetTracker, MemoryStore, `.bak` files, disabled brief-mode.
+- **🔌 Pi-api seam** — centralizes the 8-symbol Pi coupling surface in one file, hedging against Pi API churn.
+
+### Features (Phase 0 — Stabilize & Clean)
+
+- **`dbb4b6c`** — Deleted `budget-tracker.ts` (353 LOC), `memory-store.ts` (244 LOC), `brief-tool-overrides.ts` (400 LOC, disabled since 0.6.4), 3× `.bak` files (1,338 LOC), and their tests. Net −2,918 LOC including tests.
+- **`42c1442`** — **Compaction resilience (O10)**: `compaction-guard.ts` gained `collectInFlightRuns()`, `formatResumeDirective()`, and a new `session_compact` handler that re-injects a `crew:resume-directive` entry into the fresh post-compaction context + notifies the user. Covers both the proactive path and Pi's reactive auto-compact path.
+- **`40caf9e`** — `src/extension/pi-api.ts`: a type-level seam re-exporting the 8 public-API symbols pi-crew uses (ExtensionAPI, ExtensionContext, ExtensionCommandContext, ToolDefinition, defineTool, createBashTool, AgentSessionEvent, BeforeAgentStartEvent) + `BUILT_AGAINST_PI_VERSION` constant for version-drift diagnostics.
+- **`8f40b07`** — **Single-agent cliff hedge v0**: `single-agent-compose.ts` (~95 LOC). `orderSteps()` topologically sorts by dependsOn; `composeSingleAgentPrompt()` turns a workflow into one sequential execution prompt.
+
+### Features (Phase 1 — Trust Trinity)
+
+- **`3184303`** — **Cost visibility (O1)**: `state/usage.ts` gained `formatTokens()`, `formatCost()`, `aggregateUsageByRole()`, and `formatCostReport()`. The `summary` action now includes a multi-line report with token split + per-role % breakdown.
+- **`198994e`** — **Plan-level HITL (O5)**: `team-runner.ts` `requiresPlanApproval()` dropped the `workflow.name === "implementation"` constraint; `hasPendingMutatingTaskAtBoundary()` (new) gates at the plan→execute boundary for any workflow; `ensurePlanApprovalRequested()` is robust to a missing `assess` step and gives clearer approval guidance.
+- **`0272d77`** — **Cross-run memory (O4)**: `knowledge-injection.ts` (~80 LOC) registers a `before_agent_start` hook that appends `.crew/knowledge.md` (truncated to 16KB) to every agent's system prompt — main session + each crew worker.
+
+### Features (Phase 2 — Lean Power)
+
+- **`eeefe0a`** — **Single-agent runtime mode (T2.2)**: `singleAgent` boolean param on the `team plan` action. A Pi agent calling `team plan singleAgent=true` receives the full composed sequential prompt for any workflow. MCP tool consumption (T2.1) already existed for live-session workers (`mcp-proxy.ts`); verified and left in place rather than duplicated.
+
+### Upgrade Notes
+- New config: `runtime.requirePlanApproval = true` enables plan-level approval gates on any workflow.
+- New file: `.crew/knowledge.md` (optional) — write durable project knowledge; it's injected into every run.
+- Cost report appears automatically in `team summary`. Budget *enforcement* (auto-stop) is intentionally deferred until cost-data accuracy is validated.
+
+## [0.6.4] — Visually Rich Tool Rendering: Merged Frames, Live Progress Bars (2026-06-14)
+
+### Highlights
+- **Visually rich team & agent tool rendering** — framed cards with box-drawing borders, colored status badges, and structured layouts for `team` and `Agent` tool calls in the Pi TUI
+- **Merged call+result into ONE connected frame** — previously `renderCall` and `renderResult` each drew a complete box, producing two disconnected frames. Now they split a single frame (top border + header from `renderCall`, content + bottom border from `renderResult`) that merge seamlessly in Pi's `Box(1,1)` container
+- **Animated live progress bar during runs** — real-time task progress (`tasks completed=N/M`) parsed from streaming updates and rendered as a `████░░░░ N/M` bar with elapsed time, DURING the run (not after completion). Indeterminate "starting" phase uses an animated scanning bar
+- **Compact summary after completion** — collapsed cards show `✓ crew run  3/3 done · 1m2s · 26k tok · $0.068` with expand hint (`⌘E`) and agent briefs (`✓ explorer · 45.0s · 8.0k tok`)
+- **Crash fix on session resume** — `renderCall` was returning a `string` (from `buildFrame`), causing `TypeError: child.render is not a function` when Pi re-rendered stored tool calls on resume. Now wraps in `new Text(...)`
+
+### Bug Fixes
+- **`5613ecc`** — **Critical crash fix**: `teamToolRenderer.renderCall` and `agentToolRenderer.renderCall` returned `buildFrame(...)` (a string), not a Component. Pi's `addChild(string)` stored the string in `children[]`, then `Box.render()` called `child.render(width)` on the string → crash. Only surfaced on resume because fast-completing tools got their `Text` result frame painted before the string call frame was rendered. Fixed by wrapping both renderers in `new Text(..., 0, 0)`.
+- **`58ba6e5`** — Elapsed time miscalculation: Pi's `ctx.executionStarted` is a **boolean** flag (not a timestamp), so `Date.now() - true` produced ~56-year durations. Now timing is tracked via `ctx.state.briefStartedAt`.
+- **`1c2cf71`** — Reverted `lastComponent` reuse: returning `ctx.lastComponent` and mutating its private `.text` field crashed on session resume (deserialized components lose prototype methods). Pi already calls `renderContainer.clear()` before each `updateDisplay()`, so single-frame streaming is guaranteed without reuse.
+- **`7d01ebb`** — Typecheck fix: `agentToolRenderer.renderCall` had parameter named `_ctx` (unused convention) but `borderFromContext(ctx)` referenced `ctx` (`error TS2552`).
+
+### Reverts
+- **`0763e67`** — **Disabled brief tool overrides**. Re-registering built-in tools (read/bash/edit/write/find/grep/ls) replaced Pi's superior native renderers (syntax highlighting, diff views, full file content) with inferior custom `fullRender()` output, and caused `renderCall`/`renderResult` to duplicate path/command info. The file is retained for reference; re-enable by uncommenting one line in `register.ts`.
+
+### Test Fixes
+- **`39d1dc7`** — `AnimatedMascot` timing tests were flaky under CI load. The animation advances via `setInterval(20ms)` which is `unref()`'d; under `--test-concurrency=4` the unref'd timers get delayed, so a fixed 70ms wait wasn't always enough for one tick. Replaced fixed waits with polling loops (retry until the frame advances, up to 600ms). Applied to both cat and armin animation tests. Robust: finishes fast normally (~40ms), tolerates heavy load.
+
+### Features (UI)
+- **`a7b703b`** — `parseStreamingProgress()` parses `tasks completed=N running=M` and `N/M done` formats from streaming progress text; `renderScanBar()` renders an animated bouncing bar for the indeterminate "starting" phase.
+- **`9b1de38`** — `onRunStarted` now called in the async path of `run.ts` (was only in foreground path), so background runs attach the progress binder and show real-time progress instead of stuck "starting".
+- **`5741d73`** — `formatCompactToolProgress` always includes the `tasks N/M done status=X` line even when an active agent is present (was skipped via `else if` bug).
+- **`22d8132`** — `extractContentText` returns only the LAST text block (was `.join("\n")` on all blocks, causing stacked progress frames during streaming).
+- **`3777fbc`** — `buildFrameTop()` / `buildFrameBottom()` split rendering so `renderCall` + `renderResult` merge into one connected frame; `borderFromContext(ctx)` keeps top and bottom border colors consistent (accent while running, green on success, red on error).
+- **`9fa5153`** — Cost display in collapsed cards (`computeTotalCost()`), `⌘E` expand hint, agent briefs with duration/tokens, `shortenPath()` (`$HOME` → `~`), OSC 8 clickable paths (`linkPath()`).
+- **`f9c9803`** — Frame width auto-adjusts to terminal via `process.stdout.columns`.
+
+### Stats
+- 9 commits since v0.6.3
+- CI green on Ubuntu, macOS, and Windows
+
 ## [0.6.3] — Cross-Platform CI, 87 Test Fixes, Worktree Validation, Heartbeat & Crash Fixes (2026-06-12)
 
 ### Highlights

package/README.md

@@ -9,7 +9,29 @@ npm: pi-crew
 repo: https://github.com/baphuongna/pi-crew
 ```
 
-**v0.6.3**: See [CHANGELOG.md](CHANGELOG.md).
+**v0.6.4**: See [CHANGELOG.md](CHANGELOG.md).
+
+### Highlights (v0.6.4 → v0.7.0)
+
+This release implements **Phase 0 + Phase 1** of the long-term roadmap (synthesized from a 10-round research process), plus the **single-agent cliff hedge**. Principle: *build trust and cliff-resilience, stay lean, delete before adding.*
+
+- **🛡️ Compaction resilience (O10)** — the #1 user pain ("after auto-compact, the task stops midway") is fixed. In-flight crew runs are detected, a resume directive is injected into the compaction summary, and tasks re-attach after compaction.
+- **💰 Cost visibility (O1)** — `team summary <runId>` now shows a full cost report with per-role attribution and token breakdown (`$0.77 — executor 79%, reviewer 14%...`).
+- **✋ Plan-level HITL for any workflow (O5)** — set `runtime.requirePlanApproval = true` to gate any workflow at the plan→execute boundary; approve via `team api op=approve-plan`.
+- **🧠 Cross-run memory (O4)** — `.crew/knowledge.md` is auto-injected into every run's system prompt. pi-crew remembers project context across runs.
+- **🎯 Single-agent cliff hedge** — `team plan singleAgent=true` composes any workflow into one sequential prompt, so pi-crew's mission survives even if multi-agent is obsoleted by large-context models.
+- **🧹 2,335 LOC of dead code removed** + **Pi-api seam** centralizing the coupling surface.
+
+### Highlights (v0.6.3 → v0.6.4)
+
+- **Visually rich tool rendering** — `team` and `Agent` tool calls now render as framed cards in the Pi TUI with box-drawing borders, colored status badges, and structured layouts
+- **Merged call+result into ONE connected frame** — the call header and result body now form a single seamless frame instead of two disconnected boxes
+- **Animated live progress bar during runs** — real-time `████░░░░ N/M` task progress with elapsed time, rendered DURING the run; indeterminate "starting" phase uses an animated scanning bar
+- **Compact completion summary** — collapsed cards show `✓ crew run  3/3 done · 1m2s · 26k tok · $0.068` with expand hint and per-agent briefs
+- **Critical crash fix on session resume** — `renderCall` was returning a `string` instead of a `Text` component, causing `TypeError: child.render is not a function` when Pi re-rendered stored tool calls
+- **Disabled brief tool overrides** — reverted the experimental brief mode that replaced Pi's superior native renderers (syntax highlighting, diff views, full content)
+- **Flaky test fix** — `AnimatedMascot` timing tests made CI-load-robust via polling loops
+- **CI green** — 0 failures on Ubuntu, macOS, and Windows
 
 ### Highlights (v0.6.2 → v0.6.3)
 
@@ -249,6 +271,63 @@ If preconditions are not met, a friendly error message is returned instead of cr
 
 ---
 
+## Reliability & Trust
+
+### Compaction resilience
+
+pi-crew survives Pi's context compaction. When the context is compacted (auto or manual), in-flight crew runs are detected and a **resume directive** is injected into the post-compaction context, so tasks continue instead of stalling. You'll see a notification like:
+
+```
+Context compacted. 1 pi-crew run(s) still in-flight — use team status to continue.
+```
+
+### Plan-level human-in-the-loop (HITL)
+
+Set `runtime.requirePlanApproval = true` to gate **any workflow** at the plan→execute boundary. After the read-only (planning) phases complete, the run pauses for explicit approval before mutating tasks run:
+
+```
+team api op=approve-plan runId=<runId>   # approve → execute
+  team api op=cancel-plan runId=<runId>    # cancel
+```
+
+This is plan-level (not per-step) — per-step gates would kill the parallelism that's pi-crew's point.
+
+### Cross-run memory (`.crew/knowledge.md`)
+
+Create `.crew/knowledge.md` in your project root with durable learnings (code style, test commands, common pitfalls, past refactors). It's auto-read (up to 16KB) and injected into **every** agent's system prompt — the main session and each crew worker. pi-crew gets better the longer you use it.
+
+```markdown
+# Project Knowledge
+- Tests: run with `npm test` (not jest directly)
+- Style: tabs, not spaces
+- Auth refactor (2026-06): split auth.ts into session.ts + api.ts
+```
+
+### Cost visibility
+
+Every `team summary <runId>` includes a per-role cost report:
+
+```
+═══ Cost Report ═══
+Tokens: 134k (in 112k, out 5.7k, cache-write 16k)
+Cost: $0.7700 across 18 turn(s)
+By role:
+  executor (2 tasks): $0.6100 — 79%, 98k tok, 13 turns
+  reviewer (1 task): $0.1100 — 14%, 23k tok, 3 turns
+```
+
+### Single-agent mode (cliff hedge)
+
+Any workflow can run single-agent instead of multi-agent — composing all phases into one sequential prompt:
+
+```
+team plan team=default workflow=default goal="..." singleAgent=true
+```
+
+This is pi-crew's cliff-resilient mode: the workflow definitions, phase structure, and artifact contracts survive even if a single large-context model outperforms multi-agent teams.
+
+---
+
 ## Tool Actions
 
 ```json

package/docs/ui-optimization-plan.md

@@ -0,0 +1,447 @@
+# pi-crew UI Optimization & Beautification Plan
+
+> Based on deep analysis of oh-my-pi patterns + pi-crew current UI state.
+> Date: 2026-06-12
+> Status: Draft — awaiting approval
+
+## Current State
+
+### pi-crew UI (~7,800 lines across 45 files)
+
+| Component | Lines | Status |
+|---|---|---|
+| `run-snapshot-cache.ts` | 827 | Complex, over-engineered |
+| `settings-overlay.ts` | 723 | Functional |
+| `crew-widget.ts` | 544 | **High complexity, hard to read** |
+| `run-dashboard.ts` | 536 | Dense, many responsibilities |
+| `mascot.ts` | 444 | Cute but bloated |
+| `tool-render.ts` | 380 | **Needs pattern overhaul** |
+| `theme-adapter.ts` | 190 | Defensive but verbose |
+
+### Key Problems
+
+1. **No theme color consistency** — `CrewThemeColor` has ~22 slots vs oh-my-pi's 40+
+2. **Tool rendering reimplements logic** — pi-brief's delegate-execute pattern is cleaner
+3. **Widget is monolithic** — 544 lines doing state management, rendering, caching, and formatting
+4. **No structured interaction** — `respond` action is free-text only; no `ask_user`-style schema
+5. **Raw ANSI codes in places** — mixing `theme.fg()` with `\x1b[38;5;2m`
+6. **No brief/compact mode** — all output is verbose, no toggle for condensed display
+7. **Checkpoint display is text-heavy** — run history shows full text vs compact stats
+
+---
+
+## Phase 1: Theme System Upgrade
+
+**Priority**: HIGH — foundation for all other UI work
+**Effort**: 2-3 days
+**Risk**: LOW (additive changes, no breaking API)
+
+### 1.1 Expand Theme Color Slots
+
+**Current** (`src/ui/theme-adapter.ts`):
+```typescript
+export type CrewThemeColor =
+  | "accent" | "border" | "borderAccent" | "borderMuted"
+  | "success" | "error" | "warning" | "muted" | "dim" | "text"
+  | "toolDiffAdded" | "toolDiffRemoved" | "toolDiffContext"
+  | "syntaxKeyword" | "syntaxString" | "syntaxNumber"
+  | "syntaxComment" | "syntaxFunction" | "syntaxVariable"
+  | "syntaxType" | "syntaxOperator" | "syntaxPunctuation"
+  | "mdCodeBlock";
+```
+
+**Target** — add from oh-my-pi's 40+ slots:
+```typescript
+export type CrewThemeColor =
+  // Existing (keep)
+  | "accent" | "border" | "borderAccent" | "borderMuted"
+  | "success" | "error" | "warning" | "muted" | "dim" | "text"
+  | "toolDiffAdded" | "toolDiffRemoved" | "toolDiffContext"
+  | "syntaxKeyword" | "syntaxString" | "syntaxNumber"
+  | "syntaxComment" | "syntaxFunction" | "syntaxVariable"
+  | "syntaxType" | "syntaxOperator" | "syntaxPunctuation"
+  | "mdCodeBlock"
+  // NEW — message display
+  | "userMessageText" | "customMessageLabel"
+  // NEW — tool rendering
+  | "toolTitle"       // already used in tool-render.ts but missing from type
+  | "toolOutput"
+  | "toolPending" | "toolSuccess" | "toolError"
+  // NEW — markdown
+  | "mdHeading" | "mdLink" | "mdCode" | "mdQuote" | "mdHr" | "mdListBullet"
+  // NEW — thinking gradient (6 levels)
+  | "thinkingOff" | "thinkingMinimal" | "thinkingLow"
+  | "thinkingMedium" | "thinkingHigh" | "thinkingXhigh"
+  // NEW — special
+  | "bashMode" | "thinkingText";
+
+export type CrewThemeBg =
+  // Existing
+  | "selectedBg" | "userMessageBg" | "toolPendingBg" | "toolSuccessBg" | "toolErrorBg"
+  // NEW
+  | "customMessageBg";
+```
+
+**Files to change**: `src/ui/theme-adapter.ts`
+
+### 1.2 Theme Color Fallback Map
+
+Add default ANSI values for all new slots so widgets work even with minimal themes:
+
+```typescript
+const THEME_FALLBACKS: Record<CrewThemeColor, string> = {
+  toolTitle: "\x1b[36m",     // cyan
+  toolOutput: "\x1b[38;5;245m", // gray
+  toolPending: "\x1b[38;5;240m",
+  toolSuccess: "\x1b[32m",
+  toolError: "\x1b[31m",
+  mdHeading: "\x1b[33m",     // yellow
+  mdLink: "\x1b[35m",        // indigo
+  mdCode: "\x1b[32m",        // green
+  // ... all new slots
+};
+```
+
+### 1.3 Remove Raw ANSI from Business Logic
+
+Find and replace all raw `\x1b[38;5;XXXm` in non-UI files with `theme.fg("slot", text)` calls.
+
+**Files to audit**:
+- `src/ui/tool-render.ts` — check for raw ANSI
+- `src/extension/registration/commands.ts` — status line rendering
+- `src/runtime/task-display.ts` — display formatting
+
+---
+
+## Phase 2: Tool Rendering Overhaul
+
+**Priority**: HIGH — visible improvement to every tool call display
+**Effort**: 2-3 days
+**Risk**: MEDIUM (changes how tool calls look)
+
+### 2.1 Adopt Rendering-Only Override Pattern
+
+**From oh-my-pi's pi-brief**: Register tool rendering that delegates execution to original.
+
+**Current pi-crew approach** (`src/ui/tool-render.ts`):
+- 380 lines of monolithic rendering functions
+- Separate `renderTeamToolCall`, `renderAgentToolCall`, `renderTeamToolResult`, `renderAgentToolResult`
+- Each function handles both collapsed and expanded mode internally
+
+**Target**: Split into focused renderers using a registry pattern:
+
+```typescript
+// src/ui/tool-renderers/index.ts
+export interface ToolRenderer {
+  renderCall(args: unknown, theme: CrewTheme, expanded: boolean): Component;
+  renderResult(result: unknown, theme: CrewTheme, expanded: boolean): Component;
+}
+
+// src/ui/tool-renderers/team-renderer.ts
+export const teamToolRenderer: ToolRenderer = {
+  renderCall(args, theme, expanded) { ... },
+  renderResult(result, theme, expanded) { ... },
+};
+
+// src/ui/tool-renderers/agent-renderer.ts
+export const agentToolRenderer: ToolRenderer = { ... };
+```
+
+### 2.2 Compact Brief Mode for Tool Output
+
+**From pi-brief**: Add a configurable "brief" toggle that shows one-line summaries.
+
+```typescript
+// New: src/ui/tool-renderers/brief-mode.ts
+export function briefResult(result: ToolResult, theme: CrewTheme): string {
+  // read → "→ 142 lines"
+  // bash → "→ done" or "→ 12 lines"
+  // edit → "→ edited +3 -1"
+  // write → "→ written"
+  // team → "→ 3/3 tasks · 1.2m · 45k tok"
+  // agent → "✓ explorer · 8 tools · 23.4s"
+}
+```
+
+Add `/crew-brief on|off` command and persist state via `pi.appendEntry()`.
+
+### 2.3 Team Tool Result — Compact Stats Display
+
+**From pi-rewind's checkpoint display**: Show goal + task stats in one line.
+
+**Current**:
+```
+team action='run' (implementation) · status=completed · runId=team_2026... · goal="Investigate failing..."
+```
+
+**Target** (compact):
+```
+✓ team/implementation · 3/3 tasks · 1.2m · ↑45k ↓12k · $0.042
+```
+
+With expanded (Ctrl+O):
+```
+✓ team/implementation · 3/3 tasks · 1.2m · ↑45k ↓12k · $0.042
+├─ ✓ explorer · 8 tools · 23.4s · ↑12k ↓4k
+├─ ✓ executor · 15 tools · 41.2s · ↑22k ↓6k
+└─ ✓ verifier · 5 tools · 12.1s · ↑11k ↓2k
+```
+
+---
+
+## Phase 3: Widget Refactor
+
+**Priority**: MEDIUM — internal cleanup, same visual output
+**Effort**: 3-4 days
+**Risk**: MEDIUM (core display component)
+
+### 3.1 Split crew-widget.ts into Modules
+
+**Current**: 544 lines monolith doing everything.
+
+**Target structure**:
+```
+src/ui/widget/
+├── index.ts              # Public API: updateCrewWidget, stopCrewWidget
+├── widget-component.ts   # CrewWidgetComponent class (~100 lines)
+├── widget-model.ts       # Data fetching + caching (~100 lines)
+├── widget-renderer.ts    # Line building + colorizing (~150 lines)
+├── widget-formatters.ts  # formatTokens, formatDuration, agentStats (~100 lines)
+└── widget-types.ts       # Shared types
+```
+
+### 3.2 Adopt SessionStateMap Pattern
+
+**From oh-my-pi**: Generic session-scoped state container instead of scattered maps.
+
+```typescript
+// src/state/session-state-map.ts (new)
+export class SessionStateMap<T> {
+  private map = new Map<string, T>();
+  getOrUndefined(sessionId: string): T | undefined { ... }
+  set(sessionId: string, value: T): void { ... }
+  delete(sessionId: string): void { ... }
+}
+```
+
+Use this in widget, dashboard, and live-agent-manager instead of separate `Map<string, ...>` instances.
+
+### 3.3 Render Coalescing Optimization
+
+The widget currently rebuilds signature strings on every render call. Optimize:
+- Pre-compute signatures when data changes, not on render
+- Use a simple counter-based invalidation instead of string concatenation
+- Eliminate `this.cacheSignature` string comparison in hot path
+
+---
+
+## Phase 4: Dashboard Polish
+
+**Priority**: MEDIUM
+**Effort**: 3-4 days
+**Risk**: LOW
+
+### 4.1 Run History — Compact Checkpoint Style
+
+**From pi-rewind**: Show runs with file-change statistics.
+
+**Current** (status command output):
+```
+Run: team_20260612100313...
+Status: completed
+Team: implementation
+Goal: Fix failing tests
+Tasks: 3/3
+Duration: 5m23s
+Tokens: 45.2k
+```
+
+**Target** (compact):
+```
+✓ team_...3d7f  implementation · Fix failing tests
+   3/3 tasks · 5m23s · ↑45k ↓12k
+   14 files +342 -87
+```
+
+### 4.2 Agent Progress — Thinking Level Visualization
+
+**From oh-my-pi's thinking gradient**: Show thinking intensity with color gradient.
+
+```typescript
+function thinkingColor(level: number, theme: CrewTheme): CrewThemeColor {
+  // level 0-5 → off, minimal, low, medium, high, xhigh
+  return ["thinkingOff", "thinkingMinimal", "thinkingLow",
+          "thinkingMedium", "thinkingHigh", "thinkingXhigh"][level];
+}
+```
+
+Apply to agent activity line when agent is "thinking..." (no tool call, just LLM processing).
+
+### 4.3 Dashboard Pane Improvements
+
+**Agents pane**: Add compact/expanded toggle per agent
+**Progress pane**: Use brief mode rendering from Phase 2
+**Mailbox pane**: Add structured response schema option
+**Health pane**: Color-code issues by severity
+
+---
+
+## Phase 5: Structured Interaction
+
+**Priority**: MEDIUM
+**Effort**: 4-5 days
+**Risk**: MEDIUM (new feature)
+
+### 5.1 Structured Respond Action
+
+**From pi-clarify**: Add schema validation to `respond` action.
+
+```typescript
+// In team-tool/respond.ts
+interface RespondOptions {
+  message: string;
+  // NEW: structured answer option
+  answer?: {
+    type: "select" | "text" | "confirm";
+    value: string | boolean;
+    label?: string;
+  };
+}
+```
+
+### 5.2 Secret Rejection in Tool Inputs
+
+**From pi-clarify's SECRET_WORDS**: Add to all tool inputs that accept user text.
+
+```typescript
+const SECRET_PATTERNS = [
+  "api key", "apikey", "auth token", "cookie", "credential",
+  "password", "private key", "secret", "token",
+];
+```
+
+Already partially done in `env-filter.ts`, but should extend to `goal`, `message`, `task` parameters.
+
+---
+
+## Phase 6: Code Quality from oh-my-pi
+
+**Priority**: LOW-MEDIUM (foundation for long-term)
+**Effort**: 2-3 days
+**Risk**: LOW
+
+### 6.1 Type Guard Library
+
+**From runtime-core**: Create `src/utils/guards.ts` with systematic type guards.
+
+```typescript
+// src/utils/guards.ts
+export function isRecord(value: unknown): value is Record<string, unknown> { ... }
+export function isString(value: unknown): value is string { ... }
+export function isNumber(value: unknown): value is number { ... }
+export function isNonEmptyString(value: unknown): value is string { ... }
+export function isArrayOf<T>(guard: (v: unknown) => v is T): (v: unknown) => v is readonly T[] { ... }
+export function getStringField(value: unknown, key: string): string | undefined { ... }
+export function getNumberField(value: unknown, key: number): number | undefined { ... }
+export function errorMessage(err: unknown): string { ... }
+```
+
+Replace scattered `typeof x === "string"` checks across codebase.
+
+### 6.2 No-Any Lint Rule
+
+Add ESLint rule to enforce `unknown` over `any`:
+
+```javascript
+// .eslintrc
+{
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/no-unsafe-assignment": "error",
+    "@typescript-eslint/no-unsafe-call": "error"
+  }
+}
+```
+
+### 6.3 mkdir-Based Locking (Optional)
+
+**From pi-checkpoint**: Replace JSON token-based locks with `mkdir` atomic locks.
+
+This is a bigger change — could be Phase 7 if needed.
+
+---
+
+## Implementation Order & Timeline
+
+| Phase | Duration | Depends On | Impact |
+|---|---|---|---|
+| **Phase 1**: Theme System | 2-3 days | Nothing | Foundation for all UI |
+| **Phase 2**: Tool Rendering | 2-3 days | Phase 1 | Every tool call looks better |
+| **Phase 3**: Widget Refactor | 3-4 days | Phase 1 | Internal cleanup |
+| **Phase 4**: Dashboard Polish | 3-4 days | Phase 1, 2 | Visible improvement |
+| **Phase 5**: Structured Interaction | 4-5 days | Phase 2 | New feature |
+| **Phase 6**: Code Quality | 2-3 days | Nothing | Long-term maintainability |
+
+**Total estimated**: 16-22 days (can parallelize Phase 1+6, Phase 2+3)
+
+### Recommended Execution
+
+```
+Week 1: Phase 1 (Theme) + Phase 6 (Code Quality)  [parallel]
+Week 2: Phase 2 (Tool Rendering)
+Week 3: Phase 3 (Widget) + Phase 4 (Dashboard)  [sequential]
+Week 4: Phase 5 (Structured Interaction) + polish
+```
+
+---
+
+## Success Metrics
+
+| Metric | Current | Target |
+|---|---|---|
+| Theme color slots | 22 | 40+ |
+| Raw ANSI in business logic | ~15 instances | 0 |
+| Widget lines of code | 544 | ~150 (per module) |
+| Tool result compact display | N/A | All 7 tool types |
+| Structured respond | Free text only | Schema-validated |
+| `any` in production code | ~40 instances | 0 |
+| Type guard reuse | Scattered | Centralized in guards.ts |
+
+---
+
+## Risks & Mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Theme slot additions break existing themes | All new slots have fallback ANSI values |
+| Widget refactor breaks live updates | Keep same public API, refactor internals only |
+| Brief mode confuses users | Default OFF, toggle via `/crew-brief on` |
+| Structured respond breaks existing workflows | `message` field still accepts free text; `answer` is optional |
+| No-any lint produces too many errors | Incremental: start with new files, then expand |
+
+---
+
+## Files to Create/Modify
+
+### New Files
+- `src/ui/tool-renderers/index.ts`
+- `src/ui/tool-renderers/team-renderer.ts`
+- `src/ui/tool-renderers/agent-renderer.ts`
+- `src/ui/tool-renderers/brief-mode.ts`
+- `src/ui/widget/index.ts`
+- `src/ui/widget/widget-component.ts`
+- `src/ui/widget/widget-model.ts`
+- `src/ui/widget/widget-renderer.ts`
+- `src/ui/widget/widget-formatters.ts`
+- `src/ui/widget/widget-types.ts`
+- `src/state/session-state-map.ts`
+- `src/utils/guards.ts`
+
+### Modified Files
+- `src/ui/theme-adapter.ts` — expand color types + fallbacks
+- `src/ui/tool-render.ts` — slim down, delegate to renderers
+- `src/ui/crew-widget.ts` — split into widget/ modules
+- `src/ui/run-dashboard.ts` — compact display + thinking gradient
+- `src/ui/status-colors.ts` — add new status colors
+- `src/extension/team-tool/respond.ts` — structured response option
+- `src/extension/registration/commands.ts` — add `/crew-brief` command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -33,6 +33,7 @@
     "teams/",
     "workflows/",
     "skills/**/SKILL.md",
+    "themes/",
     "README.md",
     "AGENTS.md",
     "docs/",