@kienntpixon/dieu-phoi 0.7.2 → 0.7.3

package/hook.cjs

@@ -26,7 +26,7 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 
-const CORE_VERSION = '0.7.2';
+const CORE_VERSION = '0.7.3';
 const SCHEMA = 1;
 const TASK_TYPES = [
   'search', 'extract', 'mechanical-edit', 'feature-impl', 'debug', 'refactor',
@@ -274,6 +274,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
     }
@@ -1715,11 +1717,18 @@ function formatStartBlock(info) {
 
 /** 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,
   };
@@ -1871,7 +1880,7 @@ function handoffChainMessage(taskId, n) {
 const MODES = ['fast', 'normal', 'strict'];
 const DEFAULT_MODE = 'normal';
 /** 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 LOCAL_ONLY_KINDS = new Set(['mode', 'knowledge_merge', 'leftover', 'worktree', 'reap', 'reap_orphans']);
 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>`';
 
@@ -2900,6 +2909,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 +2928,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 +3002,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 +3302,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 +3401,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 +3464,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 +3491,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 +3962,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 +3981,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 +4046,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 +4565,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) {
@@ -4096,6 +4709,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 +4722,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 }) };
 }
 
@@ -4193,11 +4819,16 @@ 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 (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);
@@ -4363,9 +4994,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) {