コンテンツにスキップ
Minion Docs

Windowsミニオンが停止できない

Windowsミニオンのアップデートに失敗してパッケージファイルが破損すると、minion-cli-win stop が .env 読み込みやエージェントAPI呼び出しの段階で失敗し、サービスが止められなくなることがあります。NSSM（Windowsサービスマネージャ）が node.exe を再起動し続けるため、node_modules\@geekbeer\minion\ 配下のファイルがロックされたままとなり、npm uninstall -g @geekbeer/minion も失敗します。

まず試す: stop --force（v3.43.0以降）

Section titled “まず試す: stop --force（v3.43.0以降）”

v3.43.0 から、graceful shutdown を完全にスキップして全サービスとプロセスを強制停止する --force フラグが追加されています。管理者権限のPowerShellで実行してください。

Terminal window
minion-cli-win stop --force

このコマンドは以下を順に実行します:

  1. NSSM の AppExit を Exit + AppThrottle 0 に書き換え、自動再起動を一時的に無効化
  2. sc.exe stop で minion-agent / minion-websockify / minion-cloudflared / minion-vnc を停止
  3. tvnserver / websockify / cloudflared を Stop-Process -Force で強制終了
  4. Win32_Process の CommandLine がミニオン関連スクリプトに一致する node.exe をすべて kill
  5. 完了後に AppExit Default Restart を復元（次回 minion-cli-win start を通常運用に戻すため）

進行中のチャットやワークフローは強制中断され、HQ への offline heartbeat 通知（/api/shutdown）もスキップされます。HQ ダッシュボードの状態表示は heartbeat タイムアウトまでオンラインのまま残ります。

stop --force も使えない場合（手動手順）

Section titled “stop --force も使えない場合（手動手順）”

CLI 自体が壊れて起動しない場合や v3.43.0 未満の場合は、管理者PowerShellから手動で同じ処理を行います。

Terminal window
# 1. NSSM サービスの自動再起動を無効化してから停止 → 削除
$nssm = "$env:USERPROFILE\.minion\nssm.exe"   # vendor版なら %APPDATA%\npm\node_modules\@geekbeer\minion\win\vendor\nssm.exe
foreach ($svc in 'minion-agent','minion-websockify','minion-cloudflared','minion-vnc') {
    & $nssm set $svc AppExit Default Exit  2>$null
    & $nssm set $svc AppThrottle 0         2>$null
    sc.exe stop $svc 2>$null
    Start-Sleep -Seconds 2
    & $nssm remove $svc confirm 2>$null
}


# 2. スケジュールタスク削除
Unregister-ScheduledTask -TaskName MinionWSL -Confirm:$false -ErrorAction SilentlyContinue
Unregister-ScheduledTask -TaskName MinionVNC -Confirm:$false -ErrorAction SilentlyContinue


# 3. 残存ヘルパープロセスを強制終了
Stop-Process -Name tvnserver,websockify,cloudflared -Force -ErrorAction SilentlyContinue


# 4. ミニオン関連の node.exe のみ kill（他用途の node は触らない）
Get-CimInstance Win32_Process -Filter "Name='node.exe'" |
    Where-Object { $_.CommandLine -match 'minion|@geekbeer\\minion|terminal-server|workflow-runner|routine-runner|wsl-session-server' } |
    ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }

それでもファイルロックが残る場合

Section titled “それでもファイルロックが残る場合”

上記でほとんどのケースは解放されますが、ロックが残っているときは原因プロセスを特定します。

Terminal window
$pkg = "$env:APPDATA\npm\node_modules\@geekbeer\minion"   # グローバルインストール先
Get-Process | Where-Object { $_.Modules.FileName -like "$pkg\*" } |
    Select-Object Id, ProcessName

Sysinternals Handle があれば、より確実に特定できます。

Terminal window
handle64.exe -nobanner $pkg

表示されたPIDを Stop-Process -Id <PID> -Force で停止してください。最終手段としてOS再起動が確実ですが、再起動前に Set-Service minion-agent -StartupType Disabled でサービスの自動起動を無効化しておくと、再起動後すぐにファイルが解放されます。

パッケージの再インストール

Section titled “パッケージの再インストール”

サービスとプロセスが停止できれば、通常通り再インストールできます。

Terminal window
npm uninstall -g @geekbeer/minion
Remove-Item -Recurse -Force "$env:APPDATA\npm\node_modules\@geekbeer\minion" -ErrorAction SilentlyContinue
npm install -g @geekbeer/minion
minion-cli-win setup

通常時は stop --force を使わないこと

Section titled “通常時は stop --force を使わないこと”

stop --force は graceful shutdown を完全にスキップするため、以下の副作用があります:

  • 進行中のチャット・ワークフロー・ターミナルセッションが強制中断される
  • HQ への offline heartbeat が送られず、ダッシュボード上は heartbeat タイムアウト（数十秒〜数分）までオンライン扱いのままになる
  • 書き込み途中のログやSQLiteが中途半端な状態で終わる可能性がある

通常運用では引き続き minion-cli-win stop（graceful）を使用してください。--force は graceful stop が機能しないとき限定の緊急手段 です。