セッション状態と復元
Herdr には複数の状態管理経路があります。それぞれが異なる問題を解決します。
何が生き残るか
Section titled “何が生き残るか”| ケース | プロセスは動き続ける | レイアウトは戻る | 直近の画面は戻る | エージェントの会話は再開する |
|---|---|---|---|---|
| デタッチと再アタッチ | はい | はい | はい (ライブのターミナルから) | はい (プロセスが止まらないため) |
| サーバー再起動 | いいえ | はい | ペイン画面履歴が有効な場合のみ | エージェントネイティブのセッション復元がある場合のみ |
--handoff なしのアップデート | 互換性のあるサーバーは動き続ける。再起動が必要なサーバーは停止/再起動が必要な場合がある | 再起動後は戻る | ペイン画面履歴が有効な場合のみ | エージェントネイティブのセッション復元がある場合のみ |
--handoff ありのアップデート | 対応する稼働中サーバーではベストエフォート | はい | はい (ハンドオフが成功すればライブのターミナルから) | はい (ハンドオフが成功すればプロセスが動き続けるため) |
以下のセクションでそれぞれの経路を説明します。
ライブ永続化
Section titled “ライブ永続化”通常のデタッチでは Herdr サーバーは動き続けます。ペイン、シェル、エージェント、サーバー、テスト、コマンドプロセスはそのサーバー内で動き続けます。
ctrl+b q でクライアントをデタッチします。あとで再アタッチします:
herdr元のプロセスが一度も止まらないため、これが最も強力な永続化経路です。
スナップショット復元
Section titled “スナップショット復元”Herdr サーバーが停止して再起動すると、元のペインのプロセスは失われています。Herdr は保存されたセッションの形を復元します: ワークスペース、タブ、ペイン、cwd、レイアウト、フォーカスです。
スナップショット復元は、動作中のシェル、サーバー、テスト、その他任意のプロセスを保存しません。より強力な復元経路が使えないペインは、保存されたディレクトリで新しいシェルとして戻ってきます。
保存されたディレクトリが使えない場合やシェルを起動できない場合、ペインは消えたりホームディレクトリへ移動したりせず、エラーを表示してレイアウトに残ります。保存されたディレクトリとエージェントのセッション参照は保持されます。ディレクトリやシェル設定を修正してサーバーを再起動すると再試行できます。不要なペインは明示的に閉じて削除できます。
保存時には、OS が取得をサポートしていれば、実行中のシェルのディレクトリを優先します。シェル終了後も最後に確認したディレクトリを保持します。それ以外の環境ではシェルが報告したディレクトリを使用します。
session.json を読み込めない、解析できない、または新しい Herdr バージョンが必要な場合、読み込みに失敗した理由をログに記録します。新しいセッションを保存または削除する前に、元のファイルをそのまま session.json の隣の session-backups/ に保存し、復旧用コピーのパスを persist.backup として記録します。起動時にファイルがなかった場合も、最初の保存または削除の前に再確認します。これらの読み込み失敗時の復旧用コピーは、通常のスナップショット履歴とは別に管理します。
復旧用コピーは最新の 3 個を保持し、新しいコピーの安全な保存が完了してから古いコピーを削除します。コピーに失敗すると、自動保存時も終了時も元のファイルを変更せず、失敗をログに記録し、次の保存要求時に再試行します。コピーが自動的に復元されることはありません。復旧するには、対象のサーバーを停止し、復旧用ファイルをそのサーバーの session.json にコピーしてから再起動します。復旧用コピーにペイン画面履歴は含まれません。
シャットダウンとスナップショットからの復旧
Section titled “シャットダウンとスナップショットからの復旧”systemd-logind を使う Linux では、Herdr はホストのシャットダウン予告を受け取り、保存して停止するまで短い遅延を要求します。その後 logind がシャットダウンを進めます。遅延には OS による上限があり、無期限にはブロックしません。logind がない環境、強制終了、電源断、予告前にプロセスが終了した場合には、この保護は使えません。
全プラットフォームで、session.json の隣の session-snapshots/ に最大 48 個のレイアウトスナップショットを保持します。最初に保存したレイアウトは直ちにコピーします。その後の保存や削除では、直前の保存済みレイアウトを最大 15 分に 1 回コピーします。同じ内容は重複保存しません。この間隔はサーバーの再起動後も維持されるため、連続したペイン終了や再起動で古いコピーがすべて押し出されることはありません。直近の変更がコピーに含まれない場合があります。
通常のペイン終了は引き続き session.json に反映されます。復旧を促す通知や、古いスナップショットの自動復元はありません。手動で復旧するには:
herdr session list --jsonで対象のセッションディレクトリを確認します。- 対象サーバーを停止します。デフォルトは
herdr server stop、名前付きセッションはherdr session stop <name>です。 - 現在の
session.jsonを別にコピーしてから、session-snapshots/内の選んだファイルをsession.jsonにコピーします。ファイルの更新日時で保存時刻を確認できます。 - セッションを再起動します。
コピーにはレイアウトとエージェントのセッション参照が含まれますが、実行中のプロセスやペイン画面履歴は含まれません。非公開のセッションデータとして扱ってください。コピーの書き込みに失敗するとログに記録しますが、通常のセッション保存は続行します。
ペイン画面履歴のリプレイ
Section titled “ペイン画面履歴のリプレイ”ペイン画面履歴は、サーバーの完全な再起動後に直近のターミナル内容を復元します。復元されるのは Herdr が表示できるものであって、元のプロセスではありません。
ペイン出力にはシークレット、トークン、プロンプト、コマンド出力が含まれうるため、これはデフォルトで無効です。設定ファイルで有効にします:
[experimental]pane_history = true有効にすると、Herdr は保存したペイン履歴を session.json の隣の session-history.json に保存します。Herdr の設定/セッションディレクトリはターミナル履歴と同じ感覚で扱ってください。
履歴は、保存されたレイアウトと完全に一致する場合だけ再生されます。スナップショットを手動で復元した場合など、異なるレイアウトの履歴は無視されます。レイアウトを検証できない旧形式の履歴も無視されますが、新たに保存された履歴は次回の再起動で再生できます。
エージェントネイティブのセッション復元
Section titled “エージェントネイティブのセッション復元”一部のエージェントは自分の会話セッションを resume できます。Herdr は、公式インテグレーションが報告したセッション参照を使って、Herdr サーバーの再起動後に対応エージェントのペインを再起動できます。
これはデフォルトで有効です。無効にするには:
[session]resume_agents_on_restore = falseHerdr が resume するのは、現行の公式 Herdr インテグレーションを通じてネイティブセッション参照を報告したペインと、エージェント自身が resume コマンドを報告したペインです。エージェントに Herdr 対応を追加するを参照してください。
クライアントがアタッチしてターミナルサイズとテーマのコンテキストを提供すると、Herdr は各ペインがフォーカスされるのを待たずに、ワークスペースとタブをまたいで復元対象のエージェントペインを resume します。
エージェントネイティブのセッション復元には、次の Herdr インテグレーションバージョン以上が必要です:
| エージェント | 最低 Herdr インテグレーションバージョン | resume コマンド |
|---|---|---|
| Pi | 2 | pi --session <path-or-id> |
| OMP | 3 | omp --resume=<path-or-id> |
| Claude Code | 6 | claude --resume <id> |
| Codex | 5 | codex resume <id> |
| Cursor Agent CLI | 1 | cursor-agent --resume <id> |
| Grok CLI | 2 | grok --resume <id> |
| GitHub Copilot CLI | 2 | copilot --resume=<id> |
| Devin CLI | 2 | devin --resume <id> |
| Droid | 2 | droid --resume <id> |
| Kimi Code CLI | 3 | kimi --session <id> |
| Qoder CLI | 2 | qodercli --resume <id> |
| Qwen Code | 1 | qwen --resume <id> |
| Letta Code | 1 | letta --conversation <id>、または default:<agent-id> の場合は letta --conversation default --agent <agent-id> |
| OpenCode | 5 | opencode --session <id> |
| Kilo Code CLI | 1 | kilo --session <id> |
| Hermes Agent | 2 | hermes --resume <id> |
| MastraCode | 1 | mastracode --thread <id> |
インストール済みインテグレーションのバージョンは herdr integration status で確認できます。古いインテグレーションは herdr integration install <agent> で再インストールしてください。
未対応、欠落、無効、重複、または古くなったセッション参照は、保存されたペインディレクトリで通常のシェルとして復元されます。
あるペインにエージェントネイティブのセッション復元が適用される場合、Herdr はそのペインでは保存済みペイン履歴のリプレイではなくエージェントセッションの resume を行います。
ライブハンドオフ
Section titled “ライブハンドオフ”ライブハンドオフは、稼働中の Herdr サーバーを置き換える必要があるアップデートやリモートアタッチのフローのためのものです。古いサーバーにライブペインを新しいサーバーへ移すよう依頼し、サーバー交換をまたいでペインのプロセスが動き続けられるようにします。
これはスナップショット復元、ペイン履歴リプレイ、エージェントネイティブのセッション復元とは異なります。ハンドオフは現在のプロセスを生かし続けようとします。他の経路は、古いサーバーが停止した後に状態を再構築します。
ハンドオフが保護するのは、ペインの PTY とプロセス、エージェントの識別情報と永続メタデータ、交換後のサーバーに必要なプラグイン/セッション状態など、サーバーが所有する長寿命のセッション状態です。交換境界をまたぐ一時的な協調状態は保持しません。処理中の CLI/API リクエスト、wait、購読ストリーム、クライアントソケット、ペイン間メッセージは中断される可能性があるため、クライアントは再接続して再試行してください。
更新済みの Unix サーバーは、ペインを分割して転送することで 64 個を超えるペインを 1 回のハンドオフで送信できます。送信側サーバーがすでにこの機能を備えている必要があります。古いサーバーからの最初の更新では、引き続き 64 ペインの制限が適用されます。その場合は通常のサーバー再起動が必要になることがあり、ペインのプロセスは終了します。分割転送によって更新のインストール順序や他の互換性要件が変わるわけではありません。
ライブハンドオフは実験的機能で、オプトインです:
herdr update --handoffherdr --remote workbox --handoff素の herdr update は新しいクライアントをインストールし、エンドポイント世代 1 のサーバーを動かしたままにします。素の herdr --remote workbox も、バージョンが違っていても互換性のあるリモートサーバーを動かしたままにします。停止が必要なのは世代 1 より前のサーバーを一度だけ更新するときです。対応する実行中サーバーをペインプロセスを失わず明示的に置き換えたい場合は --handoff を使います。
herdr update --handoff は Herdr 自身のアップデーターが管理するインストールにのみ適用されます。Homebrew、mise、Nix のインストールはそれぞれのパッケージマネージャーで更新されるため、そこでは herdr update は無効化されており、ライブハンドオフは実行できません。