@kienntpixon/dieu-phoi 0.7.1 → 0.7.3

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

@@ -574,10 +574,9 @@ function runDirOf(v) {
   return isDir(p) ? { dir: p } : { error: `Không thấy run ${s} (${slash(p)}).` };
 }
 
-/** Task id a delta file belongs to: knowledge-delta-<task_id>[-r<n>].md (8 chars a-z0-9); null = untagged. */
+/** Task id a delta file belongs to: knowledge-delta-<task_id>[-r<n>|-h<n>].md (8 chars a-z0-9; -h<n> = handoff); null = untagged. */
 function deltaTaskOf(file) {
-  const m = /^knowledge-delta-([a-z0-9]{8})(?:-r\d+)?\.md$/i.exec(path.basename(file));
-  return m ? m[1].toLowerCase() : null;
+  return core.deltaTagOf(file);
 }
 
 /**
@@ -585,7 +584,7 @@ function deltaTaskOf(file) {
  * tagged with one of them (plus untagged ones when untagged is true).
  */
 function deltaFiles(runDir, filter) {
-  const num = (f) => { const m = /-r(\d+)\.md$/i.exec(f); return m ? Number(m[1]) : 0; };
+  const num = (f) => { const m = /-[rh](\d+)\.md$/i.exec(f); return m ? Number(m[1]) : 0; };
   return fs.readdirSync(runDir)
     .filter((f) => /^knowledge-delta.*\.md$/i.test(f))
     .filter((f) => {

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,
+};