@kienntpixon/dieu-phoi 0.7.2 → 0.7.4

package/lib/deps.cjs

@@ -0,0 +1,162 @@
+'use strict';
+// core 0.7.3 (s3): node_modules dùng chung cho worktree của dieu-phoi. OPT-IN: mặc định `none`.
+//  - `--deps auto|link|install|none` (hoặc env DIEU_PHOI_WT_DEPS → config.json `wt_deps` → none).
+//  - install (và auto khi có pnpm-lock.yaml): `pnpm install --frozen-lockfile --offline` (store hardlink, không tải mạng).
+//  - link (và auto khi không có pnpm-lock.yaml): junction <worktree>/<deps_path>/node_modules → node_modules của checkout
+//    chính, CHỈ khi package-lock.json giống hệt từng byte, package.json không có `workspaces`, và checkout chính có
+//    node_modules là thư mục thật. Còn lại → none + gợi ý. Không bao giờ ghi vào node_modules của checkout chính.
+//  - Gỡ an toàn: unlinkDepLinks gỡ junction (không đi xuyên) TRƯỚC `git worktree remove`; removeShell xoá vỏ còn sót
+//    bằng cách duyệt lstat, link nào cũng chỉ unlink, không bao giờ đi vào đích.
+const fs = require('fs');
+const path = require('path');
+const cp = require('child_process');
+
+const MODES = ['auto', 'link', 'install', 'none'];
+const INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
+
+function isLink(p) {
+  try { return fs.lstatSync(p).isSymbolicLink(); } catch (_) { return false; }
+}
+function isRealDir(p) {
+  try { const st = fs.lstatSync(p); return st.isDirectory() && !st.isSymbolicLink(); } catch (_) { return false; }
+}
+
+/** deps_path tương đối, nằm trong worktree ('.' = gốc). Ném nếu tuyệt đối hoặc thoát ra ngoài. */
+function normDepsPath(p) {
+  if (p === undefined || p === null || p === true || p === '') return '.';
+  if (typeof p !== 'string' || path.isAbsolute(p)) throw new Error('--deps-path cần đường dẫn tương đối trong repo (vd. cli)');
+  const n = path.normalize(p).replace(/\\/g, '/').replace(/\/+$/, '') || '.';
+  if (n === '..' || n.startsWith('../')) throw new Error('--deps-path không được ra ngoài repo');
+  return n;
+}
+
+/** Chế độ: --deps → env DIEU_PHOI_WT_DEPS → config `wt_deps` → none. Giá trị hỏng từ cờ thì ném; từ env/config thì none. */
+function depsModeOf(opts, ctx) {
+  if (opts && opts.deps !== undefined) {
+    if (typeof opts.deps !== 'string' || !MODES.includes(opts.deps)) throw new Error(`--deps cần một trong: ${MODES.join('|')}`);
+    return opts.deps;
+  }
+  const env = process.env.DIEU_PHOI_WT_DEPS;
+  const raw = env !== undefined && env !== '' ? env : (ctx && ctx.config ? ctx.config.wt_deps : undefined);
+  return typeof raw === 'string' && MODES.includes(raw) ? raw : 'none';
+}
+
+function readFileOrNull(p) {
+  try { return fs.readFileSync(p); } catch (_) { return null; }
+}
+
+/** Lý do không được junction (null = được). */
+function linkBlocker(mainDir, wtDir) {
+  const wtLock = readFileOrNull(path.join(wtDir, 'package-lock.json'));
+  if (!wtLock) return 'worktree không có package-lock.json';
+  const mainLock = readFileOrNull(path.join(mainDir, 'package-lock.json'));
+  if (!mainLock) return 'checkout chính không có package-lock.json';
+  // Giống hệt từng byte, chỉ bỏ qua khác biệt CRLF/LF (core.autocrlf trên Windows checkout worktree ra CRLF trong khi
+  // npm ghi LF vào checkout chính; nội dung lock vẫn là một).
+  const lf = (b) => b.toString('utf8').replace(/\r\n/g, '\n');
+  if (!wtLock.equals(mainLock) && lf(wtLock) !== lf(mainLock)) return 'package-lock.json khác checkout chính';
+  let pkg;
+  try { pkg = JSON.parse(fs.readFileSync(path.join(wtDir, 'package.json'), 'utf8')); } catch (_) { return 'không đọc được package.json'; }
+  if (pkg && pkg.workspaces) return 'package.json có workspaces';
+  if (!isRealDir(path.join(mainDir, 'node_modules'))) return 'checkout chính chưa có node_modules (thư mục thật)';
+  if (fs.existsSync(path.join(wtDir, 'node_modules')) || isLink(path.join(wtDir, 'node_modules'))) return 'worktree đã có node_modules';
+  return null;
+}
+
+/** Lệnh pnpm: env DIEU_PHOI_PNPM_BIN (đường dẫn) hoặc `pnpm` trên PATH. .cmd/.bat (và `pnpm` trên Windows) cần shell. */
+function pnpmSpawn(args, cwd, timeout) {
+  const bin = process.env.DIEU_PHOI_PNPM_BIN || 'pnpm';
+  const shell = process.platform === 'win32' && (!process.env.DIEU_PHOI_PNPM_BIN || /\.(cmd|bat)$/i.test(bin));
+  const cmd = shell && /\s/.test(bin) ? `"${bin}"` : bin;
+  return cp.spawnSync(cmd, args, { cwd, encoding: 'utf8', windowsHide: true, timeout, shell });
+}
+
+function pnpmInstall(wtDir) {
+  const v = pnpmSpawn(['--version'], wtDir, 30000);
+  if (v.error || v.status !== 0) return { deps: 'none', note: 'deps none: repo dùng pnpm nhưng không chạy được pnpm (vắng trên PATH?) — cài pnpm rồi chạy `pnpm install --offline` trong worktree' };
+  const r = pnpmSpawn(['install', '--frozen-lockfile', '--offline'], wtDir, INSTALL_TIMEOUT_MS);
+  if (r.error || r.status !== 0) {
+    const tail = String((r.stderr || '') + (r.stdout || '')).trim().split(/\r?\n/).slice(-3).join(' | ');
+    return { deps: 'none', note: `deps none: pnpm install --frozen-lockfile --offline lỗi (${r.error ? r.error.message : `exit ${r.status}`}${tail ? `: ${tail}` : ''}) — store thiếu gói? chạy pnpm install có mạng trong worktree` };
+  }
+  return { deps: 'pnpm', note: 'deps pnpm: đã chạy pnpm install --frozen-lockfile --offline (hardlink từ store)' };
+}
+
+/**
+ * Chuẩn bị node_modules cho worktree vừa tạo. Không ném: lỗi nào cũng thành deps none + ghi chú.
+ * Trả { deps: 'link'|'pnpm'|'none', note|null }.
+ */
+function setupDeps({ main, wtPath, mode, depsPath }) {
+  if (mode === 'none') return { deps: 'none', note: null };
+  const rel = depsPath || '.';
+  const mainDir = path.join(main, rel);
+  const wtDir = path.join(wtPath, rel);
+  if (!fs.existsSync(path.join(wtDir, 'package.json'))) return { deps: 'none', note: `deps none: không có package.json ở ${rel} (dùng --deps-path <thư mục con>)` };
+  const pnpm = fs.existsSync(path.join(wtDir, 'pnpm-lock.yaml'));
+  if (pnpm && (mode === 'auto' || mode === 'install')) return pnpmInstall(wtDir);
+  if (pnpm) return { deps: 'none', note: 'deps none: repo dùng pnpm — dùng --deps install (hoặc auto) thay cho link' };
+  if (mode === 'install') return { deps: 'none', note: 'deps none: --deps install chỉ hỗ trợ pnpm (không có pnpm-lock.yaml); repo npm dùng --deps link hoặc auto' };
+  const why = linkBlocker(mainDir, wtDir);
+  if (why) return { deps: 'none', note: `deps none: không junction được (${why}) — chạy npm ci trong worktree nếu cần` };
+  try {
+    fs.symlinkSync(path.join(mainDir, 'node_modules'), path.join(wtDir, 'node_modules'), 'junction');
+  } catch (e) {
+    return { deps: 'none', note: `deps none: tạo junction lỗi (${e.message})` };
+  }
+  return { deps: 'link', note: `deps link: ${path.join(wtDir, 'node_modules')} → ${path.join(mainDir, 'node_modules')} (junction, dùng chung, không ghi vào)` };
+}
+
+/** Bỏ một link (symlink/junction) mà không đi xuyên. Ném nếu p không phải link. */
+function unlinkOnly(p) {
+  if (!isLink(p)) throw new Error(`không phải link: ${p}`);
+  try { fs.unlinkSync(p); } catch (e) {
+    // Windows: junction/symlink thư mục đôi khi cần rmdir (RemoveDirectory chỉ bỏ reparse point, không chạm đích).
+    if (process.platform === 'win32') fs.rmdirSync(p); else throw e;
+  }
+}
+
+/**
+ * Gỡ mọi link node_modules của worktree (ở gốc và ở các deps_path) TRƯỚC `git worktree remove`.
+ * Trả [{ path, target }] để khôi phục nếu gỡ worktree thất bại. Ném nếu không gỡ được (khi đó KHÔNG được gỡ worktree).
+ */
+function unlinkDepLinks(wtPath, depsPaths) {
+  const seen = new Set();
+  const out = [];
+  for (const rel of ['.', ...(depsPaths || [])]) {
+    const p = path.join(wtPath, rel || '.', 'node_modules');
+    const key = path.resolve(p);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    if (!isLink(p)) continue;
+    let target = null;
+    try { target = fs.readlinkSync(p); } catch (_) { /* vẫn gỡ */ }
+    unlinkOnly(p);
+    if (isLink(p) || fs.existsSync(p)) throw new Error(`gỡ link ${p} không xong`);
+    out.push({ path: p, target });
+  }
+  return out;
+}
+
+/** Khôi phục link đã gỡ (best effort) khi `git worktree remove` thất bại. */
+function relink(links) {
+  for (const l of links || []) {
+    if (!l.target || fs.existsSync(l.path) || isLink(l.path)) continue;
+    try { fs.symlinkSync(l.target, l.path, 'junction'); } catch (_) { /* best effort */ }
+  }
+}
+
+/**
+ * Xoá vỏ thư mục worktree còn sót sau `git worktree remove` (git để lại junction/thư mục rỗng).
+ * Duyệt bằng lstat: link → chỉ unlink (không vào đích), file → xoá, thư mục thật → đệ quy rồi rmdir.
+ * Không bao giờ dùng rmSync recursive trên cây có thể chứa link.
+ */
+function removeShell(dir) {
+  if (isLink(dir)) { unlinkOnly(dir); return; }
+  let st;
+  try { st = fs.lstatSync(dir); } catch (_) { return; }
+  if (!st.isDirectory()) { fs.unlinkSync(dir); return; }
+  for (const name of fs.readdirSync(dir)) removeShell(path.join(dir, name));
+  fs.rmdirSync(dir);
+}
+
+module.exports = { MODES, depsModeOf, normDepsPath, setupDeps, unlinkDepLinks, relink, removeShell, isLink };

package/lib/knowledge.cjs

@@ -40,7 +40,9 @@ const KNOWLEDGE_HELP = `Cách dùng: dieu-phoi knowledge <lệnh> [--repo <đư
                          thư mục). Không --from thì tự lấy kho của khoá git-common-dir nếu có
   list [--follow] [--dirty] [--json]
                          các mục của kho (id, tiêu đề, số dòng, sha#rev, tags, paths) + repo liên quan (related),
-                         mỗi mục gắn ok / STALE / ? (độ tươi so với HEAD của worktree đang đứng)
+                         mỗi mục gắn ok / STALE / drift / ? (độ tươi so với HEAD của worktree đang đứng; drift = chỉ file
+                         file đổi nhưng không làm mục stale: glob, bản version, CHANGELOG, dòng không nêu tên mục);
+                         cuối dòng tổng: số mục không stale
   status [--follow] [--dirty] [--no-cache] [--json]
                          chỉ độ tươi: mục nào stale (file nào đổi sau sha của mục), mục nào không xác định (sha không
                          có trong repo này…). Một tiến trình git (diff-tree --no-renames, pathspec = paths của các mục),
@@ -60,6 +62,8 @@ const KNOWLEDGE_HELP = `Cách dùng: dieu-phoi knowledge <lệnh> [--repo <đư
                          "## +id" thêm mục (bắt buộc paths:), "## id" thay mục (bắt buộc base: <sha>#<rev>); base cũ
                          → xung đột, không ghi đè; mục > 40 dòng bị từ chối. Có xung đột/từ chối → exit 2.
                          Idempotent: file delta đã gộp (hash trong meta.json) và mục trùng một rev cũ trong history/ → "không đổi"
+  review <id> [--repo]   đánh dấu mục đã xem xét: reviewed_sha = HEAD hiện tại (ghi dưới khoá kho); độ tươi chỉ tính thay đổi sau sha đó.
+                         Mục bị thay bằng merge sẽ mất dấu này. Không đổi nội dung mục.
   bootstrap [--children <mẫu tên>[,…]] [--json]
                          chỉ đọc: liệt kê nguồn để seed kho (CLAUDE.md/README/AGENTS.md của repo, context-r/contract/
                          handoff cũ trong runs có nhắc repo), mục đã có, mục nên có và mẫu delta. --children: repo anh em
@@ -272,7 +276,10 @@ function sectionOut(repo, sec, body, fr) {
   const f = fr && fr.sections && fr.sections[sec.id];
   if (f) {
     out.fresh = f.state;
-    if (f.files) { out.stale = f.files; out.stale_count = f.n_files || f.files.length; }
+    if (f.files) {
+      const k = f.state === 'drift' ? 'drift' : 'stale';
+      out[k] = f.files; out[`${k}_count`] = f.n_files || f.files.length;
+    }
     if (f.why) out.fresh_why = f.why;
     if (f.dirty) out.dirty = f.dirty;
   }
@@ -299,6 +306,7 @@ function freshnessOf(storeDir, idx, start, opts) {
 
 function freshLine(s) {
   if (s.fresh === 'stale') return `STALE — ${s.stale_count} file đổi sau sha của mục: ${core.shortFileList(s.stale, 5)} (kiểm lại trước khi dùng)`;
+  if (s.fresh === 'drift') return `drift — ${s.drift_count} file đổi nhưng không tính stale: ${core.shortFileList(s.drift, 5)}`;
   if (s.fresh === 'unknown') return `độ tươi: không xác định — ${s.fresh_why}`;
   if (s.fresh === 'fresh') return 'độ tươi: tươi';
   return null;
@@ -415,7 +423,7 @@ function cmdGet(opts) {
   return { code, out: parts.join('\n\n') };
 }
 
-const FRESH_MARK = { fresh: 'ok   ', stale: 'STALE', unknown: '?    ' };
+const FRESH_MARK = { fresh: 'ok   ', stale: 'STALE', drift: 'drift', unknown: '?    ' };
 
 function listLines(idx, fr, dir) {
   return idx.sections.map((s) => {
@@ -429,7 +437,8 @@ function listLines(idx, fr, dir) {
 function freshHeader(fr, n) {
   if (!fr) return '';
   const head = fr.head ? `HEAD ${fr.head.slice(0, 7)}${fr.branch ? ` (${fr.branch})` : ''}` : 'HEAD ?';
-  return `${head} · ${core.knowledgeSummary(fr, n)} · ${fr.cached ? 'cache' : `tính mới${fr.ms_git ? ` (git ${fr.ms_git} ms)` : ''}`}${fr.error ? ` · git lỗi: ${fr.error}` : ''}`;
+  const notStale = n - ((fr.counts && fr.counts.stale) || 0);
+  return `${head} · ${core.knowledgeSummary(fr, n)} · ${notStale} không stale · ${fr.cached ? 'cache' : `tính mới${fr.ms_git ? ` (git ${fr.ms_git} ms)` : ''}`}${fr.error ? ` · git lỗi: ${fr.error}` : ''}`;
 }
 
 /** Details under list/status: stale files, unknown reasons, uncommitted files (--dirty). */
@@ -440,6 +449,7 @@ function freshDetails(idx, fr) {
     const f = fr.sections[s.id];
     if (!f) continue;
     if (f.state === 'stale') out.push(`    ${s.id}: ${f.n_files || f.files.length} file đổi — ${core.shortFileList(f.files, 5)}`);
+    else if (f.state === 'drift') out.push(`    ${s.id}: drift (không tính stale) — ${f.n_files || f.files.length} file đổi — ${core.shortFileList(f.files, 5)}`);
     else if (f.state === 'unknown') out.push(`    ${s.id}: không xác định — ${f.why}`);
     if (f.dirty) out.push(`    ${s.id}: chưa commit — ${core.shortFileList(f.dirty, 5)}`);
   }
@@ -1035,6 +1045,38 @@ function cmdLink(opts) {
   return { code: 0, out: `${verb}: ${other.name} là ${opts.rel === 'child' ? 'con' : 'cha'} của ${info.name}${a.changed || b.changed ? '' : ' (không đổi)'}.` };
 }
 
+/**
+ * Review mark (s6): records reviewed_sha = HEAD of the checkout around --repo on one section, under the store lock.
+ * freshness then counts only the changes after that sha. Body, paths and base are untouched; a merge that replaces the
+ * section writes a new entry without the mark, so new content is never shown as reviewed.
+ */
+function cmdReview(opts) {
+  const { start, info } = infoOf(opts, false);
+  if (!info) return notRepo(start);
+  const ids = opts._.map(String).filter((t) => t.trim());
+  if (ids.length !== 1 || !ID_RE.test(ids[0])) return { code: 1, out: `Cần đúng một <id> mục.\n\n${KNOWLEDGE_HELP.trimEnd()}` };
+  const id = ids[0];
+  const g = core.findGit(start);
+  const h = g ? core.readHead(g) : null;
+  const sha = h && h.sha ? h.sha : (h && h.unsupported ? headShaOf(start) : null);
+  if (!sha || !/^[0-9a-f]{40,64}$/i.test(sha)) return { code: 1, out: 'Không đọc được HEAD đầy đủ của repo (chưa có commit?).' };
+  const ri = readIndex(info.dir);
+  if (ri.error) return { code: 1, out: ri.error };
+  if (!ri.exists) return { code: 1, out: `Kho chưa có mục nào: ${info.dir}.` };
+  const lk = withLock(path.join(info.dir, 'knowledge.lock'), () => {
+    const cur = readIndex(info.dir);
+    if (cur.error) return { code: 1, out: cur.error };
+    const at = cur.idx.sections.findIndex((s) => s.id === id);
+    if (at < 0) return { code: 1, out: `Chưa có mục ${id} trong kho ${info.name}.` };
+    const prev = cur.idx.sections[at].reviewed_sha || null;
+    cur.idx.sections[at] = Object.assign({}, cur.idx.sections[at], { reviewed_sha: sha.toLowerCase(), reviewed_at: new Date().toISOString() });
+    core.writeFileAtomic(path.join(info.dir, 'index.json'), `${JSON.stringify(cur.idx, null, 2)}\n`);
+    return { code: 0, out: `review ${id}: reviewed_sha ${shortSha(sha)}${prev ? ` (trước: ${shortSha(prev)})` : ''}` };
+  }, LOCK_TRIES);
+  if (lk.locked) return { code: 1, out: 'Kho đang bị khoá (knowledge.lock), thử lại.' };
+  return lk.value;
+}
+
 function cmdKnowledge(opts) {
   const sub = opts._.shift();
   if (!sub || opts.help || opts.h || sub === 'help') {
@@ -1045,6 +1087,7 @@ function cmdKnowledge(opts) {
   if (sub === 'get') return cmdGet(opts);
   if (sub === 'list') return cmdList(opts);
   if (sub === 'status') return cmdStatus(opts);
+  if (sub === 'review') return cmdReview(opts);
   if (sub === 'merge') return cmdMerge(opts);
   if (sub === 'link') return cmdLink(opts);
   if (sub === 'bootstrap') return cmdBootstrap(opts);

package/lib/load.cjs

@@ -0,0 +1,332 @@
+'use strict';
+// core 0.7.3 (s5): đo tải để kiểm giả thuyết (contract jiptvo5g, mục 1) — số agent đồng thời và IO đĩa.
+//   dieu-phoi load sample [--interval 10] [--count 12] [--repo R] [--json]  → data/load.jsonl, một mẫu một dòng
+//   dieu-phoi load report [--days 21] [--json]                              → phút ở mỗi mức đồng thời + tương quan IO
+// Mẫu chỉ chứa số đếm và tốc độ IO: không có đường dẫn, prompt hay nội dung task (log không lộ nội dung).
+// Hook SubagentStart ghi thêm mẫu chỉ-số-đếm (không IO) qua hook.cjs appendLoadSample.
+
+const fs = require('fs');
+const cp = require('child_process');
+const core = require('../hook.cjs');
+const args = require('./args.cjs');
+const { mainCheckoutOf, markedWorktrees } = require('./worktree.cjs');
+
+const DISK_READ = '\\PhysicalDisk(_Total)\\Disk Read Bytes/sec';
+const DISK_WRITE = '\\PhysicalDisk(_Total)\\Disk Write Bytes/sec';
+const PROC_DISKSTATS = '/proc/diskstats';
+const SECTOR_BYTES = 512;
+const DISK_WINDOW_MS = 1000;
+/** Dispatch chưa có complete: tính tối đa bằng này (= stuck_hard_min mặc định của s6). */
+const OPEN_CAP_MS = 120 * 60 * 1000;
+const MIN_MS = 60 * 1000;
+const WHOLE_DISK_RE = /^(sd[a-z]+|vd[a-z]+|xvd[a-z]+|hd[a-z]+|nvme\d+n\d+|mmcblk\d+)$/;
+const MB = 1024 * 1024;
+
+function sleepSync(ms) {
+  if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function num(s) {
+  const t = String(s === undefined || s === null ? '' : s).trim();
+  return t === '' ? NaN : Number(t);
+}
+
+/** typeperf CSV: the last data row ("<date>","<read>","<write>") → {read, write}, or null. */
+function parseTypeperf(text) {
+  let row = null;
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const m = /^"(\d[^"]*)","([^"]*)","([^"]*)"$/.exec(line.trim());
+    if (m) row = m;
+  }
+  if (!row) return null;
+  const read = num(row[2]);
+  const write = num(row[3]);
+  if (!Number.isFinite(read) || !Number.isFinite(write)) return null;
+  return { read, write };
+}
+
+/** /proc/diskstats → byte totals over whole disks only (partitions, loop and ram devices skipped), or null. */
+function parseDiskstats(text) {
+  let read = 0;
+  let write = 0;
+  let any = false;
+  for (const line of String(text || '').split('\n')) {
+    const p = line.trim().split(/\s+/);
+    if (p.length < 10 || !WHOLE_DISK_RE.test(p[2])) continue;
+    read += Number(p[5]) * SECTOR_BYTES;
+    write += Number(p[9]) * SECTOR_BYTES;
+    any = true;
+  }
+  return any ? { read, write } : null;
+}
+
+function typeperfRates() {
+  const out = cp.execFileSync('typeperf', [DISK_READ, DISK_WRITE, '-sc', '1'], {
+    encoding: 'utf8', windowsHide: true, timeout: 15000, stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  return parseTypeperf(out);
+}
+
+function readDiskstats() {
+  try { return parseDiskstats(fs.readFileSync(PROC_DISKSTATS, 'utf8')); } catch (_) { return null; }
+}
+
+/**
+ * Bytes/s over one window. Windows: typeperf samples the window itself. POSIX: /proc/diskstats read twice around a
+ * DISK_WINDOW_MS sleep. Anything missing → null (never throws). deps lets the tests inject the platform and readers.
+ */
+function diskRates(deps) {
+  const d = deps || {};
+  const platform = d.platform || process.platform;
+  let r = null;
+  try {
+    if (platform === 'win32') {
+      r = (d.typeperf || typeperfRates)();
+    } else {
+      const read = d.readDiskstats || readDiskstats;
+      const a = read();
+      (d.sleep || sleepSync)(DISK_WINDOW_MS);
+      const b = read();
+      if (a && b) {
+        const secs = DISK_WINDOW_MS / 1000;
+        r = { read: (b.read - a.read) / secs, write: (b.write - a.write) / secs };
+      }
+    }
+  } catch (_) {
+    r = null;
+  }
+  if (!r) return { disk_read_Bps: null, disk_write_Bps: null };
+  return {
+    disk_read_Bps: Math.max(0, Math.round(r.read)),
+    disk_write_Bps: Math.max(0, Math.round(r.write)),
+  };
+}
+
+/** Marked worktrees that still exist in the repo at `repoDir`, or null when it is not a git checkout. */
+function markedCount(repoDir) {
+  try {
+    const { common } = mainCheckoutOf(repoDir);
+    return markedWorktrees(common).filter((w) => w.exists).length;
+  } catch (_) {
+    return null;
+  }
+}
+
+/** One sample: counts (liveLoadCounts) + IO rates + marked worktrees. */
+function collectSample(ctx, o) {
+  const now = Date.now();
+  const counts = core.liveLoadCounts(ctx, now);
+  const io = diskRates(o.deps);
+  return Object.assign({ ts: new Date(now).toISOString(), src: 'sample' }, counts,
+    { worktrees_marked: markedCount(o.repo) }, io);
+}
+
+/** Takes `count` samples `interval` seconds apart (start to start) and appends each to data/load.jsonl. */
+function sampleLoop(ctx, o) {
+  const file = core.loadFile(ctx);
+  fs.mkdirSync(ctx.paths.data, { recursive: true });
+  const recs = [];
+  for (let i = 0; i < o.count; i++) {
+    const t0 = Date.now();
+    const rec = collectSample(ctx, o);
+    fs.appendFileSync(file, `${JSON.stringify(rec)}\n`);
+    recs.push(rec);
+    if (i < o.count - 1) sleepSync(Math.max(0, o.interval * 1000 - (Date.now() - t0)));
+  }
+  return recs;
+}
+
+function numArg(v, dflt, name, min, max) {
+  if (v === undefined) return dflt;
+  const n = num(v);
+  if (!Number.isFinite(n) || n < min || n > max) throw new Error(`--${name} phải là số trong [${min}, ${max}]`);
+  return n;
+}
+
+function mbps(v) {
+  return Number.isFinite(v) ? `${(v / MB).toFixed(2)} MB/s` : 'n/a';
+}
+
+function cmdLoadSample(opts, deps) {
+  const ctx = args.ctxOf(opts);
+  const count = Math.floor(numArg(opts.count, 12, 'count', 1, 100000));
+  const interval = numArg(opts.interval, 10, 'interval', 0, 86400);
+  const repo = args.repoOf(opts);
+  const recs = sampleLoop(ctx, { count, interval, repo, deps });
+  if (opts.json) return { code: 0, out: JSON.stringify(recs, null, 2) };
+  const lines = recs.map((r) => `  ${r.ts} · máy ${r.live_machine} · hàng đợi ${r.queue} · đọc ${mbps(r.disk_read_Bps)} · ghi ${mbps(r.disk_write_Bps)}`);
+  return { code: 0, out: `dieu-phoi load sample: ${recs.length} mẫu → ${core.loadFile(ctx)}\n${lines.join('\n')}` };
+}
+
+/** Dispatch/complete events → intervals. A complete closes the oldest open dispatch of the same session+task+role. */
+function pairIntervals(events, nowMs) {
+  const sorted = events.slice().sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts));
+  const open = new Map();
+  const out = [];
+  for (const e of sorted) {
+    const t = Date.parse(e.ts);
+    const key = `${e.session || ''}|${e.task_id || ''}|${e.role || ''}`;
+    if (e.kind === 'dispatch') {
+      if (!open.has(key)) open.set(key, []);
+      open.get(key).push({ t, session: e.session || '-' });
+    } else {
+      const q = open.get(key);
+      if (q && q.length) {
+        const s = q.shift();
+        out.push({ s: s.t, e: t, session: s.session, paired: true });
+      }
+    }
+  }
+  let unpaired = 0;
+  for (const q of open.values()) {
+    for (const s of q) {
+      unpaired += 1;
+      out.push({ s: s.t, e: Math.min(s.t + OPEN_CAP_MS, nowMs), session: s.session, paired: false });
+    }
+  }
+  return { intervals: out, unpaired };
+}
+
+function addMs(map, level, ms) {
+  map.set(level, (map.get(level) || 0) + ms);
+}
+
+/** Milliseconds at each concurrency level: machine (every interval) and busiest session (max over sessions). */
+function levelTimes(intervals) {
+  const marks = [];
+  for (const iv of intervals) {
+    marks.push({ t: iv.s, d: 1, sess: iv.session });
+    marks.push({ t: iv.e, d: -1, sess: iv.session });
+  }
+  marks.sort((a, b) => (a.t - b.t) || (a.d - b.d)); // ends before starts at the same instant
+  const machine = new Map();
+  const busiest = new Map();
+  const perSession = new Map();
+  let cur = 0;
+  let maxS = 0;
+  let last = null;
+  for (const m of marks) {
+    if (last !== null && m.t > last) {
+      if (cur > 0) addMs(machine, cur, m.t - last);
+      if (maxS > 0) addMs(busiest, maxS, m.t - last);
+    }
+    last = m.t;
+    cur += m.d;
+    perSession.set(m.sess, (perSession.get(m.sess) || 0) + m.d);
+    maxS = 0;
+    for (const v of perSession.values()) if (v > maxS) maxS = v;
+  }
+  return { machine, busiest };
+}
+
+function pearson(xs, ys) {
+  const n = xs.length;
+  if (n < 3) return null;
+  const mx = xs.reduce((a, b) => a + b, 0) / n;
+  const my = ys.reduce((a, b) => a + b, 0) / n;
+  let cov = 0;
+  let vx = 0;
+  let vy = 0;
+  for (let i = 0; i < n; i++) {
+    cov += (xs[i] - mx) * (ys[i] - my);
+    vx += (xs[i] - mx) ** 2;
+    vy += (ys[i] - my) ** 2;
+  }
+  if (vx === 0 || vy === 0) return null;
+  return cov / Math.sqrt(vx * vy);
+}
+
+function readLoadSamples(ctx, sinceMs) {
+  let text = '';
+  try { text = fs.readFileSync(core.loadFile(ctx), 'utf8'); } catch (_) { return []; }
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let r = null;
+    try { r = JSON.parse(line); } catch (_) { continue; }
+    if (r && Date.parse(r.ts) >= sinceMs) out.push(r);
+  }
+  return out;
+}
+
+/** Correlation of disk read with the machine's live agent count, on samples that carry both. */
+function ioCorrelation(samples) {
+  const rows = samples.filter((r) => Number.isFinite(r.live_machine) && Number.isFinite(r.disk_read_Bps));
+  const byLevel = new Map();
+  for (const r of rows) {
+    const g = byLevel.get(r.live_machine) || { n: 0, read: 0, write: 0, writeN: 0 };
+    g.n += 1;
+    g.read += r.disk_read_Bps;
+    if (Number.isFinite(r.disk_write_Bps)) { g.write += r.disk_write_Bps; g.writeN += 1; }
+    byLevel.set(r.live_machine, g);
+  }
+  const levels = [...byLevel.entries()].sort((a, b) => a[0] - b[0]).map(([level, g]) => ({
+    live_machine: level,
+    samples: g.n,
+    mean_read_Bps: Math.round(g.read / g.n),
+    mean_write_Bps: g.writeN ? Math.round(g.write / g.writeN) : null,
+  }));
+  return {
+    samples: rows.length,
+    r: pearson(rows.map((r) => r.live_machine), rows.map((r) => r.disk_read_Bps)),
+    levels,
+  };
+}
+
+function cmdLoadReport(opts) {
+  const ctx = args.ctxOf(opts);
+  const days = numArg(opts.days, 21, 'days', 0.01, 3650);
+  const now = Date.now();
+  const since = now - days * 86400000;
+  const events = core.readEvents(ctx).filter((e) => e && (e.kind === 'dispatch' || e.kind === 'complete')
+    && Date.parse(e.ts) >= since);
+  const { intervals, unpaired } = pairIntervals(events, now);
+  const { machine, busiest } = levelTimes(intervals);
+  const toMin = (ms) => Math.round(ms / MIN_MS * 10) / 10;
+  const levels = new Map();
+  for (const k of new Set([...machine.keys(), ...busiest.keys()])) {
+    levels.set(k, { machine_min: toMin(machine.get(k) || 0), busiest_session_min: toMin(busiest.get(k) || 0) });
+  }
+  const atLeast = (m, n) => toMin([...m.entries()].filter(([k]) => k >= n).reduce((a, [, v]) => a + v, 0));
+  const samples = readLoadSamples(ctx, since);
+  const corr = ioCorrelation(samples);
+  const summary = {
+    days,
+    pairs: intervals.filter((i) => i.paired).length,
+    unpaired,
+    machine_min_at_least: { 7: atLeast(machine, 7), 9: atLeast(machine, 9) },
+    session_min_at_least: { 4: atLeast(busiest, 4) },
+    levels: [...levels.entries()].sort((a, b) => a[0] - b[0]).map(([level, v]) => Object.assign({ level }, v)),
+    load: { samples: samples.length, io_samples: corr.samples, r: corr.r === null ? null : Math.round(corr.r * 100) / 100, by_machine: corr.levels },
+  };
+  if (opts.json) return { code: 0, out: JSON.stringify(summary, null, 2) };
+  return { code: 0, out: formatReport(summary) };
+}
+
+function formatReport(s) {
+  const head = `dieu-phoi load report — ${s.days} ngày · ${s.pairs} agent có cả dispatch và complete · ${s.unpaired} dispatch chưa đóng (tính tối đa 120 phút)`;
+  const rows = ['Đồng thời | toàn máy (phút) | phiên lớn nhất (phút)', '---|---|---'];
+  for (const l of s.levels) rows.push(`${l.level} | ${l.machine_min} | ${l.busiest_session_min}`);
+  if (!s.levels.length) rows.push('(không có agent trong khoảng này)');
+  const mark = `Mốc: toàn máy ≥7 agent ${s.machine_min_at_least[7]} phút · toàn máy ≥9 ${s.machine_min_at_least[9]} phút · một phiên ≥4 ${s.session_min_at_least[4]} phút`;
+  const ld = s.load;
+  const corrLine = ld.io_samples < 3
+    ? `Tải IO: ${ld.samples} mẫu trong data/load.jsonl, ${ld.io_samples} có IO đĩa — chưa đủ để tương quan (chạy \`dieu-phoi load sample\`).`
+    : `Tải IO: ${ld.io_samples} mẫu có IO · tương quan r(agent toàn máy, đọc đĩa) = ${ld.r === null ? 'n/a' : ld.r} (chỉ báo: IO là của cả máy, không riêng agent).`;
+  const lvl = ld.by_machine.map((g) => `${g.live_machine} | ${g.samples} | ${(g.mean_read_Bps / MB).toFixed(2)} | ${g.mean_write_Bps === null ? 'n/a' : (g.mean_write_Bps / MB).toFixed(2)}`);
+  const lvlTable = lvl.length ? ['Agent toàn máy | mẫu | đọc TB (MB/s) | ghi TB (MB/s)', '---|---|---|---', ...lvl] : [];
+  return [head, '', ...rows, '', mark, '', corrLine, ...lvlTable].join('\n');
+}
+
+function cmdLoad(opts) {
+  const sub = opts._[0];
+  if (sub === 'sample') return cmdLoadSample(opts);
+  if (sub === 'report') return cmdLoadReport(opts);
+  throw new Error('Cú pháp: dieu-phoi load sample [--interval 10] [--count 12] [--repo R] [--json]\n'
+    + '         dieu-phoi load report [--days 21] [--json]');
+}
+
+module.exports = {
+  cmdLoad, cmdLoadSample, cmdLoadReport, parseTypeperf, parseDiskstats, diskRates, collectSample, sampleLoop,
+  pairIntervals, levelTimes, pearson, ioCorrelation, readLoadSamples, DISK_READ, DISK_WRITE, OPEN_CAP_MS,
+};