kenaz 0.0.0-stage → 0.3.2

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

@@ -0,0 +1,1931 @@
+#!/usr/bin/env node
+/**
+ * Formation Dispatch — CLI 入口
+ *
+ * 根據陣型調度 subagent 執行任務。
+ * 實際邏輯分散在各模組：loader, prompt, runner, logger, utils。
+ *
+ * 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
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { execSync } = require('child_process');
+const { loadSkill, loadTask } = require('./loader');
+const {
+  buildPrompt, SUBAGENT_PREFIX, SUBAGENT_PREFIX_DIRECT, buildSubagentWorktreePrefix,
+  promptProfile, extractRigor, extractComplexity, splitPromptSections,
+  applyRustCheckToPrefix,
+} = require('./prompt');
+const { runSingle, runParallel } = require('./runner');
+const {
+  generateSessionId, ensureGitReady, 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.
+// Measured 2026-07-26 by a direct Agent tool probe from the main thread:
+// model="claude-fable-5" and model="gpt-5-codex" both raise the SAME
+// InputValidationError listing exactly this enum. This is a harness-side
+// constraint that may drift with Claude Code versions — keep the four values
+// in THIS single constant; if subagent dispatch starts failing with
+// InputValidationError on the model field, re-probe the Agent tool and update
+// here (nowhere else).
+// (Declared before the CLI entry point below — module-scope code calls
+// getSubagentDispatchParams during evaluation, so a later `const` would be in
+// its temporal dead zone at call time.)
+const AGENT_TOOL_MODEL_ENUM = ['sonnet', 'opus', 'haiku', 'fable'];
+
+/**
+ * TASK_1815: translate a dashboard-models.json dispatchModel string into the
+ * Agent tool model enum. Dashboard model ids carry versions and speed
+ * modifiers (claude-opus-5[1m], claude-sonnet-4-6, ...) that the Agent tool
+ * cannot express — the enum has FAMILY names only. So this translation is
+ * structurally LOSSY: claude-opus-5[1m] and claude-opus-4-8[1m] both become
+ * 'opus'. Callers must surface that loss, never treat it as equivalence.
+ * NOTE: dashboard/src/lib/models.ts `family` ('claude'|'bifrost') is the
+ * ADAPTER family and is unrelated to this Claude sub-family mapping.
+ * @param {string} rawModel - dashboard model id, possibly with [1m]-style suffix
+ * @returns {{ model: string|null, lossless: boolean }} model=null → unmappable
+ */
+function translateModelForAgentTool(rawModel) {
+  // Strip Formation-internal speed modifier suffixes like [1m]
+  const stripped = String(rawModel || '').replace(/\[.*?\]/g, '').trim();
+  if (AGENT_TOOL_MODEL_ENUM.includes(stripped)) {
+    // Already a bare family name — lossless only if there was no suffix to strip.
+    return { model: stripped, lossless: stripped === String(rawModel).trim() };
+  }
+  // claude-<family>[-version...] → <family>. Covers every NATIVE id in
+  // dashboard/src/lib/models.ts (claude-fable-5-1[1m], claude-opus-5-5[1m],
+  // claude-fable-5[1m], claude-opus-4-8[1m], claude-sonnet-5,
+  // claude-sonnet-4-6) plus future versions of the same families. 'haiku' has
+  // no dashboard source entry today but maps fine if one appears.
+  const m = stripped.match(/^claude-(opus|sonnet|haiku|fable)(?:-|$)/);
+  if (m) return { model: m[1], lossless: false };
+  return { model: null, lossless: false };
+}
+
+// TASK_1998 R3 (spec correction, user decision 2026-09-22 — supersedes an
+// earlier low→haiku/high→opus hard-coded policy that was implemented and then
+// reverted before merge): the model ALWAYS follows the Dashboard setting.
+// For every rigor the model is dashboard-models.json's `dispatchModel`,
+// exactly as before R3 — UNLESS that same file also carries an explicit
+// `dispatchModelByRigor: {low?, medium?, high?}` object (populated from the
+// Dashboard's own settings UI, not hand-edited), in which case the entry for
+// the card's rigor wins for that rigor only (missing keys fall back to
+// dispatchModel). `--dispatch-model` CLI keeps precedence over both. Every
+// source runs through the SAME translateModelForAgentTool below, and
+// TASK_1815's rule applies uniformly: an id that cannot be mapped to the
+// Agent tool enum exits 1 loudly — never a silent substitute.
+/**
+ * @param {object} p
+ * @param {string|null} p.rigor - card rigor ('low'|'medium'|'high'|null).
+ *   null/unrecognized normalizes to 'medium' — mirrors promptProfile()'s
+ *   treatment of missing/unrecognized rigor as the diet(medium) default.
+ * @param {object|null} p.models - parsed dashboard-models.json (routing.models)
+ * @param {string|null} p.cliDispatchModel - --dispatch-model CLI value, if any
+ * @returns {{ rawModel: string, source: 'cli'|'dashboard-by-rigor'|'dashboard', label: string, rigorKey: 'low'|'medium'|'high' }}
+ */
+function resolveDispatchModelForRigor({ rigor, models, cliDispatchModel }) {
+  const rigorKey = (rigor === 'low' || rigor === 'high') ? rigor : 'medium';
+  // 1. CLI flag wins over everything.
+  if (cliDispatchModel) {
+    return { rawModel: cliDispatchModel, source: 'cli', label: '--dispatch-model', rigorKey };
+  }
+  // 2. dashboard-models.json dispatchModelByRigor — only when the Dashboard
+  // has set an entry for THIS rigor; unset keys fall through to dispatchModel.
+  const byRigor = (models && typeof models.dispatchModelByRigor === 'object' && models.dispatchModelByRigor) || null;
+  const overrideRaw = byRigor && typeof byRigor[rigorKey] === 'string' ? byRigor[rigorKey].trim() : '';
+  if (overrideRaw) {
+    return { rawModel: overrideRaw, source: 'dashboard-by-rigor', label: `dashboard-models.json dispatchModelByRigor.${rigorKey}`, rigorKey };
+  }
+  // 3. Default for every rigor: the dashboard dispatchModel, unchanged fallback
+  // ('claude-sonnet-4-6', mirrors DEFAULT_DISPATCH_MODEL in dashboard/src/lib/models.ts).
+  const rawModel = (models && typeof models.dispatchModel === 'string' && models.dispatchModel) || 'claude-sonnet-4-6';
+  return { rawModel, source: 'dashboard', label: 'dashboard-models.json dispatchModel', rigorKey };
+}
+
+// ─────────────────────────────────────────
+// -----------------------------------------
+// M1 (TASK_1758): Dispatch-time scope gate + resource lease
+// Spec: dev/MULTI_ANSUZ_SPEC.md §2.3 + §2.5
+// -----------------------------------------
+
+function normalizeScopePath(p_) {
+  if (!p_) return '';
+  let s = String(p_).split(String.fromCharCode(92)).join("/").trim();
+  if (process.platform === 'win32') s = s.toLowerCase();
+  return s;
+}
+
+function pathsCollide(a, b) {
+  const na = normalizeScopePath(a);
+  const nb = normalizeScopePath(b);
+  if (!na || !nb) return false;
+  if (na === nb) return true;
+  const naSlash = na.endsWith('/') ? na : na + '/';
+  const nbSlash = nb.endsWith('/') ? nb : nb + '/';
+  if (nb.startsWith(naSlash)) return true;
+  if (na.startsWith(nbSlash)) return true;
+  return false;
+}
+
+function _dispPidAlive(pid) {
+  if (!pid || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (e) { if (e.code === 'EPERM') return true; return false; }
+}
+
+// TASK_2263: identity + provenance. source 'hmap' = resolved via this process's own
+// CLAUDE_CODE_SESSION_ID (provable); 'current_stream' = the singleton file that may
+// name ANOTHER live session (unprovable, best-effort label only).
+function _getOwnSessionId(projectRoot) { return _resolveOwnSession(projectRoot).id; }
+
+// TASK_2265: id usable as "self" for filtering OTHER sessions' leases/claims and as an
+// authoritative owner in written records. Only hmap-proven identity qualifies; the
+// current_stream singleton may name a foreign live session, so it yields null (callers
+// fail closed: nothing is treated as self, writers fall back to the 'unknown' sentinel).
+function _getProvenSessionId(projectRoot) {
+  var o = _resolveOwnSession(projectRoot);
+  return o.source === 'hmap' ? o.id : null;
+}
+
+function _resolveOwnSession(projectRoot) {
+  // TASK_1764 AMEND: use CLAUDE_CODE_SESSION_ID (= conversation UUID, stable across compact/resume).
+  // CLAUDE_SESSION_ID does not exist; CLAUDE_CODE_SESSION_ID is the correct env variable.
+  // hmap key is now convId (transcript_path basename = conversation id), consistent with hooks.
+  try {
+    var sessId = process.env.CLAUDE_CODE_SESSION_ID;
+    if (sessId) {
+      var hmapF = require('path').join(projectRoot, '.kenaz', 'specialist', 'sessions', 'hmap_' + sessId + '.json');
+      try {
+        var hmap = JSON.parse(require('fs').readFileSync(hmapF, 'utf8'));
+        if (hmap && hmap.boot_sid) return { id: hmap.boot_sid, source: 'hmap' };
+      } catch (_e2) {}
+    }
+    // Fallback: current_stream.json (solo session, headless, or hmap not yet written)
+    var sf = require('path').join(projectRoot, '.kenaz', 'specialist', 'current_stream.json');
+    var parsed = JSON.parse(require('fs').readFileSync(sf, 'utf8'));
+    var fid = (parsed && parsed.session_id) || null;
+    return { id: fid, source: fid ? 'current_stream' : null };
+  } catch (_e) { return { id: null, source: null }; }
+}
+
+// TASK_1863: own conversation id — the STABLE self-identity anchor (TASK_1764;
+// ash rune_cfc898ca: session ids rotate/alias, conversation id does not).
+// Env CLAUDE_CODE_SESSION_ID (= transcript basename, stable across compact/resume)
+// only (TASK_2281: the current_stream.json conversation_id is NOT trusted — singleton).
+function _getOwnConversationId(projectRoot) {
+  try {
+    var envId = process.env.CLAUDE_CODE_SESSION_ID;
+    // TASK_2281: no current_stream fallback — the singleton may name another live
+    // conversation; unproven identity fails closed (null = no marker is "ours").
+    return envId || null;
+  } catch (_e) { return null; }
+}
+
+// TASK_1787/2281: is this claim marker ours? Anchor: owner_conversation_id; fallback
+// owner_session when the marker has no conv id; never owner_pid. (headless auto-claim guard)
+function _isOwnClaimMarker(marker, projectRoot) {
+  // TASK_2281: proven identity only (env conv id / hmap). The current_stream.json singleton
+  // may name another live session -> unproven -> never "ours" (fail closed).
+  if (!marker) return false;
+  if (marker.owner_conversation_id) {
+    var conv = _getOwnConversationId(projectRoot);
+    return !!conv && marker.owner_conversation_id === conv;
+  }
+  var sid = _getProvenSessionId(projectRoot);
+  return !!sid && !!marker.owner_session && marker.owner_session === sid;
+}
+
+// TASK_1863: late-failure claim rollback — the same guarantee TASK_1833 gave
+// resource leases. dispatch.js does not WRITE claim markers (task-api does, on
+// the chain's pre-claim / move→active), but a dispatch that fails AFTER the
+// scope gate must not leave that marker behind: the leaked marker blocks the
+// same conversation's retry when its owner_session is a live alias (measured
+// 2026-08-13: claim_TASK_1861 owned by ghost stream-D blocked the retry with
+// '<same-task>' until hand-deleted), and blocks every other session for the
+// full 8h liveness window if this session dies. Adoption is strictly
+// self-scoped: only a marker provably owned by this session OR this
+// conversation is ever released. Foreign markers are never touched — orphan
+// arbitration stays in task-api (never auto-steal, rune_0378754d).
+function adoptSelfClaimMarker(taskId, projectRoot, ownSessionId) {
+  const adoption = { markerPath: null, adopted: false };
+  if (!taskId || !/^TASK_/.test(taskId)) return adoption;
+  adoption.markerPath = require('path').join(projectRoot, '.kenaz', 'locks', 'claim_' + taskId + '.json');
+  let mk = null;
+  try { mk = JSON.parse(require('fs').readFileSync(adoption.markerPath, 'utf8')); } catch (_e) { return adoption; }
+  if (!mk) return adoption;
+  const ownConvId = _getOwnConversationId(projectRoot);
+  adoption.adopted =
+    (!!ownSessionId && mk.owner_session === ownSessionId) ||
+    (!!ownConvId && mk.owner_conversation_id === ownConvId);
+  return adoption;
+}
+
+function releaseAdoptedClaimMarker(adoption) {
+  if (!adoption || !adoption.adopted || !adoption.markerPath) return;
+  try { require('fs').unlinkSync(adoption.markerPath); } catch (_e) { /* already gone */ }
+}
+
+/**
+ * TASK_1859: explicit release for the serial dispatch lock (utils.dispatchLockPath).
+ * The previous release contract was "delete the lock file" — structurally
+ * unexecutable in orchestrator environments that deny Bash(rm *) (deny wins
+ * over every allow), leaving 60min staleness as the only exit. This gives the
+ * lock a first-class release interface: `--release-lock` on this CLI.
+ *
+ * Ownership rule (never silent): a release without --force requires PROVABLE
+ * same-session ownership — both the holder's sessionId and our own resolved
+ * session must exist, neither may be the 'unknown' sentinel (locks are written
+ * with sessionId `_getOwnSessionId(ROOT) || 'unknown'`), and they must match.
+ * Any unprovable case (holder corrupt, holder sessionId missing/'unknown',
+ * own session unresolvable) REFUSES and requires --force — an 'unknown' holder
+ * is exactly the case where we cannot know whose live agent we would unlock.
+ *
+ * Deliberately NOT pid-based: pid:null is the designed holder shape (the
+ * dispatch CLI exits right after emitting params — its pid proves nothing
+ * about the agent's liveness). Staleness info comes from the single authority
+ * utils.dispatchLockStaleness and is surfaced for the operator, but this
+ * function never auto-releases on staleness — the next tryAcquireDispatchLock
+ * already breaks stale locks; release stays an explicit human/orchestrator act.
+ *
+ * @param {object} [opts]
+ * @param {string|null} [opts.projectPath] - target project (lock key), null = core
+ * @param {boolean} [opts.force] - allow releasing a lock we cannot prove we own
+ * @param {string|null} [opts.ownSessionId] - test injection point ONLY; when the
+ *   key is absent the real _getOwnSessionId(ROOT) is used (same source as the
+ *   lock writer). Explicit null models "own session resolution failed".
+ * @returns {{ released: boolean, existed: boolean, lockFile: string,
+ *   holder: object|null, staleness: object|null, ownSessionId: string|null,
+ *   reason: string }}
+ */
+function releaseDispatchLock(opts = {}) {
+  const { projectPath = null, force = false } = opts;
+  const lockFile = dispatchLockPath(projectPath);
+  // TASK_2263: an identity from the singleton current_stream.json fallback can name
+  // another live session, so it is not ownership proof (injected ids count as proven).
+  const _own = ('ownSessionId' in opts) ? { id: opts.ownSessionId, source: 'injected' } : _resolveOwnSession(ROOT);
+  const ownSessionId = _own.id;
+  let raw = null;
+  try { raw = fs.readFileSync(lockFile, 'utf8'); }
+  catch (e) {
+    if (e.code === 'ENOENT') {
+      return { released: false, existed: false, lockFile, holder: null, staleness: null, ownSessionId, reason: 'not-held' };
+    }
+    return { released: false, existed: true, lockFile, holder: null, staleness: null, ownSessionId, reason: 'read-error: ' + e.message };
+  }
+  let holder = null;
+  try { holder = JSON.parse(raw); } catch { /* corrupt — unprovable ownership below */ }
+  const staleness = dispatchLockStaleness(holder);
+  const holderSession = holder && typeof holder.sessionId === 'string' && holder.sessionId.trim() ? holder.sessionId.trim() : null;
+  // Defined-behavior ladder for unprovable ownership (acceptance: never silent):
+  let refusal = null;
+  if (!holder) refusal = 'holder-unreadable';
+  else if (!holderSession || holderSession === 'unknown') refusal = 'holder-session-unknown';
+  else if (!ownSessionId) refusal = 'own-session-unresolved';
+  else if (holderSession !== ownSessionId) refusal = 'session-mismatch';
+  else if (_own.source === 'current_stream') refusal = 'own-session-unproven';
+  if (refusal && !force) {
+    return { released: false, existed: true, lockFile, holder, staleness, ownSessionId, reason: refusal };
+  }
+  try { fs.unlinkSync(lockFile); }
+  catch (e) {
+    if (e.code === 'ENOENT') {
+      // Racing releaser/breaker got there first — the desired end state holds.
+      return { released: false, existed: false, lockFile, holder, staleness, ownSessionId, reason: 'not-held' };
+    }
+    return { released: false, existed: true, lockFile, holder, staleness, ownSessionId, reason: 'unlink-failed: ' + e.message };
+  }
+  return { released: true, existed: true, lockFile, holder, staleness, ownSessionId, reason: refusal ? 'forced (' + refusal + ')' : 'own-session' };
+}
+
+function checkDispatchScopeGate(targetScopePaths, projectRoot, currentSessionId, force, targetTaskId) {
+  targetScopePaths = targetScopePaths || [];
+  // TASK_1767: empty scope_paths must not bypass the TASK_1764 same-task-id guard --
+  // early-return only when there is neither scope to compare nor a target task id.
+  if (targetScopePaths.length === 0 && !targetTaskId) return { blocked: false, collisions: [] };
+  let readAllLeases, isPidAlive, isSessionLive;
+  try {
+    const sl = require(require('path').join(projectRoot, '.specialist', 'tools', 'stream-lease.js'));
+    readAllLeases = sl.readAllLeases;
+    isPidAlive = sl.isPidAlive;
+    isSessionLive = sl.isSessionLive;
+  } catch (_e) { return { blocked: false, collisions: [] }; }
+  const locksDir = require('path').join(projectRoot, '.kenaz', 'locks');
+  const fsL = require('fs');
+  const pathMod = require('path');
+  const _ownConvForLease = process.env.CLAUDE_CODE_SESSION_ID || null;
+  const leases = readAllLeases().filter(function(l) {
+    // M1.5 (TASK_1761): use isSessionLive (pid-alive OR heartbeat-fresh) not just isPidAlive
+    // TASK_2265: own conversation's lease is self even when session identity is unproven
+    // (currentSessionId null); a foreign conversation's lease never is.
+    if (_ownConvForLease && l.conversation_id === _ownConvForLease) return false;
+    return l.session_id !== currentSessionId && (isSessionLive ? isSessionLive(l) : isPidAlive(l.pid));
+  });
+  if (leases.length === 0) return { blocked: false, collisions: [] };
+  // TASK_1863: self-recognition anchor for claim markers. A marker whose
+  // owner_conversation_id matches OUR conversation is a self-claim recorded
+  // under a session ALIAS (e.g. a boot ghost lease clobbered current_stream.json
+  // before task-api attributed the claim) — never a foreign stream. Skipping it
+  // lets a retry proceed after a mid-dispatch failure leaked our own claim.
+  // Foreign claims (different conversation, or no conversation id) still block.
+  const ownConvId = _getOwnConversationId(projectRoot);
+  const collisions = [];
+  for (const lease of leases) {
+    const claimedTaskIds = [];
+    try {
+      for (const lf of fsL.readdirSync(locksDir)) {
+        if (!lf.startsWith('claim_TASK_') || !lf.endsWith('.json')) continue;
+        try {
+          const mk = JSON.parse(fsL.readFileSync(pathMod.join(locksDir, lf), 'utf8'));
+          if (ownConvId && mk.owner_conversation_id === ownConvId) continue; // TASK_1863: self-claim via alias
+          // M1.5 (TASK_1761): liveness via owner SESSION lease, not just owner_pid
+          if (mk.owner_session === lease.session_id) {
+            const mkLive = isSessionLive ? isSessionLive(lease) : _dispPidAlive(mk.owner_pid);
+            if (mkLive) claimedTaskIds.push(lf.slice(6, -5));
+          }
+        } catch (_e2) {}
+      }
+    } catch (_e3) {}
+    // TASK_1764: same-task-id guard -- if another live stream already claimed this task, block.
+    if (targetTaskId && claimedTaskIds.indexOf(targetTaskId) !== -1) {
+      collisions.push({ stream_label: lease.label || lease.session_id, task_id: targetTaskId, paths: ['<same-task>'], sameTaskId: true });
+    }
+    for (const cid of claimedTaskIds) {
+      const claimedSP = [];
+      try {
+        const activeDir = pathMod.join(projectRoot, '.kenaz', 'tasks', 'active');
+        for (const e of fsL.readdirSync(activeDir)) {
+          if (e.startsWith(cid + '_') || e.startsWith(cid + '.')) {
+            const raw = fsL.readFileSync(pathMod.join(activeDir, e), 'utf8');
+            const spIdx = raw.indexOf('scope_paths:');
+            if (spIdx !== -1) {
+              const itemLines = raw.slice(spIdx + 12).split(String.fromCharCode(10));
+              for (const il of itemLines) {
+                const trimmed = il.trim();
+                if (!trimmed.startsWith('-')) break;
+                const val = trimmed.slice(1).trim().replace(/^['"]|['"]$/g, '');
+                if (val) claimedSP.push(val);
+              }
+            }
+            break;
+          }
+        }
+      } catch (_e4) {}
+      const cp = targetScopePaths.filter(function(tp) {
+        return claimedSP.some(function(csp) { return pathsCollide(tp, csp); });
+      });
+      if (cp.length > 0) {
+        collisions.push({ stream_label: lease.label || lease.session_id, task_id: cid, paths: cp });
+      }
+    }
+  }
+  return { blocked: collisions.length > 0 && !force, collisions: collisions };
+}
+
+function acquireResourceLocks(resources, projectRoot, sessionId, taskId) {
+  if (!resources || resources.length === 0) return { acquired: [], failed: [] };
+  const locksDir = require('path').join(projectRoot, '.kenaz', 'locks');
+  const fsL = require('fs');
+  const pathMod = require('path');
+  try { fsL.mkdirSync(locksDir, { recursive: true }); } catch (_e) {}
+  const acquired = [];
+  const failed = [];
+  for (const name of resources) {
+    const lp = pathMod.join(locksDir, 'resource_' + name + '.lock');
+    const content = JSON.stringify({
+      owner_session: sessionId || 'unknown',
+      owner_pid: process.pid,
+      task_id: taskId || null,
+      acquired_at: new Date().toISOString()
+    }, null, 2);
+    try { fsL.writeFileSync(lp, content, { flag: 'wx', encoding: 'utf8' }); acquired.push(name); }
+    catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      let holder = null;
+      try { holder = JSON.parse(fsL.readFileSync(lp, 'utf8')); } catch (_e2) {}
+      if (holder && _dispPidAlive(holder.owner_pid)) {
+        failed.push({ name: name, holder: holder });
+      } else {
+        process.stderr.write('WARNING: resource ' + name + ' ORPHAN lock (pid=' +
+          (holder && holder.owner_pid) + ' dead). Release: node .specialist/tools/stream-lease.js resource-release --name=' + name + String.fromCharCode(10));
+        failed.push({ name: name, holder: holder, orphan: true });
+      }
+    }
+  }
+  return { acquired: acquired, failed: failed };
+}
+
+function releaseResourceLocks(resources, projectRoot) {
+  if (!resources || resources.length === 0) return;
+  const locksDir = require('path').join(projectRoot, '.kenaz', 'locks');
+  for (const name of resources) {
+    try { require('fs').unlinkSync(require('path').join(locksDir, 'resource_' + name + '.lock')); } catch (_e) {}
+  }
+}
+// TASK_1710: path comparison helper — normalises separators and drive-letter case on Windows
+// so that forward-slash paths (C:/...) match backslash paths (C:...) and mixed-case drives.
+// Uses path.resolve (canonicalises separators) + toLowerCase on win32 + path.relative === ''
+// to confirm identity (also handles trailing-slash edge cases).
+function samePath(a, b) {
+  if (!a || !b) return false;
+  let ra = path.resolve(a);
+  let rb = path.resolve(b);
+  if (process.platform === 'win32') {
+    ra = ra.toLowerCase();
+    rb = rb.toLowerCase();
+  }
+  return path.relative(ra, rb) === '';
+}
+
+// ─────────────────────────────────────────
+// Yggdrasil 廣播（lazy load, fire-and-forget）
+// ─────────────────────────────────────────
+
+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:
+ *   - getSubagentDispatchParams (real sub-agent routing — ENFORCED)
+ * History: the cross-project check has been duplicated/decorative twice before
+ * (TASK_1672 omitted isolation on the real path; the old selectDispatchPath
+ * cross_project_cwd guard never influenced routing). Third recurrence of
+ * copy-the-check documented in rune_9fe1bdb57d834750ac443b1d7f09e965 /
+ * rune_eb53038640e246dea32764f89b18bfa1's point (5) — call this, never copy it.
+ * Modes:
+ *   agent_tool_worktree  — same-project: Agent tool isolation:'worktree'
+ *                          (harness-managed worktree in the conversation repo).
+ *   target_repo_worktree — cross-project + useWorktree: dispatcher pre-creates
+ *                          a worktree INSIDE the target repo (the Agent tool's
+ *                          own worktree derives from the conversation cwd repo
+ *                          and cannot isolate another repo — TASK_1672/1593).
+ *   serial_lock          — cross-project + !useWorktree (single-editor-bound
+ *                          projects like Unity): shared working tree, WRITES
+ *                          SERIALIZED via the per-project dispatch lock.
+ *   direct_no_git        — cross-project target WITHOUT a .git dir: the entire
+ *                          hazard class this decision guards (index.lock
+ *                          contention, commits silently vanishing, worktrees)
+ *                          is git-level and cannot occur — keep the plain
+ *                          direct-write behavior (no worktree, no lock).
+ * TASK_2176: also surfaces `verifyOffline` (the project's .kenaz/project.yaml
+ * `verify_offline: <command>` key, or null) regardless of isolation mode —
+ * same-project dispatches can declare it too, not only cross-project ones.
+ * The isolation decision itself (worktree vs serial_lock) is UNCHANGED by
+ * this key; verifyOffline only rides along so the caller can (a) hand the
+ * worktree agent a non-authoritative self-check instruction and (b) know,
+ * at landing time, that the authoritative run must happen serialized on the
+ * main tree (see verify-and-land.js stepVerifyOffline — a SEPARATE lock from
+ * the serial_lock dispatch lock above, scoped to just the verify command).
+ * @param {object} opts
+ * @param {string|null} opts.projectPath
+ * @param {boolean|null} [opts.useWorktreeOverride] - dispatch-time toggle (CLI --use-worktree)
+ * @returns {{ isCrossProject: boolean, mode: string, useWorktree: boolean, source: string, verifyOffline: string|null }}
+ */
+function resolveDispatchIsolation({ projectPath = null, useWorktreeOverride = null } = {}) {
+  // TASK_1710 semantics: samePath, not raw string compare (separator/case).
+  const isCrossProject = !!(projectPath && !samePath(projectPath, ROOT));
+  const verifyOffline = getVerifyOfflineCommand(projectPath);
+  if (!isCrossProject) {
+    return { isCrossProject, mode: 'agent_tool_worktree', useWorktree: true, source: 'same-project', verifyOffline };
+  }
+  if (!fs.existsSync(path.join(projectPath, '.git'))) {
+    return { isCrossProject, mode: 'direct_no_git', useWorktree: false, source: 'no-git-target', verifyOffline };
+  }
+  const d = resolveWorktreeDecision(projectPath, useWorktreeOverride);
+  return {
+    isCrossProject,
+    mode: d.useWorktree ? 'target_repo_worktree' : 'serial_lock',
+    useWorktree: d.useWorktree,
+    source: d.source,
+    verifyOffline,
+  };
+}
+
+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 前自動注入相關檔案摘要）
+// ─────────────────────────────────────────
+
+/**
+ * 從 scope_paths 提取相關檔案的簡要 context。
+ * Cortex 不可用時的 graceful fallback — 直接讀取檔案頭。
+ *
+ * 行為契約（TASK_1822 確認，回應外部 bug 回報的求證）：
+ * - 目錄條目：**完全不展開**，直接跳過（不 inline 其下任何檔案）。
+ *   scope_paths 全是目錄時，prompt 只會出現路徑清單、不會有本區段內容。
+ * - 檔案條目：inline 前 30 行，且整個 preview 另受位元組上限
+ *   （CORTEX_PREVIEW_MAX_BYTES）保護 — 30 是「行數」上限不是「位元組」
+ *   上限，單行極長的檔案（.min.js、無換行大檔）曾借道灌入數百 KB；
+ *   超過位元組上限會截斷並明確標註。
+ * - 二進位檔（開頭 sniff 區含 NUL 位元組）：跳過內容但保留區段標題
+ *   註明已跳過 — 靜默跳過會讓使用者誤以為內容已被看過。
+ *   偵測方式選 NUL-byte sniff 而非副檔名白名單：零依賴、不需維護
+ *   清單，且對無副檔名/罕見副檔名的二進位一樣有效（YAGNI）。
+ *
+ * @param {string[]} scopePaths - 任務的 scope_paths
+ * @param {string|null} projectPath - 子專案路徑
+ * @returns {string} 注入到 prompt 的 context 文字，空字串表示無可用 context
+ */
+const CORTEX_PREVIEW_MAX_LINES = 30;
+// thrift: 8KB 對 30 行綽綽有餘（平均 273 bytes/行）；若未來要 inline 更多行再調
+const CORTEX_PREVIEW_MAX_BYTES = 8 * 1024;
+const CORTEX_BINARY_SNIFF_BYTES = 8 * 1024;
+
+/**
+ * 讀取檔案開頭 sniff 區，含 NUL 位元組即視為二進位。
+ * PNG/JPEG/EXE 等格式的頭部幾乎必含 0x00；UTF-8 文字合法內容不含 NUL。
+ */
+function isBinaryFile(fullPath) {
+  const fd = fs.openSync(fullPath, 'r');
+  try {
+    const buf = Buffer.alloc(CORTEX_BINARY_SNIFF_BYTES);
+    const bytesRead = fs.readSync(fd, buf, 0, buf.length, 0);
+    return buf.subarray(0, bytesRead).includes(0);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function buildCortexContext(scopePaths, projectPath) {
+  if (!scopePaths || scopePaths.length === 0) return '';
+
+  const projectRoot = projectPath || ROOT;
+  const sections = [];
+
+  for (const sp of scopePaths) {
+    const fullPath = path.resolve(projectRoot, sp);
+    if (!fs.existsSync(fullPath)) continue;
+
+    try {
+      const stat = fs.statSync(fullPath);
+      if (stat.isDirectory()) continue;
+
+      if (isBinaryFile(fullPath)) {
+        // 註明已跳過而非靜默略過 — 讓 agent 知道這個 scope 檔案沒被預覽
+        sections.push(`### ${sp} (binary file, ${stat.size} bytes — content preview skipped)`);
+        continue;
+      }
+
+      // 只讀前 CORTEX_PREVIEW_MAX_BYTES(+1) 位元組（經 fd），不整檔載入記憶體
+      let head;
+      {
+        const fd = fs.openSync(fullPath, 'r');
+        try {
+          const buf = Buffer.alloc(CORTEX_PREVIEW_MAX_BYTES + 1);
+          head = buf.subarray(0, fs.readSync(fd, buf, 0, buf.length, 0));
+        } finally {
+          fs.closeSync(fd);
+        }
+      }
+      const partial = head.length > CORTEX_PREVIEW_MAX_BYTES; // 檔案超過上限，總行數未知
+      const content = head.toString('utf-8');
+      const lines = content.split('\n');
+      if (partial && lines.length > 1) lines.pop(); // 丟掉被截斷的最後一行
+      let preview = lines.slice(0, CORTEX_PREVIEW_MAX_LINES).join('\n');
+      const totalLines = lines.length;
+
+      // 位元組上限：防單行極長檔案（.min.js、無換行大檔）繞過行數上限
+      let byteTruncated = false;
+      if (Buffer.byteLength(preview, 'utf-8') > CORTEX_PREVIEW_MAX_BYTES) {
+        preview = Buffer.from(preview, 'utf-8')
+          .subarray(0, CORTEX_PREVIEW_MAX_BYTES)
+          .toString('utf-8')
+          .replace(/�+$/, ''); // 去掉截斷產生的不完整 multibyte 殘片
+        byteTruncated = true;
+      }
+
+      const marker = (byteTruncated || (partial && totalLines <= CORTEX_PREVIEW_MAX_LINES))
+        ? `\n... (truncated at ${CORTEX_PREVIEW_MAX_BYTES} bytes)`
+        : (totalLines > CORTEX_PREVIEW_MAX_LINES ? '\n... (truncated)' : '');
+
+      // partial 時只讀了開頭，行數僅為下限，故標 N+
+      sections.push(
+        `### ${sp} (${totalLines}${partial ? '+' : ''} lines)\n` +
+        '```\n' + preview + marker + '\n```'
+      );
+    } catch (err) {
+      // 註明已跳過而非靜默略過（與二進位分支一致）
+      sections.push(`### ${sp} (unreadable - preview skipped: ${(err && err.code) || 'error'})`);
+    }
+  }
+
+  if (sections.length === 0) return '';
+
+  return (
+    '\n## Cortex Context (Related Files Preview)\n' +
+    'The following files are in your scope. Review them before making changes.\n\n' +
+    sections.join('\n\n')
+  );
+}
+
+// ─────────────────────────────────────────
+// TASK_1998 R1: dispatch-prompt telemetry
+// ─────────────────────────────────────────
+
+/**
+ * Append one structured JSONL line to .kenaz/specialist/dispatch_prompt_stats.jsonl —
+ * one per sub-agent dispatch (getSubagentDispatchParams). Mirrors
+ * post-complete.js's appendPhase9OutcomeLog: same project-pinning
+ * (projectPath || ROOT), same best-effort append, never throws.
+ *
+ * Format: { ts, task_id, rigor, complexity, formation, prompt_bytes, sections: [{title, bytes}], model, model_source }
+ * dev/scripts/dispatch-stats.js reads this to print p50/p90 prompt_bytes per (rigor, complexity).
+ * model_source (TASK_1998 R3): 'dashboard'|'dashboard-by-rigor'|'cli' — which
+ * layer of resolveDispatchModelForRigor() picked `model`. Optional (older
+ * callers, and the non-subagent path, omit it — reader must tolerate absence).
+ * complexity (TASK_1998 two-axis policy): the normalized 'simple'|'medium'|'complex'
+ * CONTEXT-volume key (extractComplexity() default). Optional for older readers.
+ */
+function appendDispatchPromptStats({ taskId, rigor, complexity, formation, promptText, model, modelSource, projectPath }) {
+  const root = projectPath || ROOT;
+  const dir = path.join(root, '.kenaz', 'specialist');
+  try {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      task_id: taskId || null,
+      rigor: rigor || 'medium',
+      complexity: complexity || 'medium',
+      formation,
+      prompt_bytes: Buffer.byteLength(promptText || '', 'utf-8'),
+      sections: splitPromptSections(promptText || ''),
+      model,
+      model_source: modelSource || null,
+    });
+    fs.appendFileSync(path.join(dir, 'dispatch_prompt_stats.jsonl'), line + '\n', 'utf8');
+  } catch { /* best-effort — telemetry must never block dispatch */ }
+}
+
+// ─────────────────────────────────────────
+// 依賴預檢
+// ─────────────────────────────────────────
+
+/**
+ * 檢查任務的依賴是否都已完成。
+ * 掃描 done/ + archived/ + completed/。
+ *
+ * @param {string} taskData - JSON or YAML 任務文本
+ * @param {string|null} projectPath - 子專案路徑（null = core）
+ * @returns {{ blocked: boolean, unmet: string[] }}
+ */
+function checkDependencies(taskData, projectPath) {
+  let deps = [];
+  try {
+    const parsed = JSON.parse(taskData);
+    deps = parsed.dependencies || [];
+  } catch {
+    // Try YAML key extraction as fallback
+    const match = taskData.match(/^dependencies:\s*\n((?:\s+-\s+\S+\n?)+)/m);
+    if (match) {
+      deps = match[1].split('\n')
+        .map(l => l.trim().replace(/^-\s*/, ''))
+        .filter(Boolean);
+    }
+  }
+
+  if (deps.length === 0) return { blocked: false, unmet: [] };
+
+  // Collect completed task IDs from all relevant directories
+  const completedIds = new Set();
+  const blockedIds = new Set();
+  const scanDir = (dir, bucket) => {
+    if (!dir || !fs.existsSync(dir)) return;
+    try {
+      for (const f of fs.readdirSync(dir)) {
+        if (f.startsWith('TASK_')) {
+          const base = f.replace(/\.yaml$/, '');
+          bucket.add(base.split('_').slice(0, 2).join('_'));
+        }
+      }
+    } catch { /* ignore */ }
+  };
+
+  const projectRoot = projectPath || ROOT;
+
+  // New system: scan BOTH .kenaz/tasks/ and .collaboration/tasks/
+  // (Core project may have both directories)
+  const kenazTasks = path.join(projectRoot, '.kenaz', 'tasks');
+  const collabTasks = path.join(projectRoot, '.collaboration', 'tasks');
+
+  for (const base of [kenazTasks, collabTasks]) {
+    scanDir(path.join(base, 'done'), completedIds);
+    scanDir(path.join(base, 'archived'), completedIds);
+    scanDir(path.join(base, 'blocked'), blockedIds);
+  }
+
+  // Legacy system: completed/
+  scanDir(path.join(projectRoot, 'dev', 'pipeline', 'completed'), completedIds);
+
+  const blockedDeps = deps.filter(dep => blockedIds.has(dep));
+  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
+// ─────────────────────────────────────────
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+⚔️  Formation Dispatch
+
+Usage:
+  node .formation/tools/dispatch.js --skill=<name> --task=<TASK_ID|description>
+
+Options:
+  --formation <name>      Formation type: unit (default), solo, squad, legion
+  --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
+                          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.
+  --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
+                          cross-project subagent dispatch: true → pre-created
+                          worktree inside the target repo; false → shared tree
+                          with serialized writes (dispatch lock). Single-editor
+                          projects (Unity) should pass false.
+  --release-lock          TASK_1859: release the serial dispatch lock for
+                          --project-path (omit for the core lock). Prints the
+                          holder's taskId/sessionId/startedAt, then releases.
+                          Default releases only a lock held by THIS session;
+                          cross-session / unknown-holder release needs --force.
+                          Idempotent: exit 0 with a harmless message when no
+                          lock is held. Fallback remains deleting the lock file.
+  --force                 Dispatch even if dependencies are not met
+                          (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
+
+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);
+  }
+
+  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;
+  };
+
+  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
+  // either a bare Agent tool family (sonnet|opus|haiku|fable) or a full
+  // dashboard-style id (translated the same way as every other source).
+  const dispatchModelCli = getArg('--dispatch-model');
+  const force = args.includes('--force');
+  // TASK_2315: harness selector; auto-detect Codex from its session env (same signal as the boot fix).
+  const harnessCli = getArg('--harness') || ((process.env.CODEX_SESSION_ID || process.env.CODEX_THREAD_ID) ? 'codex' : 'claude');
+
+  // TASK_1833: dispatch-time worktree toggle. Parsed strictly — a typo must not
+  // silently fall through to the project default. Also exported to
+  // FORMATION_USE_WORKTREE so any in-process readWorktreeConfig consumer
+  // (formation path included) sees the same decision.
+  const useWorktreeRaw = getArg('--use-worktree');
+  let useWorktreeCli = null;
+  if (useWorktreeRaw != null) {
+    const v = String(useWorktreeRaw).trim().toLowerCase();
+    if (v === 'true' || v === '1') useWorktreeCli = true;
+    else if (v === 'false' || v === '0') useWorktreeCli = false;
+    else {
+      console.error(`❌ --use-worktree expects true|false (got '${useWorktreeRaw}')`);
+      process.exit(1);
+    }
+    process.env.FORMATION_USE_WORKTREE = String(useWorktreeCli);
+  }
+
+  // TASK_1859: standalone lock-release subcommand — needs neither --skill nor
+  // --task. Exists because "delete the lock file" (the previous release
+  // contract) is unexecutable where Bash(rm *) is denied.
+  if (args.includes('--release-lock')) {
+    const res = releaseDispatchLock({ projectPath, force });
+    const h = res.holder || {};
+    const holderLine = res.existed
+      ? `   Holder: task=${h.taskId || '?'}, session=${h.sessionId || '?'}, startedAt=${h.startedAt || '?'}` +
+        (res.staleness ? ` (age=${Number.isFinite(res.staleness.ageMs) ? Math.round(res.staleness.ageMs / 60000) + 'min' : '?'}, stale=${res.staleness.stale})` : '')
+      : null;
+    if (!res.existed) {
+      console.log(`✅ No dispatch lock held (${res.lockFile}) — nothing to release.`);
+      process.exit(0);
+    }
+    if (res.released) {
+      console.log(holderLine);
+      console.log(`✅ Dispatch lock released (${res.reason}): ${res.lockFile}`);
+      process.exit(0);
+    }
+    console.log(holderLine);
+    console.error(`❌ Dispatch lock NOT released (${res.reason}): ${res.lockFile}`);
+    if (res.reason === 'session-mismatch' || res.reason === 'holder-session-unknown' ||
+        res.reason === 'own-session-unresolved' || res.reason === 'own-session-unproven' ||
+        res.reason === 'holder-unreadable') {
+      console.error('   This session cannot prove it owns the lock. Verify the previous agent is done, then re-run with --force. (Stale locks auto-break on the next dispatch after 60min.)');
+    }
+    process.exit(1);
+  }
+
+  if (!skill) {
+    console.error('❌ --skill is required');
+    process.exit(1);
+  }
+
+  if (!task) {
+    console.error('❌ --task is required (TASK_ID or description)');
+    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;
+  }
+
+  dispatch({ formation, skill, task, output, dryRun, projectPath, force });
+}
+
+// ─────────────────────────────────────────
+// Sub-agent dispatch path
+// ─────────────────────────────────────────
+
+/**
+ * TASK_1813: read dispatch routing (dispatchFamily/dispatchAdapter) plus the raw
+ * dashboard-models.json object, mirroring kenaz.rs load_dispatch_routing /
+ * load_dashboard_model semantics:
+ * - Candidate order: project first, then core (ROOT). Same order as the Rust
+ *   side's dashboard_models_candidates — both paths must read the SAME file or
+ *   they can reach different routing conclusions for one dispatch.
+ * - ALL fields come from the FIRST parseable candidate file, so family and
+ *   adapter can never be mixed across two different dashboard-models.json files.
+ * - Empty/whitespace strings coalesce to null (mirrors Rust `.filter(|s| !s.is_empty())`).
+ * @param {string|null} projectPath
+ * @returns {{ models: object|null, family: string|null, adapter: string|null }}
+ */
+function loadDispatchRouting(projectPath) {
+  const parsed = loadDashboardModels(projectPath); // first parseable candidate wins (TASK_2249)
+  if (!parsed) return { models: null, family: null, adapter: null };
+  const get = (field) => {
+    const v = parsed[field];
+    if (typeof v !== 'string') return null;
+    const trimmed = v.trim();
+    return trimmed || null;
+  };
+  return { models: parsed, family: get('dispatchFamily'), adapter: get('dispatchAdapter') };
+}
+
+/**
+ * Build the sub-agent dispatch payload without spawning a process.
+ * Ansuz calls this to get the prompt + Agent tool parameters, then passes them
+ * to the Agent tool (isolation='worktree') directly. (Originally motivated by
+ * the June 15 claude -p credit pool, since rescinded; it remains the default
+ * because results return in-session without log polling.)
+ *
+ * Routing: use for rigor:low/medium tasks estimated <30min.
+ * Formation dispatch (claude -p) remains the default for rigor:high / multi-hour tasks.
+ *
+ * @param {object} options
+ * @param {string} [options.formation='unit']
+ * @param {string} [options.skill='do']
+ * @param {string} options.task - Task ID (TASK_XXX) or description
+ * @param {string|null} [options.projectPath]
+ * @param {boolean} [options.force] - Skip dependency check
+ * @param {boolean|null} [options.useWorktree] - TASK_1833 dispatch-time worktree toggle
+ *   (true/false overrides env/project.yaml; null = no override). Only affects
+ *   cross-project dispatch — same-project always uses Agent tool isolation:'worktree'.
+ * @param {string|null} [options.dispatchModelOverride] - TASK_1998 R3: --dispatch-model
+ *   CLI value, if any. Wins over dashboard-models.json dispatchModelByRigor and
+ *   the dashboard dispatchModel default.
+ * @returns {Promise<{ promptText: string, taskId: string, formation: string, skill: string, dispatchMode: string, effectiveMode: 'subagent', modelTranslation: { requested: string, agentToolModel: string, granularityLoss: boolean }, isolation: object, agentParams: object, rigor: 'low'|'medium'|'high', modelSource: 'dashboard'|'dashboard-by-rigor'|'cli' }|null>}
+ *   dispatchMode = TASK_1813 config echo (dashboard-models.json request);
+ *   effectiveMode = the path actually taken (always 'subagent' here — TASK_1859).
+ */
+async function getSubagentDispatchParams(options) {
+  const {
+    formation = 'unit', skill = 'do', task, projectPath = null, force = false, useWorktree = null,
+    dispatchModelOverride = null, // TASK_1998 R3: --dispatch-model CLI flag, wins over dashboard dispatchModelByRigor/dispatchModel
+    // --dry-run: build and print the payload with NO side effects — no resource
+    // leases, no worktree, no serial lock, no prompt telemetry. Gates still run
+    // so a dry run reports the same rejections a real dispatch would.
+    dryRun = false,
+    // TASK_2315: 'claude' (Agent tool) | 'codex' (Codex-native spawn_agent). Selects the payload shape.
+    harness = 'claude',
+  } = options;
+  if (harness !== 'claude' && harness !== 'codex') {
+    console.error(`❌ --harness expects claude|codex (got '${harness}')`);
+    return null;
+  }
+  const isCodex = harness === 'codex';
+
+  // 1. Load skill + task
+  const skillDef = loadSkill(formation, skill);
+  const loadOpts = projectPath ? { projectPath } : undefined;
+  const taskData = task && task.startsWith('TASK_') ? loadTask(task, loadOpts) : null;
+  const taskInput = task || '';
+  // TASK_1998 R3: extracted here (not at step 4, where it used to live) so the
+  // model-resolution step (2c) below can read it before choosing a model.
+  const rigor = extractRigor(taskData);
+  // TASK_1998 two-axis policy: complexity drives CONTEXT volume (Cross-Project
+  // Context caps, Related Files Preview, Known Failures, Project Memory).
+  // Always normalized (extractComplexity defaults to 'medium').
+  const complexity = extractComplexity(taskData);
+
+  // 2. Dependency check (same guard as Formation dispatch)
+  if (taskData) {
+    const depCheck = checkDependencies(taskData, projectPath);
+    if (depCheck.blocked && !force) {
+      console.error(`❌ Sub-agent dispatch blocked: ${taskInput} has unmet dependencies`);
+      for (const dep of depCheck.unmet) {
+        console.error(`   ⛔ ${dep} — not in done/completed`);
+      }
+      return null;
+    }
+  }
+
+  // 2b. (TASK_1813) Dispatch routing guard — mirrors kenaz.rs tool_dispatch
+  // (lines 624-654, TASK_1776) on the sub-agent path. The Agent tool's model
+  // parameter only accepts Claude models, so a non-claude dispatchFamily has NO
+  // viable execution here and MUST fail loudly (sigil_2a3f3b75 invariant:
+  // "a non-claude model id MUST resolve to an adapter or fail loudly — never
+  // silent Claude CLI fallback"). Runs BEFORE the scope gate / resource locks /
+  // prompt build so a rejected dispatch never acquires locks it won't use.
+  const routing = loadDispatchRouting(projectPath);
+  const models = routing.models;
+  // 2026-10-10: the harness decides the family. A Codex session can only spawn Codex
+  // sub-agents (model inherited), so dashboard-models.json dispatchFamily (a Dashboard
+  // preference for the retired Formation spawns) no longer blocks --harness=codex.
+  if (isCodex && routing.family !== 'bifrost') {
+    process.stderr.write(`[dispatch] --harness=codex: dispatchFamily '${routing.family || 'unset'}' ignored, Codex sub-agent inherits the session model
+`);
+  }
+  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).');
+    } 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.`);
+    }
+    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).`);
+    return null;
+  }
+
+  // 2c. (TASK_1815 + TASK_1998 R3) Resolve which raw model id to use — CLI
+  // --dispatch-model > dashboard-models.json dispatchModelByRigor[rigor] >
+  // dashboard-models.json dispatchModel (today's behaviour, used for every
+  // rigor unless dispatchModelByRigor overrides it) — THEN translate it to the
+  // Agent tool's family enum. The raw id (e.g. 'claude-fable-5[1m]') is rejected by the
+  // Agent tool for ANY source (measured 2026-07-26: same InputValidationError
+  // as 'gpt-5-codex'); only the family names in AGENT_TOOL_MODEL_ENUM pass
+  // validation. Fail loudly on unmappable ids from ANY source (TASK_1815:
+  // never silently substitute), and surface the version-granularity loss to
+  // the caller. Runs BEFORE the scope gate / resource leases (same reason as
+  // 2b: a rejected dispatch must never acquire locks it won't use).
+  const resolution = resolveDispatchModelForRigor({ rigor, models, cliDispatchModel: dispatchModelOverride });
+  const rawModel = resolution.rawModel;
+  // 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.`);
+    return null;
+  }
+  const dispatchModel = translated.model;
+  const modelTranslation = isCodex
+    ? { 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`);
+  }
+  // TASK_1998 R3 (+ two-axis policy): the resolved choice, always printed
+  // (unlike the granularity block above, which only fires on lossy translation).
+  process.stderr.write(`[dispatch] rigor=${resolution.rigorKey} complexity=${complexity} model=${rawModel} → ${isCodex ? 'inherited by Codex session' : "family '" + dispatchModel + "'"} (source: ${resolution.source})\n`);
+
+  // TASK_2362: subagent is the only route. dispatchMode is a legacy config echo:
+  // missing -> 'subagent'; 'subagent'|'auto' accepted; 'formation' (retired) or
+  // any other value warns LOUDLY and uses 'subagent'.
+  const rawDispatchMode = typeof models?.dispatchMode === 'string' ? models.dispatchMode.trim() : '';
+  let dispatchMode = 'subagent';
+  if (rawDispatchMode) {
+    if (rawDispatchMode === 'subagent' || rawDispatchMode === 'auto') {
+      dispatchMode = rawDispatchMode;
+    } else {
+      console.error(`⚠️ dashboard-models.json dispatchMode '${rawDispatchMode}' is invalid or retired (expected subagent|auto) — using 'subagent'`);
+    }
+  }
+
+  // M1 (TASK_1758): scope gate + resource lease (same as formation dispatch path)
+  // TASK_1833: acquired resources tracked OUTSIDE the block so the isolation
+  // step below can release them on late rejection (never leak leases).
+  // TASK_1863: the self-owned claim marker gets the SAME late-rejection release
+  // guarantee — tracked alongside the resources, released at every post-gate
+  // failure exit (leaked markers blocked same-task retries for the 8h window).
+  let _saAcquiredResources = [];
+  let _saClaim = null;
+  const _saRoot = projectPath || ROOT;
+  {
+    const _saSession = _getProvenSessionId(_saRoot); // TASK_2265: proven identity only
+    const _saPaths = (() => { try { return taskData ? JSON.parse(taskData).scope_paths || [] : []; } catch { return []; } })();
+    const _saResult = checkDispatchScopeGate(_saPaths, _saRoot, _saSession, !!force, taskInput);
+    if (_saResult.collisions.length > 0) {
+      for (const col of _saResult.collisions) {
+        const pl = col.paths.slice(0,3).join(', ') + (col.paths.length > 3 ? ' +' + (col.paths.length-3) + ' more' : '');
+        if (_saResult.blocked) { console.error('Sub-agent dispatch blocked: scope conflict with stream ' + col.stream_label + ' (task ' + col.task_id + '): ' + pl); }
+        else { console.warn('WARNING scope conflict (--force): stream ' + col.stream_label + ' (task ' + col.task_id + '): ' + pl); }
+      }
+      if (_saResult.blocked) { return null; }
+    }
+    _saClaim = adoptSelfClaimMarker(taskInput, _saRoot, _saSession);
+    const _saResources = (() => { try { return taskData ? JSON.parse(taskData).resources || [] : []; } catch { return []; } })();
+    if (_saResources.length > 0 && dryRun) {
+      console.error('   [dry-run] resource locks NOT acquired: ' + _saResources.join(', '));
+    } else if (_saResources.length > 0) {
+      const _saLock = acquireResourceLocks(_saResources, _saRoot, _saSession, taskInput);
+      if (_saLock.failed.length > 0) {
+        for (const fail of _saLock.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' : ' busy') + hi);
+        }
+        releaseResourceLocks(_saLock.acquired, _saRoot);
+        if (!force) { releaseAdoptedClaimMarker(_saClaim); return null; }
+        console.warn('WARNING: proceeding despite resource lock conflicts (--force).');
+      } else if (_saLock.acquired.length > 0) {
+        console.error('   Resource locks acquired: ' + _saLock.acquired.join(', '));
+      }
+      _saAcquiredResources = _saLock.acquired;
+    }
+  }
+
+  // TASK_1833: cross-project dispatch now goes through the SAME isolation
+  // decision as every other path (resolveDispatchIsolation — see its doc for
+  // the mode taxonomy and the TASK_1672/1593 reason the Agent tool's own
+  // isolation param cannot cover another repo). Before this, cross-project
+  // sub-agent dispatch unconditionally got NEITHER isolation NOR
+  // serialization, and the shared-tree `|| true` commit swallowed the
+  // resulting index.lock data loss (measured 2026-07-31).
+  // TASK_1824 ordering still holds: computed BEFORE buildPrompt so prompt
+  // assembly (appendWorkflow staging gate, TASK_1819) knows the isolation mode.
+  const iso = resolveDispatchIsolation({ projectPath, useWorktreeOverride: useWorktree });
+  // TASK_2315: Codex has no harness-managed worktree isolation — always pre-create
+  // one (same-project included) and hand its path to the agent as cwd.
+  const wtRepo2315 = projectPath || ROOT;
+  if (isCodex && iso.mode === 'agent_tool_worktree') { iso.mode = 'target_repo_worktree'; iso.source = 'codex-harness'; }
+  const isCrossProject = iso.isCrossProject || (isCodex && iso.mode === 'target_repo_worktree');
+  let crossWorktree = null; // { worktreePath, branchName } when mode=target_repo_worktree
+  let serialLock = null;    // { lockFile } when mode=serial_lock
+  let worktreeFallbackReason = null; // TASK_2067: non-null only on a genuine target_repo_worktree creation failure that degraded to serial_lock -- rides in the isolation payload, not just stderr
+
+  // TASK_2297: free-space gate before any worktree is created. Reclaims finished-card
+  // worktrees ONLY under pressure (merged+clean+no junctions+idle); refuses otherwise.
+  if (iso.useWorktree && !dryRun) {
+    const wtRepo = projectPath || ROOT;
+    const space = require('./worktree-reclaim').ensureWorktreeSpace(wtRepo, path.join(wtRepo, '.formation', 'worktrees'));
+    if (!space.ok) throw new Error(space.message);
+  }
+
+  if (iso.mode === 'target_repo_worktree' && dryRun) {
+    const idBase = taskInput.startsWith('TASK_') ? taskInput.toLowerCase() : 'adhoc';
+    crossWorktree = { worktreePath: path.join(wtRepo2315, '.formation', 'worktrees', `task_${idBase}`) + ' (dry-run: not created)', branchName: `task/${idBase}` };
+  } else if (iso.mode === 'target_repo_worktree') {
+    try {
+      crossWorktree = setupSubagentCrossProjectWorktree(wtRepo2315, taskInput);
+      // stderr, not stdout — subagent mode's stdout is machine-readable JSON
+      process.stderr.write(`   🌿 Cross-project worktree (in target repo): ${crossWorktree.worktreePath}${crossWorktree.reusedBranch ? ' (reused existing branch)' : ''}\n`);
+    } catch (e) {
+      // Safe degradation: NEVER fall back to unserialized shared-tree writes —
+      // that is exactly the defect this path exists to prevent. Serialize instead.
+      // TASK_2067: this must now be a GENUINE creation failure (e.g. branch
+      // checked out in another worktree already) -- the "branch exists but
+      // its worktree doesn't" case is handled inside createWorktree itself
+      // and no longer throws here. Surface the reason in the payload too,
+      // not only stderr, so a consumer of the JSON payload can see WHY it
+      // degraded instead of assuming this is the normal/expected path.
+      console.error(`⚠️ Cross-project worktree creation failed (${e.message}) — falling back to SERIALIZED shared-tree dispatch`);
+      worktreeFallbackReason = e.message;
+      iso.mode = 'serial_lock';
+      iso.useWorktree = false;
+    }
+  }
+
+  if (iso.mode === 'serial_lock' && dryRun) {
+    console.error('   [dry-run] shared-tree dispatch lock NOT acquired: ' + dispatchLockPath(projectPath));
+  } else if (iso.mode === 'serial_lock') {
+    const lockFile = dispatchLockPath(projectPath);
+    // pid:null on purpose — this CLI exits right after emitting params, so its
+    // own pid says nothing about the agent's liveness. pid-less locks are
+    // broken only by staleness (60min) or explicit release (delete the file
+    // after merge — the lock file path is surfaced in the returned payload).
+    const acq = tryAcquireDispatchLock(lockFile, {
+      sessionId: _getProvenSessionId(ROOT) || 'unknown', // TASK_2265: unproven fallback never written as owner
+      taskId: taskInput || null,
+      pid: null,
+      holder: 'subagent-shared-tree',
+    });
+    if (!acq.acquired) {
+      const h = acq.holder || {};
+      console.error(`❌ Sub-agent dispatch blocked: shared-tree dispatch lock for this project is held (task=${h.taskId || '?'}, session=${h.sessionId || '?'}, since=${h.startedAt || '?'}). Cross-project dispatch WITHOUT worktree isolation is serialized — multiple agents committing into one shared working tree destroy each other's work (index.lock). Wait for the current dispatch to finish (lock auto-breaks 60min after acquisition), or release it after verifying the previous agent is done: node .formation/tools/dispatch.js --release-lock${projectPath ? ` --project-path "${projectPath}"` : ''} (add --force if held by another session). Fallback: delete ${lockFile}`);
+      releaseResourceLocks(_saAcquiredResources, _saRoot);
+      releaseAdoptedClaimMarker(_saClaim); // TASK_1863: late rejection must not leak the claim
+      return null;
+    }
+    if (acq.broke) console.warn(`   ⚠️  Broke ${acq.brokeReason} dispatch lock from ${acq.broke.taskId || acq.broke.sessionId || '<corrupt>'}`);
+    serialLock = { lockFile };
+  }
+
+  // 3. Build prompt (same buildPrompt() as Formation dispatch — same prompt quality)
+  const promptOptions = { isSubagent: true, isCrossProject };
+  if (crossWorktree) promptOptions.isWorktree = true; // isolated staging (TASK_1819 gate)
+  if (projectPath) promptOptions.projectPath = projectPath;
+  if (taskInput && taskInput.startsWith('TASK_')) promptOptions.taskId = taskInput;
+
+  const rawPrompt = buildPrompt(skillDef, taskInput, taskData, promptOptions);
+
+  // 4. Cortex context (same as Formation dispatch)
+  const taskScopePaths = (() => {
+    try {
+      if (!taskData) return [];
+      const parsed = JSON.parse(taskData);
+      return parsed.scope_paths || [];
+    } catch { return []; }
+  })();
+
+  let promptText = typeof rawPrompt === 'string' ? rawPrompt : '';
+  // TASK_1998: complexity (not rigor) gates the Related Files Preview section
+  // (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 });
+  if (taskScopePaths.length > 0 && !dietProfile.skipRelatedFilesPreview) {
+    const cortexCtx = buildCortexContext(taskScopePaths, projectPath);
+    if (cortexCtx) promptText = promptText + '\n' + cortexCtx;
+  }
+
+  // TASK_2176: project declares verify_offline (single heavyweight tool —
+  // Unity/Unreal/mobile — the worktree agent cannot run authoritatively).
+  // Surface it as a non-authoritative self-check only; the authoritative,
+  // serialized run happens on the main tree at landing (verify-and-land.js
+  // stepVerifyOffline), never inside this worktree.
+  if (iso.verifyOffline) {
+    promptText += `\n\n## Offline self-check (non-authoritative)\nThis project's .kenaz/project.yaml declares \`verify_offline: ${iso.verifyOffline}\`. Run it yourself before committing as a self-check and note the pass/fail in your final summary. It does NOT replace the authoritative verification — that runs serialized on the main tree at landing.\n`;
+  }
+
+  // 5. Swap HEADLESS_PREFIX → sub-agent transport preamble (mode-specific)
+  // TASK_1833: prefix follows the isolation mode —
+  //   agent_tool_worktree  → SUBAGENT_PREFIX (harness worktree, pwd-derived)
+  //   target_repo_worktree → buildSubagentWorktreePrefix (pre-created worktree
+  //                          inside the target repo; agent cd's there)
+  //   serial_lock          → SUBAGENT_PREFIX_DIRECT (shared tree, explicit-paths
+  //                          staging, writes serialized by the dispatch lock)
+  let subagentPrefix = SUBAGENT_PREFIX;
+  if (isCrossProject) {
+    subagentPrefix = crossWorktree
+      ? buildSubagentWorktreePrefix(crossWorktree.worktreePath, crossWorktree.branchName, wtRepo2315)
+      : SUBAGENT_PREFIX_DIRECT;
+    process.stderr.write('[dispatch] cross-project detected (' + ROOT + ' vs ' + projectPath + ') — isolation mode: ' + iso.mode + '\n');
+  }
+  // TASK_2082 defect fix: when promptText's body carries the "## Rust check"
+  // section (appendWorkflow -> appendRustCheckReminder), hard rule 4's
+  // "Rust 交 Ansuz" wording inside the chosen prefix is contradictory — a
+  // later "this overrides rule 4" note in the body was observed NOT
+  // winning against the earlier hard rule. Rewrite the prefix itself at
+  // this composition point instead; a body without the section marker
+  // leaves the prefix byte-identical.
+  subagentPrefix = applyRustCheckToPrefix(subagentPrefix, promptText);
+  promptText = subagentPrefix + promptText;
+
+  // 6. Model (translated to the Agent tool enum, step 2c) + dispatchMode
+  // (step 2b routing guard) were resolved above.
+
+  // TASK_1593: the Agent tool derives its worktree directory and branch from the
+  // CONVERSATION id alone, so concurrent sub-agents of one session would collide on a
+  // single worktree. That is HARNESS behaviour, upstream of us.
+  //
+  // TASK_1833 correction (2026-07-31): in THIS repo they no longer collide, and the
+  // previous text here — "two parallel dispatches from the same Ansuz session share one
+  // worktree directory" — is now FALSE. Registering .claude/hooks/worktree-create.js as
+  // a WorktreeCreate hook makes the harness delegate creation entirely to that hook,
+  // which DISCARDS the proposed path and synthesizes wt-<sid8>-<pid> (makeWtName), then
+  // uniquifies the directory and the branch independently. Each hook invocation is its
+  // own `node -e` process so the pid differs per sub-agent; the uniquify loops are what
+  // actually guarantee correctness, since Windows recycles pids aggressively. Measured:
+  // one session produced wt-8c83ecc1-12492 and wt-8c83ecc1-12624 for two concurrent
+  // dispatches, and ten distinct wt-e989b14a-* trees exist from one earlier session.
+  //
+  // So parallel sub-agent dispatch from one Ansuz session IS safe here. Do not cite this
+  // block as a reason to serialize — the stale version of this comment cost a round of
+  // throughput on 2026-07-31 by talking a reader out of parallelizing. The historical
+  // incident (TASK_1610/1611) was NOT collision-by-sharing: an older worktree-create.js
+  // ran `worktree remove --force` for "idempotency" and destroyed a live sibling's
+  // worktree mid-task. That path is gone (TASK_1639); the hook now never claims an
+  // existing path.
+  //
+  // Still true: the description field does not affect the worktree name, and per-TASK
+  // naming (task_<taskid>) requires the formation path via
+  // formations.setupUnitWorktree({ taskId }).
+  const agentParams = isCodex ? undefined : {
+    // Include taskInput so the Agent tool description is unique per task (helps tracing)
+    description: `[${taskInput}] Kenaz subagent (${skill})`,
+    model: dispatchModel,
+    // TASK_1672: omit Agent-tool isolation for cross-project dispatch — its worktree
+    // would be rooted in the core/non-git cwd, not the sub-project repo. TASK_1833:
+    // cross-project isolation is instead provided by the pre-created target-repo
+    // worktree (target_repo_worktree) or by dispatch-lock serialization (serial_lock).
+    ...(isCrossProject ? {} : { isolation: 'worktree' }),
+    // run_in_background: false → Ansuz awaits result directly (no log polling)
+  };
+
+  // TASK_1833: isolation metadata rides NEXT TO agentParams (same reason as
+  // modelTranslation — the Agent tool schema rejects unknown fields). Ansuz
+  // needs it to: merge the target-repo worktree branch after the agent returns,
+  // and to release the serial dispatch lock after merge.
+  const isolation = {
+    mode: iso.mode,
+    source: iso.source,
+    worktreePath: crossWorktree ? crossWorktree.worktreePath : null,
+    branchName: crossWorktree ? crossWorktree.branchName : null,
+    // TASK_2067: true when an existing task/<id> branch (worktree missing,
+    // e.g. a cancelled task resumed) was reused rather than created fresh.
+    reusedBranch: crossWorktree ? !!crossWorktree.reusedBranch : false,
+    // TASK_2067: non-null only when target_repo_worktree creation genuinely
+    // failed and dispatch degraded to serial_lock -- never set for the
+    // reused-branch case above, which is not a degradation.
+    worktreeFallbackReason,
+    serialLock: serialLock
+      ? {
+          lockFile: serialLock.lockFile,
+          // TASK_1859: release contract is now the CLI (executable where
+          // Bash(rm *) is denied); deleting the file stays as the fallback.
+          releaseCommand: `node .formation/tools/dispatch.js --release-lock${projectPath ? ` --project-path "${projectPath}"` : ''}`,
+          note: 'Release after the agent finishes and its work is merged: run releaseCommand (same session; add --force cross-session). Fallback: delete lockFile. Auto-breaks 60min after acquisition.',
+        }
+      : null,
+    // TASK_2176: project's .kenaz/project.yaml verify_offline command, or
+    // null (today's behaviour) when absent. The worktree agent already got
+    // it as a non-authoritative self-check instruction above; this lets the
+    // caller (Ansuz) pass it to verify-and-land.js at landing, where it runs
+    // as the authoritative, serialized gate on the main tree.
+    verifyOffline: iso.verifyOffline || null,
+  };
+
+  // TASK_1815: modelTranslation rides NEXT TO agentParams (not inside it) so
+  // the Agent tool payload stays pure while the caller (Ansuz) still SEES the
+  // requested-vs-emitted model and the granularity loss. Do not fold it into
+  // agentParams — the Agent tool schema would reject unknown fields.
+  // TASK_1859: dispatchMode is the TASK_1813 CONFIG ECHO (what
+  // dashboard-models.json requested: formation|subagent|auto) — do NOT change
+  // its semantics, subagent-bifrost-guard.test.js pins them. effectiveMode is
+  // the path this dispatch ACTUALLY took; this function IS the subagent path,
+  // so consumers reading the payload of a --dispatch-mode=subagent run can see
+  // 'subagent' even when the config echo says 'formation'.
+
+  // TASK_1998 R1a: telemetry — one JSONL line per sub-agent dispatch.
+  // R3: modelSource rides along so dispatch-stats.js can break down turns/sec
+  // by dashboard vs dashboard-by-rigor vs cli without re-deriving it.
+  // Two-axis policy: complexity rides along too, so dispatch-stats.js can
+  // group by (rigor, complexity) instead of rigor alone.
+  if (!dryRun) appendDispatchPromptStats({ taskId: taskInput, rigor: resolution.rigorKey, complexity, formation, promptText, model: dispatchModel, modelSource: resolution.source, projectPath });
+
+  // TASK_2032: mirror headless.js's formation-path auto-activation (~L272-290)
+  // on the subagent path — every gate/guard above has passed and this function
+  // is about to return a real payload, so move the card backlog -> active NOW.
+  // Root cause this fixes: the formation path activates the card before the
+  // agent runs, but this function never did, so a --dispatch-mode=subagent
+  // card sat in backlog/ the whole time the subagent worked — and afterwards
+  // `task-api move <id> done` was rejected ("backlog -> done not allowed"),
+  // forcing a backlog->active->done two-step every time.
+  // Unlike headless.js, this does NOT git-commit the status change: the
+  // subagent never reads the task dir (buildPrompt already inlined taskData
+  // above) and post-complete's merge runs in the main tree, so there is no
+  // worktree-forks-from-stale-HEAD problem to solve here.
+  // Skipped for dryRun (same "no side effects" contract as the resource
+  // leases / worktree / serial lock / telemetry above) and for non-TASK_
+  // (ad-hoc) inputs, which have no card to move.
+  // Non-fatal by design: already-active, an invalid transition, or task-api
+  // being unavailable must never fail a dispatch that has otherwise succeeded
+  // — log one stderr line and continue.
+  if (!dryRun && taskInput && /^TASK_\d+$/i.test(taskInput)) {
+    try {
+      const projectArg = _saRoot !== ROOT ? ` --project-path "${_saRoot}"` : '';
+      execSync(
+        `node "${COLLABORATION_API}"${projectArg} move ${taskInput} active`,
+        { encoding: 'utf8', cwd: _saRoot, timeout: 10000, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] }
+      );
+      process.stderr.write(`[dispatch] Auto-activated: ${taskInput} → active/\n`);
+    } 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];
+      process.stderr.write(`[dispatch] Auto-activate skipped: ${msg}\n`);
+    }
+  }
+
+  // TASK_1998 R3: rigor + modelSource ride NEXT TO agentParams (same reason as
+  // modelTranslation/isolation — the Agent tool schema rejects unknown fields
+  // on agentParams itself). rigor is the NORMALIZED key (null/unrecognized →
+  // 'medium') that actually drove model resolution, not the raw card field.
+  // complexity is likewise the normalized CONTEXT-volume key.
+  return {
+    promptText, taskId: taskInput, formation, skill, dispatchMode, effectiveMode: 'subagent',
+    ...(isCodex ? { harness: 'codex', cwd: crossWorktree ? crossWorktree.worktreePath : null, worktreePath: crossWorktree ? crossWorktree.worktreePath : null } : {}),
+    modelTranslation, isolation, ...(agentParams ? { agentParams } : {}), rigor: resolution.rigorKey, complexity, modelSource: resolution.source,
+    ...(dryRun ? { dryRun: true } : {}),
+  };
+}
+
+/**
+ * TASK_1833: pre-create an isolated worktree INSIDE the target sub-project repo
+ * for a cross-project sub-agent dispatch. Naming matches the Formation path
+ * (formations.setupUnitWorktree: .formation/worktrees/task_<id>, branch
+ * task/<id>) so post-complete's worktree merge machinery finds it unchanged.
+ * Reuses utils.createWorktree — index.lock wait, retry/backoff, stale-branch
+ * and partial-dir cleanup all included. Throws on final failure (caller falls
+ * back to serialized shared-tree mode — never to unserialized writes).
+ * thrift: no MAX_PARALLEL semaphore / dirty-snapshot here (those live in the
+ * long-lived Formation process; this CLI exits immediately). Sub-agent
+ * cross-project dispatch is Ansuz-driven and low-fanout today — add the
+ * semaphore if parallel cross-project sub-agent dispatch becomes routine.
+ * @param {string} projectPath - target repo root
+ * @param {string} taskInput - TASK_XXX id or free-text description
+ * @returns {{ worktreePath: string, branchName: string }}
+ */
+function setupSubagentCrossProjectWorktree(projectPath, taskInput) {
+  const idBase = (taskInput && taskInput.startsWith('TASK_'))
+    ? taskInput.toLowerCase()
+    : `adhoc_${Date.now().toString(36)}`;
+  const worktreePath = path.join(projectPath, '.formation', 'worktrees', `task_${idBase}`);
+  const branchName = `task/${idBase}`;
+  // createWorktree logs progress via console.log (fine on the Formation path),
+  // but subagent mode's stdout is machine-readable JSON — redirect to stderr
+  // for the duration of the call so the payload stays parseable.
+  const origLog = console.log;
+  console.log = (...a) => console.error(...a);
+  let created;
+  try {
+    ensureWorktreeDirIgnored(projectPath);
+    created = createWorktree(projectPath, worktreePath, branchName);
+  } finally {
+    console.log = origLog;
+  }
+  // TASK_2067: createWorktree returns { reusedBranch, divergence } when it
+  // attached to a pre-existing task/<id> branch instead of creating a new
+  // one (e.g. a cancelled task resumed) -- surface it so the caller can
+  // report reuse in the dispatch payload instead of only in stderr logs.
+  return {
+    worktreePath,
+    branchName,
+    reusedBranch: !!(created && created.reusedBranch),
+    divergence: (created && created.divergence) || null,
+  };
+}
+
+module.exports = { dispatch, getSubagentDispatchParams, checkDispatchScopeGate, releaseDispatchLock, resolveDispatchIsolation, _getProvenSessionId, _getOwnConversationId, _isOwnClaimMarker, _buildCortexContext: buildCortexContext };