fix: preserve unloaded sessions before replacement (#4190)

refs #4125

3 files changed, 12 insertions, 0 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 ed370715..b2d182b0 100644
--- a/docs/next/website/src/content/docs/ja/session-state.mdx
+++ b/docs/next/website/src/content/docs/ja/session-state.mdx
@@ -34,6 +34,10 @@ Herdr サーバーが停止して再起動すると、元のペインのプロ�
 
 スナップショット復元は、動作中のシェル、サーバー、テスト、その他任意のプロセスを保存しません。より強力な復元経路が使えないペインは、保存されたディレクトリで新しいシェルとして戻ってきます。
 
+`session.json` を読み込めない、解析できない、または新しい Herdr バージョンが必要な場合、読み込みに失敗した理由をログに記録します。新しいセッションを保存または削除する前に、元のファイルをそのまま `session.json` の隣の `session-backups/` に保存し、復旧用コピーのパスを `persist.backup` として記録します。起動時にファイルがなかった場合も、最初の保存または削除の前に再確認します。正常に読み込めた場合は復旧用コピーを作成しません。
+
+復旧用コピーは最新の 3 個を保持し、新しいコピーの安全な保存が完了してから古いコピーを削除します。コピーに失敗すると、自動保存時も終了時も元のファイルを変更せず、失敗をログに記録し、次の保存要求時に再試行します。コピーが自動的に復元されることはありません。復旧するには、対象のサーバーを停止し、復旧用ファイルをそのサーバーの `session.json` にコピーしてから再起動します。復旧用コピーにペイン画面履歴は含まれません。
+
 ## ペイン画面履歴のリプレイ
 
 ペイン画面履歴は、サーバーの完全な再起動後に直近のターミナル内容を復元します。復元されるのは Herdr が表示できるものであって、元のプロセスではありません。
diff --git a/docs/next/website/src/content/docs/session-state.mdx b/docs/next/website/src/content/docs/session-state.mdx
index 51ac8f2b..38712689 100644
--- a/docs/next/website/src/content/docs/session-state.mdx
+++ b/docs/next/website/src/content/docs/session-state.mdx
@@ -32,6 +32,10 @@ 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.
+
+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.
+
 ## Pane screen history replay
 
 Pane screen history restores recent terminal contents after a full server restart without restoring the old process.
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 b4f955c6..9747e2b6 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,6 +34,10 @@ herdr
 
 快照恢复不会保留运行中的 shell、服务器、测试或任意进程。无法使用更强恢复路径的窗格,会在各自保存的目录中作为新 shell 回来。
 
+如果无法读取或解析 `session.json`，或该文件需要更新的 Herdr 版本，Herdr 会记录加载失败的原因。在保存或清除新会话之前，Herdr 会将原始文件逐字节保存到 `session.json` 旁的 `session-backups/` 中，并通过 `persist.backup` 记录恢复副本的路径。即使启动时文件不存在，也会在首次保存或清除前再次检查。正常加载的会话不会创建恢复副本。
+
+Herdr 保留最新的三个恢复副本，只有在新副本安全写入后才删除旧副本。如果无法保存副本，自动保存和退出保存都不会修改原始文件，并会记录错误，在下一次保存请求时重试。副本不会自动恢复。如需恢复，请停止对应的服务器，将恢复文件复制到该服务器的 `session.json`，然后重启。恢复副本不包含窗格屏幕历史。
+
 ## 窗格屏幕历史回放
 
 窗格屏幕历史在服务器完全重启后恢复最近的终端内容。它恢复的是 Herdr 能展示的内容,而不是原来的进程。