kenaz 0.0.0-stage → 0.3.2

package/core/.formation/tools/dispatch-model-policy.test.js

@@ -0,0 +1,165 @@
+// TASK_1998 R3: subagent-path model-by-rigor policy tests.
+// Contract (spec correction 2026-09-22, user decision — supersedes an earlier
+// low->haiku/high->opus hard-coded policy): the model ALWAYS follows the
+// Dashboard setting. For every rigor the model is dashboard-models.json's
+// `dispatchModel`, exactly as before R3 — UNLESS that same file also carries
+// an explicit `dispatchModelByRigor: {low?, medium?, high?}` object (from the
+// Dashboard's own settings), in which case the entry for the card's rigor
+// wins for that rigor only (missing keys fall back to dispatchModel). The CLI
+// flag `--dispatch-model <id>` wins over both. TASK_1815's "never substitute
+// silently" rule applies uniformly — an unmappable id from ANY source
+// (dashboard default, dashboard-by-rigor, or CLI) must exit 1 loudly.
+// Usage: node .formation/tools/dispatch-model-policy.test.js
+// Exit 0=all pass, non-zero=at least one failure
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// resolve repo root (works from worktree and main repo) — same helper as
+// __tests__/subagent-bifrost-guard.test.js
+function resolveRoot() {
+  var d = path.resolve(__dirname);
+  for (var i = 0; i < 10; i++) {
+    if (fs.existsSync(path.join(d, '.kenaz')) && fs.existsSync(path.join(d, '.formation'))) return d;
+    var parent = path.dirname(d); if (parent === d) break; d = parent;
+  }
+  if (process.env.CLAUDE_PROJECT_DIR) return process.env.CLAUDE_PROJECT_DIR;
+  throw new Error('Cannot resolve repo root from ' + __dirname);
+}
+const WT = resolveRoot();
+const SB = path.join(os.tmpdir(), 't1998r3_' + process.pid);
+const TASKAPI = path.join(WT, '.collaboration/core/task-api.js');
+const DISPATCH = path.join(WT, '.formation/tools/dispatch.js');
+const MODELS = path.join(SB, '.kenaz', 'dashboard-models.json');
+const env = { ...process.env };
+delete env.CLAUDE_PROJECT_DIR;
+
+for (const d of [
+  '.kenaz/tasks/backlog', '.kenaz/tasks/active', '.kenaz/tasks/done',
+  '.kenaz/tasks/blocked', '.kenaz/tasks/cancel', '.kenaz/locks', '.kenaz/specialist',
+]) {
+  fs.mkdirSync(path.join(SB, d), { recursive: true });
+}
+
+const run = (script, args, opts) =>
+  spawnSync(process.execPath, [script, ...args], Object.assign({ encoding: 'utf8', env, windowsHide: true, cwd: WT }, opts || {}));
+
+let pass = 0, fail = 0;
+const check = (name, cond, detail) => {
+  console.log((cond ? 'PASS' : 'FAIL') + ' | ' + name + (cond ? '' : ' | ' + detail));
+  cond ? pass++ : fail++;
+};
+
+const setModels = (obj) => fs.writeFileSync(MODELS, JSON.stringify(obj, null, 2));
+
+const mkTask = (rigor) => {
+  const r = run(TASKAPI, ['--project-path', SB, 'create', '--title', 't1998r3 ' + rigor + ' target',
+    '--description', 'model policy test task', '--scope-paths', 'zzz/policy.js',
+    '--rigor', rigor,
+    '--requirements', 'r1', '--acceptance-criteria', 'a1', '--acceptance-criteria', 'a2', '--acceptance-criteria', 'a3',
+    '--technical-notes', 't1', '--technical-notes', 't2', '--force']);
+  const id = ((r.stdout || '').match(/TASK_\d+/) || [])[0];
+  check('setup: ' + rigor + ' task created', !!id, ((r.stdout || '') + (r.stderr || '')).slice(0, 300));
+  return id;
+};
+
+const TASK_LOW = mkTask('low');
+const TASK_MEDIUM = mkTask('medium');
+const TASK_HIGH = mkTask('high');
+
+const dispatchSub = (taskId, extraArgs) =>
+  run(DISPATCH, ['--skill=do', '--task=' + taskId, '--dispatch-mode=subagent', '--project-path', SB, ...(extraArgs || [])]);
+
+const parse = (r) => { try { return JSON.parse(r.stdout); } catch { return null; } };
+
+// ── [1] default (no dispatchModelByRigor): EVERY rigor follows the dashboard
+//     dispatchModel — no hard-coded low/high substitution. ────────────────
+setModels({ dispatchModel: 'claude-opus-5[1m]', dispatchFamily: 'claude' });
+for (const [taskId, rigorKey] of [[TASK_LOW, 'low'], [TASK_MEDIUM, 'medium'], [TASK_HIGH, 'high']]) {
+  const r = dispatchSub(taskId);
+  const j = parse(r);
+  check(`${rigorKey} default: exit 0`, r.status === 0, 'status=' + r.status + ' | ' + (r.stderr || '').slice(-300));
+  check(`${rigorKey} default: model=opus (follows dashboard dispatchModel, not a hard-coded rigor default)`, !!j && j.agentParams.model === 'opus', j && JSON.stringify(j.agentParams));
+  check(`${rigorKey} default: rigor+modelSource in payload`, !!j && j.rigor === rigorKey && j.modelSource === 'dashboard', j && JSON.stringify({ rigor: j.rigor, modelSource: j.modelSource }));
+  check(`${rigorKey} default: stderr prints resolved choice`,
+    (r.stderr || '').includes(`[dispatch] rigor=${rigorKey} complexity=medium model=claude-opus-5[1m] → family 'opus' (source: dashboard)`),
+    (r.stderr || '').slice(-400));
+}
+
+// ── [2] dashboard-models.json dispatchModelByRigor — applies ONLY to the
+//     rigor it names; unset rigors keep following dispatchModel. ───────────
+setModels({
+  dispatchModel: 'claude-sonnet-4-6',
+  dispatchFamily: 'claude',
+  dispatchModelByRigor: { low: 'claude-opus-5[1m]', high: 'claude-haiku-4-5' }, // medium intentionally unset
+});
+{
+  const r = dispatchSub(TASK_LOW);
+  const j = parse(r);
+  check('by-rigor low: model=opus (dispatchModelByRigor.low)', !!j && j.agentParams.model === 'opus', j && JSON.stringify(j.agentParams));
+  check('by-rigor low: modelSource=dashboard-by-rigor', !!j && j.modelSource === 'dashboard-by-rigor', j && j.modelSource);
+}
+{
+  const r = dispatchSub(TASK_MEDIUM);
+  const j = parse(r);
+  check('by-rigor medium (unset): falls back to dispatchModel (sonnet)', !!j && j.agentParams.model === 'sonnet', j && JSON.stringify(j.agentParams));
+  check('by-rigor medium (unset): modelSource=dashboard', !!j && j.modelSource === 'dashboard', j && j.modelSource);
+}
+{
+  const r = dispatchSub(TASK_HIGH);
+  const j = parse(r);
+  check('by-rigor high: model=haiku (dispatchModelByRigor.high)', !!j && j.agentParams.model === 'haiku', j && JSON.stringify(j.agentParams));
+  check('by-rigor high: modelSource=dashboard-by-rigor', !!j && j.modelSource === 'dashboard-by-rigor', j && j.modelSource);
+}
+
+// ── [3] CLI --dispatch-model wins over dashboard-by-rigor AND dispatchModel ─
+setModels({
+  dispatchModel: 'claude-sonnet-4-6',
+  dispatchFamily: 'claude',
+  dispatchModelByRigor: { low: 'claude-opus-5[1m]' },
+});
+{
+  const r = dispatchSub(TASK_LOW, ['--dispatch-model', 'fable']);
+  const j = parse(r);
+  check('cli wins over by-rigor+dispatchModel: model=fable', !!j && j.agentParams.model === 'fable', j && JSON.stringify(j.agentParams));
+  check('cli wins: modelSource=cli', !!j && j.modelSource === 'cli', j && j.modelSource);
+  check('cli wins: rigor still reflects the card (low)', !!j && j.rigor === 'low', j && j.rigor);
+  check('cli wins: stderr shows source=cli',
+    (r.stderr || '').includes("[dispatch] rigor=low complexity=medium model=fable → family 'fable' (source: cli)"),
+    (r.stderr || '').slice(-400));
+}
+
+// ── [4] unmappable id: loud exit 1, never a silent substitute — every source ─
+setModels({ dispatchModel: 'claude-sonnet-4-6', dispatchFamily: 'claude', dispatchModelByRigor: { low: 'claude-nova-9' } });
+{
+  const r = dispatchSub(TASK_LOW);
+  check('unmappable dashboard-by-rigor: non-zero exit', r.status !== 0, 'status=' + r.status);
+  check('unmappable dashboard-by-rigor: no agentParams on stdout', !(r.stdout || '').includes('agentParams'), (r.stdout || '').slice(0, 200));
+  check('unmappable dashboard-by-rigor: loud stderr names dispatchModelByRigor.low',
+    (r.stderr || '').includes("dispatchModelByRigor.low 'claude-nova-9' cannot be mapped") &&
+    (r.stderr || '').includes('refusing to silently guess'), (r.stderr || '').slice(-400));
+}
+setModels({ dispatchModel: 'claude-nova-9', dispatchFamily: 'claude' });
+{
+  const r = dispatchSub(TASK_MEDIUM);
+  check('unmappable dashboard default: non-zero exit', r.status !== 0, 'status=' + r.status);
+  check('unmappable dashboard default: loud stderr names dispatchModel',
+    (r.stderr || '').includes("dashboard-models.json dispatchModel 'claude-nova-9' cannot be mapped") &&
+    (r.stderr || '').includes('refusing to silently guess'), (r.stderr || '').slice(-400));
+}
+setModels({ dispatchModel: 'claude-sonnet-4-6', dispatchFamily: 'claude' });
+{
+  const r = dispatchSub(TASK_MEDIUM, ['--dispatch-model', 'not-a-real-model']);
+  check('unmappable cli: non-zero exit', r.status !== 0, 'status=' + r.status);
+  check('unmappable cli: no agentParams on stdout', !(r.stdout || '').includes('agentParams'), (r.stdout || '').slice(0, 200));
+  check('unmappable cli: loud stderr names --dispatch-model',
+    (r.stderr || '').includes("--dispatch-model 'not-a-real-model' cannot be mapped") &&
+    (r.stderr || '').includes('refusing to silently guess'), (r.stderr || '').slice(-400));
+}
+
+fs.rmSync(SB, { recursive: true, force: true });
+console.log('---');
+console.log('RESULT: ' + pass + ' pass, ' + fail + ' fail');
+process.exit(fail ? 1 : 0);

package/core/.formation/tools/dispatch-notifier.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { ROOT } = require('./utils');
+
+function getDispatchNotificationFile(corePath = ROOT) {
+  return path.join(corePath, '.formation', '.dispatch-notifications.json');
+}
+
+function readDispatchNotifications(corePath = ROOT) {
+  const file = getDispatchNotificationFile(corePath);
+  try {
+    if (fs.existsSync(file)) {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+      return Array.isArray(parsed) ? parsed : [];
+    }
+  } catch {}
+  return [];
+}
+
+function writeDispatchNotifications(list, corePath = ROOT) {
+  const file = getDispatchNotificationFile(corePath);
+  try {
+    fs.writeFileSync(file, JSON.stringify(list, null, 2));
+  } catch {}
+}
+
+function enqueueDispatchNotification(event, corePath = ROOT) {
+  if (!event || !event.originSessionId || !event.taskId || !event.status) return null;
+
+  const list = readDispatchNotifications(corePath);
+  const notification = {
+    id: event.id || `dispatch-${event.taskId}-${Date.now()}`,
+    originSessionId: event.originSessionId,
+    taskId: event.taskId,
+    status: event.status,
+    summary: event.summary || '',
+    formation: event.formation || 'unit',
+    skill: event.skill || 'do',
+    dispatchSessionId: event.dispatchSessionId || null,
+    projectPath: event.projectPath || null,
+    logPath: event.logPath || null,
+    metadata: event.metadata || {},
+    createdAt: event.createdAt || new Date().toISOString(),
+  };
+  list.push(notification);
+  writeDispatchNotifications(list, corePath);
+  return notification;
+}
+
+function takeDispatchNotifications(originSessionId, corePath = ROOT) {
+  if (!originSessionId) return [];
+  const list = readDispatchNotifications(corePath);
+  if (list.length === 0) return [];
+
+  const matches = [];
+  const remaining = [];
+  for (const item of list) {
+    if (item && item.originSessionId === originSessionId) {
+      matches.push(item);
+    } else {
+      remaining.push(item);
+    }
+  }
+
+  if (matches.length > 0) {
+    if (remaining.length === 0) {
+      try { fs.unlinkSync(getDispatchNotificationFile(corePath)); } catch {}
+    } else {
+      writeDispatchNotifications(remaining, corePath);
+    }
+  }
+
+  return matches;
+}
+
+module.exports = {
+  getDispatchNotificationFile,
+  readDispatchNotifications,
+  writeDispatchNotifications,
+  enqueueDispatchNotification,
+  takeDispatchNotifications,
+};

package/core/.formation/tools/dispatch-registry.js

@@ -0,0 +1,346 @@
+'use strict';
+/**
+ * Dispatch Registry
+ *
+ * Stateless helpers for tracking active Formation dispatches via
+ * .formation/.active-dispatches.json. Extracted from headless.js.
+ *
+ * Exports: isProcessAlive, _decrementParallelCount, getAnalytics, logAnalytics,
+ *          ACTIVE_DISPATCH_FILE, MAX_CONCURRENT_DISPATCHES, STALE_DISPATCH_MS,
+ *          readActiveDispatches, writeActiveDispatches, pruneZombieDispatches,
+ *          waitForDispatchSlot, registerDispatch, unregisterDispatch
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { ROOT, dispatchLockPath, dispatchLockStaleness } = require('./utils');
+
+// Check if a process is still alive by PID (cross-platform)
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0); // signal 0 = existence check, no kill
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Parallel semaphore: atomic decrement of .parallel-count using a lock file.
+// Called after a worktree-mode dispatch finishes (worktree removed, slot freed).
+function _decrementParallelCount(countFile, countLock) {
+  const deadline = Date.now() + 10000; // 10s max wait for lock
+  while (Date.now() < deadline) {
+    let lockFd = null;
+    try {
+      lockFd = fs.openSync(countLock, 'wx');
+      try {
+        const count = fs.existsSync(countFile) ? (parseInt(fs.readFileSync(countFile, 'utf-8').trim()) || 0) : 0;
+        fs.writeFileSync(countFile, String(Math.max(0, count - 1)));
+      } finally {
+        fs.closeSync(lockFd);
+        try { fs.unlinkSync(countLock); } catch {}
+      }
+      return;
+    } catch {
+      // lock held by another process — busy wait 50ms
+      const wait = Date.now() + 50;
+      while (Date.now() < wait) {}
+    }
+  }
+}
+
+// Analytics: lazy-loaded, failure silently degrades
+let _analytics = null;
+function getAnalytics() {
+  if (_analytics === undefined) return null;
+  if (!_analytics) {
+    try { _analytics = require('./analytics'); } catch { _analytics = undefined; return null; }
+  }
+  return _analytics;
+}
+
+/**
+ * Write one JSONL record to the dispatch analytics log.
+ * Always silent — must never interrupt dispatch.
+ */
+function logAnalytics({ ts_start, taskId, skill, formation, role, projectPath, exit_code }) {
+  try {
+    const analytics = getAnalytics();
+    if (!analytics) return;
+    const ts_end = Date.now();
+    analytics.recordDispatch({
+      v: 1,
+      ts: new Date(ts_start).toISOString(),
+      task_id: taskId || null,
+      skill,
+      formation,
+      role: role || null,
+      project: path.basename(projectPath || ROOT),
+      duration_s: Math.round((ts_end - ts_start) / 1000),
+      outcome: exit_code === 0 ? 'success' : 'fail',
+      exit_code,
+    }, projectPath);
+  } catch { /* silent */ }
+}
+
+// ─────────────────────────────────────────
+// Active dispatch registry（本地檔案，Dashboard 直接讀）
+// ─────────────────────────────────────────
+
+const ACTIVE_DISPATCH_FILE = path.join(ROOT, '.formation', '.active-dispatches.json');
+
+function readActiveDispatches() {
+  try {
+    if (fs.existsSync(ACTIVE_DISPATCH_FILE)) {
+      return JSON.parse(fs.readFileSync(ACTIVE_DISPATCH_FILE, 'utf-8'));
+    }
+  } catch { /* corrupted file */ }
+  return [];
+}
+
+function writeActiveDispatches(list) {
+  // TASK_1399: temp + rename so concurrent writers (within ~1s) cannot
+  // observe a half-written file. Per-pid tmp suffix keeps two writers
+  // from clobbering each other's tmp before either rename.
+  const tmp = `${ACTIVE_DISPATCH_FILE}.tmp.${process.pid}`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(list, null, 2));
+    fs.renameSync(tmp, ACTIVE_DISPATCH_FILE);
+  } catch {
+    try { fs.unlinkSync(tmp); } catch {}
+  }
+}
+
+// Maximum concurrent formation agents (prevents resource exhaustion under heavy load)
+const MAX_CONCURRENT_DISPATCHES = parseInt(process.env.KENAZ_MAX_DISPATCHES || '3', 10);
+
+/**
+ * Prune zombie entries from .active-dispatches.json.
+ * An entry is zombie if its PID is dead or it's older than STALE_DISPATCH_MS.
+ * Returns the surviving (alive) entries.
+ */
+const STALE_DISPATCH_MS = 3600000; // 60 minutes
+
+function pruneZombieDispatches() {
+  const list = readActiveDispatches();
+  if (list.length === 0) return list;
+
+  const alive = [];
+  const pruned = [];
+  const PENDING_STALE_MS = 30000; // 30s: entries with pid=null older than this are zombie
+  for (const d of list) {
+    const age = Date.now() - new Date(d.startedAt).getTime();
+    if (age > STALE_DISPATCH_MS) {
+      pruned.push({ reason: 'stale', age: Math.round(age / 60000), ...d });
+      continue;
+    }
+    // pid=null entries are "early registrations" before the agent process spawns.
+    // If they stay pid=null for >30s, the launcher likely crashed before spawn —
+    // treat as zombie to prevent artificial slot exhaustion (deadlock root cause).
+    if (!d.pid && age > PENDING_STALE_MS) {
+      pruned.push({ reason: 'pending_stale', age: Math.round(age / 1000), ...d });
+      continue;
+    }
+    if (d.pid && !isProcessAlive(d.pid)) {
+      pruned.push({ reason: 'dead_pid', pid: d.pid, ...d });
+      continue;
+    }
+    alive.push(d);
+  }
+
+  if (pruned.length > 0) {
+    console.log(`🧹 Pruned ${pruned.length} zombie dispatch(es): ${pruned.map(p => `${p.taskId || p.sessionId} (${p.reason})`).join(', ')}`);
+    writeActiveDispatches(alive);
+  }
+  return alive;
+}
+
+// TASK_1391: clean stale .merge-lock and .dispatch-lock-* at dispatch start.
+// Idempotent + safe to call concurrently (silent on ENOENT, retries on EBUSY).
+//
+// TASK_1838: the two lock families have DIFFERENT locations and authorities:
+//   - .merge-lock lives in the TARGET project's .formation/ and keeps the
+//     original TASK_1391 semantics: dead pid OR older than maxAgeMs (10 min).
+//   - .dispatch-lock-* are written by utils.dispatchLockPath -- ALWAYS in core
+//     ROOT/.formation/ with key (projectPath || 'default'). The old cleaner
+//     recomposed the path from (projectRoot || ROOT): wrong directory for
+//     cross-project locks AND wrong key for core (projectPath=null) dispatches
+//     ('default' was never produced), so it never matched a real lock
+//     (Decorative Guard instance #2). It now enumerates the writer's own
+//     directory and judges each lock with utils.dispatchLockStaleness -- the
+//     SAME predicate tryAcquireDispatchLock breaks locks with (dead pid OR
+//     >=60 min). pid:null serial locks (TASK_1833 sub-agent dispatches) are
+//     never pid-broken; the 10 min merge-lock threshold does NOT apply to them.
+const STALE_LOCK_MAX_AGE_MS = 600000; // 10 minutes -- .merge-lock only
+function cleanupStaleLocks(projectRoot, maxAgeMs = STALE_LOCK_MAX_AGE_MS) {
+  const root = projectRoot || ROOT;
+  const formDir = path.join(root, '.formation');
+
+  // unlinkSync with EBUSY retry (Windows: AV / file watcher may briefly hold a handle)
+  const removeLock = (lockPath) => {
+    for (let i = 0; i < 3; i++) {
+      try { fs.unlinkSync(lockPath); return true; }
+      catch (e) {
+        if (e.code === 'ENOENT') return true;
+        if (e.code === 'EBUSY' && i < 2) {
+          const wait = Date.now() + 100;
+          while (Date.now() < wait) {}
+          continue;
+        }
+        return false;
+      }
+    }
+    return false;
+  };
+  const logResult = (removed, name, holder, dead, ageMs) => {
+    if (removed) {
+      console.log(`🧹 Stale lock cleared: ${name} (${holder}, ${dead ? 'dead' : `${Math.round(ageMs/1000)}s old`})`);
+    } else {
+      console.warn(`⚠️ Stale lock could not be cleared: ${name} (${holder})`);
+    }
+  };
+
+  // ── .merge-lock: target project's .formation/, dead-pid OR >maxAgeMs ──
+  const mergeLockPath = path.join(formDir, '.merge-lock');
+  if (fs.existsSync(mergeLockPath)) {
+    let dead = false;
+    let ageMs = 0;
+    let holder = '';
+    try {
+      const data = JSON.parse(fs.readFileSync(mergeLockPath, 'utf8'));
+      // TASK_2258: same freshness source as integration.js heartbeatAgeMs; heartbeat-less legacy locks keep the 10 min rule.
+      const t = data.heartbeat_at || data.acquiredAt || data.startedAt;
+      ageMs = t ? (Date.now() - new Date(t).getTime()) : maxAgeMs + 1;
+      holder = `${data.taskId || data.sessionId || '?'} pid=${data.pid}`;
+      if (data.pid && !isProcessAlive(data.pid)) dead = true;
+    } catch { dead = true; holder = '<corrupt>'; }
+    if (dead || ageMs > maxAgeMs) {
+      logResult(removeLock(mergeLockPath), '.merge-lock', holder, dead, ageMs);
+    }
+  }
+
+  // ── .dispatch-lock-*: directory AND filename prefix derived from the writer
+  // (utils.dispatchLockPath) so the cleaner cannot drift again; the 'default'
+  // suffix is the documented key for projectPath=null. Enumerating real files
+  // covers core ('default'), same-project, and cross-project locks alike.
+  const defaultLockPath = dispatchLockPath(null); // <core>/.formation/.dispatch-lock-default
+  const lockDir = path.dirname(defaultLockPath);
+  const lockPrefix = path.basename(defaultLockPath).slice(0, -'default'.length);
+  let lockNames = [];
+  try {
+    lockNames = fs.readdirSync(lockDir).filter(n => n.startsWith(lockPrefix));
+  } catch { /* no core .formation/ yet -- nothing to clean */ }
+  for (const name of lockNames) {
+    const lockPath = path.join(lockDir, name);
+    let data = null;
+    let corrupt = false;
+    try { data = JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch { corrupt = true; }
+    const { stale, pidDead, ageMs } = dispatchLockStaleness(data);
+    if (!(corrupt || stale || pidDead)) continue;
+    const holder = corrupt ? '<corrupt>' : `${data.taskId || data.sessionId || '?'} pid=${data.pid}`;
+    logResult(removeLock(lockPath), name, holder, corrupt || pidDead, ageMs);
+  }
+
+  // Reconcile .parallel-count: failed dispatches leak semaphore slots, eventually
+  // pinning count at MAX_PARALLEL and trapping new dispatchers in busy-wait.
+  // Cap count at live-dispatch count (worktree-mode entries with alive PIDs).
+  try {
+    const countFile = path.join(formDir, '.parallel-count');
+    if (!fs.existsSync(countFile)) return;
+    const current = parseInt(fs.readFileSync(countFile, 'utf-8').trim()) || 0;
+    if (current === 0) return;
+    const live = readActiveDispatches().filter(d => d.pid && isProcessAlive(d.pid) && d.worktree_path).length;
+    if (current > live) {
+      fs.writeFileSync(countFile, String(live));
+      console.log(`🧹 Reconciled .parallel-count: ${current} → ${live} (live worktree dispatches)`);
+    }
+  } catch { /* graceful no-op — count drift is recoverable on next pass */ }
+}
+
+/**
+ * Synchronously wait until active dispatch count drops below MAX_CONCURRENT_DISPATCHES.
+ * Uses Atomics.wait for a non-busy sync sleep. Huginn excluded (lightweight perception).
+ * Prunes zombie dispatches (dead PID / stale) on each poll cycle.
+ */
+function waitForDispatchSlot(formation) {
+  if (formation === 'huginn') return;
+  const POLL_MS = 15_000;
+  const sharedBuf = new Int32Array(new SharedArrayBuffer(4));
+  while (true) {
+    const active = pruneZombieDispatches().filter(d => d.formation !== 'huginn');
+    if (active.length < MAX_CONCURRENT_DISPATCHES) return;
+    console.log(`[concurrency] ${active.length}/${MAX_CONCURRENT_DISPATCHES} slots in use — waiting 15s...`);
+    Atomics.wait(sharedBuf, 0, 0, POLL_MS);
+  }
+}
+
+function registerDispatch({
+  sessionId,
+  logPath,
+  taskId,
+  formation,
+  projectPath: pp,
+  worktreePath = null,
+  originSessionId = null,
+  originTransport = null,
+  originNotificationMethod = null,
+  pid = null,
+}) {
+  const list = readActiveDispatches();
+  const nextEntry = {
+    sessionId,
+    logPath,
+    taskId,
+    formation,
+    startedAt: new Date().toISOString(),
+    projectPath: pp || null,
+    worktree_path: worktreePath || null,
+    originSessionId,
+    originTransport,
+    originNotificationMethod,
+    pid,
+  };
+  const existingIndex = list.findIndex(d => d.sessionId === sessionId);
+  if (existingIndex >= 0) {
+    const mergedEntry = {
+      ...list[existingIndex],
+      startedAt: list[existingIndex].startedAt || nextEntry.startedAt,
+    };
+    for (const [key, value] of Object.entries(nextEntry)) {
+      if (key === 'startedAt') continue;
+      if (value !== null && value !== undefined) {
+        mergedEntry[key] = value;
+      }
+    }
+    list[existingIndex] = mergedEntry;
+  } else {
+    list.push(nextEntry);
+  }
+  writeActiveDispatches(list);
+}
+
+function unregisterDispatch(sessionId) {
+  const list = readActiveDispatches().filter(d => d.sessionId !== sessionId);
+  if (list.length === 0) {
+    try { fs.unlinkSync(ACTIVE_DISPATCH_FILE); } catch { /* ignore */ }
+  } else {
+    writeActiveDispatches(list);
+  }
+}
+
+module.exports = {
+  isProcessAlive,
+  _decrementParallelCount,
+  getAnalytics,
+  logAnalytics,
+  ACTIVE_DISPATCH_FILE,
+  MAX_CONCURRENT_DISPATCHES,
+  STALE_DISPATCH_MS,
+  readActiveDispatches,
+  writeActiveDispatches,
+  pruneZombieDispatches,
+  cleanupStaleLocks,
+  waitForDispatchSlot,
+  registerDispatch,
+  unregisterDispatch,
+};