maintaining-macos-health

macOS の健全性を維持する

macOS のディスクおよびメモリの危機に対する復旧・予防の手引きです。Apple Silicon で、ディスク使用率が 90 % を超え、vm_compressor セグメントが 100 % に達したことが原因のウォッチドッグタイムアウトによるカーネルパニックを実際に検証済みです。同じ手引きは、定期的なクリーンアップや新しいマシンでの初回セットアップにも利用できます。

目次

• 使用する場面
• スキルの構成
• 基本的な考え方
• 標準的なワークフロー
  • 初回の対話型利用：ディスク対応は任意
  • A. 「今すぐ空き容量を確保する」（インシデント対応）
  • B. 「アラートを設定する」（新しいマシンまたは初回）
  • C. アラート機能が停止した／通知音が鳴り続ける
  • D. 「アプリをきれいにアンインストールする」
• 安全ルール（必須）
• 把握しているドメイン固有の注意点
• 成果の尺度

使用する場面

次のいずれかに該当する場合に使用します。

• ディスクの空き容量が 20 % 未満、または空き容量がないというユーザーからの申し出がある
• ウォッチドッグタイムアウト／カーネルパニック／「no checkins from watchdogd」
• vm-compressor-space-shortage を伴う新しい JetsamEvent-*.ips
• 「Mac の動作が遅い」、スワップが 6 GB を超えている、メモリプレッシャーが継続的に「重大」
• プロセスがコアを継続的に占有している、またはマシン全体が CPU を使い切った状態のままになっている
• ユーザーが監視／アラート機能を一から設定したい
• 新しい Mac への移行 → 同じアラート機能を復元する
• 一般的な「Mac をクリーンアップしたい」／「ストレージを確認したい」／「空き容量を確保したい」という依頼

スキルの構成

ファイル	用途
references/triage.md	最初の5分間 — どのシグナルが発生したか、どのクリーンアップティアから開始するか
references/cleanup-tiers.md	ティア別クリーンアップ手順（10ティア、リスクゼロから要相談まで）、安全にコピー＆ペーストできるシェルブロック
references/never-touch.md	sudo を使っても削除してはならないカテゴリ（Mole 由来のブラックリスト＋インシデント由来の追加項目）
references/mole-techniques.md	Mole から取り入れる手法：mo purge のマーカー→対象マップ、安全なパスの検証、経過時間のしきい値
references/alerting.md	アラート設計の全容：ディスク／メモリ／Jetsam の重大なトリガー、継続的な CPU 異常の検知、インシデントのライフサイクル、ヒステリシス、通知方法の選択、インストール／復元コマンド
references/optional-disk-responses.md	初回利用時の案内、2つの独立したオプトイン機能のインストールと運用：空き容量が2%未満の場合の緊急 Mole キャッシュクリーンアップ、および5%以下の場合の正確なセッション継続機能付き Codex クリーンアップ計画／ページ。
assets/mac-health-disk, assets/disk_*.py	同意を前提とするディスクコントローラー、決定論的なインベントリ、制限付き Codex ランナー、認証付きローカル選択／確認ページ。両モードともデフォルトでは無効です。
assets/mole-exact-file.sh, assets/mole-core-1.39.0.json	Mole との互換性を固定した、ファイル単位のアダプター。汎用的な mo clean、sudo、エージェントによるシェルコマンド実行はありません。
assets/space-scan/, assets/build-space-scan.sh	ディレクトリを明示的に除外する読み取り専用の一括メタデータスキャナーと、簡潔な全フォルダーツリー。手動でインベントリを作成する場合は references/storage-report.md を参照してください
assets/render-storage-report.py, assets/storage-tree.js	スキャナーの出力をレポートに追加し、フォルダーを遅延展開して最大サイズのファイルを表示します
assets/mac-health-check	本番環境で使用できる bash スクリプト（約250行、bash 3.2 対応）
assets/mac-health-action	読み取り専用の Codex／Claude 調査と、明示的に確認されたプロセスの正常な停止を実行するバックグラウンドアクションディスパッチャー
assets/com.local.mac-health-check.plist	StartCalendarInterval を使用する LaunchAgent plist（ノート PC では StartInterval が機能しません）
assets/config.sh	安全なしきい値を設定したデフォルト構成
assets/render-cleanup-plan.py	対話式の HTML クリーンアップ計画 UI。スキャン結果の JSON からカテゴリ別のチェックボックスを生成し、127.0.0.1:18347 で配信してブラウザーを開き、ユーザーの選択を待って /tmp/cleanup-selection-<ts>.json に書き込みます。ワークフロー A で使用します。
assets/apply-cleanup-selection.py	クリーンアップの選択を適用するために承認された唯一の方法です。選択 JSON から selected_items を読み取り、各項目の command フィールドを実行します。保護対象の上書きチェック、パス検証、Mole 互換の操作ログ記録を徹底します。ユーザーが選んだ項目と削除される項目に食い違いが生じないようにします。--dry-run に対応しています。

作業を行う前に、該当するリファレンスを読んでください。これらのファイルの内容を記憶だけに頼って作業してはいけません。実際のインシデントに合わせて詳細が調整されており、小さな変更でも安全性が損なわれます。

基本的な考え方

1. 受動的に監視する — Stats メニューバーアプリ（brew install --cask stats）を使えば、問題が深刻化してからではなく、発生し始めた段階で確認できます。
2. 積極的にアラートし、静かに診断する — ディスク、メモリ、Jetsam、システム全体の CPU 飽和は重大な問題です。単一プロセスの CPU 使用率が高い場合は、長時間継続した後にのみ、通知を伴わない注意情報として扱います。通常のサンプルはログに記録されます。
3. クリーンアップティア — リスクゼロ（キャッシュ、孤立データ）から始め、必要な場合にのみプロジェクト成果物や sudo が必要なカテゴリへ進みます。主要なツールとして適切なのは Mole の mo purge と mo clean です。
4. Mole を安全性の最低基準とする — シェルコマンドを手動で実行する場合も、Mole のパス検証ルールに従ってください。特定の許可済みサブパスを除き、/System、/bin、/usr、/etc、/var/db 内を削除してはいけません。bin/ は .NET の場合のみ、vendor/ は PHP の場合のみ対象とし、AI／パスワード／VPN／キーチェーンのバンドル ID を保護してください。

標準ワークフロー

初回の対話的な利用：ディスク応答のオプション

Macで初めて実運用として対話的に利用する場合（このスキルにアップグレードした既存のインストールを含む）は、references/optional-disk-responses.mdを読み、ユーザーの言語で2つの選択肢を個別に提示してください。通常のセットアップより先に行います。インシデント対応中は、緊急のトリアージを遅らせないでください。このスキルの編集またはレビューの依頼は、開発マシンでこのスキルを有効にすることへの同意ではありません。バックグラウンドでの呼び出しでは、登録を促すことは決して避けてください。

• 緊急クリーンアップ、空き容量が2%未満： インシデント発生時に追加の確認をせず、明示的に承認された再生成可能なキャッシュに限り、範囲を限定したMoleのクリーンアップを実行する許可です。同意を受け付ける前に、対象となるプロファイル、取り消せない削除、キャッシュの再構築やダウンロードにかかる可能性のあるコスト、対象外の項目を正確に説明してください。これは、一般的なmo clean、プロジェクトの一括削除、ゴミ箱を空にする操作、sudo、プロセスの終了を許可するものではありません。
• エージェントによるクリーンアップ計画、空き容量が5%以下： 選択したエージェントを自動的に起動し、秘密情報を含まないストレージのメタデータを調べ、デフォルトのブラウザーでローカルの選択ページを開く許可です。プロバイダーの利用状況とコスト、およびMacから外部に送信されるメタデータを説明してください。エージェントは削除を提案できますが、実行はできません。Submitは選択を確定するものであり、適用には引き続き別途確認が必要です。

各選択肢について、明示的な回答を個別に記録してください。無回答、「監視を設定する」といった一般的な回答、または一方の選択肢への承認は、もう一方への許可にはなりません。辞退された選択は、セッションやアップグレードをまたいで保持してください。再度確認するのは、ユーザーから依頼があった場合、新しいマシンの場合、または同意の範囲に重大な変更があった場合に限ります。どちらの選択肢にも同意がなくても、既存の監視は継続されます。

実装範囲： 同梱のコントローラーは、固定バージョンのMole 1.39.0アダプターと、ワークフローAと同じクリーンアップ計画UIを使用する制限付きCodex CLIセッションに対応しています。緊急クリーンアップの対象は、古いHomebrewパッケージのダウンロードファイルとnpmコンテンツキャッシュのファイルに限られます。自動計画では、ワークフローAの固定された読み取り専用の一括メタデータスキャン、Moleのclean/purgeプレビュー、Dockerのインベントリ、Downloadsの監査を実行します。自動実行機能が削除できるのは、コントローラーが再生成可能と確認したキャッシュファイルのみです。ストレージマップとユーザーデータの可能性がある項目は表示されますが無効になっており、後で対話型のワークフローAセッションを実行する必要があります。参照ドキュメントを読み、これらの制限を開示し、ローカル環境との互換性を確認したうえで、mac-health-disk configureを使って承認を記録してください。インストールだけでいずれかのモードが有効になることはありません。機能開発の依頼から同意を推定してはなりません。

A. 「今すぐ空き容量を確保」（インシデント対応）

1. トリアージ — references/triage.md を読み、どのシグナルが発生したか、緊急度はどの程度かを特定します。
2. ベースラインを記録 — df -h /System/Volumes/Data を実行し、空き容量を GB 単位で記録します。
3. 削除はまだせず、すべてのスキャンを実行 — 大容量のローカルディスクインベントリには、references/storage-report.md に記載されている同梱の一括スキャナーと完全なフォルダーツリーを使用します。使用前にスキャナーをビルドし、ビルドまたはスキャンの失敗は明示的に報告します。別のスキャン方法で黙って代用しないでください。また、mo clean --dry-run、mo purge --dry-run --debug、docker system df -v、~/Downloads の監査も実行します。すべて記録してください。削除を行うのは、ユーザーが UI で選択した後に限ります。
4. JSON の構築前に不明な項目を解決 — 用途を一文で説明できない 500 MB 超の候補項目（見慣れないアプリ、見慣れないバンドル ID、見慣れないドットフォルダー、ベンダー固有のキャッシュ、ML モデルの重み、VM イメージなど）は、すべて先に調査します。まず references/never-touch.md に既知の項目がないか確認し、次に web-searcher サブエージェントに「macOS で <path or bundle id> とは何か、2026 年時点で安全に削除できるか」を手早く調べるよう委任します。回答を待ってから、項目の description に具体的な説明（ユーザーの言語で 1〜3 文）を記載します。何であるか、誰が作成したか、どの機能が使用するか、削除すると何が壊れるか、自動的に再作成されるかを記載してください。「unknown」や「ML data」のような曖昧な仮置きを含むレポートは絶対に表示しないでください。それでは UI の意味がありません。ウェブ検索の結果が never-touch.md の記載と矛盾する場合は、より新しいウェブ検索の回答を優先し、参照ファイルの更新を提案します。
5. データ JSON を構築 — すべての候補を構造化された item にします（id、label、path、size_bytes、age_days、kind、command、必須の description、任意の protected と warning）。/tmp/cleanup-data-<ts>.json に書き込みます。スキーマは assets/render-cleanup-plan.py の docstring を参照してください。 レポートの末尾に読み取り専用のディスクインベントリを追加します。折りたたみ可能なフォルダーサイズの階層に続けて、割り当て済みサイズの降順で最大ファイルを記載します。storage_scan の入力、対象範囲ラベル、サイズの意味については references/storage-report.md に従います。これらの行は情報提供のみを目的とし、自動的に削除候補にしてはいけません。
6. クリーンアップ UI をレンダリングして開く:

   python3 .../assets/render-cleanup-plan.py /tmp/cleanup-data-<ts>.json
   

   スクリプトは 127.0.0.1:18347 で 1 回限りの HTTP サーバーを起動し、ユーザーの既定のブラウザーでページを開いて、ユーザーが Submit または Cancel をクリックするまで処理をブロックします。Submit 時には /tmp/cleanup-selection-<ts>.json に書き込み、そのパスを標準出力に表示します。ユーザーに声をかけて、「браузер открыт — поставь галочки, нажми Submit, потом пингани меня」と伝えます。その後、停止して待ちます。
7. ユーザーから連絡があった後 — 選択 JSON を読み込み、ユーザーの選択内容（カテゴリ、項目一覧、合計 GB、⚠ で示した保護対象の上書き項目）をチャットで提示し、削除前に明確な確認を一度求めます。「go」と言われるまで何も実行しないでください。
8. ヘルパースクリプトで適用 — 手書きの rm は絶対に使わない:

   python3 .../assets/apply-cleanup-selection.py /tmp/cleanup-selection-<ts>.json
   

   スクリプトは選択 JSON から selected_items を読み取り、各項目の command フィールドを実行します。組み込みの安全対策として、保護対象の項目は protected_overrides に含まれていない場合はスキップされます。実行前には、コマンドがハード保護対象パスのリストに照らして検証され、.. コンポーネントの有無も確認されます。すべての操作は、Mole 互換の TSV 形式で ~/.config/mole/operations.log に記録されます。--dry-run は実行せずにプレビューします。適用フェーズで独自の rm ブロックを書かないでください。そうすると、ユーザーが明示的に選択しなかった項目まで削除してしまいます。選択 JSON が唯一の信頼できる情報源です。selected_items に含まれていなければ、削除されません。ユーザーに見える差分を確認できるよう、実行前と実行後に df -h /System/Volumes/Data を実行します。
9. 目標に達したら終了 — 多くのユーザーは空き容量 100 GB を目標としています。無理にそれ以上を目指す必要はありません。 Python スクリプトは bash-3.2 に対応しており、標準ライブラリのみを使用し、エージェントのシェル内から安全に実行できます。references/never-touch.md に記載されている厳重に保護された項目は、必ず UI に "protected": true と具体的な warning 文字列を表示してください。UI では該当項目を暗く表示し、チェックを入れる前に項目ごとの確認ダイアログを表示します。ユーザーデータが依存している保護対象（Telegram の tdata、Bear データベース、パスワードマネージャーのコンテナなど）を絶対に省略しないでください。見えるようにすることで、その周辺にあるリスクをユーザーに伝えられます。

B. 「アラートを設定する」（新しいマシンまたは初回）

上記の初回利用時の案内を完了し、監視を復元する場合は既存の選択内容を維持してください。オプションのディスク応答については、references/optional-disk-responses.md に従ってバンドルされたヘルパーと依存関係をインストールし、どちらのモードも有効にしないでください。独立した明示的な同意を得た後にのみ、有効化を記録してください。

1. assets/mac-health-check と assets/mac-health-action を ~/bin/ にコピーします（先に mkdir し、chmod +x を実行します）。
2. assets/com.local.mac-health-check.plist を ~/Library/LaunchAgents/ にコピーします。
3. assets/config.sh を ~/.config/mac-health/config.sh にコピーします（先に mkdir します）。
4. brew install vjeantet/tap/alerter を実行します（terminal-notifier は使用しないでください。2026 年の Sequoia／Tahoe では動作しません）。
5. パッシブレイヤー用に brew install --cask stats を実行します。
6. launchctl load -w ~/Library/LaunchAgents/com.local.mac-health-check.plist を実行します。
7. 初回実行時の権限プロンプト：alerter --message test を対話的に一度実行して、macOS に通知センターの権限を求めさせます。
8. ユーザーに、7 日間のキャリブレーション中は通知されず、ログのみが記録されることを伝えます。パターンがノイジーな場合は、1 週間後に config.sh を編集するよう案内します。

キャリブレーション期間は、元からあるディスク／メモリ／Jetsam のクリティカルセンサーに適用されます。CPU には開発用ワークステーション向けの保守的なデフォルト設定が適用され、すぐに動作を開始します。プロセスに関するアドバイザリーは、インシデントの全期間にわたり通知されず、重複も排除されます。

launchctl list | grep mac-health で確認します（PID が表示され、終了コードが 0 になるはずです）。また、tail -f ~/Library/Logs/mac-health/health.log でログを確認します。

C. 「すでに alerter を使っているが、動作しなくなった／通知が鳴り続ける」

references/alerting.md の § トラブルシューティングを読みます。よくある原因：

• alerter ではなく、停止している、または古い terminal-notifier（cask）を使用している — 置き換えます。
• macOS のアップデート後に LaunchAgent が読み込まれていない — launchctl bootstrap gui/$(id -u) <plist> を実行します。
• 通知が Script Editor に送られている — TCC の権限が取り消されたため、再度許可します。
• 開発作業中にアラートが絶えず表示される — touch ~/.config/mac-health/silent を実行して通知を抑制します。

D. 「アプリをきれいにアンインストールする」

mo uninstall <app> — Mole は 12 か所以上（Application Support、Containers、Group Containers、Caches、Preferences、Saved State、LaunchAgents、LaunchDaemons、ログイン項目など）をスキャンして、アプリの痕跡を探します。必ず最初にドライランを表示し、迂回してはいけません。

安全ルール（交渉不可）

1. ティア 5 以上、または sudo 操作では、ドライランとユーザーの確認なしに削除してはいけません。
2. references/never-touch.md を決して迂回してはいけません — ユーザーから明示的に依頼された場合でも同様です。依頼を断り、その結果を説明してください。
3. mo purge と mo clean は、必ず最初に --dry-run を付けて実行してください。 推定される空き容量を示し、確認を得てください。
4. Time Machine バックアップには、rm ではなく tmutil delete <path> を使用してください。 TM タグ付きのパスには tmutil API が必要です。
5. /Library、/private/var/db/* を sudo でクリーンアップする場合は、references/never-touch.md § Sudo allowlist に記載された許可リスト内のサブパスのみを対象にしてください。
6. アラートに連動する無制限の自動クリーンアップフックを設けてはいけません。 唯一の例外は、references/optional-disk-responses.md に記載された、Mole キャッシュを 2% 未満に抑える、独立して承認済みの範囲限定の緊急プロファイルです。このプロファイルでは、対象ファイルを正確に指定したドライランが必須です。事前のプロファイルへの同意がインシデント発生時の確認に代わるのは、このプロファイルに限られます。5% 以下での計画は、削除の許可を与えるものではありません。緊急時の同意によって、通常のクリーンアップティアや保護対象パスの削除が許可されることもありません。
7. CPU アラートに連動する自動終了フックを設けてはいけません。 CPU に関する警告で提示できるのは「プロセスを停止…」という選択肢ですが、ユーザーが明示的に実行する場合に限られます。PID／実行ファイルの識別情報と所有者を再検証してから確認を取り、まず SIGTERM を送信してください。SIGKILL の送信には、別途確認が必要です。
8. スワップファイルを削除してはいけません。 実行中に rm /private/var/vm/swapfile* を実行すると、カーネルパニックが確実に発生します。
9. 適用フェーズでは、選択 JSON のみを読み取ってください。 適用時に rm ブロックを手作業で作成したり、先行するスキャン時のパスをハードコードしたりしてはいけません。実際のインシデントでは、エージェントが元のスキャンでデフォルト選択されていた録画のリストを適用し、ユーザーが送信前に UI でチェックを外していたことを無視しました。構造的な修正として、assets/apply-cleanup-selection.py を使用し、選択 JSON の selected_items のみを反復処理してください。

自動計画では、ヘルパーの型付き format_version: 2 分岐を使用し、選択内容に厳密に紐づいたローカルページ上で別途確認を行います。別個のプロファイル同意を使用するのは、ルール 6 に記載された緊急時の実行処理のみです。この処理では、ユーザーによる対話型の選択を再利用したり、範囲を広げたりすることはできません。

ドメイン固有の注意点

• macOS Tahoe（26.x）に搭載されている /bin/bash は 3.2.57 です。set -u と local var（初期化なし）を組み合わせると、初回の参照時に未定義変数エラーになります。付属のスクリプトではこの問題に対処しています。
• LaunchAgent はユーザーの PATH を継承しません。plist で EnvironmentVariables.PATH を宣言し、インタープリターには絶対パスを使用する必要があります。
• Apple Silicon 搭載ノートパソコンでは、スリープ中に StartInterval の時計が停止します（レーダー番号 6630231）。明示的な分単位のエントリーを使って StartCalendarInterval を使用してください（付属の plist には 12 個すべてが含まれています）。
• terminal-notifier は実質的にメンテナンスされておらず（最終リリースは 2019-11）、Sequoia／Tahoe を搭載した Apple Silicon では通知に失敗しても何も表示されません。代わりに alerter を使用してください。
• launchd からの osascript display notification は通知元が「スクリプトエディタ」と表示され、動作も不安定です。launchd のコンテキストでは alerter を使用してください。
• 定期チェックで log show --last 6m を実行するには時間がかかりすぎます（30 秒以上）。代わりに /Library/Logs/DiagnosticReports/JetsamEvent-*.ips をポーリングしてください。5 分間隔であれば、非同期書き込みによる遅延は許容できます。
• JetsamEvent-*.ips ファイルはシステム全体の /Library/Logs/DiagnosticReports/ にあり、~/Library/Logs/DiagnosticReports/ にはありません。
• macOS の ps %cpu は最大 1 分間の減衰平均で、論理コア 1 個を基準に測定されるため、プロセスの値が 100％を超えることがあります。2 回目の iostat サンプルから得られるシステム全体の CPU 使用率は、マシン全体を対象とした 0～100％の値です。5 分ごとに top を起動するよりも、iostat のほうが大幅に軽量です。
• CPU 通知では、コマンド引数を読み取らずに、対象アプリを特定します。まず既知のツールのパス（Playwriter、SourceCraft、Logi Options+）を照合し、次に実行ファイルまたは親プロセスのチェーンから外側の .app バンドルを特定し、最後に実行ファイルをフォールバックとして使用します。通知には App と Process の両方を表示するため、Codex (Renderer) などのヘルパープロセスも ChatGPT に正しく紐付けられます。
• 15 分を超える間隔が空くと CPU カウンターがリセットされるため、スリープやカレンダーイベントの実行漏れが、連続した高 CPU 使用率の測定値として扱われることはありません。未解決のインシデントは継続しますが、再通知を有効にするには、新たに回復の測定値が必要です。
• APFS のパージ可能領域の空き容量は、実際に削除してから数分遅れて反映されます。クリーンアップ直後は df に変化が表示されない場合があります。しばらく待つか、diskutil info /System/Volumes/Data | grep "Container Free" を実行してください。
• Claude Desktop の vm_bundles/claudevm.bundle/ は Claude Cowork であり、「Claude Code のサンドボックス」ではありません。Anthropic のサンドボックス化されたコード実行機能向けの約 10 GB の Ubuntu VM イメージ（rootfs.img、sessiondata.img、efivars.fd、vmIP）です。整合性を確認する SHA1 チェックにより、Claude Desktop を起動するたびに自動的にプロビジョニングされるため、mtime が最近であってもユーザーが最近利用したとは限りません。技術的には安全に削除できます（チャット／MCP への影響はありません）が、次回の起動時に Claude Desktop が通知なく約 10 GB を再ダウンロードし、その間は CPU を約 55％使用します。Claude Code CLI はこのバンドルを使用しません。推奨分類は「Tier 10：事前に相談」です。事前手順として Claude Desktop を終了し、Anthropic がオプトアウト用の切り替えを提供するまではバンドルが戻ってくることを警告してください（anthropics/claude-code#57371 で未解決）。
• 一般原則：一文で説明できないフォルダー／バンドル（特に 500 MB を超えるもの）に遭遇した場合は、推測しないでください。項目の description を書く前に、web-searcher サブエージェントに簡単な調査を依頼してください。ワークフロー A のステップ 4 を参照してください。

回復規模

高負荷の開発プロファイル（Docker、複数のAIツール、IDE、ブラウザー）でメモリープレッシャーが続き、空き容量が約8％になったMacでの代表的な回復例です。

• 4時間のセッションでディスク容量全体の約25％を回復
• 最大の要因：mo purgeによるプロジェクトのビルド成果物の削除（多数のスキャンパスで約30〜50 GB）
• 古いIDEのインストール、キャッシュ、環境設定：約10 GB
• Dockerの回収（未使用のイメージ、停止したビルダー、孤立したボリューム）：約10 GB
• ~/Downloadsの確認（古いインストーラー、録画、アーカイブ済みのリポジトリ）：約15 GB
• パッケージマネージャーのキャッシュ（npm、pnpm、gradle、maven、cargo、brew）：約5 GB
• sudo権限でのクリーンアップ（システムログ、ベンダーアプリのデポ）：約5〜10 GB

7日間の調整期間を設けてアクティブなアラート機能をインストールし、運用開始前に人工的なディスクトリガーテストで動作を確認しました。受動的な監視用に、メニューバーに統計アプリをインストールしました。

数値はワークロードとディスク容量によって変わります。ライトユーザーの場合は少なく、AI、Docker、IDEを多用するユーザーの場合は多くなります。