fleet-maintenance

Fleet Maintenance

曖昧なローカル作業を保護しながら、Peter の Mac をメンテナンスします。アクティブなセッション中のパッケージ更新は明示的に許可されており、アップグレード対象のソフトウェアが中断される可能性があります。インベントリ／SSH には $remote-mac を、Xcode に関するすべての作業には $xcode-sync を使用します。

目標の状態

• 希望するソフトウェアとローカルアカウントのエスクロー参照については、~/Projects/manager/fleet/inventory.json を参照してください。そのスキーマを変更したり、パッケージを採用したりする前に、references/fleet-schema.md を参照してください。
• Peter が明示的にモデルを変更しない限り、プロファイルは正確に 2 つに保ってください:
  • full: 完全な開発、コミュニケーション、メディア、エージェント用ツールセットを備えた、日常使いの Mac。
  • worker: 主に Codex、Claude、OpenClaw ノード、およびそれを支えるエージェント基盤を実行する、軽量なリモート Mac。
• プロファイルポリシーは minimum として扱ってください。必須エントリをインストールし、追加分は削除せずに報告してください。観測されたソフトウェアを無言で希望状態に変えてはいけません。
• トポロジー、SSH ルーティング、引き継ぎ状況は ~/Projects/manager/computers.yaml に保持してください。このスキル内で稼働中のトポロジーを重複させないでください。
• パスワード、リカバリーキー、秘密鍵は 1Password に保持してください。インベントリには不透明なアイテム ID のみを保存します。op コマンドの前に必ず $one-password を呼び出してください。パッケージ保守中に pending 参照があってもエラーではありません。
• 両方のプロファイルで、ssh_mesh で指定されたクラシックな OpenSSH メッシュを必須としてください。正規のピアリストと稼働中の証明は、manager の fleet セットアップドキュメントが所有します。対称的な Tailscale TCP 22 許可と、ホストごとの authorized_keys を使用してください。macOS の GUI Tailscale クライアントは Tailscale SSH サーバーとして動作できません。公開鍵のみを配布し、秘密鍵はホストローカルに保ち、BatchMode=yes と有限のタイムアウトで双方向を検証し、オフラインまたはプロバイダーによってブロックされた方向は pending のままにしてください。
• すべての fleet Mac で、安定した 1Password CLI の整合性ベースラインを必須としてください。そのホストがインベントリ内で文書化された requirement_exceptions セキュリティ境界を持たない限り、ファイルベースのサービスアカウントプロファイルブロックを必須としてください。対象となるホストは scripts/op-profile-audit.sh で監査し、トークン免除ホストは scripts/op-profile-audit.sh --cli-only で監査してください。修復は $one-password がロードされ、mode-0600 のトークンファイルがプロビジョニングされた後にのみ行ってください。トークンをインベントリに出力したり保存したりしないでください。
• すべての fleet Mac で、エージェントスキルのミラーを必須としてください。scripts/agent-skill-links-audit.sh で監査してください。その --repair は、両方の正規リポジトリが存在する場合にのみ、広範な正規同期を呼び出します。同期は実ディレクトリと実ファイルを保持し、同一ディレクトリ内のローカル所有権を受け入れ、それ以外の実宛先の競合を報告します。reason=nested-self-link の場合は、レビュー済みの同期オーナーを絶対パスで直接呼び出し、--repair-nested-self-links --dry-run -- NAME... を指定し、その後 --dry-run を外して検証済みのネストされたリーフのみを削除してください。実際の Claude スキルディレクトリと Codex バックリンクは保持してください。この限定的なループチェックは、網羅的なグラフバリデータではありません。スコープについては references/fleet-schema.md を、fleet セットアップについては ~/Projects/manager/docs/fleet-setup.md を参照してください。
• すべての fleet Mac で、共有グローバル Git ignore を必須としてください。scripts/global-gitignore-audit.sh で監査してください。--repair は ~/.config/git/ignore を作成し、無関係なエントリを保持し、インベントリの macOS メタデータパターンを追加し、core.excludesFile をそれに向けます。すでに設定済みの代替 excludes ファイルは手動レビューが必要であり、既存のルールが破棄されることは決してありません。
• Claude Code と Claude Desktop のコーディングセッションでは、AI 帰属表示を省略することを必須としてください。~/.claude/settings.json を scripts/claude-attribution-audit.sh で監査してください。--repair は無関係な設定を保持しつつ、コミットトレーラー、プルリクエストフッター、リモートセッションリンクを無効化します。
• 両方のプロファイルで公式の Codex および Claude Code CLI を必須としてください。パッケージの所有権はプロファイルの codex および claude-code Homebrew cask から取得されます。別個の claude cask は Claude Desktop であり、CLI 要件を満たしません。バージョンと非対話型認証は scripts/agent-cli-audit.sh で監査してください。--live は、制限付きでツールを使用しない非永続的なモデルターンに使用してください。通常の Claude OAuth 認証情報を Mac 間でコピーしないでください。各ホストで $anthropic を通じて個別に更新し、ロックされた Keychain、アカウント選択、またはオフラインのケースは pending のままにしてください。
• 両方のプロファイルで、GitHub キャッシュとして Octopool を requirements.github_cache: "octopool" で必須としてください。パッケージの存在だけでは不十分です。scripts/octopool-audit.sh は、非対話型およびログイン zsh が Octopool シムを通じて gh を解決すること、クライアントログインが完全な ID メタデータを持つこと、設定されたすべてのプール ID が正常であることを証明しなければなりません。--repair を使用して、既存の認証済み安定パス GitHub CLI を通じてログインし、zsh シムをインストールし、必要に応じて macOS のログイン PATH 順序を修復してください。パッケージをインストールしたり、認証情報を出力したりすることは決してありません。 決定論的なプロファイルツールを使用してください。

node skills/fleet-maintenance/scripts/fleet-profile.mjs collect
node skills/fleet-maintenance/scripts/fleet-profile.mjs \
  plan --fleet ~/Projects/manager/fleet/inventory.json \
  --host mac-studio-sf --snapshot /path/to/mac-studio-sf.json
node skills/fleet-maintenance/scripts/fleet-profile.mjs \
  diff --source /path/to/macbook-pro.json --target /path/to/mac-studio-sf.json
node skills/fleet-maintenance/scripts/fleet-profile.mjs \
  brewfile --fleet ~/Projects/manager/fleet/inventory.json --host mac-studio-sf
node skills/fleet-maintenance/scripts/fleet-profile.mjs \
  validate --fleet ~/Projects/manager/fleet/inventory.json
skills/fleet-maintenance/scripts/agent-skill-links-audit.sh
skills/fleet-maintenance/scripts/global-gitignore-audit.sh --host mac-studio-sf
skills/fleet-maintenance/scripts/claude-attribution-audit.sh
skills/fleet-maintenance/scripts/agent-cli-audit.sh
skills/fleet-maintenance/scripts/octopool-audit.sh
skills/fleet-maintenance/scripts/op-profile-audit.sh

コレクターのスナップショットは観測された証拠であり、設定ではありません。確認済みのスナップショットは ~/Projects/manager/fleet/snapshots/<host-id>.json に保存します。diff はソース側にのみ存在する候補を報告します。どれを full に含めるかは Peter が選びます。

安全性に関する契約

• ~/Projects/manager/computers.yaml を読み込み、Tailscale のライブ状態を使用して、ハードウェア UUID でホストの重複を除外します。引き渡し済みのマシンと不明なマシンは除外します。
• ホストの監査は並行して行い、変更は一度に1台のホストに対して行います。リポジトリまたは Xcode に変更を加える直前に、エージェントの稼働状況を再確認します。
• ユーザープロセスの cwd がリポジトリ内にある場合、または Git ロックがある場合は、そのリポジトリをスキップします。最近のファイルは監査の判断材料であり、作業を妨げる要因ではありません。以下の競合のない早送り手順を通じてのみ、変更のあるワークツリーを許可します。
• エージェントやサービスの稼働中でも、Homebrew およびグローバル npm パッケージの更新は許可されています。これにより、メモリー上の古いコードと置き換えられたファイルが混在し、後続のインポートや子プロセスが壊れたり、Homebrew が Cask の GUI アプリを終了して再度開いたりする可能性があります。このようなパッケージ更新のリスクは許容しますが、サービスを手動で終了または再起動してはいけません。正常性を確認し、中断や保留中の再起動があれば報告します。
• 定期メンテナンス中に、リセット、クリーン、スタッシュ、リベース、ブランチ切り替え、ローカル作業の削除、プッシュ、macOS アップデートのインストール、再起動を行ってはいけません。
• パッケージ更新の前に、役割上重要なサービスのスナップショットを取得します。明示的な許可がない限り、OpenClaw ゲートウェイやその他のサービスを再起動してはいけません。実行後は、それらを管理するスキルを使用して確認します。
• ホストごとに操作ログを記録します。到達不能なホストは保留中とし、最新の状態として扱ってはいけません。

実行順序

1. ホストの full または worker プロファイルを特定し、観測されたインベントリーを収集して、パッケージ所有権の事前確認を実行します。
2. 既存の Git／ツールチェーンを使用して、対象となるリポジトリを同期します。
3. エージェントやサービスが稼働中かどうかにかかわらず、対象となる到達可能なすべてのホストで Homebrew とグローバル npm パッケージを更新します。
4. 各ホストの macOS 安定版／ベータ版トラックを確認します。
5. $xcode-sync を通じて Xcode を同期します。
6. 今回の実行で明示的に要求された場合に限り、ゴミ箱を空にします。承認済みのパッケージクリーンアップを実行します。
7. ディスク、ツール、パッケージ所有権、リポジトリ、メモリー、役割上重要なサービスを再監査します。

事前確認

ホスト名、ハードウェア UUID、macOS、アーキテクチャ、稼働時間、Tailscale の状態、選択中の Xcode、空きバイト数／割合、ゴミ箱のサイズ、Homebrew のプレフィックス／バージョン、Node／npm のバージョン、実行中の Brew サービス、稼働中のコーディングエージェントプロセス、常駐メモリーの外れ値を記録します。

node skills/fleet-maintenance/scripts/fleet-profile.mjs collect
skills/fleet-maintenance/scripts/host-health-audit.sh 30
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'node --input-type=module - collect' \
  < skills/fleet-maintenance/scripts/fleet-profile.mjs
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'bash -s -- 30' \
  < skills/fleet-maintenance/scripts/host-health-audit.sh

常駐メモリーが 30 GiB を超えるプロセスはすべて報告します。仮想サイズだけでは警告せず、関連プロセスのメモリーを合算せず、プロセスを自動終了しないでください。PID、常駐メモリーの GiB 数、ユーザー、実行ファイル、役割、および2回目のサンプルでもメモリーがしきい値を超えているかを記録します。

絶対容量と相対容量の両方を使って、起動ディスクの空き容量を分類します。

• 正常：100 GiB 以上かつ空き容量が15％以上
• 警告：50～100 GiB、または空き容量が10～15％
• 重大：50 GiB 未満、または空き容量が10％未満

空き容量が警告または重大の状態では、Xcode の容量拡張を開始してはいけません。明示的な承認なしに、ゴミ箱、不要になったパッケージマネージャーの成果物、または $xcode-sync が管理する Xcode のパス以外を削除してはいけません。

リポジトリの同期

各ホストで読み取り専用の候補監査を実行します。

skills/fleet-maintenance/scripts/repo-sync-audit.sh ~/Projects 3
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'bash -s -- "$HOME/Projects" 3' \
  < skills/fleet-maintenance/scripts/repo-sync-audit.sh

バンドルされたアップデーターで監査済みのポリシーを適用します。安全性を再確認し、対話なしでフェッチし、クリーンまたは競合のない変更済みワークツリーをファストフォワードし、拒否されたリポジトリを隔離します。

skills/fleet-maintenance/scripts/repo-sync-update.sh ~/Projects 3
ssh -o RequestTTY=no -o RemoteCommand=none HOST \
  '"$HOME/Projects/agent-scripts/skills/fleet-maintenance/scripts/repo-sync-update.sh" "$HOME/Projects" 3'

candidate とマークされた行のみを処理します。変更を加える直前に、ブランチ、上流、Git のロック、アクティブなプロセスの cwd を再確認してから、次を実行します。

git -C "$repo" fetch --prune
git -C "$repo" rev-list --left-right --count HEAD...@{upstream}

フェッチは対話なしで実行し、それぞれに制限時間を設けます（例：5 分）。タイムアウト、認証失敗、またはネットワーク障害が発生した場合は、そのフェッチを終了し、リポジトリを保留として記録して続行します。古い、またはプライベートなミラーによってホスト全体の処理が止まること、リモートを書き換えること、フリートの保守中に認証情報の入力を促すことは、絶対に避けてください。

カウントは ahead behind の順に解釈します。

• 0 0：最新です。操作は不要です。
• 0 N：git log --oneline HEAD..@{upstream} と git diff --stat HEAD..@{upstream} を確認します。HEAD とワークツリーの状態を記録します。git merge --ff-only --no-autostash --no-overwrite-ignore @{upstream} を実行します。クリーンなワークツリーは更新されるはずです。変更済みのワークツリーは、Git がすべてのローカル変更を重複なく保持できる場合に限り更新できます。Git に拒否された場合は、修復すべきエラーではなく skip-local-overlap とします。成功後は、未マージのエントリがないこと、期待する上流コミットが HEAD にあること、変更前のローカル変更がすべて保持されていることを確認します。拒否された場合は、HEAD が変更されていないこと、未マージのエントリがないこと、ワークツリーの状態が変わっていないことを確認します。
• N 0 または N M：ローカルコミットの件名と作成者、および git diff --stat @{upstream}...HEAD を確認し、意図として考えられる内容を説明してエスカレーションします。プッシュや書き換えは絶対に行わないでください。
• detached／上流なし／フェッチ失敗：リモート、ブランチ、最近のコミット、ワークツリーの状態を把握し、判断に必要な最小限の情報を添えてエスカレーションします。

古いローカルチェックアウトが、同じホスト上の別のチェックアウトと一致すべきだと推測しないでください。各チェックアウトはユーザーが管理しています。

競合の解決に pull や merge を使わないでください。--autostash を渡す、スタッシュを作成する、変更を破棄する、ファイルをステージすることは絶対に避けてください。ファストフォワードできない場合、チェックアウトによる上書きの警告が出た場合、マージ競合が発生した場合、または安全性のスナップショットが変化した場合は、そのリポジトリの処理を停止し、フリート全体の処理は続行してください。

Homebrew

Homebrew が存在しない場合に限り、スキップします。実行中のエージェント／サービスは、パッケージ変更を妨げません。

まずホストの解決済みプロファイルを一時的な Brewfile に出力し、brew bundle check --verbose --file FILE を実行します。不足している項目を確認します。brew bundle install --file FILE では、宣言済みの依存関係をインストールまたはアップグレードできます。brew bundle cleanup --force は絶対に実行しないでください。既定の minimum ポリシーでは、余分な項目は許容されます。エントリの削除は、明示的に承認されたプルーン操作でのみ行います。

Homebrew 6 では、サードパーティのフォーミュラが信頼されるまで、その使用が拒否される場合があります。その場合は、各フォーミュラが解決済みのフリートプロファイルにすでに宣言されていることを確認し、その正確なフォーミュラ名に対して brew trust --formula ... で信頼を付与します。タップ全体や、リモートタップからのみ見つかったフォーミュラを信頼しないでください。brew trust --json v1 で信頼リストを記録し、同じ生成済み Brewfile で処理を再開します。

brew update
brew outdated --json=v2
brew upgrade
brew services list
brew doctor

brew doctor の結果は参考情報として扱い、提案を無条件に適用しないでください。サービスの状態を実行前後で比較します。検証に成功した後は brew cleanup --prune=30 を使用します。より積極的なクリーンアップは、ディスク容量が逼迫しており、明示的な承認がある場合に限り使用します。

アップグレードによって、アクティブなエージェント／サービスが使用している Node、Git、Codex、またはその他の実行ファイルが置き換えられる場合、後続のインポートや子プロセスが新しいファイルを参照する可能性を受け入れ、そのリスクを報告します。cask の GUI アプリについては、セッションが終了する可能性も含め、Homebrew による制御された終了／再起動を許可します。サービスの手動再起動、タップの変更、パッケージの自動アンインストールは行わないでください。

パッケージの所有権

パッケージを変更する前と後に、scripts/host-health-audit.sh を実行してください。その所有権候補に加え、重複する launchd ラベル／リスナー、実行可能ファイルのバージョン不一致、Homebrew formulae／casks、グローバル npm、スタンドアロンアプリ、アプリにバンドルされた CLI 間の競合を調査してください。

各候補について、実行可能ファイルの実際のパス、パッケージのレシート、サービス定義、リスナー、実行中のプロセス、依存先、バージョン、想定されるホストの役割を確認してください。正規の所有者は1つにすることを推奨します。代替が正常に動作し、インストール済みパッケージがそれに依存しておらず、現在の依頼が修正を許可している場合に限り、重複する所有者を無効化またはアンインストールしてください。名前が同じというだけで競合と判断してはいけません。formula とアプリの組み合わせが意図的な場合もあります。

グローバル npm パッケージ

「npm を更新する」とは、プロジェクトの依存関係ではなく、レジストリ経由でインストールされたトップレベルのグローバルパッケージを指します。ここではリポジトリの package.json やロックファイルを変更してはいけません。

1. node --version、npm --version、npm prefix -g、npm ls -g --depth=0 --json の結果を記録します。
2. npm outdated -g --depth=0 --json を実行します。終了コードがゼロ以外でも、更新が存在する場合があります。
3. レジストリ上の各パッケージを name@latest に更新します。リンク、file、Git、バンドルされたパッケージ、および判別が曖昧なパッケージはスキップし、その旨を報告してください。
4. npm 自体の更新は、その所有者に任せます。Homebrew は Homebrew の Node/npm を更新します。npm install -g npm@latest を使用するのは、npm が自己管理型のインストールである場合に限ります。更新後の npm --version を確認してください。
5. インベントリを再実行し、更新したグローバル CLI のスモークテストを行います。プライベートパッケージでレジストリ認証が実際に必要な場合に限り $npm と $one-password を使用してください。npm の認証情報を決して公開してはいけません。

現在、稼働中のコーディングエージェントやサービスを支えている場合でも、グローバルパッケージのメジャーアップデートは実施対象です。古いファイルと新しいファイルが混在するリスクを受け入れてください。プロセスを再起動してはいけません。新たにインストールした CLI を個別にスモークテストし、失敗や再起動待ちの状態を報告してください。

macOS のトラック

sw_vers の製品／ビルド情報と、現在のベータシード登録状態を記録します。最新の安定版ビルドと現在のベータ版ビルドを、Apple の最新の公式情報から確認してください。バージョンをハードコードしたり、バージョン番号だけからトラックを推測したりしてはいけません。softwareupdate --list を使用して、設定済みのトラックでホストに実際に提示されている内容を確認してください。

各 Mac を、最新、アップデートあり、トラックが曖昧、サポート対象外、または到達不能に分類します。設定済みの安定版／ベータ版トラックを維持してください。通常のメンテナンスでは、トラックの切り替え、macOS アップデートのインストール、再起動は行いません。アクティブなエージェント／サービスがないことと、バックアップ／ディスクの状態が十分であることを確認してから、適切なメンテナンス時間を依頼し、対象のアップデートを準備してください。

Xcode

$xcode-sync を呼び出してください。インストールのロジックを重複させてはいけません。現在の安定版／ベータ版／RC のバージョンは、ハードコードせず、最新の公式情報から確認してください。そこで定義されている正規の安定版／プレリリース版スロットと旧メジャーバージョンの保持ポリシーを維持しつつ、各ホストで選択されている安定版またはプレリリース版のトラックを保ってください。

製品ビルド、署名、初回起動の状態、選択状況、ホストとの互換性、空き容量を確認してください。サポート対象外の Mac と到達不能な Mac は分けて報告してください。

Simulator の整理は、任意のディスククリーンアップではなく、フリートで必須の不変条件です。到達可能なすべての Mac で $xcode-sync の Simulator 整理監査を実行してください。Xcode／simctl がないホストは not-applicable です。Xcode があるホストは、Apple が古いまたは使用不能なランタイムイメージを報告せず、利用できないランタイムに紐づくデバイスもない場合に限り、最新とみなされます。修復するのは、Xcode の作業が進行中でないことを確認した後に限ります。正規の操作は Simulator デバイスが起動中の場合に実行を拒否します。

ゴミ箱とディスク

実行のたびにゴミ箱の使用量を測定してください。現在の依頼でゴミ箱を空にすることが明示されていない限り、読み取り専用のままにしてください。許可がある場合は、パスを解決して確認したうえで、現在のユーザーのホームボリュームにあるゴミ箱のみを空にしてください。

trash="$HOME/.Trash"
home_real=$(cd "$HOME" && pwd -P)
trash_real=$(cd "$trash" && pwd -P)
if [[ "$trash_real" != "$home_real/.Trash" ]]; then
  printf 'refusing unexpected Trash path: %s\n' "$trash_real" >&2
  exit 2
fi
find "$trash_real" -mindepth 1 -maxdepth 1 -exec rm -rf {} +

他のユーザーのゴミ箱や外部ボリューム上のゴミ箱は決して空にしてはいけません。その後、ディスク容量を再確認してください。説明できない増加があった場合は、キャッシュを広範囲に削除するのではなく、エスカレーションしてください。

基本のヘルスチェック

これらの読み取り専用チェックをレポートに含めてください。変更を加える場合は、別途権限が必要です。

• 利用可能な macOS／セキュリティアップデートと、再起動が推奨されているかどうか
• mas がインストールされている場合は、mas outdated による Mac App Store アプリケーションの更新状況
• 設定されている場合は、最後に成功した Time Machine バックアップ
• SMART／ストレージの警告と、diskutil で確認できる APFS ボリュームの健全性を示す情報
• 稼働時間、時刻の同期状態、ノートブックのバッテリーの健全性／充放電回数
• Tailscale の到達性／バージョンの差異
• 異常のある Brew サービスと、役割別の LaunchAgents／デーモン
• FileVault、ファイアウォール、Gatekeeper、SIP の状態の差異
• Developer ID 証明書と重要な SSH 認証情報の有効期限。秘密の値は決して含めないでください

任意の便利なメンテナンス項目：古いパッケージキャッシュ／ログ、放置されたコンテナ／VM、CoreSimulator が管理していない古いデバイスサポートファイル、孤立した起動エージェント、大容量のダウンロード項目。まず監査し、範囲を明示して許可された場合にのみ削除してください。

完了

次の項目を含むホスト一覧を返してください：到達性、エージェント CLI のインストール／認証／ライブテストの状態、Octopool の shim／ログイン／プール健全性の状態、エージェントスキルのリンク状態、グローバル Git 無視設定の状態、実施中／保留中の理由、ディスク使用量の実施前／実施後、ゴミ箱から回収した容量、Brew／npm の変更、pull 済み／最新／スキップ／エスカレーション対象のリポジトリ、Xcode の安定版／プレリリース版ビルドと選択中のトラック、バックアップ／アップデート／サービスに関する警告、残っているユーザーの判断事項。