【ITニュース解説】Isolation, file ownership and cleanup: the boring half of running coding agents in parallel on Windows

システムエンジニアを目指す初心者がプログラミングの自動化ツールや開発環境を並行して動かす際に直面する、見過ごされがちな重要ポイントについて解説する。複数の「コーディングエージェント」（自動でコードを生成したり、開発作業を補助したりするプログラム）を安定して運用するためには、システムレベルの「地味な」管理が不可欠である。特にWindows環境では、その複雑さから多くの落とし穴が存在する。

まず「分離（Isolation）」が重要である。これは、それぞれのエージェントが互いに干渉しないよう、独立した作業スペースを持つことを意味する。同じWindowsアカウントで複数のエージェントを動かすと、設定ファイルや認証情報が保存される共通のホームディレクトリを共有してしまう。例えば、異なる認証情報で個別のAIアシスタントを使いたい場合、共有ホームディレクトリではそれができない。 Windows環境では、Linuxで一般的なHOME環境変数を設定するだけでは不十分である。HOMEはPOSIX標準の慣習であり、一部のツールは尊重するが、Windows自体はそうではない。そのため、HOMEだけを設定しても、一部のツールは新しい場所に設定を書き込むが、Gitなどの他のツールは依然として古いホームディレクトリに.gitconfigなどの設定ファイルを書き込み、予期せぬトラブルの原因となる。Windowsで完全に分離されたホームディレクトリをプロセスごとに実現するには、HOME、USERPROFILE、HOMEDRIVE、HOMEPATHの各環境変数をセットする必要がある。特定のCLIツールは独自の環境変数を要求する場合もあるため、ツールのドキュメントを確認することが必要だ。Node.jsのos.homedir()関数は、子プロセスに注入したUSERPROFILE変数を確実に反映しないことがあるため、ストレージの場所を決定する専用の環境変数を用意するなどの工夫が求められる。

しかし、完全な分離が常に望ましいわけではない。例えば、AIアシスタントのスキル定義や共通の設定ファイルは、複数のエージェントで共有したい場合がある。このような場合、ファイルを複製するのではなく、元の共有ファイルへの「リンク」を作成する方法が有効である。 Windowsでリンクを作成するには「シンボリックリンク」「ジャンクション」「ハードリンク」がある。ファイルシンボリックリンクには管理者権限が必要となるため、ディレクトリに対するジャンクションや、ファイルに対するハードリンクが代替手段としてよく使われる。 ハードリンクを使う際には注意が必要だ。ハードリンクはシンボリックリンクとは異なり、プログラムがリンク状況をチェックする際（例：lstat().isSymbolicLink()）、falseが返される。これにより、ユーザーが「共有設定からこのアカウントを切り離す」操作を実行しても、ハードリンクされたファイルは切り離されず、ユーザーは気づかないまま共有設定を編集し続けてしまう可能性がある。ハードリンクを正確に検出するには、ファイルのID（デバイスIDとinode番号）を比較する必要がある。WindowsではlstatSync関数のbigint: trueオプションを使い、デバイスIDとinode番号が一致し、かつinode番号が0ではないことを確認することで、同じファイルかどうかを判定できる。

次に、「ファイルの所有権」と「クリーンアップ」に関する問題がある。Windowsでは、ファイルを削除しようとすると「アクセス拒否」エラーが出ることがよくあるが、これはLinuxとは異なる意味を持つことが多い。Windowsでは、あるプロセスがディレクトリを「現在の作業ディレクトリ（CWD）」として使用している場合、そのディレクトリを削除することはできない。Gitが作業ツリーを削除しようとしてこのエラーに遭遇することが頻繁にあるが、実際にはファイルのアクセス権の問題ではなく、単にディレクトリがプロセスによって掴まれているためである。Linuxでは同じ状況で削除が成功するため、Windowsユーザーがこのバグに遭遇しても再現が難しいという事態が起きやすい。 この問題をさらに複雑にする要因として、PowerShellのSet-Locationコマンドは、プロセス自体のCWDを変更するわけではないため、ディレクトリは解放されない。また、ディレクトリを掴んでいるのが親プロセスだけでなく、その子プロセスがCWDを継承し、ディレクトリを保持し続けることもある。したがって、ディレクトリを解放するためには、単一のプロセスを終了させるだけでなく、そのプロセスツリー全体を終了させる必要がある。 作業ツリーを管理する際には、どのエージェントがどのディレクトリ内にいるかを記録し、作業ツリーを削除する際には、そのパスをプレフィックスとして持つプロセスツリー全体を終了させる必要がある。Windowsではパスの表記が異なる場合があるため、パスを正規化して比較することも忘れずに行う。

「失敗した実行後のクリーンアップ」も厄介な問題だ。例えば、git worktree removeが途中で失敗した場合、Gitは作業ツリーの内容や管理ディレクトリを削除し、git worktree listからエントリを削除した後に、ロックされたトップレベルのディレクトリにぶつかって停止することがある。その結果、Gitがもはや認識しない空のフォルダが残され、Gitコマンドでは削除できず、宙ぶらりんの状態となる。 この状態から完全に復旧するためには、手動での介入と正しい手順が求められる。まず、ディレクトリを掴んでいるプロセスツリー全体を終了させる。次に、そのディレクトリを手動で削除する。最後にgit worktree pruneを実行し、Gitが自身のメタデータのクリアまで到達していなかった場合の残骸を削除する。この順序は重要であり、誤った順序で行うと問題を複雑にする可能性がある。 また、部分的な削除を成功と見なさないことも極めて重要である。もし、一部のステップが失敗したにもかかわらず、システムが「削除が完了した」と判断して自身の記録を削除してしまうと、次に状況を確認した際に、実際には残っている作業ツリーが突然「健全な状態」として再表示され、UIからは二度と削除できなくなる。エラーメッセージを出す方が、誤った成功を報告するよりもはるかに良い。 継続的な管理の観点からは、「読み込み時に調整する」という原則が重要だ。ユーザーがアプリケーションを使わずに手動で作業ツリーを削除した場合、アプリケーション自身の記録は古くなるため、リストを表示するたびにgit worktree listの結果と照合し、Gitが認識しなくなったエントリを削除する必要がある。さらに、作業ツリーを.gitディレクトリの内部に作成してはならない。これはGit自身のメタデータフォルダであり、Gitはこれを作業ツリーとして認識しないため、削除が永久に失敗し、手動削除以外に復旧手段がなくなる。

エージェントを起動する前に実行する設定コマンド（例：npm install、.envファイルのコピー、ビルドコマンドなど）も、トラブルの温床となりやすい。

• コマンドごとのタイムアウト設定：何も出力せず、いつまでも終了しないコマンドは深刻な問題を引き起こすため、各コマンドにタイムアウトを設定し、超過したら強制終了する仕組みが必要である。
• ティアダウン時のキャンセル：作業ツリーを削除しようとした際に、設定コマンドがまだ実行中であるなら、まずそのコマンドをキャンセルする。さもなければ、ファイルを書き込んでいる最中のディレクトリを削除しようとすることになり、ファイル削除問題に逆戻りする。
• ログの機密情報削除（Redaction）：設定スクリプトの実行ログには、APIトークンなどの機密情報が含まれることがある。これらのログを永続化する際には、保存時に機密情報を除去する処理を施す必要がある。

最後に、「ログ」の問題がある。複数のエージェントが並行して動く環境では、問題が発生した際に何が起きたのかを正確に把握することが非常に難しい。各エージェントごとの個別のログは存在するかもしれないが、それらを統合した「統一されたタイムラインログ」（どのエージェントが、いつ、何を、どのような順序で行ったか、終了コードは何か、など）は、構築が非常に困難な課題である。夜間に複数のエージェントが動作し、そのうちのどれかが失敗した場合、どのエージェントがどのファイルに触れ、どのような順序で操作したのかを把握することは、個別のログを一つ一つ追うだけでは非常に労力がかかる。これはまだ未解決の課題であり、実装が複雑であるため、明確な解決策が確立されていないのが現状だ。

これらの地味で目立たない課題は、表面的な「起動」の仕組みよりもはるかに複雑で、システムの安定運用において極めて重要である。特にWindows環境では、Linuxとは異なるエラー挙動や不親切なエラーメッセージに遭遇しやすく、安定した「ティアダウン（終了処理）」を実装することは多大なコストを伴う。