kenaz 0.3.2 → 0.3.5

package/core/.formation/tools/headless.js

@@ -1,1071 +0,0 @@
-#!/usr/bin/env node
-/**
- * Formation Headless Launcher — Orchestrator (L5)
- *
- * 無頭模式啟動器：由 Formation Lead 配好任務後直接呼叫。
- * subagent 不會問問題，直接執行。
- *
- * ┌─────────────────────────────────────────────────────────────────┐
- * │  Module Dependency Graph (L3–L5 layer)                          │
- * │                                                                 │
- * │  headless.js (L5 orchestrator)                                  │
- * │    ├── formations.js       — all launchXxx + setupUnitWorktree  │
- * │    ├── task-utils.js       — task helpers + verifyTaskInProject  │
- * │    ├── broadcast.js        — Supabase status broadcasting       │
- * │    ├── dispatch-registry.js— zombie pruning + parallel slots    │
- * │    ├── process-state.js    — _activeChildren, _activeWorktrees  │
- * │    ├── prompt.js      (L3) — prompt assembly + HEADLESS_PREFIX  │
- * │    ├── runner.js      (L4) — runHeadless / killProcessTree      │
- * │    ├── loader.js           — skill + task YAML loading          │
- * │    ├── utils.js            — ROOT, generateSessionId, git ops   │
- * │    └── post-complete.js    — (used by formations.js, not here)  │
- * └─────────────────────────────────────────────────────────────────┘
- *
- * 5 種陣型（implemented in formations.js, dispatched here）：
- *   launchUnit   — 單一 agent 直接執行
- *   launchSolo   — 單一 agent 多視角分析
- *   launchSquad  — 多 agent 並行 + 辯論 + 整合
- *   launchLegion — Agent Teams（TeamCreate / SendMessage）
- *   launchLegacy — 連續排程器（Rust SingleAgentScheduler 對等實作）
- *
- * Usage:
- *   node .formation/tools/headless.js --skill=do --task="修正按鈕顏色"
- *   node .formation/tools/headless.js --formation=solo --skill=strategy --task="評估快取方案"
- *   node .formation/tools/headless.js --formation=squad --skill=blitz --task=TASK_201
- *   node .formation/tools/headless.js --formation=legion --skill=forge --task=TASK_202
- */
-
-const fs = require('fs');
-const path = require('path');
-const { execSync } = require('child_process');
-const { loadSkill, loadTask } = require('./loader');
-const {
-  buildPrompt, buildSquadSynthesisPrompt, buildSquadDebatePrompts,
-  buildLegionLeadPrompt, HEADLESS_PREFIX,
-} = require('./prompt');
-const { runSingle, runHeadless, killProcessTree } = require('./runner');
-const {
-  generateSessionId, ROOT, LOG_DIR, getLogDir, ensureGitReady, dispatchLockPath, dispatchLockStaleness,
-  unlinkNodeModulesBestEffort, loadDashboardModels,
-} = require('./utils');
-const { pruneZombieDispatches, cleanupStaleLocks, isProcessAlive, readActiveDispatches, writeActiveDispatches } = require('./dispatch-registry');
-const { _activeChildren, _activeWorktrees } = require('./process-state');
-const formations = require('./formations');
-
-// ─────────────────────────────────────────
-// NOTE: ensureTaskComplete was REMOVED.
-// Task must NOT be marked done before git merge completes.
-// post-complete.js handles task completion internally:
-//   - git merge success → task → done (line ~2247 in post-complete.js)
-//   - git merge failure → task stays in active
-// This ensures the user branch always has the code before task is closed.
-// ─────────────────────────────────────────
-
-process.on('exit', () => {
-  for (const child of _activeChildren) {
-    try { killProcessTree(child); } catch {}
-  }
-  // Cleanup dangling worktrees (process.on('exit') must be sync — use execSync)
-  for (const [worktreePath, projectRoot] of _activeWorktrees) {
-    // TASK_1844/TASK_2030: MUST run before any `git worktree remove` -- Git for
-    // Windows recurses through a node_modules junction/symlink on removal and
-    // empties the link target (the main checkout's node_modules). Sync — this
-    // handler runs inside process.on('exit').
-    try { unlinkNodeModulesBestEffort(worktreePath); } catch {}
-    try {
-      execSync(`git worktree remove --force "${worktreePath}"`, {
-        cwd: projectRoot, encoding: 'utf8', timeout: 10000, windowsHide: true, stdio: 'pipe',
-      });
-    } catch {}
-  }
-});
-
-const { broadcastStatus, broadcastStatusSync } = require('./broadcast');
-const {
-  FIX_QUEUE_FILE, checkAndDispatchFix, checkTaskDependencies,
-  recoverStaleTasks, findNextTask, verifyTaskInProject,
-} = require('./task-utils');
-
-// TASK_2243: recovery extracted so tests can run it against throwaway repos.
-// Kenaz dispatch branches are exactly task/task_<digits> (dispatch.js, formations.js,
-// headless-v2.js, git-merge.js all build `task/${taskId.toLowerCase()}`). Any other
-// task/* branch (a user's task/600-foo) is NOT ours and must never be moved.
-const DISPATCH_BRANCH_RE = /^task\/task_(\d+)$/i;
-
-// Conservative by design: plain `git checkout` only -- no -f, no stash. A dirty
-// tracked tree, a live dispatch lock for the same card, or any git failure ABORTS
-// the recovery and leaves the branch and the edits untouched.
-function recoverStaleDispatchBranch(gitRoot, opts = {}) {
-  const es = (cmd) => String(execSync(cmd, { cwd: gitRoot, encoding: 'utf8', timeout: 10000, windowsHide: true, stdio: 'pipe' }));
-  const log = opts.log || console.log;
-  const currentBranch = opts.currentBranch || es('git rev-parse --abbrev-ref HEAD').trim();
-  const m = DISPATCH_BRANCH_RE.exec(currentBranch);
-  if (!m) {
-    log(`   ℹ️  Pre-dispatch: ${currentBranch} is not a Kenaz dispatch branch, no recovery`);
-    return { recovered: false, reason: 'not-dispatch-branch' };
-  }
-  // Cheap live-dispatch signal: the project dispatch lock names the card it serves.
-  try {
-    const holder = JSON.parse(fs.readFileSync(opts.lockFile || dispatchLockPath(opts.projectPath || null), 'utf8'));
-    const { stale, pidDead } = dispatchLockStaleness(holder);
-    const holderId = String((holder && holder.taskId) || '').replace(/\D/g, '');
-    if (!stale && !pidDead && holderId === m[1]) {
-      log(`   ⚠️  Pre-dispatch: ${currentBranch} is held by a live dispatch, recovery skipped`);
-      return { recovered: false, reason: 'live-dispatch' };
-    }
-  } catch { /* no/corrupt lock file -- no live-dispatch signal */ }
-  try {
-    if (es('git status --porcelain --untracked-files=no').trim()) {
-      log(`   ⚠️  Pre-dispatch: ${currentBranch} has uncommitted tracked changes, recovery ABORTED (staying on branch, work untouched)`);
-      return { recovered: false, reason: 'dirty-tree' };
-    }
-    const targetBranch = opts.targetBranch || resolveDispatchTargetBranch(gitRoot);
-    log(`   ⚠️  Pre-dispatch: stuck on ${currentBranch}, recovering to ${targetBranch}`);
-    es(`git checkout ${targetBranch}`);
-    log(`   ✅  Pre-dispatch: recovered to ${targetBranch}`);
-    return { recovered: true, reason: 'recovered' };
-  } catch (e) {
-    log(`   ⚠️  Pre-dispatch: recovery ABORTED (${String((e && e.message) || e).split('\n')[0]}); staying on ${currentBranch}, work untouched`);
-    return { recovered: false, reason: 'checkout-failed' };
-  }
-}
-
-function resolveDispatchTargetBranch(gitRoot) {
-  try {
-    const currentBranch = execSync('git rev-parse --abbrev-ref HEAD', {
-      cwd: gitRoot, encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: 'pipe',
-    }).trim();
-    if (currentBranch && !currentBranch.startsWith('task/')) return currentBranch;
-  } catch {}
-
-  // If HEAD is a task/* branch (e.g. dispatch invoked from inside a worktree),
-  // ask git for the main worktree's branch instead of guessing from user.name.
-  // `git worktree list --porcelain` first stanza is always the main worktree.
-  try {
-    const worktreeList = execSync('git worktree list --porcelain', {
-      cwd: gitRoot, encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: 'pipe',
-    });
-    for (const line of worktreeList.split(/\r?\n/)) {
-      const m = line.match(/^branch refs\/heads\/(.+)$/);
-      if (m && !m[1].startsWith('task/')) return m[1];
-    }
-  } catch {}
-
-  try {
-    const dispatchFile = path.join(gitRoot, '.formation', '.dispatch-branch');
-    if (fs.existsSync(dispatchFile)) {
-      const savedBranch = fs.readFileSync(dispatchFile, 'utf8').trim();
-      if (savedBranch && !savedBranch.startsWith('task/')) return savedBranch;
-    }
-  } catch {}
-
-  return 'main';
-}
-
-function persistDispatchBranch(branchName, projectPath) {
-  if (!branchName) return;
-  try {
-    fs.writeFileSync(path.join(ROOT, '.formation', '.dispatch-branch'), branchName);
-    if (projectPath && path.resolve(projectPath) !== path.resolve(ROOT)) {
-      const projFormation = path.join(projectPath, '.formation');
-      if (!fs.existsSync(projFormation)) fs.mkdirSync(projFormation, { recursive: true });
-      fs.writeFileSync(path.join(projFormation, '.dispatch-branch'), branchName);
-    }
-  } catch {}
-}
-
-function resolveLaunchBifrostAdapter(explicitAdapter) {
-  const normalizedExplicit = explicitAdapter?.trim();
-  if (normalizedExplicit) return { adapter: normalizedExplicit, source: 'dispatch' };
-
-  const envAdapter = process.env.BIFROST_ADAPTER?.trim();
-  if (envAdapter) return { adapter: envAdapter, source: 'env' };
-
-  if (process.env.CODEX_THREAD_ID) {
-    return { adapter: 'openai', source: 'codex_thread' };
-  }
-
-  try {
-    const signalPath = path.join(ROOT, '.formation', '.bifrost-active');
-    if (fs.existsSync(signalPath)) {
-      const signal = JSON.parse(fs.readFileSync(signalPath, 'utf8'));
-      // Self-heal: validate signal.pid is alive before honoring. A stale signal
-      // (process crashed without cleanup, force-kill, etc.) silently mis-routes
-      // every subsequent dispatch to the wrong adapter — observed 8-day silent
-      // failure on 2026-05-01 where pid=5700 from 2026-04-23 forced openai.
-      if (signal.pid != null && !isProcessAlive(signal.pid)) {
-        try { fs.unlinkSync(signalPath); } catch {}
-        // fall through to adapter:none — caller will use native Claude CLI
-      } else {
-        const signalAdapter = signal.adapter?.trim();
-        if (signalAdapter) return { adapter: signalAdapter, source: 'signal' };
-      }
-    }
-  } catch {}
-
-  return { adapter: null, source: 'none' };
-}
-
-function attachBifrostAdapterCleanup(result, restoreEnv) {
-  const targets = [];
-  if (result?.child?.on) {
-    targets.push(result.child);
-  } else if (Array.isArray(result)) {
-    for (const child of result) {
-      if (child?.on) targets.push(child);
-    }
-  } else if (result?.on) {
-    targets.push(result);
-  }
-
-  if (targets.length === 0) {
-    restoreEnv();
-    return result;
-  }
-
-  let pending = targets.length;
-  let restored = false;
-  const finish = () => {
-    if (restored) return;
-    pending -= 1;
-    if (pending > 0) return;
-    restored = true;
-    restoreEnv();
-  };
-
-  for (const target of targets) {
-    target.once('close', finish);
-    target.once('formation:done', finish);
-  }
-
-  return result;
-}
-
-// ─────────────────────────────────────────
-// 主調度
-// ─────────────────────────────────────────
-
-function launch(options) {
-  const {
-    formation = 'unit',
-    skill = 'do',
-    task,
-    dryRun = false,
-    mode,
-    concurrency,
-    projectPath = null,
-    skipPostComplete = false,
-    skipTests = false,
-    inProcess = false,
-    trigger = null,
-    focus = null,
-    query = null,
-    originSessionId = null,
-    bifrostAdapter = null,
-    // Dashboard-driven model override (Quick Actions → Default Models →
-    // Dispatch agent). When set, takes precedence over per-skill
-    // model_override and over the parent session inheritance pattern.
-    // Read by kenaz_dispatch backend route from .kenaz/dashboard-models.json.
-    dispatchModel = null,
-    depth = 'kernel',  // Inert: forwarded as promptOpts.depth, but prompt.js buildPrompt never reads it.
-                       // Dispatch agents get a skill brief (skill + principles + task), never kernel.yaml or elixir.
-    // TASK_1929 (Agent Hub M2): see headless.js CLI section + runner.js
-    // spawnClaude / spawnBifrost for how these two flow into the actual
-    // child process. Both default to "no override" so every pre-existing
-    // caller of launch() (nothing sets these) behaves identically.
-    mcpConfigExtra = [],
-    allowedToolsOverride = null,
-  } = options;
-
-  const sessionId = process.env.KENAZ_SESSION_ID?.trim() || generateSessionId();
-  const previousAdapter = process.env.BIFROST_ADAPTER;
-  const adapterSelection = resolveLaunchBifrostAdapter(bifrostAdapter);
-  if (adapterSelection.adapter) {
-    process.env.BIFROST_ADAPTER = adapterSelection.adapter;
-    console.log(`   Bifrost adapter: ${adapterSelection.adapter} (source=${adapterSelection.source})`);
-  }
-
-  // 0.-1 Bifröst auto-detect: if launch.js wrote .bifrost-active signal, route through Codex relay.
-  // Signal file is created by launch.js on start and deleted on cleanup — reliable across all shells.
-  if (false && !process.env.BIFROST_ADAPTER) {
-    try {
-      const signalPath = path.join(ROOT, '.formation', '.bifrost-active');
-      if (fs.existsSync(signalPath)) {
-        const signal = JSON.parse(fs.readFileSync(signalPath, 'utf8'));
-        if (signal.adapter) {
-          process.env.BIFROST_ADAPTER = signal.adapter;
-          console.log(`   🌈 Bifröst: active session detected (${signal.adapter}) — routing agents through relay`);
-        }
-      }
-    } catch { /* non-fatal — default to Claude */ }
-  }
-
-  // 0. Cleanup: kill orphaned claude.exe processes + recover stale tasks
-  try {
-    const { cleanOrphanedClaude } = require('../../.specialist/tools/session');
-    const orphanResult = cleanOrphanedClaude();
-    if (orphanResult.killed > 0) {
-      console.log(`🧹 Cleaned ${orphanResult.killed} orphaned claude.exe process(es)`);
-    }
-  } catch { /* session.js not available — skip */ }
-  recoverStaleTasks(projectPath);
-  pruneZombieDispatches();
-  cleanupStaleLocks(projectPath || ROOT); // TASK_1391: clear stale .merge-lock + .dispatch-lock before spawn
-
-  // 0.0 Parallel dispatch — worktree isolation mode (with serial dispatch-lock fallback)
-  // IMPORTANT: Only real task executions (TASK_XXX) get worktrees.
-  // Coordinator sessions (Ansuz via loop.js) skip — they dispatch sub-tasks, not code changes.
-  const isRealTask = task && /^TASK_\d+$/i.test(task);
-
-  // 0.0.0 Auto-activate task: move backlog → active and git-commit BEFORE worktree creation
-  // Root cause: uncommitted filesystem changes are invisible to git worktrees (worktree forks from HEAD).
-  // Fix: commit the status change so the forked worktree sees the correct active state.
-  // Guard: only for real task dispatches (not coordinator sessions, not legacy formation).
-  if (isRealTask && formation !== 'legacy' && dryRun) {
-    // TASK_2283: dry-run must not move the task or commit.
-    console.log(`   [dry-run] would auto-activate ${task} (task-api move active + git commit NOT performed)`);
-  } else if (isRealTask && formation !== 'legacy') {
-    try {
-      const activateProjectPath = projectPath
-        || (fs.existsSync(path.join(ROOT, '.kenaz', 'tasks')) ? ROOT : null);
-      const activateArgs = [];
-      if (activateProjectPath) activateArgs.push('--project-path', activateProjectPath);
-      activateArgs.push('move', task, 'active');
-      execSync(
-        `node "${path.join(ROOT, '.collaboration', 'core', 'task-api.js')}" ${activateArgs.join(' ')}`,
-        { encoding: 'utf8', timeout: 10000, cwd: ROOT, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }
-      );
-      console.log(`   📋 Auto-activated: ${task} → active/`);
-    } catch (e) {
-      // Non-fatal: task may already be active, completed, or in an incompatible state
-      const msg = (e.stderr || e.message || '').toString().split('\n')[0];
-      console.log(`   ⚠️  Auto-activate skipped: ${msg}`);
-    }
-    // Commit the status change to git so the worktree forks from the correct state
-    try {
-      const gitRoot = projectPath || ROOT;
-      execSync('git add .kenaz/tasks/ .collaboration/tasks/', {
-        cwd: gitRoot, encoding: 'utf8', timeout: 10000, windowsHide: true, stdio: 'pipe',
-      });
-      execSync(`git commit -m "[Formation] Auto-activate: ${task} -> active"`, {
-        cwd: gitRoot, encoding: 'utf8', timeout: 15000, windowsHide: true, stdio: 'pipe',
-      });
-      console.log(`   💾 Committed: ${task} status → active`);
-    } catch (commitErr) {
-      // Non-fatal: nothing to commit (already active/committed) or git not available
-      const msg = (commitErr.stderr || commitErr.message || '').toString().split('\n')[0];
-      console.log(`   ⚠️  Status commit skipped: ${msg}`);
-    }
-  }
-
-  // Fix: always record dispatch branch BEFORE worktree creation.
-  // Root cause: the post-dispatch branch-write block (line ~282) skips worktree mode,
-  // so .dispatch-branch was only updated during non-worktree (read-only) dispatches.
-  // Since all real tasks use worktree mode, the file could lag by days.
-  if (dryRun) {
-    console.log('   [dry-run] would record dispatch branch (.dispatch-branch NOT written)');
-  } else try {
-    const gitRoot = projectPath || ROOT;
-    const currentBranch = execSync('git rev-parse --abbrev-ref HEAD', {
-      cwd: gitRoot, encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: 'pipe',
-    }).trim();
-    persistDispatchBranch(currentBranch && !currentBranch.startsWith('task/')
-      ? currentBranch
-      : resolveDispatchTargetBranch(gitRoot), projectPath);
-  } catch { /* non-fatal — post-complete has its own fallback */ }
-
-  // Special routing: huginn-think — Prefrontal Thinking Engine (no task, no skill YAML).
-  // TASK_2028: MUST stay above the worktree-setup block below: --task can make isRealTask true,
-  // and this route returns without ever using (or cleaning) a worktree.
-  if (skill === 'huginn-think') {
-    const huginnModel = resolveAgentModel('huginnModel');
-    return formations.launchHuginnThink({ trigger, focus, query, sessionId, projectPath, dryRun, inProcess, depth, model: huginnModel });
-  }
-
-  // TASK_2029: skills that are READ-ONLY (never touch git, produce no commits) must never get
-  // a worktree. huginn-think already avoids it via its early return above.
-  // heimdall: code_watch.rs spawns it in the user's live repo on EVERY commit
-  // (post-commit hook -> /api/code_watch/trigger). Its skill only produces
-  // proposals, never git writes; without this entry the pre-dispatch branch
-  // recovery ran 8 s after each commit and switched a user's task/* branch to
-  // main (field report 2026-10-03, gamem, wish-301c720c; see TASK_2243).
-  const READ_ONLY_SKILLS = ['huginn-think', 'heimdall'];
-
-  // Worktree state — passed through to launchUnit for cleanup in onDone
-  let _unitWorktreePath = null;  // non-null = worktree mode active
-  let _unitCountFile = null;
-  let _unitCountLock = null;
-
-  if (formation !== 'legacy' && isRealTask && !READ_ONLY_SKILLS.includes(skill) && dryRun) {
-    // TASK_2283: dry-run only reports. setupUnitWorktree writes a dirty snapshot, takes the
-    // parallel-count lock, creates the worktree + task branch and may recover a stale branch.
-    // _unitWorktreePath stays null; the dry-run exit below never reaches launch/cleanup.
-    const wtPath = path.join(projectPath || ROOT, '.formation', 'worktrees', `task_${task.toLowerCase()}`);
-    console.log(`   [dry-run] would create unit worktree: ${wtPath} (parallel-count lock NOT taken, no branch recovery)`);
-  } else if (formation !== 'legacy' && isRealTask && !READ_ONLY_SKILLS.includes(skill)) {
-    const result = formations.setupUnitWorktree({
-      projectRoot: projectPath || ROOT,
-      projectPath,
-      taskId: task,
-      sessionId,
-    });
-    _unitWorktreePath = result.worktreePath;
-    _unitCountFile = result.countFile;
-    _unitCountLock = result.countLock;
-  }
-
-  // 0.1 自動尋找任務（當沒有指定 --task 且非 legacy 時）
-  //     使用 projectPath 查找當前專案的任務
-  let resolvedTask = task;
-  if (!resolvedTask && formation !== 'legacy') {
-    const nextTask = findNextTask(projectPath);
-    if (!nextTask) {
-      console.log('✅ No pending tasks found in backlog. Nothing to do.');
-      if (projectPath) console.log(`   (searched in: ${projectPath})`);
-      if (inProcess) return null;
-      process.exit(0);
-    }
-    resolvedTask = nextTask.id;
-    console.log(`🔍 Auto-selected: [${nextTask.id}] ${nextTask.title} (${['P0','P1','P2','P3'][nextTask.priority] || 'P?'})\n`);
-  }
-
-  // 1. 載入（支援 projectPath）
-  const skillDef = loadSkill(formation, skill);
-  const loadOpts = projectPath ? { projectPath } : undefined;
-  const taskData = resolvedTask && resolvedTask.startsWith('TASK_') ? loadTask(resolvedTask, loadOpts) : null;
-  const taskInput = resolvedTask || '';
-
-  // 1.0.0 護欄：明確指定 TASK_ID 但任務不存在 → 早期終止，不啟動 agent
-  if (resolvedTask?.startsWith('TASK_') && !taskData) {
-    const searchPaths = projectPath
-      ? [path.join(projectPath, '.kenaz/tasks'), path.join(projectPath, '.collaboration/tasks')]
-      : ['.kenaz/tasks', '.collaboration/tasks'];
-    console.error(`❌ Task ${resolvedTask} not found — task does not exist.`);
-    console.error(`   Searched: ${searchPaths.join(', ')}`);
-    console.error(`   Aborting: will not start agent for a non-existent task.`);
-    if (!inProcess) process.exitCode = 1;
-    return null;
-  }
-
-  // 1.0.1 跨專案安全護欄：驗證 task YAML 確實屬於指定專案
-  // 防止 task 被誤 dispatch 到錯誤專案（2026-03-17 incident: TASK_549 → wrong repo）
-  if (!verifyTaskInProject(taskData, resolvedTask, projectPath)) {
-    if (!inProcess) process.exitCode = 1;
-    return null;
-  }
-
-  // 1.1 依賴預檢：確認所有依賴都已完成（legacy scheduler 有自己的依賴邏輯，跳過）
-  if (taskData && formation !== 'legacy') {
-    const depCheck = checkTaskDependencies(taskData, projectPath);
-    if (depCheck.blocked) {
-      console.error(`❌ Dispatch blocked: ${taskInput} has unmet dependencies`);
-      for (const dep of depCheck.unmet) {
-        if (depCheck.blockedDeps && depCheck.blockedDeps.includes(dep)) {
-          console.error(`   ⛔ ${dep} — blocked`);
-        } else {
-          console.error(`   ⛔ ${dep} — not in done/completed`);
-        }
-      }
-      console.error(`   → Complete the dependencies first, or use --force to override`);
-      if (!options.force) {
-        if (!inProcess) process.exitCode = 1;
-        return null;
-      }
-      console.warn(`   ⚠️  --force: dispatching despite unmet dependencies`);
-    }
-  }
-
-  const promptOpts = { analysisMode: mode };
-  if (projectPath) promptOpts.projectPath = projectPath;
-  promptOpts.depth = depth || 'kernel';
-  // TASK_1819: thread worktree-mode awareness into prompt assembly. Serial
-  // (non-worktree) dispatches share the working tree with the user/Ansuz, so
-  // appendWorkflow must not emit a blanket `git add -A` commit step for them
-  // (TASK_188: swept 392 unrelated files into one commit). Worktree setup runs
-  // BEFORE this point, so _unitWorktreePath already reflects reality — including
-  // the fallback-to-serial case when worktree creation fails.
-  promptOpts.isWorktree = !!_unitWorktreePath;
-  const rawPrompt = buildPrompt(skillDef, taskInput, taskData, promptOpts);
-
-  // 1.5. Parse taskData for canary scope binding + analytics role
-  let taskScopePaths = [];
-  let taskRole = null;
-  let taskRigor = null;
-  if (taskData) {
-    try {
-      const parsed = JSON.parse(taskData);
-      taskScopePaths = parsed.scope_paths || [];
-      taskRole = parsed.role || null;
-      taskRigor = parsed.rigor || null;
-    } catch { /* raw YAML or non-JSON — no structured scope */ }
-  }
-
-  // 2. Banner
-  console.log(`⚔️  Formation Headless Launch`);
-  console.log(`   Formation: ${formation}`);
-  console.log(`   Skill:     ${skill}`);
-  console.log(`   Task:      ${taskInput.slice(0, 60)}${taskInput.length > 60 ? '...' : ''}`);
-  console.log(`   Session:   ${sessionId}`);
-  if (projectPath) console.log(`   Project:   ${projectPath}`);
-  console.log('');
-
-  // 3. Dry run
-  if (dryRun) {
-    return printDryRun(formation, rawPrompt, skillDef, skill);
-  }
-
-  // 4. 確保子專案 git 已就緒
-  ensureGitReady(projectPath);
-
-  // 4.1. Pre-dispatch branch recovery: if stuck on a task branch from a previous
-  // failed dispatch, switch back before doing anything else.
-  // This is the FIRST LINE OF DEFENSE against "stuck on task branch" incidents.
-  // Skip for read-only skills (huginn-think, heimdall) — they don't need git and
-  // their branch recovery can race with parallel post-complete git ops.
-  // Skip for worktree mode — worktree starts clean on its own task branch, no recovery needed.
-  // (READ_ONLY_SKILLS declared once, above the worktree-setup gate — TASK_2029.)
-  if (READ_ONLY_SKILLS.includes(skill) || _unitWorktreePath) {
-    // Skip git recovery — read-only skills don't touch git; worktree mode starts clean
-  } else try {
-    const { execSync: es } = require('child_process');
-    const gitRoot = projectPath || ROOT;
-    const currentBranch = es('git rev-parse --abbrev-ref HEAD', {
-      cwd: gitRoot, encoding: 'utf8', timeout: 5000, windowsHide: true,
-    }).trim();
-
-    if (currentBranch.startsWith('task/')) {
-      recoverStaleDispatchBranch(gitRoot, { currentBranch, projectPath });
-    }
-
-    // Save current branch for post-complete recovery (re-read after potential recovery)
-    const branchAfter = es('git rev-parse --abbrev-ref HEAD', {
-      cwd: gitRoot, encoding: 'utf8', timeout: 5000, windowsHide: true,
-    }).trim();
-    persistDispatchBranch(
-      branchAfter.startsWith('task/') ? resolveDispatchTargetBranch(gitRoot) : branchAfter,
-      projectPath,
-    );
-  } catch { /* ignore — post-complete will fallback to getCurrentBranch() */ }
-
-  // 4.2. Auto-claim task: move from backlog → active before agent starts
-  // Agents may forget or delay claiming, causing dashboard to show task stuck in backlog
-  // Auto-detect .kenaz/tasks/ presence: if cwd has .kenaz/tasks/, use cwd as --project-path
-  // even when projectPath is not explicitly passed (core project with .kenaz/ layout)
-  if (resolvedTask && resolvedTask.startsWith('TASK_') && formation !== 'legacy') {
-    try {
-      const apiArgs = [];
-      const effectiveProjectPath = projectPath
-        || (fs.existsSync(path.join(ROOT, '.kenaz', 'tasks')) ? ROOT : null);
-      if (effectiveProjectPath) apiArgs.push('--project-path', effectiveProjectPath);
-
-      // TASK_1787 (DEFECT-F): read-only self-claim guard.
-      // The dispatching Ansuz stream typically pre-claims the task before spawning us.
-      // The claim subprocess below is a different pid, so task-api's re-entrancy check
-      // (owner_session AND owner_pid) can never match cross-process → it emits a spurious
-      // "already claimed" warning indistinguishable from a real foreign-stream collision.
-      // Detect our own marker here (anchor: owner_conversation_id; fallback: owner_session
-      // when conv id is null; never owner_pid) and skip the claim subprocess entirely.
-      // Foreign, absent, or corrupt markers fall through to the existing claim path untouched.
-      let selfClaimed = false;
-      if (effectiveProjectPath) {
-        try {
-          const marker = JSON.parse(fs.readFileSync(
-            path.join(effectiveProjectPath, '.kenaz', 'locks', `claim_${resolvedTask}.json`), 'utf8'));
-          selfClaimed = require('./dispatch')._isOwnClaimMarker(marker, effectiveProjectPath);
-        } catch { /* no marker / no stream identity (worker context) / corrupt → normal claim path */ }
-      }
-      if (selfClaimed) {
-        console.log(`   📋 Auto-claim: ${resolvedTask} already claimed by this stream — skipping`);
-      } else {
-        apiArgs.push('claim', resolvedTask, '--by=system', `--git-user=${resolvedTask}`);
-        execSync(
-          `node "${path.join(ROOT, '.collaboration', 'core', 'task-api.js')}" ${apiArgs.join(' ')}`,
-          { encoding: 'utf8', timeout: 10000, cwd: ROOT, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }
-        );
-        console.log(`   📋 Auto-claimed: ${resolvedTask} → active/`);
-      }
-    } catch (e) {
-      // Claim may fail if already active — non-fatal
-      console.log(`   ⚠️  Auto-claim skipped: ${(e.stderr || e.message || '').split('\n')[0]}`);
-    }
-  }
-
-  // 4.5 Yggdrasil: 廣播上線狀態（非 legacy，legacy 自己廣播）
-  if (formation !== 'legacy') {
-    broadcastStatus(projectPath, {
-      is_online: true,
-      current_task: resolvedTask || null,
-      touching_files: taskScopePaths || [],
-    });
-
-    // Signal handlers: await cleanup 確保 Supabase 更新完成
-    // Note: process.on('exit') 不支援 async，由 child.on('close') 處理 cleanup
-    // inProcess 模式跳過 — 不能在 MCP server 上註冊 signal handlers
-    if (!inProcess) {
-      const handleSignal = (code) => {
-        broadcastStatusSync(projectPath, { is_online: false, current_task: null, touching_files: [] });
-        process.exit(code);
-      };
-      process.on('SIGINT', () => handleSignal(130));
-      process.on('SIGTERM', () => handleSignal(143));
-    }
-  }
-
-  // 4.6 TASK_904: Agent Attention SNN — pre-dispatch conflict detection.
-  // Query the Thalamus HTTP endpoint for agent conflict warnings on scope files.
-  // If conflicts exist, log a warning. In --strict-conflict mode, block dispatch.
-  if (taskScopePaths.length > 0 && formation !== 'legacy') {
-    try {
-      const http = require('http');
-      const conflictCheck = new Promise((resolve) => {
-        const postData = JSON.stringify({ file_paths: taskScopePaths });
-        const req = http.request({
-          hostname: '127.0.0.1',
-          port: 54321,
-          path: '/api/rust/agent-flow/agent-conflicts',
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(postData) },
-          timeout: 3000,
-        }, (res) => {
-          let data = '';
-          res.on('data', (chunk) => { data += chunk; });
-          res.on('end', () => {
-            try { resolve(JSON.parse(data)); } catch { resolve(null); }
-          });
-        });
-        req.on('error', () => resolve(null));
-        req.on('timeout', () => { req.destroy(); resolve(null); });
-        req.write(postData);
-        req.end();
-      });
-
-      // Synchronous wait with timeout (non-blocking for 3s max)
-      const conflictResult = (() => {
-        try {
-          // Use execSync to make a synchronous HTTP call (simpler for pre-dispatch check)
-          const curlCmd = process.platform === 'win32'
-            ? `powershell -Command "try { $r = Invoke-RestMethod -Uri 'http://127.0.0.1:54321/api/rust/agent-flow/agent-conflicts' -Method POST -ContentType 'application/json' -Body '${JSON.stringify({ file_paths: taskScopePaths }).replace(/'/g, "''")}' -TimeoutSec 3; $r | ConvertTo-Json -Compress } catch { '{}' }"`
-            : `curl -s --max-time 3 -X POST -H 'Content-Type: application/json' -d '${JSON.stringify({ file_paths: taskScopePaths })}' http://127.0.0.1:54321/api/rust/agent-flow/agent-conflicts`;
-          const result = execSync(curlCmd, { encoding: 'utf8', timeout: 5000, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] }).trim();
-          return result ? JSON.parse(result) : null;
-        } catch { return null; }
-      })();
-
-      if (conflictResult && Array.isArray(conflictResult.conflicts) && conflictResult.conflicts.length > 0) {
-        console.log(`   ⚠️  Agent Conflict Warning (TASK_904):`);
-        for (const c of conflictResult.conflicts) {
-          console.log(`      🔥 ${c.file_path} — ${c.fire_count} conflict fire(s)`);
-        }
-        if (options.strictConflict) {
-          console.error(`   ❌ Dispatch blocked: --strict-conflict is set and ${conflictResult.conflicts.length} file(s) have active agent conflicts`);
-          if (!inProcess) process.exitCode = 1;
-          return null;
-        }
-        console.log(`      → Proceeding with warning (use --strict-conflict to block)`);
-      }
-    } catch { /* conflict check failed — non-fatal, proceed with dispatch */ }
-  }
-
-  // 4.7 TASK_944: Pre-dispatch health snapshot — take a fresh before-snapshot
-  // at dispatch time so Heimdall compares accurate baselines (not stale ones).
-  if (resolvedTask && resolvedTask.startsWith('TASK_') && formation !== 'legacy') {
-    try {
-      const { measureHealthScoreSync, saveTaskHealthSnapshot } = require('./post-complete');
-      const health = measureHealthScoreSync(projectPath);
-      if (health) {
-        saveTaskHealthSnapshot(resolvedTask, 'before', health, projectPath);
-        console.log(`   🛡️  Pre-dispatch health snapshot: ${health.score}/100 (${health.grade}) — saved as ${resolvedTask}_before.json`);
-      } else {
-        console.log(`   🛡️  Pre-dispatch health snapshot: Dashboard not running — skipped`);
-      }
-    } catch { /* non-fatal — post-complete will handle missing snapshot */ }
-  }
-
-  // 5. 分發到 5 種陣型（各自獨立）
-  const launchers = {
-    unit:   formations.launchUnit,
-    solo:   formations.launchSolo,
-    squad:  formations.launchSquad,
-    legion: formations.launchLegion,
-    legacy: formations.launchLegacy,
-  };
-
-  const launcher = launchers[formation];
-  if (!launcher) {
-    console.error(`❌ Unknown formation: ${formation}`);
-    process.exit(1);
-  }
-
-  const restoreAdapterEnv = () => {
-    if (previousAdapter === undefined) {
-      delete process.env.BIFROST_ADAPTER;
-    } else {
-      process.env.BIFROST_ADAPTER = previousAdapter;
-    }
-  };
-
-  // Per-agent model override: if the task role or skill matches a known agent
-  // with a dashboard model override, use that instead of the global dispatchModel.
-  let effectiveDispatchModel = dispatchModel;
-  const agentModelKey =
-    (taskRole === 'heimdall' || skill === 'heimdall') ? 'heimdallModel' :
-    (taskRole === 'forseti' || skill === 'forseti') ? 'forsetiModel' :
-    (taskRole === 'huginn' || skill === 'huginn-think') ? 'huginnModel' :
-    null;
-  if (agentModelKey) {
-    const agentModel = resolveAgentModel(agentModelKey);
-    if (agentModel) effectiveDispatchModel = agentModel;
-  }
-
-  // Early dispatch registration: write entry BEFORE calling launcher() to eliminate the
-  // race window where a status check arrives between headless.js start and launchUnit()
-  // calling registerDispatch(). The entry is written with pid=null; formations.js will
-  // call registerDispatch() again with the real PID. The post-launch dedup block below
-  // merges these two entries into one authoritative record with the real PID so that
-  // zombie pruning can correctly detect process exit.
-  if (formation !== 'legacy' && skill !== 'huginn-think') {
-    try {
-      const logRoot = projectPath ? getLogDir(projectPath) : LOG_DIR;
-      const expectedLogDir = path.join(logRoot, formation || 'misc');
-      const expectedLogPath = path.join(expectedLogDir, `${skill}_${sessionId}.log`);
-      const list = readActiveDispatches();
-      if (!list.find(d => d.sessionId === sessionId)) {
-        list.push({
-          sessionId,
-          logPath: expectedLogPath,
-          logPathStatus: 'provisional',
-          taskId: resolvedTask || null,
-          formation,
-          startedAt: new Date().toISOString(),
-          projectPath: projectPath || null,
-          originSessionId: originSessionId || null,
-          originTransport: originSessionId ? 'mcp' : null,
-          originNotificationMethod: originSessionId ? 'notifications/kenaz/dispatch_complete' : null,
-          pid: null,
-        });
-        writeActiveDispatches(list);
-        console.log(`   📡 Pre-registered dispatch: ${sessionId} (task=${resolvedTask || formation})`);
-      }
-    } catch { /* non-fatal — formations.launchUnit will register on its own */ }
-  }
-
-  const launchResult = launcher({ rawPrompt, skill, sessionId, skillDef, mode, concurrency, projectPath, taskId: resolvedTask, taskScopePaths, role: taskRole, rigor: taskRigor, skipPostComplete, skipTests, inProcess, worktreePath: _unitWorktreePath, countFile: _unitCountFile, countLock: _unitCountLock, originSessionId, dispatchModel: effectiveDispatchModel, mcpConfigExtra, allowedToolsOverride });
-  attachBifrostAdapterCleanup(launchResult, restoreAdapterEnv);
-
-  // Post-launch dedup: formations.js launchUnit() calls registerDispatch() with the real PID,
-  // but the early registration above already pushed an entry with pid=null. This creates
-  // two entries for the same sessionId. The first (pid=null) wins dispatch-status .find(),
-  // making zombie pruning unable to detect process exit — isRunning stays true for 60 minutes.
-  // Fix: merge all entries for this sessionId into one authoritative entry with the real PID.
-  if (launchResult && formation !== 'legacy' && skill !== 'huginn-think') {
-    try {
-      const realPid = launchResult?.pid || launchResult?.child?.pid || null;
-      const realLogPath = launchResult.logPath || null;
-      if (realPid) {
-        const allEntries = readActiveDispatches();
-        const mine = allEntries.filter(d => d.sessionId === sessionId);
-        if (mine.length > 1 || (mine.length === 1 && mine[0].pid === null)) {
-          const others = allEntries.filter(d => d.sessionId !== sessionId);
-          // Prefer the entry that already has a real pid; fall back to last entry.
-          const base = mine.find(d => d.pid !== null) || mine[mine.length - 1];
-          base.pid = realPid;
-          if (realLogPath) { base.logPath = realLogPath; delete base.logPathStatus; }
-          writeActiveDispatches([...others, base]);
-          if (mine.length > 1) {
-            console.log(`   🔄 Deduped ${mine.length} dispatch entries → 1 (pid=${realPid})`);
-          } else {
-            console.log(`   🔄 Updated pre-registered dispatch with real PID (pid=${realPid})`);
-          }
-        }
-      }
-    } catch { /* non-fatal — does not interrupt dispatch */ }
-  }
-
-  if (launchResult && typeof launchResult === 'object' && !Array.isArray(launchResult)) {
-    launchResult.adapter = adapterSelection.adapter;
-    // Mark log path as provisional: the .log file is created when the agent
-    // first writes output, not at launch time. Callers should not assume the
-    // file exists immediately after launch() returns.
-    if (launchResult.logPath && !('logPathStatus' in launchResult)) {
-      launchResult.logPathStatus = 'provisional';
-    }
-  }
-
-  return launchResult;
-}
-
-function printDryRun(formation, rawPrompt, skillDef, skill) {
-  console.log(`--- DRY RUN ---\n`);
-
-  if (formation === 'legion') {
-    const legionPrompt = buildLegionLeadPrompt(rawPrompt);
-    console.log(`[Legion Lead Prompt]\n${legionPrompt}\n`);
-  } else if (formation === 'squad' && Array.isArray(rawPrompt)) {
-    const reportDir = `squad-${skill}`;
-    for (const m of rawPrompt) {
-      const prompt = m.prompt.replace(/\{session\}/g, reportDir);
-      console.log(`[Round 1 - Member: ${m.memberId}]\n${HEADLESS_PREFIX}${prompt}\n`);
-    }
-    if (skillDef.debate?.enabled) {
-      console.log(`--- Round 2: Debate ---\n`);
-      const debatePrompts = buildSquadDebatePrompts(skillDef, reportDir);
-      for (const m of debatePrompts) {
-        console.log(`[Round 2 - Member: ${m.memberId}]\n${HEADLESS_PREFIX}${m.prompt}\n`);
-      }
-    }
-    if (skillDef.merge) {
-      const synthPrompt = buildSquadSynthesisPrompt(skillDef, reportDir);
-      console.log(`[Synthesis Agent]\n${HEADLESS_PREFIX}${synthPrompt}\n`);
-    }
-  } else {
-    console.log(`${HEADLESS_PREFIX}${rawPrompt}`);
-  }
-
-  console.log(`--- END ---`);
-}
-
-// ─────────────────────────────────────────
-// CLI
-// ─────────────────────────────────────────
-
-if (require.main === module) {
-  const args = process.argv.slice(2);
-
-  if (args.includes('--help') || args.includes('-h')) {
-    console.log(`
-⚔️  Formation Headless Launcher
-
-無頭模式：Formation Lead 配好任務後直接呼叫，subagent 不問問題。
-
-Usage:
-  node .formation/tools/headless.js --formation=<type> --skill=<name> --task=<value>
-
-Options:
-  --formation <name>      陣型: unit (default), solo, squad, legion, legacy
-  --skill <name>          技能 (YAML filename without extension)
-  --task <value>          TASK_ID 或任務描述
-  --concurrency <n>       並行執行數（預設 3，上限 5，僅 legacy）
-  --project-path <p>      子專案路徑（任務從此專案查找）
-  --mode <name>           分析模式: optimization, innovation (squad only)
-  --dry-run               只印 prompt，不啟動進程
-  --skip-post-complete    跳過 post-complete（手動管理 archive/git/verify）
-  --skip-tests            跳過回歸測試 + acceptance 驗證（傳遞給 post-complete）
-  --depth <mode>          Specialist prompt depth: capsule (≤12KB) | kernel (default) | standard (full)
-  --bifrost-adapter <a>   Bifröst adapter override (e.g. openai) — route agent through relay
-
-Formation-Skill:
-  unit:    do, think, plan, heimdall, huginn-think
-  solo:    strategy, diagnosis
-  squad:   blitz, sweep
-  legion:  forge, hive
-  legacy:  scheduler (連續排程器)
-
-Huginn Think (special skill — no task required):
-  --trigger <type>        manual (default)
-  --focus <dim>           architecture | agent | knowledge (optional)
-  --query <topic>         directed thinking topic (optional)
-
-Logs: .formation/logs/{formation}/
-
-Examples:
-  node .formation/tools/headless.js --skill=do --task="修正按鈕顏色"
-  node .formation/tools/headless.js --formation=solo --skill=strategy --task="評估快取方案"
-  node .formation/tools/headless.js --formation=squad --skill=blitz --task=TASK_201
-  node .formation/tools/headless.js --formation=legion --skill=forge --task=TASK_202 --dry-run
-`);
-    process.exit(0);
-  }
-
-  const getArg = (flag) => {
-    for (let i = 0; i < args.length; i++) {
-      if (args[i].startsWith(`${flag}=`)) return args[i].split('=').slice(1).join('=');
-      if (args[i] === flag && args[i + 1]) return args[i + 1];
-    }
-    return null;
-  };
-
-  // TASK_1929 (Agent Hub M2): repeatable-flag variant of getArg — collects
-  // EVERY occurrence, not just the first. Used by --mcp-config-extra, which
-  // agent_hub/launch.rs's tokio::process::Command may pass more than once
-  // in a future multi-endpoint launch (today it passes at most one).
-  const getArgAll = (flag) => {
-    const out = [];
-    for (let i = 0; i < args.length; i++) {
-      if (args[i].startsWith(`${flag}=`)) out.push(args[i].split('=').slice(1).join('='));
-      else if (args[i] === flag && args[i + 1]) out.push(args[i + 1]);
-    }
-    return out;
-  };
-
-  const formation = getArg('--formation') || 'unit';
-  const skill = getArg('--skill');
-  const task = getArg('--task');
-  const dryRun = args.includes('--dry-run');
-  const mode = getArg('--mode');
-  const concurrency = getArg('--concurrency');
-  const projectPath = getArg('--project-path');
-  const originSessionId = getArg('--origin-session-id');
-  const depth = getArg('--depth');
-  // TASK_1774: Bifröst adapter override from the dispatch caller (e.g. dashboard
-  // kenaz_dispatch backend with dispatchFamily=bifrost/dispatchAdapter=openai).
-  // Threaded into launch() opts — resolveLaunchBifrostAdapter treats it as the
-  // highest-priority source (logged as source=dispatch).
-  const bifrostAdapter = getArg('--bifrost-adapter');
-  // TASK_1929 (Agent Hub M2): extra --mcp-config file(s) to register alongside
-  // the core .mcp.json (native claude path) / translate into codex `-c`
-  // overrides (bifrost/openai/relay.js) — see runner.js spawnClaude and
-  // relay.js buildCodexMcpOverrides. Empty array = zero behavior change.
-  const mcpConfigExtra = getArgAll('--mcp-config-extra');
-  // TASK_1929: full override of spawnClaude's default allowedTools list —
-  // used by agent_hub/launch.rs's `hub` skill launches to restrict a
-  // website-triggered agent to Read/Glob/Grep + the site's own MCP server,
-  // never the default Bash/Edit/Write/synapse_* toolkit. null = unchanged
-  // default (every other dispatch path never passes this flag).
-  const allowedToolsArg = getArg('--allowed-tools');
-  // Dashboard dispatch model override (Quick Actions → Default Models →
-  // Dispatch agent). Set by the kenaz_dispatch backend route after
-  // reading .kenaz/dashboard-models.json. Takes precedence over the
-  // legacy session-inheritance pattern in runner.js spawnClaude.
-  let dispatchModel = getArg('--dispatch-model');
-  // TASK_2249: ONE parsed object (first parseable file wins) feeds both dispatchModel
-  // and per-agent models — never mixed across project/core files.
-  const _dashboardModels = loadDashboardModels(projectPath);
-  if (dispatchModel === null && _dashboardModels
-      && Object.prototype.hasOwnProperty.call(_dashboardModels, 'dispatchModel')) {
-    dispatchModel = _dashboardModels.dispatchModel;
-  }
-
-  /**
-   * Resolve per-agent model from dashboard-models.json.
-   * Returns the agent-specific model if set (non-empty string), else null.
-   * @param {string} agentKey - e.g. 'huginnModel', 'forsetiModel', 'heimdallModel'
-   * @returns {string|null}
-   */
-  function resolveAgentModel(agentKey) {
-    const val = _dashboardModels?.[agentKey];
-    // Empty string = use agent built-in default (return null to not override)
-    return (typeof val === 'string' && val.length > 0) ? val : null;
-  }
-
-  const skipPostComplete = args.includes('--skip-post-complete');
-  const skipTests = args.includes('--skip-tests');
-  const force = args.includes('--force');
-
-  // Huginn Think args
-  const trigger = getArg('--trigger');
-  const focus = getArg('--focus');
-  const query = getArg('--query');
-  // ─────────────────────────────────────────
-  // Ansuz Wake / Sleep (Continuous Ansuz Daemon — TASK_900)
-  // Spawned by Tauri lib.rs on Dashboard start/close.
-  // ─────────────────────────────────────────
-  const ansuzWake  = args.includes('--ansuz-wake');
-  const ansuzSleep = args.includes('--ansuz-sleep');
-
-  if (ansuzWake || ansuzSleep) {
-    const effectiveProjectPath = projectPath || ROOT;
-    const pidFile = path.join(effectiveProjectPath, '.kenaz', 'specialist', 'ansuz_pid.txt');
-
-    if (ansuzSleep) {
-      if (fs.existsSync(pidFile)) {
-        const existingPid = parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10);
-        if (existingPid && isProcessAlive(existingPid)) {
-          try {
-            if (process.platform === 'win32') {
-              require('child_process').execSync(
-                `taskkill /T /F /PID ${existingPid}`,
-                { stdio: 'ignore', timeout: 10000, windowsHide: true }
-              );
-            } else {
-              process.kill(existingPid, 'SIGTERM');
-            }
-            console.log(`[Ansuz sleep] Terminated session (PID: ${existingPid})`);
-          } catch (e) {
-            console.error(`[Ansuz sleep] Kill failed: ${e.message}`);
-          }
-        } else {
-          console.log('[Ansuz sleep] PID in file is stale — clearing');
-        }
-        try { fs.unlinkSync(pidFile); } catch {}
-      } else {
-        console.log('[Ansuz sleep] No active session');
-      }
-      process.exit(0);
-    }
-
-    // Wake: delegate to ansuz-sdk-runner.js (TASK_912 — multi-turn SDK mode)
-    // Spawn as detached process to escape Windows Job Object
-    (async () => {
-      const { spawn: nodeSpawn } = require('child_process');
-      // SDK runner lives in KenazAI core (ROOT), not in the selected project
-      const sdkRunner = path.join(ROOT, '.specialist', 'Ansuz', 'tools', 'ansuz-sdk-runner.js');
-
-      // Zombie guard
-      if (fs.existsSync(pidFile)) {
-        try {
-          const existingPid = parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10);
-          if (existingPid && isProcessAlive(existingPid)) {
-            console.log(`[Ansuz wake] SDK runner already alive (PID: ${existingPid}) — skipping`);
-            process.exit(0);
-          }
-        } catch { /* ignore */ }
-        try { fs.unlinkSync(pidFile); } catch {}
-      }
-
-      if (!fs.existsSync(sdkRunner)) {
-        console.error(`[Ansuz wake] SDK runner not found: ${sdkRunner}`);
-        process.exit(1);
-      }
-
-      const nodeExe = process.execPath;
-      const httpPort = process.env.KENAZ_HTTP_PORT || '18080';
-      let child, spawnedPid;
-
-      if (process.platform === 'win32') {
-        // PowerShell Start-Process escapes Node.js Job Object on Windows
-        const ps1File = path.join(require('os').tmpdir(), `ansuz_sdk_wake_${Date.now()}.ps1`);
-        const ps1Content = [
-          `$env:KENAZ_HTTP_PORT = '${httpPort}'`,
-          `Start-Process -FilePath '${nodeExe.replace(/'/g, "''")}' -ArgumentList '"${sdkRunner.replace(/"/g, '\\"')}"','--project-path=${effectiveProjectPath.replace(/'/g, "''")}' -WindowStyle Hidden`,
-          `Remove-Item '${ps1File.replace(/'/g, "''")}' -ErrorAction SilentlyContinue`,
-        ].join('\n');
-        fs.writeFileSync(ps1File, ps1Content, 'utf8');
-        child = nodeSpawn('powershell.exe', ['-WindowStyle', 'Hidden', '-NonInteractive', '-File', ps1File], {
-          detached: true, stdio: 'ignore', windowsHide: true,
-        });
-        child.unref();
-        spawnedPid = child.pid;
-      } else {
-        child = nodeSpawn(nodeExe, [sdkRunner, `--project-path=${effectiveProjectPath}`], {
-          detached: true, stdio: 'ignore', cwd: effectiveProjectPath,
-          env: { ...process.env, KENAZ_HTTP_PORT: httpPort },
-        });
-        child.unref();
-        spawnedPid = child.pid;
-      }
-
-      fs.mkdirSync(path.dirname(pidFile), { recursive: true });
-      fs.writeFileSync(pidFile, String(spawnedPid));
-      console.log(`[Ansuz wake] SDK runner started (PID: ${spawnedPid})`);
-      process.exit(0);
-    })().catch(e => {
-      console.error(`[Ansuz wake] Unexpected error: ${e.message}`);
-      process.exit(1);
-    });
-    return;
-  }
-
-  if (!skill) { console.error('❌ --skill is required'); process.exit(1); }
-
-  const opts = { formation, skill, task, dryRun, mode, projectPath, skipPostComplete, skipTests, force, trigger, focus, query, originSessionId, depth, dispatchModel, bifrostAdapter };
-  if (concurrency != null) opts.concurrency = parseInt(concurrency, 10);
-  // TASK_1929: only set when actually provided — omitting the key (rather
-  // than passing an empty array / null) keeps every pre-existing dispatch's
-  // opts object byte-identical to before this task.
-  if (mcpConfigExtra.length > 0) opts.mcpConfigExtra = mcpConfigExtra;
-  if (allowedToolsArg) opts.allowedToolsOverride = allowedToolsArg;
-
-  launch(opts);
-}
-
-module.exports = { launch, recoverStaleDispatchBranch };