ランタイムの状態と永続化

ZeroClaw のインストールルートは1つですが、モノリシックな「ワークスペースデータベース」は1つではありません。状態の各領域には、それぞれ異なる所有者、リロード動作、永続性があります。変更によって状態を追加する、状態を移動する、設定をキャッシュする、リロードに影響する、またはセッション/メモリ/ログ/コストの動作を変更する場合は、このマップを使用してください。

単一の信頼できる情報源のルールは引き続き適用されます。ある事実がすでに1つのサーフェスに存在する場合、それを別の保存フィールドにコピーしないでください。新しい状態は、このテーブルが所有するサーフェスを特定した場合にのみ保存するか、使用時に正規の所有者から解決してください。

インストールレイアウト

通常のインストールでは、<install> は解決済みの設定ディレクトリです（デフォルトは ~/.zeroclaw/。Homebrew および明示的な --config-dir によるインストールでは移動できます）。現在のレイアウトは次のとおりです:

<install>/
├── config.toml                 # canonical user config
├── .secret_key                 # key for encrypted secrets
├── data/                       # instance-wide runtime data
│   ├── sessions/
│   │   ├── sessions.db         # default chat/session backend
│   │   └── acp-sessions.db     # ACP protocol sessions
│   ├── cron/jobs.db            # scheduled job state
│   ├── sop/runs.db             # optional durable SOP run state
│   ├── control_plane.db        # task supervision records
│   ├── state/
│   │   ├── runtime-trace.jsonl # persisted logs
│   │   └── costs.jsonl         # cost ledger
│   ├── devices.db              # paired-device metadata
│   ├── plugin-state.db          # encrypted exact-instance plugin state
│   └── memory/                 # shared instance memory stores
├── shared/                     # shared resources, such as skill bundles
└── agents/<alias>/workspace/   # per-agent filesystem sandbox and identity

レガシーの <install>/workspace/ という名前は移行中も引き続き受け付けられますが、新しいランタイム状態は <install>/data/、<install>/shared/、およびエージェントごとのワークスペースの観点で記述してください。

状態マップ

Surface	正規ソース	永続パス	インメモリ所有者	リロード／同時実行の境界	注釈
設定値	`config.toml` から読み込まれた `zeroclaw-config::Config`	`<install>/config.toml`	daemon `Arc<RwLock<Config>>` とサブシステムごとの解決済みビュー	`/admin/reload` は設定を再読み込みし、daemon サブシステムを再インスタンス化します。設定の直接書き込みでは、スキーマ検証と dirty-path チェックが使用されます。RPC 側の設定変更ではさらに、読み取り・変更・フラッシュのセクション全体を `RpcContext::config_write_lock` で直列化します（tokio mutex を先に、`parking_lot` `RwLock` を後に取得し、`.await` または `lock().await` をまたいで `parking_lot` ガードを保持することはありません）。gateway の HTTP 設定変更でも同様に、読み取り・変更・スワップのセクション全体を `AppState::config_write_lock` で直列化します（ロック順序は同じです）	キャッシュがリロード時に明示的に再構築される場合を除き、設定から導出された事実を長寿命の構造体にキャッシュしないでください。
設定保存の永続性	`save()` / `save_dirty()` の `zeroclaw-config` におけるアトミック書き込みパス	`<install>/config.toml` と保持された `config.toml.bak`	設定値と同じ	書き込みは、一時ファイル、置換前のディレクトリ同期、アトミックな名前変更、置換後のディレクトリ同期を経て行われます	`Ok(())` は置換が可視になったことを示すのであって、rename の永続性が証明されたことを示すものではありません。置換前に失敗した場合は、ディスク上の設定と実行中の設定を変更しないまま中止されますが、rename 後のディレクトリ同期に失敗しても、警告がログに記録され、`config.toml.bak` が保持された状態で `Ok(())` が返されます。このような保存の直後にクラッシュすると、ディレクトリエントリが以前のファイルを再び指す可能性があります。呼び出し元は `Ok` を、より強い永続性保証として扱ってはならず、復旧時には保持された `.bak` を参照できます。
暗号化されたシークレット	Config のシークレットフィールドと `.secret_key`	`<install>/config.toml`、`<install>/.secret_key`	`zeroclaw-config` の secret-store ヘルパー	リロードで変更された設定が検出されますが、`.secret_key` を失うと暗号化された設定シークレットが復元不能になります	決して復号された値をログ、ドキュメント、PR本文、またはランタイムメタデータにコピーしないでください。
Plugin の永続状態	認証済みの状態エンベロープ。ホストが発行したプラグインインスタンスID と、移植可能な論理キーで識別されます	`data/plugin-state.db`、`<install>/.secret_key` で暗号化	実行時に `PluginHostServices` を介して注入される `PluginStateStore`	SQLite WAL と compare-and-swap による revision で書き込みを直列化し、tool/channel のサービスフレームで有効な権限(grant)を再確認する	DBは鍵付きブラインドインデックスと`enc2:`暗号文のみを公開します。`.secret_key`でバックアップしてください。鍵が存在しない場合、または置き換えられた場合は、フェイルクローズドで失敗します。
エージェントのファイルシステムアイデンティティ	エージェントごとのワークスペースファイル	`<install>/agents/<alias>/workspace/`	実効的な `SecurityPolicy` とエージェントプロンプトの構築	エージェント起動時に遅延作成されます。ワークスペースへのアクセスは設定から評価されます	これはファイルシステムサンドボックスであり、プロバイダー/チャンネル/ツールの設定ソースオブトゥルースではありません。
共有スキルバンドル	設定済みのスキルバンドルエントリと解決済みのバンドルディレクトリ	`<install>/shared/skills/<bundle>/`（デフォルト）	スキルの読み込み / プロンプトの拡充	リロードと新しいエージェントの起動で設定とファイルシステムの変更を監視します	バンドルエイリアスとディレクトリ解決は設定から取得されます。ファイルはバンドルの内容です。
会話メモリ	`zeroclaw-memory` バックエンドがエージェントごとに選択されました	SQLite/Postgres/Lucid/Qdrant/Markdown バックエンドの格納場所。SQLite 共有ストアは `data/memory/` 配下に配置されます	`Arc<dyn Memory>`（エージェントスコープのアダプターでラップ）	バックエンドの選択は、エージェントがデータを書き込んだ後はロックされます。同じバックエンドでのクロスエージェント・リコールはオプトインです	メモリ行はエージェントスコープです。コピーしたプロンプト/セッションキャッシュでメモリの所有権を置き換えないでください。
チャットとチャンネルのセッション	`[channels].session_backend` および `SessionBackend`	デフォルトは `data/sessions/sessions.db`；レガシー/明示的な JSONL では `data/sessions/*.jsonl` を使用します	`zeroclaw-infra` バックエンドハンドルは現在、チャネル、ゲートウェイ、RPC、セッションツールによって個別に構築されています	SQLiteバックエンドはWALを使用します。`SessionActorQueue`はセッションごとにアクティブなターンを直列化します。ゲートウェイのWebSocketは、セッションのアクティブなターンの所有者ではなく、閲覧者です。クライアントが切断されるとデタッチされ、ターンは最後まで実行されます。`POST /api/sessions/{id}/abort`だけがターンをキャンセルし、そのターンが開始したエージェント型デリゲート子プロセスと、ツールループを実行している並列子プロセスも併せてキャンセルします(単純なモデル呼び出しを行う並列子プロセスは、その呼び出し自体のタイムアウトで終了します)。バックグラウンドのデリゲートタスクはターンを超えて存続し、`cancel_task`によってのみ停止します。JSONLの変更は、プロセス内のセッションディレクトリロックを共有します。	Chat/Code セッションでは統合バックエンド契約を使用します。ACP プロトコルセッションでは別のストアを使用します。プロセス単位のバックエンド所有権は、まだ一元管理されていません。
ACP セッション	ACP プロトコルセッションストア	`data/sessions/acp-sessions.db`	`AcpSessionStore` はデーモン起動時と RPC コンテキストで開かれます	チャットセッションとは別の、WALバックアップ付きSQLiteストア	ACP `session/load` および `session/resume` は、チャットセッションのバックエンドではなく、このプロトコルストアに対して動作します。
ライブ RPC/TUI セッション	RPC `SessionStore`	none by itself	`crates/zeroclaw-runtime/src/rpc/session.rs` のインメモリマップ	プロセスローカル。セッション履歴はチャットまたはACPバックエンドを通じてのみ永続化されます	ライブセッションハンドル、アップロード、キャンセルトークン、オーナー、およびオーバーライドはランタイム状態です。
Cron ジョブ	宣言的設定メンバーシップと cron SQLite ストア	`data/cron/jobs.db`	`zeroclaw-runtime::cron` スケジューラー/ストア	読み取りパスでは `jobs.db` を作成しません。スケジューラが期限/ロックの状態を管理します	宣言的ジョブは設定からリコンサイルされ、実行メタデータとロックはcron DBに存在します。
SOP の実行	`SopEngine` と `SopRunStore`	デフォルトでは None。永続 SQLite の初期化に成功した場合は `data/sop/runs.db`	SOPエンジンのアクティブ/完了済み実行キャッシュ	永続ストアはアドミッション要求と永続化されたリビジョンを管理し、エンジンは起動時にアクティブ状態と終端状態を復元します	ストアの初期化に失敗すると、警告をログに記録してメモリにフォールバックします。メモリ上の監査レコードは、実行ライフサイクルの正本ではありません。
バックグラウンドタスクの監視	永続タスクのコントロールプレーン	`data/control_plane.db`	observer/producer ハンドルと、デーモン専用のリカバリ所有者およびリーパー	Owner PIDとプロセス開始時刻による識別情報により、稼働中の作業が復旧処理によって誤って引き取られることを防ぎます。ハートビートのタイムアウトは、ハートビートを送信するプロデューサーにのみ適用されます。	バックグラウンドのデリゲートにはタスク行が必要で、ステータス、出力参照、エラーをそこでアトミックに確定します。プロセスローカルのスーパーバイザーは、失敗した終端書き込みを上限付きバックオフで再試行します。発信元のエージェントエイリアスが、新規行の結果およびキャンセルへのアクセス範囲を定めます。終端の事前ルーティング行は、完全一致IDによる読み取り互換性のみを保持します。サブエージェントの登録はベストエフォートのままで、route は未設定のままにします。バックグラウンドのデリゲート行は、起動元のツールループのセッションキーを principal として記録し、実行中は heartbeat を更新します。未設定のままになるのは parent フィールドのみです。サブエージェントの行では、heartbeat、parent、principal フィールドはいずれも未設定のままにします。Goal API は存在しますが、エンドツーエンドの goal 実行はまだ接続されていません。
バックグラウンドのデリゲートの出力	\|Delegate output artifact

Translation to Japanese: “委任出力アーティファクト”|<workspace>/delegate_results/<task-id>.json|デリゲートツールのキャンセルレジストリと実行中のフューチャー||Output files survive restart; live cancellation handles do not 出力ファイルは再起動後も残りますが、ライブのキャンセルハンドルは残りません| |-|||Current artifacts contain task identity and output but no lifecycle status, error, or timestamps. Reads take lifecycle state from the task row; legacy status-bearing files are fallback-only when no row exists.

Wait — I need to translate this into Japanese, not return it unchanged. Here is the translation:

リロードして再起動

POST /admin/reload はデーモンにプロセス内リロードシグナルを送信します。外側のデーモンループはディスクから設定を再読み込みし、デーモンを再実行して、新しい設定からゲートウェイ、チャネル、ハートビート、スケジューラ、MQTT、セッション、メモリ、コストの各配線を新規に作成します。PID は変わりませんが、リスナーは一時的に再バインドされます。

完全なプロセス再起動は、ライブRPCセッション、ヘルススナップショット、アクターキュー、および一時的なツールレシートキーなどのプロセスローカル状態もローテーションします。永続ストアは上の表に従って再起動後も存続します。

セッションバックエンドの移行

SQLite セッションバックエンドを選択すると、バックエンドハンドルの構築時にレガシーな data/sessions/*.jsonl ファイルがインポートされます。インポーターは、プロセスローカルの JSONL 変更ロックを保持したまま各ソースをプライベートな .jsonl.importing 世代に移動し、1 つの SQLite トランザクションでメッセージ、メタデータ、ソースに紐付けられたインポートレシートを書き込み、その後ロールバック用にソースを .jsonl.migrated として保持します。

レシートは、ソースファイル名、セッションキー、SHA-256ダイジェスト、バイト長を紐付けます。レシートトランザクションが開始する前に、インポーターはステージ済みソースファイルを同期し、Unixではライブからステージ済みへのディレクトリ名変更も同期します。移行トランザクションでは、インポートコミットに完全なSQLite同期を使用してから、通常のランタイム設定に戻します。アーカイブへの引き渡しでも、ステージ済みソースを削除する前に、Unixでディレクトリメタデータを同期します。バックエンドの構築では、ソースファイルをスキャンする前に、永続化されたレシートからプロセスローカルの非アクティブ状態を復元します。インポートレシートがコミットされるとすぐに、そのセッションディレクトリに対するJSONLの変更は、アーカイブへの引き渡しや後続ファイルが失敗した場合でも非アクティブなままになります。次回の構築では、そのレシートと照合してステージ済みソースを検証し、重複メッセージを挿入せずに引き渡しを完了できます。空または空白のみのJSONLファイルは、メッセージ数0のSQLiteセッションとして保持されます。有効なメッセージがない空でないソースは、引き続きフェイルクローズします。

ソースをインポートせずに SQLite バックエンドを構築しても、JSONL ミューテーションは無効化されません。そのため、永続的なインポートレシートが存在しない場合、インプロセスのリロードによって JSONL に戻る可能性があります。

レシートのないソースは、同じセッションキーの既存の SQLite メッセージやメタデータにマージされません。そのコミット前チェックに失敗した場合、ステージ済みソースは稼働中の JSONL パスに復元されます。互換性のないレシート、ステージ済みソース、またはアーカイブがあると、バックエンドの構築はエラーを返します。各プロセスのエントリーポイントは現在、そのエラーによってサブシステムを停止するか、永続化を無効にするかを個別に判断します。プロセスレベルの所有権と起動ポリシーは、移行契約とは別です。

バックアップと復元

通常の単一インスタンスのインストールでは、<install> ディレクトリ全体をバックアップしてください。最低限、以下を含めてください：

config.toml
暗号化されたシークレットを使用する場合は .secret_key
data/memory/
data/sessions/
ランタイムサーフェスを通じて cron ジョブが構成されている場合は data/cron/jobs.db
永続的なSOP実行が有効な場合は data/sop/runs.db
data/control_plane.db（監視対象タスクの履歴が重要な場合）
コスト履歴が重要な場合は data/state/costs.jsonl
インシデントレビューでログが必要な場合は data/state/runtime-trace.jsonl
ペアリング済みデバイスのメタデータ用の data/devices.db
data/plugin-state.db と .secret_key は、プラグインが所有する永続状態のために使用されます

同じインストールルートに対して2つのデーモンを実行しないでください。いくつかのストアはシングルライターモデルのSQLiteを使用しており、プロセスローカルのキャッシュは1つのデーモンがそのインスタンスを所有していると想定しています。

ソースポインタ

設定、install-root、および data-dir の解決: crates/zeroclaw-config/src/schema.rs
セッションバックエンド: crates/zeroclaw-infra/src/session_sqlite.rs、crates/zeroclaw-infra/src/session_store.rs
ACP セッションストア: crates/zeroclaw-infra/src/acp_session_store.rs
RPC ライブセッション: crates/zeroclaw-runtime/src/rpc/session.rs
Cron の永続化: crates/zeroclaw-runtime/src/cron/store.rs
SOPの永続化: crates/zeroclaw-runtime/src/sop/store/
バックグラウンドタスクとゴール監視: crates/zeroclaw-runtime/src/control_plane/
バックグラウンド委任の結果: crates/zeroclaw-runtime/src/tools/delegate.rs
ログ: crates/zeroclaw-log/
コスト台帳: crates/zeroclaw-config/src/cost/tracker.rs
ペアリングガード: crates/zeroclaw-config/src/pairing.rs
デバイスレジストリ: crates/zeroclaw-gateway/src/api_pairing.rs
Plugin durable state: crates/zeroclaw-runtime/src/plugin_state.rs
リロードエンドポイント: crates/zeroclaw-gateway/src/lib.rs

Keyboard shortcuts