pi-crew 0.1.41 → 0.1.44

package/docs/refactor-tasks-phase5.md

@@ -1,402 +1,402 @@
-# Phase 5 Refactor Plan — Footer/Selectlist/Hot-reload từ pi-mono coding-agent
-
-> Xuất xứ: re-read `source/pi-mono/packages/coding-agent/src/modes/interactive/components/{footer,bordered-loader,dynamic-border,visual-truncate,diff,countdown-timer,extension-selector,theme-selector,custom-message,tool-execution,bash-execution}.ts` + `theme/theme.ts` (28/04/2026).
-> Mục tiêu: vá lỗi subtle còn lại từ Phase 4, hot-reload theme, port footer/select-list pattern, chuẩn hóa border + tool state styling.
-> Phase 4 đã hoàn tất, baseline: tsc 0 errors, 222 unit + 21 integration pass, commit `44fdd02`.
-
-## Quy ước chung
-- Không phá vỡ public API (slash commands, tool actions, config schema). Mọi thay đổi nội bộ.
-- Sau mỗi task: `npx tsc --noEmit` + `npm run test:unit` (+ `test:integration` nếu liên quan render/runtime).
-- Không thêm dependency runtime mới. Tất cả implement self-contained hoặc qua peer dep `@mariozechner/pi-tui` đã có.
-- Mỗi task = 1 commit độc lập có thể revert. Đặt tên test bám sát hành vi.
-- Ưu tiên backward compatibility: default behavior không đổi, opt-in qua config khi có hành vi mới.
-
-## Trạng thái cập nhật
-- [x] Task #50 — Fix `truncateToVisualLines` slice-after-merge bug
-- [x] Task #51 — Memoize `visibleWidth` LRU cache
-- [x] Task #52 — Theme hot-reload subscription
-- [x] Task #53 — Theme adapter `inverse` ANSI fallback
-- [x] Task #54 — `CrewFooter` component port
-- [x] Task #55 — `CrewSelectList` adapter
-- [x] Task #56 — `DynamicCrewBorder` reusable + CountdownTimer 1s tick
-- [x] Task #57 — Tool state styling cho transcript-viewer
----
-
-## Tier 1 — Bug fixes & correctness (low risk, immediate value)
-
-Mục tiêu: 2 task, vá bug từ Phase 4 + tăng hiệu năng nhỏ. Ước tính: 0.5 ngày.
-
-### Task #50 — Fix `truncateToVisualLines` slice-after-merge bug
-**Source**: `pi-mono/coding-agent/components/visual-truncate.ts`
-**Đích**: `pi-crew/src/utils/visual.ts`
-
-**Lý do**: Phase 4 #47 implement `truncateToVisualLines` với logic:
-```ts
-const visualLines = text.split("\n").flatMap((line) =>
-  wrapHard(pad(line, ...).trimEnd(), effectiveWidth).slice(0, Math.max(1, maxVisualLines))
-);
-```
-Bug: `slice(0, maxVisualLines)` áp dụng **per source line** thay vì **toàn bộ visual lines sau merge**. Nếu 1 source line wrap thành N visual lines (N > maxVisualLines), kết quả lấy đầu line đó, không phải tail của toàn bộ output. Khi nhiều source line, tổng visual có thể vượt maxVisualLines.
-
-pi-mono dùng pattern đúng: render rồi `slice(-maxVisualLines)`.
-
-**Logic chuẩn**:
-```ts
-export function truncateToVisualLines(text, maxVisualLines, width, paddingX = 0) {
-  if (!text) return { visualLines: [], skippedCount: 0 };
-  const effectiveWidth = Math.max(1, width - paddingX * 2);
-  const allVisual = text.split("\n").flatMap((line) =>
-    wrapHard(pad(line, effectiveWidth).trimEnd(), effectiveWidth)
-  );
-  if (allVisual.length <= maxVisualLines) return { visualLines: allVisual, skippedCount: 0 };
-  return { visualLines: allVisual.slice(-maxVisualLines), skippedCount: allVisual.length - maxVisualLines };
-}
-```
-
-**Acceptance**:
-- 1 source line wrap thành 5 visual lines, maxVisualLines=2 → trả về 2 visual lines cuối + skippedCount=3
-- 3 source lines × 2 visual mỗi line = 6 visual, maxVisualLines=4 → trả về 4 cuối + skippedCount=2
-- empty input → `{ visualLines: [], skippedCount: 0 }` (đổi từ `[""]` về `[]` để khớp pi-mono)
-
-**Verification**: 2 unit test mới trong `test/unit/visual.test.ts`. Verify transcript-viewer integration vẫn pass test cũ.
-
-**Risk**: thay đổi semantic empty input — kiểm tra all callers (transcript-viewer, run-dashboard) handle `[]` thay vì `[""]`.
-
----
-
-### Task #51 — Memoize `visibleWidth` qua LRU cache
-**Source**: pattern caching từ pi-tui `utils.ts`
-**Đích**: `pi-crew/src/utils/visual.ts`
-
-**Lý do**: `visibleWidth(value)` được gọi trong:
-- `pad`, `truncateToWidth`, `wrapHard` (mỗi character iter)
-- `crew-widget.ts colorWidgetLine` (mỗi line, mỗi tick 250ms)
-- `RunDashboard.render` (5-10 lần per render)
-- Total ước tính: 50+ calls/render × 4 render/sec = 200+ regex ops/sec.
-
-Cache key = string identity, value = width. Reset khi cache > 256 entries (FIFO eviction).
-
-**API**:
-```ts
-const widthCache = new Map<string, number>();
-const CACHE_LIMIT = 256;
-
-export function visibleWidth(value: string): number {
-  const cached = widthCache.get(value);
-  if (cached !== undefined) return cached;
-  let length = 0;
-  for (const char of value.replace(ANSI_PATTERN, "")) {
-    if (char !== "\n") length += 1;
-  }
-  if (widthCache.size >= CACHE_LIMIT) {
-    const firstKey = widthCache.keys().next().value;
-    if (firstKey !== undefined) widthCache.delete(firstKey);
-  }
-  widthCache.set(value, length);
-  return length;
-}
-```
-
-**Acceptance**:
-- `visibleWidth("foo")` gọi 1000 lần → chỉ tính 1 lần (kiểm qua spy với regex.exec count nếu có Diff bench).
-- Cache không leak: limit 256, sau 1000 unique strings thì size = 256.
-- Output identical với version không cache (regression test).
-
-**Verification**:
-- 1 unit test cache hit
-- 1 unit test eviction (insert 257 strings, kiểm size === 256)
-- Bench: `visibleWidth(longString) × 10000` → time giảm ≥ 5× (ms log).
-
-**Risk**: cache miss khi string concat/template (mỗi lần object identity khác). Nhận diện qua bench thực tế.
-
----
-
-## Tier 2 — Theme & style consistency
-
-Mục tiêu: 2 task, hot-reload + inverse fallback. Ước tính: 0.5 ngày.
-
-### Task #52 — Theme hot-reload subscription
-**Source**: `pi-mono/coding-agent/theme/theme.ts` `onThemeChange()` + `startThemeWatcher()`
-**Đích**: `pi-crew/src/ui/theme-adapter.ts`, `src/extension/register.ts`
-
-**Lý do**: pi-mono có cơ chế watch custom theme JSON, debounce 100ms reload, emit callback. pi-crew adapter chỉ snapshot theme 1 lần ở `ctx.ui.custom((tui, theme, ...) => Component)`. Khi user gõ `/theme dark` từ pi-coding-agent, các pi-crew widget hold theme cũ cho tới khi recreate component.
-
-**Approach**:
-1. Add `subscribeThemeChange(theme: unknown, callback: () => void): () => void` trong theme-adapter.ts. Internally:
-   - Test if `theme` object có `addEventListener?.("change", ...)` hoặc `onThemeChange?.(...)` API.
-   - Fallback: poll `theme.getColorMode?.()` + key signature mỗi 1s, callback nếu thay đổi.
-2. CrewWidgetComponent / LiveRunSidebar / RunDashboard / DurableTextViewer: gọi `subscribeThemeChange` trong constructor, store unsubscribe, gọi `this.invalidate()` khi callback fires.
-3. dispose: unsubscribe.
-
-**Acceptance**:
-- Mock theme với `onThemeChange` API → callback fires trong 200ms.
-- Mock theme polling → kiểm callback fires sau 1.1s khi sig thay đổi.
-- Dispose component → no further callback.
-
-**Verification**: 2 unit test mock theme objects. Manual test: chạy pi với `/theme light` rồi `/theme dark`, kiểm RunDashboard re-render.
-
-**Risk**: polling 1s × N components → overhead. Mitigate: shared global subscription, fan-out tới components qua singleton subscriber list. Implement singleton trong theme-adapter.
-
----
-
-### Task #53 — Theme adapter `inverse` ANSI fallback
-**Source**: `pi-mono` dùng `chalk.inverse(text)` = `\x1b[7m{text}\x1b[27m`
-**Đích**: `pi-crew/src/ui/theme-adapter.ts`
-
-**Lý do**: `asCrewTheme` hiện chỉ pass-through nếu source theme có `inverse`, fallback identity (return text nguyên). render-diff dùng `theme.inverse?.(value) ?? value` → khi theme nguồn không có inverse, intra-line diff highlight bị mất hoàn toàn. Bug visual subtle, không có test catch.
-
-**Logic chuẩn**:
-```ts
-function asInverse(value: unknown): (text: string) => string {
-  const fn = asUnaryFn(value);
-  if (fn) return fn;
-  return (text) => `\u001b[7m${text}\u001b[27m`;
-}
-```
-
-**Acceptance**:
-- `asCrewTheme(undefined).inverse?.("x")` → `"\u001b[7mx\u001b[27m"`.
-- `asCrewTheme(realTheme).inverse?.("x")` → output từ chalk (test bằng `includes("\u001b[7m")`).
-- renderDiff với theme tối giản vẫn highlight inverse lookup.
-
-**Verification**: cập nhật `loaders.test.ts`/thêm `theme-adapter.test.ts` 2 test (default fallback + provided theme passthrough).
-
-**Risk**: thấp — additive change.
-
----
-
-## Tier 3 — UX components (port pattern từ pi-mono)
-
-Mục tiêu: 3 task, footer + selectlist + dynamic border. Ước tính: 1 ngày.
-
-### Task #54 — `CrewFooter` component port
-**Source**: `pi-mono/coding-agent/components/footer.ts`
-**Đích**: `pi-crew/src/ui/crew-footer.ts` (mới), tích hợp vào `RunDashboard`.
-
-**Lý do**: pi-mono Footer là pattern multi-line trang trí (pwd+branch, tokens, context %, model). pi-crew RunDashboard có summary 1 line trộn rời rạc. Port để đồng bộ visual với coding-agent.
-
-**Layout (3 lines)**:
-```
-~/proj (main) • runId • running                                      (dim)
-↑in ↓out R cache W cache $cost • 45.3%/200k                          (dim, % colored)
-[badge1] [badge2] ...                                                 (extension statuses)
-```
-
-**API**:
-```ts
-export interface CrewFooterData {
-  pwd: string;
-  branch?: string;
-  runId?: string;
-  status?: RunStatus;
-  usage?: UsageState;
-  contextWindow?: number;
-  contextPercent?: number;
-  badges?: string[]; // raw text per extension status
-}
-
-export class CrewFooter {
-  constructor(private data: CrewFooterData, private theme: CrewTheme) {}
-  setData(data: CrewFooterData): void;
-  render(width: number): string[];
-  invalidate(): void;
-}
-```
-
-**Color logic**:
-- contextPercent > 90 → `theme.fg("error", ...)`
-- > 70 → `theme.fg("warning", ...)`
-- ≤ 70 → no color
-
-**Acceptance**:
-- Render cho run với usage tokens → output chứa `↑`, `↓`, `$cost`.
-- Truncate khi width nhỏ → ellipsis `...`.
-- contextPercent NaN/undefined → display `?/window`.
-
-**Verification**:
-- `test/unit/crew-footer.test.ts` 4 test (basic render, color thresholds, truncation, missing data).
-- Integrate vào `RunDashboard.renderFooter` (thay phần legacy footer).
-
-**Risk**: RunDashboard layout shift — kiểm snapshot lines count với existing tests.
-
----
-
-### Task #55 — `CrewSelectList` adapter
-**Source**: `@mariozechner/pi-tui` `SelectList` (peer dep) + pi-mono `extension-selector.ts`/`theme-selector.ts` patterns
-**Đích**: `pi-crew/src/ui/crew-select-list.ts`
-
-**Lý do**: RunDashboard handle keyboard navigation thủ công (j/k/enter), không có visual highlight selected, không support `onPreview`. pi-tui SelectList có sẵn nhưng pi-crew chưa wrap. Cần adapter để xài SelectList từ peer dep pi-tui (optional dep — kiểm `import { SelectList } from "@mariozechner/pi-tui"` available).
-
-**Approach**:
-1. Detect runtime: `try { require.resolve("@mariozechner/pi-tui"); }` → dùng pi-tui SelectList.
-2. Fallback: simple list component port từ extension-selector.ts (j/k/↑/↓/enter/esc handlers, highlight ` → ` cho selected).
-3. API:
-```ts
-export interface CrewSelectItem<T = string> {
-  value: T;
-  label: string;
-  description?: string;
-}
-
-export class CrewSelectList<T = string> {
-  constructor(
-    items: CrewSelectItem<T>[],
-    theme: CrewTheme,
-    options: {
-      onSelect: (item: CrewSelectItem<T>) => void;
-      onCancel: () => void;
-      onPreview?: (item: CrewSelectItem<T>) => void;
-      maxHeight?: number;
-    }
-  ) {}
-  render(width: number): string[];
-  handleInput(data: string): void;
-  invalidate(): void;
-  setSelectedIndex(i: number): void;
-  getSelected(): CrewSelectItem<T> | undefined;
-}
-```
-
-**Acceptance**:
-- Render với 5 items → 5 lines, selected có ` → `.
-- handleInput("j") → selected index +1, callback onPreview fired.
-- handleInput("\n") → callback onSelect with current item.
-- maxHeight=3 với 10 items → scroll, indicator `↑ N more`/`↓ N more`.
-
-**Verification**: `test/unit/crew-select-list.test.ts` 5 test.
-
-**Risk**: API mismatch nếu pi-tui SelectList API đổi version. Pin behavior qua adapter, fallback always available.
-
----
-
-### Task #56 — `DynamicCrewBorder` reusable + CountdownTimer 1s tick
-**Source**: `pi-mono/coding-agent/components/dynamic-border.ts` + `countdown-timer.ts`
-**Đích**: `pi-crew/src/ui/dynamic-border.ts` (mới), refactor `loaders.ts`
-
-**Lý do**:
-1. **DynamicBorder**: 10 LOC, render single line `─×width`. pi-crew có 3 nơi tự vẽ border:
-   - `loaders.ts CrewBorderedLoader`: `┌─┐│└─┘` static template
-   - `mascot.ts`: tự build `╭─╮│╰─╯`
-   - `run-dashboard.ts/transcript-viewer.ts`: tự pad border lines
-   → Refactor dùng chung `DynamicCrewBorder` cho horizontal lines, giữ corner chars riêng.
-2. **CountdownTimer 1s tick**: hiện tại tick 250ms (4×/s). pi-mono tick chính xác 1000ms + `tui.requestRender()`. 4× tick là wasteful, gây re-render trùng lặp.
-
-**API**:
-```ts
-// dynamic-border.ts
-export interface DynamicCrewBorderOptions {
-  color?: (s: string) => string;
-  char?: string; // default "─"
-}
-export class DynamicCrewBorder {
-  constructor(theme: CrewTheme, options?: DynamicCrewBorderOptions) {}
-  render(width: number): string[];
-  invalidate(): void;
-}
-```
-
-CountdownTimer change:
-```ts
-// trong loaders.ts CountdownTimer
-- this.timer = setInterval(() => { ... }, 250);
-+ this.timer = setInterval(() => {
-+   const seconds = this.secondsLeft();
-+   this.onTick(seconds);
-+   if (seconds <= 0) this.emitExpire();
-+ }, 1000);
-```
-
-**Acceptance**:
-- DynamicCrewBorder.render(20) → `["─".repeat(20)]` (with color).
-- DynamicCrewBorder dùng trong CrewBorderedLoader, mascot box, run-dashboard separators.
-- CountdownTimer onTick called ~3 lần trong 3.5s (giây 3, 2, 1, 0 không nhiều hơn).
-
-**Verification**:
-- 2 unit test cho DynamicCrewBorder (basic render, custom char).
-- Update `loaders.test.ts` CountdownTimer test: kiểm onTick count = ceil(timeoutMs/1000) + 1.
-
-**Risk**: mascot CountdownTimer (nếu có) cần điều chỉnh cùng. Visual flicker giảm bằng tick 1s thay 250ms.
-
----
-
-## Tier 4 — Power features
-
-Mục tiêu: 1 task, tool state styling. Ước tính: 0.25 ngày.
-
-### Task #57 — Tool state styling cho transcript-viewer
-**Source**: `pi-mono/coding-agent/components/tool-execution.ts` (toolPendingBg/toolSuccessBg/toolErrorBg state)
-**Đích**: `pi-crew/src/ui/transcript-viewer.ts`
-
-**Lý do**: transcript-viewer hiện render `[Tool: name] type` plain text. Không phân biệt:
-- partial vs final result
-- success vs error (`result.isError`)
-- queued vs running
-
-User scan transcript khó tìm ra error tool nhanh.
-
-**Logic update `formatTranscriptEvent`**:
-```ts
-const isError = obj.isError === true || asRecord(obj.result)?.isError === true;
-const isPartial = obj.isPartial === true;
-const status: RunStatus = isError ? "failed" : isPartial ? "running" : "completed";
-const icon = iconForStatus(status, { runningGlyph: "⋯" });
-const headerColor = colorForStatus(status);
-const header = theme.fg(headerColor, `${icon} [Tool${toolName ? `: ${toolName}` : ""}] ${type}`);
-```
-
-**Acceptance**:
-- Event với `isError: true` → header có icon `✗`, color `error`.
-- Event với `isPartial: true` → header có icon `⋯`/`▶`, color `accent`.
-- Event normal → icon `✓`, color `success`.
-- Existing tests `formatTranscriptText formats message and tool JSONL into conversation lines` vẫn pass.
-
-**Verification**: thêm 2 test cho transcript-viewer (error tool, partial tool).
-
-**Risk**: thấp — schema event đã có `isError`, chỉ unwrap đúng.
-
----
-
-## Thứ tự gợi ý thực hiện
-
-1. **Day 1 — Tier 1 (bug fix + perf)**: #50 → #51
-   - #50 fix bug subtle có thể impact nhiều screen.
-   - #51 cache độc lập, không phụ thuộc #50.
-
-2. **Day 1.5 — Tier 2 (theme)**: #52 → #53
-   - #53 nhanh (additive). #52 cần test với mock theme objects.
-
-3. **Day 2 — Tier 3 (UX)**: #54 → #55 → #56
-   - #54 footer độc lập, không break.
-   - #55 select-list pre-req cho future RunDashboard refactor.
-   - #56 dynamic-border refactor 3 file (loaders, mascot, dashboard).
-
-4. **Day 2 close — Tier 4 (#57)**: tool state styling, kết hợp với existing iconForStatus.
-
-Toàn bộ Phase 5 ước tính 1.5–2 ngày focus work, **0 dependency mới**.
-
----
-
-## Metrics mục tiêu (verification cuối Phase 5)
-
-- **truncateToVisualLines correctness**: 0 known bug. New tests catch slice-after-merge.
-- **visibleWidth perf**: cache hit rate ≥ 80% trong tick loop, regex calls giảm ≥ 5× theo bench.
-- **Theme reload latency**: < 200ms từ `onThemeChange` callback tới UI re-render.
-- **Footer info density**: RunDashboard footer 2-3 line giống pi-coding-agent.
-- **Border consistency**: 1 DynamicCrewBorder thay 3 self-rolled patterns.
-- **Test count**: 222 unit → ~234 unit (thêm ~12 test cho 8 task).
-- **Type safety**: 0 unsafe theme cast (giữ nguyên Phase 4).
-- **Deps mới**: 0.
-
----
-
-## Tracking template (per commit message)
-
-```
-Phase 5 task #<num>: <title>
-
-<body — what changed, why, refs to source pi-mono>
-
-Verification: tsc --noEmit OK; test:unit OK; test:integration <OK|N/A>
-
-Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
-```
+# Phase 5 Refactor Plan — Footer/Selectlist/Hot-reload từ pi-mono coding-agent
+
+> Xuất xứ: re-read `source/pi-mono/packages/coding-agent/src/modes/interactive/components/{footer,bordered-loader,dynamic-border,visual-truncate,diff,countdown-timer,extension-selector,theme-selector,custom-message,tool-execution,bash-execution}.ts` + `theme/theme.ts` (28/04/2026).
+> Mục tiêu: vá lỗi subtle còn lại từ Phase 4, hot-reload theme, port footer/select-list pattern, chuẩn hóa border + tool state styling.
+> Phase 4 đã hoàn tất, baseline: tsc 0 errors, 222 unit + 21 integration pass, commit `44fdd02`.
+
+## Quy ước chung
+- Không phá vỡ public API (slash commands, tool actions, config schema). Mọi thay đổi nội bộ.
+- Sau mỗi task: `npx tsc --noEmit` + `npm run test:unit` (+ `test:integration` nếu liên quan render/runtime).
+- Không thêm dependency runtime mới. Tất cả implement self-contained hoặc qua peer dep `@mariozechner/pi-tui` đã có.
+- Mỗi task = 1 commit độc lập có thể revert. Đặt tên test bám sát hành vi.
+- Ưu tiên backward compatibility: default behavior không đổi, opt-in qua config khi có hành vi mới.
+
+## Trạng thái cập nhật
+- [x] Task #50 — Fix `truncateToVisualLines` slice-after-merge bug
+- [x] Task #51 — Memoize `visibleWidth` LRU cache
+- [x] Task #52 — Theme hot-reload subscription
+- [x] Task #53 — Theme adapter `inverse` ANSI fallback
+- [x] Task #54 — `CrewFooter` component port
+- [x] Task #55 — `CrewSelectList` adapter
+- [x] Task #56 — `DynamicCrewBorder` reusable + CountdownTimer 1s tick
+- [x] Task #57 — Tool state styling cho transcript-viewer
+---
+
+## Tier 1 — Bug fixes & correctness (low risk, immediate value)
+
+Mục tiêu: 2 task, vá bug từ Phase 4 + tăng hiệu năng nhỏ. Ước tính: 0.5 ngày.
+
+### Task #50 — Fix `truncateToVisualLines` slice-after-merge bug
+**Source**: `pi-mono/coding-agent/components/visual-truncate.ts`
+**Đích**: `pi-crew/src/utils/visual.ts`
+
+**Lý do**: Phase 4 #47 implement `truncateToVisualLines` với logic:
+```ts
+const visualLines = text.split("\n").flatMap((line) =>
+  wrapHard(pad(line, ...).trimEnd(), effectiveWidth).slice(0, Math.max(1, maxVisualLines))
+);
+```
+Bug: `slice(0, maxVisualLines)` áp dụng **per source line** thay vì **toàn bộ visual lines sau merge**. Nếu 1 source line wrap thành N visual lines (N > maxVisualLines), kết quả lấy đầu line đó, không phải tail của toàn bộ output. Khi nhiều source line, tổng visual có thể vượt maxVisualLines.
+
+pi-mono dùng pattern đúng: render rồi `slice(-maxVisualLines)`.
+
+**Logic chuẩn**:
+```ts
+export function truncateToVisualLines(text, maxVisualLines, width, paddingX = 0) {
+  if (!text) return { visualLines: [], skippedCount: 0 };
+  const effectiveWidth = Math.max(1, width - paddingX * 2);
+  const allVisual = text.split("\n").flatMap((line) =>
+    wrapHard(pad(line, effectiveWidth).trimEnd(), effectiveWidth)
+  );
+  if (allVisual.length <= maxVisualLines) return { visualLines: allVisual, skippedCount: 0 };
+  return { visualLines: allVisual.slice(-maxVisualLines), skippedCount: allVisual.length - maxVisualLines };
+}
+```
+
+**Acceptance**:
+- 1 source line wrap thành 5 visual lines, maxVisualLines=2 → trả về 2 visual lines cuối + skippedCount=3
+- 3 source lines × 2 visual mỗi line = 6 visual, maxVisualLines=4 → trả về 4 cuối + skippedCount=2
+- empty input → `{ visualLines: [], skippedCount: 0 }` (đổi từ `[""]` về `[]` để khớp pi-mono)
+
+**Verification**: 2 unit test mới trong `test/unit/visual.test.ts`. Verify transcript-viewer integration vẫn pass test cũ.
+
+**Risk**: thay đổi semantic empty input — kiểm tra all callers (transcript-viewer, run-dashboard) handle `[]` thay vì `[""]`.
+
+---
+
+### Task #51 — Memoize `visibleWidth` qua LRU cache
+**Source**: pattern caching từ pi-tui `utils.ts`
+**Đích**: `pi-crew/src/utils/visual.ts`
+
+**Lý do**: `visibleWidth(value)` được gọi trong:
+- `pad`, `truncateToWidth`, `wrapHard` (mỗi character iter)
+- `crew-widget.ts colorWidgetLine` (mỗi line, mỗi tick 250ms)
+- `RunDashboard.render` (5-10 lần per render)
+- Total ước tính: 50+ calls/render × 4 render/sec = 200+ regex ops/sec.
+
+Cache key = string identity, value = width. Reset khi cache > 256 entries (FIFO eviction).
+
+**API**:
+```ts
+const widthCache = new Map<string, number>();
+const CACHE_LIMIT = 256;
+
+export function visibleWidth(value: string): number {
+  const cached = widthCache.get(value);
+  if (cached !== undefined) return cached;
+  let length = 0;
+  for (const char of value.replace(ANSI_PATTERN, "")) {
+    if (char !== "\n") length += 1;
+  }
+  if (widthCache.size >= CACHE_LIMIT) {
+    const firstKey = widthCache.keys().next().value;
+    if (firstKey !== undefined) widthCache.delete(firstKey);
+  }
+  widthCache.set(value, length);
+  return length;
+}
+```
+
+**Acceptance**:
+- `visibleWidth("foo")` gọi 1000 lần → chỉ tính 1 lần (kiểm qua spy với regex.exec count nếu có Diff bench).
+- Cache không leak: limit 256, sau 1000 unique strings thì size = 256.
+- Output identical với version không cache (regression test).
+
+**Verification**:
+- 1 unit test cache hit
+- 1 unit test eviction (insert 257 strings, kiểm size === 256)
+- Bench: `visibleWidth(longString) × 10000` → time giảm ≥ 5× (ms log).
+
+**Risk**: cache miss khi string concat/template (mỗi lần object identity khác). Nhận diện qua bench thực tế.
+
+---
+
+## Tier 2 — Theme & style consistency
+
+Mục tiêu: 2 task, hot-reload + inverse fallback. Ước tính: 0.5 ngày.
+
+### Task #52 — Theme hot-reload subscription
+**Source**: `pi-mono/coding-agent/theme/theme.ts` `onThemeChange()` + `startThemeWatcher()`
+**Đích**: `pi-crew/src/ui/theme-adapter.ts`, `src/extension/register.ts`
+
+**Lý do**: pi-mono có cơ chế watch custom theme JSON, debounce 100ms reload, emit callback. pi-crew adapter chỉ snapshot theme 1 lần ở `ctx.ui.custom((tui, theme, ...) => Component)`. Khi user gõ `/theme dark` từ pi-coding-agent, các pi-crew widget hold theme cũ cho tới khi recreate component.
+
+**Approach**:
+1. Add `subscribeThemeChange(theme: unknown, callback: () => void): () => void` trong theme-adapter.ts. Internally:
+   - Test if `theme` object có `addEventListener?.("change", ...)` hoặc `onThemeChange?.(...)` API.
+   - Fallback: poll `theme.getColorMode?.()` + key signature mỗi 1s, callback nếu thay đổi.
+2. CrewWidgetComponent / LiveRunSidebar / RunDashboard / DurableTextViewer: gọi `subscribeThemeChange` trong constructor, store unsubscribe, gọi `this.invalidate()` khi callback fires.
+3. dispose: unsubscribe.
+
+**Acceptance**:
+- Mock theme với `onThemeChange` API → callback fires trong 200ms.
+- Mock theme polling → kiểm callback fires sau 1.1s khi sig thay đổi.
+- Dispose component → no further callback.
+
+**Verification**: 2 unit test mock theme objects. Manual test: chạy pi với `/theme light` rồi `/theme dark`, kiểm RunDashboard re-render.
+
+**Risk**: polling 1s × N components → overhead. Mitigate: shared global subscription, fan-out tới components qua singleton subscriber list. Implement singleton trong theme-adapter.
+
+---
+
+### Task #53 — Theme adapter `inverse` ANSI fallback
+**Source**: `pi-mono` dùng `chalk.inverse(text)` = `\x1b[7m{text}\x1b[27m`
+**Đích**: `pi-crew/src/ui/theme-adapter.ts`
+
+**Lý do**: `asCrewTheme` hiện chỉ pass-through nếu source theme có `inverse`, fallback identity (return text nguyên). render-diff dùng `theme.inverse?.(value) ?? value` → khi theme nguồn không có inverse, intra-line diff highlight bị mất hoàn toàn. Bug visual subtle, không có test catch.
+
+**Logic chuẩn**:
+```ts
+function asInverse(value: unknown): (text: string) => string {
+  const fn = asUnaryFn(value);
+  if (fn) return fn;
+  return (text) => `\u001b[7m${text}\u001b[27m`;
+}
+```
+
+**Acceptance**:
+- `asCrewTheme(undefined).inverse?.("x")` → `"\u001b[7mx\u001b[27m"`.
+- `asCrewTheme(realTheme).inverse?.("x")` → output từ chalk (test bằng `includes("\u001b[7m")`).
+- renderDiff với theme tối giản vẫn highlight inverse lookup.
+
+**Verification**: cập nhật `loaders.test.ts`/thêm `theme-adapter.test.ts` 2 test (default fallback + provided theme passthrough).
+
+**Risk**: thấp — additive change.
+
+---
+
+## Tier 3 — UX components (port pattern từ pi-mono)
+
+Mục tiêu: 3 task, footer + selectlist + dynamic border. Ước tính: 1 ngày.
+
+### Task #54 — `CrewFooter` component port
+**Source**: `pi-mono/coding-agent/components/footer.ts`
+**Đích**: `pi-crew/src/ui/crew-footer.ts` (mới), tích hợp vào `RunDashboard`.
+
+**Lý do**: pi-mono Footer là pattern multi-line trang trí (pwd+branch, tokens, context %, model). pi-crew RunDashboard có summary 1 line trộn rời rạc. Port để đồng bộ visual với coding-agent.
+
+**Layout (3 lines)**:
+```
+~/proj (main) • runId • running                                      (dim)
+↑in ↓out R cache W cache $cost • 45.3%/200k                          (dim, % colored)
+[badge1] [badge2] ...                                                 (extension statuses)
+```
+
+**API**:
+```ts
+export interface CrewFooterData {
+  pwd: string;
+  branch?: string;
+  runId?: string;
+  status?: RunStatus;
+  usage?: UsageState;
+  contextWindow?: number;
+  contextPercent?: number;
+  badges?: string[]; // raw text per extension status
+}
+
+export class CrewFooter {
+  constructor(private data: CrewFooterData, private theme: CrewTheme) {}
+  setData(data: CrewFooterData): void;
+  render(width: number): string[];
+  invalidate(): void;
+}
+```
+
+**Color logic**:
+- contextPercent > 90 → `theme.fg("error", ...)`
+- > 70 → `theme.fg("warning", ...)`
+- ≤ 70 → no color
+
+**Acceptance**:
+- Render cho run với usage tokens → output chứa `↑`, `↓`, `$cost`.
+- Truncate khi width nhỏ → ellipsis `...`.
+- contextPercent NaN/undefined → display `?/window`.
+
+**Verification**:
+- `test/unit/crew-footer.test.ts` 4 test (basic render, color thresholds, truncation, missing data).
+- Integrate vào `RunDashboard.renderFooter` (thay phần legacy footer).
+
+**Risk**: RunDashboard layout shift — kiểm snapshot lines count với existing tests.
+
+---
+
+### Task #55 — `CrewSelectList` adapter
+**Source**: `@mariozechner/pi-tui` `SelectList` (peer dep) + pi-mono `extension-selector.ts`/`theme-selector.ts` patterns
+**Đích**: `pi-crew/src/ui/crew-select-list.ts`
+
+**Lý do**: RunDashboard handle keyboard navigation thủ công (j/k/enter), không có visual highlight selected, không support `onPreview`. pi-tui SelectList có sẵn nhưng pi-crew chưa wrap. Cần adapter để xài SelectList từ peer dep pi-tui (optional dep — kiểm `import { SelectList } from "@mariozechner/pi-tui"` available).
+
+**Approach**:
+1. Detect runtime: `try { require.resolve("@mariozechner/pi-tui"); }` → dùng pi-tui SelectList.
+2. Fallback: simple list component port từ extension-selector.ts (j/k/↑/↓/enter/esc handlers, highlight ` → ` cho selected).
+3. API:
+```ts
+export interface CrewSelectItem<T = string> {
+  value: T;
+  label: string;
+  description?: string;
+}
+
+export class CrewSelectList<T = string> {
+  constructor(
+    items: CrewSelectItem<T>[],
+    theme: CrewTheme,
+    options: {
+      onSelect: (item: CrewSelectItem<T>) => void;
+      onCancel: () => void;
+      onPreview?: (item: CrewSelectItem<T>) => void;
+      maxHeight?: number;
+    }
+  ) {}
+  render(width: number): string[];
+  handleInput(data: string): void;
+  invalidate(): void;
+  setSelectedIndex(i: number): void;
+  getSelected(): CrewSelectItem<T> | undefined;
+}
+```
+
+**Acceptance**:
+- Render với 5 items → 5 lines, selected có ` → `.
+- handleInput("j") → selected index +1, callback onPreview fired.
+- handleInput("\n") → callback onSelect with current item.
+- maxHeight=3 với 10 items → scroll, indicator `↑ N more`/`↓ N more`.
+
+**Verification**: `test/unit/crew-select-list.test.ts` 5 test.
+
+**Risk**: API mismatch nếu pi-tui SelectList API đổi version. Pin behavior qua adapter, fallback always available.
+
+---
+
+### Task #56 — `DynamicCrewBorder` reusable + CountdownTimer 1s tick
+**Source**: `pi-mono/coding-agent/components/dynamic-border.ts` + `countdown-timer.ts`
+**Đích**: `pi-crew/src/ui/dynamic-border.ts` (mới), refactor `loaders.ts`
+
+**Lý do**:
+1. **DynamicBorder**: 10 LOC, render single line `─×width`. pi-crew có 3 nơi tự vẽ border:
+   - `loaders.ts CrewBorderedLoader`: `┌─┐│└─┘` static template
+   - `mascot.ts`: tự build `╭─╮│╰─╯`
+   - `run-dashboard.ts/transcript-viewer.ts`: tự pad border lines
+   → Refactor dùng chung `DynamicCrewBorder` cho horizontal lines, giữ corner chars riêng.
+2. **CountdownTimer 1s tick**: hiện tại tick 250ms (4×/s). pi-mono tick chính xác 1000ms + `tui.requestRender()`. 4× tick là wasteful, gây re-render trùng lặp.
+
+**API**:
+```ts
+// dynamic-border.ts
+export interface DynamicCrewBorderOptions {
+  color?: (s: string) => string;
+  char?: string; // default "─"
+}
+export class DynamicCrewBorder {
+  constructor(theme: CrewTheme, options?: DynamicCrewBorderOptions) {}
+  render(width: number): string[];
+  invalidate(): void;
+}
+```
+
+CountdownTimer change:
+```ts
+// trong loaders.ts CountdownTimer
+- this.timer = setInterval(() => { ... }, 250);
++ this.timer = setInterval(() => {
++   const seconds = this.secondsLeft();
++   this.onTick(seconds);
++   if (seconds <= 0) this.emitExpire();
++ }, 1000);
+```
+
+**Acceptance**:
+- DynamicCrewBorder.render(20) → `["─".repeat(20)]` (with color).
+- DynamicCrewBorder dùng trong CrewBorderedLoader, mascot box, run-dashboard separators.
+- CountdownTimer onTick called ~3 lần trong 3.5s (giây 3, 2, 1, 0 không nhiều hơn).
+
+**Verification**:
+- 2 unit test cho DynamicCrewBorder (basic render, custom char).
+- Update `loaders.test.ts` CountdownTimer test: kiểm onTick count = ceil(timeoutMs/1000) + 1.
+
+**Risk**: mascot CountdownTimer (nếu có) cần điều chỉnh cùng. Visual flicker giảm bằng tick 1s thay 250ms.
+
+---
+
+## Tier 4 — Power features
+
+Mục tiêu: 1 task, tool state styling. Ước tính: 0.25 ngày.
+
+### Task #57 — Tool state styling cho transcript-viewer
+**Source**: `pi-mono/coding-agent/components/tool-execution.ts` (toolPendingBg/toolSuccessBg/toolErrorBg state)
+**Đích**: `pi-crew/src/ui/transcript-viewer.ts`
+
+**Lý do**: transcript-viewer hiện render `[Tool: name] type` plain text. Không phân biệt:
+- partial vs final result
+- success vs error (`result.isError`)
+- queued vs running
+
+User scan transcript khó tìm ra error tool nhanh.
+
+**Logic update `formatTranscriptEvent`**:
+```ts
+const isError = obj.isError === true || asRecord(obj.result)?.isError === true;
+const isPartial = obj.isPartial === true;
+const status: RunStatus = isError ? "failed" : isPartial ? "running" : "completed";
+const icon = iconForStatus(status, { runningGlyph: "⋯" });
+const headerColor = colorForStatus(status);
+const header = theme.fg(headerColor, `${icon} [Tool${toolName ? `: ${toolName}` : ""}] ${type}`);
+```
+
+**Acceptance**:
+- Event với `isError: true` → header có icon `✗`, color `error`.
+- Event với `isPartial: true` → header có icon `⋯`/`▶`, color `accent`.
+- Event normal → icon `✓`, color `success`.
+- Existing tests `formatTranscriptText formats message and tool JSONL into conversation lines` vẫn pass.
+
+**Verification**: thêm 2 test cho transcript-viewer (error tool, partial tool).
+
+**Risk**: thấp — schema event đã có `isError`, chỉ unwrap đúng.
+
+---
+
+## Thứ tự gợi ý thực hiện
+
+1. **Day 1 — Tier 1 (bug fix + perf)**: #50 → #51
+   - #50 fix bug subtle có thể impact nhiều screen.
+   - #51 cache độc lập, không phụ thuộc #50.
+
+2. **Day 1.5 — Tier 2 (theme)**: #52 → #53
+   - #53 nhanh (additive). #52 cần test với mock theme objects.
+
+3. **Day 2 — Tier 3 (UX)**: #54 → #55 → #56
+   - #54 footer độc lập, không break.
+   - #55 select-list pre-req cho future RunDashboard refactor.
+   - #56 dynamic-border refactor 3 file (loaders, mascot, dashboard).
+
+4. **Day 2 close — Tier 4 (#57)**: tool state styling, kết hợp với existing iconForStatus.
+
+Toàn bộ Phase 5 ước tính 1.5–2 ngày focus work, **0 dependency mới**.
+
+---
+
+## Metrics mục tiêu (verification cuối Phase 5)
+
+- **truncateToVisualLines correctness**: 0 known bug. New tests catch slice-after-merge.
+- **visibleWidth perf**: cache hit rate ≥ 80% trong tick loop, regex calls giảm ≥ 5× theo bench.
+- **Theme reload latency**: < 200ms từ `onThemeChange` callback tới UI re-render.
+- **Footer info density**: RunDashboard footer 2-3 line giống pi-coding-agent.
+- **Border consistency**: 1 DynamicCrewBorder thay 3 self-rolled patterns.
+- **Test count**: 222 unit → ~234 unit (thêm ~12 test cho 8 task).
+- **Type safety**: 0 unsafe theme cast (giữ nguyên Phase 4).
+- **Deps mới**: 0.
+
+---
+
+## Tracking template (per commit message)
+
+```
+Phase 5 task #<num>: <title>
+
+<body — what changed, why, refs to source pi-mono>
+
+Verification: tsc --noEmit OK; test:unit OK; test:integration <OK|N/A>
+
+Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
+```