kenaz 0.0.0-stage → 0.3.2

package/core/.formation/tools/legacy-scheduler.js

@@ -0,0 +1,1994 @@
+#!/usr/bin/env node
+/**
+ * Formation Legacy Scheduler (= Formation Lead)
+ *
+ * 以 Formation Lead 身份運行的連續調度排程器。
+ * 所有任務透過 Formation Legacy Skill 調度，不使用 /dev 或 /product-review CLI。
+ *
+ * 職責：
+ *   - 掃描 .collaboration + dev/pipeline 選擇 pending 任務
+ *   - 使用 Formation Skill 調度 subagent（headless 模式）
+ *   - subagent 自行完成任務移動（task-api.js complete）
+ *   - Scheduler 執行 post-complete（archive + git）— Formation Lead 職責
+ *   - 失敗時重置任務為 pending
+ *
+ * Usage:
+ *   node .formation/tools/legacy-scheduler.js
+ *   node .formation/tools/legacy-scheduler.js --dry-run
+ *   node .formation/tools/legacy-scheduler.js --initial-delay=0 --interval=5
+ *   node .formation/tools/legacy-scheduler.js --self-enhancement
+ */
+
+// Signal to task-api.js: scheduler handles post-complete centrally.
+// Prevents double post-complete (agent + scheduler both calling it).
+process.env.FORMATION_SCHEDULER = '1';
+
+// Prevent EPIPE crash when parent (dashboard) disconnects stdout/stderr pipe.
+// Without this, any console.log after pipe break throws → uncaughtException → crash.
+process.stdout.on('error', (err) => { if (err.code === 'EPIPE') return; throw err; });
+process.stderr.on('error', (err) => { if (err.code === 'EPIPE') return; throw err; });
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+const yaml = (() => { try { return require('js-yaml'); } catch { return require('../../.vendor/js-yaml.cjs'); } })();
+const { ROOT, LOG_DIR, getLogDir, generateSessionId } = require('./utils');
+const { loadSkill, loadTask } = require('./loader');
+const { buildPrompt, HEADLESS_PREFIX } = require('./prompt');
+const { runHeadless } = require('./runner');
+const { postComplete } = require('./post-complete');
+
+// Yggdrasil Layer 2: lazy-loaded modules (only init when first called)
+let _remoteConflict = null;
+let _taskSync = null;
+let _supabaseClient = null;
+function getRemoteConflict() {
+  if (!_remoteConflict) try { _remoteConflict = require('./remote-conflict'); } catch { _remoteConflict = false; }
+  return _remoteConflict || null;
+}
+function getTaskSync() {
+  if (!_taskSync) try { _taskSync = require('./task-sync'); } catch { _taskSync = false; }
+  return _taskSync || null;
+}
+function getSupabaseClient(projectPath) {
+  if (!_supabaseClient) try { _supabaseClient = require('./supabase-client'); } catch { _supabaseClient = false; }
+  if (!_supabaseClient) return null;
+  return _supabaseClient.getClient(projectPath);
+}
+
+/** Local date string YYYY-MM-DD (matches Rust chrono::Local) */
+function localDateStr() {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
+// ─────────────────────────────────────────
+// 常數（對應 Rust types.rs）
+// ─────────────────────────────────────────
+
+const Status = {
+  STOPPED: 'stopped',
+  WAITING: 'waiting',
+  RUNNING: 'running',
+  RUNNING_REVIEW: 'running_review',
+  PAUSED: 'paused',
+  COMPLETED: 'completed',
+  ERROR: 'error',
+  IDLE: 'idle',
+};
+
+const RunStatus = {
+  SUCCESS: 'success',
+  FAILED: 'failed',
+  TIMED_OUT: 'timed_out',
+  CANCELLED: 'cancelled',
+};
+
+const PRIORITY_ORDER = ['P0', 'P1', 'P2', 'P3'];
+const PENDING_STATUSES = ['pending', 'backlog', 'todo'];
+
+// ─────────────────────────────────────────
+// Scope Path Lock Manager（多實例並行協調）
+// ─────────────────────────────────────────
+
+const LOCKS_DIR = path.join(ROOT, '.collaboration', 'tasks', 'locks');
+
+class ScopeLockManager {
+  constructor() {
+    this.instanceId = `pid_${process.pid}`;
+    if (!fs.existsSync(LOCKS_DIR)) fs.mkdirSync(LOCKS_DIR, { recursive: true });
+  }
+
+  /** Read all active lock files, prune stale ones (dead processes) */
+  getActiveLocks() {
+    if (!fs.existsSync(LOCKS_DIR)) return [];
+    const locks = [];
+    for (const file of fs.readdirSync(LOCKS_DIR)) {
+      if (!file.endsWith('.lock')) continue;
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(LOCKS_DIR, file), 'utf8'));
+        // Check if the owning process is still alive
+        if (data.pid && !this._isProcessAlive(data.pid)) {
+          // Stale lock — remove it
+          try { fs.unlinkSync(path.join(LOCKS_DIR, file)); } catch {}
+          continue;
+        }
+        locks.push(data);
+      } catch {
+        // Corrupt lock file — remove
+        try { fs.unlinkSync(path.join(LOCKS_DIR, file)); } catch {}
+      }
+    }
+    return locks;
+  }
+
+  /** Check if a task's scope_paths conflict with any existing lock */
+  hasPathConflict(scopePaths) {
+    if (!scopePaths || scopePaths.length === 0) return false;
+    const locks = this.getActiveLocks();
+    for (const lock of locks) {
+      if (lock.instanceId === this.instanceId) continue; // own locks don't conflict
+      for (const lockedPath of (lock.scopePaths || [])) {
+        for (const sp of scopePaths) {
+          if (sp.startsWith(lockedPath) || lockedPath.startsWith(sp)) {
+            return true;
+          }
+        }
+      }
+    }
+    return false;
+  }
+
+  /** Acquire a scope lock for a task. Returns true if acquired. */
+  acquire(task) {
+    if (!task || !task.taskId) return true; // no-task runs don't need locks
+    const lockFile = path.join(LOCKS_DIR, `${task.taskId}.lock`);
+    // If lock already exists and isn't ours, fail
+    if (fs.existsSync(lockFile)) {
+      try {
+        const existing = JSON.parse(fs.readFileSync(lockFile, 'utf8'));
+        if (existing.instanceId !== this.instanceId && this._isProcessAlive(existing.pid)) {
+          return false; // another live instance holds this lock
+        }
+      } catch {}
+      // Stale or corrupt — overwrite
+    }
+    const lockData = {
+      taskId: task.taskId,
+      instanceId: this.instanceId,
+      pid: process.pid,
+      scopePaths: task.scopePaths || [],
+      acquiredAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(lockFile, JSON.stringify(lockData, null, 2), 'utf8');
+    return true;
+  }
+
+  /** Release scope lock for a task */
+  release(taskId) {
+    if (!taskId) return;
+    const lockFile = path.join(LOCKS_DIR, `${taskId}.lock`);
+    try { if (fs.existsSync(lockFile)) fs.unlinkSync(lockFile); } catch {}
+  }
+
+  /** Release all locks owned by this instance (cleanup on shutdown) */
+  releaseAll() {
+    if (!fs.existsSync(LOCKS_DIR)) return;
+    for (const file of fs.readdirSync(LOCKS_DIR)) {
+      if (!file.endsWith('.lock')) continue;
+      try {
+        const data = JSON.parse(fs.readFileSync(path.join(LOCKS_DIR, file), 'utf8'));
+        if (data.instanceId === this.instanceId) {
+          fs.unlinkSync(path.join(LOCKS_DIR, file));
+        }
+      } catch {}
+    }
+  }
+
+  /** Check if a process is still alive */
+  _isProcessAlive(pid) {
+    try {
+      process.kill(pid, 0); // signal 0 = check existence
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+// ─────────────────────────────────────────
+// Role → Legacy Skill 對應表
+// ─────────────────────────────────────────
+
+const ROLE_SKILL_MAP = {
+  developer: 'developer',
+  frontend: 'frontend',
+  backend: 'backend',
+  designer: 'designer',
+  qa: 'qa',
+  qa_engineer: 'qa',
+  sre: 'sre',
+  pm: 'pm',
+  product_manager: 'pm',
+};
+
+/**
+ * 將任務的 agentType/role 對應到 .formation/legacy/ 的 skill 名稱
+ * 未匹配的角色 fallback 到 'developer'（泛用開發者）
+ * @returns {string} skill 名稱
+ */
+function getLegacySkillName(agentType) {
+  const normalized = (agentType || '').toLowerCase().replace(/[-\s]/g, '_');
+  return ROLE_SKILL_MAP[normalized] || 'developer';
+}
+
+// ─────────────────────────────────────────
+// 設定載入（對應 Rust config.rs）
+// ─────────────────────────────────────────
+
+function loadConfig(overrides = {}) {
+  const configPath = path.join(ROOT, '.formation', 'legacy', 'scheduler.yaml');
+  let cfg = {};
+  if (fs.existsSync(configPath)) {
+    cfg = yaml.load(fs.readFileSync(configPath, 'utf8'));
+  }
+
+  const c = cfg.config || {};
+  const p = cfg.paths || {};
+
+  const rawConcurrency = overrides.concurrency ?? c.concurrency ?? 3;
+  const maxConcurrency = c.max_concurrency ?? 5;
+
+  // 子專案路徑（null = core）
+  const projectPath = overrides.projectPath || null;
+
+  // Log 目錄：所有有 projectPath 的專案統一用 getLogDir()
+  const logDir = projectPath
+    ? path.join(getLogDir(projectPath), 'legacy')
+    : path.join(ROOT, p.log_dir || '.formation/logs/legacy');
+
+  return {
+    concurrency: Math.min(Math.max(1, rawConcurrency), maxConcurrency),
+    maxConcurrency,
+    initialDelaySecs: overrides.initialDelay ?? c.initial_delay_secs ?? 5,
+    intervalMinutes: overrides.interval ?? c.interval_minutes ?? 20,
+    idleCheckSecs: overrides.idleCheck ?? c.idle_check_secs ?? 5,
+    earlyFinishDelaySecs: c.early_finish_delay_secs ?? 30,
+    devTimeoutMinutes: overrides.devTimeout ?? c.dev_timeout_minutes ?? 60,
+    reviewTimeoutMinutes: c.review_timeout_minutes ?? 30,
+    enableSelfEnhancement: overrides.selfEnhancement ?? c.enable_self_enhancement ?? false,
+    enableRemotePull: overrides.remotePull ?? c.enable_remote_pull ?? true,
+    idleTimeoutSecs: overrides.idleTimeout ?? c.idle_timeout_secs ?? 300,
+
+    // 子專案路徑（null = core）
+    projectPath,
+
+    tasksDir: path.join(ROOT, p.tasks_dir || 'dev/pipeline/tasks'),
+    completedDir: path.join(ROOT, p.completed_dir || 'dev/pipeline/completed'),
+    logDir,
+    statusFile: path.join(ROOT, p.status_file || 'dev/pipeline/SELF_ENHANCEMENT_STATUS.json'),
+    progressFile: path.join(ROOT, p.progress_file || 'dev/pipeline/PROGRESS.md'),
+  };
+}
+
+// ─────────────────────────────────────────
+// Logger（對應 Rust setup_log_writer / write_log）
+// ─────────────────────────────────────────
+
+class SchedulerLogger {
+  constructor(logDir, instanceId) {
+    if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
+    const date = localDateStr();
+    this.instanceId = instanceId || crypto.randomBytes(2).toString('hex');
+    this.logPath = path.join(logDir, `scheduler_${date}_${this.instanceId}.log`);
+    this.stream = fs.createWriteStream(this.logPath, { flags: 'a' });
+  }
+
+  write(message) {
+    const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    const line = `[${ts}] ${message}`;
+    try { console.log(line); } catch {}  // EPIPE if parent closed pipe
+    this.stream.write(line + '\n');
+  }
+
+  close() {
+    this.stream.end();
+  }
+}
+
+// ─────────────────────────────────────────
+// TaskSelector（對應 Rust task_selector.rs）
+// ─────────────────────────────────────────
+
+class TaskSelector {
+  constructor(config) {
+    this.projectPath = config.projectPath || null;
+    const projectRoot = this.projectPath || ROOT;
+
+    // Core fallback 路徑（僅供子專案 fallback 掃描用）
+    this.coreCollabBase = path.join(ROOT, '.collaboration', 'tasks');
+    this.coreTasksDir = config.tasksDir;
+    this.coreCompletedDir = config.completedDir;
+
+    // 統一路徑：所有有 projectPath 的專案（含 KenazAI 本體）都用 .kenaz/tasks/
+    if (this.projectPath) {
+      const kenazBase = path.join(projectRoot, '.kenaz', 'tasks');
+      const collabBase = path.join(projectRoot, '.collaboration', 'tasks');
+      // Primary base: prefer .kenaz/ if it exists
+      this.collabBase = fs.existsSync(kenazBase) ? kenazBase : collabBase;
+      // Pending dirs: scan BOTH .kenaz/ and .collaboration/
+      const pendingDirs = [];
+      for (const base of [kenazBase, collabBase]) {
+        for (const sub of ['backlog', 'todo']) {
+          const dir = path.join(base, sub);
+          if (!pendingDirs.includes(dir)) pendingDirs.push(dir);
+        }
+      }
+      this.collabPendingDirs = pendingDirs;
+      this.collabDoneDir = path.join(this.collabBase, 'done');
+      this.collabInProgressDir = path.join(this.collabBase, 'active');
+      this.tasksDir = path.join(projectRoot, 'dev', 'pipeline', 'tasks');
+      this.completedDir = path.join(projectRoot, 'dev', 'pipeline', 'completed');
+      this.corePendingDirs = null;
+      this.coreDoneDir = null;
+    } else {
+      // 無 projectPath（直接在 ROOT 執行）：使用原有路徑
+      this.tasksDir = config.tasksDir;
+      this.completedDir = config.completedDir;
+      this.collabBase = path.join(ROOT, '.collaboration', 'tasks');
+      this.collabPendingDirs = ['backlog', 'todo'].map(d => path.join(this.collabBase, d));
+      this.collabDoneDir = path.join(this.collabBase, 'done');
+      this.collabInProgressDir = path.join(this.collabBase, 'active');
+      this.corePendingDirs = null;
+      this.coreDoneDir = null;
+    }
+  }
+
+  /** 取得所有已完成的 task ID（新舊系統合併，含 core fallback）
+   *  done/ + archived/ 都算完成（archived 是從 done 移過去的） */
+  getCompletedIds() {
+    const ids = [];
+    const scanDir = (dir) => {
+      if (!dir || !fs.existsSync(dir)) return;
+      ids.push(...fs.readdirSync(dir)
+        .filter(f => f.startsWith('TASK_'))
+        .map(f => f.split('_').slice(0, 2).join('_')));
+    };
+
+    // 當前專案（sub-project 或 core）
+    scanDir(this.completedDir);  // 舊系統 completed/
+    scanDir(this.collabDoneDir); // 新系統 done/
+    // archived/ 也算完成（post-complete 可能已將 done 歸檔）
+    const archivedDir = path.join(path.dirname(this.collabDoneDir), 'archived');
+    scanDir(archivedDir);
+
+    return [...new Set(ids)];
+  }
+
+  /** 選擇最高優先級的 pending 任務（新舊系統合併，依賴已滿足）
+   *  @param {ScopeLockManager} [scopeLockMgr] - if provided, filter out tasks with path conflicts
+   *  @param {Set<string>} [excludeIds] - task IDs to skip (used for retry after claim failure)
+   *  @param {Set<string>} [remoteClaimedIds] - task IDs claimed by other nodes (Yggdrasil)
+   *  @returns {object|null} task object or null */
+  selectNextTask(scopeLockMgr, excludeIds, remoteClaimedIds) {
+    const completedIds = this.getCompletedIds();
+    const candidates = [];
+
+    // 1. 新系統：掃 backlog/ + todo/
+    for (const dir of this.collabPendingDirs) {
+      if (!fs.existsSync(dir)) continue;
+      const files = fs.readdirSync(dir).filter(f => f.startsWith('TASK_') && f.endsWith('.yaml'));
+      for (const file of files) {
+        const task = this._parseTaskFrom(dir, file, 'collab');
+        if (!task) continue;
+        if (!PENDING_STATUSES.includes(task.status)) continue;
+        if (task.dependencies.some(dep => !completedIds.includes(dep))) continue;
+        if (excludeIds && excludeIds.has(task.taskId)) continue;
+        candidates.push(task);
+      }
+    }
+
+    // 2. 舊系統：掃 dev/pipeline/tasks/
+    if (fs.existsSync(this.tasksDir)) {
+      const files = fs.readdirSync(this.tasksDir).filter(f => f.startsWith('TASK_') && f.endsWith('.yaml'));
+      for (const file of files) {
+        const task = this._parseTaskFrom(this.tasksDir, file, 'legacy');
+        if (!task) continue;
+        if (task.status !== 'pending') continue;
+        if (task.dependencies.some(dep => !completedIds.includes(dep))) continue;
+        // 避免重複（同一 taskId 已在新系統出現）
+        if (candidates.some(c => c.taskId === task.taskId)) continue;
+        if (excludeIds && excludeIds.has(task.taskId)) continue;
+        candidates.push(task);
+      }
+    }
+
+    // 3. Core fallback 新系統（子專案模式：也掃 core 的 backlog/ + todo/）
+    if (this.corePendingDirs) {
+      for (const dir of this.corePendingDirs) {
+        if (!fs.existsSync(dir)) continue;
+        const files = fs.readdirSync(dir).filter(f => f.startsWith('TASK_') && f.endsWith('.yaml'));
+        for (const file of files) {
+          const task = this._parseTaskFrom(dir, file, 'core-collab');
+          if (!task) continue;
+          if (!PENDING_STATUSES.includes(task.status)) continue;
+          if (task.dependencies.some(dep => !completedIds.includes(dep))) continue;
+          if (candidates.some(c => c.taskId === task.taskId)) continue;
+          candidates.push(task);
+        }
+      }
+    }
+
+    // Yggdrasil: 跳過已被其他 node claimed 的任務（避免重複 claim）
+    if (remoteClaimedIds && remoteClaimedIds.size > 0) {
+      for (let i = candidates.length - 1; i >= 0; i--) {
+        if (remoteClaimedIds.has(candidates[i].taskId)) {
+          console.log(`   🌍 Skipping ${candidates[i].taskId}: already claimed by another node`);
+          candidates.splice(i, 1);
+        }
+      }
+    }
+
+    let filtered = candidates;
+
+    // Scope lock filter：跳過路徑被其他實例鎖定的任務
+    if (scopeLockMgr) {
+      filtered = filtered.filter(t => {
+        if (scopeLockMgr.hasPathConflict(t.scopePaths)) {
+          console.log(`   🔒 Skipping ${t.taskId}: scope_paths locked by another instance`);
+          return false;
+        }
+        return true;
+      });
+    }
+
+    // Yggdrasil L2: Remote conflict filter — 跳過遠端節點正在處理的任務
+    const rc = getRemoteConflict();
+    if (rc) {
+      filtered = filtered.filter(t => {
+        const check = rc.hasRemoteConflict(t.scopePaths);
+        if (check.conflict) {
+          console.log(`   🌐 Skipping ${t.taskId}: scope_paths conflict with remote node ${check.conflictNode}`);
+          return false;
+        }
+        return true;
+      });
+    }
+
+    // 排序：priority (P0 first), then taskId
+    filtered.sort((a, b) => {
+      const pi = PRIORITY_ORDER.indexOf(a.priority) - PRIORITY_ORDER.indexOf(b.priority);
+      return pi !== 0 ? pi : a.taskId.localeCompare(b.taskId);
+    });
+
+    return filtered[0] || null;
+  }
+
+  /**
+   * 選取最多 n 個 pending 任務（並行用）
+   * @param {number} n - 最多選幾個
+   * @param {string[]} excludeScopes - 目前正在執行的 scope_paths（衝突排除）
+   * @param {Set<string>} [remoteClaimedIds] - task IDs claimed by other nodes (Yggdrasil)
+   * @returns {object[]} 任務陣列
+   */
+  selectNextTasks(n, excludeScopes = [], remoteClaimedIds) {
+    const completedIds = this.getCompletedIds();
+    const candidates = [];
+
+    // 1. 新系統：掃 backlog/ + todo/
+    for (const dir of this.collabPendingDirs) {
+      if (!fs.existsSync(dir)) continue;
+      const files = fs.readdirSync(dir).filter(f => f.startsWith('TASK_') && f.endsWith('.yaml'));
+      for (const file of files) {
+        const task = this._parseTaskFrom(dir, file, 'collab');
+        if (!task) continue;
+        if (!PENDING_STATUSES.includes(task.status)) continue;
+        if (task.dependencies.some(dep => !completedIds.includes(dep))) continue;
+        candidates.push(task);
+      }
+    }
+
+    // 2. 舊系統：掃 dev/pipeline/tasks/
+    if (fs.existsSync(this.tasksDir)) {
+      const files = fs.readdirSync(this.tasksDir).filter(f => f.startsWith('TASK_') && f.endsWith('.yaml'));
+      for (const file of files) {
+        const task = this._parseTaskFrom(this.tasksDir, file, 'legacy');
+        if (!task) continue;
+        if (task.status !== 'pending') continue;
+        if (task.dependencies.some(dep => !completedIds.includes(dep))) continue;
+        if (candidates.some(c => c.taskId === task.taskId)) continue;
+        candidates.push(task);
+      }
+    }
+
+    // 3. Core fallback 新系統（子專案模式：也掃 core 的 backlog/ + todo/）
+    if (this.corePendingDirs) {
+      for (const dir of this.corePendingDirs) {
+        if (!fs.existsSync(dir)) continue;
+        const files = fs.readdirSync(dir).filter(f => f.startsWith('TASK_') && f.endsWith('.yaml'));
+        for (const file of files) {
+          const task = this._parseTaskFrom(dir, file, 'core-collab');
+          if (!task) continue;
+          if (!PENDING_STATUSES.includes(task.status)) continue;
+          if (task.dependencies.some(dep => !completedIds.includes(dep))) continue;
+          if (candidates.some(c => c.taskId === task.taskId)) continue;
+          candidates.push(task);
+        }
+      }
+    }
+
+    // Yggdrasil: 跳過已被其他 node claimed 的任務（避免重複 claim）
+    if (remoteClaimedIds && remoteClaimedIds.size > 0) {
+      for (let i = candidates.length - 1; i >= 0; i--) {
+        if (remoteClaimedIds.has(candidates[i].taskId)) {
+          console.log(`   🌍 Skipping ${candidates[i].taskId}: already claimed by another node`);
+          candidates.splice(i, 1);
+        }
+      }
+    }
+
+    let filtered = candidates;
+
+    // Yggdrasil L2: Remote conflict filter — 跳過遠端節點正在處理的任務
+    const rc = getRemoteConflict();
+    if (rc) {
+      filtered = filtered.filter(t => {
+        const check = rc.hasRemoteConflict(t.scopePaths);
+        if (check.conflict) {
+          console.log(`   🌐 Skipping ${t.taskId}: scope_paths conflict with remote node ${check.conflictNode}`);
+          return false;
+        }
+        return true;
+      });
+    }
+
+    // 排序：priority (P0 first), then taskId
+    filtered.sort((a, b) => {
+      const pi = PRIORITY_ORDER.indexOf(a.priority) - PRIORITY_ORDER.indexOf(b.priority);
+      return pi !== 0 ? pi : a.taskId.localeCompare(b.taskId);
+    });
+
+    // 選取最多 n 個，排除與 excludeScopes 衝突的任務
+    const selected = [];
+    const usedScopes = [...excludeScopes];
+
+    for (const task of filtered) {
+      if (selected.length >= n) break;
+
+      // 衝突檢查：任務的 scope_paths 與已佔用的 scope 是否重疊
+      const hasConflict = task.scopePaths.length > 0 && task.scopePaths.some(sp =>
+        usedScopes.some(us => sp.startsWith(us) || us.startsWith(sp))
+      );
+
+      if (hasConflict) continue;
+
+      selected.push(task);
+      usedScopes.push(...task.scopePaths);
+    }
+
+    return selected;
+  }
+
+  /** 更新 YAML 檔案中的 status 欄位 */
+  updateTaskStatus(fileName, newStatus, sourceDir) {
+    const filePath = path.join(sourceDir || this.tasksDir, fileName);
+    if (!fs.existsSync(filePath)) return;
+    let content = fs.readFileSync(filePath, 'utf8');
+    content = content.replace(/^status:\s*.*/m, `status: "${newStatus}"`);
+    fs.writeFileSync(filePath, content, 'utf8');
+  }
+
+  /** 將任務標記為進行中（根據來源系統移動檔案）
+   *  @returns {boolean} true if successfully claimed, false if already taken */
+  markInProgress(task) {
+    const { fileName, source, sourceDir } = task;
+
+    if (source === 'collab' || source === 'core-collab') {
+      // 新系統：移到對應的 active/ 目錄
+      const base = source === 'core-collab' ? this.coreCollabBase : this.collabBase;
+      const activeDir = path.join(base, 'active');
+      if (!fs.existsSync(activeDir)) fs.mkdirSync(activeDir, { recursive: true });
+      const src = path.join(sourceDir, fileName);
+      if (!fs.existsSync(src)) return false; // 已被其他實例移走
+      try {
+        this.updateTaskStatus(fileName, 'active', sourceDir);
+        fs.renameSync(src, path.join(activeDir, fileName));
+        task.sourceDir = activeDir;
+        return true;
+      } catch (err) {
+        if (err.code === 'ENOENT') return false; // race: file moved between check and rename
+        throw err;
+      }
+    } else {
+      // 舊系統（legacy / core-legacy）：原地更新
+      this.updateTaskStatus(fileName, 'in_progress', sourceDir);
+      return true;
+    }
+  }
+
+  /** 將任務重置為 pending（根據來源系統移回原位） */
+  resetToPending(task) {
+    const { fileName, source, sourceDir } = task;
+
+    if (source === 'collab' || source === 'core-collab') {
+      // 新系統：移回對應的 backlog/
+      const base = source === 'core-collab' ? this.coreCollabBase : this.collabBase;
+      const backlogDir = path.join(base, 'backlog');
+      if (!fs.existsSync(backlogDir)) fs.mkdirSync(backlogDir, { recursive: true });
+      const src = path.join(sourceDir, fileName);
+      if (!fs.existsSync(src)) return; // 已被移走（subagent 可能已 complete）
+      this.updateTaskStatus(fileName, 'pending', sourceDir);
+      fs.renameSync(src, path.join(backlogDir, fileName));
+      task.sourceDir = backlogDir;
+    } else {
+      // 舊系統（legacy / core-legacy）：原地更新
+      const src = path.join(sourceDir, fileName);
+      if (!fs.existsSync(src)) return;
+      this.updateTaskStatus(fileName, 'pending', sourceDir);
+    }
+  }
+
+  /** 將任務移動到 completed（根據來源系統） */
+  moveToCompleted(task) {
+    const { fileName, source, sourceDir } = task;
+
+    if (source === 'collab' || source === 'core-collab') {
+      // 新系統：移到對應的 done/ 目錄
+      const doneDir = source === 'core-collab' ? this.coreDoneDir : this.collabDoneDir;
+      if (!fs.existsSync(doneDir)) {
+        fs.mkdirSync(doneDir, { recursive: true });
+      }
+      const src = path.join(sourceDir, fileName);
+      const dst = path.join(doneDir, fileName);
+
+      // subagent 可能已透過 task-api.js complete 移動，檢查是否已在 done/
+      if (fs.existsSync(dst)) {
+        // 已在 done/，清理 active/ 殘留（如果有）
+        if (fs.existsSync(src)) {
+          try { fs.unlinkSync(src); } catch {}
+        }
+        return;
+      }
+
+      if (!fs.existsSync(src)) {
+        // 來源不在 active/ 也不在 done/ — 可能被其他流程移走
+        return;
+      }
+
+      // 只有當來源檔案存在時才更新狀態並移動
+      try {
+        this.updateTaskStatus(fileName, 'done', sourceDir);
+        fs.renameSync(src, dst);
+      } catch (err) {
+        // 處理可能的 race condition（在檢查與移動之間檔案被移走）
+        if (err.code === 'ENOENT' && fs.existsSync(dst)) {
+          if (fs.existsSync(src)) {
+            try { fs.unlinkSync(src); } catch {}
+          }
+        } else {
+          throw err;
+        }
+      }
+    } else {
+      // 舊系統（legacy / core-legacy）：移到對應的 completed/
+      const completedDir = source === 'core-legacy' ? this.coreCompletedDir : this.completedDir;
+      const tasksDir = source === 'core-legacy' ? this.coreTasksDir : this.tasksDir;
+      if (!fs.existsSync(completedDir)) {
+        fs.mkdirSync(completedDir, { recursive: true });
+      }
+      const src = path.join(tasksDir, fileName);
+      const dst = path.join(completedDir, fileName);
+
+      // 同上：subagent 可能已完成移動
+      if (fs.existsSync(dst)) {
+        if (fs.existsSync(src)) {
+          try { fs.unlinkSync(src); } catch {}
+        }
+        return;
+      }
+
+      if (!fs.existsSync(src)) {
+        return;
+      }
+
+      // 只有當來源檔案存在時才更新狀態並移動
+      try {
+        this.updateTaskStatus(fileName, 'completed', tasksDir);
+        fs.renameSync(src, dst);
+      } catch (err) {
+        // 處理可能的 race condition（在檢查與移動之間檔案被移走）
+        if (err.code === 'ENOENT' && fs.existsSync(dst)) {
+          if (fs.existsSync(src)) {
+            try { fs.unlinkSync(src); } catch {}
+          }
+        } else {
+          throw err;
+        }
+      }
+    }
+  }
+
+  _parseTaskFrom(dir, fileName, source) {
+    try {
+      const content = fs.readFileSync(path.join(dir, fileName), 'utf8');
+      const raw = yaml.load(content);
+      if (!raw) return null;
+
+      const taskId = raw.id || fileName.split('_').slice(0, 2).join('_');
+      return {
+        taskId,
+        title: raw.title || taskId,
+        agentType: raw.agent_type || raw.role || 'unknown',
+        priority: (raw.priority || 'P3').toUpperCase(),
+        status: (raw.status || 'pending').toLowerCase(),
+        dependencies: Array.isArray(raw.dependencies) ? raw.dependencies : (raw.dependencies ? [raw.dependencies] : []),
+        scopePaths: Array.isArray(raw.scope_paths) ? raw.scope_paths : (raw.scope_paths ? [raw.scope_paths] : []),
+        tags: Array.isArray(raw.tags) ? raw.tags : (raw.tags ? [raw.tags] : []),
+        keywords: raw.keywords || [],
+        commitMessage: raw.commit_message || null,
+        fileName,
+        source,         // 'collab' | 'legacy'
+        sourceDir: dir,  // 實際目錄路徑
+      };
+    } catch {
+      return null;
+    }
+  }
+}
+
+// ─────────────────────────────────────────
+// ProgressInfo（對應 Rust check_pending_tasks）
+// ─────────────────────────────────────────
+
+function checkPendingTasks(config) {
+  const info = {
+    hasPendingTasks: false,
+    pendingCount: 0,
+    activeCount: 0,
+    completedCount: 0,
+    totalCount: 0,
+  };
+
+  const countYaml = (dir) => {
+    if (!fs.existsSync(dir)) return 0;
+    return fs.readdirSync(dir).filter(f => f.startsWith('TASK_') && f.endsWith('.yaml')).length;
+  };
+
+  const projectRoot = config.projectPath || ROOT;
+
+  // 掃 .kenaz/tasks/ + .collaboration/tasks/（兩者都掃）
+  const kenazBase = path.join(projectRoot, '.kenaz', 'tasks');
+  const collabBase = path.join(projectRoot, '.collaboration', 'tasks');
+  const primaryBase = (config.projectPath && fs.existsSync(kenazBase))
+    ? kenazBase
+    : collabBase;
+
+  // pending（backlog/ + todo/）— scan primary + fallback
+  info.pendingCount += countYaml(path.join(primaryBase, 'backlog'));
+  info.pendingCount += countYaml(path.join(primaryBase, 'todo'));
+  // Also scan .collaboration/ if primary was .kenaz/ (migration period)
+  if (primaryBase === kenazBase) {
+    info.pendingCount += countYaml(path.join(collabBase, 'backlog'));
+    info.pendingCount += countYaml(path.join(collabBase, 'todo'));
+  }
+
+  // [merge: main] active 統計（main 新增，{git_user} 無此項）
+  info.activeCount += countYaml(path.join(primaryBase, 'active'));
+
+  // completed（done/）
+  info.completedCount += countYaml(path.join(primaryBase, 'done'));
+
+  // 舊系統 pending（dev/pipeline/tasks/）— config.tasksDir 是 core 路徑
+  info.pendingCount += countYaml(config.tasksDir);
+
+  // 舊系統 completed（dev/pipeline/completed/）— config.completedDir 是 core 路徑
+  if (fs.existsSync(config.completedDir)) {
+    info.completedCount += fs.readdirSync(config.completedDir)
+      .filter(f => f.startsWith('TASK_')).length;
+  }
+
+  // 子專案模式不再 fallback 到 core（專案隔離）
+  info.totalCount = info.pendingCount + info.activeCount + info.completedCount;
+  info.hasPendingTasks = info.pendingCount > 0;
+
+  return info;
+}
+
+/**
+ * 透過 Formation Legacy Skill 執行任務
+ * 使用 loadSkill → buildPrompt → runHeadless 完整鏈路
+ *
+ * 分兩階段：
+ *   1. Loading phase（sync）：載入 skill + task + 建構 prompt
+ *   2. Spawn phase（async）：啟動 child process，回傳 Promise
+ *
+ * Loading phase 在 Promise 外完成，確保 fillSlots 的 for 迴圈中
+ * 多個 spawn 可以連續啟動，不被 execSync 阻塞。
+ *
+ * @param {object} task - taskSelector 回傳的任務物件
+ * @param {string} skillName - .formation/legacy/ 下的 skill 名稱
+ * @param {object} config - scheduler config
+ * @param {object} logger - scheduler logger
+ * @returns {Promise<{exitCode, status, stdout, timedOut}>}
+ */
+function runWithFormation(task, skillName, config, logger, opts = {}) {
+  // 使用預載資料（fillSlots 批量載入）或即時載入（fallback）
+  const prepared = opts._prepared;
+  const loadOpts = opts.projectPath ? { projectPath: opts.projectPath } : undefined;
+  const skillDef = prepared?.skillDef ?? loadSkill('legacy', skillName);
+  const taskData = prepared?.taskData ?? loadTask(task.taskId, loadOpts);
+  const prompt = prepared?.prompt ?? buildPrompt(skillDef, task.taskId, taskData);
+  const sessionId = prepared?.sessionId ?? generateSessionId();
+
+  logger.write(`Formation: skill=${skillName}, session=${sessionId}`);
+
+  // Inject canary with real task/scope binding
+  let finalPrompt = HEADLESS_PREFIX + prompt;
+  let coherenceToken = null;
+  try {
+    const canary = require('../../.specialist/tools/canary');
+    let taskScopePaths = [];
+    if (taskData) {
+      try { taskScopePaths = JSON.parse(taskData).scope_paths || []; } catch { /* non-JSON */ }
+    }
+    const canaryResult = canary.generate({
+      session: sessionId,
+      specialist: 'legacy',
+      task: task.taskId || 'none',
+      scope: taskScopePaths.join(','),
+    }, config.projectPath);
+    finalPrompt = canaryResult.block + '\n\n' + finalPrompt;
+    coherenceToken = canaryResult.coherenceToken;
+  } catch (err) {
+    logger.write(`Canary injection skipped: ${err.message}`);
+  }
+
+  // ── Phase 2: Spawn（async，child process 在此啟動） ──
+  return new Promise((resolve) => {
+    // [merge: main + {git_user}] sessionShort 標記 (main) + projectPath ({git_user})
+    const sessionShort = sessionId.slice(-4);
+    let lastActivityTime = Date.now();
+
+    const child = runHeadless({
+      prompt: finalPrompt,
+      formation: 'legacy',
+      skill: skillName,
+      sessionId,
+      silent: true,
+      onLog: (line) => {
+        logger.write(line.replace(/\[Agent\]/g, `[Agent#${sessionShort}]`));
+        lastActivityTime = Date.now();
+      },
+      projectPath: config.projectPath,
+      coherenceToken,
+    });
+
+    let timedOut = false;
+    let drifted = false;
+
+    // ── Canary drift detection: kill agent on context pollution ──
+    child.on('formation:drift', (reason) => {
+      if (drifted) return; // prevent double-fire
+      drifted = true;
+      logger.write(`🐦 CANARY DRIFT detected for ${task.taskId}: ${reason}`);
+      logger.write(`   Killing agent and scheduling retry with fresh context...`);
+      forceKillAndResolve();
+    });
+
+    /**
+     * Kill child process tree (Windows-safe).
+     * On Windows, child.kill() only kills the shell (cmd.exe), not the
+     * actual claude process underneath. Use taskkill /f /t to kill the
+     * entire process tree. Also schedules a failsafe done() call in case
+     * the 'close' event never fires.
+     */
+    const forceKillAndResolve = () => {
+      if (!child.pid) return;
+      try {
+        if (process.platform === 'win32') {
+          execSync(`taskkill /pid ${child.pid} /f /t`, { stdio: 'ignore', timeout: 5000, windowsHide: true });
+        } else {
+          child.kill('SIGKILL');
+        }
+      } catch {}
+      // Failsafe: if 'close' event doesn't fire within 15s, force-resolve
+      setTimeout(() => done(1), 15_000);
+    };
+
+    // Total execution timeout
+    const timeoutMinutes = opts.timeoutMinutes || config.devTimeoutMinutes;
+    const timeoutMs = timeoutMinutes * 60 * 1000;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      forceKillAndResolve();
+    }, timeoutMs);
+
+    // Idle watchdog: kill if no log output for idleTimeoutSecs (0 = disabled)
+    const idleTimeoutSecs = config.idleTimeoutSecs || 0;
+    const idleWatchdog = idleTimeoutSecs > 0 ? setInterval(() => {
+      const idleSecs = Math.round((Date.now() - lastActivityTime) / 1000);
+      if (idleSecs >= idleTimeoutSecs) {
+        logger.write(`⚠️ IDLE WATCHDOG: Agent#${sessionShort} no output for ${idleSecs}s — killing`);
+        timedOut = true;
+        forceKillAndResolve();
+        clearInterval(idleWatchdog);
+      }
+    }, 30_000) : null;
+
+    let resolved = false;
+    const done = (code) => {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      if (idleWatchdog) clearInterval(idleWatchdog);
+      resolve({
+        exitCode: code ?? 1,
+        status: drifted ? RunStatus.FAILED
+          : timedOut ? RunStatus.TIMED_OUT
+          : (code === 0 ? RunStatus.SUCCESS : RunStatus.FAILED),
+        stdout: '',
+        timedOut,
+        drifted,
+      });
+    };
+
+    child.on('close', done);
+    child.on('formation:done', done);
+  });
+}
+
+/**
+ * 執行單個任務（從 runDevAgent 拆出的核心邏輯）
+ * @param {object} prepared - 預載的 Formation 資料（可選，由 fillSlots 批量載入）
+ * @returns {Promise<{status, exitCode, durationSecs, targetTask}>}
+ */
+async function executeTask(task, config, logger, prepared = null, scopeLockMgr = null) {
+  const startTime = Date.now();
+  let result;
+
+  if (task.agentType === 'lead') {
+    // ── Lead-only 任務：Scheduler 自己處理（不派 subagent） ──
+    logger.write(`Lead-only task detected: ${task.taskId} — handling directly`);
+
+    try {
+      const commitMsg = task.commitMessage || `[${task.taskId}] ${task.title}`;
+      if (!config.projectPath) {
+        logger.write(`⚠️  Lead postComplete: projectPath is null — will use ROOT (${ROOT})`);
+      }
+      postComplete({ taskId: task.taskId, message: commitMsg, projectPath: config.projectPath });
+      logger.write(`Lead task completed: post-complete done for ${task.taskId}`);
+
+      try {
+        const projectArg = config.projectPath ? ` --project-path "${config.projectPath}"` : '';
+        execSync(`node .collaboration/core/task-api.js${projectArg} complete ${task.taskId}`, {
+          encoding: 'utf8', cwd: config.projectPath || ROOT, timeout: 10000, windowsHide: true,
+        });
+        logger.write(`Task ${task.taskId} marked as done via task-api`);
+      } catch (e) {
+        logger.write(`Warning: task-api complete failed: ${e.message}`);
+      }
+
+      result = { exitCode: 0, status: RunStatus.SUCCESS, stdout: '' };
+    } catch (e) {
+      logger.write(`Lead task failed: ${e.message}`);
+      result = { exitCode: 1, status: RunStatus.FAILED, stdout: '' };
+    }
+  } else {
+    // ── 一般任務：派給 subagent 執行 ──
+    const skillName = prepared?.skillName || getLegacySkillName(task.agentType);
+    logger.write(`Using Formation Legacy skill: ${skillName} (from role: ${task.agentType})`);
+    result = await runWithFormation(task, skillName, config, logger, { _prepared: prepared, projectPath: config.projectPath });
+  }
+
+  const durationSecs = Math.round((Date.now() - startTime) / 1000);
+  logger.write(`[${task.taskId}] Execution completed: exit=${result.exitCode}, status=${result.status}, duration=${durationSecs}s`);
+  if (result.stdout) {
+    logger.write(`Output:\n${result.stdout}`);
+  }
+
+  // Release scope lock after task completes (success or failure)
+  if (task) {
+    if (scopeLockMgr) scopeLockMgr.release(task.taskId);
+    logger.write(`Scope lock released for ${task.taskId}`);
+
+    // Filesystem-level cleanup: remove active/ residuals and lock files
+    // (git checkout during post-complete can restore committed copies)
+    if (task.source === 'collab' && result.status === RunStatus.SUCCESS) {
+      const taskRoot = config.projectPath || ROOT;
+      // 子專案: .kenaz/tasks/  Core: .collaboration/tasks/
+      const tasksBase = fs.existsSync(path.join(taskRoot, '.kenaz', 'tasks'))
+        ? path.join(taskRoot, '.kenaz', 'tasks')
+        : path.join(taskRoot, '.collaboration', 'tasks');
+      const activeDir = path.join(tasksBase, 'active');
+      const doneDir = path.join(tasksBase, 'done');
+      try {
+        const activeFiles = fs.readdirSync(activeDir).filter(f => f.startsWith(task.taskId));
+        const inDone = fs.readdirSync(doneDir).some(f => f.startsWith(task.taskId));
+        if (inDone) {
+          for (const f of activeFiles) {
+            fs.unlinkSync(path.join(activeDir, f));
+            logger.write(`Cleaned residual: active/${f}`);
+          }
+        }
+      } catch {}
+    }
+
+    // Clear task info marker so Dashboard reverts card to idle color
+    console.log('##TASK_CLEAR:');
+  }
+
+  return {
+    status: result.status,
+    exitCode: result.exitCode,
+    durationSecs,
+    targetTask: task.taskId,
+  };
+}
+
+/**
+ * 處理任務完成後的狀態同步
+ */
+function handleTaskResult(task, result, taskSelector, logger, config) {
+  if (task.agentType === 'lead') {
+    if (result.status !== RunStatus.SUCCESS) {
+      taskSelector.resetToPending(task);
+      logger.write(`Lead task ${task.taskId} reset to pending for retry`);
+    }
+    return;
+  }
+
+  if (result.status === RunStatus.SUCCESS) {
+    logger.write(`Task ${task.taskId} completed by subagent (${task.source})`);
+
+    // Safety net: ensure task is moved to done/ (agent may have failed to call task-api complete,
+    // or restoreTaskFiles may have undone the move after git operations)
+    taskSelector.moveToCompleted(task);
+    logger.write(`Task ${task.taskId} ensured in done/`);
+
+    // Yggdrasil L2: 同步 done 狀態到 Supabase
+    const ts = getTaskSync();
+    if (ts) {
+      ts.syncTaskStatus({
+        taskId: task.taskId,
+        status: 'done',
+        projectPath: config?.projectPath || null,
+      }).catch(() => {});
+    }
+
+    // Guard: validate projectPath before post-complete to prevent cross-project git contamination
+    const effectiveProjectPath = config?.projectPath || null;
+    if (!effectiveProjectPath) {
+      logger.write(`⚠️  postComplete: projectPath is null/undefined — will use ROOT (${ROOT}). If this is a sub-project task, this is a bug.`);
+    }
+
+    let mergeOk = false;
+    try {
+      const pcResult = postComplete({ taskId: task.taskId, projectPath: effectiveProjectPath });
+
+      // Check if git operations succeeded
+      // pcResult.git = { committed, merged, noChanges, taskBranch, ... }
+      if (pcResult?.git && pcResult.git.committed && !pcResult.git.merged) {
+        logger.write(`❌ Post-complete: committed on ${pcResult.git.taskBranch} but merge FAILED for ${task.taskId}`);
+        logger.write(`   → Resetting to pending — code is NOT on working branch`);
+        taskSelector.resetToPending(task);
+        return;
+      }
+      // Detect: had changes but commit failed (e.g., stash pop lost the changes)
+      if (pcResult?.git && !pcResult.git.committed && !pcResult.git.noChanges) {
+        logger.write(`❌ Post-complete: had changes but commit FAILED for ${task.taskId} (stash recovery failure?)`);
+        logger.write(`   → Resetting to pending — code changes may be in git stash`);
+        taskSelector.resetToPending(task);
+        return;
+      }
+
+      mergeOk = pcResult?.git?.merged ?? true; // no git result = skip-git mode, treat as ok
+      logger.write(`Post-complete done for ${task.taskId} (merged=${mergeOk})`);
+    } catch (e) {
+      logger.write(`❌ Post-complete failed for ${task.taskId}: ${e.message}`);
+      logger.write(`   → Resetting to pending for retry`);
+      taskSelector.resetToPending(task);
+      return;
+    }
+
+    // Post-complete git ops (stash/checkout/merge) may restore task files to old positions.
+    // Re-ensure the completed task is in done/ after all git operations.
+    taskSelector.moveToCompleted(task);
+    logger.write(`Task ${task.taskId} re-ensured in done/ after post-complete`);
+
+    // ── Acceptance Criteria 驗證 ──
+    try {
+      const { verify } = require('./verify-acceptance');
+      const verifyResult = verify(task.taskId, config?.projectPath);
+
+      if (verifyResult.skipped) {
+        logger.write(`Acceptance verify skipped: ${verifyResult.message}`);
+      } else if (verifyResult.pass) {
+        logger.write(`✅ Acceptance verify PASS for ${task.taskId}`);
+      } else {
+        logger.write(`❌ Acceptance verify FAIL for ${task.taskId}`);
+        const failed = (verifyResult.results || []).filter(r => !r.pass);
+        for (const f of failed) {
+          logger.write(`   ❌ ${f.criterion}: ${f.reason}`);
+        }
+        if (verifyResult.fixTasks) {
+          for (const ft of verifyResult.fixTasks) {
+            logger.write(`   📋 Fix task created: ${ft}`);
+          }
+        }
+      }
+    } catch (err) {
+      logger.write(`Warning: Acceptance verify error: ${err.message}`);
+    }
+  } else {
+    taskSelector.resetToPending(task);
+    if (result.drifted) {
+      logger.write(`🐦 Task ${task.taskId} reset to pending — canary drift detected, will retry with fresh context`);
+    } else {
+      logger.write(`Task ${task.taskId} reset to pending for retry (${task.source})`);
+    }
+  }
+}
+
+/**
+ * 執行 /product-review（對應 Rust run_product_review）
+ */
+async function runProductReview(config, logger) {
+  logger.write('==========================================');
+  logger.write('Starting Product Review (Self-Enhancement)');
+  logger.write('==========================================');
+
+  // 備份 status file
+  if (fs.existsSync(config.statusFile)) {
+    fs.copyFileSync(config.statusFile, config.statusFile + '.bak');
+    logger.write('Backed up previous status file');
+  }
+
+  // 使用 Formation Legacy review skill（不再用 spawnClaudeCmd）
+  const result = await runWithFormation(
+    { taskId: null, agentType: 'pm' },
+    'review',
+    config,
+    logger,
+    { timeoutMinutes: config.reviewTimeoutMinutes }
+  );
+
+  logger.write(`Product Review completed: exit=${result.exitCode}, status=${result.status}`);
+
+  if (result.status === RunStatus.TIMED_OUT) {
+    const bak = config.statusFile + '.bak';
+    if (fs.existsSync(bak)) {
+      fs.renameSync(bak, config.statusFile);
+      logger.write('Restored previous status file due to timeout');
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 讀取 SELF_ENHANCEMENT_STATUS.json 決策
+ */
+function readEnhancementDecision(config) {
+  if (!fs.existsSync(config.statusFile)) return 'continue';
+  try {
+    const data = JSON.parse(fs.readFileSync(config.statusFile, 'utf8'));
+    const decision = (data.decision || data.enhancement_decision || 'continue').toLowerCase();
+    if (decision.includes('complete_with')) return 'complete_with_suggestions';
+    if (decision.includes('complete')) return 'complete';
+    return 'continue';
+  } catch {
+    return 'continue';
+  }
+}
+
+// ─────────────────────────────────────────
+// Status File Writer
+// ─────────────────────────────────────────
+
+function updateStatusFile(config, data) {
+  if (!fs.existsSync(config.statusFile)) return;
+  try {
+    let existing = {};
+    try {
+      existing = JSON.parse(fs.readFileSync(config.statusFile, 'utf8'));
+    } catch {}
+    const updated = { ...existing, ...data, lastUpdated: new Date().toISOString() };
+    fs.writeFileSync(config.statusFile, JSON.stringify(updated, null, 2), 'utf8');
+  } catch (err) {
+    console.error('Failed to update status file:', err.message);
+  }
+}
+
+// ─────────────────────────────────────────
+// Yggdrasil L3: Remote Task Pull Helpers
+// ─────────────────────────────────────────
+
+/**
+ * 檢查本地 backlog/ 是否已有該任務（避免重複寫入）
+ */
+function localBacklogHasTask(taskId, config) {
+  const projectRoot = config.projectPath || ROOT;
+  const kenazBase = path.join(projectRoot, '.kenaz', 'tasks');
+  const collabBase = (config.projectPath && fs.existsSync(kenazBase))
+    ? kenazBase
+    : path.join(projectRoot, '.collaboration', 'tasks');
+  const backlogDir = path.join(collabBase, 'backlog');
+  if (!fs.existsSync(backlogDir)) return false;
+  return fs.readdirSync(backlogDir).some(f => f.startsWith(taskId));
+}
+
+/**
+ * 將遠端 claim 成功的任務寫入本地 backlog/ YAML
+ * full_yaml 存在 → 直接寫入；否則用 metadata 建立精簡 YAML
+ */
+function writeRemoteTaskToBacklog(task, config, logger) {
+  const projectRoot = config.projectPath || ROOT;
+  const kenazBase = path.join(projectRoot, '.kenaz', 'tasks');
+  const collabBase = (config.projectPath && fs.existsSync(kenazBase))
+    ? kenazBase
+    : path.join(projectRoot, '.collaboration', 'tasks');
+  const backlogDir = path.join(collabBase, 'backlog');
+  if (!fs.existsSync(backlogDir)) fs.mkdirSync(backlogDir, { recursive: true });
+
+  const scopeSuffix = (task.scope_paths || []).length > 0
+    ? '_' + (task.scope_paths[0] || '').replace(/[^a-zA-Z0-9]/g, '_').slice(0, 30)
+    : '';
+  const titleSlug = (task.title || '').replace(/[^a-zA-Z0-9\u4e00-\u9fff]/g, '_').slice(0, 40);
+  const fileName = `${task.task_id}_${titleSlug}${scopeSuffix}.yaml`;
+  const filePath = path.join(backlogDir, fileName);
+
+  if (task.full_yaml) {
+    // full_yaml 存在：直接寫入完整內容
+    fs.writeFileSync(filePath, task.full_yaml, 'utf8');
+    logger.write(`   📥 Remote task pulled: ${task.task_id} → backlog/ (full_yaml)`);
+  } else {
+    // full_yaml 為空：用 metadata 建立精簡 YAML
+    const minimalYaml = [
+      `id: "${task.task_id}"`,
+      `title: "${(task.title || '').replace(/"/g, '\\"')}"`,
+      `status: "backlog"`,
+      `priority: "${task.priority || 'P2'}"`,
+      `role: "developer"`,
+      `description: "${(task.description || '').replace(/"/g, '\\"')}"`,
+      `scope_paths:`,
+      ...(task.scope_paths || []).map(sp => `  - "${sp}"`),
+      `dependencies:`,
+      ...(task.dependencies || []).map(d => `  - "${d}"`),
+      `source: "yggdrasil"`,
+    ].join('\n') + '\n';
+    fs.writeFileSync(filePath, minimalYaml, 'utf8');
+    logger.write(`   📥 Remote task pulled: ${task.task_id} → backlog/ (metadata-only)`);
+  }
+}
+
+/**
+ * 對任務池（assigned_to IS NULL）中的任務打分。
+ * 簡單匹配：task.scope_paths 與本 node 最近修改的檔案是否在同目錄。
+ * @returns {Array<{task, score}>} 按分數降序排列
+ */
+function scorePoolTasks(poolTasks, config) {
+  // 取最近修改的檔案目錄（用 git 取最近 50 個 commit 的檔案）
+  let recentDirs = [];
+  try {
+    const projectRoot = config.projectPath || ROOT;
+    const output = require('child_process').execSync(
+      'git log --pretty=format: --name-only -50 | head -200',
+      { cwd: projectRoot, encoding: 'utf8', timeout: 5000, windowsHide: true }
+    );
+    const files = output.split('\n').filter(Boolean);
+    recentDirs = [...new Set(files.map(f => path.dirname(f)))];
+  } catch {
+    // git 不可用 → 所有任務得 0 分
+    return poolTasks.map(t => ({ task: t, score: 0 }));
+  }
+
+  const scored = poolTasks.map(task => {
+    const scopePaths = task.scope_paths || [];
+    if (scopePaths.length === 0) return { task, score: 0.1 }; // 無 scope 給微量分
+
+    let overlap = 0;
+    for (const sp of scopePaths) {
+      const spDir = path.dirname(sp);
+      for (const rd of recentDirs) {
+        if (sp.startsWith(rd) || rd.startsWith(spDir)) {
+          overlap++;
+          break;
+        }
+      }
+    }
+    const score = scopePaths.length > 0 ? overlap / scopePaths.length : 0;
+    return { task, score };
+  });
+
+  scored.sort((a, b) => b.score - a.score);
+  return scored;
+}
+
+// ─────────────────────────────────────────
+// 主排程迴圈（對應 Rust run_main_loop）
+// ─────────────────────────────────────────
+
+/**
+ * 等待任一 Promise 完成（不是 Promise.race — 保留其他 Promise 繼續跑）
+ * 處理 resolve 和 reject 兩種情況，避免 hang
+ * @returns {Promise<{index, value}>} 第一個完成的結果 + 在 slots 中的位置
+ */
+function raceSlots(slots) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let activeCount = 0;
+
+    slots.forEach((slot, i) => {
+      if (!slot) return;
+      activeCount++;
+
+      slot.promise.then(
+        value => {
+          if (!settled) { settled = true; resolve({ index: i, value }); }
+        },
+        error => {
+          // Promise rejected — 視為 FAILED，避免 hang
+          if (!settled) {
+            settled = true;
+            resolve({
+              index: i,
+              value: {
+                status: RunStatus.FAILED,
+                exitCode: 1,
+                durationSecs: 0,
+                targetTask: slot.task?.taskId || 'unknown',
+              },
+            });
+          }
+        }
+      );
+    });
+
+    if (activeCount === 0) {
+      reject(new Error('raceSlots: no active slots'));
+    }
+  });
+}
+
+async function runMainLoop(config, logger, scopeLockMgr, { writePidHeartbeat } = {}) {
+  const taskSelector = new TaskSelector(config);
+  let runCount = 0;
+  let status = Status.WAITING;
+  let firstRun = true;
+  let lastRunStart = Date.now();
+  const devHistory = [];
+
+  // 並行 slot 管理：每個 slot = { task, promise } | null
+  const slots = new Array(config.concurrency).fill(null);
+
+  /** 取得目前所有正在執行的 scope paths */
+  const getActiveScopes = () => {
+    const scopes = [];
+    for (const slot of slots) {
+      if (slot && slot.task.scopePaths) scopes.push(...slot.task.scopePaths);
+    }
+    return scopes;
+  };
+
+  /** 取得空閒 slot 數量 */
+  const freeSlotCount = () => slots.filter(s => s === null).length;
+
+  // Yggdrasil: 遠端節點上下文（每輪 main loop 更新，fillSlots 讀取注入 prompt）
+  let yggdrasilContext = null;
+  let remoteClaimedIds = new Set(); // Yggdrasil: task IDs claimed by other nodes
+
+  /**
+   * 填充空閒 slot（兩階段：先批量載入，再快速啟動）
+   *
+   * Phase 1 — Pre-load：批量執行 loadSkill + loadTask + buildPrompt
+   *   （execSync 在此完成，避免在 spawn 迴圈中阻塞 event loop）
+   * Phase 2 — Spawn：連續啟動所有 child process（毫秒級）
+   */
+  const fillSlots = () => {
+    const freeCount = freeSlotCount();
+    if (freeCount === 0) return 0;
+
+    const activeScopes = getActiveScopes();
+    const tasks = taskSelector.selectNextTasks(freeCount, activeScopes, remoteClaimedIds);
+    if (tasks.length === 0) return 0;
+
+    // ── Phase 1: Pre-load（所有 execSync 在此完成） ──
+    const preparations = [];
+    for (const task of tasks) {
+      let prepared = null;
+      if (task.agentType !== 'lead') {
+        const skillName = getLegacySkillName(task.agentType);
+        const skillDef = loadSkill('legacy', skillName);
+        const loadOpts = config.projectPath ? { projectPath: config.projectPath } : undefined;
+        const taskData = loadTask(task.taskId, loadOpts);
+        const promptOpts = config.projectPath ? { projectPath: config.projectPath } : {};
+        if (yggdrasilContext) promptOpts.yggdrasilContext = yggdrasilContext;
+        const prompt = buildPrompt(skillDef, task.taskId, taskData, promptOpts);
+        prepared = { skillName, skillDef, taskData, prompt, sessionId: generateSessionId() };
+      }
+      preparations.push({ task, prepared });
+    }
+
+    if (tasks.length > 1) {
+      logger.write(`🚀 Pre-loaded ${tasks.length} tasks, spawning in parallel...`);
+    }
+
+    // ── Phase 2: Spawn（不再有 execSync 阻塞，連續啟動） ──
+    let filled = 0;
+    for (const { task, prepared } of preparations) {
+      const slotIdx = slots.indexOf(null);
+      if (slotIdx === -1) break;
+
+      runCount++;
+      logger.write(`[Slot ${slotIdx}] Starting: [${task.taskId}] ${task.title} (${task.priority}, ${task.agentType}, ${task.source})`);
+      if (prepared) {
+        const projArg = config.projectPath ? ` --project-path=${config.projectPath}` : '';
+        logger.write(`[Slot ${slotIdx}] Command: node .formation/tools/headless.js --formation=legacy --skill=${prepared.skillName} --task=${task.taskId}${projArg} (session=${prepared.sessionId})`);
+        logger.write(`[Slot ${slotIdx}] Task injected: ${prepared.taskData ? 'YES' : 'NO'} | Prompt length: ${(HEADLESS_PREFIX + prepared.prompt).length} chars`);
+      } else {
+        logger.write(`[Slot ${slotIdx}] Mode: lead-only (no subagent)`);
+      }
+      taskSelector.markInProgress(task);
+
+      // Yggdrasil L2: 同步 active 狀態到 Supabase
+      const ts = getTaskSync();
+      if (ts) {
+        const sbClient = getSupabaseClient(config.projectPath || null);
+        const nodeName = sbClient?.config?.node_name || null;
+        ts.syncTaskStatus({
+          taskId: task.taskId,
+          status: 'active',
+          claimedBy: nodeName,
+          priority: task.priority,
+          scopePaths: task.scopePaths,
+          title: task.title,
+          dependencies: task.dependencies,
+          projectPath: config.projectPath || null,
+        }).catch(() => {});
+      }
+
+      const promise = executeTask(task, config, logger, prepared, scopeLockMgr);
+      slots[slotIdx] = { task, promise };
+      filled++;
+    }
+
+    return filled;
+  };
+
+  /** 有任何 slot 在跑嗎 */
+  const hasActiveSlots = () => slots.some(s => s !== null);
+
+  // 主迴圈
+  let lastIdleLog = 0;
+  while (!shuttingDown) {
+    // Heartbeat: update PID file so other instances can detect we're alive
+    if (writePidHeartbeat) writePidHeartbeat();
+
+    // 檢查待辦
+    const progress = checkPendingTasks(config);
+    const activeLabel = progress.activeCount > 0 ? `, ${progress.activeCount} active` : '';
+    const isIdle = !progress.hasPendingTasks && !hasActiveSlots();
+
+    if (!isIdle || status !== Status.WAITING) {
+      logger.write(`Progress: ${progress.completedCount}/${progress.totalCount} completed (${progress.pendingCount} pending${activeLabel})`);
+    }
+
+    updateStatusFile(config, {
+      pendingCount: progress.pendingCount,
+      activeCount: progress.activeCount,
+      completedCount: progress.completedCount,
+    });
+
+    if (isIdle) {
+      if (!config.enableSelfEnhancement) {
+        const now = Date.now();
+        if (status !== Status.WAITING || now - lastIdleLog > 300000) {
+          logger.write(`No pending tasks. Standing by (check every ${config.idleCheckSecs}s)...`);
+          lastIdleLog = now;
+        }
+        status = Status.WAITING;
+        updateStatusFile(config, { status: 'waiting' });
+        if (await waitWithShutdown(config.idleCheckSecs * 1000)) break;
+        continue;
+      }
+
+      // Self-enhancement: 執行 product review
+      logger.write('No pending tasks. Running Product Review...');
+      status = Status.RUNNING_REVIEW;
+      updateStatusFile(config, { status: 'running_review' });
+      const reviewResult = await runProductReview(config, logger);
+
+      if (reviewResult.status !== RunStatus.SUCCESS) {
+        logger.write('Product review failed. Will retry...');
+        if (await waitWithShutdown(config.intervalMinutes * 60 * 1000)) break;
+        continue;
+      }
+
+      const decision = readEnhancementDecision(config);
+      logger.write(`Enhancement Decision: ${decision}`);
+
+      if (decision === 'complete' || decision === 'complete_with_suggestions') {
+        logger.write(`PROJECT COMPLETE! (${decision})`);
+        status = Status.COMPLETED;
+        updateStatusFile(config, { status: 'completed', isRunning: false });
+        break;
+      }
+
+      const updated = checkPendingTasks(config);
+      if (!updated.hasPendingTasks) {
+        logger.write('No new tasks found after review. Waiting...');
+        if (await waitWithShutdown(config.intervalMinutes * 60 * 1000)) break;
+        continue;
+      }
+    }
+
+    // 間隔等待（非首次 & 無活躍 slot）
+    if (!firstRun && !hasActiveSlots()) {
+      const elapsed = (Date.now() - lastRunStart) / 1000;
+      const intervalSecs = config.intervalMinutes * 60;
+      const waitSecs = elapsed < intervalSecs ? config.earlyFinishDelaySecs : 0;
+
+      if (waitSecs > 0) {
+        logger.write(`Waiting ${waitSecs} seconds before next round...`);
+        status = Status.PAUSED;
+        updateStatusFile(config, { status: 'paused' });
+        if (await waitWithShutdown(waitSecs * 1000)) break;
+      }
+    }
+    firstRun = false;
+    lastRunStart = Date.now();
+
+    // Yggdrasil L2: 每輪刷新遠端衝突快取 + 查詢遠端節點（注入 agent prompt）
+    const rc = getRemoteConflict();
+    if (rc) {
+      try { await rc.refreshCache(config.projectPath || null); } catch {}
+    }
+    const ts = getTaskSync();
+    if (ts) {
+      try {
+        const [remoteNodes, remoteTasks, claimedIds] = await Promise.all([
+          ts.getOnlineNodes(config.projectPath || null).catch(() => []),
+          ts.getRemoteActiveTasks(config.projectPath || null).catch(() => []),
+          ts.getRemoteClaimedTaskIds(config.projectPath || null).catch(() => new Set()),
+        ]);
+        remoteClaimedIds = claimedIds;
+        if (remoteNodes.length > 0 || remoteTasks.length > 0) {
+          const sb = getSupabaseClient(config.projectPath || null);
+          yggdrasilContext = { onlineNodes: remoteNodes, remoteTasks, myNodeName: sb?.config?.node_name || 'unknown', myScopePaths: [] };
+        } else {
+          yggdrasilContext = null;
+        }
+      } catch { yggdrasilContext = null; remoteClaimedIds = new Set(); }
+    }
+
+    // Yggdrasil L3: 拉取遠端指派/任務池任務 → 寫入本地 backlog/
+    if (ts && config.enableRemotePull && freeSlotCount() > 0) {
+      try {
+        const remoteCandidates = await ts.getAssignedTasks(config.projectPath || null);
+        if (remoteCandidates.length > 0) {
+          const sb = getSupabaseClient(config.projectPath || null);
+          const myNode = sb?.config?.node_name || 'unknown';
+          // 分組：直接指派 vs 任務池（未指定接收者）
+          const directAssigned = remoteCandidates.filter(t => t.assigned_to === myNode);
+          const poolTasks = remoteCandidates.filter(t => !t.assigned_to);
+
+          // 直接指派的任務：優先 claim
+          for (const task of directAssigned) {
+            if (localBacklogHasTask(task.task_id, config)) continue;
+            const claimResult = await ts.tryClaimTask(task.task_id, config.projectPath || null);
+            if (claimResult.success) {
+              writeRemoteTaskToBacklog(claimResult.task, config, logger);
+            } else {
+              logger.write(`   🌍 Claim failed for ${task.task_id} (taken by another node)`);
+            }
+          }
+
+          // 任務池：打分搶單（scope overlap）
+          if (poolTasks.length > 0 && freeSlotCount() > 0) {
+            const scored = scorePoolTasks(poolTasks, config);
+            for (const { task, score } of scored) {
+              if (freeSlotCount() === 0) break;
+              if (score <= 0) continue; // 無重疊不搶
+              if (localBacklogHasTask(task.task_id, config)) continue;
+              const claimResult = await ts.tryClaimTask(task.task_id, config.projectPath || null);
+              if (claimResult.success) {
+                logger.write(`   🎯 Pool claim: ${task.task_id} (score=${score.toFixed(2)})`);
+                writeRemoteTaskToBacklog(claimResult.task, config, logger);
+              }
+            }
+          }
+        }
+      } catch (err) {
+        logger.write(`   ⚠️  Remote task pull failed (graceful skip): ${err.message}`);
+      }
+    }
+
+    // 填充空閒 slot
+    const filled = fillSlots();
+    if (filled > 0) {
+      const activeCount = slots.filter(s => s !== null).length;
+      logger.write(`Slots: ${activeCount}/${config.concurrency} active (filled ${filled} new)`);
+      status = Status.RUNNING;
+      updateStatusFile(config, {
+        status: 'running',
+        isRunning: true,
+        activeSlots: activeCount,
+        concurrency: config.concurrency,
+      });
+    }
+
+    // 如果沒有活躍 slot，跳回檢查
+    if (!hasActiveSlots()) continue;
+
+    // 等待任一 slot 完成（滑動窗口）
+    const { index, value: result } = await raceSlots(slots);
+    const completedTask = slots[index].task;
+    slots[index] = null; // 釋放 slot
+
+    logger.write(`[Slot ${index}] Completed: [${completedTask.taskId}] ${result.status} (${result.durationSecs}s)`);
+
+    // 處理結果
+    handleTaskResult(completedTask, result, taskSelector, logger, config);
+    devHistory.push({ runNumber: runCount, ...result });
+    if (devHistory.length > 20) devHistory.shift();
+
+    // 立即嘗試填補空出的 slot（滑動窗口）
+    const refilled = fillSlots();
+    if (refilled > 0) {
+      const activeCount = slots.filter(s => s !== null).length;
+      logger.write(`Slots: ${activeCount}/${config.concurrency} active (refilled ${refilled})`);
+    }
+  }
+
+  // Shutdown: 等待所有活躍 slot 完成
+  if (hasActiveSlots()) {
+    logger.write('Shutdown requested — waiting for active slots to finish...');
+    const activeSlots = slots.filter(s => s !== null);
+    const results = await Promise.all(activeSlots.map(s => s.promise));
+    results.forEach((result, i) => {
+      const task = activeSlots[i].task;
+      handleTaskResult(task, result, taskSelector, logger, config);
+    });
+  }
+
+  return { status, runCount, devHistory };
+}
+
+// ─────────────────────────────────────────
+// Shutdown 控制（對應 Rust wait_with_shutdown / is_shutdown_requested）
+// ─────────────────────────────────────────
+
+let shuttingDown = false;
+
+function requestShutdown() {
+  shuttingDown = true;
+}
+
+/** 等待 ms，可被 shutdown 打斷。回傳 true = 被打斷 */
+function waitWithShutdown(ms) {
+  return new Promise((resolve) => {
+    if (shuttingDown) return resolve(true);
+
+    const interval = setInterval(() => {
+      if (shuttingDown) {
+        clearInterval(interval);
+        clearTimeout(timer);
+        resolve(true);
+      }
+    }, 500);
+
+    const timer = setTimeout(() => {
+      clearInterval(interval);
+      resolve(false);
+    }, ms);
+  });
+}
+
+// ─────────────────────────────────────────
+// 主進入點（對應 Rust start()）
+// ─────────────────────────────────────────
+
+async function start(overrides = {}) {
+  const config = loadConfig(overrides);
+  const instanceId = overrides.instanceId || crypto.randomBytes(2).toString('hex');
+
+  // ── Singleton guard: one scheduler per project ──
+  // Heartbeat: PID file includes `heartbeat` timestamp updated every loop iteration.
+  // If the process is alive but heartbeat is stale (>5 min), treat it as a zombie.
+  const HEARTBEAT_STALE_MS = 5 * 60 * 1000;
+  if (!fs.existsSync(config.logDir)) fs.mkdirSync(config.logDir, { recursive: true });
+  const pidFile = path.join(config.logDir, 'scheduler.pid');
+  if (fs.existsSync(pidFile)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(pidFile, 'utf8'));
+      if (existing.pid && existing.pid !== process.pid) {
+        let isAlive = false;
+        try { process.kill(existing.pid, 0); isAlive = true; } catch {}
+        if (isAlive) {
+          const heartbeat = existing.heartbeat ? new Date(existing.heartbeat).getTime() : 0;
+          const stale = Date.now() - heartbeat > HEARTBEAT_STALE_MS;
+          if (stale) {
+            console.log(`⚠️  Stale scheduler detected (PID ${existing.pid}, last heartbeat: ${existing.heartbeat || 'never'}). Killing zombie...`);
+            try {
+              if (process.platform === 'win32') {
+                require('child_process').execSync(`taskkill /F /PID ${existing.pid}`, { stdio: 'ignore', timeout: 5000, windowsHide: true });
+              } else {
+                process.kill(existing.pid, 'SIGTERM');
+              }
+            } catch {}
+          } else {
+            console.log(`ℹ️  Scheduler already running (PID ${existing.pid}). Exiting quietly.`);
+            process.exit(0);
+          }
+        }
+      }
+    } catch {}
+  }
+  // Clean up old-format per-instance PID files (scheduler_{id}.pid)
+  try {
+    for (const f of fs.readdirSync(config.logDir).filter(f => /^scheduler_[0-9a-f]+\.pid$/.test(f))) {
+      try { fs.unlinkSync(path.join(config.logDir, f)); } catch {}
+    }
+  } catch {}
+
+  const logger = new SchedulerLogger(config.logDir, instanceId);
+  const scopeLockMgr = new ScopeLockManager();
+
+  // Write single PID file (with heartbeat for zombie detection)
+  const writePidHeartbeat = () => {
+    try {
+      fs.writeFileSync(pidFile, JSON.stringify({ pid: process.pid, instanceId, startedAt: new Date().toISOString(), heartbeat: new Date().toISOString() }));
+    } catch {}
+  };
+  writePidHeartbeat();
+
+  // 信號處理
+  const cleanup = () => {
+    requestShutdown();
+    // Release all scope locks held by this instance
+    try { scopeLockMgr.releaseAll(); } catch {}
+    // Clean up PID file
+    try {
+      if (fs.existsSync(pidFile)) fs.unlinkSync(pidFile);
+    } catch {}
+    // Yggdrasil L2: 下線通知 — 標記 kenaz_status is_online=false（fire-and-forget）
+    try {
+      const sb = getSupabaseClient(config.projectPath || null);
+      if (sb) {
+        const { client: supabase, config: sbCfg } = sb;
+        const tsm = getTaskSync();
+        supabase.from('kenaz_status').upsert({
+          node_name: sbCfg.node_name,
+          project: tsm?.resolveProjectName?.(config.projectPath) || 'default',
+          is_online: false,
+        }, { onConflict: 'node_name,project' }).catch(() => {});
+      }
+    } catch {}
+  };
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+  process.on('exit', cleanup);
+
+  // Banner
+  console.log('');
+  console.log(`⚔️  Formation Legacy Scheduler [${instanceId}]`);
+  console.log(`   PID:          ${process.pid}`);
+  // [merge: main + {git_user}] Instance (main) + Concurrency ({git_user})
+  console.log(`   Instance:     ${instanceId}`);
+  console.log(`   Concurrency:  ${config.concurrency} (max ${config.maxConcurrency})`);
+  console.log(`   InitialDelay: ${config.initialDelaySecs}s`);
+  console.log(`   Interval:     ${config.intervalMinutes}min`);
+  console.log(`   IdleCheck:    ${config.idleCheckSecs}s`);
+  console.log(`   DevTimeout:   ${config.devTimeoutMinutes}min`);
+  console.log(`   SelfEnhance:  ${config.enableSelfEnhancement}`);
+  console.log(`   RemotePull:   ${config.enableRemotePull}`);
+  if (config.projectPath) console.log(`   Project:      ${config.projectPath}`);
+  console.log(`   Tasks:        ${config.tasksDir}`);
+  console.log(`   Log:          ${logger.logPath}`);
+  console.log('');
+
+  logger.write('Scheduler started (Legacy Formation - Continuous Mode)');
+  logger.write(`Config: Concurrency=${config.concurrency}, InitialDelay=${config.initialDelaySecs}s, Interval=${config.intervalMinutes}min, SelfEnhancement=${config.enableSelfEnhancement}, RemotePull=${config.enableRemotePull}`);
+
+  // Yggdrasil L2: 上線通知 — 註冊到 kenaz_status
+  const sbClient = getSupabaseClient(config.projectPath || null);
+  if (sbClient) {
+    const { client: supabase, config: sbConfig } = sbClient;
+    supabase.from('kenaz_status').upsert({
+      node_name: sbConfig.node_name,
+      project: getTaskSync()?.resolveProjectName?.(config.projectPath) || 'default',
+      is_online: true,
+      branch: null,
+      current_task: null,
+      touching_files: [],
+    }, { onConflict: 'node_name,project' }).then(() => {
+      logger.write(`🌐 Yggdrasil: online (node=${sbConfig.node_name})`);
+    }).catch(() => {});
+  }
+
+  // 初始延遲
+  if (config.initialDelaySecs > 0 && !overrides.dryRun) {
+    logger.write(`Waiting ${config.initialDelaySecs} seconds before first run...`);
+    if (await waitWithShutdown(config.initialDelaySecs * 1000)) {
+      logger.write('Shutdown during initial delay');
+      logger.close();
+      return;
+    }
+  }
+
+  if (overrides.dryRun) {
+    // Dry run：只檢查任務狀態
+    const progress = checkPendingTasks(config);
+    logger.write(`[DRY RUN] Pending: ${progress.pendingCount}, Completed: ${progress.completedCount}`);
+    const ts = new TaskSelector(config);
+    const next = ts.selectNextTask();
+    if (next) {
+      logger.write(`[DRY RUN] Next task: [${next.taskId}] ${next.title} (${next.priority}, ${next.agentType})`);
+    } else {
+      logger.write('[DRY RUN] No pending tasks');
+    }
+    logger.close();
+    return;
+  }
+
+  // 主迴圈
+  const result = await runMainLoop(config, logger, scopeLockMgr, { writePidHeartbeat });
+
+  logger.write(`Scheduler finished. Total Dev Runs: ${result.runCount}, Final Status: ${result.status}`);
+  logger.close();
+}
+
+// ─────────────────────────────────────────
+// Crash Handlers（module-level，確保 headless 模式也有保護）
+// ─────────────────────────────────────────
+
+function _writeCrashLog(msg) {
+  try {
+    const logDir = path.join(ROOT, '.formation', 'logs', 'legacy');
+    if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
+    const date = localDateStr();
+    fs.appendFileSync(path.join(logDir, `scheduler_${date}.log`), msg);
+  } catch {}
+}
+
+process.on('uncaughtException', (err) => {
+  // EPIPE = parent closed stdout/stderr pipe (e.g. dashboard disconnected) — not fatal
+  if (err.code === 'EPIPE') return;
+  const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+  const msg = `[${ts}] ❌ UNCAUGHT EXCEPTION: ${err.message}\n${err.stack}\n`;
+  try { console.error(msg); } catch {}  // console may also be broken
+  _writeCrashLog(msg);
+  process.exit(1);
+});
+
+process.on('unhandledRejection', (reason) => {
+  const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+  const msg = `[${ts}] ❌ UNHANDLED REJECTION: ${reason}\n`;
+  try { console.error(msg); } catch {}
+  _writeCrashLog(msg);
+});
+
+// ─────────────────────────────────────────
+// CLI
+// ─────────────────────────────────────────
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+⚔️  Formation Legacy Scheduler (= Formation Lead)
+連續調度排程器 — 以 Formation Lead 身份運行
+
+Usage:
+  node .formation/tools/legacy-scheduler.js [options]
+
+Options:
+  --concurrency=<n>       並行執行數（預設 3，上限 5）
+  --dry-run               只檢查任務狀態，不啟動排程
+  --initial-delay=<sec>   首次延遲秒數（預設 30）
+  --interval=<min>        執行間隔分鐘（預設 20）
+  --idle-check=<sec>      無任務時輪詢秒數（預設 20）
+  --dev-timeout=<min>     任務超時分鐘（預設 60）
+  --self-enhancement      啟用 self-enhancement 模式
+  --remote-pull           啟用遠端任務拉取（預設 on，用 --no-remote-pull 關閉）
+  --no-remote-pull        關閉遠端任務拉取
+  --project-path=<path>   子專案路徑（掃描該專案的任務）
+
+Tasks:
+  Primary:   .collaboration/tasks/{backlog,active,done}/
+  Legacy:    dev/pipeline/{tasks,completed}/
+  Logs:      .formation/logs/legacy/
+
+Behavior:
+  1. 掃描 .collaboration + dev/pipeline → 按優先級選取最多 N 個 pending 任務
+  2. 並行啟動 N 個 Formation Legacy Skill subagent（滑動窗口）
+  3. subagent 自行完成任務移動（task-api.js complete）
+  4. Scheduler 執行 post-complete（archive + git，Formation Lead 職責）
+  5. Slot 完成即補入新任務，失敗 → 重置為 pending
+  6. 衝突檢查：scope_paths 重疊的任務不並行
+  7. --self-enhancement: 無任務時使用 review skill 分析專案
+`);
+    process.exit(0);
+  }
+
+  const getArg = (flag) => {
+    for (const a of args) {
+      if (a.startsWith(`${flag}=`)) return a.split('=').slice(1).join('=');
+    }
+    return null;
+  };
+
+  const overrides = {
+    dryRun: args.includes('--dry-run'),
+    selfEnhancement: args.includes('--self-enhancement'),
+    remotePull: args.includes('--no-remote-pull') ? false : (args.includes('--remote-pull') ? true : undefined),
+  };
+
+  const concurrency = getArg('--concurrency');
+  if (concurrency != null) overrides.concurrency = parseInt(concurrency, 10);
+
+  const initialDelay = getArg('--initial-delay');
+  if (initialDelay != null) overrides.initialDelay = parseInt(initialDelay, 10);
+
+  const interval = getArg('--interval');
+  if (interval != null) overrides.interval = parseInt(interval, 10);
+
+  const idleCheck = getArg('--idle-check');
+  if (idleCheck != null) overrides.idleCheck = parseInt(idleCheck, 10);
+
+  const devTimeout = getArg('--dev-timeout');
+  if (devTimeout != null) overrides.devTimeout = parseInt(devTimeout, 10);
+
+  // [merge: main + {git_user}] --instance-id (main) + --project-path & crash handlers ({git_user})
+  const instanceId = getArg('--instance-id');
+  if (instanceId) overrides.instanceId = instanceId;
+
+  const projectPath = getArg('--project-path');
+  if (projectPath) overrides.projectPath = projectPath;
+
+  // Crash handlers — 捕捉未預期的崩潰
+  // Use project-aware log dir for crash logs
+  const crashLogDir = projectPath
+    ? path.join(getLogDir(projectPath), 'legacy')
+    : path.join(ROOT, '.formation', 'logs', 'legacy');
+
+  process.on('uncaughtException', (err) => {
+    // EPIPE = parent closed stdout/stderr pipe (e.g. dashboard disconnected) — not fatal
+    if (err.code === 'EPIPE') return;
+    const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    const msg = `[${ts}] ❌ UNCAUGHT EXCEPTION: ${err.message}\n${err.stack}\n`;
+    try { console.error(msg); } catch {}  // console may also be broken
+    try {
+      const date = new Date().toISOString().slice(0, 10);
+      fs.appendFileSync(path.join(crashLogDir, `scheduler_${date}.log`), msg);
+    } catch {}
+    process.exit(1);
+  });
+  process.on('unhandledRejection', (reason) => {
+    if (reason && reason.code === 'EPIPE') return;
+    const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    const msg = `[${ts}] ❌ UNHANDLED REJECTION: ${reason}\n`;
+    try { console.error(msg); } catch {}
+    try {
+      const date = new Date().toISOString().slice(0, 10);
+      fs.appendFileSync(path.join(crashLogDir, `scheduler_${date}.log`), msg);
+    } catch {}
+  });
+
+  start(overrides).catch(err => {
+    console.error('❌ Scheduler error:', err.message);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  start,
+  loadConfig,
+  checkPendingTasks,
+  TaskSelector,
+  requestShutdown,
+  Status,
+  RunStatus,
+};