pi-crew 0.9.16 → 0.9.18

package/docs/migration/atomic-write-v2-migration.md

@@ -0,0 +1,297 @@
+# atomic-write-v2 migration plan
+
+> Status: **PROPOSED** — decision RECOMMEND MIGRATE (staged, feature-flagged).
+> Source: performance review `docs/perf/performance-review-2026-07.md` (findings F3–F6).
+> Scope: replace the standalone-function module `src/state/atomic-write.ts`
+> with the class-based `src/state/atomic-write-v2.ts` (`AtomicWriter`) over
+> three staged phases behind a feature flag.
+
+## Table of contents
+
+- [1. Why migrate](#1-why-migrate)
+- [2. API differences](#2-api-differences)
+- [3. Migration phases](#3-migration-phases)
+  - [Phase 1 — dual-write (feature flag)](#phase-1--dual-write-feature-flag)
+  - [Phase 2 — switch default](#phase-2--switch-default)
+  - [Phase 3 — deprecate v1](#phase-3--deprecate-v1)
+- [4. Risks and mitigations](#4-risks-and-mitigations)
+- [5. Effort estimate](#5-effort-estimate)
+- [6. Decision](#6-decision)
+- [7. Appendix — call-site inventory](#7-appendix--call-site-inventory)
+
+## 1. Why migrate
+
+The performance review (F3, F4, F6) traced a write-path regression to commit
+`13f4490`. That commit hardened `atomicWriteFile` against a CI-flake stale-read
+race (the `mailbox-replay` intermittent failure) by adding **two** `fsync`
+calls per synchronous write:
+
+1. **Data fsync** — `fs.fsyncSync(fd)` on the temp file before rename
+   (`atomic-write.ts` ~line 287, in the `atomicWriteFile` write body). This
+   forces the written bytes out of the page cache to disk so a subsequent
+   `readFileSync` after the rename always sees the new content.
+2. **Directory fsync** — `fs.fsyncSync(dirFd)` on the parent directory after
+   the rename (`atomic-write.ts` ~lines 307–309, POSIX-only, skipped on
+   Windows). This makes the directory-entry update (the rename) durable so a
+   subsequent `open()` cannot race and observe `ENOENT` or stale content on a
+   high-I/O CI runner.
+
+The dir-fsync is the expensive half. `persistSingleTaskUpdate` calls the write
+path ~5 times per task; at 2 fsync per call that is roughly **+10 fsync per
+task**, and directory fsync is especially costly on Windows and on
+network/overlay filesystems. The review also had to bump the CI timeout
+600s → 900s (commit `9bbeb45`) partly to absorb this cost.
+
+`atomic-write-v2.ts` (the `AtomicWriter` class) keeps only the **data fsync**,
+and even that is **best-effort** — it is wrapped in a `try/catch` that swallows
+the error (`atomic-write-v2.ts` ~line 30 in `writeSync`, and `fd.sync()` in
+`writeAsync`). It performs **no directory fsync at all**.
+
+### Quantified difference
+
+| Cost per write         | atomic-write.ts (v1)                  | atomic-write-v2.ts (v2)         |
+| ---------------------- | ------------------------------------- | ------------------------------- |
+| Data fsync             | 1 (mandatory, throws on failure)      | 1 (best-effort, swallowed)      |
+| Directory fsync        | 1 (POSIX only)                        | 0                               |
+| `isSymlinkSafePath`    | 2 full ancestor walks (pre + pre-rename) | 0                            |
+| `lstat` syscalls       | ~10+ per level × 2 for a deep path    | 0                               |
+| Rename mechanism       | `link()` + `unlink()` (+ retry/jitter) | `rename()` (single syscall)    |
+
+The headline is roughly **2× fewer fsync operations per call** (drop the dir
+fsync, keep data fsync), plus the elimination of two full ancestor-walk
+symlink scans (F5) and the `link()`+`unlink()` pair in favor of a single
+`rename()`. On a deep state-store path (`.crew/state/runs/{runId}/…`) the v1
+path issues ~20+ `lstat` calls per write for symlink validation alone; v2
+issues none. The net expected win on the hot `persistSingleTaskUpdate` path is
+approximately halving the per-call durability cost, with a larger relative win
+on syscall count.
+
+The trade-off is explicit: **v2 loses the dir-fsync durability guarantee.** On
+journaled Linux filesystems (ext4 with `data=ordered`, xfs) the rename is still
+crash-atomic, but a power loss in the sub-millisecond window between write and
+directory-entry flush can leave the *old* content visible after reboot. On
+tmpfs this window is effectively the whole lifetime of the entry (no
+durability at all). This is the guarantee the `13f4490` commit was added to
+provide, so dropping it must be a conscious, documented decision (see
+[risks](#4-risks-and-mitigations)).
+
+## 2. API differences
+
+The two modules are shaped very differently, so migration is not a
+drop-in symbol rename — callers change from free functions to a constructed
+instance.
+
+### v1 — `atomic-write.ts` (module of standalone functions)
+
+- `atomicWriteFile(filePath, content, expectedHash?)`
+- `atomicWriteFileAsync(filePath, content)`
+- `atomicWriteJson(filePath, value)`
+- `atomicWriteJsonAsync(filePath, value)`
+- `atomicWriteJsonCoalesced(filePath, value, coalesceMs?)` — 50 ms coalescing buffer
+- `flushPendingAtomicWrites()` — flush the coalesce buffer
+- `isSymlinkSafePath(filePath)` — exported symlink-safety guard
+- `renameWithRetry(...)` / `renameWithRetryAsync(...)` — exported rename helpers with jitter
+- `readJsonFile(filePath)` — tolerant JSON reader
+
+Behavioral characteristics:
+
+- **Symlink safety**: explicit `isSymlinkSafePath` check both **before open**
+  and **again immediately before rename** (TOCTOU re-check), plus a
+  post-rename `lstat` guard on failure.
+- **Rename**: `link()` + `unlink()` (`renameWithLinkSync` /
+  `renameWithLinkAsync`) so the destination symlink is *not* followed; Windows
+  falls back to `renameSync`/`MoveFileEx`. Retries with exponential backoff and
+  ±20% jitter.
+- **Durability**: mandatory data fsync (throws on failure) + POSIX directory
+  fsync.
+- **Tmp naming**: `${filePath}.${randomUUID()}.tmp`.
+- **Coalescing**: a per-path buffer with generation counters, retry/backoff,
+  and process `exit`/`SIGTERM`/`SIGINT` auto-flush hooks.
+- **Optional worker offload**: `atomicWriteFileAsync` can dispatch to a worker
+  thread when `PI_CREW_WORKER_ATOMIC_WRITER=1`.
+
+### v2 — `atomic-write-v2.ts` (`AtomicWriter` class)
+
+- `new AtomicWriter(baseDir)` — constructed with a base directory
+- `writeSync(targetPath, content)`
+- `writeAsync(targetPath, content)`
+- `writeJsonSync(targetPath, value)`
+- `writeJsonAsync(targetPath, value)`
+- private `.gitignore`-on-first-use per directory (writes `*\n` the first time
+  a directory is touched)
+
+Behavioral characteristics:
+
+- **Symlink safety**: **none** — no `isSymlinkSafePath`, no pre/post checks.
+- **Rename**: plain `rename()` (POSIX-atomic but **symlink-following**), single
+  syscall, no retry/jitter loop.
+- **Durability**: best-effort data fsync (swallowed), **no directory fsync**.
+- **Tmp naming**: `${targetPath}.${randomUUID()}.tmp` (same scheme as v1).
+- **Coalescing**: none (no buffer, no flush hooks).
+- **Reader**: none (no `readJsonFile` equivalent).
+
+### Feature-gap summary (what v2 does NOT have yet)
+
+| Capability                         | v1  | v2  | Notes                                              |
+| ---------------------------------- | --- | --- | -------------------------------------------------- |
+| Symlink-safe rename                | ✅   | ❌   | v2 uses `rename()` which follows symlinks          |
+| `isSymlinkSafePath` export         | ✅   | ❌   | consumed elsewhere — must stay available           |
+| Coalesced writes + flush hooks     | ✅   | ❌   | required by `saveRunTasksCoalesced` path (F4)      |
+| `readJsonFile`                     | ✅   | ❌   | tolerant reader used across state-store            |
+| Retry/backoff on contended rename  | ✅   | ❌   | v2 throws on first `rename()` failure              |
+| Windows short/long-name handling   | ✅   | ❌   | v1 has explicit `MoveFileEx` fallback              |
+| Directory fsync                    | ✅   | ❌   | the durability guarantee being intentionally dropped |
+| `.gitignore` on first use          | ❌   | ✅   | v2 convenience; v1 leaves this to callers          |
+
+**Implication:** a straight swap is not viable until v2 grows (or the
+dispatcher re-provides) the coalescing buffer, the tolerant reader, the retry
+loop, and an opt-in symlink guard. The phased plan below keeps v1 as the source
+of those capabilities during transition rather than porting them all up front.
+
+## 3. Migration phases
+
+### Phase 1 — dual-write (feature flag)
+
+Estimated ~1–2 days.
+
+- Introduce an environment feature flag `PI_CREW_ATOMIC_WRITER` with values
+  `v1` (default) and `v2`.
+- Add a thin adapter module `src/state/atomic-write-dispatcher.ts` that exposes
+  the v1 free-function surface (`atomicWriteFile`, `atomicWriteJson`, and their
+  async variants) and routes each call to either the v1 functions or a shared
+  `AtomicWriter` instance based on the flag. Capabilities v2 lacks
+  (`atomicWriteJsonCoalesced`, `flushPendingAtomicWrites`, `isSymlinkSafePath`,
+  `readJsonFile`) continue to delegate to v1 unconditionally in this phase.
+- Keep `atomic-write.ts` as the default; nothing changes for users who do not
+  set the flag.
+- Add a benchmark test that writes N files through both paths under **tmpfs**
+  and **ext4** and asserts the fsync-count / wall-clock delta matches the
+  ~2× prediction. Land it under `test/bench/` (guarded so it does not run in
+  the default `test:unit` gate).
+
+Exit criteria: flag flips implementation with zero behavior change for default
+users; benchmark confirms the predicted delta.
+
+### Phase 2 — switch default
+
+Estimated ~1–2 days.
+
+- Flip the dispatcher default to `v2`; users can opt back to the old path with
+  `PI_CREW_ATOMIC_WRITER=v1`.
+- Route direct callers of `atomicWriteFile` / `atomicWriteJson` (in
+  `extension/team-tool.ts`, `state-store.ts`, and any other direct importers)
+  through the dispatcher rather than importing `atomic-write.ts` directly.
+- Before flipping, back-fill v2 (or the dispatcher wrapper around v2) with the
+  currently-missing durability/safety features that production relies on:
+  retry-on-contended-rename, an **opt-in** symlink guard for
+  `userPiRoot()`-adjacent writes, and either the coalescing buffer or continued
+  delegation to v1 for the coalesced path.
+- Monitor for one full release cycle. Watch for stale-read CI flakes (the exact
+  failure `13f4490` fixed) — if they resurface, the dir-fsync drop is the prime
+  suspect and the flag provides an instant rollback.
+
+Exit criteria: one clean release cycle on the v2 default with no stale-read or
+symlink regressions reported.
+
+### Phase 3 — deprecate v1
+
+Estimated ~1 day.
+
+- Remove `atomic-write.ts` and the `v1` flag branch (keep any still-needed
+  utilities — notably the symlink-safe `link()`+`unlink()` helper and
+  `isSymlinkSafePath` — either in the renamed module or a small
+  `symlink-safety.ts`).
+- Rename `atomic-write-v2.ts` → `atomic-write.ts` and update imports.
+- Add a `CHANGELOG.md` entry under a **minor** version bump documenting the
+  durability trade-off (no directory fsync by default) and the
+  `PI_CREW_ATOMIC_WRITER` flag removal.
+
+Exit criteria: single implementation, no flag, green CI, CHANGELOG documents
+the durability change.
+
+## 4. Risks and mitigations
+
+### Drop of strict symlink safety (security)
+
+v2 performs **no** `isSymlinkSafePath` check and uses `rename()`, which follows
+a symlink at the destination. An attacker who can plant a symlink inside
+`userPiRoot()` (or an ancestor of a write target) could redirect a write to an
+arbitrary path.
+
+Mitigations:
+
+1. v2 callers must pre-validate every target path via the `paths.ts` helpers so
+   writes are confined to the user's own pi-crew state tree.
+2. Keep the v1 `link()`+`unlink()` rename helper and `isSymlinkSafePath` as
+   reusable utilities even after the module rename, and offer them as an opt-in
+   "safe rename" mode in the dispatcher for `userPiRoot()`-adjacent writes.
+3. Add a CI test that plants a symlink inside the `.pi/agent/pi-crew/` tree and
+   asserts the writer refuses (or does not follow) it.
+
+### Lockfile / tmp collision risk
+
+Both implementations name temp files `${target}.${randomUUID()}.tmp`. UUIDv4
+collision probability is astronomically low (documented here for completeness).
+The larger concern is the inode-scan cost of many `.tmp` siblings in a large
+directory. Recommend writing tmp files into a per-process subdir
+(`<baseDir>/.tmp/<pid>/`) to bound directory size and simplify crash cleanup.
+
+### Crash-durability regression
+
+v2's missing directory fsync means a power loss in the window between the data
+write and the directory-entry flush can leave the **old** content visible after
+reboot. This is rare on journaled filesystems (ext4/xfs) and common on tmpfs.
+
+Mitigations:
+
+1. Document the trade-off in the v2 module docblock and in `CHANGELOG.md`.
+2. Keep the flag so at-risk deployments (non-journaled FS, tmpfs-backed state)
+   can pin `v1`.
+3. Optionally expose a per-call `durable: true` option in the dispatcher that
+   re-enables the directory fsync for the small set of writes that truly need
+   it (e.g. terminal manifest writes), so the common path stays fast while the
+   critical path stays durable.
+
+## 5. Effort estimate
+
+**Size: M (3–5 days.)**
+
+| Work item                                  | Estimate |
+| ------------------------------------------ | -------- |
+| Phase 1 — flag + dispatcher + benchmark    | ~1–2 days |
+| Phase 2 — feature back-fill + switch + soak | ~1–2 days |
+| Phase 3 — deprecate + rename + CHANGELOG   | ~1 day    |
+| Benchmark harness (tmpfs + ext4)           | ~0.5 day  |
+| Docs / review pass                         | ~0.5 day  |
+
+## 6. Decision
+
+**RECOMMEND MIGRATE** — staged, feature-flagged.
+
+Justification:
+
+- The write path is hot: `persistSingleTaskUpdate` calls it ~5×/task and the
+  state-store fires on the same 1 Hz idle / 6 Hz active cadence as
+  `loadConfig`. Halving the per-call durability cost (drop dir fsync, keep data
+  fsync) plus eliminating the double ancestor-walk symlink scan is a meaningful
+  and broadly-applied win.
+- The durability risk from dropping the directory fsync is bounded: it only
+  matters on non-journaled/tmpfs filesystems and only within the sub-millisecond
+  on-disk write window. The `PI_CREW_ATOMIC_WRITER=v1` fallback lets at-risk
+  setups opt out.
+- The symlink-safety regression is the sharpest edge and is mitigated by
+  `paths.ts` pre-validation, an opt-in safe-rename mode, and a CI symlink-plant
+  test — not by accepting v2 as-is.
+
+Because the plan is staged behind a flag with an instant rollback, the blast
+radius at each step is small and the exact CI flake that `13f4490` fixed remains
+observable (and reversible) during the Phase 2 soak.
+
+## 7. Appendix — call-site inventory
+
+Before Phase 2, enumerate the direct importers to route through the dispatcher.
+As of this plan, `atomic-write-v2.ts` has **0 importers** (confirmed by
+`grep -rn "atomic-write-v2" src/`). The v1 surface is consumed by
+`state-store.ts`, `extension/team-tool.ts`, and the coalesced/reader paths;
+run `grep -rn "atomic-write\b" src/` at the start of Phase 2 to produce the
+authoritative list, since call sites shift between now and then.

package/docs/patterns/command-agent-skill.md

@@ -28,7 +28,7 @@ description: Chief Security Officer who finds OWASP Top 10 threats
 tools: read, bash, edit
 model: claude-sonnet-4-20250514
 effort: high
-skills: safe-bash, security-review
+skills: safe-bash
 maxTurns: 30
 contextMode: fresh
 ---

package/docs/perf/performance-review-2026-07.md

@@ -0,0 +1,287 @@
+# Performance Review — pi-crew v0.9.17 (2026-07-02)
+
+> Deep-dive review toàn bộ codebase (~434 file TS, ~82.7k dòng) tập trung vào hiệu năng.
+> Mọi phát hiện đều có file:line cụ thể và đã được xác minh trực tiếp trên source.
+> Bổ sung cho `docs/perf/final-report-2026-05.md` và `docs/optimization-plan.md` (các vòng tối ưu trước).
+>
+> **Cập nhật sau pull v0.9.17**: ban đầu review trên v0.9.16, sau đó user pull 40 commits mới
+> (`1418fa7..22a8e72`, ~20k dòng thay đổi trong `src/`). Mọi phát hiện đã được re-verify trên
+> code mới. Xem thêm [§5 — Delta v0.9.17](#5-delta-v0917--những-gì-đã-fix-và-regressed).
+
+## 1. Đánh giá tổng quan
+
+### Điểm mạnh (đã làm tốt)
+
+| Hạng mục | Bằng chứng |
+|---|---|
+| Render path zero-fs-IO | `register.ts:1744+` — renderTick chỉ đọc từ frame preload, không chạm disk |
+| Snapshot cache 2 tầng (TTL 1.5s + stamp mtime/size) | `run-snapshot-cache.ts:21-25, 79-97` — tail-read 32KB, không bao giờ parse full events.jsonl |
+| Event tail đọc theo byte-offset | `utils/incremental-reader.ts:23` — `readJsonlSince` dùng openSync/readSync từ offset |
+| Concurrency có hard cap | `config/defaults.ts:46-56` — hardCap 8, per-workflow 2-4, enforced qua `mapConcurrent` |
+| Capture stdout/stderr bounded | `child-pi.ts:53` — tail cap 512KiB, có backpressure soft watermark 256KiB |
+| Timer nền đều `unref()` | auto-repair, temp-reconcile, notifier — không giữ event loop |
+| Watcher bounded theo active runs | `register.ts:1690-1706` — reconcile watcher chỉ O(active runs) |
+| Lazy import có kỷ luật | `// LAZY:` markers + `npm run check:lazy-imports` |
+
+Kiến trúc 3 layer rõ ràng, defensive coding tốt (CAS, lock, terminal-state guard). Vấn đề hiệu năng chủ yếu KHÔNG nằm ở thuật toán mà ở **tần suất lặp lại của I/O đồng bộ nhỏ** trên hot path.
+
+### Điểm yếu tổng quát
+
+1. **State layer ghi-toàn-file + fsync per-event**: mỗi thay đổi status của 1 task ghi lại toàn bộ tasks.json (pretty-printed), mỗi event append kèm 1 fsync + 1 atomic write sidecar.
+2. **Cache tồn tại nhưng tự vô hiệu hóa**: manifest cache bị global-generation invalidation, discovery cache TTL 500ms, config hoàn toàn không cache.
+3. **Sync I/O chặn event loop**: `execFileSync` (git), `withRunLockSync` + `sleepSync`, `statSync` chuỗi — chạy trong extension host của Pi, chặn cả UI.
+4. **Hạ tầng batching/coalescing đã viết nhưng không được dùng**: `appendEventBuffered`, `saveRunTasksCoalesced` đều 0 call site.
+
+---
+
+## 2. Phát hiện chi tiết theo layer
+
+### 2.1 State layer
+
+#### F1 — HIGH: Global generation counter phá cache của TẤT CẢ runs
+- `src/state/state-store.ts:73, 125-128`
+```ts
+let manifestCacheGeneration = 0;
+function invalidateRunCache(stateRoot: string): void {
+    manifestCache.delete(stateRoot);
+    manifestCacheGeneration++;   // <-- vô hiệu hóa MỌI entry, không chỉ run này
+}
+```
+- Cache hit yêu cầu `cached.generation === manifestCacheGeneration` (`:589, :685`). Mỗi `saveRunTasks`/`saveRunManifest` của BẤT KỲ run nào đều bump counter, nên khi có 1 run active, hit-rate của cache sụp về ~0. Mỗi miss = 2 statSync + 2 readFileSync + JSON.parse trong retry loop tối đa 5 vòng (`:617-631`).
+- **Fix đề xuất**: generation counter per-stateRoot (`Map<string, number>`) thay vì global. Mtime/size check đã đủ chống spoof cho từng entry.
+
+#### F2 — HIGH: `persistSingleTaskUpdate` — sync CAS loop tối đa 100 vòng, mỗi vòng đọc lại full state
+- `src/runtime/task-runner/state-helpers.ts:28-110`, gọi tại `task-runner.ts:233, 424, 538, 617, 1347` (mỗi lần task đổi status/checkpoint)
+```ts
+return withRunLockSync(manifest, () => {
+    retryLoop: for (let attempt = 0; attempt < 100; attempt++) {
+        const latest = loadRunManifestById(manifest.cwd, manifest.runId)?.tasks ?? fallbackTasks;
+        // ... 3x statSync mtime check ...
+```
+- Toàn bộ sync, dưới `withRunLockSync` (poll bằng `sleepSync` chặn event loop). Kết hợp F1 (cache lạnh) nghĩa là mỗi checkpoint = lock + full read manifest.json + tasks.json + full rewrite tasks.json.
+- **Fix đề xuất**: (a) đã cầm run lock thì mtime-CAS 3 lần stat là thừa — lock loại trừ writer khác cùng process-tree, chỉ cần 1 lần đọc + 1 lần ghi; (b) chuyển sang async variant; (c) giữ tasks in-memory per-run và chỉ ghi diff-triggered.
+
+#### F3 — HIGH → PARTIALLY FIXED (v0.9.17): Mỗi event append = fsync + atomic-write sidecar `.seq`
+- `src/state/event-log.ts:583-611` (sync path không đổi)
+```ts
+fs.appendFileSync(eventsPath, `${JSON.stringify(redactSecrets(fullEvent))}\n`, "utf-8");
+const fd = fs.openSync(eventsPath, "r+");
+fs.fsyncSync(fd); ...
+persistSequence(eventsPath, seq);   // full atomicWriteFile của .seq mỗi event
+```
+- **Đã fix một phần (v0.9.17)**: `appendEventBuffered` giờ đã có call site — `task.progress` trong
+  `task-runner.ts:395` và `team-runner.ts:1054` đi qua buffered path (coalesce 20ms, 1 lock acquire).
+  Bench trong code comment: p95 producer giảm từ ~13µs → ~0µs. Tuy nhiên:
+  - Các event terminal/vài event khác vẫn đi `appendEvent`/`appendEventAsync` → per-event fsync + `.seq` sidecar.
+  - `persistSequence` vẫn ghi sidecar per event (trong batch, gọi tuần tự trong lock nhưng mỗi event 1 lần).
+- **Fix đề xuất còn lại**: chỉ fsync cho terminal events (`TERMINAL_EVENT_TYPES`); persist `.seq` theo batch
+  hoặc mỗi N events (recovery scan đã tự sửa được khi sidecar tụt hậu); mở rộng `appendEventBuffered`
+  cho thêm các event loại informational (`task.checkpoint`, `worker.lifecycle`, ...).
+
+#### F4 — HIGH → REGRESSED (v0.9.17): tasks.json ghi lại toàn bộ, pretty-printed, mỗi thay đổi + fsync data+dir
+- `state-store.ts:365-377` → `atomicWriteJson` dùng `JSON.stringify(value, null, 2)` (`atomic-write.ts:523`).
+- Task graph chứa attempts, verification, usage, diagnostics per task → file lớn dần trong run dài; stringify + write cost tỉ lệ O(tổng state) cho MỖI thay đổi 1 field.
+- **REGRESSED (v0.9.17, commit `13f4490`)**: `atomicWriteFile` giờ thêm `fs.fsyncSync(fd)` trên data file
+  (`atomic-write.ts:384`) **và** `fs.fsyncSync(dirFd)` trên parent directory (`:410`, POSIX only).
+  Mỗi `atomicWriteJson` call = write + fsync(data) + fsync(dir) + rename. Comment trong code ước lượng
+  "~1ms per write" nhưng thực tế trên Windows fsync đắt hơn nhiều; CI timeout đã phải bump 600s→900s
+  chính vì overhead này (`9bbeb45`). `persistSingleTaskUpdate` (F2) gọi `saveRunTasks` ~5 lần mỗi task,
+  mỗi lần giờ tốn thêm 2× fsync.
+- `saveRunTasksCoalesced` (50ms debounce) đã có tại `state-store.ts:428` nhưng **vẫn 0 call site** (v0.9.17 xác nhận).
+- **Fix đề xuất**: bỏ pretty-print cho tasks.json (giữ cho manifest nếu cần đọc tay), wire `saveRunTasksCoalesced`
+  vào checkpoint path (checkpoint là informational, mất 50ms cuối khi crash chấp nhận được vì đã có crash-recovery);
+  cân nhắc fsync chỉ trên terminal write (manifest final), không phải mỗi checkpoint.
+
+#### F5 — MEDIUM: `isSymlinkSafePath` walk toàn bộ ancestor chain, chạy 2 lần mỗi atomic write
+- `atomic-write.ts:43-56, 287, 359-361`: mỗi write = 2 × (lstatSync per path level đến root). Với path sâu điển hình `.crew/state/runs/{runId}/` là ~10+ lstat × 2 mỗi write, nhân với mọi finding ở trên.
+- `withFileLockSync` còn gọi lại check này MỖI vòng retry (`locks.ts:319`).
+- **Fix đề xuất**: cache kết quả validate theo (dirname, generation) trong process — thư mục cha của state root không đổi trong suốt run; chỉ re-validate khi ghi vào path mới.
+
+#### F6 — HIGH → REGRESSED (v0.9.17): Mailbox — mỗi message = 2 lock + full rewrite delivery.json + lstat chain × 3 + fsync data+dir
+- `src/state/mailbox.ts:380-430`: `mailboxFile(...)` tính lại 3 lần (mỗi lần re-run lstat validation), `writeDeliveryState` (`:353`) sort đến 10k entries + atomic rewrite toàn bộ pretty-printed delivery.json cho MỖI message.
+- **REGRESSED (v0.9.17)**: `atomicWriteFile` giờ fsync data + parent dir (commit `13f4490`), nên mỗi delivery.json rewrite tốn thêm 2× fsync. CI flake mailbox-replay chính là lý do commit này tồn tại, nhưng代价 là mọi write path đều nặng hơn.
+- Reads: `safeReadMailboxFile` (`:246`) readdirSync tìm archive MỖI lần đọc; `readAllMessages` (`:321`) O(tasks × dir entries); `updateMailboxMessageReply` (`:463`) quét mọi mailbox file, mỗi file full read + full rewrite.
+- **Fix đề xuất**: delivery state chuyển sang append-only JSONL + compaction (giống events), hoặc ít nhất coalesce write; cache danh sách archive theo mtime của dir; chỉ fsync khi reply/terminal, không phải mỗi informational message.
+
+#### F7 — MEDIUM/HIGH: active-run-registry O(N runs) full manifest parse mỗi register/unregister
+- `active-run-registry.ts:249-344`: `filterAliveEntries` đọc + parse manifest.json của từng run, 2× existsSync + 2× symlink walk + `process.kill(pid,0)` per entry; `registerActiveRun` gọi 2 lần; `unregisterActiveRun` chạy trên MỖI terminal transition (`state-store.ts:508`). Registry còn ghi 2 định dạng (JSON + binary mirror) = 4 temp-file ops mỗi update (`:183`).
+- **Fix đề xuất**: liveness chỉ cần pid probe + heartbeat stat, không cần parse manifest; bỏ dual-format write nếu binary mirror không còn consumer.
+
+### 2.2 Runtime / process layer
+
+#### F8 — HIGH: Worktree prep = 5-6 git subprocess `execFileSync` tuần tự + full checkout, chặn event loop
+- `src/worktree/worktree-manager.ts:1,30,331-425`: mỗi task cần worktree chạy lần lượt `rev-parse --show-toplevel`, `status --porcelain` trên leader repo (O(repo size)), `worktree list --porcelain`, `worktree prune`, `rev-parse --verify`, `worktree add -b ... HEAD`. Tất cả `execFileSync` → dù tasks chạy "song song" qua `mapConcurrent`, phần chuẩn bị worktree bị serialize và chặn toàn bộ extension host (UI đơ theo).
+- Reuse path vẫn tốn `worktree list` + `status` + leader `status` lần 2. Cleanup gọi lại `findGitRoot` 3 lần (tới 6 git spawn).
+- **v0.9.17 note**: M6 coalesce (`coalesceMicroTasks`) giảm số spawn cho workflow có nhiều task nhỏ read-only (3 task → 1 child + 1 worktree), nhưng bản thân worktree prep vẫn sync. Khi M6 mở rộng sang mutating roles, vấn đề sẽ tái xuất.
+- **Fix đề xuất**: (a) chuyển sang `execFile` async (promisify) — thay đổi cục bộ, tác động lớn nhất; (b) cache `findGitRoot`/`assertCleanLeader` per (repo, batch) — leader status chỉ cần check 1 lần mỗi batch chứ không phải mỗi task; (c) cân nhắc `git worktree add --no-checkout` + sparse checkout cho task chỉ đọc một phần repo.
+
+#### F9 — HIGH: `ChildPiLineObserver` giữ mảng không giới hạn trong suốt run
+- `child-pi.ts` (~:528): `rawTextEvents` push mọi fragment assistant-text KHÔNG cap ("RAW (uncapped)"), chỉ dùng entry cuối qua `getRawFinalText()`. `intermediateFindings` cũng push-only, chỉ trim khi đọc (`slice(-20)`).
+- Run dài + worker nói nhiều = memory tăng tuyến tính theo output, nhân với số worker song song.
+- **Fix đề xuất**: giữ tối đa N entry cuối ngay khi push (ring buffer), vì consumer chỉ cần tail.
+
+#### F10 — MEDIUM: Double JSON.parse mỗi dòng stdout + sync transcript write per line
+- Mỗi JSON line từ child bị parse 2 lần (`emitLine` → `extractText` và `compactChildPiLine`).
+- `appendTranscript` (`child-pi.ts:387-414`): mỗi dòng = realpath validation + openSync/writeSync/closeSync. Nên parse 1 lần rồi truyền object; giữ fd mở per-task (mở 1 lần, đóng khi task kết thúc) và validate path 1 lần.
+
+#### F11 — MEDIUM: `appendBoundedTail` rebuild chuỗi O(cap) mỗi dòng
+- `child-pi.ts:53, 927, 1121`: `current + chunk` rồi slice với cap 512KiB → copy ~512KB mỗi dòng khi buffer đầy. Fix: array-of-chunks + tổng byte, chỉ join khi đọc.
+
+#### F12 — MEDIUM: Latency floor 5s mỗi task thành công (final-drain)
+- `finalDrainMs = 5000` (`defaults.ts:13`): sau final assistant event, chờ 5s rồi mới SIGTERM child. Workflow 5 task tuần tự cộng thêm ~25s chết. Fix: khi đã nhận `message_end` + stopReason=stop, rút xuống 1-1.5s, hoặc drain kết thúc sớm khi stdout im lặng >300ms.
+
+#### F13 — MEDIUM: Interrupt guard poll 250ms sync fs suốt đời background run
+- `background-runner.ts:144`: existsSync + readFileSync + JSON.parse foreground-control.json mỗi 250ms, per background run (4 Hz × N runs). Fix: `fs.watch` file cha + fallback poll thưa (2s), hoặc chỉ stat mtime trước khi read.
+
+#### F14 — MEDIUM: Temp-reconcile parse cùng manifest tới 4 lần mỗi tick
+- `stale-reconciler.ts:516-700`: tick 5 phút, batch 50 dirs, nhưng mỗi dir parse manifest.json + tasks.json rồi re-scan thêm tối đa 3 pass cho TOCTOU check. Fix: đọc 1 lần, truyền parsed object qua các pass, chỉ re-stat mtime để phát hiện thay đổi.
+
+#### F15 — MEDIUM: Discovery cache TTL 500ms gần như vô dụng ở steady state
+- `discover-agents.ts:453`: TTL 500ms → scheduler loop re-scan 4 thư mục (readdir + readFile + ~12 regex pass sanitize mỗi file .md) ~2 lần/giây. `discoverTeams`/`discoverWorkflows` **không có cache nào**.
+- **Fix đề xuất**: nâng TTL lên 5-10s kèm invalidation theo mtime của các dir gốc (stat dir rẻ hơn nhiều so với scan), dùng chung 1 cache module cho cả agents/teams/workflows.
+
+### 2.3 Extension / UI layer
+
+#### F16 — HIGH: `loadConfig()` không có cache, bị gọi trên mọi hot path
+- `config/config.ts:1358-1425`: mỗi lần gọi = tới 4 file (legacy, user, `.crew/config.json`, `.pi/pi-crew.json`) × (existsSync + statSync + readFileSync + JSON.parse với reviver) + full TypeBox `Value.Check` + nhiều pass sanitize/merge.
+- Caller trên hot path:
+  - Preload tick: `register.ts:1684` — 1 Hz idle, ~6 Hz khi có run active
+  - **Mỗi write/edit tool_result**: `register.ts:2088` (`perWriteValidation` check)
+  - Mỗi subagent completion (`register.ts:265`), mỗi notification
+- **Fix đề xuất (quick win lớn nhất)**: cache mtime+TTL giống pattern `manifest-cache.ts` đã có sẵn trong repo. Stat 4 file (~4 syscall) thay vì parse + validate lại. Ước lượng loại bỏ hàng nghìn parse/validate mỗi phiên.
+
+#### F17 — HIGH: Powerbar re-scan toàn bộ workflows tới ~5 lần/giây khi run active
+- `ui/powerbar-publisher.ts:215`:
+```ts
+const workflows = allWorkflows(discoverWorkflows(run.cwd));
+```
+- Chạy trong `updatePiCrewPowerbar` (coalesce 200ms). `discoverWorkflows` = 2× readdirSync × 3 roots + readFileSync + regex-parse mọi `.workflow.md`, không cache. Fix: TTL cache 5-10s như F15, hoặc chỉ resolve workflow 1 lần khi run bắt đầu (workflow của run không đổi giữa chừng).
+
+#### F18 — MEDIUM: Preload loop không bao giờ nghỉ khi idle
+- `register.ts:1727-1741`: tick 1 Hz kể cả khi 0 run, mỗi tick gọi `loadConfig` (F16) + `manifestCache.list(20)` (list-cache TTL chỉ 500ms tại `manifest-cache.ts:36` → readdirSync + statSync per manifest gần như mỗi tick). Fix: khi N tick liên tiếp không có run active và không có event bus activity, giãn xuống 5-10s hoặc dừng hẳn, đánh thức bằng event-bus/`run` action.
+
+#### F19 — MEDIUM: `mailboxStamp` O(N task dirs) statSync mỗi lần check stale
+- `run-snapshot-cache.ts:110-129`: mỗi refresh check = readdirSync(mailbox/tasks) + 2 statSync per task dir, sync trên UI path. Code đã từng bỏ per-agent output stamp vì lý do này (comment `:604-608`) nhưng mailbox stamp còn giữ pattern cũ. Fix: 1 stamp file tổng do writer touch, hoặc dựa vào event-bus invalidation (đã có) và bỏ stamp mailbox.
+
+#### F20 — LOW/MEDIUM: `delivery.json` parse 2 lần, `outbox.jsonl` tail-read 2 lần mỗi snapshot rebuild
+- `run-snapshot-cache.ts:484, 507`. Fix: đọc 1 lần, chia sẻ kết quả giữa `mailboxFrom` và `groupJoinsFrom`.
+
+#### F21 — MEDIUM: `async-notifier` full `readEvents` mỗi 5s cho run nghi ngờ chết
+- `async-notifier.ts:74`: `markDeadAsyncRunIfNeeded` đọc + parse toàn bộ events.jsonl (tới 50MB). Fix: dùng `readEventsCursor` với byte offset lưu lại, hoặc chỉ cần tail vài KB cuối để tìm terminal event.
+
+---
+
+## 3. Kế hoạch tối ưu đề xuất (ưu tiên theo tác động / rủi ro)
+
+### Đợt 1 — Quick wins (thay đổi cục bộ, rủi ro thấp, tác động lớn)
+
+| # | Việc | File | Tác động |
+|---|---|---|---|
+| 1 | Cache `loadConfig` theo mtime+TTL (2s) | config.ts | Loại bỏ nguồn CPU lặp lại lớn nhất ở extension layer (F16) |
+| 2 | Generation counter per-stateRoot | state-store.ts | Khôi phục hit-rate manifest cache khi run active (F1) |
+| 3 | TTL cache cho `discoverWorkflows`/`discoverTeams`, nâng TTL agents lên 5-10s + mtime dir check | discover-*.ts | Diệt 5 Hz scan của powerbar (F17) + steady-state scan (F15) |
+| 4 | Bỏ pretty-print cho tasks.json | atomic-write.ts caller | Giảm ~40-60% byte ghi mỗi update (F4) |
+| 5 | Ring-buffer cho `rawTextEvents`/`intermediateFindings` | child-pi.ts | Chặn memory growth run dài (F9) |
+| 6 | Giảm `finalDrainMs` 5000 → 1500 (config đã có sẵn override) | defaults.ts | Bớt 3.5s/task latency (F12) |
+| 7 | Đọc delivery.json/outbox 1 lần mỗi snapshot rebuild | run-snapshot-cache.ts | (F20) |
+
+### Đợt 2 — Batching và giảm fsync (cần chạy lại integration tests)
+
+| # | Việc | Tác động |
+|---|---|---|
+| 8 | Wire `appendEventBuffered` cho event không-terminal; fsync chỉ terminal events; persist `.seq` mỗi N events | Giảm mạnh syscall/fsync per event (F3), hạ tầng đã viết sẵn |
+| 9 | Wire `saveRunTasksCoalesced` vào checkpoint path của task-runner | Gộp burst checkpoint writes (F4) |
+| 10 | Đơn giản hóa `persistSingleTaskUpdate`: bỏ mtime-CAS khi đã cầm run lock, chuyển async | Bỏ 3× statSync + retry loop 100 vòng (F2) |
+| 11 | Cache kết quả `isSymlinkSafePath` theo dirname trong process | Bỏ 2× ancestor lstat walk mỗi write (F5) |
+| 12 | Idle backoff cho preload loop + nâng list-cache TTL khi idle | (F18) |
+
+### Đợt 3 — Cấu trúc (cần thiết kế, test kỹ)
+
+| # | Việc | Tác động |
+|---|---|---|
+| 13 | Chuyển worktree-manager sang async `execFile`, cache leader-status per batch | Hết chặn event loop khi fanout, worktree prep song song thật (F8) |
+| 14 | Mailbox delivery-state append-only + compaction; archive-list cache | (F6) |
+| 15 | Registry liveness không cần parse manifest; bỏ dual-format write | (F7) |
+| 16 | In-memory task state per active run (write-through), disk chỉ là bản persist | Về lâu dài loại bỏ read-modify-write cycle hoàn toàn (F1/F2/F4) |
+| 17 | `readEvents` mặc định đi qua cursor/tail; notifier dùng offset | (F21, F6 read path) |
+
+### Cách đo và nghiệm thu
+
+- Repo đã có `src/benchmark/` — thêm micro-bench cho: `loadConfig` (trước/sau cache), `persistSingleTaskUpdate` (thời gian/syscall mỗi checkpoint), `appendEvent` throughput (events/s), worktree prep wall-time với N task song song.
+- Đo end-to-end: `time` của 1 run `fast-fix` scaffold-mode (loại bỏ nhiễu model) trước/sau từng đợt.
+- Windows là môi trường nhạy nhất (fsync, spawn, stat đều đắt hơn) — benchmark trên Windows trước.
+- Sau mỗi đợt: `npm run typecheck` + `npm test` + `npm run check:lazy-imports`.
+
+### Ước lượng tác động tổng
+
+- Đợt 1: giảm rõ CPU nền khi idle (config parse 1 Hz → 0), powerbar scan (5 Hz → ~0), latency mỗi task -3.5s, memory ổn định cho run dài.
+- Đợt 2: giảm 5-10× số syscall/fsync trên đường ghi state trong run active (mỗi task hiện tốn ~5 checkpoint × [lock + 2 read + 3 stat + full rewrite] + ~10-20 event × [fsync + sidecar write]).
+- Đợt 3: hết hiện tượng UI đơ khi fanout worktree trên repo lớn; state layer scale theo số run/task.
+
+---
+
+## 4. Ghi chú không phải hiệu năng (quan sát thêm)
+
+- `PluginRegistry` builtin trong team-runner.ts được register nhưng chưa có integration point (chính comment trong code thừa nhận) — dead weight nhỏ.
+- Nhiều file lớn >1500 dòng (register.ts 79KB, team-runner.ts 69KB) — không phải vấn đề runtime nhưng làm chậm typecheck/test và khó review; đã có xu hướng tách (`team-tool/*.ts`), nên tiếp tục.
+- Sync lock với `sleepSync` (locks.ts:244, event-log.ts:143) chặn event loop khi contention — Đợt 2/3 nên ưu tiên các async variant đã có sẵn.
+
+---
+
+## 5. Delta v0.9.17 — những gì đã fix và regressed
+
+> 40 commits pulled (`1418fa7..22a8e72`), ~20k dòng thay đổi trong `src/`.
+> Re-verify từng phát hiện trên code mới. Bảng tổng hợp:
+
+### 5.1 Đã cải thiện (positive)
+
+| Commit | Thay đổi | Tác động hiệu năng |
+|---|---|---|
+| `task-runner.ts:395`, `team-runner.ts:1054` | `appendEventBuffered` wired cho `task.progress` | **F3 partial fix** — event tần suất cao nhất giờ coalesce 20ms, 1 lock acquire. p95 producer ~0µs (bench trong comment). Terminal events vẫn per-fsync. |
+| `21ac434` M6 coalesce micro-tasks | `coalesceMicroTasks` workflow flag + `coalesce-tasks.ts` | Giảm số child process spawn khi workflow có nhiều task nhỏ read-only (3 task → 1 spawn). Trực tiếp giảm F8/F9/F12 cho workload phù hợp. |
+| `0543966` M5 serialize on write-path overlap | `path-overlap.ts` | Tránh conflict khi 2 task song song ghi cùng file. Không phải tối ưu tốc độ nhưng giảm retry/conflict overhead. |
+| `48aae01` L4 trim dependency output | `task-output-context.ts` + `MAX_TOTAL_DEP_INLINE_BYTES` | Giảm context size truyền cho child → giảm prompt build cost + model input tokens. |
+| `8a68825`+`06f16d7` Bundle as default entry | `dist/index.mjs` 2.9MB, esbuild | **Cold-start −31.6%** (2509ms → 1717ms p50, bench `scripts/bench-cold-start.mjs`). Tác động lớn nhất đến latency khởi động. |
+| `5281074` Split register.ts | `registration/{lifecycle,observability,ui}.ts` + LAZY markers | Giảm module-graph warmup cost; lazy import boundary rõ hơn. |
+| `cbaa572` Drop withRunLock from catch path | `team-runner.ts` | Sửa closeout lock race (run.completed rồi run.failed 500ms sau). Không phải perf nhưng sửa 1 nguồn spurious failed run → giảm retry waste. |
+
+### 5.2 Đã regressed (negative)
+
+| Commit | Thay đổi | Tác động |
+|---|---|---|
+| `13f4490` fsync data + parent dir | `atomic-write.ts:384,410` | **F4 + F6 regressed** — mỗi `atomicWriteFile` giờ thêm `fs.fsyncSync(fd)` + `fs.fsyncSync(dirFd)` (POSIX). CI timeout phải bump 600s→900s (`9bbeb45`). `persistSingleTaskUpdate` gọi ~5 lần mỗi task × 2 fsync = +10 fsync/task. Trên Windows fsync đặc biệt đắt. |
+| `test:integration` timeout 120s→300s | `22a8e72` | Phản ánh tổng overhead tăng do fsync + bundle + M6. |
+
+### 5.3 Không đổi (xác nhận vẫn còn trên v0.9.17)
+
+| Finding | Trạng thái | Bằng chứng |
+|---|---|---|
+| F1 — global generation counter | **Vẫn còn** | `state-store.ts:132` `manifestCacheGeneration++` |
+| F2 — persistSingleTaskUpdate 100-iteration sync CAS | **Vẫn còn** | `state-helpers.ts:57` `attempt < 100` |
+| F4 — saveRunTasksCoalesced 0 caller | **Vẫn còn** | grep toàn src, chỉ definition tại `state-store.ts:428` |
+| F5 — isSymlinkSafePath ancestor walk ×2 | **Vẫn còn** | `atomic-write.ts` không đổi logic validate |
+| F8 — worktree execFileSync | **Vẫn còn** | `worktree-manager.ts:1,33` — `execFileSync` unchanged |
+| F9 — rawTextEvents unbounded | **Vẫn còn** | `child-pi.ts:600` `private readonly rawTextEvents: string[] = []` |
+| F12 — finalDrainMs 5000 | **Vẫn còn** | `defaults.ts:13` `finalDrainMs: 5000` |
+| F15 — discovery cache TTL 500ms | **Vẫn còn** | `discover-agents.ts:493` `DISCOVERY_CACHE_TTL_MS = 500` |
+| F16 — loadConfig không cache | **Vẫn còn** | `config.ts` không có configCache (grep confirmed) |
+| F17 — discoverWorkflows không cache, gọi ~5Hz | **Vẫn còn** | `powerbar-publisher.ts:284` `discoverWorkflows(run.cwd)` — không cache trong discover-workflows.ts (grep confirmed) |
+| F21 — async-notifier full readEvents | **Vẫn còn** | `async-notifier.ts:90` `readEvents(run.eventsPath)` |
+
+### 5.4 Khuyến nghị cập nhật cho Đợt 1
+
+Sau v0.9.17, thứ tự ưu tiên Đợt 1 cần điều chỉnh:
+
+1. **F4 fsync mitigation** (NEW urgent): thêm tham số `durability: "full" | "best-effort"` cho `atomicWriteJson`.
+   Checkpoint/informational writes dùng `best-effort` (bỏ fsync data+dir, chỉ rename). Terminal/manifest writes giữ `full`.
+   Đây là fix nhanh nhất cho regression `13f4490` mà không mất durability cho data quan trọng.
+2. **F16 loadConfig cache** (giữ #1): vẫn là quick win lớn nhất, không bị ảnh hưởng bởi pull.
+3. **F1 generation per-stateRoot** (giữ #2): không đổi.
+4. **F3 expand buffered events** (nâng hạng): đã có hạ tầng, chỉ cần mở rộng cho thêm event types.
+5. Các mục #3-#7 còn lại trong Đợt 1 không đổi.
+
+### 5.5 Ghi chú thêm
+
+- `atomic-write-v2.ts` đã xuất hiện (file mới, `fs.fsyncSync` tại `:30`) nhưng grep `atomic-write-v2` trên toàn `src/` trả về **0 import** — có vẻ là work-in-progress hoặc dead code. Cần xác minh xem có plan migrate không.
+- Bundle entry (`dist/index.mjs`) là default từ v0.9.17. Nếu `dist/` không tồn tại (dev clone), fallback sang strip-types. Bundle giảm cold-start nhưng **không ảnh hưởng** đến các hot-path I/O findings trong review này.
+- `coalesceMicroTasks` (M6) hiện MVP, chỉ hoạt động cho `READ_ONLY` roles. Khi mở rộng sang mutating roles, cần chú ý F8 (worktree prep cho coalesced group vẫn sync).

package/docs/skills/REFERENCE.md

@@ -62,14 +62,8 @@ verification-before-done (per round)
 | Task delegation | `delegation-patterns` |
 | Complex multi-phase work | `orchestration` |
 | After bug is fixed | `post-mortem` |
-| Security review | `security-review` |
 | Workspace safety | `workspace-isolation` |
 | Bash safety | `safe-bash` |
-| Hypothesis-driven investigation | `threat-hypothesis-framework` |
-| Active threat hunting | `hunting-investigation-loop` |
-| Artifact examination | `artifact-analysis-loop` |
-| Building response procedures | `incident-playbook-construction` |
-| Designing detection pipelines | `detection-pipeline-design` |
 
 ---
 
@@ -83,17 +77,6 @@ verification-before-done (per round)
 | `verification-before-done` | Evidence before claims |
 | `orchestration` | Multi-phase coordination, 8 rules including "respawn not absorb" |
 
-### Security
-
-| Skill | Description |
-|-------|-------------|
-| `security-review` | Security review with audit and detection authoring |
-| `threat-hypothesis-framework` | Hypothesis-driven investigation |
-| `hunting-investigation-loop` | Active threat hunting with validation |
-| `artifact-analysis-loop` | Artifact analysis with IOC extraction |
-| `incident-playbook-construction` | Playbook building with steps, decisions, SLAs |
-| `detection-pipeline-design` | Data pipeline design for security monitoring |
-
 ### Documentation
 
 | Skill | Description |