fix: preserve session layouts across shutdown and restore failures (#4400)

* fix: preserve session layouts across shutdown and restore failures

refs #4320

* test: update subscription fixture for pane restore errors

---------

Co-authored-by: JJ Liebig <jonathan.liebig@gmail.com>

3 files changed, 66 insertions, 3 deletions

diff --git a/docs/next/website/src/content/docs/ja/session-state.mdx b/docs/next/website/src/content/docs/ja/session-state.mdx
index 006ba439..4f16bda6 100644
--- a/docs/next/website/src/content/docs/ja/session-state.mdx
+++ b/docs/next/website/src/content/docs/ja/session-state.mdx
@@ -34,10 +34,29 @@ Herdr サーバーが停止して再起動すると、元のペインのプロ�
 
 スナップショット復元は、動作中のシェル、サーバー、テスト、その他任意のプロセスを保存しません。より強力な復元経路が使えないペインは、保存されたディレクトリで新しいシェルとして戻ってきます。
 
-`session.json` を読み込めない、解析できない、または新しい Herdr バージョンが必要な場合、読み込みに失敗した理由をログに記録します。新しいセッションを保存または削除する前に、元のファイルをそのまま `session.json` の隣の `session-backups/` に保存し、復旧用コピーのパスを `persist.backup` として記録します。起動時にファイルがなかった場合も、最初の保存または削除の前に再確認します。正常に読み込めた場合は復旧用コピーを作成しません。
+保存されたディレクトリが使えない場合やシェルを起動できない場合、ペインは消えたりホームディレクトリへ移動したりせず、エラーを表示してレイアウトに残ります。保存されたディレクトリとエージェントのセッション参照は保持されます。ディレクトリやシェル設定を修正してサーバーを再起動すると再試行できます。不要なペインは明示的に閉じて削除できます。
+
+保存時には、OS が取得をサポートしていれば、実行中のシェルのディレクトリを優先します。シェル終了後も最後に確認したディレクトリを保持します。それ以外の環境ではシェルが報告したディレクトリを使用します。
+
+`session.json` を読み込めない、解析できない、または新しい Herdr バージョンが必要な場合、読み込みに失敗した理由をログに記録します。新しいセッションを保存または削除する前に、元のファイルをそのまま `session.json` の隣の `session-backups/` に保存し、復旧用コピーのパスを `persist.backup` として記録します。起動時にファイルがなかった場合も、最初の保存または削除の前に再確認します。これらの読み込み失敗時の復旧用コピーは、通常のスナップショット履歴とは別に管理します。
 
 復旧用コピーは最新の 3 個を保持し、新しいコピーの安全な保存が完了してから古いコピーを削除します。コピーに失敗すると、自動保存時も終了時も元のファイルを変更せず、失敗をログに記録し、次の保存要求時に再試行します。コピーが自動的に復元されることはありません。復旧するには、対象のサーバーを停止し、復旧用ファイルをそのサーバーの `session.json` にコピーしてから再起動します。復旧用コピーにペイン画面履歴は含まれません。
 
+## シャットダウンとスナップショットからの復旧
+
+systemd-logind を使う Linux では、Herdr はホストのシャットダウン予告を受け取り、保存して停止するまで短い遅延を要求します。その後 logind がシャットダウンを進めます。遅延には OS による上限があり、無期限にはブロックしません。logind がない環境、強制終了、電源断、予告前にプロセスが終了した場合には、この保護は使えません。
+
+全プラットフォームで、`session.json` の隣の `session-snapshots/` に最大 48 個のレイアウトスナップショットを保持します。最初に保存したレイアウトは直ちにコピーします。その後の保存や削除では、直前の保存済みレイアウトを最大 15 分に 1 回コピーします。同じ内容は重複保存しません。この間隔はサーバーの再起動後も維持されるため、連続したペイン終了や再起動で古いコピーがすべて押し出されることはありません。直近の変更がコピーに含まれない場合があります。
+
+通常のペイン終了は引き続き `session.json` に反映されます。復旧を促す通知や、古いスナップショットの自動復元はありません。手動で復旧するには:
+
+1. `herdr session list --json` で対象のセッションディレクトリを確認します。
+2. 対象サーバーを停止します。デフォルトは `herdr server stop`、名前付きセッションは `herdr session stop <name>` です。
+3. 現在の `session.json` を別にコピーしてから、`session-snapshots/` 内の選んだファイルを `session.json` にコピーします。ファイルの更新日時で保存時刻を確認できます。
+4. セッションを再起動します。
+
+コピーにはレイアウトとエージェントのセッション参照が含まれますが、実行中のプロセスやペイン画面履歴は含まれません。非公開のセッションデータとして扱ってください。コピーの書き込みに失敗するとログに記録しますが、通常のセッション保存は続行します。
+
 ## ペイン画面履歴のリプレイ
 
 ペイン画面履歴は、サーバーの完全な再起動後に直近のターミナル内容を復元します。復元されるのは Herdr が表示できるものであって、元のプロセスではありません。
@@ -51,6 +70,8 @@ pane_history = true
 
 有効にすると、Herdr は保存したペイン履歴を `session.json` の隣の `session-history.json` に保存します。Herdr の設定/セッションディレクトリはターミナル履歴と同じ感覚で扱ってください。
 
+履歴は、保存されたレイアウトと完全に一致する場合だけ再生されます。スナップショットを手動で復元した場合など、異なるレイアウトの履歴は無視されます。レイアウトを検証できない旧形式の履歴も無視されますが、新たに保存された履歴は次回の再起動で再生できます。
+
 ## エージェントネイティブのセッション復元
 
 一部のエージェントは自分の会話セッションを resume できます。Herdr は、公式インテグレーションが報告したセッション参照を使って、Herdr サーバーの再起動後に対応エージェントのペインを再起動できます。
diff --git a/docs/next/website/src/content/docs/session-state.mdx b/docs/next/website/src/content/docs/session-state.mdx
index fd065483..b8706cd5 100644
--- a/docs/next/website/src/content/docs/session-state.mdx
+++ b/docs/next/website/src/content/docs/session-state.mdx
@@ -32,10 +32,29 @@ If the Herdr server stops and starts again, the original pane processes are gone
 
 Snapshot restore does not preserve running shells, servers, tests, or arbitrary processes. Panes that cannot use a stronger restore path come back as new shells in their saved directories.
 
-If `session.json` cannot be read or parsed, or requires a newer Herdr version, Herdr logs why loading failed. Before saving or clearing the replacement session, it preserves the original bytes in `session-backups/` beside `session.json` and logs the recovery path as `persist.backup`. A file missing at startup is checked again before the first save or clear. Healthy restores do not create recovery copies.
+If a saved directory is unavailable or the shell cannot start, the pane stays in the layout with an error instead of disappearing or moving to your home directory. Its saved directory and agent session reference remain intact. Fix the directory or shell configuration and restart the server to retry, or explicitly close the pane to remove it.
+
+When saving, Herdr prefers the live shell's directory where the operating system exposes it, and retains the last confirmed directory after the shell exits. Shell-reported directories remain the fallback on other platforms.
+
+If `session.json` cannot be read or parsed, or requires a newer Herdr version, Herdr logs why loading failed. Before saving or clearing the replacement session, it preserves the original bytes in `session-backups/` beside `session.json` and logs the recovery path as `persist.backup`. A file missing at startup is checked again before the first save or clear. These failed-load recovery copies are separate from normal snapshot history.
 
 Herdr retains the three most recent recovery copies, pruning older copies only after a new copy is safely written. If preservation fails, autosave and shutdown leave the original untouched and log the failure; preservation is retried on the next save request. Copies are never restored automatically. To recover one, stop the affected server, copy the recovery file over its `session.json`, then restart. Recovery copies do not include pane screen history.
 
+## Shutdown and snapshot recovery
+
+On Linux systems with systemd-logind, Herdr listens for the host shutdown warning and requests a short delay while it saves and stops. This happens before logind proceeds with shutdown. The operating system limits the delay; Herdr does not block shutdown indefinitely. This protection is unavailable without logind and does not cover forced shutdown, power loss, or processes killed before the warning arrives.
+
+Herdr also keeps up to 48 layout snapshots in `session-snapshots/` beside `session.json`, on all platforms. The first saved layout is copied immediately. Later saves or clears can add a snapshot of the previous saved layout, at most once every 15 minutes. Unchanged snapshots are not duplicated. The interval survives server restarts, so a burst of pane exits or restarts cannot rotate away all older layouts. Recent changes may not be in the recovery snapshots.
+
+Normal pane closures still update `session.json`. There are no recovery prompts and no automatic restoration of older snapshots. To recover a layout:
+
+1. Find the affected session directory with `herdr session list --json`.
+2. Stop that server (`herdr server stop` for the default session, or `herdr session stop <name>` for a named session).
+3. Keep a copy of its current `session.json`, then copy the chosen file from `session-snapshots/` over `session.json`. File modification times identify when snapshots were taken.
+4. Start the session again.
+
+Snapshots contain layout and agent session references, not running processes or pane screen history. Treat them as private session data. A snapshot-write failure is logged but does not prevent the primary session from saving.
+
 ## Pane screen history replay
 
 Pane screen history restores recent terminal contents after a full server restart without restoring the old process.
@@ -49,6 +68,8 @@ pane_history = true
 
 When enabled, Herdr stores saved pane history in `session-history.json` next to `session.json`. Treat the Herdr config/session directory like terminal history.
 
+History is replayed only when it matches the exact saved layout. History from a different layout, including after manual snapshot recovery, is ignored. Older history files without layout verification are also ignored; newly saved history can be replayed on the next restart.
+
 ## Native agent session restore
 
 Some agents can resume their own conversation sessions. Herdr can use official integration-reported session references to restart supported agent panes after a Herdr server restart.
diff --git a/docs/next/website/src/content/docs/zh-cn/session-state.mdx b/docs/next/website/src/content/docs/zh-cn/session-state.mdx
index c4c4a387..9be84060 100644
--- a/docs/next/website/src/content/docs/zh-cn/session-state.mdx
+++ b/docs/next/website/src/content/docs/zh-cn/session-state.mdx
@@ -34,10 +34,29 @@ herdr
 
 快照恢复不会保留运行中的 shell、服务器、测试或任意进程。无法使用更强恢复路径的窗格,会在各自保存的目录中作为新 shell 回来。
 
-如果无法读取或解析 `session.json`，或该文件需要更新的 Herdr 版本，Herdr 会记录加载失败的原因。在保存或清除新会话之前，Herdr 会将原始文件逐字节保存到 `session.json` 旁的 `session-backups/` 中，并通过 `persist.backup` 记录恢复副本的路径。即使启动时文件不存在，也会在首次保存或清除前再次检查。正常加载的会话不会创建恢复副本。
+如果保存的目录不可用或 shell 无法启动,窗格会留在布局中并显示错误,而不是消失或切换到主目录。保存的目录和智能体会话引用仍会保留。修复目录或 shell 配置后,重启服务器即可重试;也可以明确关闭窗格将其移除。
+
+保存时,如果操作系统支持查询,Herdr 会优先使用正在运行的 shell 的目录,并在 shell 退出后保留最后确认的目录。在其他平台上,则使用 shell 报告的目录。
+
+如果无法读取或解析 `session.json`，或该文件需要更新的 Herdr 版本，Herdr 会记录加载失败的原因。在保存或清除新会话之前，Herdr 会将原始文件逐字节保存到 `session.json` 旁的 `session-backups/` 中，并通过 `persist.backup` 记录恢复副本的路径。即使启动时文件不存在，也会在首次保存或清除前再次检查。这些加载失败时的恢复副本与常规快照历史分开管理。
 
 Herdr 保留最新的三个恢复副本，只有在新副本安全写入后才删除旧副本。如果无法保存副本，自动保存和退出保存都不会修改原始文件，并会记录错误，在下一次保存请求时重试。副本不会自动恢复。如需恢复，请停止对应的服务器，将恢复文件复制到该服务器的 `session.json`，然后重启。恢复副本不包含窗格屏幕历史。
 
+## 关机与快照恢复
+
+在使用 systemd-logind 的 Linux 系统上，Herdr 会监听主机关机预告，并请求短暂延迟，以便保存并停止服务器，随后 logind 才继续关机。延迟由操作系统限制，不会无限阻止关机。此保护不适用于没有 logind 的系统、强制关机、断电，或进程在预告到达前已被终止的情况。
+
+在所有平台上，Herdr 还会在 `session.json` 旁的 `session-snapshots/` 中保留最多 48 个布局快照。首次保存的布局会立即复制。之后的保存或清除操作会复制之前保存的布局，最多每 15 分钟一次，不重复保存相同内容。此间隔在服务器重启后仍然有效，因此连续的窗格退出或重启不会挤掉所有旧快照。最近的更改可能尚未包含在快照中。
+
+正常关闭窗格仍会更新 `session.json`，不会出现恢复提示，也不会自动恢复旧布局。如需手动恢复：
+
+1. 用 `herdr session list --json` 找到对应的会话目录。
+2. 停止对应的服务器：默认会话用 `herdr server stop`，命名会话用 `herdr session stop <name>`。
+3. 先另存当前的 `session.json`，再将 `session-snapshots/` 中选定的文件复制到 `session.json`。文件修改时间表示快照的保存时间。
+4. 重新启动该会话。
+
+快照包含布局和代理会话引用，不包含运行中的进程或窗格屏幕历史。请将其视为私密会话数据。快照写入失败会记录到日志，但不会阻止主会话文件的正常保存。
+
 ## 窗格屏幕历史回放
 
 窗格屏幕历史在服务器完全重启后恢复最近的终端内容。它恢复的是 Herdr 能展示的内容,而不是原来的进程。
@@ -51,6 +70,8 @@ pane_history = true
 
 开启后,Herdr 把保存的窗格历史存放在 `session.json` 旁边的 `session-history.json` 中。请像对待终端历史一样对待 Herdr 的配置/会话目录。
 
+只有与保存的布局完全匹配的历史才会回放。来自其他布局的历史,包括手动恢复快照后不再匹配的历史,都会被忽略。无法验证布局的旧版历史文件也会被忽略;新保存的历史可在下次重启时回放。
+
 ## 智能体原生会话恢复
 
 一些智能体可以恢复它们自己的对话会话。Herdr 可以使用官方集成上报的会话引用,在 Herdr 服务器重启后重新启动受支持的智能体窗格。