herdr-throwaway-repro

Herdr 使い捨て再現

再現に実際の Herdr サーバー、ペイン、PTY、エージェント、またはソケット API が必要で、ユーザーのメインセッションを危険にさらしたくない場合は、使い捨ての名前付き Herdr セッションを使用してください。

一時的な TUI は、使い捨てセッションをアタッチしたままにし、ターミナルのジオメトリを提供するだけです。再現は、Herdr の CLI/API を通じて親セッションから操作します。バグがクライアント入力を特に必要としない限り、ネストされた TUI を手動で操作しないでください。

譲れない安全事項

• 再現をデフォルトセッションで実行しないでください。
• メインの Herdr サーバーを停止、再起動、削除、または強制終了しないでください。
• クリーンアップに pkill、広範なプロセスマッチング、または推測した PID を使用しないでください。
• 一意のセッション名を作成してください。無関係な名前付きセッションを再利用または削除しないでください。
• 新しい外側のペインを作成し、クリーンアップ中はそのペインのみを閉じてください。
• ワークスペース、タブ、ペイン、ターミナル、およびエージェントの ID はコマンド出力から読み取ってください。決して自分で構築しないでください。
• 再現ディレクトリおよび大きくなる可能性のある成果物には /var/tmp を使用してください。
• 破壊的または不要なエージェントのアクションを承認しないでください。
• ユーザーの承認なしに有料のエージェントトークンを消費しないでください。要求された低コストモデルと、最小限で有用なプロンプトを使用してください。

まずインストールされているインターフェースを確認する

インストールされているバイナリが権威です。このスキルが書かれてから CLI 構文が変更されている可能性があります。

呼び出し元が Herdr 内にいることを確認し、何かを行う前に関連するヘルプを調べてください:

test "${HERDR_ENV:-}" = 1
herdr --version
herdr --help
herdr session
herdr pane
herdr agent

使い慣れていない、または変更を加える可能性のあるコマンドを使用する前に、ネストされたコマンドのヘルプを調べてください。herdr を素で実行して発見しようとしないでください。TUI が起動またはアタッチされるためです。

再現がテストする Herdr バイナリとバージョンを記録してください。チェックアウトビルドをテストする場合は、インストールされているバイナリを黙って代用するのではなく、そのビルドを実行するためのリポジトリの指示に従ってください。

外側のペインを作成する

フォーカスを移動せずに、現在のタブに兄弟シェルペインを作成します。ハーネスが提供する場合は、利用可能な Herdr レイアウトツールを使用してください。そうでない場合は、インストールされているペイン分割コマンドのヘルプを確認したうえで使用してください。

新しいペインの cwd として /var/tmp または専用の再現ディレクトリを使用してください。返された外側のペイン ID を保存してください。これは、クリーンアップが閉じることができる唯一の親セッションペインです。

使い捨てセッションを起動する

repro-<topic>-<timestamp> のような短く一意な名前を選択してください。

起動する前に、使い捨てクライアントが実際に読み込む設定でネストを明示的に許可してください。HERDR_ENV=1 は外側のペインから継承されるため、[experimental].allow_nested が有効になっていない限り、起動は拒否されます。分離された XDG_CONFIG_HOME は、たとえそこでネストが有効になっていても、ユーザーのグローバル設定からこの設定を継承しません。

ファイル書き込みツールを使用して、再現ディレクトリの下にテスト専用の設定を作成してください。デフォルト設定での再現の場合、その内容は次のとおりです。

[experimental]
allow_nested = true

ユーザーの設定で再現する場合は、その設定をテストディレクトリにコピーし、既存の [experimental] テーブルで allow_nested を有効にしてください（テーブルが存在しない場合は追加してください）。テーブルやキーを重複して作成しないでください。再現を許可するためにユーザーのグローバル設定を編集しないでください。また、ネストのチェックを回避するために HERDR_ENV を unset しないでください。

以下で起動する際に、テスト設定の絶対パスを HERDR_CONFIG_PATH として渡してください。設定の検証や、テスト設定を読み込む必要があるすべてのコマンドでも同じオーバーライドを使用してください。このオーバーライドは設定ファイルを選択するものであり、保存されたマシンカタログやその他のグローバル状態を分離するものではありません。再現によって保存されたマシンが変更される場合は、テスト専用の XDG_CONFIG_HOME と XDG_STATE_HOME も併せて使用し、そのテスト環境を扱うすべてのコマンドでこれらのオーバーライドを維持してください。

新しい外側のペイン内で、名前付きセッションを実行してください。継承されたセッション選択、ソケットのオーバーライド、および呼び出し元 ID をクリアして、ネストされたランタイムが誤って親セッションを対象にできないようにしてください。

env \
  -u HERDR_SOCKET_PATH \
  -u HERDR_CLIENT_SOCKET_PATH \
  -u HERDR_SESSION \
  -u HERDR_WORKSPACE_ID \
  -u HERDR_TAB_ID \
  -u HERDR_PANE_ID \
  HERDR_CONFIG_PATH=<absolute-test-config-path> \
  herdr --session <session-name>

必要に応じて、この起動コマンドに再現固有の環境変数を追加してください。サーバーを構成する環境変数は、名前付きサーバーが起動する前に設定されている必要があります。

起動する前に、同じ設定オーバーライドを使用して herdr config check でテスト設定を検証してください。起動後は、外側のペインを読んで nested herdr is disabled by default などの起動エラーを検出してください。pane run が成功を返したという理由だけで、起動が成功したとみなさないでください。

名前付きセッションの API が準備完了になるまで続行しないでください。親からそのセッションを対象にしてペインを一覧表示することで、準備完了を確認してください。

使い捨てセッションのみを対象にする

親から発行されるすべての制御コマンドは、継承されたソケットのオーバーライドをクリアし、一時セッションを明示的に選択する必要があります。

env \
  -u HERDR_SOCKET_PATH \
  -u HERDR_CLIENT_SOCKET_PATH \
  -u HERDR_WORKSPACE_ID \
  -u HERDR_TAB_ID \
  -u HERDR_PANE_ID \
  HERDR_SESSION=<session-name> \
  herdr pane list

すべてのコマンドでこのプレフィックスを繰り返してください。ツール呼び出しの間でシェルの状態が持続することに依存しないでください。

pane list から使い捨てルートペイン ID を読み取ってください。そこで何かを開始する前に、その cwd とフォアグラウンドプロセスを確認してください。

名前付きセッションは、ランタイム状態、ソケット、ペイン、および永続化を分離します。ただし、デフォルトではグローバルの Herdr 設定とエージェントマニフェストのオーバーライドは引き続き共有します。再現に影響を与える可能性がある場合は、設定の由来を確認してください。テストに合格させるためだけに共有設定を変更しないでください。

API を通じて再現を実行する

シェルや通常のプロセスにはペインコマンドを使用します。

• pane run で、利用可能なシェルプロンプトでコマンドを開始します。
• pane wait-output で、決定論的な出力を待機します。
• pane read で、ターミナルの内容をキャプチャします。
• pane send-text で、リテラル入力を送信します。
• pane send-keys で、サポートされているキーを送信します。
• pane get、pane process-info、pane layout で、実行時の状態を取得します。

Herdr がコーディングエージェントを認識した後にのみ、エージェントコマンドを使用します。

• agent start で、既存のシェルペインでサポートされているエージェントを起動します。
• agent prompt で、1 つのプロンプトをアトミックに送信します。
• agent wait で、working、blocked、idle、done、または unknown を待機します。
• agent read で、エージェントのターミナルをキャプチャします。
• agent get と agent explain で、状態と検出を検査します。
• agent send-keys で、対話的な応答を送信します。

名前やオプションは変更される可能性があるため、まず該当するコマンドグループのヘルプを実行してください。

任意のスリープよりも待機を優先してください。タイミング自体がテスト対象である場合は、タイムスタンプを記録し、上限付きのポーリングを使用します。再現対象の遷移の前、最中、後に状態をキャプチャします。

必要なターミナルキーが高レベルのコマンドでサポートされていない場合は、対象アプリケーションの期待されるキーを確認した後にのみ、使い捨てのペインを通じてそのターミナルシーケンスを送信してください。親ペインに生の制御シーケンスを送信しないでください。

エージェントを慎重に起動する

エージェントを起動する前に、インストールされているその --version と --help を検査します。ネイティブのエージェント引数は、Herdr の引数セパレーターの後に渡します。

ユーザーが要求または承認した正確なモデルを使用します。エイリアスを信用するのではなく、ライブのエージェント画面からモデルを確認します。エージェントがサポートしている場合は、ベースラインとして低エフォート、セーフモード、手動パーミッションを優先します。疑わしい動作がフック、プラグイン、または設定に依存する場合にのみ、ユーザーの実際の構成で繰り返します。

パーミッション状態のテストには無害な操作を使用します。証拠をキャプチャした後に保留中のアクションを拒否し、成果物が作成されていないことを確認します。

有用な証拠を収集する

他の人が結果を再現できるだけの情報を記録します。

• Herdr バイナリとバージョン。
• 名前付きセッションと起動環境。
• 対象アプリケーションまたはエージェントのバージョンと引数。
• 正確なコマンドまたはプロンプト。
• 各遷移の前後におけるペインとエージェントの状態。
• 関連する pane read、agent read、agent explain、API 出力、およびセッションログ。
• グローバル設定またはローカルマニフェストのオーバーライドが有効であったかどうか。

名前付きセッションのディレクトリとソケットは、パスを仮定するのではなく、herdr session list から読み取ります。ユーザーが別の場所に保存するよう求めない限り、大きな証拠は /var/tmp の下に保管します。

観察された事実と提唱された原因を区別します。まず標準の動作を再現し、その後で一度に 1 つの変数だけを変更します。

クリーンアップ

クリーンアップは、失敗後の場合も含め、再現の一部です。

1. 保留中のプロンプトを拒否し、実用的な場合はテストアプリケーションをクリーンに停止します。
2. 無害なプローブファイルやその他のテスト成果物が存在しないことを確認するか、この再現で作成された成果物のみを削除します。
3. インストールされているセッションコマンドで、一時的な名前付きセッションを停止します。
4. 停止したその同じセッションを削除します。
5. それが実行中として表示されなくなったことを確認します。
6. 外側のペインがシェルに戻るのを待機します。
7. このワークフローで作成された外側のペインのみを閉じます。

古く見えるという理由で別の名前付きセッションを削除しないでください。現在のエージェントを実行しているペインや、再現のために作成されていないペインは決して閉じないでください。

結果を報告する

何が再現し、何が再現しなかったか、および失敗した正確な遷移を述べます。クリーンアップの状況を含めます。結果に影響を与えた可能性のある共有設定またはマニフェストのオーバーライドについて言及します。