agent viewのbackground serviceが応答しないときの直し方

attachやpeek、claude logsで「background service did not respond」と出たら、バックグラウンドセッションを預かるsupervisor(常駐のバックグラウンドサービス)が固まっている可能性が高い状況です。直し方は、そのsupervisorだけを止めて、新しいものを起動させることです。

--keep-workersを付ければ、動いているセッションを止めずに済みます。ただし、新しいsupervisorを立ち上げる猶予は止めてから約1分です。以下、切り分けから復旧、daemon.lockを消す分岐までを順に説明します。

このメッセージは何が止まっているサインか

agent viewに並ぶセッションは、すべてsupervisorの配下で動くバックグラウンドセッションです。端末を閉じても動き続けるのはこのためです。attach、peek、claude logsは、どれもsupervisorに問い合わせて結果を受け取ります。

その問い合わせに返事がないときに出るのが、このメッセージです。セッション本体の不調ではなく、窓口のsupervisorが止まっている状態です。supervisorは最初にセッションをバックグラウンドへ送るか、agent viewを開いたときに、勝手に起動します。手で管理するものではありません。

起動はしたが受け付けないときは自動で直る

supervisorが起動しても接続を受け付けられない場合は、自分でロックを手放して終了します。次のclaude agentsが新しいsupervisorを立ち上げるので、手動の操作は要りません。

マシンのスリープだけでは、セッションもsupervisorも止まりません。復帰するとsupervisorがセッションへ再接続します。止まるのはシャットダウンのときで、こちらは再起動後にattachか返信で再開します。

手動の停止が要るのは、すでに動いているsupervisorが固まったときです。メッセージの出方だけでは両者を見分けられないので、先に状態を確かめます。

まずclaude daemon statusで状態を見る

claude daemon statusは、supervisorに届くかどうか、プロセスID、バージョン、ソケットのディレクトリ、生きているバックグラウンドセッションの数を表示します。 何も動いていない環境では次のように出ます。空の設定ディレクトリでv2.1.296を使って確認した出力です(ソケットのパスは省略しています)。

CLAUDE_CONFIG_DIR=$(mktemp -d) claude daemon status

not running
 
bg sessions:
  sock dir:     /tmp/cc-daemon-<uid>/<hash>
  control.sock: unreachable (connect ENOENT .../control.sock)
  bg workers:   0 in roster.json (control unreachable)
  roster.json:  absent
  daemon.log:   absent

この出力は「supervisorが存在しない」ケースの見え方です。supervisorが動いていれば、プロセスIDとバージョンが表示されます。そのうえでdaemon.logの末尾を見ておくと、止める前の様子を残せます。

claude daemon status
claude daemon logs

claude daemon logsは~/.claude/daemon.logを追いかけて表示し、Ctrl+Cで抜けます。

入れ替えても残るもの

supervisorが管理する状態は設定ディレクトリの下にあります。~/.claude/daemon.logがsupervisorのログ、~/.claude/daemon/roster.jsonが動いているバックグラウンドセッションの一覧です。新しいsupervisorは、この一覧を手がかりにセッションへ再接続します。

セッションに選んだ権限モード、モデル、effortも、supervisorがプロセスを再起動したあとまで保たれます。/modelや/effortで途中から変えた値も同様です。

セッションを残したままsupervisorだけ入れ替える

claude daemon stop --any --keep-workers
claude agents

--anyは、Claude Codeが必要に応じて自動で起動したsupervisor(サービスとしてインストールしていないもの)も止める指定です。--keep-workersを付けないと、バックグラウンドセッションも一緒に終了します。

1分を過ぎるとどうなるか

supervisorが止まると、各セッションのプロセスは新しいsupervisorが戻るのを約1分待ち、来なければ自分で終了します。これはmacOSとLinuxの挙動です。

1分を過ぎても会話は消えません。保存済みの会話はディスクに残っており、そのセッションにattachするか返信すれば、保存した会話から再開します。ただし、実行中の監視(モニター)のように、プロセスと一緒に止まる作業もあります。

そのため、stopとclaude agentsは続けて実行するのが安全です。手順をコピーするときは、2行をまとめて貼り付ける形にしておくと、間が空きません。

「recorded process couldn't be verified」と出たらdaemon.lockを消す

claude daemon stopが、記録されているプロセスをsupervisorとして確認できないという趣旨で終了することがあります。そのときは次の順で進めます。

rm ~/.claude/daemon.lock
claude agents

順番は、プロセスの確認が先、ロックの削除が後です。動いているsupervisorを自分で止めてからでないと、ロックを消す意味がありません。

CLAUDE_CONFIG_DIRを設定している環境では、supervisorは~/.claudeではなくそのディレクトリを使い、別のインスタンスとして動きます。ロックの場所も、そのディレクトリの下になります。

Windowsではtaskkillが必要になることがある

Windowsでは、supervisorが停止要求に応じないとき、コマンドがプロセスIDを表示します。そのIDに対してtaskkill /PID <pid>を実行すれば復旧できます。--keep-workersを付けていれば、この場合もバックグラウンドセッションは保たれます。

Windowsには、ロックにまつわる別の症状もあります。v2.1.257より前は、マシンの前回起動より古いロックが残っていると、起動のたびに「exited before it became reachable」で失敗し、daemon.lockを消すまで直りませんでした。v2.1.257以降は、そうしたロックや、記録されたプロセスIDが別のプロセスのものになったロックは自動で置き換えられます。

似たメッセージとの見分け方

supervisor関連のエラーは文面が近いものが多く、対処が違います。

最後の認証エラーも、復旧は同じclaude daemon stop --any --keep-workersです。止めたあと、約1分以内にclaude agentsかclaude --bgを実行します。ANTHROPIC_API_KEYのような環境変数で認証している場合は、その変数を設定したシェルから実行してください。

起動時のEACCESやEUNKNOWNのように、そもそもsupervisorを起動できない症状は別の原因です。EUNKNOWNとEACCESの切り分けを見てください。Homebrewの更新直後にセッションが落ちる件はHomebrewアップグレード後のdaemon ENOENTに書いています。

更新後のバージョン不一致でも同じコマンドを使う

claude daemon statusには、動いているsupervisorのバージョンと手元のclaudeが違うときの警告があります。自動更新の直後で、supervisorがまだ新バージョンに入れ替わっていない場合に出ます。警告には両方のバージョンと、claude daemon stop --anyで入れ替える案内が付きます。

この場合もセッションを残したいなら、--keep-workersを付けた形が使えます。セッションが古いバイナリのまま動いているのが気になるときは、claude respawn --allで全セッションを新しいバイナリへ再起動する手もあります。

supervisorの設計全体(自動更新時の引き継ぎや、アイドルセッションが止まる条件)は、agent viewの常駐プロセス設計で扱っています。バックグラウンドセッションが終了時に引き継ぐ作業の扱いは、終了時の引き継ぎを止める設定にあります。