kenaz 0.3.3 → 0.3.6

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

@@ -2,14 +2,12 @@
 /**
  * Formation Dispatch — CLI 入口
  *
- * 根據陣型調度 subagent 執行任務。
- * 實際邏輯分散在各模組：loader, prompt, runner, logger, utils。
+ * Sub-agent dispatch: prints the JSON payload (promptText + agentParams) the
+ * Agent tool (or Codex spawn_agent) consumes. The only live dispatch path.
  *
  * Usage:
- *   node .formation/tools/dispatch.js --skill=do --task=TASK_172
- *   node .formation/tools/dispatch.js --formation=solo --skill=strategy --task=TASK_172
- *   node .formation/tools/dispatch.js --formation=squad --skill=blitz --task=TASK_173
- *   node .formation/tools/dispatch.js --formation=legion --skill=forge --task=TASK_174 --dry-run
+ *   node .formation/tools/dispatch.js --skill=do --task=TASK_172 --dispatch-mode=subagent
+ *   node .formation/tools/dispatch.js --skill=do --task=TASK_172 --dispatch-mode=subagent --harness=codex
  */
 
 const path = require('path');
@@ -21,14 +19,12 @@ const {
   promptProfile, extractRigor, extractComplexity, splitPromptSections,
   applyRustCheckToPrefix,
 } = require('./prompt');
-const { runSingle, runParallel } = require('./runner');
 const {
-  generateSessionId, ensureGitReady, ROOT, loadDashboardModels,
+  ROOT, loadDashboardModels,
   resolveWorktreeDecision, dispatchLockPath, tryAcquireDispatchLock, dispatchLockStaleness,
   createWorktree, ensureWorktreeDirIgnored, COLLABORATION_API,
   getVerifyOfflineCommand,
 } = require('./utils');
-const { refreshCache, hasRemoteConflict, hasRemoteFileConflict, isCacheStale } = require('./remote-conflict');
 
 // TASK_1815: the Agent tool's `model` parameter accepts ONLY these Claude
 // family names — no versions, no [1m] speed modifiers, no full model ids.
@@ -448,66 +444,9 @@ function samePath(a, b) {
 }
 
 // ─────────────────────────────────────────
-// Yggdrasil 廣播（lazy load, fire-and-forget）
+// Isolation routing
 // ─────────────────────────────────────────
 
-let _supabaseClient = null;
-let _taskSync = null;
-let _commitSync = null;
-function getSupabaseClient(projectPath) {
-  if (_supabaseClient === undefined) return null;
-  if (!_supabaseClient) try { _supabaseClient = require('./supabase-client'); } catch { _supabaseClient = undefined; return null; }
-  return _supabaseClient.getClient(projectPath);
-}
-function getTaskSync() {
-  if (_taskSync === undefined) return null;
-  if (!_taskSync) try { _taskSync = require('./task-sync'); } catch { _taskSync = undefined; return null; }
-  return _taskSync;
-}
-function getCommitSync() {
-  if (_commitSync === undefined) return null;
-  if (!_commitSync) try { _commitSync = require('./commit-sync'); } catch { _commitSync = undefined; return null; }
-  return _commitSync;
-}
-
-/**
- * 同步 commit 到 kenaz_commits。
- * 回傳 Promise（await 時確保完成，或 fire-and-forget）。
- */
-function syncCommit(taskId, projectPath) {
-  try {
-    const cs = getCommitSync();
-    if (!cs) return Promise.resolve();
-    return cs.syncLatestCommit({ taskId, projectPath }).catch(() => {});
-  } catch { return Promise.resolve(); }
-}
-
-/**
- * 廣播 kenaz_status。
- * 回傳 Promise — caller 可 await 確保完成（cleanup 場景），
- * 或 fire-and-forget（上線廣播場景）。
- */
-function broadcastStatus(projectPath, updates) {
-  try {
-    const sb = getSupabaseClient(projectPath);
-    if (!sb) return Promise.resolve();
-    const { client, config } = sb;
-    const ts = getTaskSync();
-    const project = ts?.resolveProjectName?.(projectPath || ROOT) || path.basename(ROOT);
-    return client.from('kenaz_status').upsert({
-      node_name: config.node_name,
-      project,
-      ...updates,
-    }, { onConflict: 'node_name,project' }).then(() => {}).catch(() => {});
-  } catch { return Promise.resolve(); }
-}
-
-// ─────────────────────────────────────────
-// Active dispatch registry（Dashboard Agent Monitor 用）
-// ─────────────────────────────────────────
-
-const ACTIVE_DISPATCH_FILE = path.join(ROOT, '.formation', '.active-dispatches.json');
-
 /**
  * TASK_1833: THE single isolation-routing decision for a dispatch. Consumed by
  * the real sub-agent path — do not copy the check:
@@ -566,59 +505,6 @@ function resolveDispatchIsolation({ projectPath = null, useWorktreeOverride = nu
   };
 }
 
-function readActiveDispatches() {
-  try {
-    if (fs.existsSync(ACTIVE_DISPATCH_FILE)) {
-      return JSON.parse(fs.readFileSync(ACTIVE_DISPATCH_FILE, 'utf-8'));
-    }
-  } catch { /* corrupted file */ }
-  return [];
-}
-
-function writeActiveDispatches(list) {
-  try {
-    fs.writeFileSync(ACTIVE_DISPATCH_FILE, JSON.stringify(list, null, 2));
-  } catch { /* ignore */ }
-}
-
-function registerDispatch({ sessionId, logPath, taskId, formation, projectPath: pp }) {
-  const list = readActiveDispatches();
-  const nextEntry = {
-    sessionId,
-    logPath,
-    taskId,
-    formation,
-    startedAt: new Date().toISOString(),
-    projectPath: pp || null,
-  };
-  const existingIndex = list.findIndex(d => d.sessionId === sessionId);
-  if (existingIndex >= 0) {
-    const mergedEntry = {
-      ...list[existingIndex],
-      startedAt: list[existingIndex].startedAt || nextEntry.startedAt,
-    };
-    for (const [key, value] of Object.entries(nextEntry)) {
-      if (key === 'startedAt') continue;
-      if (value !== null && value !== undefined) {
-        mergedEntry[key] = value;
-      }
-    }
-    list[existingIndex] = mergedEntry;
-  } else {
-    list.push(nextEntry);
-  }
-  writeActiveDispatches(list);
-}
-
-function unregisterDispatch(sessionId) {
-  const list = readActiveDispatches().filter(d => d.sessionId !== sessionId);
-  if (list.length === 0) {
-    try { fs.unlinkSync(ACTIVE_DISPATCH_FILE); } catch { /* ignore */ }
-  } else {
-    writeActiveDispatches(list);
-  }
-}
-
 // ─────────────────────────────────────────
 // Cortex Context 注入（dispatch 前自動注入相關檔案摘要）
 // ─────────────────────────────────────────
@@ -837,385 +723,6 @@ function checkDependencies(taskData, projectPath) {
   const unmet = deps.filter(dep => !completedIds.has(dep));
   return { blocked: unmet.length > 0, unmet, blockedDeps };
 }
-
-// ─────────────────────────────────────────
-// 調度主函數
-// ─────────────────────────────────────────
-
-async function dispatch(options) {
-  const {
-    formation = 'unit',
-    skill = 'do',
-    task,
-    output = null,
-    dryRun = false,
-    projectPath = null
-  } = options;
-
-  const sessionId = generateSessionId();
-
-  // 1. 載入技能定義
-  const skillDef = loadSkill(formation, skill);
-
-  // 2. 載入任務（如果是 TASK_ID，支援 projectPath）
-  const loadOpts = projectPath ? { projectPath } : undefined;
-  const taskData = task && task.startsWith('TASK_') ? loadTask(task, loadOpts) : null;
-  const taskInput = task || '';
-
-  // 2.5 依賴預檢：確認所有依賴都已完成
-  if (taskData) {
-    const depCheck = checkDependencies(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`);
-          continue;
-        }
-        console.error(`   ⛔ ${dep} — not in done/completed`);
-      }
-      console.error(`   → Complete the dependencies first, or use --force to override`);
-      if (!options.force) {
-        process.exitCode = 1;
-        return null;
-      }
-      console.warn(`   ⚠️  --force: dispatching despite unmet dependencies`);
-    }
-  }
-
-  // 3. 組裝 prompt（注入 projectPath context + Yggdrasil network context）
-  const promptOptions = {};
-  if (projectPath) {
-    promptOptions.projectPath = projectPath;
-  }
-  if (taskInput && taskInput.startsWith('TASK_')) {
-    promptOptions.taskId = taskInput;
-  }
-
-  // Yggdrasil: 查詢遠端節點狀態，注入 prompt 讓 Agent 知道其他人在做什麼
-  const taskScopePaths = (() => {
-    try {
-      if (!taskData) return [];
-      const parsed = JSON.parse(taskData);
-      return parsed.scope_paths || [];
-    } catch { return []; }
-  })();
-  try {
-    const ts = getTaskSync();
-    if (ts) {
-      const [onlineNodes, remoteTasks] = await Promise.all([
-        ts.getOnlineNodes(projectPath).catch(() => []),
-        ts.getRemoteActiveTasks(projectPath).catch(() => []),
-      ]);
-      if (onlineNodes.length > 0 || remoteTasks.length > 0) {
-        const sb = getSupabaseClient(projectPath);
-        promptOptions.yggdrasilContext = {
-          onlineNodes,
-          remoteTasks,
-          myNodeName: sb?.config?.node_name || 'unknown',
-          myScopePaths: taskScopePaths,
-        };
-      }
-    }
-  } catch { /* Yggdrasil context is best-effort */ }
-
-  let prompt = buildPrompt(skillDef, taskInput, taskData, promptOptions);
-
-  // 3.5 Cortex Context 注入：將 scope_paths 相關檔案摘要注入 prompt
-  // TASK_1998: "Related Files Preview" is CONTEXT volume, driven by
-  // complexity — simple/medium drop it entirely (it was 3.9 KB of mostly
-  // low-relevance file-head previews on the measured TASK_1992 prompt),
-  // complex keeps it.
-  const _dietProfile = promptProfile({ rigor: extractRigor(taskData), complexity: extractComplexity(taskData) });
-  if (typeof prompt === 'string' && taskScopePaths.length > 0 && !_dietProfile.skipRelatedFilesPreview) {
-    const cortexCtx = buildCortexContext(taskScopePaths, projectPath);
-    if (cortexCtx) {
-      prompt = prompt + '\n' + cortexCtx;
-    }
-  }
-
-  console.log(`⚔️  Formation Dispatch`);
-  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}`);
-
-  // 4. 確保子專案 git 已就緒（TASK_2274: dry-run 不得 git init — 只回報）
-  if (dryRun) {
-    if (projectPath && !fs.existsSync(path.join(projectPath, '.git'))) console.log('   [dry-run] would git init: ' + projectPath);
-  } else {
-    ensureGitReady(projectPath);
-  }
-
-  // 4.5 遠端衝突預檢（警告但不阻擋）
-  const scopePaths = taskData?.scope_paths || [];
-  if (scopePaths.length > 0) {
-    try {
-      if (isCacheStale()) {
-        await refreshCache(projectPath);
-      }
-      const taskConflict = hasRemoteConflict(scopePaths);
-      if (taskConflict.conflict) {
-        console.log(`\n   ⚠️  Remote conflict: ${taskConflict.conflictNode} is working on ${taskConflict.conflictTask}`);
-      }
-      const fileConflict = hasRemoteFileConflict(scopePaths);
-      if (fileConflict.conflict) {
-        console.log(`   ⚠️  Remote file conflict: ${fileConflict.conflictNode} is touching ${fileConflict.conflictFile}`);
-      }
-    } catch {
-      // 衝突檢查失敗不阻擋 dispatch
-    }
-  }
-
-
-  // M1 (TASK_1758): Dispatch-time scope gate + resource lease
-  {
-    const _sgRoot = projectPath || ROOT;
-    const _sgSession = _getProvenSessionId(_sgRoot); // TASK_2265: proven identity only
-    const _sgPaths = (() => { try { return taskData ? JSON.parse(taskData).scope_paths || [] : []; } catch { return []; } })();
-    const _sgResult = checkDispatchScopeGate(_sgPaths, _sgRoot, _sgSession, !!options.force, taskInput);
-    if (_sgResult.collisions.length > 0) {
-      for (const col of _sgResult.collisions) {
-        const pl = col.paths.slice(0,3).join(', ') + (col.paths.length > 3 ? ' +' + (col.paths.length-3) + ' more' : '');
-        if (_sgResult.blocked) {
-          console.error('   Scope conflict with stream ' + col.stream_label + ' (task ' + col.task_id + '): ' + pl);
-        } else {
-          console.warn('   WARNING scope conflict with stream ' + col.stream_label + ' (task ' + col.task_id + '): ' + pl);
-        }
-      }
-      if (_sgResult.blocked) {
-        console.error('Dispatch blocked: scope overlap with live stream(s). Use --force to override.');
-        process.exitCode = 1;
-        return null;
-      }
-    }
-    // TASK_1863: adopt our own claim marker (written by the chain's pre-claim /
-    // move→active) so a post-gate rejection below releases it — TASK_1833
-    // late-failure semantics extended from resource leases to the claim marker.
-    const _sgResources = (() => { try { return taskData ? JSON.parse(taskData).resources || [] : []; } catch { return []; } })();
-    // TASK_2274: dry-run takes no claim adoption / resource locks (mirrors the subagent path)
-    const _sgClaim = dryRun ? null : adoptSelfClaimMarker(taskInput, _sgRoot, _sgSession);
-    if (_sgResources.length > 0 && dryRun) {
-      console.log('   [dry-run] resource locks NOT acquired: ' + _sgResources.join(', '));
-    } else if (_sgResources.length > 0) {
-      const _sgLock = acquireResourceLocks(_sgResources, _sgRoot, _sgSession, taskInput);
-      if (_sgLock.failed.length > 0) {
-        for (const fail of _sgLock.failed) {
-          const hi = fail.holder ? ' (session=' + fail.holder.owner_session + ', task=' + fail.holder.task_id + ')' : '';
-          console.error((fail.orphan ? 'WARNING' : 'ERROR') + ': resource ' + fail.name + (fail.orphan ? ' ORPHAN lock' : ' busy') + hi);
-        }
-        releaseResourceLocks(_sgLock.acquired, _sgRoot);
-        if (!options.force) { releaseAdoptedClaimMarker(_sgClaim); console.error('Dispatch blocked: resource lock conflict. Use --force to override.'); process.exitCode = 1; return null; }
-        console.warn('WARNING: proceeding despite resource lock conflicts (--force).');
-      } else if (_sgLock.acquired.length > 0) {
-        console.log('   Resource locks acquired: ' + _sgLock.acquired.join(', '));
-        console.log('   (Release after merge: node .specialist/tools/stream-lease.js resource-release --name=<resource>)');
-      }
-    }
-  }
-
-  // 5. Dry run
-  if (dryRun) {
-    return handleDryRun(formation, prompt);
-  }
-
-  // 5.5 Yggdrasil: 廣播上線狀態
-  // Note: cleanup 由 child.on('close') 處理（await 確保完成）
-  // process.on('exit') 不支援 async，不適合做 Supabase cleanup
-  if (formation !== 'legion') {
-    broadcastStatus(projectPath, {
-      is_online: true,
-      current_task: taskInput || null,
-      touching_files: scopePaths || [],
-    });
-
-    // Yggdrasil: 同步任務狀態為 active
-    if (taskInput.startsWith('TASK_')) {
-      const ts = getTaskSync();
-      if (ts) {
-        const sb = getSupabaseClient(projectPath);
-        const myNode = sb?.config?.node_name || null;
-        ts.syncTaskStatus({
-          taskId: taskInput,
-          status: 'active',
-          claimedBy: myNode,
-          scopePaths: taskScopePaths,
-          projectPath,
-        }).catch(() => {});
-      }
-    }
-
-    // Signal handlers: 盡力 cleanup（best-effort，process 會等 promise）
-    const handleSignal = (code) => {
-      broadcastStatus(projectPath, { current_task: null, touching_files: [] })
-        .finally(() => process.exit(code));
-    };
-    process.on('SIGINT', () => handleSignal(130));
-    process.on('SIGTERM', () => handleSignal(143));
-  }
-
-  // 6. 根據陣型執行（傳入 projectPath + sessionId for registry）
-  return execute(formation, { prompt, skill, sessionId, output, projectPath, taskId: taskInput });
-}
-
-// ─────────────────────────────────────────
-// Dry Run
-// ─────────────────────────────────────────
-
-function handleDryRun(formation, prompt) {
-  if (formation === 'squad' && Array.isArray(prompt)) {
-    console.log(`\n--- SQUAD PROMPTS (${prompt.length} members) ---\n`);
-    for (const m of prompt) {
-      console.log(`=== Member: ${m.memberId} (skill: ${m.skill}) ===`);
-      console.log(m.prompt);
-      console.log('');
-    }
-    console.log(`--- END ---`);
-  } else if (formation === 'legion' && prompt.members) {
-    console.log(`\n--- LEGION CONFIG ---`);
-    console.log(`Team: ${prompt.teamName}`);
-    console.log(`Description: ${prompt.teamDesc}`);
-    console.log(`Members: ${prompt.members.length}`);
-    console.log(`\n--- LEAD PROMPT ---\n`);
-    console.log(prompt.lead.prompt);
-    console.log(`\n--- MEMBER PROMPTS ---\n`);
-    for (const m of prompt.members) {
-      console.log(`=== ${m.name} (${m.agentType}) ===`);
-      console.log(m.prompt);
-      console.log('');
-    }
-    console.log(`--- END ---`);
-  } else {
-    console.log(`\n--- PROMPT ---\n`);
-    console.log(prompt);
-    console.log(`\n--- END ---`);
-  }
-}
-
-// ─────────────────────────────────────────
-// 執行分發
-// ─────────────────────────────────────────
-
-function execute(formation, opts) {
-  const { prompt, skill, sessionId, output, projectPath, taskId } = opts;
-
-  switch (formation) {
-    case 'unit':
-    case 'solo': {
-      const child = runSingle({
-        prompt,
-        formation,
-        skill,
-        sessionId,
-        outputPath: output,
-        projectPath
-      });
-
-      // 註冊 dispatch（Dashboard Agent Monitor 用）
-      registerDispatch({ sessionId, logPath: child._formation?.logPath, taskId, formation, projectPath });
-
-      // Cleanup guard: 確保只執行一次，防止 close + formation:done 重複觸發
-      let cleanedUp = false;
-      const cleanup = (code) => {
-        if (cleanedUp) return;
-        cleanedUp = true;
-        unregisterDispatch(sessionId);
-        // Keep event loop alive with a timer so Supabase HTTP requests can complete
-        // before Node.js exits (child close leaves no other handles active)
-        const keepAlive = setTimeout(() => {}, 10000);
-
-        // Yggdrasil: 同步任務最終狀態到 kenaz_tasks
-        const syncFinalStatus = (() => {
-          if (!taskId || !taskId.startsWith('TASK_')) return Promise.resolve();
-          try {
-            const ts = getTaskSync();
-            if (!ts) return Promise.resolve();
-            return ts.syncTaskStatus({
-              taskId,
-              status: code === 0 ? 'done' : 'failed',
-              projectPath,
-            }).catch(() => {});
-          } catch { return Promise.resolve(); }
-        })();
-
-        Promise.allSettled([
-          broadcastStatus(projectPath, { current_task: null, touching_files: [] }),
-          code === 0 ? syncCommit(taskId, projectPath) : Promise.resolve(),
-          syncFinalStatus,
-        ]).then(() => {
-          clearTimeout(keepAlive);
-        });
-      };
-
-      child.on('close', cleanup);
-      // Fallback: formation:done fires when result is received, even if process lingers
-      child.on('formation:done', cleanup);
-
-      return child;
-    }
-
-    case 'squad': {
-      if (!Array.isArray(prompt)) {
-        throw new Error('Squad prompt builder should return an array of member prompts');
-      }
-
-      // Squad: 註冊整個 session
-      registerDispatch({ sessionId, logPath: null, taskId, formation: 'squad', projectPath });
-
-      const result = runParallel({
-        members: prompt,
-        formation,
-        sessionId,
-        projectPath
-      });
-
-      // runParallel returns a promise; await cleanup 確保完成
-      if (result && typeof result.then === 'function') {
-        const cleanup = (results) => {
-          unregisterDispatch(sessionId);
-
-          // Yggdrasil: 同步任務最終狀態（squad 以全員成功為準）
-          const syncFinalStatus = (() => {
-            if (!taskId || !taskId.startsWith('TASK_')) return Promise.resolve();
-            try {
-              const ts = getTaskSync();
-              if (!ts) return Promise.resolve();
-              const allSuccess = Array.isArray(results) && results.every(r => r.exitCode === 0);
-              return ts.syncTaskStatus({
-                taskId,
-                status: allSuccess ? 'done' : 'failed',
-                projectPath,
-              }).catch(() => {});
-            } catch { return Promise.resolve(); }
-          })();
-
-          return Promise.allSettled([
-            broadcastStatus(projectPath, { current_task: null, touching_files: [] }),
-            syncFinalStatus,
-          ]);
-        };
-        result.then(cleanup, () => cleanup(null));
-      }
-
-      return result;
-    }
-
-    case 'legion':
-      // Legion 不 spawn 進程，輸出 TeamCreate 配置供 Formation Lead 使用
-      console.log(`\n⚔️  Legion: TeamCreate configuration generated`);
-      console.log(`   Team: ${prompt.teamName}`);
-      console.log(`   Members: ${prompt.members.length}`);
-      console.log(`\n   Legion 不直接啟動進程。`);
-      console.log(`   請使用 TeamCreate API 搭配以上配置啟動團隊。`);
-      console.log(`   或使用 --dry-run 查看完整 prompt。`);
-      return prompt;
-
-    default:
-      throw new Error(`Unknown formation: ${formation}`);
-  }
-}
-
 // ─────────────────────────────────────────
 // CLI
 // ─────────────────────────────────────────
@@ -1228,22 +735,21 @@ if (require.main === module) {
 ⚔️  Formation Dispatch
 
 Usage:
-  node .formation/tools/dispatch.js --skill=<name> --task=<TASK_ID|description>
+  node .formation/tools/dispatch.js --skill=<name> --task=<TASK_ID|description> --dispatch-mode=subagent
 
 Options:
-  --formation <name>      Formation type: unit (default), solo, squad, legion
+  --formation <name>      Skill folder: unit (default) or solo
   --skill <name>          Skill to use (YAML filename without extension)
   --task <value>          Task ID (TASK_XXX) or free-text description
-  --concurrency <n>       Parallel execution slots (default 3, max 5, legacy only)
-  --output <path>         Custom log output path
-  --dry-run               Only print the prompt, don't launch
-  --prompt-only           Print raw prompt text to stdout (machine-readable, no headers)
-  --dispatch-mode <mode>  Output mode: formation (default), subagent (JSON params for Agent tool)
-  --dispatch-model <id>   TASK_1998 R3: subagent-path model override (wins over
+  --dry-run               Build and print the payload with no side effects
+  --dispatch-mode <mode>  Required: subagent (JSON params for the Agent tool)
+  --harness <name>        claude (default) | codex (Codex spawn_agent payload)
+  --project-path <path>   Target sub-project (omit for the core repo)
+  --dispatch-model <id>   TASK_1998 R3: model override (wins over
                           dashboard-models.json dispatchModelByRigor and the
                           default — the dashboard dispatchModel, used for
                           every rigor unless dispatchModelByRigor sets that
-                          rigor's entry). Only used with --dispatch-mode=subagent.
+                          rigor's entry).
   --use-worktree <bool>   TASK_1833: dispatch-time worktree toggle (true|false).
                           Overrides env FORMATION_USE_WORKTREE and the target
                           project's .kenaz/project.yaml use_worktree. For
@@ -1262,25 +768,12 @@ Options:
                           (with --release-lock: release a lock this session
                           cannot prove it owns)
 
-Formation-Skill Quick Reference:
-  unit:    do, think, plan
-  solo:    strategy, diagnosis
-  squad:   blitz, sweep
-  legion:  forge, hive
+Skills: unit: do, think, plan; solo: strategy, diagnosis.
 
 Sub-agent dispatch (Ansuz billing-aware path):
   node .formation/tools/dispatch.js --skill=do --task=TASK_172 --dispatch-mode=subagent
   → prints JSON: { promptText, taskId, agentParams: { model, isolation, description } }
   Ansuz passes promptText to Agent tool with agentParams for worktree-isolated execution.
-
-Headless Mode (recommended for long tasks):
-  node .formation/tools/headless.js --formation=legion --skill=forge --task=TASK_174
-
-Examples:
-  node .formation/tools/dispatch.js --skill=do --task=TASK_172
-  node .formation/tools/dispatch.js --formation=solo --skill=strategy --task="評估新功能"
-  node .formation/tools/dispatch.js --formation=squad --skill=blitz --task=TASK_173
-  node .formation/tools/dispatch.js --formation=legion --skill=forge --task=TASK_174 --dry-run
 `);
     process.exit(0);
   }
@@ -1300,10 +793,8 @@ Examples:
   const formation = getArg('--formation') || 'unit';
   const skill = getArg('--skill');
   const task = getArg('--task');
-  const output = getArg('--output');
   const projectPath = getArg('--project-path');
   const dryRun = args.includes('--dry-run');
-  const promptOnly = args.includes('--prompt-only');
   const dispatchModeCli = getArg('--dispatch-mode');
   // TASK_1998 R3: subagent-path model override — wins over dashboard
   // dispatchModelByRigor and the dashboard dispatchModel default. Accepts
@@ -1370,30 +861,18 @@ Examples:
     process.exit(1);
   }
 
-  // Sub-agent mode: output JSON params for Agent tool consumption
-  if (dispatchModeCli === 'subagent') {
-    getSubagentDispatchParams({ formation, skill, task, projectPath, force, useWorktree: useWorktreeCli, dispatchModelOverride: dispatchModelCli, dryRun, harness: harnessCli }).then(result => {
-      if (!result) { process.exitCode = 1; return; }
-      process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-    });
-    return;
-  }
-
-  // Prompt-only mode: output raw prompt to stdout (machine-readable, no decorations)
-  if (promptOnly) {
-    const skillDef = loadSkill(formation, skill);
-    const loadOpts = projectPath ? { projectPath } : undefined;
-    const taskData = task && task.startsWith('TASK_') ? loadTask(task, loadOpts) : null;
-    const promptOptions = {};
-    if (projectPath) promptOptions.projectPath = projectPath;
-    if (task && task.startsWith('TASK_')) promptOptions.taskId = task;
-    const rawPrompt = buildPrompt(skillDef, task, taskData, promptOptions);
-    const text = typeof rawPrompt === 'string' ? rawPrompt : JSON.stringify(rawPrompt);
-    process.stdout.write(text + '\n');
-    return;
+  // Sub-agent mode (the only dispatch path): output JSON params for Agent tool consumption
+  if (dispatchModeCli !== 'subagent') {
+    console.error('❌ --dispatch-mode=subagent is required (Formation headless/squad/legion dispatch is retired)');
+    process.exit(1);
   }
-
-  dispatch({ formation, skill, task, output, dryRun, projectPath, force });
+  getSubagentDispatchParams({ formation, skill, task, projectPath, force, useWorktree: useWorktreeCli, dispatchModelOverride: dispatchModelCli, dryRun, harness: harnessCli }).then(result => {
+    if (!result) { process.exitCode = 1; return; }
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  }).catch(e => {
+    console.error('❌ ' + (e && e.message ? e.message : e));
+    process.exitCode = 1;
+  });
 }
 
 // ─────────────────────────────────────────
@@ -1511,14 +990,14 @@ async function getSubagentDispatchParams(options) {
   }
   if (routing.family === 'bifrost' && !isCodex) {
     if (!routing.adapter) {
-      console.error('❌ dashboard-models.json sets dispatchFamily=bifrost but dispatchAdapter is missing/empty — refusing to silently dispatch with the native Claude CLI. Fix the model selection (Quick Actions → Default Models) or dashboard-models.json, then use Formation dispatch (kenaz_dispatch).');
+      console.error('❌ dashboard-models.json sets dispatchFamily=bifrost but dispatchAdapter is missing/empty — refusing to silently dispatch with the native Claude CLI. Fix the model selection (Quick Actions → Default Models) or dashboard-models.json.');
     } else {
-      console.error(`❌ dashboard-models.json sets dispatchFamily=bifrost (dispatchAdapter '${routing.adapter}') — sub-agent dispatch cannot run non-Claude models (the Agent tool only accepts Claude models); refusing to silently dispatch with the native Claude CLI. Use Formation dispatch (kenaz_dispatch) instead — it routes through the Bifrost adapter.`);
+      console.error(`❌ dashboard-models.json sets dispatchFamily=bifrost (dispatchAdapter '${routing.adapter}') — sub-agent dispatch cannot run non-Claude models (the Agent tool only accepts Claude models); refusing to silently dispatch with the native Claude CLI. Select a Claude model in Default Models.`);
     }
     return null;
   }
   if (!isCodex && routing.family && routing.family !== 'claude') {
-    console.error(`❌ dashboard-models.json sets unsupported dispatchFamily '${routing.family}' (expected 'claude' or 'bifrost') — refusing to silently dispatch with the native Claude CLI. Fix the model selection (Quick Actions → Default Models) or use Formation dispatch (kenaz_dispatch).`);
+    console.error(`❌ dashboard-models.json sets unsupported dispatchFamily '${routing.family}' (expected 'claude' or 'bifrost') — refusing to silently dispatch with the native Claude CLI. Fix the model selection (Quick Actions → Default Models).`);
     return null;
   }
 
@@ -1538,7 +1017,7 @@ async function getSubagentDispatchParams(options) {
   // TASK_2315: Codex inherits the session model — nothing to translate or pass.
   const translated = isCodex ? { model: null, lossless: true } : translateModelForAgentTool(rawModel);
   if (!isCodex && !translated.model) {
-    console.error(`❌ ${resolution.label} '${rawModel}' cannot be mapped to an Agent tool model family (${AGENT_TOOL_MODEL_ENUM.join('|')}) — refusing to silently guess a substitute model. Fix the model selection (Quick Actions → Default Models) or use Formation dispatch (kenaz_dispatch), which accepts full model ids via --dispatch-model.`);
+    console.error(`❌ ${resolution.label} '${rawModel}' cannot be mapped to an Agent tool model family (${AGENT_TOOL_MODEL_ENUM.join('|')}) — refusing to silently guess a substitute model. Fix the model selection (Quick Actions → Default Models).`);
     return null;
   }
   const dispatchModel = translated.model;
@@ -1546,7 +1025,7 @@ async function getSubagentDispatchParams(options) {
     ? { requested: rawModel, inherited: true }
     : { requested: rawModel, agentToolModel: dispatchModel, granularityLoss: !translated.lossless };
   if (!translated.lossless) {
-    process.stderr.write(`[dispatch] model '${rawModel}' → Agent tool family '${dispatchModel}' — the Agent tool only expresses family names (${AGENT_TOOL_MODEL_ENUM.join('|')}); version/speed selections (e.g. 5 vs 4.x, [1m]) are NOT expressible on the subagent path. If the exact version matters, use Formation dispatch (kenaz_dispatch), which passes full model ids.\n`);
+    process.stderr.write(`[dispatch] model '${rawModel}' → Agent tool family '${dispatchModel}' — the Agent tool only expresses family names (${AGENT_TOOL_MODEL_ENUM.join('|')}); version/speed selections (e.g. 5 vs 4.x, [1m]) are NOT expressible on the subagent path. If the exact version matters, choose a model whose family the Agent tool can express.\n`);
   }
   // TASK_1998 R3 (+ two-axis policy): the resolved choice, always printed
   // (unlike the granularity block above, which only fires on lossy translation).
@@ -1705,7 +1184,7 @@ async function getSubagentDispatchParams(options) {
   // (same two-axis gate as the Formation-dispatch path above). `rigor` and
   // `complexity` were both extracted in step 1 (rigor needed earlier, for
   // model resolution).
-  const dietProfile = promptProfile({ rigor, complexity });
+  const dietProfile = promptProfile({ complexity });
   if (taskScopePaths.length > 0 && !dietProfile.skipRelatedFilesPreview) {
     const cortexCtx = buildCortexContext(taskScopePaths, projectPath);
     if (cortexCtx) promptText = promptText + '\n' + cortexCtx;
@@ -1928,4 +1407,4 @@ function setupSubagentCrossProjectWorktree(projectPath, taskInput) {
   };
 }
 
-module.exports = { dispatch, getSubagentDispatchParams, checkDispatchScopeGate, releaseDispatchLock, resolveDispatchIsolation, _getProvenSessionId, _getOwnConversationId, _isOwnClaimMarker, _buildCortexContext: buildCortexContext };
+module.exports = { getSubagentDispatchParams, checkDispatchScopeGate, releaseDispatchLock, resolveDispatchIsolation, _getProvenSessionId, _getOwnConversationId, _isOwnClaimMarker, _buildCortexContext: buildCortexContext };