@kienntpixon/dieu-phoi 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog — @kienntpixon/dieu-phoi
 
+## 0.6.1 (2026-10-22)
+
+`CORE_VERSION` 0.6.1; đi cùng skill 1.5.1. codebase-memory-mcp là **khuyến nghị, không bắt buộc** (nhánh `cbm-support`, task 7s6mouxg). `sheet/` không đổi, không cần deploy lại `Code.gs`.
+
+- **`doctor` kiểm codebase-memory-mcp** (module mới `lib/cbm.cjs`; mọi mục tối đa CẢNH BÁO, không bao giờ LỖI):
+  `codebase-memory` — binary (đăng ký MCP → PATH → `~/.local/bin`, `%LOCALAPPDATA%/Programs/codebase-memory-mcp`), `--version`,
+  đăng ký MCP trong Claude Code (user/local trong `.claude.json` — `$CLAUDE_CONFIG_DIR/.claude.json` hoặc `~/.claude.json` —
+  và project `.mcp.json`); thiếu → lệnh cài `dieu-phoi setup --with-codebase-memory`, chưa đăng ký → lệnh `claude mcp add --scope user`.
+  `cbm-version` (chỉ `--net`, GitHub API, timeout 6 s) so với bản mới nhất. `cbm-daemon` đọc `daemon status` (~3 s, timeout 5 s,
+  chạy song song với các kiểm khác): daemon khác version đang chạy → cảnh báo kèm pid các phiên giữ nó và cách xử lý.
+  `cbm-index` — repo cwd/`--repo` đã index chưa, đọc thư mục cache (`$CBM_CACHE_DIR` hoặc `~/.cache/codebase-memory-mcp/<project>.db`,
+  so tên lỏng), không spawn `cli list_projects` (~13 s, và lỗi khi daemon lệch version); worktree chưa index thì báo repo chính.
+- **`setup --with-codebase-memory [--force] [--cbm-dir D]`** (tuỳ chọn, không mặc định): tải `checksums.txt` + asset của
+  `DeusData/codebase-memory-mcp` `releases/latest` (windows-amd64/arm64 `.zip`, darwin `.tar.gz`, linux `-portable.tar.gz`),
+  kiểm sha256 (lệch → không cài gì), giải nén bằng `tar` (Windows: `System32\tar.exe`), chạy thử `--version`, cài binary và đăng ký
+  MCP user scope bằng `claude mcp add --scope user codebase-memory-mcp -- <binary>` (không có `claude` → in lệnh để tự chạy).
+  Đã có binary/đăng ký → giữ nguyên trừ khi `--force`; bản cũ đổi tên `<binary>.bak-dieu-phoi-<thời gian>` (đổi tên được cả khi exe
+  đang chạy trên Windows), copy lỗi thì khôi phục. Cài lỗi → exit 1 nhưng phần setup dieu-phoi vẫn xong.
+- Agent `dp-exec/dp-scout/dp-verify/dp-helper`: MCP lỗi kết nối/không phản hồi/daemon khác version → Grep/Glob ngay, ghi một dòng
+  `codebase-memory: unavailable (<lý do>)`, không thử lại (chạy lại `dieu-phoi setup` để cập nhật file agent).
+- **Sửa theo review (task 0kgiz68m)**:
+  - `doctor` thường trở lại ~0,5 s: `daemon status` (~2,7 s) chỉ chạy với `--cbm` hoặc `--net`; không có cờ thì dùng kết quả nhớ
+    10 phút (`data/cbm-daemon.json`, khoá theo đường dẫn + version binary, không lưu timeout) hoặc ghi "chưa kiểm — `doctor --cbm`".
+  - `DIEU_PHOI_CBM_BASE_URL` khác nguồn chính thức → từ chối kèm cảnh báo (sha256 lấy cùng nguồn nên không còn bảo đảm), trừ khi có
+    cờ mới `--allow-custom-source` (khi đó vẫn ghi CẢNH BÁO vào ghi chú).
+  - `--force`: nhớ đăng ký cũ (command/args/env) trước `claude mcp remove`; `mcp add` lỗi → đăng ký lại bản cũ (`mcp: restored`);
+    khôi phục cũng lỗi → ghi tên, command, tên biến env (không bao giờ in giá trị) để tự thêm lại.
+  - `doctor --net`: timeout kiểm sink 8 s → 20 s (Apps Script đo thực 8,3–14,6 s; có từ trước, không do nhánh này). Hết giờ = "chậm/không
+    xác định" (CẢNH BÁO, `sink-check.json` có `timeout: true`, không tính là lỗi cứng ở `doctor`/`start`/hook; `doctor` thường không đợi lại 20 s
+    trong 1 giờ). Lỗi kết nối/HTTP thật vẫn là lỗi cứng như cũ.
+- Test mới `test/cbm.test.cjs` (21 ca, không gọi mạng: download/extract/`claude` mock, binary giả `.cjs`, server HTTP cục bộ cho
+  `--net`). `_fixtures.cjs` đặt `DIEU_PHOI_CBM_BIN=none` + `CBM_CACHE_DIR` tạm để doctor trong test không chạm binary/cache thật.
+
 ## 0.6.0 (2026-10-22)
 
 `CORE_VERSION` 0.6.0; đi cùng skill 1.5.0. Gộp nhánh `s5-parallel-safety` và `knowledge` (kế hoạch 464k2t30). `sheet/` không đổi, không cần deploy lại `Code.gs`.

package/README.md

@@ -33,14 +33,23 @@ Không cài toàn cục được thì dùng `npx -y @kienntpixon/dieu-phoi <lệ
 
 Khởi động lại Claude Code sau khi cài. Kiểm tra bằng `dieu-phoi doctor` (chạy thử chính lệnh hook đã đăng ký).
 
+**codebase-memory-mcp (khuyến nghị, không bắt buộc).** `setup --with-codebase-memory` (không mặc định) tải bản phát hành
+chính thức từ GitHub `DeusData/codebase-memory-mcp` (`releases/latest`), kiểm sha256 với `checksums.txt`, chạy thử
+`--version`, cài binary (Windows `%LOCALAPPDATA%\Programs\codebase-memory-mcp\`, macOS/Linux `~/.local/bin/`, hoặc
+`--cbm-dir`) và đăng ký MCP ở user scope bằng `claude mcp add --scope user codebase-memory-mcp -- <binary>` (không có
+lệnh `claude` thì in lệnh để tự chạy). Đã có binary/đăng ký → giữ nguyên; `--force` cài lại, bản cũ đổi tên
+`<binary>.bak-dieu-phoi-<thời gian>`. `doctor` thêm các mục `codebase-memory`, `cbm-version` (chỉ với `--net`),
+`cbm-daemon`, `cbm-index` — tất cả tối đa là CẢNH BÁO; `daemon status` mất ~3 s (timeout 5 s, chạy song song với kiểm
+khác).
+
 `CLAUDE_CONFIG_DIR` được tôn trọng (thay cho `~/.claude`). Thử trên thư mục tạm: thêm `--claude-dir <thư mục>` vào mọi lệnh.
 
 ## Lệnh
 
 | Lệnh | Việc |
 |---|---|
-| `setup [--dept D] [--sink-url U --sink-token T] [--skill-dir P]` | cài hook, đăng ký `PostToolUse(Agent)` + `SubagentStop` + `SessionStart(compact)` + `UserPromptSubmit` trong settings, ghi config; tạo thư mục báo cáo `~/.dieu-phoi/runs` (env `DIEU_PHOI_RUNS_DIR` để đổi; ngoài `~/.claude` vì đó là protected path) và thêm quyền `Read`/`Edit(~/.dieu-phoi/runs/**)` + `additionalDirectories` để subagent nền ghi được báo cáo (không nhân đôi, có sao lưu); gỡ luật cũ của bản dev cho `~/.claude/dieu-phoi/runs` |
-| `doctor [--net] [--json]` | kiểm node, hook, settings (+ `prompt-hook`), config, profile, sink (từ bộ nhớ đệm 24 giờ; `--net` kiểm trực tiếp); context phiên điều phối hiện tại nếu đo được (`orch-ctx`); thư mục `~/.dieu-phoi/runs` + quyền của nó, không còn luật cũ (`run-permissions`); `--json` có `runs_dir` |
+| `setup [--dept D] [--sink-url U --sink-token T] [--skill-dir P] [--with-codebase-memory [--force] [--cbm-dir D]]` | (`--with-codebase-memory`: cài + đăng ký codebase-memory-mcp, xem mục Cài đặt)  cài hook, đăng ký `PostToolUse(Agent)` + `SubagentStop` + `SessionStart(compact)` + `UserPromptSubmit` trong settings, ghi config; tạo thư mục báo cáo `~/.dieu-phoi/runs` (env `DIEU_PHOI_RUNS_DIR` để đổi; ngoài `~/.claude` vì đó là protected path) và thêm quyền `Read`/`Edit(~/.dieu-phoi/runs/**)` + `additionalDirectories` để subagent nền ghi được báo cáo (không nhân đôi, có sao lưu); gỡ luật cũ của bản dev cho `~/.claude/dieu-phoi/runs` |
+| `doctor [--net] [--repo P] [--json]` | kiểm codebase-memory-mcp (khuyến nghị: cài, MCP, daemon khác version, index của repo; `--net` so bản mới nhất), node, hook, settings (+ `prompt-hook`), config, profile, sink (từ bộ nhớ đệm 24 giờ; `--net` kiểm trực tiếp); context phiên điều phối hiện tại nếu đo được (`orch-ctx`); thư mục `~/.dieu-phoi/runs` + quyền của nó, không còn luật cũ (`run-permissions`); `--json` có `runs_dir` |
 | `verdict <agent_id\|last> <pass\|fail\|timeout\|aborted> [--verify tests\|lint\|review\|judgment\|none] [--reason short-kebab]` | nghiệm thu tầng agent (`by=agent`). `aborted` (0.4.0) = dừng vì usage limit/quota: không pass/fail, không leo thang; hook tự ghi khi bắt được. `last` = agent hoàn thành gần nhất; từ chối (liệt kê ứng viên) nếu trong 30 phút qua có > 1 agent xong mà chưa có verdict. Được viết tắt agent_id nếu không trùng |
 | `verdict --task <task_id> <accept\|reject> [--cause quality\|scope] [--round n] [--reason R]` | nghiệm thu của **người dùng** (`by=user`). `reject` bắt buộc `--cause`: `quality` = làm sai (tính là fail), `scope` = yêu cầu đổi/thiếu (không tính cho model). `--round` mặc định tự tăng |
 | `verdict --root <root_task_id> accept [--steps a,b]` | (0.4.0) người dùng nhận một lúc mọi bước đã giao exec của kế hoạch đã duyệt mà chưa có verdict người dùng. (0.6.0) `accept` tự gộp knowledge: `--task T` gộp `knowledge-delta-T*.md` của run gốc; `--root R` gộp delta của R + các bước vừa accept + file không mang task_id. Xung đột/từ chối không đổi verdict (exit 0): output in `XUNG ĐỘT` + lệnh `knowledge merge` để chạy lại. `--root` mà mọi bước đã có verdict người dùng: vẫn gộp delta của R + file không thẻ, exit theo kết quả gộp (không có delta nào → lỗi "không có bước nào cần nghiệm thu"). `reject` không gộp; `--no-knowledge` bỏ qua |

package/agents/dp-exec.md

@@ -28,7 +28,7 @@ Bạn là agent thực thi (exec) của dieu-phoi. Brief ở tin nhắn đầu (
 
 Bàn giao qua file: ghi TOÀN BỘ kết quả vào `dp-out-<task_id>-exec-try<n>.md` trong run dir (đường dẫn brief chỉ định), rồi chỉ trả: đường dẫn file đó, dòng `STATUS:`, và ≤ 3 dòng ý chính. Không đặt tên file `report*` / `summary*` / `findings*` / `analysis*.md` — Claude Code chặn cứng Write các tên đó trong subagent. File dp-out/handoff mà brief trỏ tới là báo cáo chính thức: đọc thẳng, không cần xin thêm quyền.
 
-Repo đích và knowledge: dòng `repo:` của brief là repo ĐÍCH (có thể là repo con, khác cwd). Trước khi đọc code: `dieu-phoi knowledge list --repo <repo>` rồi `knowledge get <id|từ khoá> --repo <repo>` (ít nhất `build-test ports-resources` nếu có); mục STALE chỉ là gợi ý. Cấu trúc code: dùng codebase-memory-mcp khi repo đã có index (`list_projects`), không thì Grep/Glob — không tự index. Brief có `worktree:` → chỉ sửa và chạy lệnh trong worktree đó, dùng cổng/tài nguyên riêng brief ghi, chỉ kill tiến trình do chính mình mở. Học được điều không suy ra từ code (lệnh test thật, cổng, bẫy) → ghi `<run>/knowledge-delta-<task_id>.md` (header `repo:`; `## +id` + `paths:` cho mục mới; sửa mục cũ `## id` + dòng `base:` chép từ `get`; ≤ 40 dòng/mục; không ghi giá trị secret); không tự `knowledge merge`.
+Repo đích và knowledge: dòng `repo:` của brief là repo ĐÍCH (có thể là repo con, khác cwd). Trước khi đọc code: `dieu-phoi knowledge list --repo <repo>` rồi `knowledge get <id|từ khoá> --repo <repo>` (ít nhất `build-test ports-resources` nếu có); mục STALE chỉ là gợi ý. Cấu trúc code: dùng codebase-memory-mcp khi repo đã có index (`list_projects`), không thì Grep/Glob — không tự index. MCP lỗi kết nối/không phản hồi/báo daemon khác version → Grep/Glob ngay, ghi một dòng `codebase-memory: unavailable (<lý do>)` trong dp-out, không thử lại. Brief có `worktree:` → chỉ sửa và chạy lệnh trong worktree đó, dùng cổng/tài nguyên riêng brief ghi, chỉ kill tiến trình do chính mình mở. Học được điều không suy ra từ code (lệnh test thật, cổng, bẫy) → ghi `<run>/knowledge-delta-<task_id>.md` (header `repo:`; `## +id` + `paths:` cho mục mới; sửa mục cũ `## id` + dòng `base:` chép từ `get`; ≤ 40 dòng/mục; không ghi giá trị secret); không tự `knowledge merge`.
 
 Helper thế hệ 2 (tuỳ chọn, chỉ khi giúp giữ ngữ cảnh nhỏ): tối đa 4 agent `subagent_type: dp-helper`, `model` đặt rõ `haiku` hoặc `sonnet`, cho đúng hai loại việc — (a) đọc/quét code hoặc tài liệu rồi trả tóm tắt ≤ 15 dòng, (b) chạy test / Unity smoke rồi tóm tắt log. Dòng đầu prompt helper: `[dp:<type>|s<n>|<urgency>|try1|task=<id mới từ dieu-phoi new-id>|role=helper|parent=<task của bạn>]`. Hook từ chối mọi lần giao sai luật. Không giao helper sửa code.
 

package/agents/dp-helper.md

@@ -17,6 +17,7 @@ Bạn là helper thế hệ 2 của dieu-phoi, do một agent exec giao (thẻ `
 
 Giữ ngữ cảnh nhỏ (mỗi lượt gửi lại toàn bộ ngữ cảnh — số lượt mới là thứ làm phình):
 - Grep/Glob trước, rồi Read đúng đoạn cần bằng offset/limit; không cat/sed -n cả file qua Bash.
+- codebase-memory-mcp lỗi kết nối/không phản hồi → Grep/Glob ngay, ghi một dòng `codebase-memory: unavailable (<lý do>)` trong tóm tắt, không thử lại.
 - Không đọc lại file đã đọc — ghi chú điều cần nhớ ngay khi đọc.
 - Lọc output lệnh dài (`| tail -n 40`, `| grep ...`); không dump log/JSON thô.
 - Mỗi ảnh/screenshot xem một lần, ghi nhận xét thành chữ, không mở lại.

package/agents/dp-scout.md

@@ -19,7 +19,7 @@ Bạn là scout/planner của dieu-phoi: khảo sát (code, tài liệu, dữ li
 
 Bàn giao qua file: ghi TOÀN BỘ kết quả vào `dp-out-<task_id>-plan-try<n>.md` trong run dir (đường dẫn brief chỉ định), rồi chỉ trả: đường dẫn file đó, dòng `STATUS:`, và ≤ 3 dòng ý chính. Không đặt tên file `report*` / `summary*` / `findings*` / `analysis*.md` — Claude Code chặn cứng Write các tên đó trong subagent. File dp-out/handoff mà brief trỏ tới là báo cáo chính thức: đọc thẳng, không cần xin thêm quyền.
 
-Repo đích và knowledge: `repo:` trong prompt là repo ĐÍCH (phiên ở repo cha làm việc trên repo con → repo con). Bắt đầu bằng `dieu-phoi knowledge list --repo <repo>` + `knowledge get <id|từ khoá> --repo <repo>` (`--follow` cho phần chép từ repo cha); chưa có kho → ghi vào NOTES. Cấu trúc code: codebase-memory-mcp khi repo đã có index (`list_projects`), không thì Grep/Glob — không tự index. Bước sửa code chạy song song cùng repo → ghi cần worktree + cổng riêng. Điều không suy ra từ code → `<run>/knowledge-delta-<task_id>.md` (header `repo:`, `## +id` + `paths:`), không tự merge.
+Repo đích và knowledge: `repo:` trong prompt là repo ĐÍCH (phiên ở repo cha làm việc trên repo con → repo con). Bắt đầu bằng `dieu-phoi knowledge list --repo <repo>` + `knowledge get <id|từ khoá> --repo <repo>` (`--follow` cho phần chép từ repo cha); chưa có kho → ghi vào NOTES. Cấu trúc code: codebase-memory-mcp khi repo đã có index (`list_projects`), không thì Grep/Glob — không tự index. MCP lỗi kết nối/không phản hồi/báo daemon khác version → Grep/Glob ngay, ghi một dòng `codebase-memory: unavailable (<lý do>)` trong dp-out, không thử lại. Bước sửa code chạy song song cùng repo → ghi cần worktree + cổng riêng. Điều không suy ra từ code → `<run>/knowledge-delta-<task_id>.md` (header `repo:`, `## +id` + `paths:`), không tự merge.
 
 Giữ ngữ cảnh nhỏ (mỗi lượt gửi lại toàn bộ ngữ cảnh — số lượt mới là thứ làm phình):
 - Grep/Glob trước, rồi Read đúng đoạn cần bằng offset/limit; không cat/sed -n cả file qua Bash.

package/agents/dp-verify.md

@@ -23,6 +23,7 @@ Repo đích và knowledge: chạy lệnh trong `worktree:` của bước nếu b
 
 Giữ ngữ cảnh nhỏ (mỗi lượt gửi lại toàn bộ ngữ cảnh — số lượt mới là thứ làm phình):
 - Grep/Glob trước, rồi Read đúng đoạn cần bằng offset/limit; không cat/sed -n cả file qua Bash.
+- codebase-memory-mcp lỗi kết nối/không phản hồi → Grep/Glob ngay, ghi một dòng `codebase-memory: unavailable (<lý do>)` trong dp-out, không thử lại.
 - Không đọc lại file đã đọc — ghi chú điều cần nhớ ngay khi đọc.
 - Lọc output lệnh dài (`| tail -n 40`, `| grep ...`); không dump log/JSON thô.
 - Mỗi ảnh/screenshot xem một lần, ghi nhận xét thành chữ, không mở lại.

package/bin/dieu-phoi.cjs

@@ -10,7 +10,14 @@ Cách dùng: dieu-phoi <lệnh> [tuỳ chọn]
 
   setup [--dept D] [--sink-url U --sink-token T] [--skill-dir P]
                          cài hook vào ~/.claude/dieu-phoi/bin, đăng ký trong settings.json
-  doctor [--net]         kiểm hook, node, config, sink (sink lấy từ bộ nhớ đệm 24 giờ; --net kiểm trực tiếp)
+  setup --with-codebase-memory [--force] [--cbm-dir D] [--allow-custom-source]
+                         thêm: tải bản phát hành chính thức codebase-memory-mcp (kiểm sha256), cài binary, đăng ký
+                         MCP user scope (\`claude mcp add\`); đã có thì giữ nguyên trừ khi --force (bản cũ đổi tên .bak-dieu-phoi-*;
+                         đăng ký cũ được khôi phục nếu đăng ký mới lỗi). DIEU_PHOI_CBM_BASE_URL (nguồn tải khác) cần --allow-custom-source
+  doctor [--net] [--cbm] [--repo P]
+                         kiểm hook, node, config, sink (sink lấy từ bộ nhớ đệm 24 giờ; --net kiểm trực tiếp) và
+                         codebase-memory-mcp (khuyến nghị: cài/MCP/index của repo; --cbm hoặc --net mới chạy \`daemon status\` ~3 s,
+                         kết quả nhớ 10 phút; --net còn so bản mới nhất)
   start [--json]         khởi động cổng 1 trong một lệnh (~150 ms, không gọi mạng): kiểm cục bộ, task_id gốc,
                          tạo run dir, đường dẫn brief scout — dùng khi hook UserPromptSubmit không chạy
   verdict <agent_id|last> <pass|fail|timeout|aborted> [--verify tests|lint|review|judgment|none] [--reason short-kebab]

package/hook.cjs

@@ -26,7 +26,7 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 
-const CORE_VERSION = '0.6.0';
+const CORE_VERSION = '0.6.1';
 const SCHEMA = 1;
 const TASK_TYPES = [
   'search', 'extract', 'mechanical-edit', 'feature-impl', 'debug', 'refactor',
@@ -1397,7 +1397,8 @@ function sinkStatusCached(ctx, nowMs) {
   const now = nowMs || Date.now();
   const cands = [];
   const chk = readJsonFile(ctx.paths.sinkCheck, null);
-  if (chk && chk.url === sinkUrlKey(cfg) && Date.parse(chk.ts)) {
+  // a timed-out doctor check (`timeout: true`) is "slow/unknown", not a failure: ignored here, so a fresher sync result or `unknown` wins
+  if (chk && !chk.timeout && chk.url === sinkUrlKey(cfg) && Date.parse(chk.ts)) {
     cands.push({ state: chk.ok ? 'ok' : 'fail', ts: chk.ts, source: 'doctor', detail: chk.detail || null });
   }
   const ls = readJsonFile(ctx.paths.lastSync, null);
@@ -1651,7 +1652,7 @@ function handoffChainMessage(taskId, n) {
   return `dieu-phoi: task ${taskId} đã handoff ${n} lần (trần ${HANDOFF_CHAIN_WARN}). Đừng nối tiếp thêm: nếu agent vừa giao là agent tiếp nối, cân nhắc dừng nó và giao planner (dp-scout) đọc handoff-${taskId}.md rồi chia phần còn lại thành bước mới (task_id mới từ \`dieu-phoi new-id\`).`;
 }
 
-// ------------------------------------------------------------------ core 0.6.0 (unreleased): project identity
+// ------------------------------------------------------------------ core 0.6.0: project identity
 //
 // A project (= one git repo, however many worktrees/clones) gets a stable key so every session and worktree can
 // share one knowledge store (~/.dieu-phoi/projects/<name>-<sha8(key)>/). Everything here is plain file reads —
@@ -1912,7 +1913,7 @@ function readHead(start) {
   return sha ? { branch, sha, detached: false } : { branch, sha: null, detached: false, unborn: true };
 }
 
-// ------------------------------------------------------------------ core 0.6.0 (unreleased), s3: knowledge freshness
+// ------------------------------------------------------------------ core 0.6.0, s3: knowledge freshness
 //
 // A knowledge section is stale when a file matching its `paths` globs differs between the commit it was merged at
 // (`sha`) and the HEAD of the worktree asking. Used by the start block here and by `knowledge get/list/status`

package/lib/args.cjs

@@ -4,7 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const core = require('../hook.cjs');
 
-const BOOLEAN_FLAGS = new Set(['json', 'help', 'h', 'purge', 'version', 'v', 'dry-run', 'no-sync', 'approve', 'yes', 'force', 'follow', 'remove', 'dirty', 'no-cache', 'untagged', 'no-knowledge']);
+const BOOLEAN_FLAGS = new Set(['json', 'help', 'h', 'purge', 'version', 'v', 'dry-run', 'no-sync', 'approve', 'yes', 'force', 'follow', 'remove', 'dirty', 'no-cache', 'untagged', 'no-knowledge', 'net', 'with-codebase-memory', 'cbm', 'allow-custom-source']);
 
 /** Minimal argv parser: positionals, --k v, --k=v, boolean flags. */
 function parseArgs(argv) {

package/lib/cbm.cjs

@@ -0,0 +1,490 @@
+'use strict';
+
+// codebase-memory-mcp (https://github.com/DeusData/codebase-memory-mcp): a recommended, optional MCP server that
+// gives agents a code graph. `doctor` reports on it (installed? registered? version? a daemon of another version?
+// repo indexed?) and `setup --with-codebase-memory` installs the official release binary + registers it in Claude
+// Code at user scope. Nothing here is required for dieu-phoi to work: every problem is a warning, never an error.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const cp = require('child_process');
+const crypto = require('crypto');
+
+const REPO = 'DeusData/codebase-memory-mcp';
+const SERVER_NAME = 'codebase-memory-mcp';
+const RELEASE_BASE = `https://github.com/${REPO}/releases/latest/download`;
+const LATEST_API = `https://api.github.com/repos/${REPO}/releases/latest`;
+const INSTALL_HINT = 'dieu-phoi setup --with-codebase-memory';
+const CHECKSUMS_MAX = 1024 * 1024;
+const DAEMON_CACHE_MS = 10 * 60 * 1000;
+
+const binName = (platform) => ((platform || process.platform) === 'win32' ? `${SERVER_NAME}.exe` : SERVER_NAME);
+const toSlash = (p) => String(p).replace(/\\/g, '/');
+
+/** Claude Code's own config file: `$CLAUDE_CONFIG_DIR/.claude.json`, or `~/.claude.json` for the default ~/.claude. */
+function claudeJsonPath(claudeDir) {
+  const def = path.join(os.homedir(), '.claude');
+  if (path.resolve(claudeDir) === path.resolve(def)) return path.join(os.homedir(), '.claude.json');
+  return path.join(claudeDir, '.claude.json');
+}
+
+function isCbmEntry(name, cfg) {
+  if (/codebase-memory/i.test(name)) return true;
+  return !!(cfg && typeof cfg.command === 'string' && /codebase-memory-mcp(\.exe)?$/i.test(cfg.command.trim()));
+}
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { return null; }
+}
+
+function samePath(a, b) {
+  const n = (p) => toSlash(path.resolve(p)).replace(/\/+$/, '');
+  return process.platform === 'win32' ? n(a).toLowerCase() === n(b).toLowerCase() : n(a) === n(b);
+}
+
+/** MCP registrations of codebase-memory-mcp visible to Claude Code for `repo`: user, local (per project) and project (.mcp.json). */
+function registrations(claudeDir, repo) {
+  const out = [];
+  const file = claudeJsonPath(claudeDir);
+  const j = readJson(file);
+  const push = (scope, servers, src) => {
+    if (!servers || typeof servers !== 'object') return;
+    for (const [name, cfg] of Object.entries(servers)) {
+      if (!isCbmEntry(name, cfg)) continue;
+      const c = cfg && typeof cfg === 'object' ? cfg : {};
+      // args/env are kept (never printed) so `install --force` can restore the entry if re-registering fails
+      out.push({
+        scope, name, command: typeof c.command === 'string' ? c.command : null, file: src,
+        args: Array.isArray(c.args) ? c.args.map(String) : [],
+        env: c.env && typeof c.env === 'object' && !Array.isArray(c.env) ? c.env : {},
+      });
+    }
+  };
+  if (j) {
+    push('user', j.mcpServers, file);
+    if (repo && j.projects && typeof j.projects === 'object') {
+      for (const [p, pc] of Object.entries(j.projects)) {
+        if (pc && samePath(p, repo)) push('local', pc.mcpServers, file);
+      }
+    }
+  }
+  if (repo) {
+    const root = repoRoot(repo) || repo;
+    const mj = readJson(path.join(root, '.mcp.json'));
+    if (mj) push('project', mj.mcpServers, path.join(root, '.mcp.json'));
+  }
+  return out;
+}
+
+function isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch (_) { return false; }
+}
+
+function defaultInstallDir(platform, env) {
+  const e = env || process.env;
+  if ((platform || process.platform) === 'win32') {
+    const base = e.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return path.join(base, 'Programs', SERVER_NAME); // where the project's own install.ps1 puts it
+  }
+  return path.join(os.homedir(), '.local', 'bin');
+}
+
+/**
+ * Locate the binary: DIEU_PHOI_CBM_BIN (a path; `none` turns off PATH/default-dir search, for tests), the command of a
+ * Claude Code registration, PATH, then the default install dirs (~/.local/bin, %LOCALAPPDATA%/Programs/...).
+ */
+function findBinary(regs, env) {
+  const e = env || process.env;
+  const forced = e.DIEU_PHOI_CBM_BIN;
+  if (forced && forced !== 'none') return isFile(forced) ? { path: forced, source: 'DIEU_PHOI_CBM_BIN' } : null;
+  for (const r of regs || []) {
+    if (r.command && isFile(r.command)) return { path: r.command, source: `MCP ${r.scope}` };
+  }
+  if (forced === 'none') return null;
+  const name = binName();
+  for (const dir of String(e.PATH || e.Path || '').split(path.delimiter)) {
+    if (dir && isFile(path.join(dir, name))) return { path: path.join(dir, name), source: 'PATH' };
+  }
+  for (const dir of [path.join(os.homedir(), '.local', 'bin'), defaultInstallDir(process.platform, e)]) {
+    if (isFile(path.join(dir, name))) return { path: path.join(dir, name), source: 'thư mục mặc định' };
+  }
+  return null;
+}
+
+/** argv for running `bin` (a .js/.cjs path runs under this node — lets tests use a fake binary on every OS). */
+function binArgv(bin, args) {
+  return /\.c?js$/i.test(bin) ? [process.execPath, [bin, ...args]] : [bin, args];
+}
+
+function probeVersion(bin, timeoutMs) {
+  const [cmd, args] = binArgv(bin, ['--version']);
+  const r = cp.spawnSync(cmd, args, { encoding: 'utf8', timeout: timeoutMs || 3000, windowsHide: true });
+  if (r.error || r.status !== 0) return null;
+  const m = /(\d+\.\d+\.\d+)/.exec(`${r.stdout || ''}`);
+  return m ? m[1] : null;
+}
+
+/** `codebase-memory-mcp daemon status` → { state: active|none|unresponsive|unknown, version, pid, clients }. */
+function parseDaemonStatus(text) {
+  const t = String(text || '');
+  const res = { state: 'unknown', version: null, pid: null, clients: [] };
+  if (/daemon:\s*active/i.test(t)) res.state = 'active';
+  else if (/not responding/i.test(t)) res.state = 'unresponsive';
+  else if (/not running|no daemon|inactive|stopped/i.test(t)) res.state = 'none';
+  const b = /build:\s*v?(\d+\.\d+\.\d+)/i.exec(t) || /active version\s*v?(\d+\.\d+\.\d+)/i.exec(t);
+  if (b) res.version = b[1];
+  const p = /^\s*pid:\s*(\d+)/im.exec(t) || /held by pid\s*(\d+)/i.exec(t);
+  if (p) res.pid = Number(p[1]);
+  const re = /^\s*-\s*pid\s+(\d+)/gim;
+  let m;
+  while ((m = re.exec(t))) res.clients.push(Number(m[1]));
+  return res;
+}
+
+/** Async so doctor can start it first and overlap it with its other (blocking) checks. */
+function daemonStatus(bin, timeoutMs) {
+  return new Promise((resolve) => {
+    const [cmd, args] = binArgv(bin, ['daemon', 'status']);
+    cp.execFile(cmd, args, { encoding: 'utf8', timeout: timeoutMs || 5000, windowsHide: true }, (err, stdout, stderr) => {
+      if (err && err.killed) return resolve({ state: 'timeout', version: null, pid: null, clients: [] });
+      resolve(parseDaemonStatus(`${stdout || ''}\n${stderr || ''}`));
+    });
+  });
+}
+
+function cacheDir(env) {
+  const e = env || process.env;
+  return e.CBM_CACHE_DIR ? path.resolve(e.CBM_CACHE_DIR) : path.join(os.homedir(), '.cache', SERVER_NAME);
+}
+
+/** Top of the git work tree containing `dir` (a .git dir or file), or null. */
+function repoRoot(dir) {
+  let d = path.resolve(dir);
+  for (;;) {
+    if (fs.existsSync(path.join(d, '.git'))) return d;
+    const up = path.dirname(d);
+    if (up === d) return null;
+    d = up;
+  }
+}
+
+/** For a linked worktree (`.git` is a file), the main checkout's root; else null. */
+function mainCheckoutOf(root) {
+  try {
+    const g = path.join(root, '.git');
+    if (!fs.statSync(g).isFile()) return null;
+    const m = /gitdir:\s*(.+)/.exec(fs.readFileSync(g, 'utf8'));
+    if (!m) return null;
+    const gitdir = path.resolve(root, m[1].trim());
+    let common = gitdir;
+    try { common = path.resolve(gitdir, fs.readFileSync(path.join(gitdir, 'commondir'), 'utf8').trim()); } catch (_) { /* none */ }
+    return path.basename(common) === '.git' ? path.dirname(common) : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+const canon = (s) => toSlash(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+
+/**
+ * Is `repo` indexed? codebase-memory-mcp keeps one `<project>.db` per repo in its cache dir, the project name being the
+ * path with separators as `-` (D:/Projects/x → D-Projects-x). Compared loosely (case, punctuation). Best effort: no
+ * process is spawned (a `cli list_projects` takes ~13 s and fails while a daemon of another version runs).
+ */
+function indexStatus(repo, env) {
+  const root = repoRoot(repo);
+  if (!root) return { root: null, indexed: false, skipped: 'ngoài git' };
+  let names = [];
+  const dir = cacheDir(env);
+  try { names = fs.readdirSync(dir).filter((n) => /\.db$/.test(n) && !n.startsWith('_')).map((n) => n.slice(0, -3)); } catch (_) { /* none */ }
+  const want = (p) => names.find((n) => canon(n) === canon(p));
+  const hit = want(root);
+  if (hit) return { root, indexed: true, project: hit, dir };
+  const main = mainCheckoutOf(root);
+  const mainHit = main ? want(main) : null;
+  return { root, indexed: false, main, main_project: mainHit || null, dir };
+}
+
+function cmpVersion(a, b) {
+  const pa = String(a).replace(/^v/, '').split('.').map(Number);
+  const pb = String(b).replace(/^v/, '').split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+async function latestVersion(env, timeoutMs) {
+  const url = (env || process.env).DIEU_PHOI_CBM_LATEST_URL || LATEST_API;
+  const res = await fetch(url, { headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'dieu-phoi' }, signal: AbortSignal.timeout(timeoutMs || 6000) });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const j = await res.json();
+  const m = /(\d+\.\d+\.\d+)/.exec(String(j && j.tag_name || ''));
+  if (!m) throw new Error('không đọc được tag_name');
+  return m[1];
+}
+
+function indexCommand(bin, root) {
+  return `${bin ? `"${toSlash(bin)}"` : SERVER_NAME} cli index_repository '{"repo_path":"${toSlash(root)}"}'`;
+}
+
+function registerCommand(bin) {
+  return `claude mcp add --scope user ${SERVER_NAME} -- "${toSlash(bin)}"`;
+}
+
+function readDaemonCache(file, bin, version, nowMs) {
+  if (!file) return null;
+  const c = readJson(file);
+  if (!c || !c.daemon || c.bin !== toSlash(bin) || c.version !== (version || null)) return null;
+  const t = Date.parse(c.ts);
+  if (!t || nowMs - t > DAEMON_CACHE_MS || t > nowMs + 60000) return null;
+  if (!c.daemon.state || c.daemon.state === 'timeout') return null;
+  return { ts: c.ts, daemon: c.daemon };
+}
+
+function writeDaemonCache(file, bin, version, daemon, nowMs) {
+  if (!file || !daemon || daemon.state === 'timeout') return;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify({ ts: new Date(nowMs).toISOString(), bin: toSlash(bin), version: version || null, daemon })}\n`);
+  } catch (_) { /* cache is best effort */ }
+}
+
+/**
+ * Doctor checks (all warnings at worst). Spawns at most `--version` (~40 ms) and, only with `deep` (doctor `--net` /
+ * `--cbm`), `daemon status` (~2.7 s, async, so it overlaps the other checks); otherwise the daemon line comes from a
+ * 10-minute cache (`cacheFile`) or says it was not checked. `net` adds one GitHub API call (6 s timeout).
+ * Returns a Promise of the checks: call it early, await it at the end.
+ */
+function doctorChecks({ claudeDir, repo, net, deep, cacheFile, env, now }) {
+  const e = env || process.env;
+  const nowMs = typeof now === 'number' ? now : Date.now();
+  const checks = [];
+  const add = (ok, name, detail) => checks.push({ ok, level: ok ? 'OK' : 'CẢNH BÁO', name, detail });
+  const regs = registrations(claudeDir, repo);
+  const found = findBinary(regs, e);
+  const regTxt = regs.length ? regs.map((r) => `${r.scope}:${r.name}`).join(', ') : null;
+  if (!found) {
+    add(false, 'codebase-memory', regs.length
+      ? `MCP đã đăng ký (${regTxt}) nhưng không thấy binary ${regs.map((r) => r.command).filter(Boolean).join(', ') || ''} — cài lại: \`${INSTALL_HINT} --force\``
+      : `chưa cài (khuyến nghị, không bắt buộc: agent dùng Grep/Glob khi thiếu) — cài: \`${INSTALL_HINT}\``);
+    return Promise.resolve(checks);
+  }
+  const version = probeVersion(found.path);
+  const wantDaemon = !!(deep || net);
+  const cached = wantDaemon ? null : readDaemonCache(cacheFile, found.path, version, nowMs);
+  const daemonP = wantDaemon ? daemonStatus(found.path, 5000) : Promise.resolve(null);
+  const latestP = net ? latestVersion(e).then((v) => ({ v }), (err) => ({ err: err.message })) : Promise.resolve(null);
+  return (async () => {
+    add(!!version && regs.length > 0, 'codebase-memory', `${version ? `v${version}` : 'không chạy được `--version`'} tại ${toSlash(found.path)} (${found.source})${regs.length
+      ? `; MCP: ${regTxt}` : ` — chưa đăng ký MCP trong Claude Code: \`${registerCommand(found.path)}\``}`);
+    const latest = await latestP;
+    if (latest && version) {
+      if (latest.err) add(true, 'cbm-version', `không kiểm được bản mới nhất (${latest.err})`);
+      else if (cmpVersion(version, latest.v) < 0) add(false, 'cbm-version', `v${version} cũ hơn bản mới nhất v${latest.v} — nâng cấp: \`${INSTALL_HINT} --force\` (đóng các phiên đang dùng MCP trước)`);
+      else add(true, 'cbm-version', `v${version} là bản mới nhất`);
+    }
+    let d = await daemonP;
+    let suffix = '';
+    if (d) writeDaemonCache(cacheFile, found.path, version, d, nowMs);
+    else if (cached) { d = cached.daemon; suffix = ` (bộ nhớ đệm lúc ${cached.ts}; \`dieu-phoi doctor --cbm\` để kiểm lại)`; }
+    if (!d) {
+      add(true, 'cbm-daemon', 'chưa kiểm (`daemon status` mất ~3 s) — chạy `dieu-phoi doctor --cbm` khi MCP báo lỗi hoặc nghi daemon khác version');
+    } else if (d.state === 'active' && d.version && version && d.version !== version) {
+      add(false, 'cbm-daemon', `daemon v${d.version} (pid ${d.pid || '?'}) đang chạy khác bản cài v${version} — bản cài sẽ bị từ chối (agent rơi về Grep/Glob) tới khi daemon cũ thoát. Daemon tự thoát khi phiên cuối đóng: đóng/khởi động lại các phiên Claude Code đang dùng MCP${d.clients.length ? ` (pid ${d.clients.join(', ')})` : ''}, hoặc \`codebase-memory-mcp daemon stop\` khi không còn phiên.${suffix}`);
+    } else if (d.state === 'unresponsive') {
+      add(false, 'cbm-daemon', `daemon không phản hồi${d.pid ? ` (endpoint do pid ${d.pid} giữ)` : ''} — có thể là bản khác; khởi động lại các phiên Claude Code đang dùng MCP${suffix}`);
+    } else if (d.state === 'active') {
+      add(true, 'cbm-daemon', `daemon v${d.version || '?'} đang chạy${d.clients.length ? `, ${d.clients.length} phiên` : ''}${suffix}`);
+    } else if (d.state === 'timeout') {
+      add(true, 'cbm-daemon', 'không đọc được `daemon status` trong 5 s (bỏ qua)');
+    } else {
+      add(true, 'cbm-daemon', `không có daemon đang chạy${suffix}`);
+    }
+    const ix = indexStatus(repo, e);
+    if (ix.root) {
+      if (ix.indexed) add(true, 'cbm-index', `${toSlash(ix.root)} đã index (project ${ix.project})`);
+      else {
+        add(false, 'cbm-index', `${toSlash(ix.root)} chưa index${ix.main_project ? ` (repo chính ${toSlash(ix.main)} đã có: ${ix.main_project})` : ''} — agent dùng Grep/Glob; index: \`${indexCommand(found.path, ix.root)}\``);
+      }
+    }
+    return checks;
+  })();
+}
+
+// ------------------------------------------------------------------ install
+
+/** Official release asset for this OS/arch (names as published in checksums.txt). */
+function assetFor(platform, arch) {
+  const a = arch === 'arm64' ? 'arm64' : (arch === 'x64' ? 'amd64' : null);
+  if (!a) return null;
+  if (platform === 'win32') return `${SERVER_NAME}-windows-${a}.zip`;
+  if (platform === 'darwin') return `${SERVER_NAME}-darwin-${a}.tar.gz`;
+  if (platform === 'linux') return `${SERVER_NAME}-linux-${a}-portable.tar.gz`; // portable = no glibc version dependency
+  return null;
+}
+
+function sha256File(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+function digestFor(checksums, asset) {
+  for (const line of String(checksums).split(/\r?\n/)) {
+    const m = /^([0-9a-fA-F]{64})\s+\*?(\S+)\s*$/.exec(line.trim());
+    if (m && m[2] === asset) return m[1].toLowerCase();
+  }
+  return null;
+}
+
+const defaultDeps = {
+  async fetchText(url) {
+    const res = await fetch(url, { redirect: 'follow', headers: { 'User-Agent': 'dieu-phoi' }, signal: AbortSignal.timeout(30000) });
+    if (!res.ok) throw new Error(`${url} → HTTP ${res.status}`);
+    const len = Number(res.headers.get('content-length') || 0);
+    if (len > CHECKSUMS_MAX) throw new Error('checksums.txt vượt 1 MiB');
+    const t = await res.text();
+    if (t.length > CHECKSUMS_MAX) throw new Error('checksums.txt vượt 1 MiB');
+    return t;
+  },
+  async download(url, dest) {
+    const res = await fetch(url, { redirect: 'follow', headers: { 'User-Agent': 'dieu-phoi' }, signal: AbortSignal.timeout(600000) });
+    if (!res.ok) throw new Error(`${url} → HTTP ${res.status}`);
+    fs.writeFileSync(dest, Buffer.from(await res.arrayBuffer()));
+  },
+  extract(archive, destDir) {
+    // Windows' own bsdtar reads .zip; a git-bash GNU tar earlier on PATH would not.
+    const tar = process.platform === 'win32' ? path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe') : 'tar';
+    const r = cp.spawnSync(tar, ['-xf', archive, '-C', destDir], { encoding: 'utf8', timeout: 300000, windowsHide: true });
+    if (r.error || r.status !== 0) throw new Error(`giải nén lỗi: ${r.error ? r.error.message : (r.stderr || '').trim().slice(0, 200)}`);
+  },
+  probeVersion,
+  runClaude(args, env) {
+    const win = process.platform === 'win32';
+    const q = (a) => (win && /[\s"&|<>^]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a);
+    const r = cp.spawnSync(win ? ['claude', ...args.map(q)].join(' ') : 'claude', win ? [] : args, {
+      shell: win, encoding: 'utf8', timeout: 60000, windowsHide: true, env,
+    });
+    return { status: r.error ? null : r.status, out: `${r.stdout || ''}${r.stderr || ''}`.trim(), error: r.error ? r.error.message : null };
+  },
+};
+
+function tsStamp(d) {
+  return (d || new Date()).toISOString().replace(/[-:]/g, '').replace(/\..*/, '').replace('T', '-');
+}
+
+/**
+ * `setup --with-codebase-memory`: install the official release binary (checksum-verified) and register it in Claude Code
+ * at user scope. An existing binary / registration is kept unless `force`; a replaced binary is renamed to
+ * `<bin>.bak-dieu-phoi-<ts>` first (rename works on Windows even while the old exe runs). `deps` is injectable for tests.
+ */
+async function install(opts, deps) {
+  const d = Object.assign({}, defaultDeps, deps || {});
+  const env = opts.env || process.env;
+  const platform = opts.platform || process.platform;
+  const arch = opts.arch || process.arch;
+  const claudeDir = opts.claudeDir;
+  const force = !!opts.force;
+  const res = { ok: true, binary: null, version: null, action: null, backup: null, mcp: null, notes: [] };
+  const regs = registrations(claudeDir, null).filter((r) => r.scope === 'user');
+  const existing = findBinary(regs, env);
+
+  let target;
+  if (existing && !force) {
+    res.binary = existing.path;
+    res.version = d.probeVersion(existing.path);
+    res.action = 'kept';
+    target = existing.path;
+  } else {
+    const asset = assetFor(platform, arch);
+    if (!asset) throw new Error(`không có bản phát hành cho ${platform}/${arch} — xem https://github.com/${REPO}/releases`);
+    const base = (env.DIEU_PHOI_CBM_BASE_URL || RELEASE_BASE).replace(/\/+$/, '');
+    if (base !== RELEASE_BASE) {
+      const warn = `DIEU_PHOI_CBM_BASE_URL đang đặt nguồn tải KHÁC bản phát hành chính thức (${base} thay vì ${RELEASE_BASE}); checksums.txt lấy cùng nguồn đó nên sha256 không còn bảo đảm đây là bản chính thức`;
+      if (!opts.allowCustomSource) throw new Error(`${warn}. Không tải gì. Nếu đúng ý (mirror nội bộ, thử nghiệm): thêm --allow-custom-source; không thì bỏ biến này.`);
+      res.notes.push(`CẢNH BÁO: ${warn} (đã xác nhận bằng --allow-custom-source)`);
+    }
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dieu-phoi-cbm-'));
+    try {
+      const sums = await d.fetchText(`${base}/checksums.txt`);
+      const want = digestFor(sums, asset);
+      if (!want) throw new Error(`checksums.txt không có ${asset}`);
+      const archive = path.join(tmp, asset);
+      await d.download(`${base}/${asset}`, archive);
+      const got = sha256File(archive);
+      if (got !== want) throw new Error(`sha256 không khớp cho ${asset}: tải về ${got}, checksums.txt ${want} — không cài`);
+      const out = path.join(tmp, 'x');
+      fs.mkdirSync(out);
+      d.extract(archive, out);
+      const name = binName(platform);
+      const fresh = path.join(out, name);
+      const st = fs.existsSync(fresh) ? fs.lstatSync(fresh) : null;
+      if (!st || !st.isFile()) throw new Error(`không thấy ${name} (tệp thường) trong ${asset}`);
+      const v = d.probeVersion(fresh);
+      if (!v) throw new Error(`binary vừa tải không chạy được \`--version\` — không cài`);
+      const dir = typeof opts.dir === 'string' ? path.resolve(opts.dir) : (existing ? path.dirname(existing.path) : defaultInstallDir(platform, env));
+      target = path.join(dir, name);
+      fs.mkdirSync(dir, { recursive: true });
+      if (fs.existsSync(target)) {
+        res.backup = `${target}.bak-dieu-phoi-${tsStamp(d.now ? d.now() : new Date())}`;
+        fs.renameSync(target, res.backup);
+      }
+      try {
+        fs.copyFileSync(fresh, target);
+        if (platform !== 'win32') fs.chmodSync(target, 0o755);
+      } catch (e) {
+        if (res.backup) { try { fs.renameSync(res.backup, target); res.backup = null; } catch (_) { /* keep backup */ } }
+        throw e;
+      }
+      res.binary = target;
+      res.version = v;
+      res.action = existing ? 'replaced' : 'installed';
+      if (existing && !samePath(existing.path, target)) res.notes.push(`bản cũ vẫn ở ${toSlash(existing.path)} (không đụng)`);
+    } finally {
+      try { fs.rmSync(tmp, { recursive: true, force: true }); } catch (_) { /* best effort */ }
+    }
+  }
+
+  // registration (user scope, the standard `claude mcp add`)
+  const cmdPath = toSlash(target);
+  const same = regs.find((r) => r.command && samePath(r.command, target));
+  if (regs.length && !force) {
+    res.mcp = same ? 'kept' : 'kept-other';
+    if (!same) res.notes.push(`MCP user đã đăng ký trỏ tới ${regs.map((r) => r.command).join(', ')} — giữ nguyên (dùng --force để trỏ về ${cmdPath})`);
+  } else {
+    const cenv = Object.assign({}, env);
+    if (path.resolve(claudeDir) !== path.resolve(path.join(os.homedir(), '.claude'))) cenv.CLAUDE_CONFIG_DIR = claudeDir;
+    // old entries are remembered (command/args/env) before `remove`, so a failed `add` can put them back
+    const removed = [];
+    for (const r of regs) {
+      const rm = d.runClaude(['mcp', 'remove', '--scope', 'user', r.name], cenv);
+      if (rm.status === 0) removed.push(r);
+    }
+    const r = d.runClaude(['mcp', 'add', '--scope', 'user', SERVER_NAME, '--', cmdPath], cenv);
+    if (r.status === 0) res.mcp = regs.length ? 'replaced' : 'added';
+    else {
+      res.mcp = 'manual';
+      res.notes.push(`không chạy được \`claude mcp add\` (${r.error || r.out || `exit ${r.status}`}) — tự chạy: ${registerCommand(cmdPath)}`);
+      const lost = [];
+      for (const o of removed) {
+        const argv = ['mcp', 'add'];
+        for (const [k, v] of Object.entries(o.env || {})) argv.push('--env', `${k}=${v}`);
+        argv.push('--scope', 'user', o.name, '--', o.command || '', ...(o.args || []));
+        if (o.command && d.runClaude(argv, cenv).status === 0) res.mcp = 'restored';
+        else lost.push(o);
+      }
+      if (removed.length && !lost.length) res.notes.push(`đã khôi phục đăng ký cũ (${removed.map((o) => o.name).join(', ')}), không mất gì`);
+      for (const o of lost) {
+        res.notes.push(`KHÔNG khôi phục được đăng ký cũ "${o.name}" (command: ${o.command ? toSlash(o.command) : '?'}${o.args && o.args.length ? `, ${o.args.length} args` : ''}${Object.keys(o.env || {}).length ? `, env: ${Object.keys(o.env).join(', ')}` : ''}); thêm lại bằng \`claude mcp add --scope user ${o.name} -- <command> <args>\` (giá trị env lấy từ bản sao .claude.json của bạn)`);
+      }
+    }
+  }
+  return res;
+}
+
+module.exports = {
+  REPO, SERVER_NAME, INSTALL_HINT, claudeJsonPath, registrations, findBinary, probeVersion, parseDaemonStatus, daemonStatus,
+  cacheDir, repoRoot, indexStatus, cmpVersion, latestVersion, doctorChecks, assetFor, digestFor, install, defaultInstallDir,
+  registerCommand, indexCommand,
+};

package/lib/commands.cjs

@@ -8,6 +8,7 @@ const core = require('../hook.cjs');
 const agg = require('./aggregate.cjs');
 const chooser = require('./choose.cjs');
 const setupLib = require('./setup.cjs');
+const cbm = require('./cbm.cjs');
 const { claudeDirOf, ctxOf, yesNo, repoOf } = require('./args.cjs');
 
 const AGENT_OUTCOMES = ['pass', 'fail', 'timeout', 'aborted'];
@@ -48,6 +49,7 @@ function table(rows) {
 // ------------------------------------------------------------------ setup / uninstall
 
 function cmdSetup(opts) {
+  if (opts['with-codebase-memory']) return cmdSetupWithCbm(opts);
   const res = setupLib.setup({
     claudeDir: claudeDirOf(opts),
     dept: typeof opts.dept === 'string' ? opts.dept : undefined,
@@ -75,6 +77,30 @@ function cmdSetup(opts) {
   return { code: 0, out: lines.join('\n') };
 }
 
+/** `setup --with-codebase-memory [--force] [--cbm-dir D]`: normal setup, then install + register codebase-memory-mcp. */
+async function cmdSetupWithCbm(opts) {
+  const base = cmdSetup(Object.assign({}, opts, { 'with-codebase-memory': false, json: false }));
+  let res;
+  let err = null;
+  try {
+    res = await cbm.install({ claudeDir: claudeDirOf(opts), force: !!opts.force, dir: typeof opts['cbm-dir'] === 'string' ? opts['cbm-dir'] : undefined, allowCustomSource: !!opts['allow-custom-source'] });
+  } catch (e) {
+    err = e.message;
+  }
+  if (opts.json) return { code: err ? 1 : 0, out: JSON.stringify({ setup: 'ok', codebase_memory: err ? { ok: false, error: err } : res }, null, 2) };
+  const lines = [base.out];
+  if (err) {
+    lines.push(`codebase-memory-mcp: LỖI — ${err} (setup dieu-phoi vẫn xong; không có gì bị ghi đè)`);
+  } else {
+    const act = { kept: 'đã có, giữ nguyên (--force để cài lại)', installed: 'đã cài', replaced: 'đã thay' }[res.action];
+    lines.push(`codebase-memory-mcp: ${act} v${res.version || '?'} tại ${res.binary.replace(/\\/g, '/')}${res.backup ? ` (bản cũ: ${path.basename(res.backup)})` : ''}`);
+    lines.push(`MCP (user scope): ${{ kept: 'đã đăng ký, giữ nguyên', 'kept-other': 'đã đăng ký (binary khác), giữ nguyên', added: 'đã đăng ký bằng `claude mcp add`', replaced: 'đã đăng ký lại', restored: 'đăng ký mới lỗi — đã khôi phục đăng ký cũ', manual: 'chưa đăng ký (xem ghi chú)' }[res.mcp]}`);
+    for (const n of res.notes) lines.push(`  - ${n}`);
+    if (res.action !== 'kept' || res.mcp === 'added' || res.mcp === 'replaced') lines.push('Khởi động lại các phiên Claude Code để nạp MCP; kiểm bằng `dieu-phoi doctor`.');
+  }
+  return { code: err ? 1 : 0, out: lines.join('\n') };
+}
+
 function cmdUninstall(opts) {
   const res = setupLib.uninstall({ claudeDir: claudeDirOf(opts), purge: !!opts.purge });
   if (opts.json) return { code: 0, out: JSON.stringify(res, null, 2) };
@@ -116,6 +142,14 @@ async function cmdDoctor(opts) {
   const sd = ctx.config.skill_dir;
   add(!!sd && fs.existsSync(path.join(sd, 'profile', 'profile.json')), 'profile',
     sd ? path.join(sd, 'profile', 'profile.json') : 'không có skill_dir — choose dùng priors mặc định', 'CẢNH BÁO');
+  // codebase-memory-mcp (optional): started here so its `daemon status` (~2.7 s, only with --cbm/--net; else a 10-minute
+  // cache) overlaps the hook-run check below
+  let cbmP = Promise.resolve([]);
+  try {
+    cbmP = cbm.doctorChecks({ claudeDir, repo: repoOf(opts), net: !!opts.net, deep: !!opts.cbm, cacheFile: path.join(ctx.paths.data, 'cbm-daemon.json') }).catch((e) => [{ ok: true, level: 'OK', name: 'codebase-memory', detail: `bỏ qua kiểm (${e.message})` }]);
+  } catch (e) {
+    cbmP = Promise.resolve([{ ok: true, level: 'OK', name: 'codebase-memory', detail: `bỏ qua kiểm (${e.message})` }]);
+  }
   if (reg.commands.length) {
     const cmd = reg.commands[0];
     const t0 = Date.now();
@@ -168,13 +202,17 @@ async function cmdDoctor(opts) {
     const cached = opts.net ? null : core.sinkStatusCached(ctx);
     if (cached && (cached.state === 'ok' || cached.state === 'fail')) {
       add(cached.state === 'ok', 'sink', `${ctx.config.sink_url} → ${cached.state === 'ok' ? 'ok' : `lỗi: ${cached.detail}`} (bộ nhớ đệm: ${cached.source} lúc ${cached.ts}; \`doctor --net\` để kiểm trực tiếp)`);
+    } else if (!opts.net && recentSinkTimeout(ctx)) {
+      const t = recentSinkTimeout(ctx);
+      add(false, 'sink', `${ctx.config.sink_url} → chậm/không xác định: lần kiểm lúc ${t.ts} không phản hồi kịp (chưa coi là lỗi); \`doctor --net\` để thử lại`, 'CẢNH BÁO');
     } else {
       const live = await checkSinkLive(ctx);
-      add(live.ok, 'sink', `${ctx.config.sink_url} → ${live.detail}`);
+      add(live.ok, 'sink', `${ctx.config.sink_url} → ${live.detail}`, live.slow ? 'CẢNH BÁO' : undefined);
     }
   } else {
     add(true, 'sink', 'chưa cấu hình (chỉ lưu cục bộ)');
   }
+  for (const c of await cbmP) checks.push(c);
   const failed = checks.some((c) => c.level === 'LỖI');
   if (opts.json) return { code: failed ? 1 : 0, out: JSON.stringify({ ok: !failed, runs_dir: reg.runs_dir, checks }, null, 2) };
   const out = checks.map((c) => `[${c.level}] ${c.name}: ${c.detail}`).join('\n');
@@ -208,26 +246,45 @@ function sweepStaleTmp(ctx) {
   return { removed, left };
 }
 
-/** Live sink check (view=stats); result cached in data/sink-check.json for 24 h. */
+/** The doctor's own timed-out sink check for the current sink, if less than 1 h old (else null): plain `doctor` does not retry a 20 s wait each time. */
+function recentSinkTimeout(ctx) {
+  const chk = core.readJsonFile(ctx.paths.sinkCheck, null);
+  if (!chk || !chk.timeout || chk.url !== core.sinkUrlKey(ctx.config)) return null;
+  const t = Date.parse(chk.ts);
+  return t && Date.now() - t < 3600 * 1000 && t <= Date.now() + 60000 ? { ts: chk.ts } : null;
+}
+
+/**
+ * Live sink check (view=stats); result cached in data/sink-check.json for 24 h. Apps Script often needs 8-15 s, so the
+ * timeout is 20 s (DIEU_PHOI_SINK_CHECK_TIMEOUT_MS overrides, for tests). A timeout is not a hard failure: it is
+ * reported as slow/unknown (CẢNH BÁO) and cached with `timeout: true`, which the cache readers ignore.
+ */
 async function checkSinkLive(ctx) {
   let ok = false;
+  let slow = false;
   let detail;
+  const ms = Number(process.env.DIEU_PHOI_SINK_CHECK_TIMEOUT_MS) > 0 ? Number(process.env.DIEU_PHOI_SINK_CHECK_TIMEOUT_MS) : 20000;
   try {
     const u = new URL(ctx.config.sink_url);
     u.searchParams.set('token', ctx.config.sink_token);
     u.searchParams.set('view', 'stats');
-    const res = await fetch(u, { redirect: 'follow', signal: AbortSignal.timeout(8000) });
+    const res = await fetch(u, { redirect: 'follow', signal: AbortSignal.timeout(ms) });
     const txt = await res.text();
     ok = res.ok;
     try { const b = JSON.parse(txt); if (b && b.ok === false) ok = false; } catch (_) { ok = false; }
     detail = `HTTP ${res.status}`;
   } catch (e) {
-    detail = e.message;
+    if (e && (e.name === 'TimeoutError' || e.name === 'AbortError')) {
+      slow = true;
+      detail = `chậm/không xác định: không phản hồi trong ${Math.round(ms / 1000)} s (Apps Script thường mất 8-15 s; chạy lại \`doctor --net\`, hoặc xem kết quả sync nền)`;
+    } else {
+      detail = e.message;
+    }
   }
   try {
-    core.writeFileAtomic(ctx.paths.sinkCheck, `${JSON.stringify({ ts: core.nowIso(), ok, detail, url: core.sinkUrlKey(ctx.config) })}\n`);
+    core.writeFileAtomic(ctx.paths.sinkCheck, `${JSON.stringify({ ts: core.nowIso(), ok, detail, url: core.sinkUrlKey(ctx.config), ...(slow ? { timeout: true } : {}) })}\n`);
   } catch (_) { /* cache is best effort */ }
-  return { ok, detail };
+  return { ok, detail, slow };
 }
 
 // ------------------------------------------------------------------ start

package/lib/knowledge.cjs

@@ -1,5 +1,5 @@
 'use strict';
-// `dieu-phoi knowledge ...` — per-project knowledge store (core 0.6.0, unreleased).
+// `dieu-phoi knowledge ...` — per-project knowledge store (core 0.6.0).
 // s1: project identity (path, rekey). s2: the store itself — index.json + sections/<id>.md + history/, read with
 // get/list, written only by `merge --run <id>` (lock, tmp+rename, history, 40-line cap, sha/rev conflicts), and
 // cross-repo links (related: child|parent) for a parent repo whose sessions work in its child repos.

package/lib/profile.cjs

@@ -1,5 +1,5 @@
 'use strict';
-// `dieu-phoi profile base|apply` (core 0.6.0, unreleased): apply an approved retro to <skill>/profile/lessons.md and
+// `dieu-phoi profile base|apply` (core 0.6.0): apply an approved retro to <skill>/profile/lessons.md and
 // profile.json without overwriting what other sessions wrote meanwhile.
 //
 //   profile base --save <dir>   snapshot both files into <dir>/profile-base/ (+ base.json with their sha256) before the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kienntpixon/dieu-phoi",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Hook + CLI ghi log subagent của Claude Code và chọn model/effort theo chi phí + thời gian tới lúc nghiệm thu.",
   "license": "MIT",
   "author": "kiennt <kiennt@pixon.games>",