バックグラウンド作業のライフサイクル

ZeroClaw には、起動のきっかけとなったインバウンドリクエストの完了後も作業を継続するための方法がいくつかあります。Cron ジョブ、SOP 実行、委譲タスク、および実行時に生成されるサブエージェントは一部の実行機構を共有していますが、ライフサイクルや永続ストアは共有していません。ゴールモードは、エンドツーエンドではまだ接続されていない関連するターゲットコントラクトを定義します。

変更によってスケジュール実行される作業や自律的な作業が追加される場合、待機状態または承認状態が導入される場合、キャンセルや再起動の挙動が変更される場合、または子作業が所有タスクに関連付けられる場合は、このページを使用してください。最初に設計上検討すべき問いは「バックグラウンドでどのように実行されるか」ではなく、「そのライフサイクルを管理するのはどのサブシステムか」です。

所有権マップ

永続的なメタデータは、永続的な実行と同一ではありません。結果ファイルやタスク行は、既知の情報を保持し、作業を実行していたプロセスローカルのfutureを保持することなく、リカバリが作業を「失敗」「タイムアウト」「終了」としてマークできるようにします。

Cron ジョブ

Cron は宣言的なメンバーシップと SQLite の実行ストアを組み合わせます。実行時に作成されたジョブと、調整された構成ジョブは、いずれも所有元の agent_alias を持ちます。実行時には、暗黙のデーモン ID で実行するのではなく、そのエージェントのセキュリティポリシーが解決されます。

スケジューラは、実行期限が来た有効な未クレームの行をポーリングします。行をクレームすることで、処理中の重複選択を防ぎます。完了時には出力を一定範囲に収めて記録し、その後、繰り返しジョブを再スケジュールするか、正常完了した自動削除のワンショットジョブを削除するか、それ以外のワンショットジョブを無効化します。クレームを解放する前にプロセスが終了した場合、次回のスケジューラ起動時に古いロックがクリアされます。

起動時の動作は明示的です。キャッチアップが有効な場合、期限切れのジョブは実行対象として考慮されます。無効な場合、期限切れのワンショットジョブは skipped の結果とともに無効化され、定期ジョブは実行結果を記録せずに次の将来の実行タイミングに進みます。スケジューラはポーリングの反復間でキャンセルトークンをチェックするため、シャットダウン時は現在の実行対象ジョブのバッチが完了するまで待機してからループを終了します。スケジューラのキャンセルは、既にディスパッチされた外部副作用がロールバックされることを保証するものではありません。

SOP の実行

SOP 定義は、設定された sops ディレクトリ配下に配置されます。SopEngine は、実行の進行、承認待ち、チェックポイント、終端遷移、インプロセスのステータスサーフェスを管理します。SopRunStore は、実行を受け入れて確保する際の同時実行制御における信頼できる唯一の情報源です。

実行の永続化はオプトイン方式です。デフォルトの sop.persist_runs = false では、エンジンはインメモリストアを使用します。永続化を有効にすると、デフォルトの SQLite バックエンドは run_state_dir で上書きされない限り、<data_dir>/sop の下に runs.db を書き込みます。ストアの初期化に成功すると、アクティブなスナップショット、ターミナルレコード、イベント、リビジョン、および並行実行クレームによって、再起動時の復元がサポートされます。ストアの初期化に失敗した場合、デーモンは警告をログに記録し、インメモリストアにフォールバックします。

Memory バックエンドの SOP 監査レコードは、別個の可観測性サーフェスです。これらは実行ストアに取って代わるものではなく、実行がアクティブ、一時停止中、承認済み、または終了済みかどうかを判断する権威として使用してはなりません。

承認状態とチェックポイント状態が永続的な制御状態になるのは、run store が永続的な場合のみです。タイムアウトポリシーはデフォルトでフェイルクローズのままです: タイムアウトした承認は、設定でキャンセルまたは従来の自動承認動作が明示的に選択されていない限り、エスカレートして待機を続けます。

委譲とサブエージェント

サブエージェントは、親の実効セキュリティ境界を継承します。ポリシーとメモリのオーバーライドによって親のエンベロープを狭めることはできますが、広げることはできません。また、子のアクションの計上には親のトラッカーが使用されるため、子を生成しても親のアクション予算を回避することはできません。

spawn_subagent パスは同期的です。親は子の実行が完了するまで待機し、このパスにはローカルのタイムアウトやバックグラウンドのキャンセルハンドルがありません。

delegate ツールは同期的に実行することも、バックグラウンドタスクを開始して UUID を返すこともできます。バックグラウンドの結果は、ツールに渡されたワークスペース配下にアトミックに書き込まれ、確認、一覧表示、バッチでの待機、またはキャンセルが可能です。ライブなキャンセルレジストリはタスク ID をプロセスローカルなトークンにマッピングします。キャンセル時には永続化された結果が更新され、そのライブトークンがまだ利用可能な場合は実行中のタスクにシグナルが送られます。

デーモンが起動している状態では、delegate および subagent のプロデューサーも、永続的なコントロールプレーンにタスク行を書き込みます。これらの書き込みはベストエフォートであり、delegate の結果ファイルへの書き込みとは独立しています。delegate 結果の読み取りは引き続きファイル優先です。コントロールプレーンの状態から lost または timed_out としてオーバーレイされるのは、まだ running とマークされているファイルだけであるため、2 つのレコードは食い違うことがあります。

現在のデリゲート行とサブエージェント行には、agent、status、owner PID と boot ID、depth、timestamps が設定されます。heartbeat、parent task、route、principal は未設定のままです。起動時のリカバリでは、前回のブートで実行中だった行を lost とマークします。timed_out は古い heartbeat を発行するプロデューサーにのみ適用されますが、これらのプロデューサーは現在そのような heartbeat を発行していません。タスク行によって中断された子は可視化されますが、その実行が再作成されることはありません。

ゴールモードのターゲット契約

ADR-008 は、ゴールのライフサイクル、所有権、ルート、プリンシパル、親子関係、およびリカバリの適格性について、タスク制御プレーンを将来の権威として位置付けています。リポジトリにはゴールのストレージと制御プレーン API が存在しますが、本番環境におけるゴールの受け入れと実行は、まだエンドツーエンドで接続されていません。

バックグラウンドパスは、所有元のゴールとの関係を維持し、終端状態とモデル使用状況をそのゴールに報告して初めて、ゴールモードに参加できます。それまでは、そのパスはゴールモードでの実行ではなく、通常のバックグラウンド作業です。

変更チェックリスト

バックグラウンド処理の変更については、レビュアーの承認前に次の質問に回答してください：

• どのサブシステムがライフサイクルを所有し、どのストアが信頼できる情報源となりますか？
• 作業はプロセスローカルか、永続的に管理されているか、それとも実際に再起動後も再開可能か？
• どのトークンまたはコントロールプレーンのアクションがそれをキャンセルするか、また何がインフライトのまま残る可能性があるか？
• このパスは、実際にどの親タスク、エージェント、ルート、プリンシパル、再帰深度、使用状況フィールドに値を設定しますか？
• 待機中、承認、チェックポイント、消失、タイムアウト、および終了の各状態は区別できますか？
• 起動時のリカバリーが副作用を重複させたり、クレームを暗黙のうちに宙ぶらりんにしたりする可能性はありますか？
• 再起動後に完了が観測された場合でも、結果の配信はべき等性を保ちますか？

ソースポインタ

• Cronスケジューラと永続化: crates/zeroclaw-runtime/src/cron/scheduler.rs、crates/zeroclaw-runtime/src/cron/store.rs
• SOPエンジンと実行ストア: crates/zeroclaw-runtime/src/sop/engine.rs、crates/zeroclaw-runtime/src/sop/store/
• 委任とサブエージェントの動作: Delegation & SubAgents、crates/zeroclaw-runtime/src/tools/delegate.rs、crates/zeroclaw-runtime/src/tools/spawn_subagent.rs、crates/zeroclaw-runtime/src/subagent/mod.rs
• 耐久性のあるタスクのコントロールプレーンとリカバリ: crates/zeroclaw-runtime/src/control_plane/
• Goal-mode に関する決定: ADR-008
• SOP運用ガイド: SOPの実行方法