kenaz 0.0.0-stage → 0.3.2

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

@@ -0,0 +1,1071 @@
+#!/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 };