kenaz 0.0.0-stage → 0.3.2

package/core/.formation/tools/utils.js

@@ -0,0 +1,1020 @@
+/**
+ * Formation Utils
+ * 共用工具函數
+ */
+
+const { execSync, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const crypto = require('crypto');
+
+// 路徑常數
+const ROOT = path.resolve(__dirname, '..', '..');
+const FORMATION_DIR = path.resolve(__dirname, '..');
+const COLLABORATION_API = path.join(ROOT, '.collaboration', 'core', 'task-api.js');
+
+// Legacy constant — maintained for backward compatibility
+const LOG_DIR = path.join(FORMATION_DIR, 'logs');
+
+// ── TASK_2030: node_modules provisioning for Formation/cross-project worktrees ──
+// TASK_1844 built junction/symlink node_modules provisioning (linkNodeModules)
+// and the matching pre-remove guard (unlinkNodeModulesLinks) into the Agent-tool
+// WorktreeCreate hook (.claude/hooks/worktree-create.js) ONLY. Formation unit
+// worktrees and dispatch.js's cross-project target_repo_worktree both go through
+// utils.createWorktree/removeWorktree below, which never called either helper —
+// measured result: those worktrees get ZERO node_modules, and (worse) any
+// hand-built junction an agent adds is unprotected against the TASK_1844
+// traversal hazard (git worktree remove --force on Windows recurses THROUGH a
+// junction and empties the MAIN checkout's node_modules).
+// Fix: require the hook's exports lazily (GEN-008: path resolved from ROOT, not
+// hard-coded) and reuse them here — never copy the implementation. Requiring the
+// hook as a library is safe: require.main here is the caller's entry module
+// (headless.js/formations.js/a test file), never `undefined` and never the hook
+// module itself, so the hook's `require.main === undefined` WorktreeCreate-mode
+// branch never fires (see worktree-create.js's own entry-dispatch comment).
+let _wtCreateHook = undefined;
+function _loadWorktreeCreateHook() {
+  if (_wtCreateHook !== undefined) return _wtCreateHook;
+  try {
+    _wtCreateHook = require(path.join(ROOT, '.claude', 'hooks', 'worktree-create.js'));
+  } catch {
+    _wtCreateHook = null; // missing/broken hook file -> degrade to no linking, never crash dispatch
+  }
+  return _wtCreateHook;
+}
+
+/**
+ * Best-effort: link the main checkout's node_modules into `worktreePath`
+ * (see .claude/hooks/worktree-create.js linkNodeModules). Never throws —
+ * a bare worktree beats a failed dispatch.
+ */
+function linkNodeModulesBestEffort(projectRoot, worktreePath) {
+  const hook = _loadWorktreeCreateHook();
+  if (!hook || typeof hook.linkNodeModules !== 'function') return;
+  try { hook.linkNodeModules(projectRoot, worktreePath); }
+  catch (e) { console.warn(`   ⚠️  node_modules linking failed: ${(e && e.message) || 'unknown'}`); }
+}
+
+/**
+ * Best-effort: drop node_modules junctions/symlinks inside `worktreePath`
+ * BEFORE any `git worktree remove` (see .claude/hooks/worktree-create.js
+ * unlinkNodeModulesLinks). MANDATORY ahead of `git worktree remove --force` —
+ * Git for Windows recurses through a junction on removal and empties the link
+ * target (the main checkout's node_modules). Never throws.
+ */
+function unlinkNodeModulesBestEffort(worktreePath) {
+  const hook = _loadWorktreeCreateHook();
+  if (!hook || typeof hook.unlinkNodeModulesLinks !== 'function') return;
+  try { hook.unlinkNodeModulesLinks(worktreePath); }
+  catch (e) { console.warn(`   ⚠️  node_modules unlink failed: ${(e && e.message) || 'unknown'}`); }
+}
+
+/**
+ * Get the log directory for a given project.
+ * All projects (including KenazAI core) use .kenaz/logs/ when available.
+ * This eliminates the core vs sub-project distinction for path selection.
+ *
+ * @param {string} [projectPath] - Absolute path to project root
+ * @returns {string} Absolute path to log directory
+ */
+function getLogDir(projectPath) {
+  if (!projectPath) return LOG_DIR;
+
+  // .kenaz/logs/ takes priority for ALL projects (core included)
+  const kenazLogsDir = path.join(projectPath, '.kenaz', 'logs');
+  if (fs.existsSync(kenazLogsDir)) return kenazLogsDir;
+
+  // Fallback: default LOG_DIR
+  return LOG_DIR;
+}
+
+function generateSessionId() {
+  const injected = process.env.KENAZ_SESSION_ID?.trim();
+  if (injected) return injected;
+  const now = new Date();
+  const ts = now.toISOString().replace(/[-:T]/g, '').slice(0, 14);
+  const rand = crypto.randomBytes(2).toString('hex');
+  return `${ts.slice(0, 8)}-${ts.slice(8, 14)}-${rand}`;
+}
+
+let _gitBashCache = undefined;
+function detectGitBash() {
+  if (_gitBashCache !== undefined) return _gitBashCache;
+  try {
+    const gitPaths = execSync('where git', { encoding: 'utf8', windowsHide: true }).split('\n').map(l => l.trim()).filter(Boolean);
+    for (const gitPath of gitPaths) {
+      // 嘗試從每個 git.exe 路徑推導 bash.exe
+      // git.exe 可能在 cmd/git.exe 或 mingw64/bin/git.exe
+      // bash.exe 固定在 Git/bin/bash.exe
+      let dir = path.dirname(gitPath);
+      // 往上找到包含 bin/bash.exe 的 Git 根目錄
+      for (let i = 0; i < 4; i++) {
+        const bashPath = path.join(dir, 'bin', 'bash.exe');
+        if (fs.existsSync(bashPath)) { _gitBashCache = bashPath; return _gitBashCache; }
+        dir = path.dirname(dir);
+      }
+    }
+  } catch (e) {}
+
+  const fallbacks = [
+    'C:\\Program Files\\Git\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+    'D:\\Program Files\\Git\\bin\\bash.exe'
+  ];
+  for (const p of fallbacks) {
+    if (fs.existsSync(p)) { _gitBashCache = p; return _gitBashCache; }
+  }
+  _gitBashCache = null;
+  return null;
+}
+
+/**
+ * 偵測 claude 可執行檔路徑
+ * 優先順序：where/which → 獨立安裝（~/.claude/local/） → fallback
+ * 結果 memoize — 每個進程只呼叫一次 where claude
+ */
+let _claudeCmdCache = null;
+/**
+ * Choose the claude binary from `where claude` output (PATH order). The first
+ * hit is what the user's terminal runs. An npm shim (claude / claude.cmd) maps
+ * to the package's native bin/claude.exe, so no cmd.exe is spawned. The old
+ * rule "first .exe anywhere in the list" picked a stale WinGet install
+ * (2.1.248) over the npm one the user had updated (2.1.288), so every
+ * formation dispatch ran an older CLI than the terminal.
+ * @param {string[]} wherePaths  `where claude` lines, in PATH order
+ * @param {(p: string) => boolean} exists
+ * @returns {string}
+ */
+function pickClaudeFromWhere(wherePaths, exists) {
+  for (const p of wherePaths) {
+    if (/\.exe$/i.test(p)) return p;
+    const nativeExe = path.join(path.dirname(p), 'node_modules', '@anthropic-ai', 'claude-code', 'bin', 'claude.exe');
+    if (exists(nativeExe)) return nativeExe;
+    if (/\.cmd$/i.test(p)) return p;
+  }
+  return wherePaths.find(p => /\.exe$/i.test(p)) || wherePaths[0];
+}
+
+function detectClaudeCmd() {
+  if (_claudeCmdCache) return _claudeCmdCache;
+  if (process.platform !== 'win32') { _claudeCmdCache = 'claude'; return _claudeCmdCache; }
+
+  // 1. 嘗試 where claude（npm 安裝的 claude.cmd 或 PATH 中的 claude.exe）
+  // windowsHide:true 防止 cmd.exe 視窗閃現
+  try {
+    const result = execSync('where claude', { encoding: 'utf8', timeout: 5000, windowsHide: true })
+      .split('\n').map(l => l.trim()).filter(Boolean);
+    if (result.length > 0) {
+      _claudeCmdCache = pickClaudeFromWhere(result, fs.existsSync);
+      return _claudeCmdCache;
+    }
+  } catch (e) {}
+
+  // 2. 獨立安裝：~/.claude/local/claude.exe
+  const homedir = process.env.USERPROFILE || process.env.HOME || '';
+  const standalonePaths = [
+    path.join(homedir, '.claude', 'local', 'claude.exe'),
+    path.join(homedir, '.claude', 'bin', 'claude.exe'),
+  ];
+  for (const p of standalonePaths) {
+    if (fs.existsSync(p)) { _claudeCmdCache = p; return _claudeCmdCache; }
+  }
+
+  // 3. Fallback
+  _claudeCmdCache = 'claude.cmd';
+  return _claudeCmdCache;
+}
+
+function getClaudeEnv() {
+  const env = { ...process.env };
+
+  // 啟用 agent teams（與 Sunny 一致）
+  env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
+
+  // 移除 CLAUDECODE 避免 nested session 錯誤
+  delete env.CLAUDECODE;
+
+  // Windows: 設定 git-bash 路徑
+  if (process.platform === 'win32' && !env.CLAUDE_CODE_GIT_BASH_PATH) {
+    const gitBash = detectGitBash();
+    if (gitBash) env.CLAUDE_CODE_GIT_BASH_PATH = gitBash;
+  }
+  return env;
+}
+
+/**
+ * 確保子專案的 git 已就緒（有 .git/ + 至少一個 commit）
+ * 在 dispatch / headless 啟動 agent 前呼叫，避免 post-complete 時才補救。
+ *
+ * @param {string|null} projectPath - 子專案路徑（null = core，跳過）
+ */
+function ensureGitReady(projectPath) {
+  if (!projectPath) return;
+
+  // GIT_CEILING_DIRECTORIES：防止 git 向上遍歷到 Core 專案
+  const env = { ...process.env };
+  const parentDir = path.dirname(projectPath);
+  env.GIT_CEILING_DIRECTORIES = parentDir;
+
+  const gitDir = path.join(projectPath, '.git');
+  const execOpts = { cwd: projectPath, encoding: 'utf8', timeout: 15000, env, windowsHide: true };
+
+  // 1. 沒有 .git/ → git init
+  if (!fs.existsSync(gitDir)) {
+    console.log(`   📦 Sub-project has no .git/ — initializing...`);
+    try {
+      execSync('git init --initial-branch=main', execOpts);
+      console.log(`   ✅ git init completed`);
+    } catch {
+      try {
+        execSync('git init', execOpts);
+        execSync('git checkout -b main', execOpts);
+        console.log(`   ✅ git init completed (legacy git)`);
+      } catch (e) {
+        console.error(`   ❌ git init failed: ${e.message}`);
+        return;
+      }
+    }
+
+    // 建立基礎 .gitignore（如果不存在）
+    const gitignorePath = path.join(projectPath, '.gitignore');
+    if (!fs.existsSync(gitignorePath)) {
+      fs.writeFileSync(gitignorePath, [
+        'node_modules/', '__pycache__/', '*.pyc', 'venv/',
+        '.env', '.env.local', '*.db', '.chroma/',
+      ].join('\n') + '\n');
+      console.log(`   ✅ .gitignore created`);
+    }
+  }
+
+  // 2. 沒有 commit → initial commit
+  try {
+    execSync('git rev-parse HEAD', { ...execOpts, stdio: 'pipe', windowsHide: true });
+  } catch {
+    console.log(`   📦 Sub-project has no commits — creating initial commit...`);
+    try {
+      execSync('git add -A', execOpts);
+      // F3: Use -c flags to supply fallback identity when user has no global git config.
+      // This prevents "Author identity unknown" error that causes HEAD to not exist,
+      // which in turn makes git worktree add fail with "not a valid object name: HEAD".
+      execSync(
+        'git -c user.name="Kenaz AI" -c user.email="kenaz-ai@local" commit -m "Initial commit: Kenaz AI project setup" --allow-empty',
+        execOpts
+      );
+      console.log(`   ✅ Initial commit created`);
+    } catch (e) {
+      console.error(`   ❌ Initial commit failed: ${e.message}`);
+    }
+  }
+}
+
+/**
+ * Rewrite stash commands so merge/recovery flows preserve untracked workspace
+ * artifacts written outside the task diff (audit reports, notes, design docs).
+ * We only remove the explicit include-untracked flag; tracked edits still stash.
+ *
+ * @param {string} command
+ * @returns {string}
+ */
+function preserveUntrackedStashCommand(command) {
+  const raw = String(command || '');
+  if (!/\bstash\s+push\b/.test(raw)) return raw;
+  return raw
+    .replace(/\s--include-untracked(?=\s|$)/g, '')
+    .replace(/\s-u(?=\s|$)/g, '')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+}
+
+/**
+ * TASK_1775: Read worktree dispatch config for a project.
+ * Sources (later wins): defaults -> .kenaz/project.yaml -> env
+ * (FORMATION_WORKTREE_TIMEOUT_MS, FORMATION_USE_WORKTREE).
+ * project.yaml keys:
+ *   use_worktree: false        # top-level -- opt out of worktree isolation entirely
+ *   worktree:
+ *     timeout_ms: 120000       # git worktree add timeout (default 30000)
+ * @param {string|null} projectDir - Project root containing .kenaz/project.yaml
+ * useWorktreeSource records WHICH lever produced useWorktree, because the caller
+ * (resolveWorktreeDecision) reports it as diagnostics and folding env into the
+ * project-config label made an env-driven decision read as if project.yaml had
+ * said it — sending an operator to edit a file that already disagrees. The
+ * provenance is tracked here, at the single place each lever is read, rather
+ * than re-read by the caller (that would be the copy-the-check pattern).
+ * @returns {{ useWorktree: boolean, timeoutMs: number, useWorktreeSource: 'default'|'project-config'|'env' }}
+ */
+function readWorktreeConfig(projectDir) {
+  const cfg = { useWorktree: true, timeoutMs: 30000, useWorktreeSource: 'default' };
+  try {
+    const yamlPath = path.join(projectDir || ROOT, '.kenaz', 'project.yaml');
+    if (fs.existsSync(yamlPath)) {
+      const content = fs.readFileSync(yamlPath, 'utf-8');
+      // TASK_2259: explicit true is also project-config provenance (boolean unchanged: default is true).
+      const uwMatch = content.match(/^use_worktree:\s*(true|false)\b/m);
+      if (uwMatch) {
+        cfg.useWorktree = uwMatch[1] === 'true';
+        cfg.useWorktreeSource = 'project-config';
+      }
+      const lines = content.split(/\r?\n/);
+      const wIdx = lines.findIndex(l => /^worktree:\s*$/.test(l));
+      if (wIdx !== -1) {
+        for (let i = wIdx + 1; i < lines.length; i++) {
+          if (lines[i].trim() === '') continue;
+          if (!/^[ \t]/.test(lines[i])) break; // dedent -- worktree block ended
+          const m = lines[i].match(/^[ \t]+timeout_ms:\s*(\d+)\s*$/);
+          if (m) { cfg.timeoutMs = parseInt(m[1], 10); break; }
+        }
+      }
+    }
+  } catch { /* unreadable project.yaml -- keep defaults */ }
+  const envMs = parseInt(process.env.FORMATION_WORKTREE_TIMEOUT_MS || '', 10);
+  if (Number.isFinite(envMs) && envMs > 0) cfg.timeoutMs = envMs;
+  // TASK_1833: dispatch-time worktree toggle -- env wins over project.yaml
+  // (mirrors FORMATION_WORKTREE_TIMEOUT_MS). Set by `dispatch.js --use-worktree=...`
+  // or by the operator for headless launches:
+  //   FORMATION_USE_WORKTREE=false node .formation/tools/headless.js ...
+  const envUW = String(process.env.FORMATION_USE_WORKTREE || '').trim().toLowerCase();
+  if (envUW === 'false' || envUW === '0') { cfg.useWorktree = false; cfg.useWorktreeSource = 'env'; }
+  else if (envUW === 'true' || envUW === '1') { cfg.useWorktree = true; cfg.useWorktreeSource = 'env'; }
+  return cfg;
+}
+
+/**
+ * TASK_2176: pure parser for the top-level `verify_offline: <command>` key in
+ * project.yaml. Separated from the fs read (getVerifyOfflineCommand below) so
+ * verify-and-land.js's injectable-deps unit tests can exercise the exact same
+ * parsing logic through a fake fs without touching the real filesystem —
+ * single format authority shared by both consumers, not a second copy
+ * (same reasoning as dispatchLockStaleness above). A quoted value has its
+ * surrounding quotes stripped; the rest of the line is taken verbatim as the
+ * shell command (no inline-comment stripping — keep the command on one line,
+ * same convention as use_worktree/timeout_ms).
+ * @param {string} content - raw project.yaml text
+ * @returns {string|null} the command, or null when the key is absent/empty
+ */
+function parseVerifyOfflineFromYaml(content) {
+  const m = /^verify_offline:\s*(.+?)\s*$/m.exec(String(content || ''));
+  if (!m) return null;
+  const raw = m[1].trim();
+  if (!raw) return null;
+  return raw.replace(/^["']|["']$/g, '');
+}
+
+/**
+ * TASK_2176: reads `verify_offline` from a project's .kenaz/project.yaml.
+ * Per-project opt-in for a SINGLE heavyweight, offline (no network/service
+ * dependency) verification command, for projects whose authoritative check
+ * needs one shared tool a worktree agent cannot run concurrently (Unity/
+ * Unreal editor domain reload, a mobile build chain). dispatch.js surfaces
+ * this to the worktree agent as a non-authoritative self-check (see
+ * resolveDispatchIsolation); verify-and-land.js runs it as the authoritative,
+ * serialized gate on the main tree before merge (see stepVerifyOffline).
+ * Projects without the key are unaffected — returns null, today's behaviour.
+ * @param {string|null} projectDir - project root containing .kenaz/project.yaml
+ * @returns {string|null}
+ */
+function getVerifyOfflineCommand(projectDir) {
+  try {
+    const yamlPath = path.join(projectDir || ROOT, '.kenaz', 'project.yaml');
+    if (!fs.existsSync(yamlPath)) return null;
+    return parseVerifyOfflineFromYaml(fs.readFileSync(yamlPath, 'utf-8'));
+  } catch {
+    return null; // unreadable/corrupt project.yaml -- treat as "no key" (today's behaviour)
+  }
+}
+
+/**
+ * TASK_1833: THE worktree on/off decision for a dispatch. Single source of
+ * truth consumed by BOTH dispatch paths (formations.setupUnitWorktree on the
+ * Formation path, dispatch.js resolveDispatchIsolation on the sub-agent path).
+ * Do NOT copy this logic into a new call site -- the copy-the-check pattern has
+ * recurred twice already (rune_eb53038640e246dea32764f89b18bfa1); call it.
+ * Precedence: explicit dispatch-time override (CLI/MCP param) >
+ * env FORMATION_USE_WORKTREE > project .kenaz/project.yaml use_worktree > default true.
+ * NOTE the default: a project WITHOUT .kenaz/project.yaml defaults INTO worktree
+ * mode. Single-editor-bound projects (e.g. Unity: Library/, huge assets, one
+ * editor instance) must opt out via any of the three levers above.
+ * @param {string|null} projectDir - target project root
+ * @param {boolean|null} [override] - dispatch-time override (true/false); null = no override
+ * The three documented levers get three distinct source labels — a two-value
+ * provenance field for a three-lever decision misattributed every env override
+ * to project.yaml (measured 2026-07-31: project.yaml said false,
+ * FORMATION_USE_WORKTREE=true won, and source still read 'project-config').
+ * 'default' means no lever fired and the project simply inherited worktree mode,
+ * which is the case Unity-style single-editor projects most need to SEE.
+ * @returns {{ useWorktree: boolean, source: 'dispatch-param'|'env'|'project-config'|'default' }}
+ */
+function resolveWorktreeDecision(projectDir, override = null) {
+  if (override === true || override === false) {
+    return { useWorktree: override, source: 'dispatch-param' };
+  }
+  const cfg = readWorktreeConfig(projectDir);
+  return { useWorktree: cfg.useWorktree, source: cfg.useWorktreeSource };
+}
+
+/**
+ * TASK_1833: canonical dispatch-lock file path for a target project -- ONE
+ * naming scheme so Formation serial dispatches, sub-agent shared-tree
+ * dispatches, and forseti-verify L1 all serialize against the SAME lock.
+ * Formula is byte-compatible with the historical inline computation in
+ * formations.js setupUnitWorktree AND forseti-verify.js (line ~714) -- if you
+ * change it here, forseti-verify must move with it or the two stop excluding
+ * each other.
+ * @param {string|null} projectPath - target project root (null = core)
+ * @returns {string} absolute lock file path (lives in CORE .formation/)
+ */
+function dispatchLockPath(projectPath) {
+  const projectKey = (projectPath || 'default').replace(/[\\/:]/g, '_').toLowerCase();
+  return path.join(ROOT, '.formation', `.dispatch-lock-${projectKey}`);
+}
+
+function _pidAlive(pid) {
+  if (!pid || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (e) { return e.code === 'EPERM'; }
+}
+
+// TASK_1838: single staleness threshold for .dispatch-lock-* files, shared by
+// tryAcquireDispatchLock (break-on-acquire) and dispatch-registry
+// cleanupStaleLocks (sweep at dispatch start). Do NOT reintroduce a second
+// threshold: the 10min sweep threshold vs this 60min hold semantics was the
+// TTL-authority split that made a live TASK_1833 serial lock deletable.
+const DISPATCH_LOCK_STALE_MS = 3600000; // 60 minutes
+
+/**
+ * TASK_1838: THE staleness verdict for a dispatch-lock holder. Consumed by
+ * BOTH tryAcquireDispatchLock and dispatch-registry.cleanupStaleLocks -- do
+ * not inline a second age/pid check at a new call site (copy-the-check has
+ * recurred four times; see Decorative Guard sigil).
+ * pid:null holders (TASK_1833 sub-agent serial locks -- the dispatch CLI exits
+ * right after emitting params, so its pid proves nothing about the agent's
+ * liveness) are NEVER pidDead; only >=60min staleness or explicit post-merge
+ * release clears them.
+ * @param {object|null} holder - parsed lock-file JSON (null/corrupt => stale)
+ * @returns {{ stale: boolean, pidDead: boolean, ageMs: number }}
+ */
+function dispatchLockStaleness(holder) {
+  const ageMs = holder && holder.startedAt ? Date.now() - new Date(holder.startedAt).getTime() : Infinity;
+  const stale = !(ageMs < DISPATCH_LOCK_STALE_MS); // NaN/Infinity (corrupted/unreadable) => stale
+  const pidDead = !!(holder && holder.pid && !_pidAlive(holder.pid));
+  return { stale, pidDead, ageMs };
+}
+
+/**
+ * TASK_1833: single-attempt dispatch-lock acquisition shared by BOTH dispatch
+ * paths (formations.setupUnitWorktree serial loop + dispatch.js sub-agent
+ * serial_lock mode). Atomic create via wx flag; breaks stale (>60min),
+ * dead-pid, and corrupted-holder locks. Holders with pid:null (sub-agent
+ * locks -- the dispatch CLI exits immediately after emitting params, so its
+ * own pid proves nothing about the agent's liveness) are broken ONLY by
+ * staleness or explicit release (delete the lock file after merge).
+ * @param {string} lockFile - absolute lock file path (see dispatchLockPath)
+ * @param {object} meta - { sessionId, taskId, pid, holder? } -- startedAt is added here
+ * @returns {{ acquired: boolean, holder: object|null, broke?: object, brokeReason?: string, error?: Error }}
+ */
+function tryAcquireDispatchLock(lockFile, meta) {
+  const write = () => fs.writeFileSync(lockFile, JSON.stringify({
+    ...meta,
+    startedAt: new Date().toISOString(),
+  }), { flag: 'wx' });
+  try { fs.mkdirSync(path.dirname(lockFile), { recursive: true }); } catch { /* exists */ }
+  try { write(); return { acquired: true, holder: null }; }
+  catch (e) {
+    if (e.code !== 'EEXIST') return { acquired: false, holder: null, error: e };
+  }
+  let holder = null;
+  try { holder = JSON.parse(fs.readFileSync(lockFile, 'utf8')); } catch { /* corrupted -- treated as stale below */ }
+  const { stale, pidDead } = dispatchLockStaleness(holder);
+  if (stale || pidDead) {
+    try { fs.unlinkSync(lockFile); } catch { /* racing breaker */ }
+    try {
+      write();
+      return { acquired: true, holder: null, broke: holder || {}, brokeReason: pidDead ? 'dead-holder' : 'stale' };
+    } catch { /* lost the re-acquire race -- report as held */ }
+  }
+  return { acquired: false, holder };
+}
+
+/**
+ * TASK_1775: Kill a spawned git process AND its children.
+ * On Windows, execSync/spawnSync timeout only closes pipes / kills the direct
+ * child; `git worktree add` checkout work can keep running in the background.
+ * taskkill /T /F takes the whole tree down by PID.
+ * @param {number|undefined} pid
+ */
+function killGitProcessTree(pid) {
+  if (!pid) return;
+  try {
+    if (process.platform === 'win32') {
+      spawnSync('taskkill', ['/T', '/F', '/PID', String(pid)], {
+        windowsHide: true, timeout: 10000, stdio: 'ignore',
+      });
+    } else {
+      process.kill(pid, 'SIGKILL');
+    }
+  } catch { /* already dead -- nothing to kill */ }
+  // Wait for the process to actually die and release file handles (max 3s).
+  // taskkill returns before handles are released; cleaning up immediately
+  // races the dying checkout and rmSync fails EBUSY, leaving the branch
+  // "checked out" in a half-deleted worktree.
+  const deadline = Date.now() + 3000;
+  while (Date.now() < deadline) {
+    try { process.kill(pid, 0); } catch { return; /* ESRCH -- gone */ }
+    const w = Date.now() + 100; while (Date.now() < w) {}
+  }
+}
+
+/**
+ * TASK_1775: Delete a local branch ONLY if it has no unique commits vs baseRef.
+ * Never destroys a pre-existing user branch (or unmerged task work).
+ * @returns {boolean} true when the branch is gone (deleted or never existed)
+ */
+function deleteBranchIfSafe(projectRoot, branchName, baseRef) {
+  const opts = {
+    cwd: projectRoot, encoding: 'utf8', timeout: 10000, windowsHide: true,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  };
+  try {
+    execSync(`git rev-parse --verify --quiet "refs/heads/${branchName}"`, opts);
+  } catch { return true; /* branch doesn't exist -- nothing to delete */ }
+  try {
+    const unique = execSync(`git rev-list --count "${baseRef}..${branchName}"`, opts).trim();
+    if (unique !== '0') {
+      console.warn(`   ⚠️  Branch ${branchName} has ${unique} unique commit(s) vs ${baseRef} — NOT deleting`);
+      return false;
+    }
+    execSync(`git branch -D "${branchName}"`, opts);
+    return true;
+  } catch { return false; /* verification/delete failed -- leave the branch alone */ }
+}
+
+/**
+ * TASK_2175: is `worktreePath` currently a REGISTERED git worktree of
+ * `projectRoot` (i.e. `git worktree list` knows about it right now)?
+ * This is the one signal that actually distinguishes "a live worktree
+ * something else may depend on" from "an orphaned directory nothing has
+ * registered" — directory existence (`fs.existsSync`) cannot tell the two
+ * apart, which is what let cleanupFailedWorktreeAttempt wrongly treat a
+ * dirty/abandoned leftover the same as a concurrent sibling's live worktree
+ * (TASK_1610/1611 guard) and refuse to ever reclaim it.
+ * Fails safe: any error (git missing, not a repo, etc.) returns true so the
+ * caller's destructive path stays closed rather than opening on uncertainty.
+ */
+function isRegisteredWorktree(projectRoot, worktreePath) {
+  try {
+    const out = execSync('git worktree list --porcelain', {
+      cwd: projectRoot, encoding: 'utf8', timeout: 10000, windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const targetKey = path.resolve(worktreePath);
+    const norm = (p) => process.platform === 'win32' ? p.toLowerCase() : p;
+    for (const line of out.split('\n')) {
+      if (!line.startsWith('worktree ')) continue;
+      const wt = path.resolve(line.slice('worktree '.length).trim());
+      if (norm(wt) === norm(targetKey)) return true;
+    }
+    return false;
+  } catch { return true; /* can't verify -- assume registered, stay conservative */ }
+}
+
+/**
+ * TASK_1775: Clean the residue of a failed `git worktree add` attempt so the
+ * next retry doesn't die on 'branch already exists' or a stale partial dir.
+ * Order matters: rm partial dir -> prune metadata (releases the branch
+ * checkout claim) -> delete branch (guarded).
+ */
+function cleanupFailedWorktreeAttempt(projectRoot, worktreePath, branchName, baseRef, dirExistedBefore) {
+  // TASK_2175: `dirExistedBefore` alone used to gate this entirely ("only
+  // remove it when THIS attempt created it") — but that flag just means "did
+  // the path exist a moment ago", which is equally true for (a) a dirty
+  // leftover from an earlier, abandoned attempt at this SAME task_<id> path
+  // (ours to reclaim — nothing else uses this naming convention) and (b) a
+  // live sibling's worktree someone else may be mid-task on (never touch).
+  // `dirExistedBefore` cannot tell those apart; whether git itself still
+  // REGISTERS the path as a worktree can: an unregistered directory cannot be
+  // anyone's live worktree (git doesn't think anything is checked out there),
+  // so it is always safe to reclaim regardless of dirExistedBefore. A
+  // registered worktree is left untouched either way (TASK_1610/1611 guard).
+  const registered = isRegisteredWorktree(projectRoot, worktreePath);
+  // A killed-mid-add registration is LOCKED (.git/worktrees/<name>/locked) and
+  // git worktree prune NEVER prunes locked entries even with the dir gone --
+  // the branch stays "used by worktree". Unlock first; safe unconditionally
+  // since this exact path/branch naming convention (task_<id> / task/<id>)
+  // is ours alone -- no foreign process locks a path we constructed.
+  try {
+    execSync(`git worktree unlock "${worktreePath}"`, {
+      cwd: projectRoot, encoding: 'utf8', timeout: 10000, windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch { /* not locked / not registered */ }
+  if (!registered && fs.existsSync(worktreePath)) {
+    removeWorktree(projectRoot, worktreePath);
+    for (let i = 0; i < 5 && fs.existsSync(worktreePath); i++) {
+      try { fs.rmSync(worktreePath, { recursive: true, force: true }); } catch {}
+      if (fs.existsSync(worktreePath)) { const w = Date.now() + 400; while (Date.now() < w) {} }
+    }
+  }
+  try {
+    execSync('git worktree prune', {
+      cwd: projectRoot, encoding: 'utf8', timeout: 10000, windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch { /* prune failure is non-fatal */ }
+  deleteBranchIfSafe(projectRoot, branchName, baseRef);
+}
+
+/**
+ * Create a git worktree at the given path with a new branch.
+ * Deletes a stale same-named branch first (guarded -- see deleteBranchIfSafe).
+ * Includes .git/index.lock detection and retry with exponential backoff for Windows
+ * parallel-load resilience (ETIMEDOUT from competing git processes).
+ * TASK_1775: on timeout the spawned git process tree is killed, leftover
+ * branch/partial dir are cleaned between attempts, and the timeout is
+ * configurable (FORMATION_WORKTREE_TIMEOUT_MS / project.yaml worktree.timeout_ms).
+ * @param {string} projectRoot - Root of the git repo
+ * @param {string} worktreePath - Absolute path for the new worktree directory
+ * @param {string} branchName - New branch name for this worktree
+ */
+function createWorktree(projectRoot, worktreePath, branchName) {
+  const ts_start = Date.now();
+  const indexLock = path.join(projectRoot, '.git', 'index.lock');
+  const worktreeBranchCmd = 'git rev-parse --abbrev-ref HEAD';
+  const worktreeStatusCmd = 'git status --porcelain';
+  // TASK_1165: base from current branch HEAD, NOT origin/main.
+  // TASK_1180 verification: post-fix formation:feature dispatches TASK_1166..1172
+  // completed without reintroducing the stale-base worktree conflict pattern.
+  // origin/main may be 100+ commits behind the working branch (e.g. xyz951610)
+  // because we don't push feature work to main. Worktrees built from origin/main
+  // miss recent commits and produce massive rebase conflicts on completion.
+  // Detect current branch dynamically for cross-project safety.
+  let baseRef;
+  try {
+    baseRef = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: projectRoot, encoding: 'utf8', timeout: 5000, windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim() || 'HEAD';
+  } catch {
+    baseRef = 'HEAD';
+  }
+
+  // Wait for .git/index.lock to clear (Windows parallel git lock contention)
+  const waitForIndexLock = (maxMs) => {
+    const deadline = Date.now() + maxMs;
+    while (fs.existsSync(indexLock) && Date.now() < deadline) {
+      const w = Date.now() + 200; while (Date.now() < w) {}
+    }
+    if (fs.existsSync(indexLock)) {
+      console.warn(`   ⚠️  .git/index.lock still held after ${maxMs}ms — proceeding anyway`);
+    }
+  };
+
+  // Wait for any existing lock before branch cleanup
+  waitForIndexLock(15000);
+
+  if (fs.existsSync(worktreePath)) {
+    try {
+      const existingBranch = execSync(worktreeBranchCmd, {
+        cwd: worktreePath, encoding: 'utf8', timeout: 10000, windowsHide: true,
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+      const existingStatus = execSync(worktreeStatusCmd, {
+        cwd: worktreePath, encoding: 'utf8', timeout: 10000, windowsHide: true,
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+      if (existingBranch === branchName && !existingStatus) {
+        const duration = Date.now() - ts_start;
+        console.log(`   Reusing clean worktree: ${worktreePath} (${duration}ms)`);
+        // TASK_2030: idempotent -- linkNodeModules skips links that already exist.
+        linkNodeModulesBestEffort(projectRoot, worktreePath);
+        return;
+      }
+    } catch { /* existing path is not a reusable git worktree */ }
+  }
+
+  // TASK_1775: a previous process crashed/killed mid-add can leave a LOCKED
+  // registration (.git/worktrees/<name>/locked) claiming branchName; prune
+  // skips locked entries, so unlock first or the branch stays undeletable.
+  try {
+    execSync(`git worktree unlock "${worktreePath}"`, {
+      cwd: projectRoot, encoding: 'utf8', timeout: 10000, windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch { /* not locked / not registered */ }
+  try {
+    execSync('git worktree prune', {
+      cwd: projectRoot, encoding: 'utf8', timeout: 10000, windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch { /* prune failure is non-fatal */ }
+
+  // Clean up stale branch from a previous failed attempt.
+  // TASK_1775: guarded -- a branch with unique commits vs baseRef (unmerged
+  // work or a pre-existing user branch) is never force-deleted.
+  const branchDeleted = deleteBranchIfSafe(projectRoot, branchName, baseRef);
+
+  // TASK_2067: the branch survived the guard above (it has unique commits vs
+  // baseRef -- e.g. a cancelled cross-project task resumed: its worktree dir
+  // was removed but the branch with its committed work was correctly left
+  // alone) while the worktree PATH itself does not exist (checked above --
+  // if it existed we would have returned via the reuse-clean-worktree path).
+  // Without this, `git worktree add -b branchName` below dies on "a branch
+  // named '<branchName>' already exists" on every retry, and the caller
+  // (dispatch.js) degrades to serial_lock -- exactly the unserialized
+  // shared-tree risk this isolation path exists to prevent (field report
+  // ce1d12b6, TASK_1055). Attach the worktree to the EXISTING branch instead
+  // (no -b). Decision: never auto-merge baseRef into the reused branch --
+  // only report divergence -- so a resumed task's history is never rewritten
+  // without the operator seeing it. A branch genuinely checked out in another
+  // worktree still fails here (git surfaces "already checked out") and falls
+  // through to the normal create/retry loop below, whose existing error
+  // propagation is the correct outcome for that genuine failure.
+  if (!branchDeleted && !fs.existsSync(worktreePath)) {
+    const reuseTimeoutMs = readWorktreeConfig(projectRoot).timeoutMs;
+    const r = spawnSync('git', ['worktree', 'add', worktreePath, branchName], {
+      cwd: projectRoot, encoding: 'utf8', timeout: reuseTimeoutMs, windowsHide: true,
+    });
+    if (!r.error && r.status === 0) {
+      const duration = Date.now() - ts_start;
+      console.log(`   ♻️  Reused existing branch '${branchName}' for worktree (${duration}ms)`);
+      let divergence = null;
+      try {
+        const counts = execSync(`git rev-list --left-right --count "${baseRef}...${branchName}"`, {
+          cwd: projectRoot, encoding: 'utf8', timeout: 10000, windowsHide: true,
+          stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim().split(/\s+/).map(Number);
+        divergence = { behind: counts[0] || 0, ahead: counts[1] || 0 };
+        if (divergence.behind > 0) {
+          console.warn(`   ⚠️  Reused branch '${branchName}' is ${divergence.behind} commit(s) behind ${baseRef} (${divergence.ahead} ahead of it) -- NOT auto-merged; merge manually if needed.`);
+        }
+      } catch { /* best-effort divergence report only -- never fails the reuse */ }
+      linkNodeModulesBestEffort(projectRoot, worktreePath);
+      return { reusedBranch: true, divergence };
+    }
+    const errLines = (r.error ? r.error.message : (r.stderr || `git exited ${r.status}`))
+      .toString().trim().split('\n');
+    const errLine = errLines.find(l => l.includes('fatal:')) || errLines[0];
+    console.warn(`   ⚠️  Could not attach worktree to existing branch '${branchName}' (${errLine}) — falling back to normal creation, which will surface this as a genuine failure.`);
+  }
+
+  // F1: Remove stale worktree directory if it exists and is empty (or only has a .git pointer file).
+  // git worktree add refuses to create a worktree into a pre-existing directory, even if empty.
+  if (fs.existsSync(worktreePath)) {
+    const entries = fs.readdirSync(worktreePath).filter(e => e !== '.git');
+    if (entries.length === 0) {
+      fs.rmSync(worktreePath, { recursive: true, force: true });
+      console.log(`   🗑️  Removed stale empty worktree directory: ${worktreePath}`);
+    } else {
+      console.warn(`   ⚠️  Worktree directory exists and has files — skipping removal: ${worktreePath}`);
+    }
+  }
+
+  // Retry with exponential backoff: 3 retries at 2s, 4s, 8s
+  // TASK_1775: configurable timeout + orphan-git kill + per-attempt cleanup.
+  const timeoutMs = readWorktreeConfig(projectRoot).timeoutMs;
+  const retryDelays = [2000, 4000, 8000];
+  // TASK_2175: captured ONCE, before attempt 0 — NOT re-read every iteration.
+  // Bug this fixes: the old code re-ran `fs.existsSync(worktreePath)` inside
+  // the loop on every attempt, so if attempt 0's own cleanup left residue
+  // behind (a Windows file-lock stopping `removeWorktree`/`fs.rmSync` from
+  // fully clearing the dir — routine on this platform, see the retry/backoff
+  // scaffolding throughout this file), attempt 1 saw an "existing" dir and
+  // treated it as a pre-existing foreign worktree to leave alone, permanently
+  // poisoning cleanupFailedWorktreeAttempt for every remaining retry with the
+  // SAME "already exists" / "branch already exists" failure (measured,
+  // TASK_2175 repro: a single dirty leftover worktree dir makes all 4 attempts
+  // fail identically with zero progress). "Did this call start from a clean
+  // target" is decided once, from the state before we did anything.
+  const dirExistedBefore = fs.existsSync(worktreePath);
+  let lastErr;
+  for (let attempt = 0; attempt <= retryDelays.length; attempt++) {
+    if (attempt > 0) waitForIndexLock(10000);
+    // F2: Prune zombie .git/worktrees/ metadata before each attempt.
+    // If a previous worktree dir was deleted without `git worktree remove`, its metadata
+    // remains in .git/worktrees/ and causes "already checked out" errors on re-creation.
+    // git worktree prune is idempotent and fast (<100ms).
+    try {
+      execSync('git worktree prune', {
+        cwd: projectRoot, encoding: 'utf8', timeout: 10000, windowsHide: true,
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+    } catch { /* prune failure is non-fatal */ }
+    // TASK_1165: no fetch needed — base from local current branch HEAD.
+    // Removed `git fetch origin main` block from TASK_1152 since baseRef is no
+    // longer origin/main. Local current branch is always up to date.
+    // TASK_1775: spawnSync (not execSync) so the child PID is available — on
+    // ETIMEDOUT Windows only closes the pipes while the orphan git keeps
+    // checking out in the background; we must taskkill the tree by PID.
+    const r = spawnSync('git', ['worktree', 'add', worktreePath, '-b', branchName, baseRef], {
+      cwd: projectRoot, encoding: 'utf8', timeout: timeoutMs, windowsHide: true,
+    });
+    if (!r.error && r.status === 0) {
+      const duration = Date.now() - ts_start;
+      console.log(`   ⏱️  Worktree created in ${duration}ms (attempt ${attempt + 1}, timeout ${timeoutMs}ms)`);
+      // TASK_2030: provision node_modules so the dispatched agent doesn't hand-junction it.
+      linkNodeModulesBestEffort(projectRoot, worktreePath);
+      return;
+    }
+    const errLines = (r.error ? r.error.message : (r.stderr || `git exited ${r.status}`))
+      .toString().trim().split('\n');
+    const errLine = errLines.find(l => l.includes('fatal:')) || errLines[0];
+    lastErr = r.error || new Error(`git worktree add failed: ${errLine}`);
+    // Timeout / spawn error -> the git process tree may still be alive
+    if (r.error) killGitProcessTree(r.pid);
+    // Clean leftover branch + partial dir so the next attempt starts fresh
+    // instead of dying on 'branch already exists'.
+    cleanupFailedWorktreeAttempt(projectRoot, worktreePath, branchName, baseRef, dirExistedBefore);
+    if (attempt < retryDelays.length) {
+      const delay = retryDelays[attempt];
+      console.warn(`   ⚠️  Worktree attempt ${attempt + 1} failed: ${errLine}`);
+      console.warn(`   Retrying in ${delay / 1000}s...`);
+      const w = Date.now() + delay; while (Date.now() < w) {}
+    }
+  }
+
+  const duration = Date.now() - ts_start;
+  console.warn(`   ❌ Worktree creation failed after ${retryDelays.length + 1} attempts (${duration}ms)`);
+  throw lastErr;
+}
+
+/**
+ * Remove a git worktree with retry logic (Windows PDB/lock contention).
+ * Falls back to `git worktree prune` on total failure.
+ * @param {string} projectRoot
+ * @param {string} worktreePath
+ * @param {number} [maxRetries=3]
+ * @returns {boolean} true if removed successfully
+ */
+function removeWorktree(projectRoot, worktreePath, maxRetries = 3) {
+  // TASK_1844/TASK_2030: MUST run before any `git worktree remove` -- Git for
+  // Windows recurses through a node_modules junction/symlink on removal and
+  // empties the link target (the main checkout's node_modules).
+  unlinkNodeModulesBestEffort(worktreePath);
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      execSync(`git worktree remove --force "${worktreePath}"`, {
+        cwd: projectRoot, encoding: 'utf8', timeout: 30000, windowsHide: true,
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+      return true;
+    } catch {
+      if (i < maxRetries - 1) {
+        // Wait 1s before retry — Windows PDB lock typically releases within 1-2s
+        const wait = Date.now() + 1000;
+        while (Date.now() < wait) {}
+      }
+    }
+  }
+  // Last resort: prune stale .git/worktrees/ entries
+  try {
+    execSync('git worktree prune', {
+      cwd: projectRoot, encoding: 'utf8', timeout: 10000, windowsHide: true,
+      stdio: 'ignore'
+    });
+  } catch {}
+  return false;
+}
+
+/**
+ * Ensure `.formation/worktrees/` is listed in .gitignore.
+ * Prevents orphaned worktree files from appearing in `git status`.
+ * Idempotent — no-op if the entry already exists.
+ * @param {string} projectRoot
+ */
+function ensureWorktreeDirIgnored(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  const worktreeLine = '.formation/worktrees/';
+  try {
+    const content = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
+    if (!content.includes(worktreeLine)) {
+      fs.appendFileSync(gitignorePath, `\n# Formation worktrees (parallel agent isolation)\n${worktreeLine}\n`, 'utf8');
+    }
+  } catch { /* best-effort — non-fatal */ }
+}
+
+/**
+ * Read and parse .kenaz/dashboard-models.json for the given project.
+ * Returns null if the file is absent or unparseable.
+ * @param {string|null} projectPath
+ * @returns {object|null}
+ */
+function readDashboardModels(projectPath) {
+  const modelsPath = path.join(projectPath || ROOT, '.kenaz', 'dashboard-models.json');
+  try {
+    if (!fs.existsSync(modelsPath)) return null;
+    return JSON.parse(fs.readFileSync(modelsPath, 'utf-8'));
+  } catch { return null; }
+}
+
+/**
+ * TASK_2249: candidate-chain loader — project file first, then core (ROOT);
+ * the FIRST parseable file wins and is returned whole, so no field is ever
+ * mixed across two dashboard-models.json files. Null when none parses.
+ * @param {string|null} projectPath
+ * @returns {object|null}
+ */
+function loadDashboardModels(projectPath) {
+  const candidates = projectPath ? [projectPath, ROOT] : [ROOT];
+  for (const candidate of candidates) {
+    const parsed = readDashboardModels(candidate);
+    if (parsed) return parsed;
+  }
+  return null;
+}
+
+// TASK_1957: telemetry/daemon-noise paths that must never be swept into a task
+// commit by a blanket `git add -A` run inside an isolated worktree (Formation
+// unit worktree OR cross-project target_repo_worktree — dispatch.js). Root
+// cause of esp32 TASK_82/83: the sub-project's .kenaz/ and .formation/ are
+// tracked (only .kenaz/tasks + .kenaz/logs are gitignored), so `git add -A`
+// staged canary session files, progress notes, daemon state, and dispatch
+// telemetry into the task branch. Merging that branch into the sub-project's
+// main then collided with main's own LIVE copies of those same paths
+// ("local changes would be overwritten" / "untracked working tree files
+// would be overwritten").
+//
+// This list runs CLIENT-SIDE, at staging time, before any commit exists —
+// excluding here is strictly stronger than the post-merge unstage/revert
+// defenses in post-complete.js (daemon-manifest.yaml + getDaemonPathsToUnstage
+// + revertDaemonManagedFiles), which only clean up AFTER the noise is already
+// staged/committed and only cover paths enumerated in that manifest. Kept
+// deliberately coarse (whole directories, not the manifest's per-file list)
+// since it has to be a short, readable pathspec embedded in a dispatch
+// prompt's shell command line, not a manifest lookup.
+// A task that legitimately needs to edit a file under one of these
+// directories (e.g. daemon-manifest.yaml itself) must stage it explicitly
+// (`git add <path>`) rather than relying on the blanket `-A` step.
+const WORKTREE_COMMIT_EXCLUDE_PATHSPECS = [
+  ':!.kenaz/sessions',
+  ':!.kenaz/specialist',
+  ':!.formation/.dispatch-branch',
+  ':!.formation/analytics',
+  // Live channel heartbeat writer appends here continuously; swept into
+  // TASK_1977 and TASK_1979 commits before this exclusion was added.
+  ':!.kenaz/channel_heartbeats.jsonl',
+];
+
+/**
+ * Args (without the leading `git `) for an `add -A` that stages everything
+ * EXCEPT the telemetry paths in WORKTREE_COMMIT_EXCLUDE_PATHSPECS, using
+ * git's pathspec-exclude magic (`add -A -- . ":!path"`). Use this form when
+ * invoking through a wrapper that already prepends `git ` (e.g. git-merge.js's
+ * `git(cmd, opts)`).
+ *
+ * Double quotes, not single quotes (GEN-009 cross-platform): this string is
+ * embedded verbatim in a dispatch prompt's shell command line (POSIX sh/bash
+ * on the agent side) AND passed straight to Node's execSync (cmd.exe argv
+ * parsing on Windows — post-complete.js's own recovery-commit path runs this
+ * way). Double quotes are honored as a single argv token by both; a bare
+ * single quote is not special to cmd.exe and would reach git literally.
+ * @returns {string}
+ */
+function buildWorktreeGitAddArgs() {
+  const excludes = WORKTREE_COMMIT_EXCLUDE_PATHSPECS.map((p) => `"${p}"`).join(' ');
+  return `add -A -- . ${excludes}`;
+}
+
+/**
+ * Build a full `git add -A` shell command line that stages everything EXCEPT
+ * the telemetry paths in WORKTREE_COMMIT_EXCLUDE_PATHSPECS. Intended for use
+ * inside an ISOLATED worktree only (Formation unit worktree / cross-project
+ * target_repo_worktree) — a shared working tree must keep using explicit-paths
+ * staging instead.
+ * @returns {string} shell command line (no trailing `&&`/`;`)
+ */
+function buildWorktreeGitAddCommand() {
+  return `git ${buildWorktreeGitAddArgs()}`;
+}
+
+module.exports = {
+  ROOT,
+  FORMATION_DIR,
+  COLLABORATION_API,
+  LOG_DIR,
+  getLogDir,
+  generateSessionId,
+  detectGitBash,
+  detectClaudeCmd,
+  pickClaudeFromWhere,
+  getClaudeEnv,
+  ensureGitReady,
+  preserveUntrackedStashCommand,
+  createWorktree,
+  removeWorktree,
+  isRegisteredWorktree,
+  ensureWorktreeDirIgnored,
+  readWorktreeConfig,
+  resolveWorktreeDecision,
+  parseVerifyOfflineFromYaml,
+  getVerifyOfflineCommand,
+  dispatchLockPath,
+  DISPATCH_LOCK_STALE_MS,
+  dispatchLockStaleness,
+  tryAcquireDispatchLock,
+  readDashboardModels,
+  loadDashboardModels,
+  linkNodeModulesBestEffort,
+  unlinkNodeModulesBestEffort,
+  WORKTREE_COMMIT_EXCLUDE_PATHSPECS,
+  buildWorktreeGitAddCommand,
+  buildWorktreeGitAddArgs,
+};