コンテンツにスキップ

af-arch-repair

ワークスペースが別の CPU アーキテクチャ(amd64 ↔ arm64)のマシンに移ったあと、ホームディレクトリに自分で入れたものを 同じバージョンで入れ直します。ワークスペースが、その起動の中で自動で実行します。手で実行するのは、やり直すときと、 まだ壊れているものを確かめるときだけです。失敗した入れ直しは、そのあとの何回かの起動でやり直します。 見つけたけれど直してはいけない残りものと、やり直しをやめた入れ直しは、Console の通知で知らせます。 見つけるのは調べる対象のものだけで、すべてではありません。限界 を見てください。

Agent Fleet 自身が入れるツール(エージェントの CLI、選んだ JDK と Node.js、Chromium)は、af-arch-repair ではなく ワークスペースの起動が入れ直します。

ターミナルウィンドウ
af-arch-repair <was> <now>

<was> と <now> は、前といまのアーキテクチャで、amd64 か arm64 です。<was> はメッセージに出るだけです。 <now> がないと usage: af-arch-repair <was> <now> を出して、終了コード 2 で終わります。

ターミナルウィンドウ
af-arch-repair amd64 arm64
ターミナルウィンドウ
af-arch-repair --due

--due は何も変えず、何も出しません。失敗した入れ直しが、自動のやり直しか、あきらめて通知を出す起動を待っているとき (やり直し を見てください)は終了コード 0、そうでなければ 1 で終わります。ワークスペースの起動が使います。

もの 対象 方法
pip install --user のパッケージ ファイルの一覧に、別のアーキテクチャ用にビルドされたネイティブ拡張があるもの。ピュア Python のものには触りません pip install --user --force-reinstall --no-deps <名前>==<バージョン> を 1 つずつ実行します。--no-deps で依存はそのまま残します
uv tool のツール 環境の中に、別のアーキテクチャ用のネイティブ拡張(*-linux-gnu.so)があるもの uv tool install --force --reinstall <ツール>==<バージョン>。ツールのバージョンが読めないときは ==<バージョン> を付けないので、最新バージョンが入ります
~/.local に npm install -g したパッケージ アーキテクチャが変わった起動の最初に、ワークスペースが ~/.local/lib/node_modules を消す前に控えたもの npm install -g --prefix ~/.local <名前>@<バージョン> を 1 つずつ実行します

npm の一覧は、アーキテクチャが変わる起動でワークスペースが書きます。前の変更から残っている項目があれば、それに、これから 消すものを足します。一覧は、そこにあるパッケージがそれぞれ入れ直せるまで残ります(やり直し を見てください)。 手で実行したときに npm のパッケージを入れ直すのは、この一覧があるときだけです。

次のものには触らず、名前を出して知らせます。

もの 触らない理由 直しかた
~/repos の下のビルド生成物。別のアーキテクチャ用のバイナリを含む node_modules、target、.venv 未コミットの作業がある場所だから npm ci、cargo clean && cargo build、.venv の作り直し
~/.local/bin に自分で置いた、別のアーキテクチャ用のプログラム 出どころが分からないから ダウンロードかビルドをやり直します

af-arch-repair は、ディレクトリがあるかどうかではなく、バイナリそのものを調べます。ピュア JavaScript の node_modules は 知らせず、直したものは次に実行したときから知らせなくなります。

見つけられなかったものは、直しも知らせもしません。特に次の点に注意してください。

  • pip のパッケージは、ファイル名にアーキテクチャが入ったネイティブ拡張で見つけます。名前とバージョンが読めないものも対象外です。 どちらの場合も入れ直しません。
  • ~/repos では、各作業コピーの直下にある node_modules、target、.venv だけを見ます。もっと深いサブプロジェクトは 見ません。それぞれ最初に見つけた .node ファイル(node_modules)か .so ファイル(target、.venv)で判断するので、 混ざっているディレクトリは知らせないことがあり、そこでビルドしたプログラムは調べません。
  • ~/.local/bin では、そこに直接置いたプログラムだけを見ます。

移ったあとに Exec format error やモジュールが見つからないエラーが出るものは、新しいマシンと同じように、ビルドや インストールをやり直してください。

自分の行は [arch-repair] で始まります。その間に、pip、uv、npm の出力がそのまま出ます。

[arch-repair] pip: 2 件を同じ版で入れ直します: greenlet==3.0.3 PyYAML==6.0.1
...
[arch-repair] pip: 完了
[arch-repair] ⚠️ ~/repos のビルド生成物が amd64 用のままです(~/repos は触っていません):
[arch-repair] ⚠️ shop/node_modules
[arch-repair] ⚠️ 直す: node_modules → npm ci / target → cargo clean && cargo build / .venv → 作り直し
[arch-repair] 完了

入れ直しに失敗すると、手で実行するコマンドを書いた WARN: の行を出します。最後の行には、まだ入れ直しが要るものと、 あとの起動でもう一度試すかどうかが出ます。

[arch-repair] 入れ直せなかったものが残っています: pip:greenlet==3.0.3(次の起動で自動でもう一度試します。自動で試すのはあと 3 回です)

ワークスペースの起動の中では、この出力は起動のログに出るので、見ることはできません。見えるのは 「自動で戻せなかったものがあります」という通知で、残っている ~/repos のディレクトリと ~/.local/bin のプログラム、 それに、どの起動ももうやり直さない入れ直し(pip:greenlet==3.0.3 や npm:cowsay@1.6.0 など)が並びます。変更後の確認が最後まで終わらなかったときは、実行するコマンドも出ます。通知の元は af-arch-repair が書くファイル ~/.local/share/agent-fleet/arch-residue で、いま残っているものが入り、 なくなれば消えます。同じ内容の通知は、2 度は出ません。

失敗した入れ直しが通知に出るのは、自動のやり直しを使い切ったときだけです。次の起動で直る失敗は、通知に出ません。 やり直しが残っているあいだは、自分で入れたツールが何回かの起動のあいだ壊れたままのことがあります。すぐにやり直すには、 ターミナルで af-arch-repair <was> <now> を実行し、WARN: の行を読んでください。

入れ直しに失敗すると、その一覧が ~/.local/share/agent-fleet(arch-repair-npm、arch-repair-pip、arch-repair-uv)に 残ります。一覧が残っているあいだは、次の起動で af-arch-repair がもう一度実行されます。その起動でアーキテクチャが 変わっていなくても同じです。

項目 ふるまい
一覧に残るもの 入れ直しのコマンドがまだ成功で終わっていないパッケージだけです。1 つずつ入れ直し、そのパッケージのコマンドが成功したときだけ一覧を抜けるので、失敗し続けるものがあっても、ほかのものは巻き込みません。途中で止まった実行でも、終わっていないパッケージは一覧に残ります
やり直すもの 失敗した種類(pip、uv、npm)だけです。一覧にあるパッケージは、ディスクの状態に関係なく、すべてもう一度入れます。失敗した入れ直しが、入っているように見えるファイルを残すことがあるためです。pip と uv はもう一度調べもするので、そのあとで壊れたものも加わります。バージョンは、パッケージが入っていればいま入っているバージョンで、途中で止まった更新で 2 つのバージョンが並んでいるときは高いほうです。そのあとで自分でバージョンを上げたパッケージは、そのバージョンのまま、ネイティブの部分だけが作り直されます。一覧のバージョンを使うのは、パッケージがなくなっているときだけです
回数 アーキテクチャが変わった起動のあと、やり直しの起動は最大 3 回までです。入れられないパッケージが、毎回の起動を遅くし続けないためです。やり直しは始めたときに数えるので、入れ直しの途中で止まった起動も数えます。アーキテクチャが変わった起動が af-arch-repair の終わる前に止まったときは、次の起動ですべてやり直し、このやり直しも同じ 3 回に数えます
3 回目のやり直しのあと 次の起動は何も入れません。残ったものを通知に出してから、あきらめたことを記録し、それ以降の起動はそれらのために af-arch-repair を実行しません。アーキテクチャが変わったあとの確認が最後まで終わらなかったときは、一覧が足りないことがあるので、実行するコマンド af-arch-repair <was> <now> も通知に出します。一覧は残ります。WARN: の行のコマンドか、af-arch-repair <was> <now> を実行してください
手で実行したとき 回数に関係なく、壊れているものをすべてやり直します。成功すると、一覧と、通知に出していた残りものが消えます
その起動で Python のメジャーバージョンが変わったとき 待っている pip の失敗は、やり直さずに捨てます。新しい Python には同じバージョンがないことがあるためです
変数 効果
AF_REPAIR_PY=0 pip の入れ直しを飛ばします。同じ起動で Python のメジャーバージョンも変わったときに、ワークスペースが設定します。新しい Python には同じバージョンのパッケージがないことがあるためです
AF_ARCH_REPAIR_AUTO ワークスペースの起動が設定します。change はやり直しの回数を 0 に戻します。retry はやり直しを 1 回数えて、前に失敗したものだけを入れ直します。rerun は止まった変更の起動をやり直し、やり直しを 1 回数えます。上限を超えると、retry と rerun は何も入れず、知らせるだけです。自分では設定しないでください
値 意味
0 実行した。入れ直しに失敗したときも含みます(出力に出ます)。--due では、一覧が残っていて、あきらめたことがまだ記録されていない
1 --due のときだけ。待っているものがないか、ワークスペースがもうあきらめた
2 <now> がない