pi-crew 0.11.8 → 0.11.9

package/docs/usage.md

@@ -45,7 +45,7 @@ Supported fields:
     "widgetPlacement": "aboveEditor",
     "widgetMaxLines": 8,
     "powerbar": true,
-    "dashboardPlacement": "center",
+    "dashboardPlacement": "right",
     "dashboardWidth": 72,
     "dashboardLiveRefreshMs": 1000,
     "autoOpenDashboard": false,

package/install.mjs

@@ -54,7 +54,10 @@ export const defaultConfig = {
     widgetPlacement: "bottom",
     widgetMaxLines: 8,
     powerbar: true,
-    dashboardPlacement: "center",
+    // L3 (2026-10-07 real-test review): tracks DEFAULT_UI.dashboardPlacement —
+    // enforced by test/unit/install-defaults-sync.test.ts (mutation: edit
+    // DEFAULT_UI without this file and that test goes red).
+    dashboardPlacement: "right",
     dashboardWidth: 72,
     dashboardLiveRefreshMs: 1000,
     autoOpenDashboard: false,

package/package.json

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

package/skills/real-test-pi-crew/SKILL.md

@@ -8,6 +8,10 @@ description: >
 
 origin: pi-crew
 triggers:
+  - "pi crashed"
+  - "tmux server died"
+  - "crashes.json"
+  - "completion popup"
   - "test the change"
   - "verify it works"
   - "is it really working"
@@ -105,6 +109,7 @@ End-to-end verification discipline for pi-crew changes. Distilled from the broke
 | Đổi… | Tier bắt buộc (thứ tự) |
 |---|---|
 | `src/runtime/broker/` | T1 → T7 → T9b-W |
+| `src/extension/command-completions.ts` / `src/extension/registration/commands/*.ts` (autocomplete providers + slash-command handlers) | T1 + pinned `test/unit/extension/core/command-completions*.test.ts` → **T5 completion-popup probe**: trong tmux session thật, gõ `/team-transcript <runId> ` + 1 ký tự nữa cho popup fire — assert (a) pi CÒN SỐNG, (b) gợi ý task id hiện với runId hợp lệ, (c) KHÔNG crash entry mới trong `~/.pi/agent/crashes.json`. Completion callbacks chạy trong `CombinedAutocompleteProvider.getSuggestions` của pi core — nơi KHÔNG catch lỗi extension: một throw = chết cả pi process (P0 live-caught 2026-10-08: `Invalid runId: team_x/team-transcript`, crashes.json có full stack) | 
 | `src/ui/` | T1 → (T5|T6) → T13 |
 | `src/config/` (kể cả migration-validator) | T1 → T11c |
 | `src/runtime/child-pi/` (spawn/kill/steer) | T7 → T9g |
@@ -146,6 +151,7 @@ End-to-end verification discipline for pi-crew changes. Distilled from the broke
 
 > **2026-10-01 update (SDD-2 W-B — G2 MCP role-gate + G3 spill-always + Phase D bump 0.99.1, commits `66f37875`→`f0b343ed`, execution record §13 `pi-crew-sdd-2026-09-30-buoi1.md`)**: (1) **G2 flips full-loadout sanity semantics** — MCP presence in workers is now ROLE- and PATH-dependent: the live-session SDK path strips MCP (`DefaultResourceLoader({ extensionsOverride: stripMcpExtensions })`) cho read-only roles (`mcpPermittedForRole` — explorer/reviewer/security-reviewer/analyst/critic/planner + unknown default-deny); a read-only worker WITHOUT MCP is CORRECT, a write-role worker without MCP is a regression; nếu strip không arm được (SDK hết export `DefaultResourceLoader`…) → fail-open + warning event `task.mcp_enforcement_degraded` (registry 168 → 169, `check:event-types --enforce` clean). CLI child-process path CHƯA cover (WI-4 defer: `~/.pi/agent/mcp.json` trống + `-ne` giết provider `oc-go` — read-only roles vẫn discover adapter MCP trên đường đó). (2) **G3 spill-always**: MỌI task text qua `task.md` 0600 — argv worker KHÔNG bao giờ chứa task text; probe đọc argv phải expect `@<temp>/task.md`, task ngắn mất prefix `Task: `; `TASK_ARG_LIMIT` đã xóa. (3) Phase D bump `@earendil-works/*` → 0.99.x: SDK bỏ option `enableMCP`, tool seam cần `ExtensionToolContext` (export mới `src/extension/pi-api.ts`). Decision table thêm row `mcp-proxy.ts`/`model/pi-args.ts`; D5 loadout line refs dời `:283-330` → `:280-336`.
 > **2026-10-07 update (0.11.6 → 0.11.7/0.11.8-pre stack, GH#61/#62 + pi 1.0.4 adoption + RPC hardening, HEAD `11e717f5`)**: (1) **GH#61 (0.11.6)** — directory `pi.extensions` entries được normalize sang entry-file identity (`resolveExtensionDirEntry`): child worker không còn double-load directory extension (`Tool "…" conflicts … exit 1` — CHANGELOG 0.11.6 block, `CHANGELOG.md:207`). (2) **pi 1.0.4 adoption** — devDeps `@earendil-works/*` ^1.0.4 (`package.json:153-156`; peerDeps `:136-139` giữ `*`), host pi 1.0.4. (3) **U2-lite MCP parity cut** — parity spawns fold `mcp__*` vào disallow list trên MỌI host (`pi-args.ts:414`) + `--no-mcp` khi host ≥ `PI_NO_MCP_FLOOR="1.0.4"` (`pi-version.ts:76`, gate `pi-args.ts:430`); hermetic spawns MCP-clean qua `--no-extensions` — probe loadout: worker KHÔNG thấy `mcp__*` là ĐÚNG trên cả parity lẫn hermetic path (verdict `docs/reviews/pi-1.0.4-upgrade-notes-2026-10-06.md`). (4) **RPC transport wired (W7)** — `PI_CREW_WORKER_TRANSPORT=rpc` chọn RPC transport tại run-worker seam (`runWorker`, `src/runtime/run-worker.ts:138`; env names `src/runtime/rpc/rpc-worker.ts:43-49`), precedence **env > `runtime.workerTransport` config > stdio**, invalid → stdio (`config-schema.ts:157`); probe recipe = T7 smoke với `PI_CREW_WORKER_TRANSPORT=rpc`; DR1/DR5 exit-race hardening + `PI_CREW_RPC_TURN_TIMEOUT_MS` (default 600_000; dialog policy `PI_CREW_RPC_DIALOG_ANSWER` default `cancel`) — suite `run-worker-rpc-seam.test.ts` (8) có 3 scenario MỚI: DR1 exit-race `:223`, DR5 started-then-fail KHÔNG fallback `:266`, DR1 turn-timeout `:298` (+ truth table `:328`); pin kèm `test/unit/runtime/rpc/rpc-worker.test.ts` (10). RPC vẫn EXPERIMENTAL — fail trước agent output → stdio fallback (structured warn). (5) **Classifier seam DORMANT (P2-1)** — default OFF (`config-schema.ts:95`; `resolveClassifierEnabled`: env `PI_CREW_CLASSIFIER_ENABLED` > config > FALSE, `classifier-service.ts:158`); battery KHÔNG dính trừ khi set `PI_CREW_CLASSIFIER_ENABLED=1` (+ `PI_CREW_CLASSIFIER_MODEL`, default `opencode/jev-1.13-free`) — unit-only (`classifier-service.test.ts` 14 + `child-executor-retry-triage.test.ts` 6), KHÔNG live tier. (6) **Pre-push hook (D3)** — `.githooks/pre-push` qua `git config core.hooksPath .githooks` (wired `package.json` `prepare` → `scripts/install-hooks.mjs`): MỌI push chạy `check:conflict-markers` + typecheck; push `refs/heads/main` TỰ chạy FULL `test:unit` (~13-14 phút) rồi mới in `[pre-push] gates green.`; bypass `git push --no-verify` CHỈ khẩn cấp (CI vẫn gate main). (7) **GH#62 foreground completion** (`62c9ed0d`→`51adb1e1`→`3ed0067e`→`c956b2d4`→`af462d7b`) — foreground-run completion path sống sót qua spread-copy contexts; suite `test/unit/extension/registration/foreground-run-completion.test.ts` (4 tests). (8) **hermeticWorkers DEFAULT ON** (`config-schema.ts:89`; env `PI_CREW_HERMETIC_WORKERS`; `resolveHermeticWorkers` `pi-args.ts:149` — `explicit ?? true`). (9) **U9 version-floor wiring** — suites `test/unit/runtime/child-pi/pi-version.test.ts` (11) + `test/unit/runtime/model/pi-args-version-floor.test.ts` (7) + `test/unit/runtime/child-pi/pi-version-floor-wiring.test.ts` (2). (10) **RT-11 lesson (`48cc088d`)** — static spawn-site scan (`child-pi-spawn-registration.test.ts:33`) đếm CẢ prose trong comment (`spawn (`); khi dash vì comment → **reword comment, KHÔNG relax test**. Suite anchors @ 2026-10-07: unit **8711 tests / 8707 pass / 1 flaky-under-load / 3 skipped** (968 files, ~13 min; flaky = `team-tool-resume-liveness` F1 liveness race — 6/6 pass isolated ×3, KHÔNG phải regression), integration **139 / 135 pass / 4 skipped** (exit 0 — CHỈ khi scrub ĐỦ `PI_CREW_*`/`PI_TEAMS_*`, xem Failure-symptoms row MAX_DEPTH), `test:critical` **120** (~19-20s), bundle **1620.1 KB** (1,658,985 B) md5 `20544cf9ea436c69b0b434462def91b9` (`--committed-hash` OK), event registry **176 registered / 141 emitted** (`check:event-types --enforce` clean), devDeps `@earendil-works/*` ^1.0.4 / host pi **1.0.4**.
+> **2026-10-08 update (L-wave UI instability review + L10 plan flicker + P0 completion crash, commits `28e0d58d`+`c068fc4a`+`c89c759a`, report `docs/real-test/reports/real-test-2026-10-07-ui-instability-review.md` + fix-wave addenda)**: (1) **P0 — completion throw giết cả pi**: `/team-transcript` popup race làm input dính `/<cmd>` suffix vào runId token → `assertSafePathId` throw bên trong `CombinedAutocompleteProvider.getSuggestions` (pi core KHÔNG catch lỗi extension) → uncaught_exception chết cả process. Fix: MỌI completion provider (`suggestTaskIds`, `suggestRunIds`…) try/catch → null; pin test + mutation. **Evidence source mới: `~/.pi/agent/crashes.json`** — khi pi/tmux chết bất ngờ giữa probe, đọc file này TRƯỚC khi đoán (có kind/message/stack qua dist). Decision table có row mới cho command-completions. (2) **L10 — plan card flicker**: tasks variant không được paint spinner động (comment thiết kế của chính nó); signature phải strip `:spin=`. Dock giữ đúng MỘT dòng spinner (chủ ý). (3) **Probe-hygiene lessons** (đều tốn điều tra giả session này): tmux `new-session -t <sess>` tạo GROUPED session (cùng process — vô dụng cho bystander probe; phải `new-session -d -s <tên> "cd … && exec pi"`); `pkill -f <pattern>` từ bash của assistant TỰ MATCH command line của chính nó (chuỗi literal nằm trong args/heredoc — bracket-trick không đủ; kill bằng PID hoặc tên script riêng); so sánh frame theo row-index bị transcript-scroll làm nhiễu — so BLOCK theo marker `┏ NAME ▸`…`┗`, và dock có HAI dạng render (`┏ CREW ▸` mở rộng / `┃ CREW ▸` thu gọn — marker phải match cả hai, từng gây báo động giả "dock biến mất"); dispatch sync run khi có run khác đang chạy → assistant có thể join/wait run cũ thay vì tạo run mới (luôn verify runId mới trong `.crew/state/runs/` trước khi probe). (4) **Load-flake rule**: `test:critical` đỏ 1 suite lạ + treo isolation dưới load 82+ (build song song của user) = starvation, KHÔNG phải regression — check `uptime` TRƯỚC, re-run khi máy êm (session này: symlink-steering treo dưới load 82, 120/120 xanh khi load 0.8). Suite anchors @ 2026-10-08: `test:critical` **120**, bundle **1622.6 KB** md5 `4f76457497bd20779e298cee4d8d982e`.
 > **2026-09-21 update (F-L2 — steer boot-window loss, found by the live feature battery)**: a steer written to `<artifactsRoot>/steering/<taskId>.jsonl` while the worker extension is still LOADING was silently lost forever — `registerPiTeamsPromptRuntime` starts the file poll at load time, pi's loader gates action methods until bind (`sendMessage: notInitialized` THROWS), and the old poll advanced `lastOffset` to `stat.size` BEFORE the line loop while its per-line catch swallowed the throw as "malformed line" (run `team_20260921035840`, root-caused by watcher-driven bisection probes R7-R9: +0.65s post-boot = lost, +2.5s+ = delivered). Fix (`src/prompt/prompt-runtime.ts`): walk the buffer by byte offset, advance only past terminal verdicts (delivered/non-steer/rejected/malformed), rewind to the failing line on a DELIVERY failure, `createSeenSteerIdSet.unmark()` releases the dedup id so the retry is not skipped. Regression suite `test/unit/prompt/prompt-runtime-steer-boot-window.test.ts` (4 tests) — mutation-checked both layers (offset-revert → 4 fail; unmark-removal → exactly the id-bearing test fails). Note: `dist/index.mjs` is UNCHANGED by this fix — child workers load prompt-runtime from the SOURCE path (`pi-args.ts PROMPT_RUNTIME_EXTENSION_PATH`), so the fix is live without a bundle bump.
 >
 > **F-L2 live re-verification (post-restart, 2026-09-21 afternoon)** — two independent proofs: (a) **lab**: pre-write the steer, then `PI_CREW_STEERING_FILE=<file> pi --extension <repo>/src/prompt/prompt-runtime.ts -p '<long task>'` — stderr shows `[pi-crew:prompt-runtime.steer-delivery-failed] Extension runtime not initialized…` ×2 (pre-bind ticks now LOGGED instead of swallowed) then the post-bind tick delivers and the model complies; (b) **real team run**: watcher writes at **+0.51s** after the steering dir appears (the previously-lost window) → worker session log gains the `custom_message` and the probe token lands in `results/<taskId>.txt`. Suite anchors @ 2026-09-21 (post-fix): unit **8006 tests / 8003 pass / 0 fail / 3 skipped** (875 files; 1088s under load), integration **134 / 130 pass / 4 skipped**, `test:critical` **116**, bundle **3360.1 KB** md5 `2f45df91ed0580ee5bb5b9b57a8a8c3f` (UNCHANGED — see the source-path note above).
@@ -408,6 +414,20 @@ tmux capture-pane -t pi -p > /tmp/screen-after-up.txt
 | App-cursor-mode | `\x1bOA` | `\x1bOB` | vim, less, full-screen apps |
 | Kitty protocol | `\x1b[1;2A` (Shift+Up) etc. | — | modern terminals (kitty, foot, ghostty) |
 
+**Completion-popup probe (P0 2026-10-08 — dùng khi đụng `command-completions.ts` / slash-command handlers)**: completion callbacks chạy trong `CombinedAutocompleteProvider.getSuggestions` của pi core — nơi KHÔNG catch lỗi extension, một throw = chết cả pi process. Probe:
+
+```bash
+# (a) input từng gây crash: runId token dính suffix "/<cmd>" + trailing space cho popup fire
+tmux -S /tmp/sock send-keys -t pi '/team-transcript team_20261008_xxx/team-transcript '
+sleep 2.5; tmux -S /tmp/sock ls >/dev/null && echo ALIVE   # phải sống
+# crashes.json phải KHÔNG có entry mới (đọc ~/.pi/agent/crashes.json, lọc timestamp > thời điểm probe)
+# (b) flow hợp lệ: runId thật + space + 1 ký tự → popup gợi ý task id
+tmux -S /tmp/sock send-keys -t pi C-c
+tmux -S /tmp/sock send-keys -t pi '/team-transcript <runId-thật> '
+sleep 2; tmux -S /tmp/sock send-keys -t pi '0'; sleep 2
+tmux -S /tmp/sock capture-pane -t pi -p | grep -aE '0[123]_' | head -3  # kỳ vọng 01_explore/02_execute…
+```
+
 **References**:
 
 | What | Where |
@@ -1144,6 +1164,12 @@ When a tier fails, the recovery is usually quick. Match the symptom to the cause
 
 | Symptom | Likely cause | Recovery |
 |---|---|---|
+| Pi process / tmux server chết bất ngờ giữa probe (capture-pane báo "no server running") | **Extension giết pi bằng uncaught exception** — pi core không catch lỗi extension trong autocomplete provider / async callback. P0 2026-10-08: `Invalid runId: team_x/team-transcript` từ `assertSafePathId` qua `suggestTaskIds` | Đọc `~/.pi/agent/crashes.json` TRƯỚC khi đoán gì khác — có `kind`/`message`/`stack` (symbol qua `dist/index.mjs` → map lại src). Session mới mở cũng hiện banner "pi crashed on …" kèm message. Fix pattern: callback phải try/catch → degrade, KHÔNG bao giờ throw ra ngoài |
+| `test:critical` đỏ đúng 1 suite lạ (broker/steering) + treo cả khi chạy isolated, trong khi xanh hoàn toàn vài giờ trước | **Starvation dưới load cao** (build song song, load 80+): broker handshake/timeout-based tests chết đói CPU, KHÔNG phải regression từ thay đổi UI — session 2026-10-08 đỏ symlink-steering dưới load 82, 120/120 xanh lại khi load 0.8 | `uptime` + `ps -eo pcpu --sort=-pcpu | head` TRƯỚC; đợi/re-run khi máy êm; chỉ chẩn đoán regression khi đỏ lại trên máy sạch |
+| Probe session thứ 2 (bystander) hiển thị y hệt session 1, keystroke session này ảnh hưởng session kia | `tmux new-session -t <sess>` tạo **GROUPED session** — cùng window/cùng process, không phải pi riêng | Bystander phải STANDALONE: `tmux -S <sock> new-session -d -x 150 -y 50 -s by "cd <cwd> && exec pi 2>&1"` (KHÔNG dùng `-t`); verify bằng 2 PID pi riêng trong `ps` |
+| Bash của assistant tự chết exit 143 ngay sau lệnh `pkill -f <pattern>` | **pkill tự match**: command line của chính bash chứa chuỗi pattern (trong heredoc/args) — bracket-trick `pat[.]tern` KHÔNG đủ khi chuỗi literal nằm trong tham số | Đặt tên script capture riêng (capV7.sh…), kill bằng `pkill -f loopV7` với tên KHÔNG xuất hiện trong lệnh hiện tại, hoặc kill theo PID ghi sẵn |
+| So sánh frame theo row-index cho hàng trăm "diff" giả (mọi row "đổi" liên tục) | **Transcript scroll**: output worker/stream làm mọi dòng dịch chuyển row — so row-index đếm toàn bộ là đổi | So BLOCK theo marker biên: `┏ PLAN`…`┗`, `┏ DASHBOARD`…, và LƯU Ý dock có 2 dạng: mở rộng `┏ CREW ▸` (có progress bar) / thu gọn `┃ CREW ▸` (1 dòng) — match cả hai, từng gây báo động giả "dock biến mất" |
+| Dispatch sync run nhưng không có run mới trong `.crew/state/runs/`, transcript nói "ran synchronously despite async=true" | Assistant/agent JOIN hoặc WAIT vào run đang chạy thay vì tạo run mới | Luôn verify runId mới xuất hiện (`ls -t .crew/state/runs/`) sau lệnh dispatch trước khi probe; dispatch khi không run nào active |
 | `test:critical` returns `# fail N>0` | Regression in touched source | Read the failing test's name + assertion; fix the source; rerun |
 | `test:critical` hangs >60s | One test opened a socket/pty that didn't close | Run individual file: `node --import tsx/esm --test --test-force-exit test/unit/<file>.test.ts`; check for missing `await` or unclosed handle |
 | `typecheck` fails with `TS2xxx` | TS type drift after src/ edit | Fix the type error; do not commit until exit 0 |

package/src/config/defaults.ts

@@ -138,7 +138,14 @@ export const DEFAULT_UI = {
 	widgetMaxLines: 8,
 	inlinePanel: true,
 	powerbar: true,
-	dashboardPlacement: "center" as const,
+	// L3 (2026-10-07 real-test review): default "right" — the centered 90%
+	// overlay leaves both margins showing chopped background words (pi-tui's
+	// compositeTuiLine keeps base.before/base.after visible outside overlay
+	// bounds by design); the right-anchored panel covers them. Mirror updates:
+	// install.mjs + the two EFFECTIVE_DEFAULTS maps (handle-settings.ts,
+	// settings-overlay.ts) — install-defaults-sync.test.ts enforces the first,
+	// G17 lesson enforces the rest.
+	dashboardPlacement: "right" as const,
 	dashboardWidth: 72,
 	dashboardLiveRefreshMs: 1000,
 	autoOpenDashboard: false,

package/src/extension/command-completions.ts

@@ -53,31 +53,53 @@ function statusIcon(status: TeamRunManifest["status"]): string {
  * process cwd matches the session cwd.
  */
 export function suggestRunIds(_prefix: string, cwd?: string): AutocompleteItem[] | null {
-	const resolvedCwd = cwd ?? process.cwd();
-	const runs = listRecentRuns(resolvedCwd, MAX_RUN_SUGGESTIONS);
-	if (runs.length === 0) return null;
-	const items: AutocompleteItem[] = runs.map((run) => ({
-		value: run.runId,
-		label: run.runId,
-		description: `${statusIcon(run.status)} ${run.status} · ${run.team} · ${(run.goal ?? "").slice(0, 48)}`,
-	}));
-	return filterByPrefix(items, _prefix);
+	// L-crash (2026-10-08): completion callbacks run inside pi's autocomplete
+	// provider, which does not catch extension errors — never throw here.
+	try {
+		const resolvedCwd = cwd ?? process.cwd();
+		const runs = listRecentRuns(resolvedCwd, MAX_RUN_SUGGESTIONS);
+		if (runs.length === 0) return null;
+		const items: AutocompleteItem[] = runs.map((run) => ({
+			value: run.runId,
+			label: run.runId,
+			description: `${statusIcon(run.status)} ${run.status} · ${run.team} · ${(run.goal ?? "").slice(0, 48)}`,
+		}));
+		return filterByPrefix(items, _prefix);
+	} catch {
+		return null;
+	}
 }
 
-/** Suggest task IDs within a specific run (for /team-result <runId> <taskId>). */
+/**
+ * Suggest task IDs within a specific run (for /team-result <runId> <taskId>).
+ *
+ * L-crash (2026-10-08, P0): this runs inside pi's autocomplete provider
+ * (`CombinedAutocompleteProvider.getSuggestions`), which does NOT catch
+ * extension errors — a throw here kills the whole pi process (live-caught:
+ * uncaught_exception "Invalid runId: team_x/team-transcript" after the
+ * autocomplete popup raced typed input and glued a "/…" suffix onto the
+ * runId token; assertSafePathId correctly rejected it, but the throw
+ * escaped). Completion callbacks must NEVER throw: any failure -> null.
+ */
 export async function suggestTaskIds(runId: string, prefix: string, cwd?: string): Promise<AutocompleteItem[] | null> {
-	const resolvedCwd = cwd ?? process.cwd();
-	// Dynamic import to avoid pulling state-store into the hot command-registration path.
-	// LAZY: defer dynamic import of ../state/stores/state-store.ts to its call site.
-	const { loadRunManifestById } = await import("../state/stores/state-store.ts");
-	const loaded = loadRunManifestById(resolvedCwd, runId);
-	if (!loaded) return null;
-	const items: AutocompleteItem[] = loaded.tasks.map((task) => ({
-		value: task.id,
-		label: task.id,
-		description: `${task.status} · ${task.role} · ${task.title?.slice(0, 40) ?? ""}`,
-	}));
-	return filterByPrefix(items, prefix);
+	try {
+		const resolvedCwd = cwd ?? process.cwd();
+		// Dynamic import to avoid pulling state-store into the hot command-registration path.
+		// LAZY: defer dynamic import of ../state/stores/state-store.ts to its call site.
+		const { loadRunManifestById } = await import("../state/stores/state-store.ts");
+		const loaded = loadRunManifestById(resolvedCwd, runId);
+		if (!loaded) return null;
+		const items: AutocompleteItem[] = loaded.tasks.map((task) => ({
+			value: task.id,
+			label: task.id,
+			description: `${task.status} · ${task.role} · ${task.title?.slice(0, 40) ?? ""}`,
+		}));
+		return filterByPrefix(items, prefix);
+	} catch {
+		// Invalid runId (path-unsafe chars), import/state-store/cache failure —
+		// degrade to "no suggestions" instead of crashing the host process.
+		return null;
+	}
 }
 
 /** Suggest available teams for /team-run <team>. */

package/src/extension/registration/render-loop.ts

@@ -319,12 +319,34 @@ export function setupRenderLoop(
 				);
 			}
 		};
+		// L2 (real-test 2026-10-07, report L2): rebuild-in-place, NEVER
+		// hard-delete. The health gates below used `invalidate(runId)`
+		// (entries.delete) on every tick for terminal/divergent runs — exactly
+		// what the FLICKER FIX invariant (run-snapshot-cache.ts scheduleRefresh
+		// docs + the onRunChange wiring above) forbids: for 1-n frames
+		// `snapshotCache.get(runId)` returned undefined and the widget/powerbar
+		// fell back to their disk-read branch around every run completion
+		// (visible flicker). Route through the coalesced ASYNC rebuild instead —
+		// the entry stays populated until the rebuild re-sets it in place. No
+		// renderScheduler.schedule() here: unlike the fs.watch onRunChange path
+		// we are ALREADY inside a renderTick, and list(20) keeps terminal runs
+		// in sessionManifests for many ticks, so a schedule() from the gates
+		// would reset lastEventAt on every tick and defeat the R1 idle stop
+		// (pinned by preload-idle-render.test.ts).
+		const refreshSnapshotInPlace = (runId: string): void => {
+			try {
+				snapshotCache.scheduleRefresh(runId);
+			} catch (error) {
+				logInternalError("register.renderLoop.snapshotRefresh", error, runId);
+			}
+		};
 		for (const run of sessionManifests) {
 			if (run.status !== "running") {
-				// GATE 1 — preloaded manifest says terminal. Purge any stale snapshot
-				// and clear previously-emitted health notifications so the dashboard
-				// stays clean (belt-and-suspenders with the FIX #1 fresh-read gate).
-				snapshotCache.invalidate(run.runId);
+				// GATE 1 — preloaded manifest says terminal. Refresh the snapshot in
+				// place (never delete) and clear previously-emitted health notifications
+				// so the dashboard stays clean (belt-and-suspenders with the FIX #1
+				// fresh-read gate).
+				refreshSnapshotInPlace(run.runId);
 				clearHealthNotifications(run.runId);
 				continue;
 			}
@@ -333,20 +355,25 @@ export function setupRenderLoop(
 				// (from lastPreloadedManifests) can lag the on-disk terminal
 				// transition; the manifest cache has a 500ms TTL + file watcher so it
 				// is the source of truth. A terminal run must NEVER reach
-				// maybeNotifyHealth. Also purge the stale snapshot + clear any
-				// previously-emitted health notification for this run.
+				// maybeNotifyHealth. Also refresh the stale snapshot in place
+				// (never delete) and clear any previously-emitted health
+				// notification for this run.
 				const freshManifest = ctx.getManifestCache(extensionCtx.cwd).get(run.runId);
 				if (freshManifest?.status !== "running") {
-					snapshotCache.invalidate(run.runId);
+					refreshSnapshotInPlace(run.runId);
 					clearHealthNotifications(run.runId);
 					continue;
 				}
-				const snapshot = snapshotCache.get(run.runId);
+				// L5: paint-path read through the read-only accessor — cached
+				// snapshot only; a lapsed TTL schedules the coalesced async refresh
+				// instead of ever rebuilding synchronously inside renderTick.
+				const snapshot = snapshotCache.readForRender(run.runId);
 				if (!snapshot) continue;
 				if (snapshot.manifest.status !== "running") {
-					// GATE 2 — a running snapshot paired with a now-terminal manifest is
-					// stale. Purge it so subsequent ticks get a fresh view, and clear.
-					snapshotCache.invalidate(run.runId);
+					// GATE 2 — a running manifest paired with a now-terminal snapshot is
+					// stale. Refresh it in place so subsequent ticks get the fresh view,
+					// and clear.
+					refreshSnapshotInPlace(run.runId);
 					clearHealthNotifications(run.runId);
 					continue;
 				}
@@ -357,10 +384,10 @@ export function setupRenderLoop(
 				// worker counted as active-without-heartbeat and fired a false
 				// "dead worker" (live: team_20260923100114, 01_explore parked on
 				// ask). Overlay FRESH statuses before summarizing; divergence also
-				// invalidates the stale cache entry so the next tick rebuilds it.
+				// schedules an in-place rebuild so the cache syncs off the tick.
 				const freshTasks = loadTasksWithRecovery(freshManifest.tasksPath, freshManifest.eventsPath, run.runId);
 				const overlaid = overlayFreshTaskStatuses(snapshot, freshTasks);
-				if (overlaid !== snapshot) snapshotCache.invalidate(run.runId);
+				if (overlaid !== snapshot) refreshSnapshotInPlace(run.runId);
 				const summary = summarizeHeartbeats(overlaid, { now });
 				const fingerprint = healthNotifyFingerprint(summary, overlaid.tasks.length);
 				const maybeNotifyHealth = (kind: string, count: number, title: string, body: string): void => {
@@ -424,13 +451,16 @@ export function setupRenderLoop(
 			// The next `renderTick` then saw `get() === undefined` for every run,
 			// so `activeWidgetRuns` dropped them to "(loading…)" until the async
 			// preload rebuilt the cache — an endless visible flicker. For a
-			// specific runId we now refresh-if-stale (stale-while-revalidate) so
-			// the widget always sees a populated snapshot; a no-runId tick does
-			// nothing (renderTick itself repaints; the cache's own
-			// run:state/worker:lifecycle subscription refreshes affected runs).
+			// specific runId we schedule the coalesced ASYNC refresh (L5,
+			// real-test 2026-10-07): refreshIfStale() did a SYNC full rebuild
+			// between paints (and a sync build for missing entries), blocking the
+			// event loop mid-render; scheduleRefresh keeps the entry populated and
+			// rebuilds off the tick. A no-runId tick does nothing (renderTick
+			// itself repaints; the cache's own run:state/worker:lifecycle
+			// subscription refreshes affected runs).
 			if (!runId) return;
 			try {
-				ctx.getRunSnapshotCache(extensionCtx.cwd).refreshIfStale(runId);
+				ctx.getRunSnapshotCache(extensionCtx.cwd).scheduleRefresh(runId);
 			} catch (error) {
 				logInternalError("register.renderScheduler.refresh", error, runId);
 			}
@@ -442,9 +472,9 @@ export function setupRenderLoop(
 	const unsubscribeRunEvents = runEventBus.onAny((event) => {
 		// bug-026 sub-issue C: evict terminal runs from the preloaded manifest
 		// frame so a stale "running" entry cannot persist for the session
-		// lifetime. Additive to the renderTick GATE 1 / FIX #1 / GATE 2 snapshot
-		// purges (which invalidate the snapshot cache) — those gates do not
-		// touch lastPreloadedManifests itself.
+		// lifetime. Additive to the renderTick GATE 1 / FIX #1 / GATE 2
+		// snapshot refreshes (which rebuild the snapshot cache entries in
+		// place) — those gates do not touch lastPreloadedManifests itself.
 		lastPreloadedManifests = applyTerminalRunEventToManifests(lastPreloadedManifests, event);
 		sched.schedule({
 			runId: event.runId,

package/src/extension/team-tool/handle-settings.ts

@@ -35,7 +35,10 @@ const EFFECTIVE_DEFAULTS: Record<string, unknown> = {
 	"ui.showModel": true,
 	"ui.showTokens": true,
 	"ui.showTools": true,
-	"ui.dashboardPlacement": "center",
+	// L3 (2026-10-07): mirrors DEFAULT_UI.dashboardPlacement = "right"
+	// (defaults.ts) — G17: duplicated EFFECTIVE_DEFAULTS maps must track the
+	// canonical default or the settings overlay shows a stale value.
+	"ui.dashboardPlacement": "right",
 	"ui.dashboardWidth": 72,
 	"ui.autoOpenDashboard": false,
 	// G17 sync (2026-09-10 review): canonical DEFAULT_UI.widgetPlacement =

package/src/ui/dashboard-panes/agents-pane.ts

@@ -134,8 +134,9 @@ export function renderAgentsPane(snapshot: RunUiSnapshot | undefined, options: R
 
 	// `3/3 tasks · 3 agents` — the label arrives pre-pluralised by the caller
 	// ("N agents"); the task tally keeps the slash form on purpose (it reads as
-	// progress, not as a count).
-	lines.push(`${completed}/${total} tasks · ${label}`);
+	// progress, not as a count), with the noun pluralised by the TOTAL
+	// (formatCount, L9): `1/1 task`, `3/3 tasks`.
+	lines.push(`${completed}/${formatCount(total, "task")} · ${label}`);
 
 	for (const agent of realAgents.slice(0, 12)) {
 		const liveHandle = liveByTaskId.get(agent.taskId);

package/src/ui/dashboard-panes/health-pane.ts

@@ -16,8 +16,13 @@ function seconds(ms: number): string {
 export function renderHealthPane(snapshot: RunUiSnapshot | undefined, opts: HealthPaneOptions = {}): string[] {
 	if (!snapshot) return ["Health pane: snapshot unavailable"];
 	const summary = summarizeHeartbeats(snapshot, opts);
+	// L7 judgment: this pane IS the diagnostic surface — `stale`/`dead`/
+	// `missing` are the exact vocabulary the K kill-stale / R recovery actions
+	// and the diagnostic export act on, so the LABELS stay. But the wire
+	// separator goes (report L7 flags `stale=`): the line now speaks the same
+	// count-first tally dialect as `1/3 healthy`, not `stale=2` key=value.
 	const lines = [
-		`Health pane: ${summary.healthy}/${summary.totalTasks} healthy · stale=${summary.stale} · dead=${summary.dead} · missing=${summary.missing}`,
+		`Health pane: ${summary.healthy}/${summary.totalTasks} healthy · ${summary.stale} stale · ${summary.dead} dead · ${summary.missing} missing`,
 	];
 	if (summary.worstStaleMs > 0) lines.push(`Worst stale: ${seconds(summary.worstStaleMs)} ago`);
 	// One hint format (rail.ts `formatHint`): keys `label` joined by ` · `.

package/src/ui/dashboard-panes/mailbox-pane.ts

@@ -1,3 +1,4 @@
+import { formatCount } from "../format-helpers.ts";
 import { formatHint } from "../rail.ts";
 import type { RunUiSnapshot } from "../snapshot-types.ts";
 
@@ -8,24 +9,28 @@ export function renderMailboxPane(snapshot: RunUiSnapshot | undefined): string[]
 	const unread = mailbox.inboxUnread ?? 0;
 	const outgoing = mailbox.outboxPending ?? 0;
 	const attention = mailbox.needsAttention ?? 0;
-	const lines: string[] = [`Mailbox pane: inbox unread=${unread} · outbox pending=${outgoing} · attention=${attention}${approx}`];
-	// Kind-separated breakdown
+	// L7 dialect: counts speak the compactUsage TUI form (the `↑2.8k ↓3.7k`
+	// pattern from live-run-sidebar.ts), NOT the `unread=2` wire format. ↓ =
+	// received (inbox), ↑ = sent (outbox pending); ⚠ marks attention (the same
+	// pane-local warning glyph the steering line below already uses).
+	const lines: string[] = [`Mailbox pane: ↓${unread} unread · ↑${outgoing} pending · ⚠${attention} attention${approx}`];
+	// Kind-separated breakdown — every kind here is an inbox (received) count.
 	const kindParts: string[] = [];
 	const steer = mailbox.steerUnread ?? 0;
 	const followUp = mailbox.followUpUnread ?? 0;
 	const response = mailbox.responseUnread ?? 0;
 	const message = mailbox.messageUnread ?? 0;
-	if (steer > 0) kindParts.push(`steer=${steer}`);
-	if (followUp > 0) kindParts.push(`follow-up=${followUp}`);
-	if (response > 0) kindParts.push(`response=${response}`);
-	if (message > 0) kindParts.push(`message=${message}`);
+	if (steer > 0) kindParts.push(`↓${steer} steer`);
+	if (followUp > 0) kindParts.push(`↓${followUp} follow-up`);
+	if (response > 0) kindParts.push(`↓${response} response`);
+	if (message > 0) kindParts.push(`↓${message} message`);
 	if (kindParts.length > 0) {
 		lines.push(`  Breakdown: ${kindParts.join(" · ")}`);
 		if (steer > 0) {
 			lines.push("  ⚠ Urgent: steering messages require immediate attention.");
 		}
 		if (followUp > 0) {
-			lines.push(`  📋 ${followUp} follow-up(s) pending review.`);
+			lines.push(`  📋 ${formatCount(followUp, "follow-up")} pending review.`);
 		}
 	}
 	if (attention > 0) {

package/src/ui/dashboard-panes/plan-pane.ts

@@ -17,6 +17,7 @@
 import { isPlanApprovalPending } from "../../runtime/plan-approval.ts";
 import { deriveItemProgress } from "../../state/stores/plan-store.ts";
 import type { PlanItemStatus, TeamTaskState } from "../../state/types.ts";
+import { formatCount } from "../format-helpers.ts";
 import { ACTIVE, formatHint, statusIcon } from "../rail.ts";
 
 /**
@@ -99,7 +100,9 @@ export function planRevisionDiff(snapshot: RunUiSnapshot): string[] {
 		const beforeTasks = before.taskIds?.length ?? 0;
 		const currentTasks = item.taskIds?.length ?? 0;
 		if (before.status !== item.status || beforeTasks !== currentTasks) {
-			lines.push(`  ~ ${item.id} ${item.title ?? "?"} [${before.status}→${item.status} · ${beforeTasks}→${currentTasks} tasks]`);
+			lines.push(
+				`  ~ ${item.id} ${item.title ?? "?"} [${before.status}→${item.status} · ${beforeTasks}→${formatCount(currentTasks, "task")}]`,
+			);
 		}
 		prevItems.delete(item.id);
 	}
@@ -128,7 +131,7 @@ export function renderPlanPane(snapshot: RunUiSnapshot, options: PlanPaneOptions
 	const itemById = new Map(items.map((i) => [i.id, i]));
 
 	const pending = isPlanApprovalPending(snapshot.manifest);
-	const header = `Plan pane: ${current.title ?? "?"} @v${current.version} (${phases.length} phases · ${items.length} items)`;
+	const header = `Plan pane: ${current.title ?? "?"} @v${current.version} (${formatCount(phases.length, "phase")} · ${formatCount(items.length, "item")})`;
 	// Hint join format is the rail one (` · `, close/deny last). NOT routed
 	// through `formatHint` (yet): its `keyToken` upper-cases a bare letter
 	// (`n` → `N`) and the locked pane test

package/src/ui/dashboard-panes/progress-pane.ts

@@ -8,8 +8,14 @@ export function renderProgressPane(snapshot: RunUiSnapshot | undefined): string[
 	if (!snapshot) return ["Progress pane: snapshot unavailable"];
 	const progress = snapshot.progress;
 	const groupJoins = snapshot.groupJoins ?? [];
+	// L7 judgment: the header and group-join lines speak the count-first tally
+	// dialect (`1 running · 0 queued`, `req-123 · acknowledged`), not the
+	// `running=1`/`ack=acknowledged` wire format. The ONE deliberate
+	// key=value survivor is `reason=` below: the cancellation reason is a
+	// machine code (`leader_interrupted`) — diagnostic data, not prose, and
+	// the shape (not the wording) is what the operator greps for.
 	const groupJoinLines = groupJoins.length
-		? groupJoins.map((item) => `group join ${item.partial ? "partial" : "completed"}: ${item.requestId} ack=${item.ack}`)
+		? groupJoins.map((item) => `group join ${item.partial ? "partial" : "completed"}: ${item.requestId} · ${item.ack}`)
 		: ["group joins: none"];
 	const cancellationLine = snapshot.cancellationReason ? [`cancelled: reason=${snapshot.cancellationReason}`] : [];
 	const runProgress = computePhaseProgress(snapshot.tasks);
@@ -30,7 +36,7 @@ export function renderProgressPane(snapshot: RunUiSnapshot | undefined): string[
 	// uncolored by design). One line while the run is parked on approval.
 	const planBanner = isPlanApprovalPending(snapshot.manifest) ? [`⚠ plan approval pending — ${PLAN_APPROVAL_HINT}`] : [];
 	return [
-		`Progress pane: ${progress.completed}/${progress.total} completed · running=${progress.running} queued=${progress.queued} failed=${progress.failed}`,
+		`Progress pane: ${progress.completed}/${progress.total} completed · ${progress.running} running · ${progress.queued} queued · ${progress.failed} failed`,
 		...planBanner,
 		...dwfPhaseLines,
 		...phaseHeader,

package/src/ui/live-conversation-overlay.ts

@@ -28,7 +28,7 @@
 import { matchesKey } from "@earendil-works/pi-tui";
 import type { LiveAgentHandle } from "../runtime/live-session/live-agent-manager.ts";
 import { truncate } from "../utils/visual.ts";
-import { formatCount } from "./format-helpers.ts";
+import { formatCount, formatDuration } from "./format-helpers.ts";
 import { computeLiveDurationMs } from "./live-duration.ts";
 import { canopyLine, formatHint, gaugeBar, RAIL, railLeaders, railLine, statusSlot } from "./rail.ts";
 import { spinnerFrame } from "./spinner.ts";
@@ -120,7 +120,9 @@ export class LiveConversationOverlay {
 
 	private refreshSummary(): void {
 		const act = this.handle.activity;
-		const summary = `${LiveConversationOverlay.SUMMARY_PREFIX}[${formatCount(act.turnCount ?? 0, "turn")} · ${formatCount(act.toolUses ?? 0, "tool")} · ${(computeLiveDurationMs(act, this.nowMs()) / 1000).toFixed(1)}s]`;
+		// L9: durations speak formatDuration (`5m44s`), never raw
+		// `(ms/1000).toFixed(1)s` seconds (`344.0s`).
+		const summary = `${LiveConversationOverlay.SUMMARY_PREFIX}[${formatCount(act.turnCount ?? 0, "turn")} · ${formatCount(act.toolUses ?? 0, "tool")} · ${formatDuration(computeLiveDurationMs(act, this.nowMs()))}]`;
 		const lastLine = this.cachedLines[this.cachedLines.length - 1];
 		if (lastLine?.startsWith(LiveConversationOverlay.SUMMARY_PREFIX)) {
 			this.cachedLines[this.cachedLines.length - 1] = summary;
@@ -270,7 +272,7 @@ export class LiveConversationOverlay {
 		if (act.maxTurns != null) parts.push(`turn ${act.turnCount ?? 0}/${act.maxTurns}`);
 		else if ((act.turnCount ?? 0) > 0) parts.push(`turn ${act.turnCount}`);
 		if ((act.toolUses ?? 0) > 0) parts.push(formatCount(act.toolUses ?? 0, "tool"));
-		parts.push(`${(computeLiveDurationMs(act, this.nowMs()) / 1000).toFixed(1)}s`);
+		parts.push(formatDuration(computeLiveDurationMs(act, this.nowMs())));
 		try {
 			const ctxPct = this.handle.session.getSessionStats?.()?.contextUsage?.percent;
 			if (ctxPct != null) {

package/src/ui/live-duration.ts

@@ -49,7 +49,8 @@ export function computeLiveDurationMs(activity: LiveActivity, nowMs: number = Da
 	return Number.isFinite(ms) && ms >= 0 ? ms : 0;
 }
 
-/** Format a live duration in seconds, e.g. `12.3s`. Returns `0.0s` for 0. */
-export function formatLiveDuration(activity: LiveActivity, nowMs: number = Date.now()): string {
-	return `${(computeLiveDurationMs(activity, nowMs) / 1000).toFixed(1)}s`;
-}
+// L9 note: the `formatLiveDuration` export was deleted (2026-10-07). It had
+// zero production importers — its raw-seconds `(ms/1000).toFixed(1)s` output
+// was exactly the wire format the dialect sweep retires; every live surface
+// now formats via `formatDuration` (format-helpers.ts) over
+// `computeLiveDurationMs`.