Housekeeping

Housekeeping は、ThreadCells が対象であることを証明できる場合にのみランタイム成果物を回収します。意図的に保守的です。未知、読み取り不能、アクティブ、参照中、または変更済みのリソースは、安全に削除できると推測せず保護します。

Click to expand

クリーンアップできるもの

経過時間と所有権の証拠に応じて、計画には次を含められます。

• ThreadCells の所有権マーカーを持つ期限切れ一時パス。
• アクティブな端末から参照されていない古い端末アタッチメント。
• 圧縮または保持期間によるクリーンアップの対象となるログ。
• 正確なプロセス ID で特定された孤立ブラウザープロセスグループ。
• アクティブなメタデータから参照されていないブラウザーリビジョンとキャッシュ。
• 所有者が停止済みで未参照の ThreadCells ラベル付きコンテナとボリューム。
• 回収操作を測定できる信頼済みパッケージキャッシュ。
• 正規のステージングメタデータで表される非アクティブな候補／リリース。
• 永続的端末がすでに終了し、プロセス ID がなお一致する、正確な終了端末ランタイムペインとプロセス子孫。
• 永続的な結果／退役境界が確認応答され再検証された後の、クリーンアップ保留中の管理対象子 worktree。
• HEAD が明示的に設定された永続 Git ref にすでに含まれている、クリーンな非アクティブリンク済み worktree。
• 所有者が停止し保持期間が経過した後に、承認済みキャッシュルート直下にある、マーク済みの再現可能なキャッシュ／生成済み証拠。

Housekeeping は、ソースリポジトリ、アクティブまたは未知の worktree、実行中端末、オープンファイル、現在／ロールバックリリース、ステージ済み候補、バックアップを無差別には削除しません。リンク済み worktree は汎用の再帰削除ではなく、git worktree remove と git worktree prune で退役します。終了端末ランタイムの退役によって、その永続セッション、エージェント、Inbox、結果、ワークフロー履歴が削除されることはありません。

再現可能なディレクトリは、設定済みルートの直下の子であり、.threadcells-reproducible.json を持つ必要があります。

{"schema_version":1,"owner":"threadcells","kind":"cache","created_at":1790000000,"owner_pid":12345}

サポートされる種類は cache、generated、test_evidence、candidate です。マーカーの欠落または無効、シンボリックリンク、パスエスケープ、稼働中の所有者、保持期間内のパスは保護されたままです。

デプロイメントでは、後方互換の CI キャッシュ向けに、ThreadCells 所有の正確なキャッシュプレフィックスを追加で指定できます。これらのエントリーも、承認済みのランタイム所有ルート直下の子に限定され、保持期間の経過に加えて、同じアクティブプロセスおよび実行時 ID チェックが必要です。曖昧なリリース候補成果物を含む未登録のプレフィックスは保護されたままです。

最初に計画、次に実行

ドライラン計画は読み取り専用です。各候補には、カテゴリ、正規 ID／フィンガープリント、提案する操作、総バイト数、判明している場合の推定回収バイト数、保持理由、保護理由が含まれます。クラスの要約では、操作可能／回収可能なフットプリントと保存／保護されたフットプリントを別々に報告するため、大きな保護クラスがゼロバイトとして隠れることはありません。

Inspect current state
      ↓
Build immutable plan and plan_id
      ↓ operator reviews
Execute exact plan_id
      ↓
Rebuild protected set under lock
      ↓
Revalidate each candidate immediately before action
      ↓
Report reclaimed, skipped, changed, and failed items

計画作成から実行までに候補セットが変わった場合、手動実行はリソースを変更せずに古い計画を拒否します。残った各候補も変更の直前に再確認されます。

Full Cleanup

Settings → Housekeeping の最後の危険領域の操作は Delete all system files — Full Cleanup です。通常の Housekeeping と同じ正規インベントリー、保護セット、不変の計画 ID、実行時 ID チェックを使用しますが、最大限の証明済み安全な保持ポリシーを適用します。再現可能なキャッシュ、古いログ、ビルド／候補／一時アーティファクト、安全に退役できる worktree、非アクティブなすべてのローカルリリースが対象になり得ます。所有権が不明、または権限が曖昧なものは保護され、計画とレポートに理由が示されます。

Full Cleanup を利用できるのは、バックエンドのライフサイクル事実により、関連する全エージェントが Ready、Exited、または明示的に同等な非実行状態にあると証明された場合だけです。Working、Processing、Starting、キュー内のファイルシステム変更、プロバイダー実行、Heavy 作業、ランタイム操作、不明なライフサイクル ID は実行をブロックします。サーバーは正規のアドミッションフェンスを取得し、変更直前にこのアイドルゲートを再確認します。プレビュー後にエージェントがアクティブになった場合、何も削除せずに実行を中止します。

プレビューは読み取り専用です。実行の受け入れには既存の短命なオペレーターアンロックと、既存の永続操作確認モーダルが必要です。Full Cleanup 専用パスワードやクライアント保存シークレットはありません。受け入れ時に、正確な64文字の plan_id に結び付いた不透明な操作 ID が一つ作られ、任意のパスは受け取りません。受け入れ後は、ブラウザー切断、アンロック期限切れ、コントロールプレーン再起動を越えて、進捗と最終レポートが永続化されます。同じ操作の再要求は状態を観測するだけで、二度目の破壊的処理を開始しません。別の計画には新しい認可が必要です。

パス名に基づく Full Cleanup の各候補は、限定されたソケットアクティベーション方式の root ヘルパーによって実行されます。ヘルパーは一回限りのサーバー能力を消費し、正確な計画を再構築し、アイドルゲートを証明し、コントロールプレーンがすべてのアドミッションフェンスを保持し続けていることを検証します。生のオペレーター認証情報がヘルパーへ送られることはありません。各候補は同じファイルシステム上の root 専用隔離領域へ移動され、取得済みディレクトリーツリーは runtime ユーザーによる変更に対してロックされ、その後ディレクトリーディスクリプターを通じて検証済み ID だけが削除されます。ヘルパーは応答前に範囲制限された最終レポートを永続化します。再起動時とポーリング時の整合処理は、まだ生存する正確なヘルパーを保持するか、破壊的処理を再実行せずに真実どおりの失敗／不確定結果を報告します。ID が変わっていれば保持して報告し、ファイルシステム以外のライフサイクルリソースは引き続き正規のトランザクション実行器を通ります。

Full Cleanup が成功すると、アクティブな不変ローカル ThreadCells リリースだけが残ります。証明済みの非アクティブなロールバック／復旧リリースはすべて削除され、リリースメタデータはアトミックに整合され、ローカルロールバックは利用不可と報告されます。アクティブリリースとアクティブポインターは決して候補になりません。Ready エージェントは引き続き利用できます。worktree、書き込み権限、現在のコンテキスト、現在の出力、その他の継続状態は保護されます。終了済み履歴は、安全なファイルシステム出力がクリーンアップされた後も SQLite に残る場合があります。その場合 Full Output は、失敗したりテキストを作り上げたりせず、永続出力が利用できないことを報告します。

バックアップ、現在のソース／ツール権限、プロバイダー認証情報／状態、SQLite データベース、証明できないリソースは保護されたままです。2回目の Full Cleanup は安全で、新たに適格になった項目または以前に保護された項目を除き、実行可能項目がほぼゼロの計画になります。

安全な手動実行例

インストール済み環境から、まず JSON 出力を要求します。

threadcells-housekeeping --dry-run --json

すべての候補を確認し、返された plan_id をコピーします。確認した計画だけを実行します。

threadcells-housekeeping --plan-id PLAN_ID_FROM_DRY_RUN

計画を理解するまでは、plan_id の抽出と即時実行をスクリプト化しないでください。ドライランは削除承認を意味しません。

保護セットの考え方

保護セットは、アクティブな端末と worktree、書き込み／ワークフロー所有権、現在のソース／ランタイム系統、アクティブおよびロールバックリリース、ステージ済み候補、参照中のブラウザーリビジョン、オープンファイル、稼働中プロセスの開始 ID と端末 ID、コンテナ参照メタデータ、バックアップ、共有ロックを組み合わせます。

実装では詳細が重要ですが、オペレーター向けの規則は単純です。証拠がないことは、リソースが停止している証拠ではありません。保護を正確に確立できない場合、Housekeeping はそれをスキップし、理由を報告します。

保護されるワークフロー権限は、永続的なルート端末 ID から導出されます。起動時および頻繁な照合で、ルート端末が存在しなくなった孤立した非復旧ワークフローを取り消し、保護セットを再生成します。この関係が照合されるまで、worktree の退役は不確実なインベントリー全体に対してフェイルクローズします。

スケジュール

Settings → Housekeeping では、ポリシー、スケジュール、計画、実行、レポートを分けます。サポートされるスケジュール形式には次があります。

• 6h のように、15 分から 365 日までの頻繁な間隔。
• Sun 04:00 UTC のような毎週 UTC のスケジュール。
• on_red を使うディスク圧迫時のクリーンアップ。

インストール済みタイマーは 15 分ごとにポーリングでき、頻繁なチェックと週次チェックが通常は衝突しないよう初回アクティベーションをずらします。永続的な受領記録により、スケジュールクラスが期限前に二度実行されることはありません。正規の Housekeeping エンジンがすでにアクティブだと判定したスケジュール済みポーリングは、スキップとして正常終了し後で再試行します。一方、手動のロック競合はエラーのままです。スケジュール済み実行は一つのサービスロック下で期限到来の計画を作成して実行します。人が承認した手動計画を再利用することはありません。

Housekeeping の変更と手動実行は、オペレーター認可で保護されます。

ディスク圧迫時の動作

YELLOW では、増加状況を確認してドライ計画を実行します。RED では、通常の重い作業が拒否される場合でも、ThreadCells は復旧安全な Housekeeping の Heavy リースを受け入れられます。圧迫時の計画は、証明済みで安全な最大の候補を先に並べ、支配的な保護クラスを表示しますが、クリーンアップは依然として一つの Heavy 実行として数えられ、候補保護を回避しません。

YELLOW は確認状態であり、回収可能なバイト数を作り出す許可ではありません。大きなクラスがすべて保護されている場合は、条件を弱めるのではなく、外部容量を確保するか保護されたフットプリントを文書化してください。

パッケージキャッシュの回収は、コマンドがバイト数を証明できない場合、unknown/zero として報告されます。ThreadCells が推測した回収量を示すことはありません。

レポートと部分的失敗

最新レポートには、計画／実行 ID、リソース状態、推定値、実際の結果、候補ごとの結果、安定した理由コードが記録されます。一つの候補の失敗によって、後続候補の保護が弱まったり、独立した成功が隠れたりすることはありません。

実行後、ディスク圧迫を確認し、スキップ／失敗したエントリーを調べます。次の実行前に再計画してください。状態が変わった後に古い計画を再利用してはいけません。

バックアップとリリース

バックアップはインベントリー専用です。バックアップ媒体の保持判断は、Housekeeping の自動処理ではなく、オペレーターのバックアップポリシーに属します。

リリースと候補のクリーンアップは正規のステージングロックを共有し、信頼済み参照メタデータを必要とします。通常の Housekeeping はアクティブおよびロールバックランタイムを保護します。Full Cleanup はアクティブリリースだけを保護し、オペレーターの明示的な確認後に、証明済みの非アクティブなローカルロールバックリリースをすべて意図的に削除します。アップグレードを参照してください。

インストール済みのスケジュール Housekeeping サービスには、対象となる不変リリースを回収するために必要な、限定されたリリース保守グループが付与されます。メインコントロールプレーンと通常のエージェントプロセスには付与されません。この権限なしの手動／API 実行は、RELEASE_ADMIN_GROUP_REQUIRED としてリリース削除をスキップし、独立した安全なクリーンアップを続行します。スケジュール済みサービスは、同じ計画／実行エンジンを通じて後でリリースを回収します。

オープンパス保護は、手動計画を呼び出す承認済みアカウントに関係なく、設定済み ThreadCells ランタイムアカウントが所有するすべてのプロセスをインベントリーします。他のホストアカウントは、破棄可能な ThreadCells 状態の所有権境界の外です。それらのアカウントの読み取り不能な非公開 /proc エントリーが、ホスト全体のクリーンアップを無効にすることはありません。ランタイム ID が不明、またはランタイムアカウントのプロセス確認中に不確実性がある場合は、常にフェイルクローズします。

よくある誤り

• 空き容量を回復するために worktree ディレクトリを直接削除する。
• 推定バイト数を回収保証と見なす。
• 確認していない計画を実行する。
• 停止した PID だけでブラウザー／プロセスグループが古いものだと証明できると考える。
• Housekeeping がバックアップを削除すると期待する。
• 継続的な増加への対処ではなく、ディスクしきい値を上げる。