@kienntpixon/dieu-phoi 0.1.2 → 0.2.0

package/hook.cjs

@@ -19,7 +19,7 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 
-const CORE_VERSION = '0.1.2';
+const CORE_VERSION = '0.2.0';
 const SCHEMA = 1;
 const TASK_TYPES = [
   'search', 'extract', 'mechanical-edit', 'feature-impl', 'debug', 'refactor',
@@ -119,6 +119,7 @@ function pathsFor(home) {
     data,
     events: path.join(data, 'events.jsonl'),
     segments: path.join(data, 'segments'),
+    plans: path.join(data, 'plans'),
     skippedInternal: path.join(data, 'skipped-internal.json'),
     syncOffset: path.join(data, 'sync-offset.json'),
     syncSpawn: path.join(data, 'sync-spawn.json'),
@@ -425,6 +426,285 @@ function summarizeTranscript(lines, opts) {
   };
 }
 
+// ------------------------------------------------------------------ orchestrator (main session) usage
+
+const SESSION_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const ORCH_CACHE_V = 2;  // 2: + compactions
+const ORCH_CHUNK = 1 << 20;            // read granularity; memory = chunk + longest line
+const ORCH_SEEN_KEEP = 64;             // requestIds kept for last-line-wins dedupe across scans
+const ORCH_HEAD_BYTES = 4096;          // fingerprint of the file start (rotation / replacement check)
+const ORCH_TAIL_START = 256 * 1024;    // tail window for the cold fast path, doubled while no usage
+const ORCH_EDGE_MAX = 16 << 20;        // cap for head/tail probes in the cold fast path
+const HOOK_COLD_MAX_BYTES = 32 << 20;  // hook: transcripts larger than this without a cache take the fast path
+const ORCH_CACHE_TTL_MS = 14 * 24 * 3600 * 1000;
+const USAGE_NEEDLE = Buffer.from('"usage"');
+const COMPACT_NEEDLE = Buffer.from('"compact_boundary"');
+
+const ORCH_NONE = Object.freeze({
+  ctx_tokens: null, ctx_baseline: null, ctx_growth: null, cum_usd: null, requests: null, compactions: null,
+  scanned_bytes: 0,
+});
+
+/**
+ * One main-thread transcript line -> { key, usage, model } for a request, { compact: true } for a
+ * compaction marker (`type:"system", subtype:"compact_boundary"`, written by /compact and auto-compact),
+ * null for anything else.
+ */
+function parseMainLine(text) {
+  let l;
+  try { l = JSON.parse(text); } catch (_) { return null; }
+  if (!l || l.isSidechain === true) return null;
+  if (l.type === 'system' && l.subtype === 'compact_boundary') return { compact: true };
+  if (l.type !== 'assistant') return null;
+  const msg = l.message;
+  if (!msg || typeof msg !== 'object' || !msg.usage || msg.model === '<synthetic>') return null;
+  const key = l.requestId || msg.id || l.uuid || null;
+  return { key, usage: msg.usage, model: msg.model };
+}
+
+/** Request lines only. */
+function mainUsageOf(text) {
+  const r = parseMainLine(text);
+  return r && !r.compact ? r : null;
+}
+
+function ctxOfBuckets(b) {
+  return b.input + b.cache_write_5m + b.cache_write_1h + b.cache_read + b.output;
+}
+
+/**
+ * Stream complete lines of fd in [start, end) in chunks; only lines containing "usage" are decoded and
+ * passed to onLine (return true to stop). Returns { consumed: byte just past the last complete line
+ * handled, read: bytes read }.
+ */
+function scanUsageLines(fd, start, end, onLine) {
+  const buf = Buffer.allocUnsafe(ORCH_CHUNK);
+  let carry = null;
+  let pos = start;
+  let consumed = start;
+  let read = 0;
+  while (pos < end) {
+    const n = fs.readSync(fd, buf, 0, Math.min(buf.length, end - pos), pos);
+    if (n <= 0) break;
+    pos += n;
+    read += n;
+    const data = carry ? Buffer.concat([carry, buf.subarray(0, n)]) : buf.subarray(0, n);
+    const base = pos - data.length;
+    let s = 0;
+    let nl;
+    while ((nl = data.indexOf(0x0a, s)) >= 0) {
+      const line = data.subarray(s, nl);
+      s = nl + 1;
+      if ((line.indexOf(USAGE_NEEDLE) >= 0 || line.indexOf(COMPACT_NEEDLE) >= 0)
+        && onLine(line.toString('utf8')) === true) {
+        return { consumed: base + s, read };
+      }
+    }
+    consumed = base + s;
+    carry = s < data.length ? Buffer.from(data.subarray(s)) : null;
+  }
+  return { consumed, read };
+}
+
+function headFingerprint(fd, size) {
+  const len = Math.min(ORCH_HEAD_BYTES, size);
+  const b = Buffer.alloc(len);
+  if (len) fs.readSync(fd, b, 0, len, 0);
+  return { head_len: len, head: crypto.createHash('sha256').update(b).digest('hex').slice(0, 16) };
+}
+
+function freshOrchState(fp) {
+  return {
+    v: ORCH_CACHE_V, head_len: fp.head_len, head: fp.head, offset: 0, requests: 0, cost: 0, priced: 0,
+    baseline: null, baseline_req: null, last_ctx: null, cum_known: true, compactions: 0, seen: [],
+  };
+}
+
+/** Fold one main-thread request line into the state (last line of a requestId wins). */
+function applyUsage(st, seen, u, pricing) {
+  const b = usageBuckets(u.usage);
+  const c = requestCost(pricing, u.model, b);
+  const ctx = ctxOfBuckets(b);
+  const key = u.key || `anon-${st.requests}-${st.offset}`;
+  if (seen.has(key)) {
+    const prev = seen.get(key);
+    if (prev !== null) { st.cost -= prev; st.priced--; }
+    seen.delete(key);
+  } else {
+    if (st.requests !== null) st.requests++;
+    if (st.baseline_req === null && st.baseline === null) st.baseline_req = key;
+  }
+  if (key === st.baseline_req) st.baseline = ctx;
+  if (c !== null) { st.cost += c; st.priced++; }
+  seen.set(key, c);
+  if (seen.size > ORCH_SEEN_KEEP) seen.delete(seen.keys().next().value);
+  st.last_ctx = ctx;
+}
+
+/** Cold fast path: baseline from the head, current ctx from the tail; cost unknown. */
+function edgeProbe(fd, size, st) {
+  let first = null;
+  scanUsageLines(fd, 0, Math.min(size, ORCH_EDGE_MAX), (t) => { first = mainUsageOf(t); return !!first; });
+  let last = null;
+  let lastNl = -1;
+  for (let w = ORCH_TAIL_START; ; w *= 2) {
+    const start = Math.max(0, size - w);
+    const b = Buffer.allocUnsafe(size - start);
+    fs.readSync(fd, b, 0, b.length, start);
+    lastNl = b.lastIndexOf(0x0a);
+    const from = start === 0 ? 0 : b.indexOf(0x0a) + 1;
+    let s = from;
+    let nl;
+    while (lastNl >= 0 && (nl = b.indexOf(0x0a, s)) >= 0 && nl <= lastNl) {
+      const line = b.subarray(s, nl);
+      s = nl + 1;
+      if (line.indexOf(USAGE_NEEDLE) < 0) continue;
+      const u = mainUsageOf(line.toString('utf8'));
+      if (u) last = u;
+    }
+    if (lastNl >= 0) lastNl += start;
+    if (last || start === 0 || w >= ORCH_EDGE_MAX) break;
+  }
+  st.cum_known = false;
+  st.requests = null;
+  st.compactions = null; // unknown until a full scan
+  if (first) {
+    st.baseline = ctxOfBuckets(usageBuckets(first.usage));
+    st.baseline_req = first.key;
+  }
+  if (last) st.last_ctx = ctxOfBuckets(usageBuckets(last.usage));
+  st.offset = lastNl >= 0 ? lastNl + 1 : 0;
+}
+
+/** Drop stale session caches. Only ever touches <data>/orch/*.json (never another directory). */
+function pruneOrchCache(dir) {
+  try {
+    if (path.basename(dir) !== 'orch') return;
+    const now = Date.now();
+    for (const f of fs.readdirSync(dir)) {
+      if (!/^[A-Za-z0-9_-]{1,140}\.json$/.test(f)) continue;
+      const p = path.join(dir, f);
+      try { if (now - fs.statSync(p).mtimeMs > ORCH_CACHE_TTL_MS) fs.unlinkSync(p); } catch (_) { /* gone */ }
+    }
+  } catch (_) { /* no dir */ }
+}
+
+/** Cache file for a session (data/orch/<session_id>.json); no session -> hash of the transcript path. */
+function orchCacheFile(paths, sessionId, transcriptPath) {
+  if (!paths || !paths.data) return null;
+  const name = typeof sessionId === 'string' && SESSION_ID_RE.test(sessionId)
+    ? sessionId : `p-${sha8(String(transcriptPath))}`;
+  return path.join(paths.data, 'orch', `${name}.json`);
+}
+
+/**
+ * Size and running cost of the orchestrating (main) session, from its transcript JSONL.
+ * Only main-thread requests count: `type:"assistant"` lines with message.usage, minus
+ * `isSidechain:true` and `<synthetic>`; deduped per requestId (last line wins).
+ *   ctx_tokens   = input + cache_creation + cache_read + output of the LAST request (= current context)
+ *   ctx_baseline = the same for the FIRST request of the session (system prompt + tools + first turn)
+ *   ctx_growth   = max(0, ctx_tokens - ctx_baseline)
+ *   cum_usd      = sum of requestCost per request at its own model's price (unpriced requests left out;
+ *                  null when none priced, or when only the cold fast path ran)
+ * opts.cacheFile: per-session state ({offset, cost, seen requestIds, baseline, …}); each call then parses
+ *   only the bytes appended since the last call. A shrunk or replaced file (offset > size or a different
+ *   head fingerprint) is recomputed from 0.
+ * opts.coldMaxBytes: no usable cache and the file is larger -> head/tail probe only (ctx + baseline,
+ *   cum_usd null); a later call without the limit (`dieu-phoi ctx`) recomputes the full sum.
+ * Reads in chunks (memory = chunk + longest line), never the whole file at once. Never throws.
+ */
+function orchestratorUsage(transcriptPath, pricing, opts) {
+  const o = opts || {};
+  let fd = null;
+  try {
+    if (typeof transcriptPath !== 'string' || !transcriptPath) return Object.assign({}, ORCH_NONE);
+    let stat;
+    try { stat = fs.statSync(transcriptPath); } catch (_) { return Object.assign({}, ORCH_NONE); }
+    if (!stat.isFile()) return Object.assign({}, ORCH_NONE);
+    const size = stat.size;
+    const pr = pricing || loadPricing(null);
+    fd = fs.openSync(transcriptPath, 'r');
+    const fp = headFingerprint(fd, size);
+    let st = null;
+    const cached = o.cacheFile ? readJsonFile(o.cacheFile, null) : null;
+    if (cached && cached.v === ORCH_CACHE_V && Number.isFinite(cached.offset) && cached.offset <= size
+      && cached.head_len <= size && Array.isArray(cached.seen)
+      && (cached.cum_known || o.coldMaxBytes)) {
+      const now = cached.head_len === fp.head_len ? fp : (() => {
+        const b = Buffer.alloc(cached.head_len);
+        if (cached.head_len) fs.readSync(fd, b, 0, cached.head_len, 0);
+        return { head_len: cached.head_len, head: crypto.createHash('sha256').update(b).digest('hex').slice(0, 16) };
+      })();
+      if (now.head === cached.head) st = cached;
+    }
+    let scanned = 0;
+    const startOffset = st ? st.offset : 0;
+    if (!st) {
+      st = freshOrchState(fp);
+      if (o.coldMaxBytes && size > o.coldMaxBytes) {
+        edgeProbe(fd, size, st);
+        scanned = -1; // probe, not a scan
+      }
+    }
+    if (scanned === 0 && st.offset < size) {
+      const seen = new Map(st.seen);
+      const r = scanUsageLines(fd, st.offset, size, (t) => {
+        const u = parseMainLine(t);
+        if (u && u.compact) { if (st.compactions !== null) st.compactions++; } else if (u) applyUsage(st, seen, u, pr);
+        return false;
+      });
+      st.offset = r.consumed;
+      st.seen = Array.from(seen.entries());
+      scanned = r.read;
+    }
+    const reused = st === cached;
+    if (o.cacheFile && (!reused || st.offset !== startOffset)) {
+      try {
+        if (!cached) pruneOrchCache(path.dirname(o.cacheFile));
+        writeFileAtomic(o.cacheFile, `${JSON.stringify(st)}\n`);
+      } catch (_) { /* cache is an optimisation only */ }
+    }
+    if (st.last_ctx === null) return Object.assign({}, ORCH_NONE, { scanned_bytes: Math.max(0, scanned) });
+    const growth = st.baseline === null ? null : Math.max(0, st.last_ctx - st.baseline);
+    return {
+      ctx_tokens: st.last_ctx,
+      ctx_baseline: st.baseline,
+      ctx_growth: growth,
+      cum_usd: st.cum_known && st.priced > 0 ? Math.round(st.cost * 1e6) / 1e6 : null,
+      requests: st.cum_known ? st.requests : null,
+      compactions: typeof st.compactions === 'number' ? st.compactions : null,
+      scanned_bytes: Math.max(0, scanned),
+    };
+  } catch (_) {
+    return Object.assign({}, ORCH_NONE);
+  } finally {
+    if (fd !== null) { try { fs.closeSync(fd); } catch (_) { /* closed */ } }
+  }
+}
+
+/**
+ * Main transcript of a session: <claudeDir>/projects/<any project>/<sessionId>.jsonl (newest if
+ * several). Returns null when the id is malformed or no file exists.
+ */
+function findSessionTranscript(claudeDir, sessionId) {
+  try {
+    if (typeof sessionId !== 'string' || !SESSION_ID_RE.test(sessionId)) return null;
+    const root = path.join(claudeDir || defaultClaudeDir(), 'projects');
+    let best = null;
+    let bestM = -1;
+    for (const d of fs.readdirSync(root)) {
+      const f = path.join(root, d, `${sessionId}.jsonl`);
+      try {
+        const st = fs.statSync(f);
+        if (st.isFile() && st.mtimeMs > bestM) { best = f; bestM = st.mtimeMs; }
+      } catch (_) { /* not in this project */ }
+    }
+    return best;
+  } catch (_) {
+    return null;
+  }
+}
+
 // ------------------------------------------------------------------ events (append-only)
 
 /** Append one event. events.jsonl is append-only: never rewritten, sync progress lives elsewhere. */
@@ -511,6 +791,312 @@ function saveSegments(ctx, agentId, rec) {
   writeFileAtomic(segmentFile(ctx, agentId), `${JSON.stringify(rec)}\n`);
 }
 
+// ------------------------------------------------------------------ session state (for /compact)
+
+const STATE_TEXT_CAP = 8000;
+const COMPACT_PREFIX = 'dieu-phoi: ngữ cảnh vừa được nén; trạng thái điều phối hiện tại (dựng từ log):';
+const AGENT_FAIL = { fail: 1, timeout: 1 };
+
+/**
+ * Run directory for subagent reports: ~/.dieu-phoi/runs (override: DIEU_PHOI_RUNS_DIR, absolute).
+ * Deliberately outside ~/.claude (a Claude Code protected path).
+ */
+function runsDir() {
+  if (process.env.DIEU_PHOI_RUNS_DIR) return path.resolve(process.env.DIEU_PHOI_RUNS_DIR);
+  return path.join(os.homedir(), '.dieu-phoi', 'runs');
+}
+
+function shortModelName(m) {
+  const id = normalizeModel(m);
+  if (!id) return null;
+  for (const k of ['opus', 'sonnet', 'haiku', 'fable']) if (id.includes(k)) return k;
+  return id;
+}
+
+function tierOf(model, effort) {
+  const m = shortModelName(model);
+  return m || effort ? `${m || '?'}/${effort || '?'}` : null;
+}
+
+function evMs(ev) {
+  const t = Date.parse(ev && ev.ts);
+  return isNaN(t) ? 0 : t;
+}
+
+/** Verdict layer, same reading as the stats (legacy `rework` = user reject quality). */
+function verdictLayer(ev) {
+  if (ev.outcome === 'rework' && !ev.by) return { by: 'user', outcome: 'reject', cause: 'quality' };
+  const by = ev.by === 'user' ? 'user' : 'agent';
+  let cause = ev.cause || null;
+  if (by === 'user' && ev.outcome === 'reject' && cause !== 'scope') cause = 'quality';
+  return { by, outcome: ev.outcome, cause };
+}
+
+function dispatchInSession(ev, sessionId) {
+  if (!ev || ev.kind !== 'dispatch') return false;
+  if (typeof ev.session_id === 'string' && ev.session_id) return ev.session_id === sessionId;
+  return ev.session === sha8(sessionId); // core < 0.2.0: hashed session only
+}
+
+/** Approved-plan records written by `plan-table --approve` (<data>/plans/<root>.json). Never throws. */
+function loadPlans(dir) {
+  const out = [];
+  if (!dir) return out;
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch (_) { return out; }
+  for (const n of names) {
+    if (!/^[A-Za-z0-9_-]{1,64}\.json$/.test(n)) continue;
+    const p = readJsonFile(path.join(dir, n), null);
+    if (p && typeof p.root_task_id === 'string' && Array.isArray(p.steps)) out.push(p);
+  }
+  return out;
+}
+
+/**
+ * Orchestration state of one session, rebuilt from events.jsonl plus the local approved-plan records
+ * (CONTRACT "Sau khi nén"). Tasks = task_ids that had a dispatch in this session, plus the root and steps
+ * of every approved plan touching those tasks. Never reads run-dir files.
+ * opts: { runsDir, plansDir | plans }.
+ */
+function buildSessionState(events, sessionId, opts) {
+  const o = opts || {};
+  const runs = toPosix(o.runsDir || runsDir());
+  const taskIds = [];
+  const seenTask = new Set();
+  for (const ev of events) {
+    if (dispatchInSession(ev, sessionId) && typeof ev.task_id === 'string' && ev.task_id && !seenTask.has(ev.task_id)) {
+      seenTask.add(ev.task_id);
+      taskIds.push(ev.task_id);
+    }
+  }
+  const allPlans = Array.isArray(o.plans) ? o.plans : loadPlans(o.plansDir);
+  const plans = allPlans.filter((p) => seenTask.has(p.root_task_id)
+    || p.steps.some((s) => s && s.task_id && seenTask.has(s.task_id)));
+  const planOfRoot = new Map(plans.map((p) => [p.root_task_id, p]));
+  const stepOf = new Map();
+  for (const p of plans) {
+    for (const s of p.steps) if (s && s.task_id && !stepOf.has(s.task_id)) stepOf.set(s.task_id, { plan: p, step: s });
+  }
+  for (const id of [...planOfRoot.keys(), ...stepOf.keys()]) {
+    if (!seenTask.has(id)) { seenTask.add(id); taskIds.push(id); }
+  }
+  const per = new Map(taskIds.map((id) => [id, { dispatches: [], user: [], steers: [], overrides: [], agentIds: new Set() }]));
+  events.forEach((ev, i) => {
+    if (!ev || typeof ev !== 'object') return;
+    ev._i = i;
+    if (ev.kind === 'dispatch' && per.has(ev.task_id)) {
+      const t = per.get(ev.task_id);
+      if (!t.agentIds.has(ev.agent_id)) { t.agentIds.add(ev.agent_id); t.dispatches.push(ev); }
+    }
+  });
+  const agentTask = new Map();
+  for (const [id, t] of per) for (const a of t.agentIds) agentTask.set(a, id);
+  const completes = new Map();
+  const agentVerdicts = new Map();
+  for (const ev of events) {
+    if (!ev || typeof ev !== 'object') continue;
+    if (ev.kind === 'complete' && agentTask.has(ev.agent_id)) completes.set(ev.agent_id, (completes.get(ev.agent_id) || 0) + 1);
+    if (ev.kind === 'verdict') {
+      const v = verdictLayer(ev);
+      if (v.by === 'user') {
+        const id = ev.task_id || (String(ev.agent_id).startsWith('task:') ? String(ev.agent_id).slice(5) : agentTask.get(ev.agent_id));
+        if (per.has(id)) per.get(id).user.push(Object.assign({}, ev, v));
+      } else if (agentTask.has(ev.agent_id)) {
+        if (!agentVerdicts.has(ev.agent_id)) agentVerdicts.set(ev.agent_id, []);
+        agentVerdicts.get(ev.agent_id).push(Object.assign({}, ev, v));
+      }
+    }
+    if (ev.kind === 'steer') {
+      const id = ev.task_id || agentTask.get(ev.agent_id);
+      if (per.has(id)) per.get(id).steers.push(ev);
+    }
+    if (ev.kind === 'override' && per.has(ev.task_id)) per.get(ev.task_id).overrides.push(ev);
+  }
+  const byTime = (a, b) => evMs(a) - evMs(b) || a._i - b._i;
+  const tasks = [];
+  for (const id of taskIds) {
+    const t = per.get(id);
+    const ps = stepOf.get(id) || null;
+    const plan = ps ? ps.plan : (planOfRoot.get(id) || null);
+    const planInfo = {
+      root_task_id: plan ? plan.root_task_id : null,
+      step_id: ps ? (ps.step.id === undefined ? null : String(ps.step.id)) : null,
+      is_root: !!(plan && plan.root_task_id === id && !ps),
+    };
+    const planDir = plan ? `${runs}/${plan.root_task_id}/` : `${runs}/${id}/`;
+    if (!t.dispatches.length) {
+      if (!ps) continue; // a plan root without any dispatch: nothing to show
+      const pov = t.overrides.slice().sort((a, b) => evMs(a) - evMs(b)).pop();
+      const pApproved = pov && evMs(pov) > (Date.parse(ps.plan.approved_at) || 0) ? pov.chosen_tier || null : null;
+      tasks.push(Object.assign({
+        task_id: id, task_type: ps.step.type || null, gate: 2, pending: true, verify_only: false, round: 0,
+      }, planInfo, {
+        approved_tier: pApproved || ps.step.tier || null, last_tier: null, attempts: [], user_verdict: null, last_steer: null,
+        run_dir: planDir, last_ts: null,
+      }));
+      continue;
+    }
+    const attempts = t.dispatches.slice().sort(byTime).map((d) => {
+      const vs = (agentVerdicts.get(d.agent_id) || []).slice().sort(byTime);
+      const last = vs[vs.length - 1];
+      let status;
+      if (last) status = last.outcome;
+      else status = completes.get(d.agent_id) ? 'done' : 'running';
+      return {
+        agent_id: d.agent_id, role: d.role || 'exec', try: d.try === undefined ? null : d.try,
+        model: shortModelName(d.model), effort: d.effort || null, status, _ms: evMs(d), _i: d._i,
+      };
+    });
+    const user = t.user.slice().sort((a, b) => ((Number(a.round) || 0) - (Number(b.round) || 0)) || byTime(a, b));
+    const lastUser = user[user.length - 1] || null;
+    let gate;
+    let round = lastUser ? (Number(lastUser.round) || user.length) : 0;
+    // attempts that count for the current round: after the latest user reject
+    const sinceMs = lastUser && lastUser.outcome === 'reject' ? evMs(lastUser) : -Infinity;
+    const live = attempts.filter((a) => a._ms > sinceMs || (a._ms === sinceMs && a._i > lastUser._i));
+    const execs = live.filter((a) => a.role === 'exec');
+    if (lastUser && lastUser.outcome === 'accept') {
+      gate = 'done';
+    } else if (!execs.length) {
+      gate = 1;
+    } else {
+      const running = live.some((a) => a.status === 'running' || a.status === 'done');
+      const lastExec = execs[execs.length - 1];
+      const lastPassIdx = execs.map((a) => a.status).lastIndexOf('pass');
+      const failAfterPass = execs.some((a, i) => AGENT_FAIL[a.status] && i > lastPassIdx);
+      if (running || lastPassIdx < 0 || failAfterPass || lastExec.status !== 'pass') gate = 2;
+      else gate = 3;
+    }
+    if (lastUser && lastUser.outcome === 'reject' && gate !== 'done') round = Number(lastUser.round) || round;
+    const lastExecAny = attempts.filter((a) => a.role === 'exec').pop() || null;
+    const ov = t.overrides.slice().sort(byTime).pop();
+    const st = t.steers.slice().sort(byTime).pop();
+    const first = t.dispatches[0] || {};
+    const lastMs = Math.max(0, ...attempts.map((a) => a._ms), ...user.map(evMs), ...t.steers.map(evMs));
+    // approved tier: the plan record's tier; an override logged after the approval wins; no plan -> override
+    const approvedMs = plan ? Date.parse(plan.approved_at) || 0 : 0;
+    let approved = null;
+    if (ps && ps.step.tier) approved = ps.step.tier;
+    if (ov && (!approved || evMs(ov) > approvedMs)) approved = ov.chosen_tier || approved;
+    tasks.push(Object.assign({
+      task_id: id,
+      task_type: (t.dispatches.find((d) => d.role === 'exec') || first).task_type || null,
+      gate,
+      pending: false,
+      verify_only: attempts.length > 0 && attempts.every((a) => a.role === 'verify'),
+      round,
+    }, planInfo, {
+      approved_tier: approved,
+      last_tier: lastExecAny ? tierOf(lastExecAny.model, lastExecAny.effort) : null,
+      attempts: attempts.map(({ _ms, _i, ...a }) => a),
+      user_verdict: lastUser ? { outcome: lastUser.outcome, cause: lastUser.cause || null, round: Number(lastUser.round) || null, ts: lastUser.ts } : null,
+      last_steer: st ? st.steer_kind || null : null,
+      run_dir: planDir,
+      last_ts: lastMs ? new Date(lastMs).toISOString() : null,
+    }));
+  }
+  return {
+    session_id: sessionId,
+    generated_at: nowIso(),
+    runs_dir: `${runs}/`,
+    plans: plans.map((p) => ({
+      root_task_id: p.root_task_id,
+      approval: Number.isInteger(p.approval) ? p.approval : (Number.isInteger(p.round) ? p.round : null),
+      approved_at: p.approved_at || null,
+      steps: p.steps.length, run_dir: `${runs}/${p.root_task_id}/`,
+    })),
+    tasks,
+  };
+}
+
+function toPosix(p) {
+  return String(p).replace(/\\/g, '/').replace(/\/+$/, '');
+}
+
+const GATE_LABEL = { 1: 'cổng 1 (kế hoạch/duyệt)', 2: 'cổng 2 (đang thực thi)', 3: 'cổng 3 (chờ nghiệm thu)', done: 'xong' };
+
+function gateLabel(t) {
+  if (t.pending) return 'chưa giao (cổng 2)';
+  if (t.is_root && t.gate === 1) return 'gốc kế hoạch';
+  if (t.verify_only && !t.root_task_id && t.gate === 1) return 'chỉ có verify';
+  return GATE_LABEL[t.gate] || String(t.gate);
+}
+
+function taskLines(t) {
+  const indent = t.root_task_id ? '  ' : '';
+  const head = `${indent}- ${t.step_id ? `bước ${t.step_id}: ` : ''}${t.task_id} [${t.task_type || '?'}] ${gateLabel(t)}`
+    + `${t.round ? ` · vòng ${t.round}` : ''}${t.approved_tier ? ` · duyệt ${t.approved_tier}` : ''}`
+    + `${t.last_tier && t.last_tier !== t.approved_tier ? ` · tier cuối ${t.last_tier}` : ''}`
+    + `${t.user_verdict ? ` · người dùng: ${t.user_verdict.outcome}${t.user_verdict.cause ? `/${t.user_verdict.cause}` : ''}` : ''}`
+    + `${t.last_steer ? ` · steer: ${t.last_steer}` : ''}`;
+  const att = t.attempts.map((a) => `${a.agent_id} ${a.role}${a.try ? ` try${a.try}` : ''} ${tierOf(a.model, a.effort) || '?'} ${a.status}`);
+  const out = [head];
+  if (att.length) out.push(`${indent}    ${att.join(' | ')}`);
+  if (!t.root_task_id) out.push(`    → ${t.run_dir}`); // plan members: the run dir is on the plan line
+  return out.join('\n');
+}
+
+/** Body lines: one block per approved plan (root first, then steps in plan order), then tasks without a plan. */
+function stateBody(state, kept) {
+  const lines = [];
+  const shown = state.tasks.filter((t) => kept.has(t));
+  for (const p of state.plans || []) {
+    const mine = shown.filter((t) => t.root_task_id === p.root_task_id);
+    if (!mine.length) continue;
+    lines.push(`Kế hoạch ${p.root_task_id} (lần duyệt ${p.approval === null ? '?' : p.approval}, lúc ${p.approved_at || '?'}, ${p.steps} bước) → ${p.run_dir}`);
+    for (const t of mine.filter((x) => x.is_root).concat(mine.filter((x) => !x.is_root))) lines.push(taskLines(t));
+  }
+  const loose = shown.filter((t) => !t.root_task_id);
+  if (loose.length && lines.length) lines.push('Không thuộc kế hoạch đã duyệt:');
+  for (const t of loose) lines.push(taskLines(t));
+  return lines;
+}
+
+/**
+ * Vietnamese text of a session state, at most `cap` chars. When too long, done tasks go first
+ * (oldest first), then the oldest open ones; the count of omitted tasks is stated.
+ */
+function formatSessionState(state, cap) {
+  const limit = cap || STATE_TEXT_CAP;
+  const open = state.tasks.filter((t) => t.gate !== 'done' && !t.pending);
+  const pending = state.tasks.filter((t) => t.pending).length;
+  const running = state.tasks.reduce((n, t) => n + t.attempts.filter((a) => a.status === 'running').length, 0);
+  const header = `Phiên ${state.session_id}: ${state.tasks.length} task (${open.length} chưa xong, ${pending} bước chưa giao, ${running} agent đang chạy). `
+    + `Thư mục chạy: ${state.runs_dir} (chỉ trỏ tới, không tự đọc).`;
+  if (!state.tasks.length) return `${header}\nChưa có task nào được giao trong phiên này.`;
+  const byAge = (a, b) => String(a.last_ts || '').localeCompare(String(b.last_ts || ''));
+  const dropOrder = state.tasks.filter((t) => t.gate === 'done').sort(byAge)
+    .concat(open.slice().sort(byAge), state.tasks.filter((t) => t.pending));
+  const kept = new Set(state.tasks);
+  const render = (omitted) => {
+    const body = stateBody(state, kept);
+    const tail = omitted ? `\n(bỏ bớt ${omitted} task cũ nhất để vừa ${limit} ký tự; xem đủ: dieu-phoi state --json)` : '';
+    return `${header}\n${body.join('\n')}${tail}`;
+  };
+  let omitted = 0;
+  let text = render(0);
+  while (text.length > limit && omitted < dropOrder.length) {
+    kept.delete(dropOrder[omitted]);
+    omitted++;
+    text = render(omitted);
+  }
+  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+
+/** SessionStart(compact): additionalContext with the state, only when the session dispatched via dieu-phoi. */
+function handleSessionStart(p, ctx) {
+  if (p.source && p.source !== 'compact') return null;
+  const sid = typeof p.session_id === 'string' ? p.session_id : null;
+  if (!sid) return null;
+  const events = readEvents(ctx);
+  if (!events.some((ev) => dispatchInSession(ev, sid))) return null;
+  const state = buildSessionState(events, sid, { plansDir: ctx.paths.plans });
+  const text = `${COMPACT_PREFIX}\n${formatSessionState(state, STATE_TEXT_CAP)}`;
+  return {
+    stdout: JSON.stringify({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: text } }),
+  };
+}
+
 // ------------------------------------------------------------------ hook handlers
 
 function extractAgentId(tr) {
@@ -536,6 +1122,10 @@ function buildDispatch(p, ctx) {
   const agentId = extractAgentId(tr)
     || (typeof p.tool_use_id === 'string' && p.tool_use_id ? p.tool_use_id : null)
     || `noid-${crypto.randomBytes(6).toString('hex')}`;
+  const orch = orchestratorUsage(p.transcript_path, loadPricing(ctx), {
+    cacheFile: orchCacheFile(ctx.paths, p.session_id, p.transcript_path),
+    coldMaxBytes: HOOK_COLD_MAX_BYTES,
+  });
   return Object.assign({
     schema: SCHEMA,
     kind: 'dispatch',
@@ -553,6 +1143,12 @@ function buildDispatch(p, ctx) {
     effort_inherited: !explicitEffort,
     subagent_type: typeof ti.subagent_type === 'string' && ti.subagent_type ? ti.subagent_type : 'general-purpose',
     background: ti.run_in_background === true || trObj.isAsync === true,
+    // Orchestrator (main session) at the moment of this dispatch. Raw session_id joins with `dieu-phoi ctx`.
+    session_id: typeof p.session_id === 'string' && p.session_id ? p.session_id : null,
+    orch_ctx_tokens: orch.ctx_tokens,
+    orch_ctx_baseline: orch.ctx_baseline,
+    orch_compactions: orch.compactions,
+    orch_cum_usd: orch.cum_usd,
   }, commonFields(ctx));
 }
 
@@ -681,7 +1277,10 @@ function readStdin() {
   return Buffer.concat(chunks).toString('utf8');
 }
 
-/** Process one hook payload. Never throws. Returns the written event (or null). */
+/**
+ * Process one hook payload. Never throws. Returns the written event, or for SessionStart { stdout } (the
+ * JSON the caller prints), or null. Nothing is printed here: stdout is written only after success.
+ */
 function runHook(opts) {
   const o = opts || {};
   let home = null;
@@ -693,6 +1292,7 @@ function runHook(opts) {
     const ctx = makeCtx(home);
     let ev = null;
     const name = p.hook_event_name;
+    if (name === 'SessionStart') return handleSessionStart(p, ctx); // { stdout } or null, never an event
     if (name === 'SubagentStop') ev = handleSubagentStop(p, ctx);
     else if (name === 'PostToolUse' || (!name && p.tool_name)) ev = handlePostToolUse(p, ctx);
     if (ev) {
@@ -844,11 +1444,12 @@ async function runSync(ctx, opts) {
 // ------------------------------------------------------------------ exports / main
 
 module.exports = {
+  runsDir, loadPlans, buildSessionState, formatSessionState, handleSessionStart, dispatchInSession, STATE_TEXT_CAP, COMPACT_PREFIX,
   CORE_VERSION, SCHEMA, TASK_TYPES, URGENCIES, ROLES, MODEL_ALIASES, UNTAGGED,
   sha8, nowIso, readJsonFile, writeFileAtomic, defaultClaudeDir, resolveHome, pathsFor, loadConfig, makeCtx,
   logError, computeUserHash, userHash, commonFields, parseTag, normalizeModel, loadPricing,
   priceFor, usageBuckets, requestCost, parseJsonl, readTranscript, lastUuidOf,
-  tagFromTranscript, summarizeTranscript, appendEvent, eventLinesFrom, readEventLines, readEvents,
+  tagFromTranscript, summarizeTranscript, orchestratorUsage, orchCacheFile, findSessionTranscript, SESSION_ID_RE, HOOK_COLD_MAX_BYTES, appendEvent, eventLinesFrom, readEventLines, readEvents,
   loadSyncOffset, saveSyncOffset, recordRejected, unsyncedInfo, loadSegments, saveSegments, segmentFile,
   extractAgentId, hasAssistantUsage, hasDispatch, buildDispatch, handlePostToolUse, handleSubagentStop, maybeSpawnSync, runHook, runSync,
 };
@@ -863,7 +1464,8 @@ if (require.main === module) {
       .catch((e) => logError(ctx.home, e, 'sync'))
       .finally(() => process.exit(0));
   } else {
-    runHook();
+    const r = runHook();
+    if (r && typeof r.stdout === 'string') process.stdout.write(r.stdout);
     process.exitCode = 0;
   }
 }