kenaz 0.0.0-stage → 0.3.2

package/core/dev/scripts/multi_agent_scheduler.ps1

@@ -0,0 +1,2021 @@
+# ============================================================
+# Multi-Agent Parallel Scheduler
+# ============================================================
+# 啟動多個 Claude Agent 並行開發
+# - 自動分配無衝突的任務給多個 Agent
+# - 使用路徑鎖定防止衝突
+# - 每個 Agent 在獨立 Branch 工作
+# ============================================================
+
+param(
+    [int]$MaxAgents = 3,              # 最大並行 Agent 數量
+    [int]$PollIntervalSeconds = 30,   # 輪詢間隔
+    [int]$TaskTimeoutMinutes = 60,    # 單任務超時
+    [switch]$DryRun,                  # 模擬運行（不實際啟動）
+    [switch]$SingleRun,               # 單次運行（不循環）
+    [string]$WorkingDirectory,        # 工作目錄
+    [switch]$nopause,                 # 從 Tauri 調用時使用（跳過暫停）
+    [switch]$Standalone               # 獨立模式：忽略 Dashboard heartbeat，適合開發 Tauri 本身時使用
+)
+
+# Helper function to normalize Windows extended path format (\\?\)
+function Get-NormalizedPath {
+    param([string]$Path)
+    if ($Path -and $Path.StartsWith("\\?\")) {
+        return $Path.Substring(4)
+    }
+    return $Path
+}
+
+# Use KENAZ_PROJECT_PATH env var if WorkingDirectory not specified
+if (-not $WorkingDirectory) {
+    if ($env:KENAZ_PROJECT_PATH) {
+        $WorkingDirectory = $env:KENAZ_PROJECT_PATH
+    } else {
+        $WorkingDirectory = (Get-Location).Path
+    }
+}
+
+# Normalize WorkingDirectory to handle \\?\ prefix from Tauri
+$WorkingDirectory = Get-NormalizedPath $WorkingDirectory
+
+# === STARTUP DEBUG LOG ===
+# Write startup info to a debug file for troubleshooting Tauri execution issues
+$StartupDebugFile = Join-Path $WorkingDirectory "multi_agent_startup.log"
+
+# Helper function to append to debug log
+function Write-DebugLog {
+    param([string]$Message, [string]$Level = "INFO")
+    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
+    $logLine = "[$timestamp] [$Level] $Message"
+    try {
+        Add-Content -Path $StartupDebugFile -Value $logLine -Encoding UTF8 -ErrorAction SilentlyContinue
+    } catch { }
+    if ($Level -eq "ERROR") {
+        Write-Host $logLine -ForegroundColor Red
+    }
+}
+
+try {
+    $startupInfo = @"
+=== Multi-Agent Scheduler Startup ===
+Time: $(Get-Date -Format "yyyy-MM-dd HH:mm:ss")
+WorkingDirectory (raw param): $($PSBoundParameters['WorkingDirectory'])
+WorkingDirectory (normalized): $WorkingDirectory
+KENAZ_PROJECT_PATH env: $($env:KENAZ_PROJECT_PATH)
+Script Path: $($MyInvocation.MyCommand.Path)
+Script Directory: $(Split-Path -Parent $MyInvocation.MyCommand.Path)
+PowerShell Version: $($PSVersionTable.PSVersion)
+OS: $($PSVersionTable.OS)
+Platform: $($PSVersionTable.Platform)
+Arguments: $($args -join ' ')
+nopause: $nopause
+DryRun: $DryRun
+SingleRun: $SingleRun
+Standalone: $Standalone
+MaxAgents: $MaxAgents
+PollIntervalSeconds: $PollIntervalSeconds
+TaskTimeoutMinutes: $TaskTimeoutMinutes
+
+=== Path Checks ===
+WorkingDirectory exists: $(Test-Path $WorkingDirectory)
+dev folder exists: $(Test-Path (Join-Path $WorkingDirectory 'dev'))
+dev/pipeline exists: $(Test-Path (Join-Path $WorkingDirectory 'dev\pipeline'))
+dev/scripts exists: $(Test-Path (Join-Path $WorkingDirectory 'dev\scripts'))
+TASK_QUEUE.json exists: $(Test-Path (Join-Path $WorkingDirectory 'dev\pipeline\TASK_QUEUE.json'))
+
+=== Environment Variables ===
+PATH (first 500 chars): $($env:PATH.Substring(0, [Math]::Min(500, $env:PATH.Length)))
+
+=== Execution Log ===
+"@
+    # Ensure directory exists
+    $debugDir = Split-Path $StartupDebugFile -Parent
+    if (-not (Test-Path $debugDir)) {
+        New-Item -ItemType Directory -Path $debugDir -Force | Out-Null
+    }
+    Set-Content -Path $StartupDebugFile -Value $startupInfo -Encoding UTF8
+    Write-Host "[DEBUG] Startup log written to: $StartupDebugFile" -ForegroundColor DarkGray
+} catch {
+    Write-Host "[DEBUG] Failed to write startup log: $_" -ForegroundColor Yellow
+}
+# === END STARTUP DEBUG LOG ===
+
+# 檢測是否在交互式控制台
+$script:IsInteractiveConsole = $false
+try {
+    $null = [Console]::CursorTop
+    $script:IsInteractiveConsole = $true
+} catch {
+    $script:IsInteractiveConsole = $false
+}
+
+# Standalone 模式（忽略 Dashboard heartbeat）
+$script:StandaloneMode = $Standalone
+
+# 在 Standalone 模式下，刪除舊的 heartbeat 文件避免混淆
+if ($Standalone) {
+    $heartbeatPath = Join-Path $WorkingDirectory "dev\pipeline\DASHBOARD_HEARTBEAT.json"
+    if (Test-Path $heartbeatPath) {
+        Remove-Item $heartbeatPath -Force -ErrorAction SilentlyContinue
+        Write-Host "[STANDALONE] Removed old heartbeat file" -ForegroundColor Magenta
+    }
+}
+
+# 配置
+$LogFile = Join-Path $WorkingDirectory "dev\pipeline\logs\multi_agent_$(Get-Date -Format 'yyyy-MM-dd').log"
+$TaskQueueFile = Join-Path $WorkingDirectory "dev\pipeline\TASK_QUEUE.json"
+$LockStateFile = Join-Path $WorkingDirectory "dev\pipeline\LOCK_STATE.json"
+$AgentStateFile = Join-Path $WorkingDirectory "dev\pipeline\AGENT_STATE.json"
+$HeartbeatFile = Join-Path $WorkingDirectory "dev\pipeline\DASHBOARD_HEARTBEAT.json"
+
+# Heartbeat timeout disabled - only stop on explicit "closing" signal
+
+# 確保目錄存在
+$LogDir = Split-Path $LogFile -Parent
+if (-not (Test-Path $LogDir)) {
+    New-Item -ItemType Directory -Path $LogDir -Force | Out-Null
+}
+
+# ============================================================
+# 工具函數
+# ============================================================
+
+function Write-Log {
+    param([string]$Message, [string]$Level = "INFO")
+    $Timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
+    $LogMessage = "[$Timestamp] [$Level] $Message"
+
+    switch ($Level) {
+        "ERROR" { Write-Host $LogMessage -ForegroundColor Red }
+        "WARN"  { Write-Host $LogMessage -ForegroundColor Yellow }
+        "SUCCESS" { Write-Host $LogMessage -ForegroundColor Green }
+        default { Write-Host $LogMessage }
+    }
+
+    Add-Content -Path $LogFile -Value $LogMessage -Encoding UTF8
+}
+
+function Write-FileWithRetry {
+    param(
+        [string]$Path,
+        [string]$Content,
+        [int]$MaxRetries = 5,
+        [int]$RetryDelayMs = 200
+    )
+
+    $attempt = 0
+    while ($attempt -lt $MaxRetries) {
+        try {
+            $Content | Set-Content $Path -Encoding UTF8 -ErrorAction Stop
+            return $true
+        } catch [System.IO.IOException] {
+            $attempt++
+            if ($attempt -lt $MaxRetries) {
+                Start-Sleep -Milliseconds $RetryDelayMs
+                $RetryDelayMs = $RetryDelayMs * 2  # Exponential backoff
+            } else {
+                Write-Log "Failed to write to $Path after $MaxRetries retries: $_" "ERROR"
+                throw $_
+            }
+        }
+    }
+    return $false
+}
+
+function Stop-ProcessTree {
+    param([int]$ProcessId)
+
+    # Use taskkill with /T flag to kill the process tree
+    # This ensures all child processes are also terminated
+    try {
+        $null = taskkill /PID $ProcessId /T /F 2>&1
+        Write-Log "Terminated process tree for PID $ProcessId" "INFO"
+        return $true
+    } catch {
+        Write-Log "Failed to terminate process tree for PID $ProcessId : $_" "WARN"
+        return $false
+    }
+}
+
+function Stop-OrphanClaudeProcesses {
+    # Find and terminate orphan Claude processes that are not tracked by this scheduler
+    # SAFETY: Only terminates processes that:
+    #   1. Are NOT in TrackedProcessIds
+    #   2. Have a command line containing "--dangerously-skip-permissions" (scheduler-launched agents)
+    # This prevents accidentally killing user's IDE Claude sessions
+    param(
+        [hashtable]$TrackedProcessIds = @{},
+        [switch]$Force  # Force cleanup even without command line check (dangerous!)
+    )
+
+    $claudeProcesses = Get-Process -Name "claude" -ErrorAction SilentlyContinue
+
+    if (-not $claudeProcesses) {
+        return 0
+    }
+
+    $orphanCount = 0
+    foreach ($proc in $claudeProcesses) {
+        # Skip if this process is being tracked
+        if ($TrackedProcessIds.ContainsKey($proc.Id)) {
+            continue
+        }
+
+        # Safety check: only kill processes launched by scheduler (have --dangerously-skip-permissions flag)
+        if (-not $Force) {
+            try {
+                $cmdLine = (Get-CimInstance Win32_Process -Filter "ProcessId = $($proc.Id)" -ErrorAction SilentlyContinue).CommandLine
+                if (-not $cmdLine -or $cmdLine -notmatch "--dangerously-skip-permissions") {
+                    # This is likely a user's IDE session, skip it
+                    continue
+                }
+            } catch {
+                # If we can't check command line, don't kill to be safe
+                continue
+            }
+        }
+
+        try {
+            Write-Log "Found orphan Claude agent process (PID: $($proc.Id), Started: $($proc.StartTime))" "WARN"
+            Stop-ProcessTree -ProcessId $proc.Id
+            $orphanCount++
+        } catch {
+            Write-Log "Failed to stop orphan process $($proc.Id): $_" "ERROR"
+        }
+    }
+
+    return $orphanCount
+}
+
+# ============================================================
+# Smart Agent Dispatch Functions
+# ============================================================
+
+function Get-AgentType {
+    param(
+        [string]$TaskId,
+        [string]$TaskTitle,
+        [string[]]$ScopePaths,
+        [string]$ExplicitType = $null
+    )
+
+    # If explicit type is specified, use it
+    if ($ExplicitType) {
+        return $ExplicitType
+    }
+
+    $titleLower = $TaskTitle.ToLower()
+
+    # Keyword matching for agent type (English only for PowerShell compatibility)
+    $designerKeywords = @('ui', 'ux', 'layout', 'style', 'design', 'css', 'theme', 'color', 'visual', 'icon')
+    $backendKeywords = @('api', 'database', 'backend', 'endpoint', 'server', 'sql', 'migration', 'supabase', 'postgres')
+    $qaKeywords = @('test', 'qa', 'quality', 'unit test', 'e2e', 'spec', 'coverage', 'assert')
+    $sreKeywords = @('deploy', 'ci/cd', 'monitoring', 'infrastructure', 'docker', 'kubernetes', 'devops', 'pipeline')
+    $frontendKeywords = @('component', 'react', 'frontend', 'tsx', 'jsx', 'hook', 'state', 'page', 'dashboard')
+
+    # Check keywords in title
+    foreach ($kw in $designerKeywords) {
+        if ($titleLower.Contains($kw)) { return "designer" }
+    }
+    foreach ($kw in $backendKeywords) {
+        if ($titleLower.Contains($kw)) { return "backend" }
+    }
+    foreach ($kw in $qaKeywords) {
+        if ($titleLower.Contains($kw)) { return "qa" }
+    }
+    foreach ($kw in $sreKeywords) {
+        if ($titleLower.Contains($kw)) { return "sre" }
+    }
+    foreach ($kw in $frontendKeywords) {
+        if ($titleLower.Contains($kw)) { return "developer" }
+    }
+
+    # Scope path matching
+    foreach ($path in $ScopePaths) {
+        $pathLower = $path.ToLower()
+        if ($pathLower -match "api/" -or $pathLower -match "backend/") {
+            return "backend"
+        }
+        if ($pathLower -match "components/" -or $pathLower -match "src/" -or $pathLower -match "dashboard/") {
+            return "developer"
+        }
+        if ($pathLower -match "tests/" -or $pathLower -match "spec/") {
+            return "qa"
+        }
+        if ($pathLower -match "deploy/" -or $pathLower -match "infra/") {
+            return "sre"
+        }
+    }
+
+    # Default to dev_agent
+    return "dev"
+}
+
+function Get-SkillPath {
+    param([string]$AgentType)
+
+    $skillPaths = @{
+        "developer"  = ".claude/skills/developer/SKILL.md"
+        "backend"    = ".claude/skills/backend_engineer/SKILL.md"
+        "designer"   = ".claude/skills/designer/SKILL.md"
+        "qa"         = ".claude/skills/qa_engineer/SKILL.md"
+        "sre"        = ".claude/skills/sre_agent/SKILL.md"
+        "dev"        = ".claude/skills/dev_agent/SKILL.md"
+        "frontend"   = ".claude/skills/frontend_agent/SKILL.md"
+        "architect"  = ".claude/skills/architect_agent/SKILL.md"
+    }
+
+    if ($skillPaths.ContainsKey($AgentType)) {
+        return $skillPaths[$AgentType]
+    }
+
+    # Default to dev_agent
+    return ".claude/skills/dev_agent/SKILL.md"
+}
+
+function Get-AgentDisplayName {
+    param([string]$AgentType)
+
+    $displayNames = @{
+        "developer"  = "Frontend Developer"
+        "backend"    = "Backend Engineer"
+        "designer"   = "UI/UX Designer"
+        "qa"         = "QA Engineer"
+        "sre"        = "SRE Agent"
+        "dev"        = "Dev Agent"
+        "frontend"   = "Frontend Agent"
+        "architect"  = "Architect"
+    }
+
+    if ($displayNames.ContainsKey($AgentType)) {
+        return $displayNames[$AgentType]
+    }
+
+    return "Dev Agent"
+}
+
+function Get-TaskQueue {
+    if (-not (Test-Path $TaskQueueFile)) {
+        return $null
+    }
+
+    try {
+        $content = Get-Content $TaskQueueFile -Raw -Encoding UTF8
+        return $content | ConvertFrom-Json
+    } catch {
+        Write-Log "Failed to read task queue: $_" "ERROR"
+        return $null
+    }
+}
+
+function Get-LockState {
+    if (-not (Test-Path $LockStateFile)) {
+        return @{ locks = @() }
+    }
+
+    try {
+        $content = Get-Content $LockStateFile -Raw -Encoding UTF8
+        return $content | ConvertFrom-Json
+    } catch {
+        return @{ locks = @() }
+    }
+}
+
+function Save-LockState {
+    param($State)
+
+    try {
+        $State | Add-Member -NotePropertyName "last_updated" -NotePropertyValue (Get-Date -Format "o") -Force
+        $jsonContent = $State | ConvertTo-Json -Depth 10
+        Write-FileWithRetry -Path $LockStateFile -Content $jsonContent
+    } catch {
+        Write-Log "Failed to save lock state: $_" "WARN"
+        # Don't propagate - allow scheduler to continue
+    }
+}
+
+function Get-AgentState {
+    if (-not (Test-Path $AgentStateFile)) {
+        return @{ agents = @() }
+    }
+
+    try {
+        $content = Get-Content $AgentStateFile -Raw -Encoding UTF8
+        return $content | ConvertFrom-Json
+    } catch {
+        return @{ agents = @() }
+    }
+}
+
+function Save-AgentState {
+    param($State)
+
+    try {
+        $State | Add-Member -NotePropertyName "last_updated" -NotePropertyValue (Get-Date -Format "o") -Force
+        $jsonContent = $State | ConvertTo-Json -Depth 10
+        Write-FileWithRetry -Path $AgentStateFile -Content $jsonContent
+    } catch {
+        Write-Log "Failed to save agent state: $_" "WARN"
+        # Don't propagate - allow scheduler to continue
+    }
+}
+
+function Test-DashboardHeartbeat {
+    # Check if dashboard is still alive via heartbeat file
+    # Stop agents when:
+    #   1. Dashboard explicitly sends "closing" signal
+    #   2. Heartbeat file hasn't been updated for too long (crash detection)
+    #
+    # NOTE: In Standalone mode, heartbeat is ignored entirely
+
+    # Standalone mode - always return alive
+    if ($script:StandaloneMode) {
+        return @{ Alive = $true; Reason = "Standalone mode (heartbeat ignored)" }
+    }
+
+    $HeartbeatTimeoutSeconds = 120  # 2 minutes - if no heartbeat update, assume crashed
+
+    if (-not (Test-Path $HeartbeatFile)) {
+        # No heartbeat file - assume running without dashboard (CLI mode)
+        return @{ Alive = $true; Reason = "No heartbeat file (CLI mode)" }
+    }
+
+    try {
+        $content = Get-Content $HeartbeatFile -Raw -Encoding UTF8
+        $heartbeat = $content | ConvertFrom-Json
+
+        # Check if dashboard is explicitly closing
+        if ($heartbeat.status -eq "closing") {
+            return @{ Alive = $false; Reason = "Dashboard closing" }
+        }
+
+        # Check heartbeat timeout (crash detection)
+        if ($heartbeat.timestamp) {
+            $lastHeartbeat = [DateTime]::Parse($heartbeat.timestamp)
+            $elapsed = (Get-Date) - $lastHeartbeat
+            if ($elapsed.TotalSeconds -gt $HeartbeatTimeoutSeconds) {
+                return @{
+                    Alive = $false
+                    Reason = "Dashboard heartbeat timeout ($([int]$elapsed.TotalSeconds)s > ${HeartbeatTimeoutSeconds}s)"
+                }
+            }
+        }
+
+        return @{ Alive = $true; SessionId = $heartbeat.session_id }
+    } catch {
+        # Failed to read/parse - check file modification time as fallback
+        try {
+            $fileInfo = Get-Item $HeartbeatFile
+            $elapsed = (Get-Date) - $fileInfo.LastWriteTime
+            if ($elapsed.TotalSeconds -gt $HeartbeatTimeoutSeconds) {
+                return @{
+                    Alive = $false
+                    Reason = "Dashboard heartbeat file stale ($([int]$elapsed.TotalSeconds)s)"
+                }
+            }
+        } catch { }
+        return @{ Alive = $true; Reason = "Heartbeat check fallback" }
+    }
+}
+
+function Add-AgentToState {
+    param(
+        [string]$AgentId,
+        [string]$TaskId,
+        [string]$TaskTitle,
+        [string]$Branch,
+        [string]$Status = "working",
+        [string]$AgentType = "dev_agent"
+    )
+
+    $agentState = Get-AgentState
+    $agents = [System.Collections.ArrayList]@()
+    if ($agentState.agents) {
+        $agents = [System.Collections.ArrayList]@($agentState.agents)
+    }
+
+    # Remove existing entry if any
+    $agents = [System.Collections.ArrayList]@($agents | Where-Object { $_.id -ne $AgentId })
+
+    # Map internal agent type to dashboard-compatible type
+    $dashboardType = switch ($AgentType) {
+        "developer"  { "developer" }
+        "backend"    { "backend_engineer" }
+        "designer"   { "designer" }
+        "qa"         { "qa_engineer" }
+        "sre"        { "sre_agent" }
+        "frontend"   { "frontend_agent" }
+        "architect"  { "architect_agent" }
+        default      { "dev_agent" }
+    }
+
+    # Debug: Log type mapping for troubleshooting
+    Write-Log "Type mapping: AgentType='$AgentType' -> dashboardType='$dashboardType'" "INFO"
+
+    # Add new agent entry (format compatible with dashboard)
+    $agents.Add(@{
+        id = $AgentId
+        type = $dashboardType
+        status = $Status
+        current_task = $TaskId
+        current_operation = $TaskTitle
+        branch = $Branch
+        started_at = (Get-Date -Format "o")
+        task_id = $TaskId
+        task_title = $TaskTitle
+    }) | Out-Null
+
+    $agentState.agents = $agents
+    Save-AgentState $agentState
+    $displayName = Get-AgentDisplayName -AgentType $AgentType
+    Write-Log "Added agent $AgentId ($displayName) to AGENT_STATE.json (task: $TaskId)"
+}
+
+function Remove-AgentFromState {
+    param([string]$AgentId)
+
+    $agentState = Get-AgentState
+    if ($agentState.agents) {
+        $newAgents = @($agentState.agents | Where-Object { $_.id -ne $AgentId })
+        $agentState.agents = $newAgents
+        Save-AgentState $agentState
+        Write-Log "Removed agent $AgentId from AGENT_STATE.json"
+    }
+}
+
+# Clean exit function - ensures AGENT_STATE.json is updated before exit
+# PowerShell's `exit` doesn't trigger `finally` blocks, so we need this
+function Stop-SchedulerCleanly {
+    param(
+        [int]$ExitCode = 0,
+        [string]$Reason = "Normal exit"
+    )
+
+    Write-Log "Scheduler stopping: $Reason"
+
+    # Terminate all active agents if any
+    if ($script:activeAgents -and $script:activeAgents.Count -gt 0) {
+        foreach ($agentId in @($script:activeAgents.Keys)) {
+            $agent = $script:activeAgents[$agentId]
+            if ($agent.Process -and -not $agent.Process.HasExited) {
+                Write-Log "Terminating agent $agentId (PID: $($agent.Process.Id))"
+                Stop-ProcessTree -ProcessId $agent.Process.Id
+            }
+            Remove-AgentLocks -AgentId $agentId
+            Remove-AgentFromState -AgentId $agentId
+        }
+        $script:activeAgents.Clear()
+    }
+
+    # Update AGENT_STATE.json to show scheduler is stopped
+    $agentState = @{
+        agents = @()
+        scheduler = @{
+            status = "stopped"
+            stopped_at = (Get-Date -Format "o")
+        }
+        last_updated = (Get-Date -Format "o")
+    }
+    Save-AgentState $agentState
+    Write-Log "AGENT_STATE.json updated: scheduler stopped"
+
+    exit $ExitCode
+}
+
+function Test-PathConflict {
+    param(
+        [string[]]$RequestedPaths,
+        $LockState
+    )
+
+    foreach ($reqPath in $RequestedPaths) {
+        foreach ($lock in $LockState.locks) {
+            $lockPath = $lock.path
+
+            # 檢查路徑衝突
+            if ($reqPath.StartsWith($lockPath) -or $lockPath.StartsWith($reqPath) -or $reqPath -eq $lockPath) {
+                return @{
+                    Conflict = $true
+                    ConflictingPath = $lockPath
+                    HeldBy = $lock.agent_id
+                    Task = $lock.task_id
+                }
+            }
+        }
+    }
+
+    return @{ Conflict = $false }
+}
+
+function Get-ReadyTasks {
+    param($Queue)
+
+    $readyTasks = @()
+    $completedIds = @()
+
+    # 收集已完成任務 ID（queue 內）
+    foreach ($task in $Queue.tasks) {
+        if ($task.status -eq "completed") {
+            $completedIds += $task.id
+        }
+    }
+
+    # 收集已完成且被移除的任務 ID（completed/ 目錄內的 YAML）
+    $completedDir = Join-Path $WorkingDirectory "dev/pipeline/completed"
+    if (Test-Path $completedDir) {
+        Get-ChildItem -Path $completedDir -Filter "TASK_*.yaml" | ForEach-Object {
+            if ($_.Name -match "^(TASK_\d+)") {
+                $completedId = $Matches[1]
+                if ($completedId -notin $completedIds) {
+                    $completedIds += $completedId
+                }
+            }
+        }
+    }
+
+    # 找出可執行的任務
+    foreach ($task in $Queue.tasks) {
+        if ($task.status -ne "pending") {
+            continue
+        }
+
+        # 檢查依賴
+        $depsOk = $true
+        if ($task.dependencies) {
+            foreach ($dep in $task.dependencies) {
+                if ($dep -notin $completedIds) {
+                    $depsOk = $false
+                    break
+                }
+            }
+        }
+
+        if ($depsOk) {
+            $readyTasks += $task
+        }
+    }
+
+    # 按優先級排序 (P0 > P1 > P2 > P3)
+    $priorityOrder = @{ "P0" = 0; "P1" = 1; "P2" = 2; "P3" = 3 }
+    $readyTasks = $readyTasks | Sort-Object { $priorityOrder[$_.priority] }
+
+    return $readyTasks
+}
+
+function New-AgentId {
+    return "agent_$(Get-Date -Format 'HHmmss')_$([guid]::NewGuid().ToString().Substring(0,4))"
+}
+
+function Start-AgentWorker {
+    param(
+        [string]$AgentId,
+        [string]$TaskId,
+        [string]$TaskTitle,
+        [string[]]$ScopePaths,
+        [string]$AgentType = "dev"
+    )
+
+    $displayName = Get-AgentDisplayName -AgentType $AgentType
+    $skillPath = Get-SkillPath -AgentType $AgentType
+    Write-Log "Starting $displayName ($AgentId) for task $TaskId" "SUCCESS"
+    Write-Log "  Skill: $skillPath" "INFO"
+
+    if ($DryRun) {
+        Write-Log "[DRY RUN] Would start: claude -p '/agent-worker --task $TaskId --agent $AgentId'" "WARN"
+        return $null
+    }
+
+    # Check if task has a resumable branch (from previous interrupted session)
+    $queue = Get-TaskQueue
+    $resumeBranch = $null
+    if ($queue) {
+        $taskObj = $queue.tasks | Where-Object { $_.id -eq $TaskId } | Select-Object -First 1
+        if ($taskObj -and $taskObj.resume_branch) {
+            $resumeBranch = $taskObj.resume_branch
+        }
+    }
+
+    # 決定使用的 Branch
+    $branchName = if ($resumeBranch) {
+        Write-Log "Resuming task from existing branch: $resumeBranch" "INFO"
+        $resumeBranch
+    } else {
+        "task-$($TaskId.ToLower())-$AgentId"
+    }
+
+    try {
+        Push-Location $WorkingDirectory
+
+        if ($resumeBranch) {
+            # Resume: checkout existing branch
+            $null = git checkout $resumeBranch 2>$null
+            if ($LASTEXITCODE -ne 0) {
+                Write-Log "Failed to checkout resume branch, creating new one" "WARN"
+                $branchName = "task-$($TaskId.ToLower())-$AgentId"
+                $null = git checkout main 2>$null
+                if ($LASTEXITCODE -ne 0) { $null = git checkout master 2>$null }
+                $null = git checkout -b $branchName 2>$null
+            }
+        } else {
+            # New task: create new branch from main
+            $currentBranch = git rev-parse --abbrev-ref HEAD 2>$null
+            if ($currentBranch -ne "main" -and $currentBranch -ne "master") {
+                $null = git checkout main 2>$null
+                if ($LASTEXITCODE -ne 0) {
+                    $null = git checkout master 2>$null
+                }
+            }
+            # 創建任務分支
+            $null = git checkout -b $branchName 2>$null
+        }
+
+        Pop-Location
+    } catch {
+        Write-Log "Failed to setup branch: $_" "ERROR"
+        Pop-Location
+        return $null
+    }
+
+    # 啟動 Claude Agent Worker
+    $prompt = "/agent-worker --task $TaskId --agent $AgentId --branch $branchName"
+
+    # Create log file for this agent's output
+    $logDir = Join-Path $WorkingDirectory "dev\pipeline\logs"
+    if (-not (Test-Path $logDir)) { New-Item -ItemType Directory -Path $logDir -Force | Out-Null }
+    $agentLogFile = Join-Path $logDir "agent_${AgentId}.log"
+
+    try {
+        # Use cmd.exe /c to invoke claude (npm global installs create .cmd scripts on Windows)
+        # This ensures proper execution regardless of how claude was installed
+        $process = Start-Process -FilePath "cmd.exe" `
+            -ArgumentList "/c", "claude", "--dangerously-skip-permissions", "-p", "`"$prompt`"" `
+            -WorkingDirectory $WorkingDirectory `
+            -PassThru `
+            -NoNewWindow `
+            -RedirectStandardOutput $agentLogFile `
+            -RedirectStandardError "${agentLogFile}.err"
+
+        Write-Log "Agent $AgentId started (PID: $($process.Id))"
+        Write-Log "Agent log: $agentLogFile"
+
+        $result = @{
+            Process = $process
+            AgentId = $AgentId
+            TaskId = $TaskId
+            Branch = $branchName
+            StartTime = Get-Date
+            LogFile = $agentLogFile
+        }
+        return $result
+    } catch {
+        Write-Log "Failed to start agent: $_" "ERROR"
+        return $null
+    }
+}
+
+function Update-TaskStatus {
+    param(
+        [string]$TaskId,
+        [string]$Status,
+        [string]$AgentId = $null,
+        [string]$Branch = $null
+    )
+
+    $queue = Get-TaskQueue
+    if (-not $queue) { return }
+
+    foreach ($task in $queue.tasks) {
+        if ($task.id -eq $TaskId) {
+            $task.status = $Status
+
+            if ($Status -eq "in_progress") {
+                $task | Add-Member -NotePropertyName "started_at" -NotePropertyValue (Get-Date -Format "o") -Force
+                if ($AgentId) {
+                    $task | Add-Member -NotePropertyName "assigned_agent" -NotePropertyValue $AgentId -Force
+                }
+                if ($Branch) {
+                    $task | Add-Member -NotePropertyName "branch" -NotePropertyValue $Branch -Force
+                }
+                # Clear resume_branch marker now that agent has started
+                if ($task.PSObject.Properties["resume_branch"]) {
+                    $task.PSObject.Properties.Remove("resume_branch")
+                }
+            } elseif ($Status -eq "completed") {
+                $task | Add-Member -NotePropertyName "completed_at" -NotePropertyValue (Get-Date -Format "o") -Force
+            }
+
+            break
+        }
+    }
+
+    try {
+        $queue | Add-Member -NotePropertyName "last_updated" -NotePropertyValue (Get-Date -Format "o") -Force
+        $jsonContent = $queue | ConvertTo-Json -Depth 10
+        Write-FileWithRetry -Path $TaskQueueFile -Content $jsonContent
+    } catch {
+        Write-Log "Failed to update task queue for ${TaskId}: $_" "WARN"
+        # Don't propagate - allow scheduler to continue
+    }
+}
+
+function Move-TaskToCompleted {
+    param([string]$TaskId)
+
+    $tasksDir = Join-Path $WorkingDirectory "dev\pipeline\tasks"
+    $completedDir = Join-Path $WorkingDirectory "dev\pipeline\completed"
+
+    # Ensure completed directory exists
+    if (-not (Test-Path $completedDir)) {
+        New-Item -ItemType Directory -Path $completedDir -Force | Out-Null
+    }
+
+    # Find and move task file (support both .md and .yaml formats)
+    $taskFile = Get-ChildItem -Path $tasksDir -Filter "${TaskId}_*" -ErrorAction SilentlyContinue |
+        Where-Object { $_.Extension -in @('.md', '.yaml', '.yml') } |
+        Select-Object -First 1
+    if ($taskFile) {
+        $destPath = Join-Path $completedDir $taskFile.Name
+        Move-Item -Path $taskFile.FullName -Destination $destPath -Force
+        Write-Log "Moved task file to completed: $($taskFile.Name)" "INFO"
+    }
+
+    # TASK_084: Remove completed task from TASK_QUEUE.json to prevent pollution
+    # This prevents completed tasks from being re-added to the queue by sync script
+    try {
+        $TaskQueueFile = Join-Path $WorkingDirectory "dev\pipeline\TASK_QUEUE.json"
+        if (Test-Path $TaskQueueFile) {
+            $queue = Get-Content $TaskQueueFile -Raw -Encoding UTF8 | ConvertFrom-Json
+            $beforeCount = $queue.tasks.Count
+            $queue.tasks = $queue.tasks | Where-Object { $_.id -ne $TaskId }
+            $afterCount = $queue.tasks.Count
+
+            if ($beforeCount -ne $afterCount) {
+                # Recalculate statistics
+                $queue.statistics.total = $queue.tasks.Count
+                $queue.statistics.pending = ($queue.tasks | Where-Object { $_.status -eq "pending" }).Count
+                $queue.statistics.in_progress = ($queue.tasks | Where-Object { $_.status -eq "in_progress" }).Count
+                $queue.statistics.blocked = ($queue.tasks | Where-Object { $_.status -eq "blocked" }).Count
+                $queue.statistics.completed = 0  # No completed tasks in queue anymore
+                $queue.statistics.cancelled = ($queue.tasks | Where-Object { $_.status -eq "cancelled" }).Count
+                $queue.last_updated = (Get-Date -Format "o")
+
+                $jsonContent = $queue | ConvertTo-Json -Depth 10
+                Write-FileWithRetry -Path $TaskQueueFile -Content $jsonContent
+                Write-Log "Removed ${TaskId} from TASK_QUEUE.json (cleanup to prevent pollution)" "INFO"
+            }
+        }
+    } catch {
+        Write-Log "Failed to remove ${TaskId} from TASK_QUEUE.json: $_" "WARN"
+        # Don't propagate - task file was already moved
+    }
+}
+
+# ============================================================
+# 任務檔案備份（啟動時執行）
+# ============================================================
+
+function Backup-TaskFiles {
+    # Backup tasks/ folder before starting scheduler
+    # This prevents loss of task files if scheduler crashes or misbehaves
+
+    $tasksDir = Join-Path $WorkingDirectory "dev\pipeline\tasks"
+    $backupDir = Join-Path $WorkingDirectory "dev\pipeline\backups"
+
+    if (-not (Test-Path $tasksDir)) {
+        Write-Log "Tasks directory not found, skipping backup" "WARN"
+        return $null
+    }
+
+    $taskFiles = Get-ChildItem -Path $tasksDir -File -ErrorAction SilentlyContinue
+    if (-not $taskFiles -or $taskFiles.Count -eq 0) {
+        Write-Log "No task files to backup" "INFO"
+        return $null
+    }
+
+    # Create backup directory with timestamp
+    $timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
+    $backupPath = Join-Path $backupDir "tasks_$timestamp"
+
+    try {
+        if (-not (Test-Path $backupDir)) {
+            New-Item -ItemType Directory -Path $backupDir -Force | Out-Null
+        }
+
+        # Copy entire tasks folder
+        Copy-Item -Path $tasksDir -Destination $backupPath -Recurse -Force
+
+        $backupCount = (Get-ChildItem -Path $backupPath -File -ErrorAction SilentlyContinue).Count
+        Write-Log "Backed up $backupCount task file(s) to: $backupPath" "SUCCESS"
+
+        # Clean up old backups (keep last 5)
+        $oldBackups = Get-ChildItem -Path $backupDir -Directory -Filter "tasks_*" |
+            Sort-Object CreationTime -Descending |
+            Select-Object -Skip 5
+
+        foreach ($old in $oldBackups) {
+            Remove-Item -Path $old.FullName -Recurse -Force -ErrorAction SilentlyContinue
+            Write-Log "Removed old backup: $($old.Name)" "INFO"
+        }
+
+        return $backupPath
+    } catch {
+        Write-Log "Failed to backup task files: $_" "ERROR"
+        return $null
+    }
+}
+
+# ============================================================
+# 改進的 Exit Code 偵測
+# ============================================================
+
+function Test-AgentSuccess {
+    param(
+        [int]$ExitCode,
+        [string]$LogFile,
+        [string]$Branch,
+        [string]$TaskId
+    )
+
+    # Priority 1: Exit code 0 is always success
+    if ($ExitCode -eq 0) {
+        return @{ Success = $true; Reason = "Exit code 0" }
+    }
+
+    # Priority 2: Check for commits in branch (actual work done)
+    if ($Branch) {
+        try {
+            Push-Location $WorkingDirectory
+
+            # Check if branch exists
+            $null = git rev-parse --verify $Branch 2>$null
+            if ($LASTEXITCODE -eq 0) {
+                # Determine main branch
+                $mainBranch = "main"
+                $null = git rev-parse --verify main 2>$null
+                if ($LASTEXITCODE -ne 0) { $mainBranch = "master" }
+
+                # Count commits ahead of main
+                $commitsAhead = git rev-list --count "${mainBranch}..${Branch}" 2>$null
+                if ($LASTEXITCODE -eq 0 -and [int]$commitsAhead -gt 0) {
+                    # Check if any commit message contains the task ID
+                    $commitMessages = git log --oneline "${mainBranch}..${Branch}" 2>$null
+                    if ($commitMessages -match $TaskId) {
+                        Pop-Location
+                        return @{
+                            Success = $true
+                            Reason = "Branch has $commitsAhead commit(s) with $TaskId"
+                        }
+                    }
+                }
+            }
+
+            Pop-Location
+        } catch {
+            Pop-Location
+        }
+    }
+
+    # Priority 3: Check log file for success indicators
+    if ($LogFile -and (Test-Path $LogFile)) {
+        try {
+            $logContent = Get-Content $LogFile -Raw -ErrorAction SilentlyContinue
+            if ($logContent) {
+                # Multiple success patterns
+                $successPatterns = @(
+                    "Status:\s*SUCCESS",
+                    "TASK_\d+\s+is\s+now\s+complete",
+                    "Task.*completed\s+successfully",
+                    "^\s*##\s+TASK_\d+\s+Summary",
+                    "\[SUCCESS\].*completed",
+                    "All\s+\d+\s+tests\s+pass"
+                )
+
+                foreach ($pattern in $successPatterns) {
+                    if ($logContent -match $pattern) {
+                        return @{
+                            Success = $true
+                            Reason = "Log matches success pattern: $pattern"
+                        }
+                    }
+                }
+
+                # Check for failure patterns (explicit failures)
+                $failurePatterns = @(
+                    "API Error:\s*5\d\d",
+                    "FATAL\s+ERROR",
+                    "Build\s+failed",
+                    "Compilation\s+error"
+                )
+
+                foreach ($pattern in $failurePatterns) {
+                    if ($logContent -match $pattern) {
+                        return @{
+                            Success = $false
+                            Reason = "Log matches failure pattern: $pattern"
+                        }
+                    }
+                }
+            }
+        } catch {
+            # Ignore log read errors
+        }
+    }
+
+    # Default: If exit code is null/unknown and no definitive indicators, check branch again
+    if ($null -eq $ExitCode -or $ExitCode -eq "") {
+        # One more check: if branch exists with commits, consider it partial success
+        if ($Branch) {
+            try {
+                Push-Location $WorkingDirectory
+                $null = git rev-parse --verify $Branch 2>$null
+                if ($LASTEXITCODE -eq 0) {
+                    $commitsAhead = git rev-list --count "main..${Branch}" 2>$null
+                    if ($LASTEXITCODE -ne 0) {
+                        $commitsAhead = git rev-list --count "master..${Branch}" 2>$null
+                    }
+                    if ($LASTEXITCODE -eq 0 -and [int]$commitsAhead -gt 0) {
+                        Pop-Location
+                        return @{
+                            Success = $true
+                            Reason = "Exit null but branch has $commitsAhead commit(s) - assuming success"
+                        }
+                    }
+                }
+                Pop-Location
+            } catch {
+                Pop-Location
+            }
+        }
+
+        return @{
+            Success = $false
+            Reason = "Exit code null with no success indicators"
+        }
+    }
+
+    return @{
+        Success = $false
+        Reason = "Exit code $ExitCode (non-zero)"
+    }
+}
+
+function Update-ProgressFile {
+    param(
+        [string]$TaskId,
+        [string]$TaskTitle,
+        [string]$Action
+    )
+
+    $progressFile = Join-Path $WorkingDirectory "dev\pipeline\PROGRESS.md"
+    if (-not (Test-Path $progressFile)) { return }
+
+    $content = Get-Content $progressFile -Raw -Encoding UTF8
+    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm"
+
+    # Update Last Update section
+    $content = $content -replace '(?ms)(## Last Update\r?\n-.*?Time.*?:)[^\r\n]*', "`$1 $timestamp"
+    $content = $content -replace '(?ms)(## Last Update\r?\n.*?Agent.*?:)[^\r\n]*', "`$1 Multi-Agent Scheduler"
+    $content = $content -replace '(?ms)(## Last Update\r?\n.*?Session.*?:)[^\r\n]*', "`$1 $TaskId $Action"
+
+    # Update statistics based on current queue
+    $queue = Get-TaskQueue
+    if ($queue) {
+        $total = $queue.tasks.Count
+        $completed = @($queue.tasks | Where-Object { $_.status -eq "completed" }).Count
+        $inProgress = @($queue.tasks | Where-Object { $_.status -eq "in_progress" }).Count
+        $pending = @($queue.tasks | Where-Object { $_.status -eq "pending" }).Count
+        $blocked = @($queue.tasks | Where-Object { $_.status -eq "blocked" }).Count
+
+        $completedPct = if ($total -gt 0) { [math]::Round($completed / $total * 100) } else { 0 }
+        $inProgressPct = if ($total -gt 0) { [math]::Round($inProgress / $total * 100) } else { 0 }
+        $pendingPct = if ($total -gt 0) { [math]::Round($pending / $total * 100) } else { 0 }
+        $blockedPct = if ($total -gt 0) { [math]::Round($blocked / $total * 100) } else { 0 }
+
+        $statsBlock = @"
+Total Tasks: $total
+Completed: $completed ($completedPct%)
+In Progress: $inProgress ($inProgressPct%)
+Pending: $pending ($pendingPct%)
+Blocked: $blocked ($blockedPct%)
+"@
+        $content = $content -replace '(?ms)(### Overall Progress\r?\n```\r?\n).*?(```)', "`$1$statsBlock`n`$2"
+    }
+
+    # Add to change history
+    $dateStr = Get-Date -Format "yyyy-MM-dd"
+    $historyEntry = "| $dateStr | $Action | $TaskId - $TaskTitle |"
+    $content = $content -replace '(\| 2026-01-29 \| Tasks Created \|[^\r\n]*)', "`$1`n$historyEntry"
+
+    Set-Content $progressFile -Value $content -Encoding UTF8
+    Write-Log "Updated PROGRESS.md" "INFO"
+}
+
+function Add-PathLocks {
+    param(
+        [string]$AgentId,
+        [string]$TaskId,
+        [string[]]$Paths
+    )
+
+    $lockState = Get-LockState
+    $locks = [System.Collections.ArrayList]@($lockState.locks)
+
+    foreach ($path in $Paths) {
+        $locks.Add(@{
+            path = $path
+            agent_id = $AgentId
+            task_id = $TaskId
+            lock_type = if ($path.EndsWith("/")) { "directory" } else { "file" }
+            acquired_at = (Get-Date -Format "o")
+        }) | Out-Null
+    }
+
+    $lockState.locks = $locks
+    Save-LockState $lockState
+
+    Write-Log "Acquired locks for $AgentId on $($Paths.Count) paths"
+}
+
+function Remove-AgentLocks {
+    param([string]$AgentId)
+
+    $lockState = Get-LockState
+    $newLocks = $lockState.locks | Where-Object { $_.agent_id -ne $AgentId }
+    $lockState.locks = @($newLocks)
+    Save-LockState $lockState
+
+    Write-Log "Released locks for $AgentId"
+}
+
+# ============================================================
+# 狀態一致性檢查與清理（啟動時執行）
+# ============================================================
+
+function Clear-StaleState {
+    # CRITICAL: Clear all stale state from previous sessions at startup
+    # This function runs BEFORE consistency check to ensure clean slate
+    #
+    # Why: When scheduler restarts, any existing locks/agents from previous
+    # crashed sessions are invalid and must be cleared immediately
+
+    Write-Log "Cleaning stale state from previous sessions..." "INFO"
+    $cleaned = @()
+
+    # 1. Clear ALL locks - new scheduler session means fresh state
+    try {
+        $lockState = Get-LockState
+        if ($lockState.locks -and $lockState.locks.Count -gt 0) {
+            $lockCount = $lockState.locks.Count
+            $lockDetails = @($lockState.locks | ForEach-Object { "$($_.task_id):$($_.path)" })
+            Write-Log "Found $lockCount stale lock(s) from previous session:" "WARN"
+            foreach ($detail in $lockDetails) {
+                Write-Log "  - $detail" "WARN"
+            }
+
+            # Clear all locks
+            Save-LockState @{ locks = @() }
+            $cleaned += "Cleared $lockCount stale lock(s)"
+        }
+    } catch {
+        Write-Log "Error clearing locks: $_" "ERROR"
+        # Force reset
+        try {
+            Save-LockState @{ locks = @() }
+            $cleaned += "Force reset LOCK_STATE.json"
+        } catch { }
+    }
+
+    # 2. Clear stale agents from AGENT_STATE.json
+    try {
+        $agentState = Get-AgentState
+        if ($agentState.agents -and $agentState.agents.Count -gt 0) {
+            $agentCount = $agentState.agents.Count
+            $agentDetails = @($agentState.agents | ForEach-Object { "$($_.id):$($_.current_task)" })
+            Write-Log "Found $agentCount stale agent(s) from previous session:" "WARN"
+            foreach ($detail in $agentDetails) {
+                Write-Log "  - $detail" "WARN"
+            }
+
+            # Clear agents but preserve scheduler info
+            $agentState.agents = @()
+            Save-AgentState $agentState
+            $cleaned += "Cleared $agentCount stale agent(s)"
+        }
+    } catch {
+        Write-Log "Error clearing agents: $_" "ERROR"
+    }
+
+    # 3. Reset in_progress tasks to pending (check branch progress first)
+    try {
+        $queue = Get-TaskQueue
+        if ($queue -and $queue.tasks) {
+            $inProgressTasks = @($queue.tasks | Where-Object { $_.status -eq "in_progress" })
+            if ($inProgressTasks.Count -gt 0) {
+                Write-Log "Found $($inProgressTasks.Count) in_progress task(s) to check:" "WARN"
+                $resetCount = 0
+                $resumeCount = 0
+
+                foreach ($task in $queue.tasks) {
+                    if ($task.status -eq "in_progress") {
+                        $hasProgress = $false
+                        $branchName = $task.branch
+
+                        # Check if branch exists and has commits ahead of main
+                        if ($branchName) {
+                            try {
+                                Push-Location $WorkingDirectory
+
+                                # Check if branch exists
+                                $null = git rev-parse --verify $branchName 2>$null
+                                if ($LASTEXITCODE -eq 0) {
+                                    # Check for commits ahead of main/master
+                                    $mainBranch = "main"
+                                    $null = git rev-parse --verify main 2>$null
+                                    if ($LASTEXITCODE -ne 0) { $mainBranch = "master" }
+
+                                    $commitsAhead = git rev-list --count "${mainBranch}..${branchName}" 2>$null
+                                    if ($LASTEXITCODE -eq 0 -and [int]$commitsAhead -gt 0) {
+                                        $hasProgress = $true
+                                        Write-Log "  - $($task.id): $($task.title) - branch has $commitsAhead commit(s), will RESUME" "SUCCESS"
+                                    }
+                                }
+
+                                Pop-Location
+                            } catch {
+                                Pop-Location
+                            }
+                        }
+
+                        # Reset task to pending
+                        $task.status = "pending"
+
+                        # Clear stale assignment info
+                        if ($task.PSObject.Properties["assigned_agent"]) {
+                            $task.PSObject.Properties.Remove("assigned_agent")
+                        }
+                        if ($task.PSObject.Properties["started_at"]) {
+                            $task.PSObject.Properties.Remove("started_at")
+                        }
+
+                        if ($hasProgress) {
+                            # Keep branch for resume
+                            $task | Add-Member -NotePropertyName "resume_branch" -NotePropertyValue $branchName -Force
+                            if ($task.PSObject.Properties["branch"]) {
+                                $task.PSObject.Properties.Remove("branch")
+                            }
+                            $resumeCount++
+                        } else {
+                            # Full reset - no progress to preserve
+                            if (-not $hasProgress) {
+                                Write-Log "  - $($task.id): $($task.title) - no progress, will RESET" "WARN"
+                            }
+                            if ($task.PSObject.Properties["branch"]) {
+                                $task.PSObject.Properties.Remove("branch")
+                            }
+                            if ($task.PSObject.Properties["resume_branch"]) {
+                                $task.PSObject.Properties.Remove("resume_branch")
+                            }
+                            $resetCount++
+                        }
+                    }
+                }
+
+                # Save updated queue
+                $queue.last_updated = (Get-Date -Format "o")
+                $jsonContent = $queue | ConvertTo-Json -Depth 10
+                Write-FileWithRetry -Path $TaskQueueFile -Content $jsonContent
+
+                if ($resetCount -gt 0) {
+                    $cleaned += "Reset $resetCount task(s) with no progress"
+                }
+                if ($resumeCount -gt 0) {
+                    $cleaned += "Will resume $resumeCount task(s) with branch progress"
+                }
+            }
+        }
+    } catch {
+        Write-Log "Error resetting tasks: $_" "ERROR"
+    }
+
+    # Report
+    if ($cleaned.Count -gt 0) {
+        Write-Log "Stale state cleanup completed:" "SUCCESS"
+        foreach ($item in $cleaned) {
+            Write-Log "  - $item" "SUCCESS"
+        }
+    } else {
+        Write-Log "No stale state found - clean startup" "SUCCESS"
+    }
+
+    return $cleaned
+}
+
+function Test-StateConsistency {
+    # Comprehensive state consistency check at scheduler startup
+    # This prevents issues from previous crashed sessions
+    # NOTE: Clear-StaleState should be called BEFORE this function
+
+    $issues = @()
+    $fixed = @()
+
+    # 1. Validate TASK_QUEUE.json
+    Write-Log "Checking state consistency..." "INFO"
+
+    try {
+        $queue = Get-TaskQueue
+        if (-not $queue) {
+            $issues += "TASK_QUEUE.json is missing or invalid"
+            # Will be recreated by sync script
+        }
+    } catch {
+        $issues += "TASK_QUEUE.json parse error: $_"
+    }
+
+    # 2. Validate LOCK_STATE.json (should be empty after Clear-StaleState)
+    try {
+        $lockState = Get-LockState
+        if ($lockState.locks -and $lockState.locks.Count -gt 0) {
+            # This shouldn't happen after Clear-StaleState, but handle it
+            $issues += "Unexpected locks remain after cleanup: $($lockState.locks.Count)"
+            Save-LockState @{ locks = @() }
+            $fixed += "Force cleared remaining locks"
+        }
+    } catch {
+        $issues += "LOCK_STATE.json error: $_"
+        try {
+            Save-LockState @{ locks = @() }
+            $fixed += "Reset LOCK_STATE.json"
+        } catch { }
+    }
+
+    # 3. Validate AGENT_STATE.json (should have no agents after Clear-StaleState)
+    try {
+        $agentState = Get-AgentState
+        if ($agentState.agents -and $agentState.agents.Count -gt 0) {
+            $issues += "Unexpected agents remain after cleanup: $($agentState.agents.Count)"
+        }
+    } catch {
+        $issues += "AGENT_STATE.json error: $_"
+    }
+
+    # 4. Check for tasks stuck in in_progress (should be none after Clear-StaleState)
+    if ($queue -and $queue.tasks) {
+        $stuckTasks = @($queue.tasks | Where-Object { $_.status -eq "in_progress" })
+        if ($stuckTasks.Count -gt 0) {
+            $issues += "Unexpected in_progress tasks after cleanup: $($stuckTasks.Count)"
+        }
+    }
+
+    # Report
+    if ($issues.Count -gt 0) {
+        Write-Log "State consistency issues found:" "WARN"
+        foreach ($issue in $issues) {
+            Write-Log "  - $issue" "WARN"
+        }
+    }
+
+    if ($fixed.Count -gt 0) {
+        Write-Log "Auto-fixed issues:" "SUCCESS"
+        foreach ($fix in $fixed) {
+            Write-Log "  - $fix" "SUCCESS"
+        }
+    }
+
+    if ($issues.Count -eq 0 -and $fixed.Count -eq 0) {
+        Write-Log "State consistency check passed" "SUCCESS"
+    }
+
+    return @{
+        Issues = $issues
+        Fixed = $fixed
+        HasCriticalIssues = ($issues | Where-Object { $_ -match "parse error|invalid" }).Count -gt 0
+    }
+}
+
+# ============================================================
+# 主循環
+# ============================================================
+
+Clear-Host
+Write-Host ""
+Write-Host "============================================================" -ForegroundColor Cyan
+Write-Host "       Multi-Agent Parallel Scheduler" -ForegroundColor Cyan
+Write-Host "============================================================" -ForegroundColor Cyan
+Write-Host "  Max Parallel Agents: $MaxAgents"
+Write-Host "  Poll Interval: ${PollIntervalSeconds}s"
+Write-Host "  Task Timeout: ${TaskTimeoutMinutes}min"
+Write-Host "  Working Dir: $WorkingDirectory"
+if ($DryRun) { Write-Host "  Mode: DRY RUN" -ForegroundColor Yellow }
+if ($Standalone) { Write-Host "  Mode: STANDALONE (heartbeat ignored)" -ForegroundColor Magenta }
+Write-Host "============================================================" -ForegroundColor Cyan
+Write-Host ""
+
+# ============================================================
+# Prerequisite Checks
+# ============================================================
+Write-Host "[CHECK] Running prerequisite checks..." -ForegroundColor Yellow
+Write-DebugLog "Starting prerequisite checks"
+
+# Check 1: Claude CLI installed
+try {
+    $claudeCmd = Get-Command "claude" -ErrorAction SilentlyContinue
+    $claudeInstalled = $null -ne $claudeCmd
+    if ($claudeCmd) {
+        Write-DebugLog "Claude CLI found at: $($claudeCmd.Source)"
+    }
+} catch {
+    $claudeInstalled = $false
+    Write-DebugLog "Error checking Claude CLI: $_" "ERROR"
+}
+
+if (-not $claudeInstalled) {
+    $errorMsg = "Claude CLI not found in PATH"
+    Write-DebugLog $errorMsg "ERROR"
+    Write-Host ""
+    Write-Host "============================================================" -ForegroundColor Red
+    Write-Host "  ERROR: Claude CLI not found!" -ForegroundColor Red
+    Write-Host "============================================================" -ForegroundColor Red
+    Write-Host ""
+    Write-Host "  Multi-Agent mode requires Claude CLI to be installed."
+    Write-Host ""
+    Write-Host "  To install:" -ForegroundColor White
+    Write-Host "    npm install -g @anthropic-ai/claude-code" -ForegroundColor Cyan
+    Write-Host ""
+    Write-Host "  After installation, restart your terminal and try again."
+    Write-Host ""
+    Write-Host "============================================================" -ForegroundColor Red
+    Write-DebugLog "Exiting with code 1 - Claude CLI not found"
+    exit 1
+}
+Write-Host "  [OK] Claude CLI found" -ForegroundColor Green
+Write-DebugLog "Claude CLI check passed"
+
+# Check 2: Working directory exists
+if (-not (Test-Path $WorkingDirectory)) {
+    $errorMsg = "Working directory not found: $WorkingDirectory"
+    Write-DebugLog $errorMsg "ERROR"
+    Write-DebugLog "Exiting with code 1 - working directory not found"
+    Write-Host "  [ERROR] $errorMsg" -ForegroundColor Red
+    exit 1
+}
+Write-Host "  [OK] Working directory exists" -ForegroundColor Green
+Write-DebugLog "Working directory check passed: $WorkingDirectory"
+
+# Check 3: dev/pipeline directory exists
+$pipelineDir = Join-Path $WorkingDirectory "dev\pipeline"
+if (-not (Test-Path $pipelineDir)) {
+    $errorMsg = "Pipeline directory not found: $pipelineDir - Run Initialize Project first"
+    Write-DebugLog $errorMsg "ERROR"
+    Write-DebugLog "Exiting with code 1 - pipeline directory not found"
+    Write-Host "  [ERROR] $errorMsg" -ForegroundColor Red
+    exit 1
+}
+Write-Host "  [OK] Pipeline directory exists" -ForegroundColor Green
+Write-DebugLog "Pipeline directory check passed"
+
+# Check 4: Task queue file exists (will be created by sync if needed)
+$TaskQueueFile = Join-Path $WorkingDirectory "dev\pipeline\TASK_QUEUE.json"
+if (-not (Test-Path $TaskQueueFile)) {
+    Write-Host "  [WARN] Task queue not found, will be created by sync" -ForegroundColor Yellow
+    Write-DebugLog "Task queue file not found, will attempt sync" "WARN"
+}
+
+Write-Host "[CHECK] Prerequisites passed" -ForegroundColor Green
+Write-DebugLog "All prerequisite checks passed"
+Write-Host ""
+
+# Auto-sync task queue from markdown files
+Write-Host "[SYNC] Syncing task queue from markdown files..." -ForegroundColor Yellow
+Write-DebugLog "Starting task queue sync"
+
+# Look for sync script in the same directory as this script (not in user's project)
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+Write-DebugLog "Script directory (raw): $scriptDir"
+
+# Normalize path to handle \\?\ prefix from Tauri
+if ($scriptDir -and $scriptDir.StartsWith("\\?\")) {
+    $scriptDir = $scriptDir.Substring(4)
+    Write-DebugLog "Script directory (normalized): $scriptDir"
+}
+
+$syncScript = Join-Path $scriptDir "sync_task_queue.ps1"
+Write-DebugLog "Looking for sync script at: $syncScript"
+
+if (Test-Path $syncScript) {
+    Write-DebugLog "Found sync script, executing..."
+    try {
+        & $syncScript -WorkingDirectory $WorkingDirectory -Quiet | Out-Null
+        Write-Host "[SYNC] Task queue synced successfully" -ForegroundColor Green
+        Write-DebugLog "Task queue sync completed successfully"
+    } catch {
+        Write-DebugLog "Sync script execution failed: $_" "ERROR"
+        Write-Host "[SYNC] Sync failed: $_" -ForegroundColor Red
+    }
+} else {
+    Write-DebugLog "Sync script not found at primary location, trying fallback..."
+    # Fallback: check in user's working directory (for manual runs)
+    $syncScriptFallback = Join-Path $WorkingDirectory "dev\scripts\sync_task_queue.ps1"
+    Write-DebugLog "Fallback sync script path: $syncScriptFallback"
+
+    if (Test-Path $syncScriptFallback) {
+        Write-DebugLog "Found fallback sync script, executing..."
+        try {
+            & $syncScriptFallback -WorkingDirectory $WorkingDirectory -Quiet | Out-Null
+            Write-Host "[SYNC] Task queue synced successfully" -ForegroundColor Green
+            Write-DebugLog "Task queue sync completed successfully (fallback)"
+        } catch {
+            Write-DebugLog "Fallback sync script execution failed: $_" "ERROR"
+            Write-Host "[SYNC] Sync failed: $_" -ForegroundColor Red
+        }
+    } else {
+        Write-DebugLog "No sync script found at either location" "WARN"
+        Write-Host "[SYNC] sync_task_queue.ps1 not found, skipping auto-sync" -ForegroundColor Yellow
+    }
+}
+Write-Host ""
+
+Write-Log "Multi-Agent Scheduler started (MaxAgents=$MaxAgents)"
+
+# Backup task files before starting (prevent data loss)
+$backupResult = Backup-TaskFiles
+if ($backupResult) {
+    Write-DebugLog "Task files backed up to: $backupResult"
+}
+
+# CRITICAL: Clean stale state from previous sessions FIRST
+# This ensures locks, agents, and tasks are reset before any checks
+$null = Clear-StaleState
+
+# Run state consistency check (should find no issues after cleanup)
+$consistencyResult = Test-StateConsistency
+if ($consistencyResult.HasCriticalIssues) {
+    Write-Log "Critical state issues detected. Running sync to repair..." "WARN"
+    if (Test-Path $syncScript) {
+        & $syncScript -WorkingDirectory $WorkingDirectory -Force -Quiet | Out-Null
+        Write-Log "Forced sync completed" "SUCCESS"
+    }
+}
+
+# NOTE: Removed orphan Claude process cleanup
+# The previous logic was dangerous - it would terminate ALL Claude processes
+# including user's active VSCode Claude extension sessions.
+# If cleanup is needed, user should manually terminate processes before starting scheduler.
+Write-Log "Scheduler ready (stale state cleaned)"
+
+# Check if there are any pending tasks before starting the main loop
+$queue = Get-TaskQueue
+if ($queue) {
+    $pendingTasks = @($queue.tasks | Where-Object { $_.status -eq "pending" })
+    $completedTasks = @($queue.tasks | Where-Object { $_.status -eq "completed" })
+    $totalTasks = $queue.tasks.Count
+
+    if ($pendingTasks.Count -eq 0) {
+        Write-Host ""
+        Write-Host "============================================================" -ForegroundColor Yellow
+        Write-Host "  No pending tasks found!" -ForegroundColor Yellow
+        Write-Host "============================================================" -ForegroundColor Yellow
+        Write-Host ""
+        Write-Host "  Task Queue Status:"
+        Write-Host "    Total: $totalTasks"
+        Write-Host "    Completed: $($completedTasks.Count)"
+        Write-Host "    Pending: 0"
+        Write-Host ""
+        Write-Host "  To add tasks, you can:" -ForegroundColor White
+        Write-Host "    1. Run /product to generate PRD and tasks" -ForegroundColor Cyan
+        Write-Host "    2. Add task files to dev/pipeline/tasks/" -ForegroundColor Cyan
+        Write-Host "    3. Use /dev to start development manually" -ForegroundColor Cyan
+        Write-Host ""
+        Write-Host "============================================================" -ForegroundColor Yellow
+
+        if ($SingleRun) {
+            Stop-SchedulerCleanly -ExitCode 0 -Reason "No pending tasks (SingleRun mode)"
+        }
+
+        Write-Log "No pending tasks. Scheduler will wait for new tasks..."
+    } else {
+        Write-Log "Found $($pendingTasks.Count) pending task(s) out of $totalTasks total" "SUCCESS"
+    }
+} else {
+    Write-Host ""
+    Write-Host "============================================================" -ForegroundColor Red
+    Write-Host "  ERROR: Task queue not found or invalid!" -ForegroundColor Red
+    Write-Host "============================================================" -ForegroundColor Red
+    Write-Host ""
+    Write-Host "  Expected file: $TaskQueueFile"
+    Write-Host ""
+    Write-Host "  Run Initialize Project first to create the task queue."
+    Write-Host ""
+    Write-DebugLog "Task queue not found or invalid: $TaskQueueFile" "ERROR"
+    Write-DebugLog "Exiting with code 1 - task queue missing"
+    exit 1
+}
+
+# Clear stale agents and set scheduler status
+$schedulerState = @{
+    agents = @()
+    scheduler = @{
+        status = "running"
+        max_agents = $MaxAgents
+        started_at = (Get-Date -Format "o")
+    }
+    last_updated = (Get-Date -Format "o")
+}
+Save-AgentState $schedulerState
+Write-Log "Scheduler status set to 'running' in AGENT_STATE.json"
+
+# 活躍 Agent 追蹤
+$activeAgents = @{}
+
+# 同步計數器（每 5 次輪詢同步一次新任務）
+$syncCounter = 0
+$SyncIntervalCycles = 5
+
+# 保存狀態行位置（用於同一行更新，僅在交互式控制台）
+$statusLineRow = 0
+if ($script:IsInteractiveConsole) {
+    $statusLineRow = [Console]::CursorTop
+}
+
+Write-DebugLog "Entering main scheduler loop"
+
+try {
+    while ($true) {
+        # Check if scheduler was stopped via API (AGENT_STATE.json status)
+        $agentState = Get-AgentState
+        if ($agentState.scheduler.status -eq "stopped") {
+            Write-Log "Scheduler stop requested via API - shutting down..." "WARN"
+
+            # Terminate all active agents
+            foreach ($agentId in $activeAgents.Keys) {
+                $agent = $activeAgents[$agentId]
+                if (-not $agent.Process.HasExited) {
+                    Write-Log "Terminating agent $agentId (stop requested, PID: $($agent.Process.Id))"
+                    Stop-ProcessTree -ProcessId $agent.Process.Id
+                }
+                Remove-AgentLocks -AgentId $agentId
+                Remove-AgentFromState -AgentId $agentId
+            }
+            $activeAgents.Clear()
+
+            Write-Log "All agents terminated. Scheduler exiting." "SUCCESS"
+            Stop-SchedulerCleanly -ExitCode 0 -Reason "Scheduler stop requested via API"
+        }
+
+        # Check dashboard heartbeat - stop all agents if dashboard is closed
+        $heartbeatStatus = Test-DashboardHeartbeat
+        if (-not $heartbeatStatus.Alive) {
+            Write-Log "Dashboard disconnected: $($heartbeatStatus.Reason)" "WARN"
+            Write-Log "Stopping all agents due to dashboard disconnection..." "WARN"
+
+            # Terminate all active agents
+            foreach ($agentId in $activeAgents.Keys) {
+                $agent = $activeAgents[$agentId]
+                if (-not $agent.Process.HasExited) {
+                    Write-Log "Terminating agent $agentId (dashboard closed, PID: $($agent.Process.Id))"
+                    # Use process tree termination to ensure all child processes are killed
+                    Stop-ProcessTree -ProcessId $agent.Process.Id
+                }
+                Remove-AgentLocks -AgentId $agentId
+                Remove-AgentFromState -AgentId $agentId
+
+                # Reset task to pending for retry
+                Update-TaskStatus -TaskId $agent.TaskId -Status "pending"
+            }
+            $activeAgents.Clear()
+
+            # If dashboard explicitly closed, exit immediately
+            if ($heartbeatStatus.Reason -match "closing") {
+                Write-Log "Dashboard explicitly closed. Scheduler exiting." "SUCCESS"
+                Stop-SchedulerCleanly -ExitCode 0 -Reason "Dashboard explicitly closed"
+            }
+
+            # Wait for dashboard to reconnect (max 60 seconds)
+            $reconnectTimeout = 60
+            $waited = 0
+            Write-Log "Waiting up to ${reconnectTimeout}s for dashboard to reconnect..." "INFO"
+            while (-not (Test-DashboardHeartbeat).Alive -and $waited -lt $reconnectTimeout) {
+                Start-Sleep -Seconds 5
+                $waited += 5
+                Write-Host "." -NoNewline
+            }
+            Write-Host ""
+
+            if (-not (Test-DashboardHeartbeat).Alive) {
+                Write-Log "Dashboard did not reconnect within ${reconnectTimeout}s. Scheduler exiting." "WARN"
+                Stop-SchedulerCleanly -ExitCode 0 -Reason "Dashboard did not reconnect within timeout"
+            }
+
+            Write-Log "Dashboard reconnected! Resuming scheduler..." "SUCCESS"
+        }
+
+        # 定期同步新任務（每 5 個輪詢週期，或 Scheduler 空閒時）
+        $syncCounter++
+        $shouldSync = ($syncCounter -ge $SyncIntervalCycles) -or ($activeAgents.Count -eq 0)
+        if ($shouldSync) {
+            $syncCounter = 0
+            if (Test-Path $syncScript) {
+                & $syncScript -WorkingDirectory $WorkingDirectory -Quiet | Out-Null
+                # 不輸出日誌，避免洗版
+            }
+        }
+
+        # 檢查已完成的 Agent
+        $completedAgents = @()
+        foreach ($agentId in $activeAgents.Keys) {
+            $agent = $activeAgents[$agentId]
+
+            if ($agent.Process.HasExited) {
+                $exitCode = $agent.Process.ExitCode
+                $durationMin = [math]::Round(((Get-Date) - $agent.StartTime).TotalMinutes, 1)
+
+                # Use improved success detection
+                $successResult = Test-AgentSuccess -ExitCode $exitCode -LogFile $agent.LogFile -Branch $agent.Branch -TaskId $agent.TaskId
+                $isSuccess = $successResult.Success
+
+                if ($isSuccess -and $successResult.Reason -ne "Exit code 0") {
+                    Write-Log "Success detected via: $($successResult.Reason)" "INFO"
+                }
+
+                if ($isSuccess) {
+                    Write-Log "Agent $agentId completed task $($agent.TaskId) successfully ($durationMin min)" "SUCCESS"
+
+                    # Get task title before updating status
+                    $queue = Get-TaskQueue
+                    $taskTitle = ""
+                    foreach ($t in $queue.tasks) {
+                        if ($t.id -eq $agent.TaskId) {
+                            $taskTitle = $t.title
+                            break
+                        }
+                    }
+
+                    Update-TaskStatus -TaskId $agent.TaskId -Status "completed"
+
+                    # Move task file to completed folder
+                    Move-TaskToCompleted -TaskId $agent.TaskId
+
+                    # Update PROGRESS.md
+                    Update-ProgressFile -TaskId $agent.TaskId -TaskTitle $taskTitle -Action "Completed"
+
+                    # Merge task branch to main
+                    try {
+                        Push-Location $WorkingDirectory
+                        git checkout main 2>$null
+                        git merge $agent.Branch -m "Merge $($agent.TaskId): Completed by $agentId" 2>$null
+                        git branch -d $agent.Branch 2>$null
+                        Pop-Location
+                        Write-Log "Merged branch $($agent.Branch) to main" "SUCCESS"
+                    } catch {
+                        Pop-Location
+                        Write-Log "Failed to merge branch: $_" "WARN"
+                    }
+                } else {
+                    $exitCodeStr = if ($null -eq $exitCode -or $exitCode -eq "") { "null" } else { $exitCode }
+                    Write-Log "Agent $agentId failed task $($agent.TaskId) after $durationMin min (exit: $exitCodeStr)" "ERROR"
+                    Write-Log "Failure reason: $($successResult.Reason)" "ERROR"
+
+                    # Read error log for debugging
+                    if ($agent.LogFile -and (Test-Path "$($agent.LogFile).err")) {
+                        $errContent = Get-Content "$($agent.LogFile).err" -Raw -ErrorAction SilentlyContinue
+                        if ($errContent -and $errContent.Trim().Length -gt 0) {
+                            Write-Log "Agent error: $($errContent.Substring(0, [Math]::Min(500, $errContent.Length)))" "ERROR"
+                        }
+                    }
+
+                    # Check if there's partial work done (branch with commits) - mark for resume instead of full reset
+                    $hasPartialWork = $false
+                    if ($agent.Branch) {
+                        try {
+                            Push-Location $WorkingDirectory
+                            $null = git rev-parse --verify $agent.Branch 2>$null
+                            if ($LASTEXITCODE -eq 0) {
+                                $mainBranch = "main"
+                                $null = git rev-parse --verify main 2>$null
+                                if ($LASTEXITCODE -ne 0) { $mainBranch = "master" }
+                                $commitsAhead = git rev-list --count "${mainBranch}..$($agent.Branch)" 2>$null
+                                if ($LASTEXITCODE -eq 0 -and [int]$commitsAhead -gt 0) {
+                                    $hasPartialWork = $true
+                                    Write-Log "Branch $($agent.Branch) has $commitsAhead commit(s) - marking for resume" "INFO"
+                                }
+                            }
+                            Pop-Location
+                        } catch {
+                            Pop-Location
+                        }
+                    }
+
+                    # Reset task to pending for retry, potentially with resume info
+                    if ($hasPartialWork) {
+                        $queue = Get-TaskQueue
+                        if ($queue) {
+                            foreach ($t in $queue.tasks) {
+                                if ($t.id -eq $agent.TaskId) {
+                                    $t.status = "pending"
+                                    $t | Add-Member -NotePropertyName "resume_branch" -NotePropertyValue $agent.Branch -Force
+                                    if ($t.PSObject.Properties["assigned_agent"]) {
+                                        $t.PSObject.Properties.Remove("assigned_agent")
+                                    }
+                                    break
+                                }
+                            }
+                            $queue.last_updated = (Get-Date -Format "o")
+                            $jsonContent = $queue | ConvertTo-Json -Depth 10
+                            Write-FileWithRetry -Path $TaskQueueFile -Content $jsonContent
+                        }
+                    } else {
+                        Update-TaskStatus -TaskId $agent.TaskId -Status "pending"
+                    }
+                }
+
+                # 釋放鎖
+                Remove-AgentLocks -AgentId $agentId
+                $completedAgents += $agentId
+            } else {
+                # 檢查超時
+                $elapsed = ((Get-Date) - $agent.StartTime).TotalMinutes
+                if ($elapsed -gt $TaskTimeoutMinutes) {
+                    Write-Log "Agent $agentId timed out on task $($agent.TaskId) (PID: $($agent.Process.Id))" "WARN"
+                    # Use process tree termination to ensure all child processes are killed
+                    Stop-ProcessTree -ProcessId $agent.Process.Id
+                    Remove-AgentLocks -AgentId $agentId
+                    $completedAgents += $agentId
+                }
+            }
+        }
+
+        # 清理已完成的 Agent
+        foreach ($agentId in $completedAgents) {
+            $activeAgents.Remove($agentId)
+            # 從 AGENT_STATE.json 移除 (for dashboard)
+            Remove-AgentFromState -AgentId $agentId
+        }
+
+        # 檢查是否可以啟動新 Agent
+        $availableSlots = $MaxAgents - $activeAgents.Count
+
+        if ($availableSlots -gt 0) {
+            $queue = Get-TaskQueue
+
+            if ($queue) {
+                $readyTasks = Get-ReadyTasks -Queue $queue
+                $lockState = Get-LockState
+
+                # Only log when there are ready tasks to potentially launch
+                if ($readyTasks.Count -gt 0) {
+                    Write-Host ""  # New line before log message
+                    Write-Log "Found $($readyTasks.Count) ready task(s), checking availability..."
+                }
+
+                foreach ($task in $readyTasks) {
+                    if ($availableSlots -le 0) { break }
+
+                    # 跳過已經在執行的任務
+                    $alreadyRunning = $false
+                    foreach ($agent in $activeAgents.Values) {
+                        if ($agent.TaskId -eq $task.id) {
+                            $alreadyRunning = $true
+                            break
+                        }
+                    }
+                    if ($alreadyRunning) { continue }
+
+                    # 取得任務 scope
+                    $scopePaths = @()
+                    # 優先使用 scope_paths（新格式）
+                    if ($task.scope_paths) {
+                        $scopePaths += $task.scope_paths
+                    }
+                    # 向下相容：檢查舊格式 scope.paths / scope.files
+                    elseif ($task.scope) {
+                        if ($task.scope.paths) { $scopePaths += $task.scope.paths }
+                        if ($task.scope.files) { $scopePaths += $task.scope.files }
+                    }
+
+                    # 如果沒有定義 scope，使用預設路徑
+                    if ($scopePaths.Count -eq 0) {
+                        $scopePaths = @("src/")
+                    }
+
+                    # 檢查路徑衝突
+                    $conflict = Test-PathConflict -RequestedPaths $scopePaths -LockState $lockState
+
+                    if ($conflict.Conflict) {
+                        Write-Log "Task $($task.id) conflicts with $($conflict.HeldBy) on $($conflict.ConflictingPath)" "WARN"
+                        continue
+                    }
+
+                    # Determine agent type (smart dispatch)
+                    $explicitType = $null
+                    if ($task.agent_type) {
+                        $explicitType = $task.agent_type
+                    }
+                    $agentType = Get-AgentType -TaskId $task.id -TaskTitle $task.title -ScopePaths $scopePaths -ExplicitType $explicitType
+
+                    # 啟動 Agent
+                    $agentId = New-AgentId
+                    $agentInfo = Start-AgentWorker -AgentId $agentId -TaskId $task.id -TaskTitle $task.title -ScopePaths $scopePaths -AgentType $agentType
+
+                    if ($agentInfo -and $agentInfo -is [hashtable]) {
+                        try {
+                            # Store agent type in agent info for later reference
+                            $agentInfo.AgentType = $agentType
+
+                            # 加入鎖
+                            Add-PathLocks -AgentId $agentId -TaskId $task.id -Paths $scopePaths
+
+                            # 更新任務狀態
+                            Update-TaskStatus -TaskId $task.id -Status "in_progress" -AgentId $agentId -Branch $agentInfo.Branch
+
+                            # 更新 AGENT_STATE.json (for dashboard) with agent type
+                            Add-AgentToState -AgentId $agentId -TaskId $task.id -TaskTitle $task.title -Branch $agentInfo.Branch -Status "working" -AgentType $agentType
+
+                            # 追蹤 Agent (CRITICAL: must happen for cleanup to work)
+                            $activeAgents[$agentId] = $agentInfo
+                            $availableSlots--
+
+                            $displayName = Get-AgentDisplayName -AgentType $agentType
+                            Write-Log "Launched $displayName ($agentId) for $($task.id): $($task.title)"
+                        } catch {
+                            Write-Log "Error setting up agent $agentId for task $($task.id): $_" "ERROR"
+                            # Agent process was started but setup failed - must still track it for cleanup
+                            if ($agentInfo.Process -and -not $agentInfo.Process.HasExited) {
+                                $activeAgents[$agentId] = $agentInfo
+                                Write-Log "Agent $agentId still tracked for cleanup despite setup error" "WARN"
+                            }
+                            # Release any locks that were acquired
+                            Remove-AgentLocks -AgentId $agentId
+                        }
+                    }
+                }
+            }
+        }
+
+        # 顯示狀態 (更新同一行，避免洗版)
+        $timestamp = Get-Date -Format "HH:mm:ss"
+        $statusLine = "[$timestamp] Agents: $($activeAgents.Count)/$MaxAgents"
+        if ($activeAgents.Count -gt 0) {
+            $agentInfo = @()
+            foreach ($agent in $activeAgents.Values) {
+                $elapsedMin = [math]::Round(((Get-Date) - $agent.StartTime).TotalMinutes, 1)
+                $agentInfo += "$($agent.TaskId)($elapsedMin min)"
+            }
+            $statusLine += " | " + ($agentInfo -join ", ")
+        } else {
+            $statusLine += " | Waiting for tasks..."
+        }
+        # 顯示狀態（交互式用同行更新，非交互式用普通輸出）
+        if ($script:IsInteractiveConsole) {
+            [Console]::SetCursorPosition(0, $statusLineRow)
+            [Console]::ForegroundColor = [ConsoleColor]::Cyan
+            [Console]::Write($statusLine.PadRight(100))
+            [Console]::ResetColor()
+        } else {
+            Write-Host $statusLine -ForegroundColor Cyan
+        }
+
+        if ($SingleRun -and $activeAgents.Count -eq 0) {
+            Write-Log "Single run completed, no active agents"
+            break
+        }
+
+        # 等待下一個輪詢週期
+        Start-Sleep -Seconds $PollIntervalSeconds
+    }
+} catch {
+    $errorMsg = "FATAL ERROR in main loop: $_"
+    Write-DebugLog $errorMsg "ERROR"
+    Write-DebugLog "Stack trace: $($_.ScriptStackTrace)" "ERROR"
+    Write-Log $errorMsg "ERROR"
+    throw
+} finally {
+    # 清理：終止所有 Agent 並釋放鎖
+    Write-Log "Shutting down scheduler..."
+    Write-DebugLog "Entering finally block - cleanup starting"
+
+    foreach ($agentId in $activeAgents.Keys) {
+        $agent = $activeAgents[$agentId]
+        if (-not $agent.Process.HasExited) {
+            Write-Log "Terminating agent $agentId (PID: $($agent.Process.Id))"
+            Write-DebugLog "Terminating agent $agentId (PID: $($agent.Process.Id))"
+            # Use process tree termination to ensure all child processes are killed
+            Stop-ProcessTree -ProcessId $agent.Process.Id
+        }
+        Remove-AgentLocks -AgentId $agentId
+    }
+
+    # 清理 AGENT_STATE.json - 移除所有 agents 並設置 scheduler 為 stopped
+    $agentState = @{
+        agents = @()
+        scheduler = @{
+            status = "stopped"
+            stopped_at = (Get-Date -Format "o")
+        }
+        last_updated = (Get-Date -Format "o")
+    }
+    Save-AgentState $agentState
+    Write-Log "Cleared AGENT_STATE.json and set scheduler to 'stopped'"
+    Write-DebugLog "Cleanup completed, scheduler stopped"
+
+    Write-Log "Scheduler stopped"
+}