@kienntpixon/dieu-phoi 0.7.2 → 0.7.4

package/hook.cjs

@@ -6,7 +6,8 @@
  * This file is copied verbatim to ~/.claude/dieu-phoi/bin/hook.cjs by `dieu-phoi setup`
  * and run by Claude Code on PostToolUse(Agent), SubagentStop, SessionStart(compact) and UserPromptSubmit; the dp-* agent
  * files (`dieu-phoi setup` -> ~/.claude/agents) also run it inside those subagents as `--watch` (PostToolUse, context
- * handoff watchdog), `--gate` (PreToolUse(Agent), gen-2 helper rules) and `--gate-release`. It must stay
+ * handoff watchdog), `--gate` (PreToolUse(Agent), gen-2 helper rules), `--gate-bash` (PreToolUse(Bash), no
+ * `knowledge review|merge`) and `--gate-release`. It must stay
  * self-contained: Node built-ins only, no requires of other package files.
  *
  * Hook rules: stdout only for the JSON of SessionStart(compact) / UserPromptSubmit / a PostToolUse(Agent) warning
@@ -19,6 +20,7 @@
  *   node hook.cjs --watch    -> dp subagent PostToolUse: context watchdog (additionalContext JSON or nothing)
  *   node hook.cjs --gate     -> dp-exec PreToolUse(Agent): allow / deny a gen-2 helper spawn
  *   node hook.cjs --gate-release -> dp-exec PostToolUseFailure(Agent): give a failed spawn's helper slot back
+ *   node hook.cjs --gate-bash -> dp-* PreToolUse(Bash|PowerShell): deny `knowledge review|merge` in a subagent
  */
 
 const fs = require('fs');
@@ -26,7 +28,7 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 
-const CORE_VERSION = '0.7.2';
+const CORE_VERSION = '0.7.4';
 const SCHEMA = 1;
 const TASK_TYPES = [
   'search', 'extract', 'mechanical-edit', 'feature-impl', 'debug', 'refactor',
@@ -274,6 +276,8 @@ function parseTag(text) {
       tag.chain_ok = true; // core 0.7.1 (C1): the user agreed to continue a long handoff chain
     } else if (p === 'session_ok') {
       tag.session_ok = true; // core 0.7.2 (K5): the user agreed to open a new root in an oversized session
+    } else if (p === 'parallel_ok') {
+      tag.parallel_ok = true; // core 0.7.3 (s1): the user agreed to dispatch past the parallel cap
     } else if (p === 'batch') {
       tag.batch = true; // core 0.7.1 (C5): the one batched verifier of a fast request
     }
@@ -1170,8 +1174,8 @@ function buildSessionState(events, sessionId, opts) {
     if (!seenTask.has(id) && !discarded.has(id)) { seenTask.add(id); taskIds.push(id); }
   }
   const modeEvents = new Map();
-  for (const ev of events) if (ev && ev.kind === 'mode' && isMode(ev.mode) && typeof ev.root_task_id === 'string') modeEvents.set(ev.root_task_id, ev);
-  const modeOfRoot = (root) => (modeEvents.has(root) ? modeEvents.get(root).mode : DEFAULT_MODE);
+  for (const ev of events) if (ev && ev.kind === 'mode' && normMode(ev.mode) && typeof ev.root_task_id === 'string') modeEvents.set(ev.root_task_id, ev);
+  const modeOfRoot = (root) => (modeEvents.has(root) ? normMode(modeEvents.get(root).mode) : DEFAULT_MODE);
   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;
@@ -1223,7 +1227,7 @@ function buildSessionState(events, sessionId, opts) {
       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,
-        mode: isMode(ps.step.mode) ? ps.step.mode : modeOfRoot(ps.plan.root_task_id),
+        mode: normMode(ps.step.mode) || modeOfRoot(ps.plan.root_task_id),
       }, planInfo, {
         approved_tier: pApproved || ps.step.tier || null, last_tier: null, attempts: [], user_verdict: null, last_steer: null,
         run_dir: planDir, last_ts: null,
@@ -1281,7 +1285,7 @@ function buildSessionState(events, sessionId, opts) {
       pending: false,
       verify_only: attempts.length > 0 && attempts.every((a) => a.role === 'verify'),
       round,
-      mode: dispatchModeFromEvents(t.dispatches, id) || (ps && isMode(ps.step.mode) ? ps.step.mode : modeOfRoot(plan ? plan.root_task_id : id)),
+      mode: dispatchModeFromEvents(t.dispatches, id) || (ps && normMode(ps.step.mode)) || modeOfRoot(plan ? plan.root_task_id : id),
     }, planInfo, {
       approved_tier: approved,
       last_tier: lastExecAny ? tierOf(lastExecAny.model, lastExecAny.effort) : null,
@@ -1299,12 +1303,9 @@ function buildSessionState(events, sessionId, opts) {
   for (const [root, ev] of modeEvents) if (ev.session_id === sessionId || ev.session === sidHash) modeRoots.add(root);
   const modes = Array.from(modeRoots).map((root) => {
     const ev = modeEvents.get(root);
-    const mode = ev ? ev.mode : DEFAULT_MODE;
-    // core 0.7.0 (s2): suggestion only — the mode itself never changes here
-    const sug = modeSuggestion(events, root, { mode, taskIds: rootTaskIds(allPlans, root) });
+    const mode = ev ? normMode(ev.mode) : DEFAULT_MODE;
     return {
       root_task_id: root, mode, since: ev ? ev.ts : null, source: ev ? ev.source || null : 'default', reason_code: ev ? ev.reason_code || null : null,
-      mode_suggest: sug.mode_suggest, mode_suggest_reason: sug.mode_suggest_reason,
     };
   });
   const orphans = findOrphanAgents(events, taskIds.filter((id) => !discarded.has(id)), { nowMs: o.nowMs });
@@ -1468,14 +1469,7 @@ function compactSystemMessage(state) {
 function modesLine(state) {
   const ms = Array.isArray(state.modes) ? state.modes : [];
   if (!ms.length) return '';
-  const sug = ms.slice(-6).filter((m) => m.mode_suggest).map((m) => `\n${modeSuggestLine(m.root_task_id, m.mode, m.mode_suggest_reason)}`).join('');
-  return `\nMode (theo yêu cầu, đổi bằng \`dieu-phoi mode --root <id> <mode>\`): ${ms.slice(-6).map((m) => `${m.root_task_id}=${m.mode}`).join(', ')}.${sug}`;
-}
-
-/** One line telling the orchestrator to ASK the user about returning to normal (never switch by itself). */
-function modeSuggestLine(root, mode, reason) {
-  return `GỢI Ý mode: ${root ? `${root} đang ${mode}` : `đang ${mode}`} — hỏi người dùng có muốn quay về normal không (${reason}); `
-    + `chỉ đổi khi người dùng đồng ý: \`dieu-phoi mode --root ${root || '<root>'} normal\`. KHÔNG tự đổi mode.`;
+  return `\nMode (theo yêu cầu, đổi bằng \`dieu-phoi mode --root <id> <mode>\`): ${ms.slice(-6).map((m) => `${m.root_task_id}=${m.mode}`).join(', ')}.`;
 }
 
 function formatSessionState(state, cap) {
@@ -1693,9 +1687,10 @@ function orchLessonLines(info) {
   return ls.length ? ['bài học cho điều phối viên (profile/lessons.md, [orch]):'].concat(ls.map((l) => `  - ${l}`)) : [];
 }
 
-/** Gate-1 mode line: the chosen mode, or the reminder to ASK the user (default normal). */
+/** Gate-1 mode line: only when a mode was chosen (`start --mode fast`); '' otherwise (no mode question, default normal). */
 function modeLine(info) {
-  return info && isMode(info.mode) ? `mode: ${info.mode} (đã ghi cho root ${info.id}; đổi: dieu-phoi mode --root ${info.id} <mode>)` : MODE_ASK_LINE;
+  const m = info && normMode(info.mode);
+  return m ? `mode: ${m} (đã ghi cho root ${info.id}; đổi: dieu-phoi mode --root ${info.id} <mode>)` : '';
 }
 
 function formatStartBlock(info) {
@@ -1710,16 +1705,23 @@ function formatStartBlock(info) {
     ...orchLessonLines(info),
     ...knowledgeLines(info),
     'Dùng khối này cho yêu cầu MỚI ở cổng 1 (không dùng nếu đang giữa một lần điều phối). Không chạy `dieu-phoi doctor` / `new-id` / mkdir: lượt đầu tiên là Agent scout + câu hỏi cổng 1 cho người dùng.',
-  ].join('\n');
+  ].filter((l) => l !== '').join('\n');
 }
 
 /** UserPromptSubmit: on a dieu-phoi prompt, pre-create the run and inject id/run dir/health/brief. */
 function handleUserPromptSubmit(p, ctx) {
-  if (!isDieuPhoiPrompt(p.prompt)) return null;
+  // s6: stuck/orphaned agents of this session → TaskStop + reap reminder, on any prompt (not only dieu-phoi ones)
+  const stuck = typeof p.session_id === 'string' && p.session_id && !watchAgentId(p) ? stuckReminder(ctx, { sessionId: p.session_id }) : null;
+  if (!isDieuPhoiPrompt(p.prompt)) {
+    if (!stuck) return null;
+    return { stdout: JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: stuck } }), stuck: true };
+  }
   const info = startInfo(ctx, typeof p.cwd === 'string' ? p.cwd : null);
+  const text = stuck ? `${formatStartBlock(info)}
+${stuck}` : formatStartBlock(info);
   return {
     stdout: JSON.stringify({
-      hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: formatStartBlock(info) },
+      hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text },
     }),
     info,
   };
@@ -1861,29 +1863,36 @@ function handoffChainMessage(taskId, n) {
   return `dieu-phoi: task ${taskId} đã handoff ${n} lần (cảnh báo từ ${HANDOFF_CHAIN_WARN}; từ ${HANDOFF_CHAIN_DENY} hook chặn lượt exec tiếp nối, trừ thẻ có \`chain_ok\` khi người dùng đồng ý). Đừng nối tiếp thêm: nếu agent vừa giao là agent tiếp nối, cân nhắc dừng nó và giao planner (dp-scout) đọc handoff-${taskId}.md rồi chia phần còn lại thành bước mới (task_id mới từ \`dieu-phoi new-id\`).`;
 }
 
-// ------------------------------------------------------------------ core 0.7.0: mode per request (fast | normal | strict)
+// ------------------------------------------------------------------ core 0.7.0: mode per request (fast | normal; 0.7.4: strict removed)
 //
 // A request (root_task_id) has a mode; the user picks it at gate 1 (`start --mode`, `plan-table` file, or
 // `dieu-phoi mode --root R <mode>` at any time). Every change is one local-only event kind=mode. A step not yet
 // dispatched follows the root's current mode (or its own `mode` override in the approved plan); a step already
 // dispatched keeps the mode its first exec dispatch recorded. Nothing here ever changes a mode by itself.
 
-const MODES = ['fast', 'normal', 'strict'];
+const MODES = ['fast', 'normal'];
 const DEFAULT_MODE = 'normal';
+/** Removed in 0.7.4: old events/plans/configs may still carry it; every reader treats it as normal. */
+const LEGACY_MODE = 'strict';
 /** Event kinds that stay on this machine: runSync does not send them (an older sink would answer bad_kind). */
-const LOCAL_ONLY_KINDS = new Set(['mode', 'knowledge_merge', 'leftover', 'worktree']);
-const MODE_ASK_LINE = 'mode: chưa chọn — chỉ hỏi ở cổng 1 khi plan-table báo ≥4 bước s≤6 (fast | normal | strict, mặc định normal); '
-  + 'đặt bằng `dieu-phoi mode --root <root_task_id> <mode>`';
-
+const LOCAL_ONLY_KINDS = new Set(['mode', 'knowledge_merge', 'leftover', 'worktree', 'reap', 'reap_orphans']);
+/** A mode the user may choose now (fast | normal). */
 function isMode(m) {
   return typeof m === 'string' && MODES.includes(m);
 }
 
+/** Mode as stored/read: fast | normal; legacy 'strict' reads as normal; anything else null. */
+function normMode(m) {
+  if (typeof m !== 'string') return null;
+  if (m === LEGACY_MODE) return DEFAULT_MODE;
+  return MODES.includes(m) ? m : null;
+}
+
 /** Last mode event of `root` in an events array (null when none). */
 function rootModeFromEvents(events, root) {
   let last = null;
   for (const ev of events) {
-    if (ev && ev.kind === 'mode' && ev.root_task_id === root && isMode(ev.mode)) last = ev;
+    if (ev && ev.kind === 'mode' && ev.root_task_id === root && normMode(ev.mode)) last = ev.mode === normMode(ev.mode) ? ev : Object.assign({}, ev, { mode: normMode(ev.mode) });
   }
   return last;
 }
@@ -1901,7 +1910,7 @@ function rootModeFromText(txt, root) {
     if (line.includes(rootNeedle)) {
       try {
         const ev = JSON.parse(line);
-        if (ev && ev.kind === 'mode' && isMode(ev.mode)) last = ev;
+        if (ev && ev.kind === 'mode' && normMode(ev.mode)) last = ev.mode === normMode(ev.mode) ? ev : Object.assign({}, ev, { mode: normMode(ev.mode) });
       } catch (_) { /* corrupt line */ }
     }
     i = end < 0 ? -1 : txt.indexOf(needle, end);
@@ -1912,7 +1921,7 @@ function rootModeFromText(txt, root) {
 /** Mode the first exec dispatch of `taskId` recorded (a dispatched step keeps its mode), from an events array. */
 function dispatchModeFromEvents(events, taskId) {
   for (const ev of events) {
-    if (ev && ev.kind === 'dispatch' && ev.task_id === taskId && (ev.role || 'exec') === 'exec' && isMode(ev.mode)) return ev.mode;
+    if (ev && ev.kind === 'dispatch' && ev.task_id === taskId && (ev.role || 'exec') === 'exec' && normMode(ev.mode)) return normMode(ev.mode);
   }
   return null;
 }
@@ -1926,7 +1935,7 @@ function dispatchModeFromText(txt, taskId) {
     const line = txt.slice(start, end < 0 ? undefined : end);
     if (line.includes('"kind":"dispatch"') && !line.includes('"role":"verify"') && !line.includes('"role":"plan"') && !line.includes('"role":"helper"')) {
       const m = /"mode":"(fast|normal|strict)"/.exec(line);
-      if (m) return m[1];
+      if (m) return normMode(m[1]);
     }
     i = end < 0 ? -1 : txt.indexOf(needle, end);
   }
@@ -1957,7 +1966,7 @@ function taskModeInfo(ctx, taskId, events) {
     const locked = events ? dispatchModeFromEvents(events, taskId) : dispatchModeFromText(txt, taskId);
     if (locked) return { mode: locked, source: 'dispatched', root };
   }
-  if (pl && pl.step && isMode(pl.step.mode)) return { mode: pl.step.mode, source: 'step', root };
+  if (pl && pl.step && normMode(pl.step.mode)) return { mode: normMode(pl.step.mode), source: 'step', root };
   if (root) {
     const ev = events ? rootModeFromEvents(events, root) : rootModeFromText(txt, root);
     if (ev) return { mode: ev.mode, source: 'root', root };
@@ -1965,90 +1974,6 @@ function taskModeInfo(ctx, taskId, events) {
   return { mode: DEFAULT_MODE, source: 'default', root };
 }
 
-// core 0.7.0 (s2): signals for SUGGESTING a return to normal. The CLI never switches the mode itself; only the
-// user's `dieu-phoi mode` does. A suggestion is computed only while the root is in fast.
-const FAST_FAIL_WINDOW = 10;     // last N fast exec steps (all roots, file order of their first exec dispatch)
-const FAST_FAIL_MIN_N = 5;       // fewer fast steps than this -> no rate signal yet
-const FAST_FAIL_RATE = 0.15;     // >= this share failed -> suggest normal
-const BATCH_VERIFY_RE = /^batch-verify(?:-|$)/;
-const QUOTA_VERDICT_RE = /^(?:quota-pause|usage-limit|auto-quota-pause|auto-usage-limit|paused-for-quota)(?:-|$)/;
-
-/** A user reject that counts as a quality signal (legacy `rework` too); scope rejects (request changed) do not. */
-function isQualityReject(ev) {
-  if (ev.outcome === 'rework' && !ev.by) return true;
-  return ev.by === 'user' && ev.outcome === 'reject' && ev.cause !== 'scope';
-}
-
-/** Agent-layer fail (fail / timeout, never a quota pause or aborted). */
-function isAgentFail(ev) {
-  if (ev.by === 'user' || ev.by === 'auto') return false;
-  if (ev.outcome === 'fail') return true;
-  return ev.outcome === 'timeout' && !QUOTA_VERDICT_RE.test(String(ev.reason_code || ''));
-}
-
-/**
- * Fail rate over the last FAST_FAIL_WINDOW fast exec steps (any root): a step is a task whose first exec dispatch
- * recorded mode=fast; it failed when it has an agent-layer fail or a quality reject. Discarded tasks are left out.
- * Returns { n, failed, rate } (rate null when n = 0).
- */
-function fastFailRate(events) {
-  const gone = new Set();
-  for (const ev of events) if (ev && ev.kind === 'discard' && typeof ev.task_id === 'string') gone.add(ev.task_id);
-  const order = [];
-  const seen = new Set();
-  for (const ev of events) {
-    if (!ev || ev.kind !== 'dispatch' || typeof ev.task_id !== 'string' || !ev.task_id) continue;
-    if ((ev.role || 'exec') !== 'exec' || seen.has(ev.task_id)) continue;
-    seen.add(ev.task_id);
-    if (ev.mode === 'fast' && !gone.has(ev.task_id)) order.push(ev.task_id);
-  }
-  const win = new Set(order.slice(-FAST_FAIL_WINDOW));
-  const failed = new Set();
-  for (const ev of events) {
-    if (ev && ev.kind === 'verdict' && win.has(ev.task_id) && (isAgentFail(ev) || isQualityReject(ev))) failed.add(ev.task_id);
-  }
-  return { n: win.size, failed: failed.size, rate: win.size ? failed.size / win.size : null };
-}
-
-/**
- * Should the orchestrator SUGGEST (never apply) a return to normal for `root`? Only while `mode` (the root's current
- * mode) is fast. Signals, each with a short Vietnamese reason:
- *   - batch-verify: an agent verdict fail with reason batch-verify on a task of the root, after the root's last mode event;
- *   - reject: a quality reject (user) on a task of the root, after that mode event;
- *   - fail-rate: >= 15% failed among the last 10 fast steps (all roots; needs >= 5 steps).
- * `taskIds` = the root and its plan's step task ids. Returns { mode_suggest: 'normal'|null, mode_suggest_reason,
- * mode_suggest_signals[] }.
- */
-function modeSuggestion(events, root, o) {
-  const opts = o || {};
-  const none = { mode_suggest: null, mode_suggest_reason: null, mode_suggest_signals: [] };
-  if (opts.mode !== 'fast') return none;
-  const ids = new Set(opts.taskIds || []);
-  if (root) ids.add(root);
-  const last = root ? rootModeFromEvents(events, root) : null;
-  const since = last ? (Date.parse(last.ts) || 0) : 0;
-  const signals = [];
-  const reasons = [];
-  let batch = null;
-  let reject = null;
-  for (const ev of events) {
-    if (!ev || ev.kind !== 'verdict' || !ids.has(ev.task_id)) continue;
-    const t = Date.parse(ev.ts) || 0;
-    if (t < since) continue;
-    if (!batch && ev.outcome === 'fail' && BATCH_VERIFY_RE.test(String(ev.reason_code || ''))) batch = ev.task_id;
-    if (!reject && isQualityReject(ev)) reject = ev.task_id;
-  }
-  if (batch) { signals.push('batch-verify'); reasons.push(`verifier gộp báo fail (task ${batch})`); }
-  if (reject) { signals.push('reject'); reasons.push(`người dùng reject (task ${reject})`); }
-  const fr = fastFailRate(events);
-  if (fr.n >= FAST_FAIL_MIN_N && fr.rate >= FAST_FAIL_RATE) {
-    signals.push('fail-rate');
-    reasons.push(`${fr.failed}/${fr.n} bước fast gần nhất fail (${Math.round(fr.rate * 100)}% ≥ ${Math.round(FAST_FAIL_RATE * 100)}%)`);
-  }
-  if (!signals.length) return none;
-  return { mode_suggest: 'normal', mode_suggest_reason: reasons.join('; '), mode_suggest_signals: signals };
-}
-
 /** Task ids of a root: the root itself plus the step task ids of its approved plan (if any). */
 function rootTaskIds(plans, root) {
   const out = new Set(root ? [root] : []);
@@ -2321,8 +2246,10 @@ function readHead(start) {
 
 // ------------------------------------------------------------------ core 0.6.0, s3: knowledge freshness
 //
-// A knowledge section is stale when a file matching its `paths` globs differs between the commit it was merged at
-// (`sha`) and the HEAD of the worktree asking. Used by the start block here and by `knowledge get/list/status`
+// A knowledge section is stale when a file named by one of its plain (non-glob) `paths` entries differs between the
+// commit it was merged at (`sha`) and the HEAD of the worktree asking. A file that only matches a glob entry (`**`,
+// `*`, `?`) gives state `drift`: shown lightly, never counted as stale (rule 2, 0.7.4 s5; cache entries carry `rule`).
+// Used by the start block here and by `knowledge get/list/status`
 // (lib/knowledge.cjs). Lives in hook.cjs because the installed hook is a single file (builtins only). Rules, from
 // measurements on the pixon-fast-forward repos (contract r1-2 §2):
 //   - ONE git process per check, whatever the number of distinct section shas: `git diff-tree --stdin` reads one
@@ -2341,8 +2268,69 @@ const FRESH_CACHE_MAX = 12; // HEADs remembered per store (worktrees of one repo
 const DIFF_TIMEOUT_MS = 10000;
 const HOOK_DIFF_TIMEOUT_MS = 1500;
 const DIRTY_TIMEOUT_MS = 2000;
+// Tests only: DIEU_PHOI_GIT_STATUS_TIMEOUT_MS overrides the `git status` bound of --dirty (a busy Windows box overruns 2 s);
+// invalid or non-positive values are ignored, the product default stays DIRTY_TIMEOUT_MS.
+function dirtyTimeoutMs() {
+  const v = Number(process.env.DIEU_PHOI_GIT_STATUS_TIMEOUT_MS);
+  return Number.isFinite(v) && v > 0 ? v : DIRTY_TIMEOUT_MS;
+}
 const PATHSPEC_MAX_CHARS = 6000; // beyond this: no pathspec (Windows command line limit), filter in JS only
 const STALE_FILES_KEEP = 50; // stale files kept per section (the count stays exact)
+const FRESH_RULE = 4; // 4 (0.7.4 s9): rule 3 + identifiers compared as nameKey (kebab/camel match), >= 3 chars; cache of rule 3 dropped
+const GLOB_CHARS_RE = /[*?]/;
+const LARGE_FILE_BYTES = 30000; // above this a plain path counts only when a changed line names one of the entry's identifiers
+// A changed line that is only a version bump (package.json, SKILL.md frontmatter, a `const CORE_VERSION = '…'` in code) or blank: routine, never stale.
+const ROUTINE_LINE_RES = [/^\s*$/, /^\s*"version"\s*:\s*"[^"]*",?\s*$/, /^\s*version\s*:\s*[^\s#]+\s*$/,
+  /^\s*(?:const|let|var)\s+\w*VERSION\w*\s*=\s*(['"])[^'"]*\1;?\s*$/];
+// Words too common in code to tell an entry's identifiers from ordinary lines.
+const NAME_STOPWORDS = new Set(['const', 'return', 'function', 'string', 'number', 'object', 'boolean', 'undefined',
+  'files', 'file', 'json', 'path', 'paths', 'value', 'values', 'state', 'null', 'true', 'false', 'test', 'tests', 'node', 'cli']);
+
+function plainPathsOf(s) { return (s.paths || []).filter((g) => !GLOB_CHARS_RE.test(g)); }
+function isChangelogPath(f) { return /(^|\/)CHANGELOG[^/]*$/i.test(f); }
+function entryAboutChangelog(s) { return [s.id, s.title, ...(s.tags || [])].some((x) => /changelog/i.test(String(x || ''))); }
+function isRoutineLine(t) { return ROUTINE_LINE_RES.some((re) => re.test(t)); }
+function isLargeFile(root, f) {
+  try { return fs.statSync(path.join(root, f)).size > LARGE_FILE_BYTES; } catch (_) { return false; }
+}
+function readSectionBody(dir, id) {
+  try { return fs.readFileSync(path.join(dir, 'sections', `${id}.md`), 'utf8'); } catch (_) { return ''; }
+}
+/** Comparable form of an identifier: lower-case letters and digits only (`plan-table` ~ `cmdPlanTable` ~ `plantable`). */
+function nameKey(t) { return String(t || '').toLowerCase().replace(/[^a-z0-9]/g, ''); }
+/** Identifiers an entry names: the pieces of its backtick spans and the words of its id (nameKey form, >= 3 chars). */
+function namesOf(s, body) {
+  const out = new Set();
+  for (const m of String(body || '').matchAll(/`([^`\n]{2,200})`/g)) {
+    for (const t of m[1].split(/[\s(),;:=<>[\]{}'"|]+/)) {
+      const low = nameKey(t);
+      if (low.length >= 3 && /[a-z]/.test(low) && !NAME_STOPWORDS.has(low)) out.add(low);
+    }
+  }
+  for (const p of String(s.id || '').split('-')) if (p.length >= 5) out.add(nameKey(p));
+  return Array.from(out);
+}
+/**
+ * Changed lines (added and removed text, no diff markers) of `files` between sha and head, one git diff with -U0.
+ * Returns { byFile: Map<file, string[]> } or null when git fails.
+ */
+function changedLinesOf(root, sha, head, files, timeoutMs) {
+  const r = runGit(root, ['--literal-pathspecs', 'diff', '-U0', '--no-renames', '--no-color', '--no-ext-diff', sha, head, '--', ...files], undefined, timeoutMs);
+  if (!r.ok) return null;
+  const byFile = new Map();
+  let cur = null;
+  let inHunk = false;
+  for (const raw of r.stdout.split('\n')) {
+    const line = raw.replace(/\r$/, '');
+    if (line.startsWith('diff --git ')) {
+      const m = / b\/(.*)$/.exec(line);
+      cur = m ? m[1] : null; inHunk = false;
+      if (cur && !byFile.has(cur)) byFile.set(cur, []);
+    } else if (line.startsWith('@@')) inHunk = true;
+    else if (inHunk && cur && (line.startsWith('+') || line.startsWith('-'))) byFile.get(cur).push(line.slice(1));
+  }
+  return { byFile };
+}
 const FULL_SHA_RE = /^[0-9a-f]{40}([0-9a-f]{24})?$/i;
 
 /**
@@ -2435,7 +2423,7 @@ function diffShas(root, shas, head, globs, timeoutMs) {
 function dirtyFiles(root, globs, timeoutMs) {
   const spec = pathspecOf(globs);
   const base = ['status', '--porcelain=v1', '-z', '-uno', '--no-renames'];
-  const r = runGit(root, spec ? base.concat('--', spec) : base, undefined, timeoutMs || DIRTY_TIMEOUT_MS);
+  const r = runGit(root, spec ? base.concat('--', spec) : base, undefined, timeoutMs || dirtyTimeoutMs());
   if (!r.ok) return { error: r.error, timedOut: !!r.timedOut, ms: r.ms };
   const files = r.stdout.split('\0').filter((x) => x.length > 3).map((x) => x.slice(3));
   return { files, ms: r.ms };
@@ -2461,7 +2449,7 @@ function readFreshCache(dir) {
 
 function cachedFor(dir, head, stamp) {
   if (!head || !stamp) return null;
-  return readFreshCache(dir).entries.find((e) => e.head === head && e.index_mtime === stamp.mtime && e.index_size === stamp.size) || null;
+  return readFreshCache(dir).entries.find((e) => e.rule === FRESH_RULE && e.head === head && e.index_mtime === stamp.mtime && e.index_size === stamp.size) || null;
 }
 
 /** Best effort (tmp+rename, last writer wins); a store that vanished or is read-only only loses the cache. */
@@ -2473,7 +2461,7 @@ function writeFreshCache(dir, entry) {
 }
 
 function freshCounts(sections) {
-  const c = { total: 0, fresh: 0, stale: 0, unknown: 0 };
+  const c = { total: 0, fresh: 0, stale: 0, drift: 0, unknown: 0 };
   for (const s of Object.values(sections)) { c.total++; c[s.state] = (c[s.state] || 0) + 1; }
   return c;
 }
@@ -2500,7 +2488,8 @@ function computeFreshness(o) {
   if (!head) why = o.head && o.head.unsupported ? `HEAD không đọc được từ file (${o.head.unsupported})` : 'không đọc được HEAD (repo chưa có commit?)';
   else if (!o.root) why = 'repo không có thư mục làm việc (bare)';
   for (const s of idx.sections) {
-    const sha = String(s.sha || '').toLowerCase();
+    // review mark (s6): an entry reviewed at reviewed_sha (full sha) is judged from that sha on; a merge that replaces the entry drops the mark
+    const sha = String(FULL_SHA_RE.test(String(s.reviewed_sha || '')) ? s.reviewed_sha : (s.sha || '')).toLowerCase();
     if (why) sections[s.id] = { state: 'unknown', why };
     else if (!sha || sha === 'none') sections[s.id] = { state: 'unknown', why: 'mục chưa có sha' };
     else if (sha === head) sections[s.id] = { state: 'fresh' };
@@ -2514,19 +2503,65 @@ function computeFreshness(o) {
     const d = diffShas(o.root, Array.from(pending.keys()), head, globs, o.timeoutMs || DIFF_TIMEOUT_MS);
     out.ms_git = d.ms || 0;
     if (d.error) error = d.error;
+    // rule 3 (0.7.4 s5b): read the changed lines of the plain-path files that could make an entry stale (one git
+    // diff per distinct sha, only on a cache miss); CHANGELOG files an entry is not about are never read
+    const timeout = o.timeoutMs || DIFF_TIMEOUT_MS;
+    const want = new Map(); // sha -> Set(file)
+    for (const [sha, list] of pending) {
+      if (d.error || d.missing.has(sha)) continue;
+      for (const s of list) {
+        const plain = plainPathsOf(s);
+        for (const f of d.bySha.get(sha) || []) {
+          if (!plain.some((g) => globMatch(g, f))) continue;
+          if (isChangelogPath(f) && !entryAboutChangelog(s)) continue;
+          if (!want.has(sha)) want.set(sha, new Set());
+          want.get(sha).add(f);
+        }
+      }
+    }
+    const lines = new Map(); // `${sha}\0${file}` -> changed texts, or null when git could not say
+    for (const [sha, set] of want) {
+      const r = changedLinesOf(o.root, sha, head, Array.from(set), timeout);
+      for (const f of set) lines.set(`${sha}\0${f}`, r ? (r.byFile.get(f) || []) : null);
+    }
+    const names = new Map(); // section id -> identifiers it names (read lazily)
+    const namesFor = (s) => {
+      if (!names.has(s.id)) names.set(s.id, namesOf(s, readSectionBody(o.dir, s.id)));
+      return names.get(s.id);
+    };
+    const counts = (sha, s, f) => { // does this changed plain-path file make the entry stale?
+      if (isChangelogPath(f) && !entryAboutChangelog(s)) return false;
+      const texts = lines.get(`${sha}\0${f}`);
+      if (!texts) return true; // content unknown: count the change, never hide it
+      const real = texts.filter((t) => !isRoutineLine(t));
+      if (!real.length) return false; // only version bumps / blank lines
+      if (!isLargeFile(o.root, f)) return true;
+      const nm = namesFor(s);
+      return real.some((t) => { const low = nameKey(t); return nm.some((x) => low.includes(x)); });
+    };
     for (const [sha, list] of pending) {
       for (const s of list) {
         if (d.error) { sections[s.id] = { state: 'unknown', why: `git diff-tree lỗi: ${d.error}` }; continue; }
         if (d.missing.has(sha)) { sections[s.id] = { state: 'unknown', why: `commit ${sha.slice(0, 7)} không có trong repo này (clone/nhánh khác chưa fetch?)` }; continue; }
-        const files = d.bySha.get(sha).filter((f) => (s.paths || []).some((g) => globMatch(g, f)));
-        sections[s.id] = files.length ? { state: 'stale', files: files.slice(0, STALE_FILES_KEEP), n_files: files.length } : { state: 'fresh' };
+        const changed = d.bySha.get(sha) || [];
+        const plain = plainPathsOf(s);
+        const globPaths = (s.paths || []).filter((g) => GLOB_CHARS_RE.test(g));
+        const named = [];
+        const soft = []; // changed, but not counted as stale: glob-only, routine, CHANGELOG, lines the entry does not name
+        for (const f of changed) {
+          if (plain.some((g) => globMatch(g, f))) (counts(sha, s, f) ? named : soft).push(f);
+          else if (globPaths.some((g) => globMatch(g, f))) soft.push(f);
+        }
+        if (named.length) sections[s.id] = { state: 'stale', files: named.slice(0, STALE_FILES_KEEP), n_files: named.length };
+        else if (soft.length) sections[s.id] = { state: 'drift', files: soft.slice(0, STALE_FILES_KEEP), n_files: soft.length };
+        else sections[s.id] = { state: 'fresh' };
       }
     }
   }
   Object.assign(out, { computed: new Date().toISOString(), sections, counts: freshCounts(sections) });
   if (error) out.error = error;
   if (head && !error && o.cache !== false && stamp) {
-    writeFreshCache(o.dir, { head, index_mtime: stamp.mtime, index_size: stamp.size, computed: out.computed, sections });
+    writeFreshCache(o.dir, { rule: FRESH_RULE, head, index_mtime: stamp.mtime, index_size: stamp.size, computed: out.computed, sections });
   }
   return out;
 }
@@ -2551,12 +2586,14 @@ function shortFileList(files, n) {
   return f.slice(0, k).join(', ') + (f.length > k ? ` (+${f.length - k})` : '');
 }
 
-/** "N mục, k stale (ids), u không xác định (ids)". */
+/** "N mục, k stale (ids), d drift (ids), u không xác định (ids)"; drift only when present (it is not stale). */
 function knowledgeSummary(fr, n) {
   const ids = (st) => Object.keys(fr.sections).filter((id) => fr.sections[id].state === st);
   const stale = ids('stale');
+  const drift = ids('drift');
   const unk = ids('unknown');
   const parts = [`${n} mục`, `${stale.length} stale${stale.length ? ` (${shortFileList(stale, 6)})` : ''}`];
+  if (drift.length) parts.push(`${drift.length} drift (${shortFileList(drift, 4)})`);
   if (unk.length) parts.push(`${unk.length} không xác định (${shortFileList(unk, 4)})`);
   return parts.join(', ');
 }
@@ -2900,6 +2937,7 @@ function buildDispatch(p, ctx) {
     ...(tag.type_alias_from ? { type_alias_from: tag.type_alias_from } : {}),
     ...(tag.chain_ok ? { chain_ok: true } : {}),
     ...(tag.session_ok ? { session_ok: true } : {}),
+    ...(tag.parallel_ok ? { parallel_ok: true } : {}),
     ...(tag.batch ? { batch: true } : {}),
     ...(dispatchRun(ti.prompt) ? { run: dispatchRun(ti.prompt) } : {}),
     task_type: tag.task_type,
@@ -2918,7 +2956,7 @@ function buildDispatch(p, ctx) {
     orch_ctx_baseline: orch.ctx_baseline,
     orch_compactions: orch.compactions,
     orch_cum_usd: orch.cum_usd,
-  }, tag.parent_task_id ? { parent_task_id: tag.parent_task_id } : {},
+  }, dispatchLiveCounts(ctx, p, tag), tag.parent_task_id ? { parent_task_id: tag.parent_task_id } : {},
   projectFields(p),
   modeFields(ctx, tag),
   tierFields(ctx, tag, normalizeModel(trObj.resolvedModel) || normalizeModel(ti.model) || null, explicitEffort || parentEffort || null),
@@ -2992,6 +3030,12 @@ function handlePostToolUse(p, ctx) {
   }
   appendEvent(ctx, ev);
   if (implicit) appendEvent(ctx, implicit);
+  // s6: the orchestrator just dispatched: remind it of its stuck/orphaned agents (main session only; an exec hears about
+  // its own helpers through --watch)
+  if (!watchAgentId(p) && typeof p.session_id === 'string' && p.session_id) {
+    const stuck = stuckReminder(ctx, { sessionId: p.session_id });
+    if (stuck) notes.push(stuck);
+  }
   if (notes.length) {
     Object.defineProperty(ev, 'stdout', {
       enumerable: false,
@@ -3286,7 +3330,7 @@ function openBackgroundTasks(lines) {
   return Array.from(open, ([k, v]) => v || k);
 }
 
-function handleSubagentStop(p, ctx) {
+function handleSubagentStop(p, ctx, opt) {
   const agentId = typeof p.agent_id === 'string' && p.agent_id ? p.agent_id : null;
   if (!agentId) return null;
   const prev = loadSegments(ctx, agentId);
@@ -3385,7 +3429,14 @@ function handleSubagentStop(p, ctx) {
   }
   // s16 (core 0.7.2): processes the agent left behind (report; kill only with config kill_leftovers). Never throws, bounded to ~5 s.
   if (tag && tag.task_id && exists) {
-    try { scanLeftoverProcs(ctx, { agentId, taskId: tag.task_id, lines }); } catch (e) { logError(ctx.home, e, 'leftover-procs'); }
+    const live = opt && opt.live ? opt.live : null;
+    try {
+      scanLeftoverProcs(ctx, {
+        agentId, taskId: tag.task_id, lines, worktree: live && live.cwd ? live.cwd : null, liveStart: live ? live.start : null,
+        sessionCwd: typeof p.cwd === 'string' ? p.cwd : null,
+        sessionTranscript: typeof p.transcript_path === 'string' ? p.transcript_path : (live && live.session_transcript) || null,
+      });
+    } catch (e) { logError(ctx.home, e, 'leftover-procs'); }
   }
   return ev;
 }
@@ -3441,15 +3492,19 @@ function otherAgentsRunning(events, agentId, startMs, endMs) {
 /**
  * Looks at the process table after a dp agent stopped. Descendants of this session's Claude Code process created since the
  * agent started and still alive (not the hook's own chain, not claude/code-graph) -> one local `leftover` event
- * {task_id, n, names}. They are only reported, unless config kill_leftovers is true AND no other dp agent ran in the
- * meantime (then the leftover trees are killed). deps = { procs, now, selfPid, events } for tests. Returns the event or null.
+ * {task_id, n, names}. kill_leftovers (procs.killMode: env → config → 'guarded'):
+ *   - 'guarded' (default, s7): kill only what procs.guardedSelect attributes to this agent (agent shell under this session's
+ *     claude.exe, never-kill list, cmd in its own worktree or no other dp agent meanwhile), each pid re-checked against a
+ *     fresh list (same creation time) right before; killed_pids + kill_skips {pid, name, reason} go in the event;
+ *   - true: 0.7.2 behaviour, the leftover tree roots (taskkill /T) when no other dp agent ran meanwhile; false: report only.
+ * deps = { procs, now, selfPid, events, kill } for tests. Returns the event or null.
  */
 function scanLeftoverProcs(ctx, a, deps) {
   const d = deps || {};
   if (ctx.config.scan_leftover_procs === false || (!d.procs && process.env.DIEU_PHOI_NO_PROCS === '1')) return null;
   const procs = d.procs || loadProcs();
   if (!procs) return null;
-  const startMs = transcriptStartMs(a.lines);
+  const startMs = transcriptStartMs(a.lines) || (a.liveStart ? Date.parse(a.liveStart) || null : null);
   const now = typeof d.now === 'number' ? d.now : Date.now();
   // an agent that started over 24 h ago (a long-resumed or odd transcript) has no meaningful "created since" window
   if (startMs === null || now - startMs > LEFTOVER_OVERLAP_MAX_AGE_MS) return null;
@@ -3464,22 +3519,88 @@ function scanLeftoverProcs(ctx, a, deps) {
   const counts = new Map();
   for (const p of left.all) { const n = String(p.name || '?').toLowerCase(); counts.set(n, (counts.get(n) || 0) + 1); }
   const names = Array.from(counts).sort((x, y) => y[1] - x[1] || (x[0] < y[0] ? -1 : 1)).slice(0, 8).map((x) => x[0]);
-  const killOn = ctx.config.kill_leftovers === true;
+  const mode = typeof procs.killMode === 'function' ? procs.killMode(ctx.config) : (ctx.config.kill_leftovers === true ? 'tree' : 'off');
   let killed = 0;
   let skipped = null;
-  if (killOn) {
+  const extra = {};
+  if (mode === 'tree') {
     const events = d.events || readEvents(ctx);
     if (otherAgentsRunning(events, a.agentId, startMs, now)) skipped = 'other-agent-running';
     else killed = procs.killTree(left.roots.map((p) => p.pid), { deadline: t0 + LEFTOVER_BUDGET_MS }).length;
+  } else if (mode === 'guarded') {
+    // s7: kill only what is attributable to THIS agent, after re-checking pid + creation time; pids + reasons go in the event
+    const events = d.events || readEvents(ctx);
+    const otherAgent = otherAgentsRunning(events, a.agentId, startMs, now);
+    const mainShell = !otherAgent && (typeof d.mainShell === 'boolean' ? d.mainShell : mainShellSince(a.sessionTranscript, startMs));
+    const exclusive = !otherAgent && !mainShell;
+    const sel = procs.guardedSelect(list, left.all, { rootPid: root.pid, worktree: ownWorktree(ctx, a, now), exclusive });
+    const res = sel.kill.length
+      ? procs.killVerified(sel.kill, { relist: () => procs.listProcesses({ timeoutMs: LEFTOVER_LIST_TIMEOUT_MS }), kill: d.kill, deadline: t0 + LEFTOVER_BUDGET_MS })
+      : { killed: [], skipped: [] };
+    killed = res.killed.length;
+    const skips = sel.skip.concat(res.skipped);
+    if (!exclusive && sel.skip.some((s) => s.reason === 'not-attributable')) skipped = otherAgent ? 'other-agent-running' : 'main-thread-shell';
+    extra.killed_pids = res.killed.slice(0, 20);
+    if (skips.length) extra.kill_skips = skips.slice(0, 20).map((s) => ({ pid: s.pid, name: String(s.name || '').toLowerCase(), reason: s.reason }));
   }
   const ev = Object.assign({
     schema: SCHEMA, kind: 'leftover', ts: nowIso(), agent_id: a.agentId, task_id: a.taskId,
-    n: left.all.length, names, kill_leftovers: killOn, killed,
-  }, skipped ? { kill_skipped: skipped } : {}, commonFields(ctx));
+    n: left.all.length, names, kill_leftovers: typeof procs.killModeValue === 'function' ? procs.killModeValue(mode) : mode === 'tree', killed,
+  }, extra, skipped ? { kill_skipped: skipped } : {}, commonFields(ctx));
   appendEvent(ctx, ev);
   return ev;
 }
 
+const MAIN_SHELL_TAIL_BYTES = 4 * 1024 * 1024;
+const MAIN_SHELL_TOOLS = new Set(['Bash', 'PowerShell', 'Monitor']);
+
+/**
+ * Did the session's main thread start a shell (Bash / PowerShell / Monitor tool_use) at or after startMs? Its processes sit
+ * under the same claude.exe as the agent's, so "no other dp agent ran" is not enough to call the tree the agent's. Reads the
+ * last 4 MB of the session transcript. true = yes OR unknown (unreadable, or the tail does not reach back to startMs).
+ */
+function mainShellSince(file, startMs) {
+  if (typeof file !== 'string' || !file || !startMs) return true;
+  let fd;
+  try { fd = fs.openSync(file, 'r'); } catch (_) { return true; }
+  try {
+    const size = fs.fstatSync(fd).size;
+    const from = Math.max(0, size - MAIN_SHELL_TAIL_BYTES);
+    const text = readSlice(fd, from, size - from).toString('utf8');
+    const lines = text.split('\n');
+    if (from > 0) lines.shift(); // partial first line
+    let oldest = Infinity;
+    for (const raw of lines) {
+      if (!raw.trim()) continue;
+      let l;
+      try { l = JSON.parse(raw); } catch (_) { continue; }
+      const t = typeof l.timestamp === 'string' ? Date.parse(l.timestamp) : NaN;
+      if (Number.isFinite(t)) oldest = Math.min(oldest, t);
+      if (!(t >= startMs) || l.isSidechain) continue;
+      const content = l.message && Array.isArray(l.message.content) ? l.message.content : [];
+      if (content.some((c) => c && c.type === 'tool_use' && MAIN_SHELL_TOOLS.has(c.name))) return true;
+    }
+    return from > 0 && !(oldest <= startMs); // tail too short to see the whole window: unknown
+  } catch (_) {
+    return true;
+  } finally {
+    try { fs.closeSync(fd); } catch (_) { /* closed */ }
+  }
+}
+
+/**
+ * The agent's own worktree for the guarded kill: its live-record cwd (brief `worktree:` or SubagentStart cwd), only when it is
+ * not the session's own cwd and no other live agent works in it (a shared directory says nothing about whose process it is).
+ */
+function ownWorktree(ctx, a, now) {
+  const norm = (s) => String(s || '').replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  const wt = norm(a.worktree);
+  if (!wt || (a.sessionCwd && norm(a.sessionCwd) === wt)) return null;
+  let others = [];
+  try { others = readLive(ctx, now).agents.filter((r) => r.agent_id !== a.agentId); } catch (_) { others = []; }
+  return others.some((r) => norm(r.cwd) === wt) ? null : a.worktree;
+}
+
 // Exact marker an agent puts on the FIRST line of its final report when it stops at a safe point because of a quota
 // / usage limit (brief template A, SKILL.md). Nothing looser: "STATUS: partial" + "quota" can be a real failure
 // ("Drive storage quota exceeded", a half-built rate limiter).
@@ -3869,6 +3990,17 @@ function handleWatch(p, ctx, o) {
   if (!agentId) return null;
   const { st, file, tpath } = watchState(p, ctx, agentId);
   if (!st || !st.dp || !tpath) return null;
+  const touched = touchLive(ctx, p, agentId, st); // core 0.7.3 (s1): live register heartbeat
+  // s6: an exec's own stuck helpers (checked at most once per heartbeat, i.e. ≤ 1/30 s)
+  const helperNote = touched && st.role === 'exec' && st.task_id ? stuckReminder(ctx, { parentTask: st.task_id }) : null;
+  const withHelperNote = (r) => {
+    if (!helperNote) return r;
+    if (!r) return { stuck: true, stdout: JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: helperNote } }) };
+    const out = JSON.parse(r.stdout);
+    out.hookSpecificOutput.additionalContext += `\n${helperNote}`;
+    r.stdout = JSON.stringify(out);
+    return r;
+  };
   // Gate slots: a helper's first hook proves its spawn started; so does the exec's own successful Agent call.
   if (st.role === 'helper' && st.parent_task_id && st.task_id) gateConfirm(ctx, st.parent_task_id, st.task_id);
   if ((p.tool_name === 'Agent' || p.tool_name === 'Task') && st.role === 'exec') {
@@ -3877,21 +4009,21 @@ function handleWatch(p, ctx, o) {
   }
   const thresholds = Array.isArray(o && o.thresholds) && o.thresholds.length ? o.thresholds : watchThresholds(ctx);
   const tokens = lastContextTokens(tpath);
-  if (tokens === null) return null;
+  if (tokens === null) return withHelperNote(null);
   let level = 0;
   while (level < thresholds.length && tokens >= thresholds[level]) level++;
-  if (level <= (Number(st.fired) || 0)) return null;
+  if (level <= (Number(st.fired) || 0)) return withHelperNote(null);
   st.fired = level;
   st.ctx_tokens = tokens;
   st.t = Date.now();
   writeFileAtomic(file, `${JSON.stringify(st)}\n`);
-  return {
+  return withHelperNote({
     level,
     ctx_tokens: tokens,
     stdout: JSON.stringify({
       hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: handoffMessage(st, tokens, level, thresholds) },
     }),
-  };
+  });
 }
 
 /** A reservation that neither the parent's PostToolUse(Agent) nor the helper's own first hook confirmed in this long never started. */
@@ -3942,6 +4074,514 @@ function gateReserve(dir, child) {
   return 0;
 }
 
+// ------------------------------------------------------------------ live agents + parallel cap (core 0.7.3 s1)
+
+/**
+ * Live-agent register `data/live/<agent_id>.json`: written at SubagentStart, refreshed by --watch (last_activity, at most
+ * once per LIVE_TOUCH_MS), removed at SubagentStop, ignored (and deleted) once idle past LIVE_TTL_MS. Counting is a
+ * readdir of small files, cheap enough for PreToolUse. The SubagentStart payload has no prompt (only session_id,
+ * agent_id, agent_type, cwd — checked 2026-11-06 with a probe session) and the subagent transcript does not exist yet,
+ * so the tag comes from an intent `live/pending/<session8>-<task>-<role>.json` that the allowing PreToolUse(Agent)
+ * (main session) or --gate (gen-2 helper) wrote: SubagentStart claims the oldest unclaimed intent of the same session
+ * and agent_type with an exclusive `.claim` create. No intent → a dp-* agent_type still gets a file (role from the
+ * type, task unknown, filled in by its first --watch); any other subagent (Claude Code internal, untagged) is skipped.
+ */
+const LIVE_TTL_MS = 6 * 3600 * 1000;
+const LIVE_TOUCH_MS = 30 * 1000;
+/** An unclaimed intent counts towards the cap this long (the spawn it announces has not started yet). */
+const LIVE_PENDING_MS = 60 * 1000;
+/** SubagentStart may still claim an intent this old (a permission prompt can sit between PreToolUse and the spawn). */
+const LIVE_CLAIM_MS = 10 * 60 * 1000;
+const PARALLEL_DEFAULTS = { max_parallel_session: 4, max_parallel_machine: 8, warn_parallel_machine: 6 };
+/** Roles the per-session cap counts (gen 1 dispatches of the orchestrator). The machine cap counts every live agent. */
+const LIVE_SESSION_ROLES = ['exec', 'plan', 'verify'];
+const AGENT_TYPE_ROLES = { 'dp-exec': 'exec', 'dp-verify': 'verify', 'dp-scout': 'plan', 'dp-helper': 'helper' };
+
+function liveName(id) {
+  return String(id).replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 80) || 'x';
+}
+function liveDir(ctx) { return path.join(ctx.paths.data, 'live'); }
+function liveFile(ctx, agentId) { return path.join(liveDir(ctx), `${liveName(agentId)}.json`); }
+function livePendingDir(ctx) { return path.join(liveDir(ctx), 'pending'); }
+function intentFile(ctx, sessionId, taskId, role) {
+  return path.join(livePendingDir(ctx), `${sha8(String(sessionId || ''))}-${liveName(taskId || 'none')}-${liveName(role || 'exec')}.json`);
+}
+
+/** Caps: env DIEU_PHOI_<KEY> → config.json → PARALLEL_DEFAULTS. Integers ≥ 0; 0 turns that cap (or warning) off. */
+function parallelLimits(ctx) {
+  const cfg = (ctx && ctx.config) || {};
+  const pick = (key) => {
+    for (const v of [process.env[`DIEU_PHOI_${key.toUpperCase()}`], cfg[key]]) {
+      if (v === undefined || v === null || v === '') continue;
+      const n = Number(v);
+      if (Number.isFinite(n) && n >= 0) return Math.floor(n);
+    }
+    return PARALLEL_DEFAULTS[key];
+  };
+  return { session: pick('max_parallel_session'), machine: pick('max_parallel_machine'), warn: pick('warn_parallel_machine') };
+}
+
+function liveMs(v) {
+  const n = typeof v === 'number' ? v : Date.parse(v);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** Live agents + still-pending intents. Files idle past LIVE_TTL_MS are deleted and not returned. Never throws. */
+function readLive(ctx, now) {
+  const t = typeof now === 'number' ? now : Date.now();
+  const agents = [];
+  const pending = [];
+  let names = [];
+  try { names = fs.readdirSync(liveDir(ctx)); } catch (_) { return { agents, pending }; }
+  for (const n of names) {
+    if (!n.endsWith('.json')) continue;
+    const f = path.join(liveDir(ctx), n);
+    const r = readJsonFile(f, null);
+    const last = r && typeof r === 'object' ? (liveMs(r.last_activity) || liveMs(r.start)) : null;
+    if (last === null || t - last > LIVE_TTL_MS) {
+      // unreadable: give a concurrent writer a moment before treating it as junk
+      let old = true;
+      if (last === null) { try { old = t - fs.statSync(f).mtimeMs > LIVE_TOUCH_MS; } catch (_) { old = false; } }
+      if (old) { try { fs.unlinkSync(f); } catch (_) { /* gone already */ } }
+      continue;
+    }
+    agents.push(r);
+  }
+  let pnames = [];
+  try { pnames = fs.readdirSync(livePendingDir(ctx)); } catch (_) { pnames = []; }
+  const claimed = new Set(pnames.filter((n) => n.endsWith('.claim')).map((n) => n.slice(0, -6)));
+  for (const n of pnames) {
+    if (!n.endsWith('.json')) continue;
+    const f = path.join(livePendingDir(ctx), n);
+    const r = readJsonFile(f, null);
+    const at = r && typeof r === 'object' ? liveMs(r.t) : null;
+    if (at === null || t - at > LIVE_TTL_MS) {
+      try { fs.unlinkSync(f); } catch (_) { /* ignore */ }
+      try { fs.unlinkSync(`${f.slice(0, -5)}.claim`); } catch (_) { /* ignore */ }
+      continue;
+    }
+    if (claimed.has(n.slice(0, -5)) || t - at > LIVE_PENDING_MS) continue;
+    pending.push(Object.assign({ pending: true }, r));
+  }
+  return { agents, pending };
+}
+
+/** session = exec/plan/verify (gen 1) of `sessionId`, live or pending; machine = every live agent + pending intent. */
+function liveCounts(live, sessionId) {
+  const all = live.agents.concat(live.pending);
+  const mine = all.filter((r) => sessionId && r.session_id === sessionId && LIVE_SESSION_ROLES.includes(r.role) && !(Number(r.gen) > 1));
+  return { session: mine.length, machine: all.length, mine, all };
+}
+
+function liveAgeMin(r, now) {
+  const s = liveMs(r.start) || liveMs(r.t);
+  return s === null ? null : Math.max(0, Math.round((now - s) / 60000));
+}
+
+function liveLabel(r, now, withSession) {
+  const age = liveAgeMin(r, now);
+  const bits = [r.role || '?'];
+  if (age !== null) bits.push(`${age} phút`);
+  if (r.pending) bits.push('vừa giao');
+  if (withSession && r.session_id) bits.push(`phiên ${sha8(r.session_id)}`);
+  return `${r.task_id || (r.agent_id ? `agent ${r.agent_id}` : '?')} (${bits.join(', ')})`;
+}
+
+/** s6: run dir the brief points at (dp-out-/handoff- path or …/runs/<id>), else null — never the made-up fallback. */
+function briefRunDir(prompt, taskId) {
+  if (typeof prompt !== 'string' || !prompt) return null;
+  const d = resultRunDir(prompt, taskId || 'none');
+  const fallback = path.join(runsDir(), safeName(taskId || 'none'));
+  return d === fallback && !/\/runs\/[A-Za-z0-9_-]/.test(prompt.replace(/\\/g, '/')) ? null : d;
+}
+
+/** s6: where Claude Code will write a subagent's transcript, from the parent's transcript_path at SubagentStart. */
+function liveTranscriptGuess(parentTp, agentId) {
+  if (typeof parentTp !== 'string' || !parentTp || !agentId) return null;
+  const name = `agent-${agentId}.jsonl`;
+  if (path.basename(path.dirname(parentTp)) === 'subagents') return path.join(path.dirname(parentTp), name); // nested spawn
+  return path.join(path.dirname(parentTp), path.basename(parentTp, '.jsonl'), 'subagents', name);
+}
+
+/** Absolute path on the brief's `worktree:` line (best effort), else null. */
+function briefWorktree(prompt) {
+  if (typeof prompt !== 'string') return null;
+  const m = /^\s*worktree:(.*)$/m.exec(prompt);
+  if (!m) return null;
+  const pm = /([A-Za-z]:[\\/][^\s,;`'"()]+|\/[^\s,;`'"()]+)/.exec(m[1]);
+  return pm ? pm[1].replace(/[.)]+$/, '') : null;
+}
+
+function writeIntent(ctx, p, tag, extra) {
+  try {
+    const f = intentFile(ctx, p.session_id, tag.task_id, tag.role);
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    try { fs.unlinkSync(`${f.slice(0, -5)}.claim`); } catch (_) { /* no earlier claim */ }
+    const ti = p.tool_input && typeof p.tool_input === 'object' ? p.tool_input : {};
+    writeFileAtomic(f, `${JSON.stringify(Object.assign({
+      session_id: typeof p.session_id === 'string' ? p.session_id : null,
+      task_id: tag.task_id || null,
+      role: tag.role || 'exec',
+      gen: 1,
+      agent_type: typeof ti.subagent_type === 'string' && ti.subagent_type ? ti.subagent_type : 'general-purpose',
+      parent_task_id: tag.parent_task_id || null,
+      worktree: briefWorktree(ti.prompt),
+      run_dir: briefRunDir(ti.prompt, tag.task_id), // s6: where its dp-out/STATUS lands (stuck after-status)
+      t: Date.now(),
+    }, extra || {}))}\n`);
+    return f;
+  } catch (e) {
+    logError(ctx.home, e, 'live-intent');
+    return null;
+  }
+}
+
+/** Oldest unclaimed intent of this session + agent_type; claimed by exclusive create so two parallel starts never share one. */
+function claimIntent(ctx, sessionId, agentType, agentId, now) {
+  const dir = livePendingDir(ctx);
+  let names = [];
+  try { names = fs.readdirSync(dir); } catch (_) { return null; }
+  const set = new Set(names);
+  const cands = [];
+  for (const n of names) {
+    if (!n.endsWith('.json') || set.has(`${n.slice(0, -5)}.claim`)) continue;
+    const r = readJsonFile(path.join(dir, n), null);
+    if (!r || r.session_id !== sessionId || r.agent_type !== agentType) continue;
+    const at = liveMs(r.t);
+    if (at === null || now - at > LIVE_CLAIM_MS) continue;
+    cands.push({ n, r, at });
+  }
+  cands.sort((a, b) => a.at - b.at);
+  for (const c of cands) {
+    try {
+      fs.writeFileSync(path.join(dir, `${c.n.slice(0, -5)}.claim`), `${agentId}\n`, { flag: 'wx' });
+      return c.r;
+    } catch (_) { /* another start claimed it */ }
+  }
+  return null;
+}
+
+/** SubagentStart: register the agent (see the block comment above). Prints nothing. Returns the record or null. */
+function handleSubagentStart(p, ctx) {
+  const agentId = typeof p.agent_id === 'string' && p.agent_id ? p.agent_id : null;
+  if (!agentId) return null;
+  const type = typeof p.agent_type === 'string' && p.agent_type ? p.agent_type : 'general-purpose';
+  const sid = typeof p.session_id === 'string' && p.session_id ? p.session_id : null;
+  const now = Date.now();
+  const intent = claimIntent(ctx, sid, type, agentId, now);
+  if (!intent && !AGENT_TYPE_ROLES[type]) return null; // internal / untagged subagent: not ours
+  const role = intent ? intent.role : AGENT_TYPE_ROLES[type];
+  const ts = new Date(now).toISOString();
+  const rec = {
+    agent_id: agentId,
+    session_id: sid,
+    task_id: intent ? intent.task_id : null,
+    role,
+    gen: intent ? (Number(intent.gen) || 1) : (role === 'helper' ? 2 : 1),
+    agent_type: type,
+    parent_task_id: intent ? intent.parent_task_id || null : null,
+    start: ts,
+    last_activity: ts,
+    cwd: (intent && intent.worktree) || (typeof p.cwd === 'string' ? p.cwd : null),
+    live_session: intent && typeof intent.live_session === 'number' ? intent.live_session : null,
+    live_machine: intent && typeof intent.live_machine === 'number' ? intent.live_machine : null,
+    // s6: liveness evidence for `reap` / the stuck reminder (the transcript does not exist yet at SubagentStart)
+    transcript: liveTranscriptGuess(p.transcript_path, agentId),
+    session_transcript: typeof p.transcript_path === 'string' && p.transcript_path ? p.transcript_path : null,
+    run_dir: intent && typeof intent.run_dir === 'string' ? intent.run_dir : null,
+  };
+  fs.mkdirSync(liveDir(ctx), { recursive: true });
+  writeFileAtomic(liveFile(ctx, agentId), `${JSON.stringify(rec)}\n`);
+  // core 0.7.3 (s5): one counts-only sample per registered agent (no disk IO, no paths) for `dieu-phoi load report`
+  appendLoadSample(ctx, Object.assign({ ts, src: 'start' }, liveLoadCounts(ctx, now)));
+  return rec;
+}
+
+/** core 0.7.3 (s5): data/load.jsonl, one JSON object per line (written by SubagentStart and `dieu-phoi load sample`). */
+function loadFile(ctx) { return path.join(ctx.paths.data, 'load.jsonl'); }
+
+/**
+ * Counts for a load sample, read the same way as the cap: per-session exec/plan/verify (gen 1, keyed by sha8 of the
+ * session), every live agent + pending intent, and queue = intents still waiting for their SubagentStart. No IO.
+ */
+function liveLoadCounts(ctx, now) {
+  try {
+    const live = readLive(ctx, now);
+    const bySession = {};
+    for (const r of live.agents.concat(live.pending)) {
+      if (!r.session_id || !LIVE_SESSION_ROLES.includes(r.role) || Number(r.gen) > 1) continue;
+      const k = sha8(r.session_id);
+      bySession[k] = (bySession[k] || 0) + 1;
+    }
+    return { live_session_counts: bySession, live_machine: live.agents.length + live.pending.length, queue: live.pending.length };
+  } catch (_) {
+    return { live_session_counts: {}, live_machine: null, queue: null };
+  }
+}
+
+/** Appends one sample line to data/load.jsonl. Never throws. */
+function appendLoadSample(ctx, rec) {
+  try {
+    fs.mkdirSync(ctx.paths.data, { recursive: true });
+    fs.appendFileSync(loadFile(ctx), `${JSON.stringify(rec)}\n`);
+    return true;
+  } catch (e) {
+    logError(ctx.home, e, 'load-sample');
+    return false;
+  }
+}
+
+/** SubagentStop: the agent is no longer live. */
+function removeLive(ctx, agentId) {
+  if (!agentId) return false;
+  try { fs.unlinkSync(liveFile(ctx, agentId)); return true; } catch (_) { return false; }
+}
+
+/** --watch: refresh last_activity (≤ once per LIVE_TOUCH_MS), fill a missing task from the watch state; create if absent. */
+function touchLive(ctx, p, agentId, st) {
+  try {
+    const f = liveFile(ctx, agentId);
+    const now = Date.now();
+    const rec = readJsonFile(f, null);
+    if (rec && typeof rec === 'object') {
+      const fill = !rec.task_id && st.task_id;
+      if (!fill && now - (liveMs(rec.last_activity) || 0) < LIVE_TOUCH_MS) return false;
+      rec.last_activity = new Date(now).toISOString();
+      if (!rec.transcript || !fs.existsSync(rec.transcript)) rec.transcript = subagentTranscriptPath(p, agentId) || rec.transcript || null;
+      if (fill) { rec.task_id = st.task_id; if (st.role) rec.role = st.role; if (st.parent_task_id) rec.parent_task_id = st.parent_task_id; }
+      writeFileAtomic(f, `${JSON.stringify(rec)}\n`);
+      return true;
+    }
+    // no SubagentStart record (hook registered after the agent started, or an older setup): register it now
+    const ts = new Date(now).toISOString();
+    fs.mkdirSync(liveDir(ctx), { recursive: true });
+    writeFileAtomic(f, `${JSON.stringify({
+      agent_id: agentId, session_id: typeof p.session_id === 'string' ? p.session_id : null,
+      task_id: st.task_id || null, role: st.role || 'exec', gen: st.role === 'helper' || st.parent_task_id ? 2 : 1,
+      agent_type: null, parent_task_id: st.parent_task_id || null, start: ts, last_activity: ts,
+      cwd: typeof p.cwd === 'string' ? p.cwd : null, live_session: null, live_machine: null, from_watch: true,
+      transcript: subagentTranscriptPath(p, agentId), session_transcript: null, run_dir: null,
+    })}\n`);
+    return true;
+  } catch (e) {
+    logError(ctx.home, e, 'live-touch');
+    return false;
+  }
+}
+
+/** Counts for the dispatch event: those recorded when the dispatch was allowed (intent), else the current ones. */
+function dispatchLiveCounts(ctx, p, tag) {
+  try {
+    if (tag && tag.task_id) {
+      const r = readJsonFile(intentFile(ctx, p.session_id, tag.task_id, tag.role), null);
+      if (r && typeof r.live_session === 'number' && typeof r.live_machine === 'number') {
+        return { live_session: r.live_session, live_machine: r.live_machine };
+      }
+    }
+    const c = liveCounts(readLive(ctx), p.session_id);
+    return { live_session: c.session, live_machine: c.machine };
+  } catch (_) {
+    return { live_session: null, live_machine: null };
+  }
+}
+
+function parallelDenyText(scope, c, lim, tag, now) {
+  const list = scope === 'session' ? c.mine : c.all;
+  const shown = list.slice().sort((a, b) => (liveMs(a.start) || liveMs(a.t) || 0) - (liveMs(b.start) || liveMs(b.t) || 0));
+  const names = shown.slice(0, 8).map((r) => liveLabel(r, now, scope === 'machine')).join('; ');
+  const head = scope === 'session'
+    ? `dieu-phoi: phiên này đã có ${c.session}/${lim.session} agent exec/plan/verify đang chạy (trần max_parallel_session)`
+    : `dieu-phoi: toàn máy đã có ${c.machine}/${lim.machine} agent dieu-phoi đang chạy, gồm helper (trần max_parallel_machine)`;
+  const first = shown[0] ? (shown[0].task_id || shown[0].agent_id) : null;
+  return `${head} — chưa giao ${tag.role} của task ${tag.task_id}. Đang chạy: ${names}${list.length > 8 ? ` (+${list.length - 8})` : ''}. `
+    + `Chờ ${first ? `agent ${first}` : 'một agent'} (hoặc agent khác trong danh sách) xong — có thông báo hoàn tất — rồi giao lại đúng lời gọi này; `
+    + 'trong lúc chờ đừng giao thêm. Agent kẹt thì TaskStop nó trước; agent mồ côi (crash, không có SubagentStop) vẫn giữ chỗ — `dieu-phoi reap` xem, `reap --yes` dọn. '
+    + 'Chỉ khi người dùng đồng ý vượt trần: thêm `|parallel_ok` vào thẻ (tắt hẳn: max_parallel_session / max_parallel_machine = 0 trong config.json).';
+}
+
+/**
+ * Core 0.7.3 (s1): PreToolUse(Agent) of the orchestrating session. A dp dispatch with role exec/plan/verify is denied
+ * (`parallel-cap`) while the session already runs max_parallel_session of them, or the machine (this DIEU_PHOI_HOME)
+ * max_parallel_machine dp agents; `|parallel_ok` passes. An allowed dispatch leaves an intent for SubagentStart, and
+ * at warn_parallel_machine it answers with an additionalContext warning instead of nothing.
+ */
+function parallelCapGate(p, ctx, tag) {
+  const now = Date.now();
+  const lim = parallelLimits(ctx);
+  const c = liveCounts(readLive(ctx, now), p.session_id);
+  if (!tag.parallel_ok) {
+    const scope = lim.session > 0 && c.session >= lim.session ? 'session'
+      : (lim.machine > 0 && c.machine >= lim.machine ? 'machine' : null);
+    if (scope) {
+      const ev = logGate(ctx, p, `task:${tag.task_id}`, { task_id: tag.task_id, role: tag.role },
+        { gate_action: 'deny', reason_code: 'parallel-cap', cap_scope: scope, live_session: c.session, live_machine: c.machine });
+      return { denied: true, event: ev, stdout: preToolDeny(parallelDenyText(scope, c, lim, tag, now)) };
+    }
+  }
+  writeIntent(ctx, p, tag, { live_session: c.session, live_machine: c.machine });
+  if (lim.warn > 0 && c.machine + 1 >= lim.warn) {
+    return {
+      denied: false,
+      stdout: JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          additionalContext: `dieu-phoi: toàn máy sẽ có ${c.machine + 1} agent dieu-phoi chạy cùng lúc (cảnh báo từ ${lim.warn}, trần ${lim.machine || 'tắt'}); `
+            + `phiên này ${c.session + 1}/${lim.session || 'tắt'}. Máy chậm dần khi đông agent: ưu tiên chờ bớt trước khi giao tiếp.`,
+        },
+      }),
+    };
+  }
+  return null;
+}
+
+/** Counts + per-agent rows for doctor / state. */
+function liveSummary(ctx, sessionId, now) {
+  const t = typeof now === 'number' ? now : Date.now();
+  const c = liveCounts(readLive(ctx, t), sessionId);
+  return {
+    session: sessionId ? c.session : null,
+    machine: c.machine,
+    limits: parallelLimits(ctx),
+    agents: c.all.map((r) => ({
+      agent_id: r.agent_id || null, task_id: r.task_id || null, role: r.role || null, gen: Number(r.gen) || 1,
+      session: r.session_id ? sha8(r.session_id) : null, age_min: liveAgeMin(r, t), pending: !!r.pending,
+      idle_min: r.pending ? null : Math.max(0, Math.round((t - (liveMs(r.last_activity) || t)) / 60000)),
+    })),
+    labels: c.all.map((r) => liveLabel(r, t, true)),
+  };
+}
+
+/*
+ * Core 0.7.3 (s6): stuck / orphaned live agents. done/fail = SubagentStop (removeLive), so whatever is still in data/live
+ * is running, stuck, or orphaned (crashed without SubagentStop). Evidence per record: last_activity (--watch heartbeat),
+ * the subagent transcript mtime, the parent session transcript mtime, and a dp-out-/handoff- file of its task in the run
+ * dir. stuck = idle ≥ stuck_idle_min, OR running ≥ stuck_hard_min, OR its dp-out (STATUS) is on disk and it is still live
+ * stuck_after_status_min later (waiting on a background task). orphan = idle AND the parent session is silent too (or
+ * unknown) — the agent is almost certainly gone and its live file only holds a parallel-cap slot until LIVE_TTL_MS.
+ * The main session is reminded (UserPromptSubmit / PostToolUse(Agent)) to TaskStop + `dieu-phoi reap --yes`; an exec is
+ * reminded about its own helpers through --watch. Nothing here kills or deletes: `reap --yes` does (lib/commands.cjs).
+ */
+const STUCK_DEFAULTS = { stuck_idle_min: 20, stuck_hard_min: 120, stuck_after_status_min: 5 };
+/** One reminder per agent per this long (stored as stuck_notified in its live file). */
+const STUCK_REMIND_MS = 10 * 60 * 1000;
+
+/** Thresholds in minutes: env DIEU_PHOI_<KEY> → config.json → STUCK_DEFAULTS. Numbers ≥ 0; 0 turns that rule off. */
+function stuckLimits(ctx) {
+  const cfg = (ctx && ctx.config) || {};
+  const pick = (key) => {
+    for (const v of [process.env[`DIEU_PHOI_${key.toUpperCase()}`], cfg[key]]) {
+      if (v === undefined || v === null || v === '') continue;
+      const n = Number(v);
+      if (Number.isFinite(n) && n >= 0) return n;
+    }
+    return STUCK_DEFAULTS[key];
+  };
+  return { idle: pick('stuck_idle_min'), hard: pick('stuck_hard_min'), after_status: pick('stuck_after_status_min') };
+}
+
+function mtimeMs(f) {
+  if (typeof f !== 'string' || !f) return null;
+  try { return fs.statSync(f).mtimeMs; } catch (_) { return null; }
+}
+
+/** Newest dp-out-<task>-* / handoff-<task>* .md in the run dir written after the agent started, else null. */
+function statusFileOf(rec, startMs) {
+  if (!rec.run_dir || !rec.task_id) return null;
+  const t = safeName(rec.task_id);
+  let names = [];
+  try { names = fs.readdirSync(rec.run_dir); } catch (_) { return null; }
+  let best = null;
+  for (const n of names) {
+    if (!n.endsWith('.md') || !(n.startsWith(`dp-out-${t}-`) || n.startsWith(`handoff-${t}`))) continue;
+    if (rec.role && n.startsWith(`dp-out-${t}-`) && !n.startsWith(`dp-out-${t}-${rec.role}`)) continue; // exec vs verify of one task
+    const m = mtimeMs(path.join(rec.run_dir, n));
+    if (m !== null && m >= (startMs || 0) - 1000 && (!best || m > best.mtime)) best = { file: path.join(rec.run_dir, n), mtime: m };
+  }
+  return best;
+}
+
+/** Verdict on one live record: { state: ok|stuck|orphan, reasons[], idle_min, age_min, … }. Never throws. */
+function assessLive(rec, now, lim) {
+  const startMs = liveMs(rec.start) || liveMs(rec.t) || now;
+  const tMtime = mtimeMs(rec.transcript);
+  const last = Math.max(liveMs(rec.last_activity) || 0, startMs, tMtime || 0);
+  const idleMin = Math.max(0, (now - last) / 60000);
+  const ageMin = Math.max(0, (now - startMs) / 60000);
+  const reasons = [];
+  if (lim.idle > 0 && idleMin >= lim.idle) reasons.push('idle');
+  if (lim.hard > 0 && ageMin >= lim.hard) reasons.push('hard');
+  const status = lim.after_status > 0 ? statusFileOf(rec, startMs) : null;
+  if (status && (now - status.mtime) / 60000 >= lim.after_status) reasons.push('after-status');
+  let state = reasons.length ? 'stuck' : 'ok';
+  if (reasons.includes('idle')) {
+    const sMtime = mtimeMs(rec.session_transcript);
+    if (sMtime === null || (now - sMtime) / 60000 >= lim.idle) state = 'orphan';
+  }
+  return {
+    agent_id: rec.agent_id || null, task_id: rec.task_id || null, role: rec.role || null, gen: Number(rec.gen) || 1,
+    parent_task_id: rec.parent_task_id || null, session_id: rec.session_id || null, cwd: rec.cwd || null,
+    start_ms: startMs, idle_min: Math.round(idleMin), age_min: Math.round(ageMin), reasons, state,
+    transcript_seen: tMtime !== null, status_file: status ? status.file : null,
+    status_min: status ? Math.round((now - status.mtime) / 60000) : null, notified: liveMs(rec.stuck_notified),
+  };
+}
+
+/** Stuck + orphaned live agents (oldest first). `sessionId` filters to one session, `parentTask` to one exec's helpers. */
+function stuckAgents(ctx, o) {
+  const opt = o || {};
+  const now = typeof opt.now === 'number' ? opt.now : Date.now();
+  const lim = opt.limits || stuckLimits(ctx);
+  const out = [];
+  for (const rec of readLive(ctx, now).agents) {
+    if (opt.sessionId && rec.session_id !== opt.sessionId) continue;
+    if (opt.parentTask && rec.parent_task_id !== opt.parentTask) continue;
+    const a = assessLive(rec, now, lim);
+    if (a.state !== 'ok') out.push(a);
+  }
+  return out.sort((a, b) => a.start_ms - b.start_ms);
+}
+
+const STUCK_REASON_TEXT = { idle: 'im lặng', hard: 'chạy quá lâu', 'after-status': 'đã có dp-out/STATUS mà chưa dừng' };
+
+function stuckReasonText(a) {
+  const bits = a.reasons.map((r) => (r === 'after-status' && a.status_min !== null ? `${STUCK_REASON_TEXT[r]} ${a.status_min} phút` : STUCK_REASON_TEXT[r] || r));
+  if (a.state === 'orphan') bits.push('có vẻ mồ côi — phiên cũng im');
+  return bits.join(', ');
+}
+
+/** One reminder line per agent: what is stuck and the exact next step. */
+function stuckLine(a, forExec) {
+  const who = `agent ${a.agent_id} task ${a.task_id || '?'} (${a.role || '?'}${a.gen > 1 ? `, gen ${a.gen}` : ''})`;
+  const n = a.reasons.includes('idle') ? a.idle_min : a.age_min;
+  const wt = a.cwd ? ` Worktree ${toPosix(a.cwd)} giữ nguyên (còn công việc).` : '';
+  const stop = !forExec && a.gen > 1 && a.parent_task_id
+    ? `helper của ${a.parent_task_id}: TaskStop ${a.agent_id} (hoặc nhắc exec cha dừng nó)`
+    : `TaskStop ${a.agent_id}`;
+  return `dieu-phoi: ${who} kẹt ${n} phút [${stuckReasonText(a)}] → ${stop}; xong rồi \`dieu-phoi reap --yes\` (xem trước: \`dieu-phoi reap\`).${wt}`;
+}
+
+/**
+ * Reminder text for stuck agents not reminded in the last STUCK_REMIND_MS, or null. Marks them (stuck_notified) so a
+ * busy session is not told the same thing on every prompt. Never throws.
+ */
+function stuckReminder(ctx, o) {
+  try {
+    const opt = o || {};
+    const now = typeof opt.now === 'number' ? opt.now : Date.now();
+    const due = stuckAgents(ctx, Object.assign({}, opt, { now })).filter((a) => !(a.notified && now - a.notified < STUCK_REMIND_MS));
+    if (!due.length) return null;
+    for (const a of due) {
+      const f = liveFile(ctx, a.agent_id);
+      const rec = readJsonFile(f, null);
+      if (rec && typeof rec === 'object') { rec.stuck_notified = new Date(now).toISOString(); try { writeFileAtomic(f, `${JSON.stringify(rec)}\n`); } catch (_) { /* best effort */ } }
+    }
+    return due.slice(0, 6).map((a) => stuckLine(a, !!opt.parentTask)).join('\n') + (due.length > 6 ? `\n(+${due.length - 6} agent kẹt khác: \`dieu-phoi reap\`)` : '');
+  } catch (e) {
+    logError(ctx.home, e, 'stuck-remind');
+    return null;
+  }
+}
+
 /**
  * Core 0.7.1 (C1): global PreToolUse(Agent) in the orchestrating session. An exec dispatch of a task that already
  * handed off HANDOFF_CHAIN_DENY times is denied (the 4th, 5th… segment of one chain cost $15-36 per task in session
@@ -3953,11 +4593,12 @@ function handleChainGate(p, ctx) {
   const ti = p.tool_input && typeof p.tool_input === 'object' ? p.tool_input : {};
   const tag = resolveTag(ti.prompt, knownTaskTypes(ctx));
   if (!tag || !tag.task_id || !isValidTaskId(tag.task_id)) return null;
-  if (tag.role === 'verify') return verifyOrphanGate(p, ctx, tag);
-  if (tag.role !== 'exec') return null;
-  const chain = tag.chain_ok ? null : chainGateDenial(p, ctx, tag);
-  if (chain) return chain;
-  return sessionCapGate(p, ctx, tag);
+  let r = null;
+  if (tag.role === 'verify') r = verifyOrphanGate(p, ctx, tag);
+  else if (tag.role === 'exec') r = (tag.chain_ok ? null : chainGateDenial(p, ctx, tag)) || sessionCapGate(p, ctx, tag);
+  if (r) return r;
+  // core 0.7.3 (s1): parallel cap last, so a dispatch another gate denies never leaves an intent behind
+  return LIVE_SESSION_ROLES.includes(tag.role) ? parallelCapGate(p, ctx, tag) : null;
 }
 
 function preToolDeny(reason) {
@@ -3996,7 +4637,7 @@ function verifyOrphanGate(p, ctx, tag) {
     denied: true,
     event: ev,
     stdout: preToolDeny(`dieu-phoi: verifier của task ${tag.task_id} không có lượt exec nào trong phiên này và không nằm trong kế hoạch đã duyệt — `
-      + 'không chạy verifier cho việc chưa giao. Giao exec của task trước; verifier gộp của mode fast dùng thẻ `|batch`.'),
+      + 'không chạy verifier cho việc chưa giao. Giao exec của task trước; verifier gộp (fast, normal s≤4) dùng thẻ `|batch`.'),
   };
 }
 
@@ -4096,6 +4737,12 @@ function handleGate(p, ctx) {
     }),
   });
   if (why.length) return deny(why, codes.join('+'));
+  // core 0.7.3 (s1): helpers count towards the machine cap
+  const lim = parallelLimits(ctx);
+  const lc = liveCounts(readLive(ctx), p.session_id);
+  if (!tag.parallel_ok && lim.machine > 0 && lc.machine >= lim.machine) {
+    return deny([`toàn máy đã có ${lc.machine}/${lim.machine} agent dieu-phoi đang chạy (trần max_parallel_machine) — tự làm phần này, đừng giao helper`], 'parallel-cap');
+  }
   const root = path.join(ctx.paths.data, 'gate');
   fs.mkdirSync(root, { recursive: true });
   pruneGate(root);
@@ -4103,6 +4750,13 @@ function handleGate(p, ctx) {
   const slot = gateReserve(dir, tag.task_id);
   if (!slot) return deny([`đã giao đủ ${GATE_MAX_CHILDREN} helper cho bước này — tự làm phần còn lại`], 'max-children');
   const children = gateSlots(dir).length;
+  const parentLive = readJsonFile(liveFile(ctx, agentId), null);
+  writeIntent(ctx, p, tag, {
+    gen: (parentLive && Number(parentLive.gen) ? Number(parentLive.gen) : 1) + 1,
+    parent_task_id: tag.parent_task_id || st.task_id || null,
+    worktree: (parentLive && parentLive.cwd) || null,
+    live_session: lc.session, live_machine: lc.machine,
+  });
   return { denied: false, slot, children, event: log('allow', { slot, children }) };
 }
 
@@ -4121,6 +4775,43 @@ function logGate(ctx, p, agentId, st, fields) {
   return ev;
 }
 
+/**
+ * `--gate-bash` (PreToolUse(Bash|PowerShell) inside dp-* subagents): `knowledge review|merge` writes knowledge
+ * outside the accept gate (a subagent could clear a STALE mark on its own). Deny it; the coordinator runs it.
+ * Matching (0.7.4 S4a): split on `| ; & newline`. In a segment, a token naming the CLI (`dieu-phoi`, `dieu-phoi.cjs|.cmd|.js`,
+ * optional `@version`, optional path: `node D:/x/dieu-phoi.cjs`, `npx @kienntpixon/dieu-phoi@0.7.4`) comes before a `knowledge`
+ * token; between `knowledge` and the subcommand only flags are allowed (`--repo x`, `--repo=x`, before or after `knowledge`,
+ * a flag's one value skipped), then `review|merge`. Known limit: a shell variable or alias hiding the CLI name
+ * (`$DP knowledge review`) is not seen; this gate is a guard for subagents, not a sandbox.
+ */
+const KNOWLEDGE_WRITE_SUBS = new Set(['review', 'merge']);
+const DP_CLI_TOKEN_RE = /(?:^|[\/\\])dieu-phoi(?:\.cjs|\.cmd|\.js)?(?:@\S*)?$/;
+function isKnowledgeWriteCall(cmd) {
+  for (const seg of cmd.split(/[|;&\n]/)) {
+    const toks = (seg.match(/"[^"]*"|'[^']*'|\S+/g) || []).map((t) => t.replace(/^["']|["']$/g, ''));
+    for (let i = 0; i < toks.length; i++) {
+      if (!DP_CLI_TOKEN_RE.test(toks[i])) continue;
+      for (let j = i + 1; j < toks.length; j++) {
+        if (toks[j] !== 'knowledge') continue;
+        let flagValue = false; // previous token was a flag without `=`, so this word may be its value
+        for (let k = j + 1; k < toks.length; k++) {
+          const t = toks[k];
+          if (KNOWLEDGE_WRITE_SUBS.has(t)) return true;
+          if (t.startsWith('-')) { flagValue = !t.includes('='); continue; }
+          if (!flagValue) break;
+          flagValue = false;
+        }
+      }
+    }
+  }
+  return false;
+}
+function handleGateBash(p) {
+  const cmd = p.tool_input && typeof p.tool_input.command === 'string' ? p.tool_input.command : '';
+  if (!isKnowledgeWriteCall(cmd)) return null;
+  return { stdout: preToolDeny('dp-*: subagent không được chạy `knowledge review|merge` (đường ghi knowledge ngoài cổng accept). Báo điều phối viên thay vì tự chạy.') };
+}
+
 /** `--gate-release` (PostToolUseFailure(Agent) inside dp-exec): the spawn failed, give its unconfirmed slot back. */
 function handleGateRelease(p, ctx) {
   if (p.tool_name !== 'Agent' && p.tool_name !== 'Task') return null;
@@ -4193,11 +4884,17 @@ function runHook(opts) {
     if (o.mode === 'watch') return handleWatch(p, ctx, o); // { stdout } or null
     if (o.mode === 'gate') return handleGate(p, ctx, o); // { stdout } or null
     if (o.mode === 'gate-release') return handleGateRelease(p, ctx); // { released } or null, prints nothing
-    if (name === 'PreToolUse') return handleChainGate(p, ctx); // { stdout } (deny) or null
+    if (o.mode === 'gate-bash') return handleGateBash(p); // { stdout } (deny) or null
+    if (name === 'PreToolUse') return handleChainGate(p, ctx); // { stdout } (deny / warn) or null
+    if (name === 'SubagentStart') return handleSubagentStart(p, ctx); // live record or null, prints nothing
     if (name === 'SessionStart') return handleSessionStart(p, ctx); // { stdout } or null, never an event
     if (name === 'UserPromptSubmit') return handleUserPromptSubmit(p, ctx); // { stdout } or null
     if (name === 'SubagentStop') {
-      const r = handleSubagentStop(p, ctx);
+      // s7: keep the live record (worktree, start) for the guarded leftover kill before the file goes
+      let live = null;
+      try { live = typeof p.agent_id === 'string' && p.agent_id ? readJsonFile(liveFile(ctx, p.agent_id), null) : null; } catch (_) { live = null; }
+      try { removeLive(ctx, p.agent_id); } catch (e) { logError(home, e, 'live-remove'); }
+      const r = handleSubagentStop(p, ctx, { live });
       if (r && typeof r.stdout === 'string') return r; // s15: block decision, printed as the hook's JSON answer
       ev = r;
     } else if (name === 'PostToolUse' || (!name && p.tool_name)) ev = handlePostToolUse(p, ctx);
@@ -4351,8 +5048,8 @@ async function runSync(ctx, opts) {
 
 module.exports = {
   runsDir, loadPlans, isDieuPhoiPrompt, foldPrompt, sinkStatusCached, sinkUrlKey, SINK_CACHE_TTL_MS, scoutBriefPath, quickHealth, startRun, startInfo, startKnowledgeOf, knowledgeLines, orchLessons, orchLessonLines, abortReasonOf, completionStatus, logGate, QUOTA_PAUSE_MARKER, stepIds, START_STEP_IDS, healthLine, formatStartBlock, handleUserPromptSubmit, START_PREFIX, buildSessionState, findOrphanAgents, orphanLines, ORPHAN_MIN_MS, ORPHAN_NO_COMPLETE_MS, formatSessionState, stateCounts, compactSystemMessage, handleSessionStart, dispatchInSession, STATE_TEXT_CAP, COMPACT_PREFIX,
-  modeLine, MODES, DEFAULT_MODE, LOCAL_ONLY_KINDS, MODE_ASK_LINE, isMode, rootModeFromEvents, rootModeFromText, dispatchModeFromEvents, taskModeInfo, planOfTask, modeFields,
-  modeSuggestion, modeSuggestLine, fastFailRate, rootTaskIds, FAST_FAIL_WINDOW, FAST_FAIL_MIN_N, FAST_FAIL_RATE,
+  modeLine, MODES, DEFAULT_MODE, LOCAL_ONLY_KINDS, isMode, normMode, LEGACY_MODE, rootModeFromEvents, rootModeFromText, dispatchModeFromEvents, taskModeInfo, planOfTask, modeFields,
+  rootTaskIds,
   testCommandInfo, testTimeOf, testSFromText,
   CORE_VERSION, SCHEMA, TASK_TYPES, URGENCIES, ROLES, MODEL_ALIASES, UNTAGGED, TYPE_ALIASES,
   sha8, nowIso, readJsonFile, writeFileAtomic, renameWithRetry, acquireLock, acquireFileLock, withFileLock, defaultClaudeDir, resolveHome, pathsFor, loadConfig, makeCtx,
@@ -4363,9 +5060,11 @@ module.exports = {
   RESULT_ROLES, BLOCKED_RESULT_NAME_RE, resultFileName, findResultFiles, resultRunDir, finalAssistantText, persistInlineResult, orchestratorUsage, countCompactions, orchCacheFile, findSessionTranscript, SESSION_ID_RE, HOOK_COLD_MAX_BYTES, SESSION_CAP_TOKENS, SESSION_CAP_COMPACTIONS, appendEvent, EVENTS_LOCK_WAIT_MS, eventLinesFrom, readEventLines, readEvents, readEventsBuffer, archiveFiles, readArchiveLines,
   loadSyncOffset, saveSyncOffset, recordRejected, unsyncedInfo, loadSegments, saveSegments, segmentFile,
   HANDOFF_MARKER, HANDOFF_THRESHOLDS, watchThresholds, GATE_MAX_CHILDREN, HELPER_AGENT_TYPE, watchAgentId, subagentTranscriptPath, readHeadTag, lastContextTokens, watchState, handoffMessage, handleWatch, handleGate, handleGateRelease, gateDir, gateSlots, gateReserve, gateConfirm, GATE_PENDING_MS,
+  liveLoadCounts, appendLoadSample, loadFile, LIVE_TTL_MS, LIVE_TOUCH_MS, LIVE_PENDING_MS, PARALLEL_DEFAULTS, LIVE_SESSION_ROLES, AGENT_TYPE_ROLES, liveDir, liveFile, livePendingDir, intentFile, parallelLimits, readLive, liveCounts, liveSummary, briefWorktree, writeIntent, claimIntent, handleSubagentStart, removeLive, touchLive, dispatchLiveCounts, parallelCapGate,
+  STUCK_DEFAULTS, STUCK_REMIND_MS, stuckLimits, assessLive, stuckAgents, stuckReminder, stuckLine, stuckReasonText, statusFileOf, briefRunDir, liveTranscriptGuess,
   globMatch, pathspecOf, diffShas, dirtyFiles, computeFreshness, addDirty, indexStamp, freshnessCacheFile, readFreshCache, cachedFor, freshCounts, knowledgeSummary, shortFileList, readStoreIndex, relatedStatus, startKnowledge, deltaHash, deltaRepoOf, isBareRepoName, storeCatalog, storeByName, scanUnmergedDeltas, scanUnmergedDeltasFor, unmergedDeltaLines, hasUnmergedDeltas, deltaTagOf, deltaClassifier, dispatchRun, DELTA_WARN_MS, DELTA_WINDOW_MS, FRESH_CACHE_MAX, DIFF_TIMEOUT_MS, HOOK_DIFF_TIMEOUT_MS, DIRTY_TIMEOUT_MS,
   projectsDir, findGit, originUrlFromConfig, normalizeRemoteUrl, resolveProject, readHead, repoFromBrief, projectFields, nativePath, isStoreDirName, aliasesFile, loadAliases, keyDirName,
-  extractAgentId, hasAssistantUsage, hasDispatch, buildDispatch, handlePostToolUse, handleSubagentStop, openBackgroundTasks, scanLeftoverProcs, otherAgentsRunning, maybeSpawnSync, runHook, runSync,
+  extractAgentId, hasAssistantUsage, hasDispatch, buildDispatch, handlePostToolUse, handleSubagentStop, openBackgroundTasks, scanLeftoverProcs, otherAgentsRunning, mainShellSince, ownWorktree, maybeSpawnSync, runHook, runSync,
 };
 
 if (require.main === module) {
@@ -4379,7 +5078,8 @@ if (require.main === module) {
       .finally(() => process.exit(0));
   } else {
     const mode = process.argv.includes('--watch') ? 'watch'
-      : (process.argv.includes('--gate-release') ? 'gate-release' : (process.argv.includes('--gate') ? 'gate' : null));
+      : (process.argv.includes('--gate-release') ? 'gate-release'
+        : (process.argv.includes('--gate-bash') ? 'gate-bash' : (process.argv.includes('--gate') ? 'gate' : null)));
     const r = runHook({ mode });
     if (r && typeof r.stdout === 'string') process.stdout.write(r.stdout);
     process.exitCode = 0;