@kienntpixon/dieu-phoi 0.0.0-stage → 0.1.0

package/lib/commands.cjs

@@ -0,0 +1,626 @@
+'use strict';
+
+const fs = require('fs');
+const cp = require('child_process');
+const crypto = require('crypto');
+const path = require('path');
+const core = require('../hook.cjs');
+const agg = require('./aggregate.cjs');
+const chooser = require('./choose.cjs');
+const setupLib = require('./setup.cjs');
+const { claudeDirOf, ctxOf, yesNo } = require('./args.cjs');
+
+const AGENT_OUTCOMES = ['pass', 'fail', 'timeout'];
+const USER_OUTCOMES = ['accept', 'reject'];
+const CAUSES = ['quality', 'scope'];
+const STEER_KINDS = ['minor', 'plan', 'redirect'];
+const VERIFY = ['tests', 'lint', 'review', 'judgment', 'none'];
+
+function skillDirOf(opts, ctx) {
+  if (typeof opts['skill-dir'] === 'string') return path.resolve(opts['skill-dir']);
+  if (ctx.config.skill_dir && fs.existsSync(path.join(ctx.config.skill_dir, 'profile', 'profile.json'))) {
+    return ctx.config.skill_dir;
+  }
+  return setupLib.findSkillDir(claudeDirOf(opts)) || ctx.config.skill_dir || null;
+}
+
+function fmtUsd(v) {
+  return v === null || v === undefined ? '-' : `$${v.toFixed(v < 1 ? 3 : 2)}`;
+}
+
+function fmtNum(v, d) {
+  return v === null || v === undefined ? '-' : v.toFixed(d === undefined ? 1 : d);
+}
+
+function table(rows) {
+  const widths = rows[0].map((_, i) => Math.max(...rows.map((r) => String(r[i]).length)));
+  return rows.map((r) => r.map((c, i) => String(c).padEnd(widths[i])).join('  ').trimEnd()).join('\n');
+}
+
+// ------------------------------------------------------------------ setup / uninstall
+
+function cmdSetup(opts) {
+  const res = setupLib.setup({
+    claudeDir: claudeDirOf(opts),
+    dept: typeof opts.dept === 'string' ? opts.dept : undefined,
+    sinkUrl: typeof opts['sink-url'] === 'string' ? opts['sink-url'] : undefined,
+    sinkToken: typeof opts['sink-token'] === 'string' ? opts['sink-token'] : undefined,
+    skillDir: typeof opts['skill-dir'] === 'string' ? opts['skill-dir'] : undefined,
+  });
+  if (opts.json) {
+    const safe = Object.assign({}, res, { config: Object.assign({}, res.config) });
+    if (safe.config.sink_token) safe.config.sink_token = '***';
+    return { code: 0, out: JSON.stringify(safe, null, 2) };
+  }
+  const lines = [
+    `Đã cài hook: ${res.hook}`,
+    res.settings_changed
+      ? `Đã đăng ký PostToolUse(Agent) + SubagentStop trong ${res.settings}${res.backup ? ` (sao lưu: ${path.basename(res.backup)})` : ''}`
+      : `settings.json đã có hook, không đổi gì (${res.settings})`,
+    `Phòng ban: ${res.config.dept || '(chưa đặt, dùng --dept)'}`,
+    `Sink: ${res.config.sink_url ? res.config.sink_url : '(chưa có — log chỉ lưu cục bộ)'}`,
+    `Skill: ${res.config.skill_dir || '(không thấy; dùng --skill-dir)'}${res.config.skill_version ? ` v${res.config.skill_version}` : ''}`,
+    'Khởi động lại Claude Code (hoặc mở /hooks) để hook có hiệu lực.',
+  ];
+  return { code: 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) };
+  return {
+    code: 0,
+    out: res.removed
+      ? `Đã gỡ ${res.removed} hook khỏi ${res.settings}${res.backup ? ` (sao lưu: ${path.basename(res.backup)})` : ''}. Dữ liệu giữ ở ${res.data_kept}.`
+      : `Không thấy hook dieu-phoi trong ${res.settings}.`,
+  };
+}
+
+// ------------------------------------------------------------------ doctor
+
+async function cmdDoctor(opts) {
+  const ctx = ctxOf(opts);
+  const claudeDir = claudeDirOf(opts);
+  const checks = [];
+  const add = (ok, name, detail, level) => checks.push({ ok, level: ok ? 'OK' : (level || 'LỖI'), name, detail });
+  const major = Number(process.versions.node.split('.')[0]);
+  add(major >= 18, 'node', `v${process.versions.node}${major >= 18 ? '' : ' (cần ≥ 18)'}`);
+  add(fs.existsSync(ctx.paths.hook), 'hook', ctx.paths.hook);
+  const reg = setupLib.registration(claudeDir);
+  add(reg.PostToolUse && reg.SubagentStop, 'settings',
+    `PostToolUse(Agent)=${reg.PostToolUse ? 'có' : 'thiếu'}, SubagentStop=${reg.SubagentStop ? 'có' : 'thiếu'} (${reg.file})`);
+  const hasCfg = fs.existsSync(ctx.paths.config);
+  add(hasCfg, 'config', hasCfg ? `${ctx.paths.config} dept=${ctx.config.dept || '-'}` : 'chưa có — chạy `dieu-phoi setup`');
+  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');
+  if (reg.commands.length) {
+    const cmd = reg.commands[0];
+    const t0 = Date.now();
+    const r = cp.spawnSync(cmd, {
+      shell: true, input: '{}', encoding: 'utf8', timeout: 10000, windowsHide: true,
+    });
+    const ms = Date.now() - t0;
+    const ok = r.status === 0 && !r.error && !(r.stdout || '').trim();
+    add(ok, 'hook-run', ok ? `chạy lệnh đã đăng ký với {} → exit 0, không in stdout (${ms} ms)`
+      : `chạy \`${cmd}\` lỗi: exit=${r.status}${r.error ? ` ${r.error.message}` : ''}${(r.stdout || '').trim() ? ' (có stdout)' : ''} ${(r.stderr || '').trim().slice(0, 200)}`);
+  }
+  let rejectedLines = [];
+  try {
+    rejectedLines = fs.readFileSync(ctx.paths.syncRejected, 'utf8').split(/\r?\n/).filter((l) => l.trim());
+  } catch (_) { /* none */ }
+  const rejectedCount = rejectedLines.reduce((n, l) => {
+    try { const o = JSON.parse(l); return n + (o.unidentified || 1); } catch (_) { return n + 1; }
+  }, 0);
+  add(rejectedCount === 0, 'sync-rejected', rejectedCount
+    ? `sink từ chối ${rejectedCount} bản ghi — xem ${ctx.paths.syncRejected}` : 'không có bản ghi bị sink từ chối', 'CẢNH BÁO');
+  const events = core.readEvents(ctx);
+  const un = core.unsyncedInfo(ctx);
+  add(true, 'events', `${events.length} bản ghi, ${un.lines} chưa đẩy lên sink (${un.bytes} byte sau offset) (${ctx.paths.events})`);
+  let errSize = 0;
+  try { errSize = fs.statSync(ctx.paths.errlog).size; } catch (_) { /* none */ }
+  add(errSize === 0, 'hook-errors', errSize ? `${ctx.paths.errlog} có ${errSize} byte lỗi` : 'không có lỗi', 'CẢNH BÁO');
+  if (ctx.config.sink_url && ctx.config.sink_token) {
+    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 txt = await res.text();
+      let ok = res.ok;
+      try { const b = JSON.parse(txt); if (b && b.ok === false) ok = false; } catch (_) { ok = false; }
+      add(ok, 'sink', `${ctx.config.sink_url} → HTTP ${res.status}`);
+    } catch (e) {
+      add(false, 'sink', `${ctx.config.sink_url} → ${e.message}`);
+    }
+  } else {
+    add(true, 'sink', 'chưa cấu hình (chỉ lưu cục bộ)');
+  }
+  const failed = checks.some((c) => c.level === 'LỖI');
+  if (opts.json) return { code: failed ? 1 : 0, out: JSON.stringify({ ok: !failed, checks }, null, 2) };
+  const out = checks.map((c) => `[${c.level}] ${c.name}: ${c.detail}`).join('\n');
+  return { code: failed ? 1 : 0, out };
+}
+
+// ------------------------------------------------------------------ hook / sync
+
+function cmdHook(opts) {
+  const home = typeof opts['claude-dir'] === 'string' ? path.join(path.resolve(opts['claude-dir']), 'dieu-phoi') : undefined;
+  core.runHook({ home });
+  return { code: 0, out: null };
+}
+
+async function cmdSync(opts) {
+  const ctx = ctxOf(opts);
+  const res = await core.runSync(ctx);
+  if (opts.json) return { code: res.ok ? 0 : 1, out: JSON.stringify(res) };
+  if (res.skipped === 'no-sink') return { code: 0, out: 'Chưa cấu hình sink — không đẩy gì.' };
+  if (res.skipped === 'locked') return { code: 0, out: 'Đang có tiến trình sync khác — bỏ qua.' };
+  const msg = `Đã đẩy ${res.sent} bản ghi trong ${res.batches} lô (nhận ${res.accepted}, trùng ${res.duplicates}).`;
+  return { code: res.ok ? 0 : 1, out: res.ok ? msg : `${msg} Lỗi: ${res.error}` };
+}
+
+// ------------------------------------------------------------------ verdict
+
+const LAST_WINDOW_MS = 30 * 60 * 1000;
+
+/**
+ * `last`: the most recent completed agent. Refuses when more than one agent completed in
+ * the last 30 min without a verdict (ambiguous: give the agent_id explicitly).
+ */
+function resolveAgentId(events, ref, now) {
+  if (ref === 'last') {
+    const latest = new Map();
+    const verdicted = new Set();
+    events.forEach((e, i) => {
+      if (!e.agent_id) return;
+      if (e.kind === 'verdict' && agg.normalizeVerdict(e).by === 'agent') verdicted.add(e.agent_id);
+      if (e.kind !== 'complete') return;
+      const t = Date.parse(e.ts) || 0;
+      const cur = latest.get(e.agent_id);
+      if (!cur || t > cur.t || (t === cur.t && i > cur.i)) latest.set(e.agent_id, { id: e.agent_id, t, i, ev: e });
+    });
+    if (!latest.size) throw new Error('Chưa có agent nào hoàn thành trong log.');
+    const nowMs = now || Date.now();
+    const pending = Array.from(latest.values())
+      .filter((x) => !verdicted.has(x.id) && nowMs - x.t <= LAST_WINDOW_MS)
+      .sort((a, b) => b.t - a.t || b.i - a.i);
+    if (pending.length > 1) {
+      const list = pending.slice(0, 10).map((x) => `  ${x.id}  ${x.ev.task_type || '?'}${x.ev.task_id ? ` task=${x.ev.task_id}` : ''}${x.ev.try ? ` try${x.ev.try}` : ''}  ${new Date(x.t).toISOString()}`);
+      throw new Error(`"last" không rõ: ${pending.length} agent hoàn thành trong 30 phút qua chưa có verdict. Ghi rõ agent_id:\n${list.join('\n')}`);
+    }
+    if (pending.length === 1) return pending[0].id;
+    let best = null;
+    for (const x of latest.values()) if (!best || x.t > best.t || (x.t === best.t && x.i > best.i)) best = x;
+    return best.id;
+  }
+  const ids = new Set(events.filter((e) => e.kind === 'dispatch' || e.kind === 'complete')
+    .map((e) => e.agent_id).filter(Boolean));
+  if (ids.has(ref)) return ref;
+  const pref = Array.from(ids).filter((id) => ref.length >= 4 && id.startsWith(ref));
+  if (pref.length === 1) return pref[0];
+  if (pref.length > 1) throw new Error(`agent_id "${ref}" khớp nhiều agent: ${pref.slice(0, 5).join(', ')}`);
+  throw new Error(`Không thấy agent "${ref}" trong log.`);
+}
+
+function kebab(s) {
+  if (typeof s !== 'string') return null;
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || null;
+}
+
+function verdictAgent(opts, ctx, events) {
+  const [ref, outcome] = opts._;
+  if (!ref || !outcome) {
+    throw new Error('Cú pháp: dieu-phoi verdict <agent_id|last> <pass|fail|timeout> [--verify V] [--reason R]\n'
+      + '         dieu-phoi verdict --task <task_id> <accept|reject> [--cause quality|scope] [--round n]');
+  }
+  if (outcome === 'rework') {
+    throw new Error('"rework" đã bỏ. Người dùng không nhận kết quả → dieu-phoi verdict --task <task_id> reject --cause quality');
+  }
+  if (!AGENT_OUTCOMES.includes(outcome)) throw new Error(`outcome tầng agent phải là ${AGENT_OUTCOMES.join('|')} (accept/reject dùng --task)`);
+  const verify = typeof opts.verify === 'string' ? opts.verify : 'none';
+  if (!VERIFY.includes(verify)) throw new Error(`--verify phải là ${VERIFY.join('|')}`);
+  const agentId = resolveAgentId(events, ref);
+  const agent = agg.buildAgents(events).agents.find((a) => a.agent_id === agentId);
+  return Object.assign({
+    schema: core.SCHEMA,
+    kind: 'verdict',
+    ts: core.nowIso(),
+    agent_id: agentId,
+    task_id: (agent && agent.task_id) || null,
+    by: 'agent',
+    outcome,
+    verify,
+    reason_code: kebab(opts.reason),
+    cause: null,
+    round: null,
+  }, core.commonFields(ctx));
+}
+
+function verdictUser(opts, ctx, events) {
+  const taskId = opts.task;
+  const outcome = opts._[0];
+  if (typeof taskId !== 'string' || !taskId) throw new Error('--task cần task_id');
+  if (!USER_OUTCOMES.includes(outcome)) throw new Error(`verdict --task: outcome phải là ${USER_OUTCOMES.join('|')}`);
+  let cause = typeof opts.cause === 'string' ? opts.cause : null;
+  if (outcome === 'reject' && !CAUSES.includes(cause)) throw new Error(`reject cần --cause ${CAUSES.join('|')} (scope = yêu cầu đổi/thiếu, không phải lỗi model)`);
+  if (outcome === 'accept') cause = null;
+  const known = events.some((e) => e.task_id === taskId);
+  if (!known) throw new Error(`Không thấy task "${taskId}" trong log.`);
+  const rounds = events.filter((e) => e.kind === 'verdict' && e.task_id === taskId
+    && agg.normalizeVerdict(e).by === 'user').map((e) => Number(e.round) || 1);
+  let round = (rounds.length ? Math.max(...rounds) : 0) + 1;
+  if (opts.round !== undefined) {
+    round = Number(opts.round);
+    if (!Number.isInteger(round) || round < 1) throw new Error('--round phải là số nguyên ≥ 1');
+  }
+  return Object.assign({
+    schema: core.SCHEMA,
+    kind: 'verdict',
+    ts: core.nowIso(),
+    agent_id: `task:${taskId}`,
+    task_id: taskId,
+    by: 'user',
+    outcome,
+    cause,
+    round,
+    verify: 'judgment',
+    reason_code: kebab(opts.reason),
+  }, core.commonFields(ctx));
+}
+
+function cmdVerdict(opts) {
+  const ctx = ctxOf(opts);
+  const events = core.readEvents(ctx);
+  const ev = typeof opts.task === 'string' ? verdictUser(opts, ctx, events) : verdictAgent(opts, ctx, events);
+  core.appendEvent(ctx, ev);
+  if (opts.json) return { code: 0, out: JSON.stringify(ev) };
+  if (ev.by === 'user') {
+    return { code: 0, out: `Đã ghi người dùng ${ev.outcome}${ev.cause ? ` (${ev.cause})` : ''} cho task ${ev.task_id}, vòng ${ev.round}.` };
+  }
+  return { code: 0, out: `Đã ghi ${ev.outcome} cho ${ev.agent_id}${ev.task_id ? ` (task ${ev.task_id})` : ''}.` };
+}
+
+// ------------------------------------------------------------------ steer
+
+/**
+ * One `steer` invocation = one user action with one steer_id shared by its events.
+ * --task: marks only the task's in-flight agents (dispatched, not yet complete+verdict);
+ * none in flight -> one task-level event (agent_id task:<id>) that affects no rate.
+ */
+function cmdSteer(opts) {
+  const ref = opts._[0];
+  const kind = opts.kind;
+  if (!ref && !opts.task) throw new Error('Cú pháp: dieu-phoi steer <agent_id> | --task <task_id> --kind minor|plan|redirect [--reason R]');
+  if (!STEER_KINDS.includes(kind)) throw new Error(`--kind phải là ${STEER_KINDS.join('|')}`);
+  const ctx = ctxOf(opts);
+  const events = core.readEvents(ctx);
+  const steerId = crypto.randomBytes(4).toString('hex');
+  const ts = core.nowIso();
+  const { agents } = agg.buildAgents(events);
+  const mk = (agentId, taskId, taskType) => Object.assign({
+    schema: core.SCHEMA, kind: 'steer', ts, agent_id: agentId, steer_id: steerId,
+    task_id: taskId || null, task_type: taskType || null, steer_kind: kind, reason_code: kebab(opts.reason),
+  }, core.commonFields(ctx));
+  let out;
+  if (!ref) {
+    const taskId = String(opts.task);
+    const mine = agents.filter((a) => a.task_id === taskId);
+    if (!mine.length && !events.some((e) => e.task_id === taskId)) throw new Error(`Không thấy task ${taskId} trong log`);
+    const inFlight = mine.filter((a) => a.dispatched && !(a.completed && a.outcome));
+    const type = (mine.find((a) => a.role === 'exec') || mine[0] || {}).task_type || null;
+    out = inFlight.length ? inFlight.map((a) => mk(a.agent_id, taskId, a.task_type)) : [mk(`task:${taskId}`, taskId, type)];
+  } else {
+    const agentId = resolveAgentId(events, ref);
+    const agent = agents.find((a) => a.agent_id === agentId);
+    out = [mk(agentId, agent && agent.task_id, agent && agent.task_type)];
+  }
+  for (const ev of out) core.appendEvent(ctx, ev);
+  if (opts.json) return { code: 0, out: JSON.stringify(ref ? out[0] : out) };
+  const target = out[0].agent_id.startsWith('task:') ? `task ${out[0].task_id} (không có agent đang chạy)`
+    : `${out.length} agent${out[0].task_id ? ` của task ${out[0].task_id}` : ''}`;
+  return { code: 0, out: `Đã ghi steer ${kind} (${steerId}) cho ${target}.` };
+}
+
+// ------------------------------------------------------------------ stats / retro
+
+function lambdaOf(opts, ctx) {
+  const prof = chooser.loadProfile(skillDirOf(opts, ctx));
+  return { prof, lambda: prof.lambda.normal };
+}
+
+function pct(v) {
+  return v === null || v === undefined ? '-' : `${Math.round(v * 100)}%`;
+}
+
+function cmdStats(opts) {
+  const ctx = ctxOf(opts);
+  const { lambda } = lambdaOf(opts, ctx);
+  const { cells, steers } = agg.analyze(core.readEvents(ctx), { lambda });
+  const type = typeof opts.type === 'string' ? opts.type : null;
+  const rows = type ? cells.filter((c) => c.task_type === type) : cells;
+  const steerRows = type ? steers.filter((s) => s.task_type === type) : steers;
+  if (opts.json) {
+    return { code: 0, out: JSON.stringify({ lambda_usd_per_min: lambda, min_n: agg.MIN_N, cells: rows, steers: steerRows }, null, 2) };
+  }
+  if (!rows.length) return { code: 0, out: 'Chưa có dữ liệu.' };
+  const t = [['task_type', 'model/effort', 'n', 'accept%', 'agent_pass%', 'E[cost]', 'E[time]', 'p50', 'p75', 'score', '']];
+  for (const c of rows) {
+    t.push([
+      c.task_type,
+      `${chooser.shortModel(c.model) || c.model || '?'}/${c.effort || '?'}`,
+      `${c.n}${c.dispatched > c.n ? `/${c.dispatched}` : ''}${c.n_excluded ? ` (-${c.n_excluded})` : ''}`,
+      c.n ? `${pct(c.accept_rate)}${c.n_user ? ` (${c.n_user} ng.dùng)` : ''}` : '-',
+      c.n_agent ? `${pct(c.agent_pass_rate)} (${c.n_agent})` : '-',
+      fmtUsd(c.cost_mean_usd),
+      c.time_mean_min === null ? '-' : `${fmtNum(c.time_mean_min)}m`,
+      c.time_p50_min === null ? '-' : `${fmtNum(c.time_p50_min)}m`,
+      c.time_p75_min === null ? '-' : `${fmtNum(c.time_p75_min)}m`,
+      c.score === null ? '-' : fmtNum(c.score, 3),
+      c.note,
+    ]);
+  }
+  const s = [['task_type', 'task', 'task có steer', 'lần steer', 'minor', 'plan', 'redirect', 'tỉ lệ steer']];
+  for (const r of steerRows) {
+    s.push([r.task_type, r.tasks, r.steered_tasks, r.actions, r.minor, r.plan, r.redirect, pct(r.steer_rate)]);
+  }
+  return {
+    code: 0,
+    out: `${table(t)}\n\n${table(s)}\n\n`
+      + 'n = task tính tỉ lệ (/số đã giao, (-k) = bị loại: reject-scope hoặc lượt exec đầu bị steer plan/redirect). '
+      + 'accept% = thành công theo verdict người dùng đầu tiên, chưa có thì verdict agent; agent_pass% = chỉ tầng agent. '
+      + `E[cost], E[time] tính trọn mọi lượt + review của task. score = E[cost] + λ·E[time], λ=${lambda} USD/phút.`,
+  };
+}
+
+const HIGH_STEER_RATE = 0.3;
+const HIGH_STEER_MIN_TASKS = 3;
+
+function cmdRetro(opts) {
+  const ctx = ctxOf(opts);
+  const { prof, lambda } = lambdaOf(opts, ctx);
+  const events = core.readEvents(ctx);
+  const { agents, tasks, cells, steers, userVerdicts, overrides } = agg.analyze(events, { lambda });
+  const reasons = {};
+  const outcomes = {};
+  const userOutcomes = {};
+  for (const a of agents) {
+    if (a.outcome) outcomes[a.outcome] = (outcomes[a.outcome] || 0) + 1;
+    if (a.reason_code) reasons[a.reason_code] = (reasons[a.reason_code] || 0) + 1;
+  }
+  for (const v of userVerdicts) {
+    const k = v.outcome === 'reject' ? `reject_${v.cause}` : v.outcome;
+    userOutcomes[k] = (userOutcomes[k] || 0) + 1;
+    if (v.reason_code) reasons[v.reason_code] = (reasons[v.reason_code] || 0) + 1;
+  }
+  const types = {};
+  for (const t of tasks) {
+    if (!types[t.task_type]) types[t.task_type] = { task_type: t.task_type, n: 0, verdicted: 0, accepted: 0 };
+    types[t.task_type].n++;
+    if (t.success !== null) types[t.task_type].verdicted++;
+    if (t.accepted) types[t.task_type].accepted++;
+  }
+  const ts = events.map((e) => Date.parse(e.ts)).filter((x) => !isNaN(x));
+  const escalations = tasks.filter((t) => t.attempts.length > 1).length;
+  const highSteer = steers.filter((s) => s.tasks >= HIGH_STEER_MIN_TASKS && s.steer_rate >= HIGH_STEER_RATE)
+    .map((s) => Object.assign({}, s, { signal: 'brainstorm hỏi người dùng quá ít trước khi giao' }));
+  const summary = {
+    generated_at: core.nowIso(),
+    core_version: core.CORE_VERSION,
+    dept: ctx.config.dept || prof.dept || null,
+    period: ts.length ? { from: new Date(Math.min(...ts)).toISOString(), to: new Date(Math.max(...ts)).toISOString() } : null,
+    totals: {
+      events: events.length,
+      agents: agents.length,
+      tasks: tasks.length,
+      untagged_agents: agents.filter((a) => a.task_type === 'untagged').length,
+      no_verdict_agents: agents.filter((a) => a.completed && !a.outcome && a.role !== 'verify').length,
+      no_user_verdict_tasks: tasks.filter((t) => !t.user_verdicts.length).length,
+      multi_attempt_tasks: escalations,
+      overrides: overrides.length,
+      cost_usd: agents.reduce((s, a) => s + (a.cost_usd || 0), 0),
+    },
+    lambda_usd_per_min: prof.lambda,
+    min_n: agg.MIN_N,
+    task_types: Object.values(types).sort((a, b) => b.n - a.n),
+    outcomes,
+    user_outcomes: userOutcomes,
+    reason_codes: Object.entries(reasons).sort((a, b) => b[1] - a[1]).map(([code, count]) => ({ code, count })),
+    steers,
+    high_steer_task_types: highSteer,
+    overrides: overrides.map((o) => ({ ts: o.ts, task_type: o.task_type, suggested_tier: o.suggested_tier, chosen_tier: o.chosen_tier })),
+    cells,
+  };
+  if (opts.json) return { code: 0, out: JSON.stringify(summary, null, 2) };
+  const lines = [
+    `Retro ${summary.dept || ''} — ${summary.period ? `${summary.period.from.slice(0, 10)} → ${summary.period.to.slice(0, 10)}` : 'chưa có dữ liệu'}`,
+    `${summary.totals.tasks} task, ${summary.totals.agents} agent, chi phí ≈ ${fmtUsd(summary.totals.cost_usd)}, ${summary.totals.untagged_agents} agent không thẻ, ${summary.totals.no_user_verdict_tasks} task chưa có verdict người dùng, ${escalations} task nhiều lượt, ${overrides.length} override.`,
+    `Người dùng: ${Object.entries(userOutcomes).map(([k, v]) => `${k}=${v}`).join(', ') || '-'} · Agent: ${Object.entries(outcomes).map(([k, v]) => `${k}=${v}`).join(', ') || '-'}`,
+    `Lý do hay gặp: ${summary.reason_codes.slice(0, 8).map((r) => `${r.code}×${r.count}`).join(', ') || '-'}`,
+    `Loại task: ${summary.task_types.map((t) => `${t.task_type}(${t.n})`).join(', ') || '-'}`,
+    `Steer nhiều (brainstorm hỏi quá ít): ${highSteer.map((s) => `${s.task_type} ${pct(s.steer_rate)}`).join(', ') || '-'}`,
+    'Chi tiết theo ô: `dieu-phoi stats`; đưa cho LLM: `dieu-phoi retro --json`.',
+  ];
+  return { code: 0, out: lines.join('\n') };
+}
+
+// ------------------------------------------------------------------ choose
+
+function chooseInput(opts, ctx, events) {
+  return {
+    type: opts.type,
+    score: opts.score,
+    urgency: typeof opts.urgency === 'string' ? opts.urgency : 'normal',
+    reversible: yesNo(opts.reversible, true),
+    verifiable: yesNo(opts.verifiable, true),
+    role: typeof opts.role === 'string' ? opts.role : 'exec',
+    seed: opts.seed,
+    taskId: typeof opts.task === 'string' ? opts.task : null,
+    override: typeof opts.override === 'string' ? opts.override : null,
+    approved: typeof opts.approved === 'string' ? opts.approved : null,
+    events,
+    profile: chooser.loadProfile(skillDirOf(opts, ctx)),
+    pricing: core.loadPricing(ctx),
+  };
+}
+
+function cmdChoose(opts) {
+  const ctx = ctxOf(opts);
+  if (opts.override !== undefined && typeof opts.task !== 'string') {
+    throw new Error('--override cần --task <task_id> (để học override theo từng task)');
+  }
+  const input = chooseInput(opts, ctx, core.readEvents(ctx));
+  const res = chooser.choose(input);
+  if (res.overridden) {
+    const tid = input.taskId;
+    core.appendEvent(ctx, Object.assign({
+      schema: core.SCHEMA,
+      kind: 'override',
+      ts: core.nowIso(),
+      agent_id: tid ? `task:${tid}` : `override-${require('crypto').randomBytes(6).toString('hex')}`,
+      task_id: tid,
+      task_type: String(input.type).toLowerCase(),
+      suggested_tier: res.suggested_tier,
+      chosen_tier: res.tier,
+    }, core.commonFields(ctx)));
+  }
+  if (opts.json) return { code: 0, out: JSON.stringify(res) };
+  const est = `~${fmtUsd(res.est_cost_usd)} · ~${fmtNum(res.est_time_min)} phút (${res.est_source === 'data' ? 'dữ liệu' : 'ước lượng thô'})`;
+  if (res.action === 'ask_user') {
+    return { code: 0, out: `HỎI NGƯỜI DÙNG — ${res.reason}` };
+  }
+  return {
+    code: 0,
+    out: `model=${res.model} effort=${res.effort}${res.explored ? ' (thăm dò)' : ''}${res.overridden ? ' (override)' : ''}${res.deviation ? ' (LỆCH khỏi tier đã duyệt)' : ''} ${est} — ${res.reason}`,
+  };
+}
+
+// ------------------------------------------------------------------ plan-table
+
+/** Longest path through the step DAG; steps without depends_on run in parallel. */
+function criticalPath(steps, timeOf) {
+  const byName = new Map(steps.map((s) => [s.step, s]));
+  const finish = new Map();
+  const visiting = new Set();
+  const visit = (name) => {
+    if (finish.has(name)) return finish.get(name);
+    if (visiting.has(name)) throw new Error(`plan-table: phụ thuộc vòng tại bước "${name}"`);
+    const s = byName.get(name);
+    if (!s) throw new Error(`plan-table: không có bước "${name}" (trong depends_on)`);
+    visiting.add(name);
+    let start = 0;
+    for (const d of s.deps) start = Math.max(start, visit(d));
+    visiting.delete(name);
+    const f = start + (timeOf(name) || 0);
+    finish.set(name, f);
+    return f;
+  };
+  let total = 0;
+  for (const s of steps) total = Math.max(total, visit(s.step));
+  return total;
+}
+
+function buildPlanTable(rawSteps, base) {
+  if (!Array.isArray(rawSteps) || !rawSteps.length) throw new Error('plan-table: file phải là mảng JSON các bước');
+  const steps = rawSteps.map((s, i) => {
+    if (!s || typeof s !== 'object') throw new Error(`plan-table: bước #${i + 1} không phải object`);
+    const rawName = s.step !== undefined ? s.step : s.id;
+    const name = String(rawName !== undefined ? rawName : i + 1);
+    let deps = s.depends_on === undefined || s.depends_on === null ? [] : s.depends_on;
+    if (!Array.isArray(deps)) deps = [deps];
+    return {
+      step: name,
+      title: s.title,
+      type: s.type !== undefined ? s.type : s.task_type,
+      task: s.task_id,
+      override: s.override,
+      role: s.role,
+      score: s.score,
+      verifiable: s.verifiable === undefined ? true : yesNo(s.verifiable, true),
+      reversible: s.reversible === undefined ? true : yesNo(s.reversible, true),
+      urgency: s.urgency,
+      deps: deps.map(String),
+    };
+  });
+  const names = new Set();
+  for (const s of steps) {
+    if (names.has(s.step)) throw new Error(`plan-table: trùng tên bước "${s.step}"`);
+    names.add(s.step);
+  }
+  const rows = steps.map((s) => {
+    const call = () => chooser.choose(Object.assign({}, base, {
+      type: s.type,
+      score: s.score,
+      verifiable: s.verifiable,
+      reversible: s.reversible,
+      urgency: s.urgency || base.urgency,
+      taskId: s.task || base.taskId,
+      override: s.override || base.override,
+      role: s.role || base.role,
+      seed: base.seed === undefined || base.seed === null ? `plan:${s.step}` : `${base.seed}:${s.step}`,
+    }));
+    const head = { step: s.step, title: s.title, type: s.type, score: Number(s.score), depends_on: s.deps };
+    try {
+      return Object.assign(head, call());
+    } catch (e) {
+      // One bad step (e.g. override below a floor) must not hide the rest of the plan.
+      return Object.assign(head, {
+        action: 'refused', tier: null, reason: `từ chối: ${e.message}`, error: e.message,
+        est_cost_usd: null, est_time_min: null, est_source: null,
+      });
+    }
+  });
+  const timeOf = new Map(rows.map((r) => [r.step, r.est_time_min]));
+  const critical = criticalPath(steps, (n) => timeOf.get(n));
+  const ok = rows.filter((r) => r.action !== 'refused');
+  const costs = ok.map((r) => r.est_cost_usd);
+  const totalCost = costs.every((c) => typeof c === 'number') ? costs.reduce((a, b) => a + b, 0) : null;
+  return {
+    steps: rows,
+    refused: rows.filter((r) => r.action === 'refused').map((r) => ({ step: r.step, error: r.error })),
+    total_cost_usd: totalCost === null ? null : Math.round(totalCost * 1000) / 1000,
+    critical_path_min: Math.round(critical * 10) / 10,
+    sum_time_min: Math.round(rows.reduce((a, r) => a + (r.est_time_min || 0), 0) * 10) / 10,
+    rough: rows.some((r) => r.est_source === 'rough'),
+  };
+}
+
+function mdCell(s) {
+  return String(s).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+}
+
+function cmdPlanTable(opts) {
+  if (typeof opts.file !== 'string') throw new Error('Cú pháp: dieu-phoi plan-table --file <steps.json> [--json]');
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(path.resolve(opts.file), 'utf8').replace(/^/, ''));
+  } catch (e) {
+    throw new Error(`plan-table: không đọc được ${opts.file}: ${e.message}`);
+  }
+  const ctx = ctxOf(opts);
+  const base = chooseInput(Object.assign({}, opts, { type: 'x', score: 0, override: undefined }), ctx, core.readEvents(ctx));
+  delete base.override;
+  const plan = buildPlanTable(raw, base);
+  if (opts.json) return { code: 0, out: JSON.stringify(plan, null, 2) };
+  const lines = ['| Bước | Model/effort | Lý do | Ước tính |', '|---|---|---|---|'];
+  for (const r of plan.steps) {
+    const tierCell = r.action === 'refused' ? '—' : (r.action === 'ask_user' ? `${r.tier} (hỏi người dùng)` : r.tier);
+    const why = `${r.type}, điểm ${r.score}${r.depends_on.length ? `, sau ${r.depends_on.join(', ')}` : ''} — ${r.reason.replace(/; profile: .*$/, '')}`;
+    const est = r.action === 'refused' ? '-' : `~${fmtUsd(r.est_cost_usd)} · ~${fmtNum(r.est_time_min)} phút${r.est_source === 'rough' ? ' (thô)' : ''}`;
+    lines.push(`| ${mdCell(r.title ? `${r.step}. ${r.title}` : r.step)} | ${mdCell(tierCell)} | ${mdCell(why)} | ${mdCell(est)} |`);
+  }
+  lines.push('');
+  lines.push(`**Tổng chi phí ước tính:** ~${fmtUsd(plan.total_cost_usd)} · **Thời gian (đường găng, chạy song song khi không phụ thuộc):** ~${fmtNum(plan.critical_path_min)} phút (cộng dồn ${fmtNum(plan.sum_time_min)} phút)`);
+  if (plan.rough) lines.push('', '_(thô) = ô chưa đủ 5 task, ước lượng theo giả định token của từng tier._');
+  if (plan.refused.length) {
+    lines.push('', `**Cảnh báo:** ${plan.refused.length} bước bị từ chối (${plan.refused.map((x) => x.step).join(', ')}), không tính vào tổng — sửa rồi chạy lại.`);
+    process.stderr.write(`dieu-phoi plan-table: cảnh báo — ${plan.refused.length} bước bị từ chối
+`);
+  }
+  return { code: 0, out: lines.join('\n') };
+}
+
+module.exports = {
+  cmdSetup, cmdUninstall, cmdDoctor, cmdHook, cmdSync, cmdVerdict, cmdSteer, cmdStats, cmdRetro, cmdChoose,
+  cmdPlanTable, buildPlanTable, criticalPath, resolveAgentId, AGENT_OUTCOMES, USER_OUTCOMES, VERIFY,
+};