トラブルシューティング

まずバージョンとセッション状態を確認します:

herdr -V
herdr status

OS、外側のターミナル名とバージョン、ローカルまたはリモートのどちらか、tmux を使用しているかも記録してください。

Windows で CJK IME の UI 位置がずれる、またはカーソルがちらつく

Herdr は、ConPTY ベースのマルチプレクサーによる画面再描画中にネイティブカーソルがちらついたり、ジャンプしたり、古い位置を表示したりすることを避けるため、ネイティブ Windows と WSL ではデフォルトでセル描画カーソルを使います。セル描画カーソルは、韓国語、日本語、中国語 IME の変換中テキストや候補 UI が使用するネイティブカーソルの基準位置を提供できません。

IME の変換中テキストや候補ウィンドウが誤った位置に表示される場合は、ネイティブカーソルを有効にしてください:

[ui]
host_cursor = "native"

ネイティブモードでは IME の基準位置が正しくなりますが、出力中にカーソル表示が乱れることがあります。視覚的に安定したカーソルへ戻すには host_cursor = "drawn" を設定するか、設定を削除して Windows のデフォルトを使ってください。現在の制限については Windows サポート を参照してください。

Enter、Tab、Backspace が 2 回入力される

古いターミナルでは、アプリケーションが Kitty キーボードイベント報告を有効にすると、Enter、Tab、Backspace のリリースをプレスと同じバイトとして送ることがあります。送信後は Herdr から重複したバイトを区別できません。

上流の修正を含むバージョンへ外側のターミナルを更新してください:

ターミナル	修正済みの最小バージョン
kitty	0.33.0
foot	1.20.0
Alacritty	0.15.0

長期サポート版 Linux ディストリビューションの古いターミナルパッケージで特に発生します。確認済みの境界キャプチャと上流参照は Herdr issue #1116 を参照してください。現在のターミナルでも発生する場合は、正確なバージョンと Herdr の外でも発生するかを報告してください。

Option+Left または Option+Right を押すと ;3D または ;3C が入力される

ターミナルは一般に、Alt+Left と Alt+Right を標準の修飾付き矢印シーケンス ESC[1;3D と ESC[1;3C として送信します。macOS では、まず外側のターミナルで Option を Alt として扱うよう設定する必要があります。シェルがこれらのシーケンスを割り当てていない場合、zsh は残りの文字を ;3D または ;3C と表示することがあります。これは kitty、Alacritty、その他のターミナルで発生する可能性があります。Herdr と tmux はどちらも元の修飾付き矢印入力を保持します。

すべてのターミナルとネストしたシェルで修飾付き矢印を単語移動として使う場合は、zsh のバインドを明示的に追加します:

bindkey $'\e[1;3D' backward-word
bindkey $'\e[1;3C' forward-word

kitty の外では動作するのに Herdr 内では動作しないことがあります。これは kitty の自動 zsh インテグレーションが、kitty が直接起動したシェルにだけこれらのバインドを追加し、ターミナルマルチプレクサーが起動したシェルには追加しないためです。kitty の手動シェルインテグレーション手順に従うか、シェルへ届く前に kitty.conf でキーを割り当ててください:

map alt+left send_text all \x1bb
map alt+right send_text all \x1bf

ターミナルアプリケーションが Alt+Left と Alt+Right を直接使用する場合があるため、Herdr は修飾付き矢印を意図的に書き換えません。調査の詳細は Herdr issue #1370 を参照してください。

Herdr を更新したのに実行中のセッションが古い

バイナリを更新しても、互換性のある実行中サーバーは置き換わりません。Herdr を開き直せば更新済みクライアントを使えます。サーバー側の新機能も必要な場合だけ、herdr status で確認してからセッションを停止し、Herdr を再起動します:

herdr server stop
herdr

サーバーを停止するとペインのプロセスも終了します。名前付きセッションでは herdr session stop <name> を使います。更新機能、パッケージマネージャー、ライブハンドオフについてはインストールを参照してください。

macOS の Herdr 内で Keychain を使うツールが失敗する

Herdr のペインからサーバーの起動コンテキストを確認します:

launchctl managername

自動起動された macOS サーバーでは Background は正常で、この表示だけでは Keychain の問題を意味しません。Keychain にアクセスできず、サーバーを SSH やバックグラウンドジョブから起動していた場合は、停止して通常の GUI ターミナルから Herdr を再起動してください:

herdr server stop
herdr

サーバーを停止するとペインのプロセスも終了します。Herdr のペインは長時間動作するサーバーの macOS 起動コンテキストを継承するため、SSH やバックグラウンドジョブから起動されたサーバーは対話型 Keychain サービスにアクセスできないことがあります。詳細は Herdr issue #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 を参照してください。

herdr コマンドが見つからない

ターミナルを再起動して環境を読み込み直し、Herdr のインストール先が PATH に含まれていることを確認してください。パッケージマネージャー経由のインストールは、そのパッケージマネージャーから更新して公開する必要があります。インストールを参照してください。

直接キーバインドが動作しない

OS または外側のターミナルが Herdr に届く前にキーを処理している可能性があります。そのレイヤーでキーを解放するか、別のバインドを選んでください。既知の競合と安全なデフォルトはキーボードを参照してください。

リモートアタッチで認証できない

まず ssh <host> で通常の OpenSSH 接続が動作することを確認してください。非対話シェル、CI、モバイルターミナルでパスフレーズ付きキーを使う場合は、リモートアタッチの前にキーを ssh-agent へ読み込んでください。永続化とリモートアクセスを参照してください。

診断ログを探す

Herdr のログはデフォルトで ~/.config/herdr/ にあります:

herdr.log
herdr-client.log
herdr-server.log

詳細なログには HERDR_LOG=herdr=debug を設定します。問題を報告するときは現在のログとローテーション済みログを含めてください。設定を参照してください。