fix: preserve macos services across logout (#4202)

refs #4100

3 files changed, 27 insertions, 3 deletions

diff --git a/docs/next/website/src/content/docs/ja/troubleshooting.mdx b/docs/next/website/src/content/docs/ja/troubleshooting.mdx
index a170b0b1..345d8a99 100644
--- a/docs/next/website/src/content/docs/ja/troubleshooting.mdx
+++ b/docs/next/website/src/content/docs/ja/troubleshooting.mdx
@@ -78,7 +78,7 @@ Herdr のペインからサーバーの起動コンテキストを確認しま�
 launchctl managername
 ```
 
-`Background` と表示された場合は、サーバーを停止し、通常の GUI ターミナルから Herdr を再起動してください:
+自動起動された macOS サーバーでは `Background` は正常で、この表示だけでは Keychain の問題を意味しません。Keychain にアクセスできず、サーバーを SSH やバックグラウンドジョブから起動していた場合は、停止して通常の GUI ターミナルから Herdr を再起動してください:
 
 ```bash
 herdr server stop
@@ -87,6 +87,14 @@ herdr
 
 サーバーを停止するとペインのプロセスも終了します。Herdr のペインは長時間動作するサーバーの macOS 起動コンテキストを継承するため、SSH やバックグラウンドジョブから起動されたサーバーは対話型 Keychain サービスにアクセスできないことがあります。詳細は [Herdr issue #966](https://github.com/herdrdev/herdr/issues/966) を参照してください。
 
+## macOS のログアウト後に SSH や DNS が失敗する
+
+自動起動された macOS サーバーはユーザー単位のサービスコンテキストを使用するため、ログアウトしてもペインと macOS サービスの接続が無効になりません。明示的な `herdr server` 起動では、呼び出し元のコンテキストを維持します。
+
+古いサーバーはログアウト後も動作し続ける一方、ユーザー情報の検索や DNS が使えなくなることがあります。症状には `No user exists for uid 501`、`Could not get manager name.`、`curl: (6) Could not resolve host` などがあります。再ログインだけでは修復されません。対象セッションを停止し、新しいログインの GUI ターミナルから Herdr を起動してください。実行中のペインプロセスは終了しますが、保存されたセッション配置は復元されます。ライブハンドオフは元のサーバーのサービスコンテキストと既存のペインプロセスを維持します。そのため、古いサーバーにこの修正を適用するにはセッションの完全な再起動が必要です。ハンドオフでは継承したコンテキストを修復できません。
+
+新しく起動したサーバーでも問題が起きる場合は、`herdr-server.log` の `could not select persistent user service context` を確認してください。必要な macOS API が利用できない場合、Herdr は継承したコンテキストを維持します。[Herdr issue #4100](https://github.com/herdrdev/herdr/issues/4100) を参照してください。
+
 ## `herdr` コマンドが見つからない
 
 ターミナルを再起動して環境を読み込み直し、Herdr のインストール先が `PATH` に含まれていることを確認してください。パッケージマネージャー経由のインストールは、そのパッケージマネージャーから更新して公開する必要があります。[インストール](/ja/docs/install/#verify)を参照してください。
diff --git a/docs/next/website/src/content/docs/troubleshooting.mdx b/docs/next/website/src/content/docs/troubleshooting.mdx
index 69e65110..e7225893 100644
--- a/docs/next/website/src/content/docs/troubleshooting.mdx
+++ b/docs/next/website/src/content/docs/troubleshooting.mdx
@@ -78,7 +78,7 @@ Check the server launch context from a Herdr pane:
 launchctl managername
 ```
 
-If it prints `Background`, stop the server and start Herdr again from a normal GUI terminal:
+`Background` is normal for automatically started macOS servers and does not by itself indicate a Keychain problem. If Keychain access fails and the server was started through SSH or a background job, stop it and start Herdr again from a normal GUI terminal:
 
 ```bash
 herdr server stop
@@ -87,6 +87,14 @@ herdr
 
 Stopping the server exits its pane processes. Herdr panes inherit the long-lived server's macOS launch context, so a server started through SSH or a background job may not have access to interactive Keychain services. See [Herdr issue #966](https://github.com/herdrdev/herdr/issues/966) for details.
 
+## SSH or DNS fails after macOS logout
+
+Automatically started macOS servers use a per-user service context so logging out does not leave their panes with a dead connection to macOS services. Explicit `herdr server` launches retain their caller's context.
+
+An older server can survive logout while losing user lookup and DNS. Symptoms include `No user exists for uid 501`, `Could not get manager name.`, and `curl: (6) Could not resolve host`. Logging back in does not repair that server. Stop the affected session and start Herdr from a GUI terminal in the new login. This ends live pane processes but restores the saved session layout. Live handoff preserves the source server's service context and existing pane processes. Older servers therefore need a full session restart to adopt this fix; handoff cannot repair their inherited context.
+
+If a newly started server still has this problem, check `herdr-server.log` for `could not select persistent user service context`. Herdr keeps the inherited context if the required macOS APIs are unavailable. See [Herdr issue #4100](https://github.com/herdrdev/herdr/issues/4100).
+
 ## The `herdr` command is not found
 
 Restart the terminal so it reloads its environment, then confirm the Herdr install directory is on `PATH`. For package-manager installs, use that package manager to update Herdr and expose it on `PATH`. See [Install Herdr](/docs/install/#verify).
diff --git a/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx b/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx
index fe828a02..3d25e9e1 100644
--- a/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx
+++ b/docs/next/website/src/content/docs/zh-cn/troubleshooting.mdx
@@ -78,7 +78,7 @@ herdr
 launchctl managername
 ```
 
-如果输出为 `Background`，请停止服务器，然后从普通 GUI 终端重新启动 Herdr:
+自动启动的 macOS 服务器显示 `Background` 是正常的，不能仅凭此判断钥匙串访问有问题。如果钥匙串访问失败，且服务器是通过 SSH 或后台任务启动的，请停止服务器，然后从普通 GUI 终端重新启动 Herdr:
 
 ```bash
 herdr server stop
@@ -87,6 +87,14 @@ herdr
 
 停止服务器会结束窗格进程。Herdr 窗格会继承长期运行服务器的 macOS 启动上下文，因此通过 SSH 或后台任务启动的服务器可能无法访问交互式钥匙串服务。详情见 [Herdr issue #966](https://github.com/herdrdev/herdr/issues/966)。
 
+## macOS 注销后 SSH 或 DNS 失败
+
+自动启动的 macOS 服务器使用用户级服务上下文，避免注销后窗格与 macOS 服务的连接失效。显式运行 `herdr server` 时仍会保留调用方的上下文。
+
+旧服务器可能在注销后继续运行，但无法查询用户信息或解析 DNS。症状包括 `No user exists for uid 501`、`Could not get manager name.` 和 `curl: (6) Could not resolve host`。重新登录不能修复该服务器。请停止受影响的会话，然后从新登录会话的 GUI 终端启动 Herdr。这会结束正在运行的窗格进程，但会恢复保存的会话布局。实时移交会保留源服务器的服务上下文和现有窗格进程。因此，旧服务器需要完全重启会话才能应用此修复；移交无法修复继承的上下文。
+
+如果新启动的服务器仍出现此问题，请在 `herdr-server.log` 中查找 `could not select persistent user service context`。所需的 macOS API 不可用时，Herdr 会保留继承的上下文。详情见 [Herdr issue #4100](https://github.com/herdrdev/herdr/issues/4100)。
+
 ## 找不到 `herdr` 命令
 
 重启终端以重新加载环境，然后确认 Herdr 安装目录位于 `PATH` 中。通过软件包管理器安装的 Herdr 必须通过该管理器更新并加入环境。见[安装 Herdr](/zh-cn/docs/install/#verify)。