pylot-cli

実行モードを選択する

人間が確認しながら進める作業は、ミッションではなく devbox で行います。ミッションは、自律的に実行するオペレーターの実行（cron、auto-pylot、スキルにルーティングされたタスク）です。

devbox は既定で隔離された環境であるため、Git worktree は必要ありません。devbox の通常のリポジトリチェックアウトで作業し、その中に worktree を作成しないでください。そこで意図するブランチとベースを選び、既存の変更を保持して、そのチェックアウトでアプリケーションとテストを検証します。ブランチの切り替えでアプリのサービスが中断した場合は、別のチェックアウトを作成せず、文書化された devbox のライフサイクルに沿って復旧してください。

• 作業の契約が、ワーカーがその場での指示なしに実行、レビュー、報告できる程度に整っている場合は、自律型ミッションを使用します。ディスパッチしたら、実装の反復はファクトリーに任せます。
• 作業にリアルタイムの選択、反復的な診断、ワーカー間の引き継ぎ、または頻繁なユーザーの指示が本当に必要な場合は、インタラクティブ devboxを使用します。アクティブなセッションがプロンプト、検証、スナップショット、シャットダウンを管理します。
• インタラクティブだからといって、継続的に指示を出す必要はありません。選択したスキルやランナーが通常のフェーズを進められるよう、自己完結したプロンプトを 1 つ用意し、質問、失敗、または結果が返るまで待ってから指示を追加してください。
• 進捗を確認できるという理由だけで、自律型ミッションをインタラクティブに変更しないでください。定期的に実行するミッションに指示が必要な場合は、そのケースを処理すべきファクトリーのスキルを改善してください。

新しい外部クラウドセッションを認証する

device-auth broker は、環境設定で PYLOT_API_TOKEN としてバインドされた永続的な共有シークレット pdab_… を使い、使い捨ての外部クラウドセッションを認証します。登録は、サインイン済みのマシンで pylot auth broker enroll を実行し、公式デバイス承認を 1 回監督下で行うことで完了します。その後、このバインディングを使用するセッションは自動的に認証されるため、各セッションで pylot auth login を実行したり、~/.pylot/credentials ディレクトリをコピーしたりする必要はありません。ブローカーは許可情報をサーバー側で保持して更新します。30 日間更新に成功しない場合は、再登録が必要です。

これは、heartbeat と Git トークンの発行に制限されたミッション／ワーカー用ブローカー JWT である PYLOT_BROKER_TOKEN とは異なります。PYLOT_API_TOKEN にはほかの種類のトークンも格納できます。device-auth broker のルールを適用する前に、変数の内容ではなく、安全な ID 応答を確認してください。常にセッション JWT だと決めつけないでください。

リポジトリを操作する前に、意図するゲートウェイと組織を明示して使用してください。

pylot --version
pylot auth broker --help   # proxy-injected cloud broker workflows require CLI 0.9.20+
pylot --url https://hooks.fellowship.dev --org <org> auth status
pylot --url https://hooks.fellowship.dev --org <org> devboxes projects
pylot --url https://hooks.fellowship.dev --org <org> devboxes project <org/repo>
pylot --url https://hooks.fellowship.dev --org <org> devboxes list <org/repo>

このブローカーでは、auth status に type: device_broker と、環境バインディングがある場合は _cli.tokenSource: PYLOT_API_TOKEN が表示されます。意図する組織に権限が付与されていることを確認してから、必要なネイティブ読み取りを個別に検証してください。ID 応答には org: null の組織が複数表示されることがありますが、それだけでは、後続のリクエストで正しい組織が選択されることや、そのルートへの権限があることの証明にはなりません。リポジトリ名を推測せず、ディスカバリーから実際のプロジェクト識別子を解決してください。

管理対象のクラウドでは、サポートされている認証情報の準備状況を確認し、引き継がれたプロキシ、TLS の信頼設定、認証ガードを保持してください。バインドされた変数には、実際のシークレットではなくプロキシのプレースホルダーが含まれている場合があります。これを表示したり、認証情報ファイルを調べたり、コピーした認証情報で置き換えたりしないでください。生のトークンが見えないというだけで、インタラクティブなログインを開始しないでください。

ブローカーには、組織スコープの読み取りと devbox／ワーカー操作のための明示的なエンドポイント許可リストがあります。付与されたスコープが、すべてのゲートウェイルートを認可するわけではありません。次の失敗は、それぞれ区別してください。

• broker_org_required：対象の org を選択してください。明示的に --org を指定しても解消しない場合は、セレクターの転送失敗として報告してください。ログインを繰り返さないでください。
• broker_route_not_allowed：その操作はブローカーの現在の許可リストに含まれていません。その操作を中止し、必要な機能を報告してください。個人用の認証情報に黙って切り替えないでください。
• broker_reauth_required、broker_grant_revoked、または broker_secret_revoked：サインイン済みのマシンで、所有者とともにサーバー固有の復旧ヒントに従ってください。ブローカーの管理（status、revoke、rotate-secret）には個人ログインが必要です。ブローカーのシークレットでブローカー自体を管理することはできません。ローテーションすると古いシークレットは直ちに無効になり、環境バインディングの更新が必要です。

クラウド互換性： CLI 0.9.20 以降と、 pylot#3988 のゲートウェイ修正を使用してください。org の選択がプロキシのプレースホルダーで機能するようになり、ブローカーは読み取り専用のリポジトリコンテキスト／プレイブックと、org のスコープ内での route および dispatch（--dry-run を含む）をサポートします。コンテキストで解決されるのはシークレットキー名だけです。通常のスコープ、スキル、モデル、アクティブミッションのチェックは引き続き適用されます。ブローカーはディスパッチを強制したり、事前チェックを省略したりできません。管理者による書き込み、シークレット値、Git トークンの発行、ブローカーの管理は引き続き許可リストの対象外です。古い CLI では --org を指定しても broker_org_required が返る場合があります。新たなログイン失敗と判断する前に、インストール済みの実行ファイルとゲートウェイのバージョンを確認してください。事前チェックに合格しても、ミッションがキューに登録されるわけではなく、ネイティブ実行が証明されるわけでもありません。必要なワークフローは個別にテストしてください。

SSH を利用できない場合： ローカルの SSH キーがない、TCP 経路がブロックされている、または SSH キー管理が拒否されたというだけでは、devbox での実行が利用できないとは判断できません。ブローカー認証と対象 devbox／ワーカーの読み取りに成功した場合は、HTTPS 経由の workers prompt を使用して、設定済みの devbox でリモート LLM を実行してください。互換性のある記録済みワーカーを再利用し、その組織と所有者のスコープを維持して、Drive に記載されているとおり、確認応答されたターンとネイティブの結果を検証してください。ミッションの所有権がない外部セッションでは、--mission を省略してください。ワーカーコマンドでは、ゲートウェイ URL と --org を明示したままにしてください。

broker_route_not_allowed の応答は、その操作の拒否として扱ってください。拒否された操作を中止したうえで、許可されたワーカーワークフローを個別に確認してください。ログインを繰り返したり、SSH 管理者アクセスを要求したり、認証情報を変更したり、SSH 管理が拒否されたという理由だけで実行がすべてブロックされたと報告したりしないでください。プロンプト自体が拒否された場合、またはリモートランタイムが失敗した場合は、その具体的な失敗を記録し、不足している機能または必要なランタイムの復旧を報告してください。

ミッションをディスパッチする

CONV_ID=$(ls ~/.claude/session-env/ | head -1)
pylot dispatch "<task>" --agent <team>.<role> --repo <org/repo> --context "conversation_id=$CONV_ID"

自動起動には必ず --context conversation_id=… を渡してください。すべてのディスパッチペイロードは、次の条件を満たす必要があります。

• /skill プレフィックス：タスク文は明示的な /skill で始める必要があります。自由形式のテキストは起動時に routing failed: task has no explicit /skill で失敗します（終了コード 1、トークン消費 0）。ただし、auto-pylot と investigate … report findings のキーワードによるフォールバックは除きます。
• team.role：チーム名とロールは変わるため、正となる情報は pylot teams list です。また、ディスパッチを実行してコストが発生する前に、pylot route で <team>.<role> を検証してください。
• プロンプトのサイズ：約 2560 バイト（ECS_OVERRIDES_LIMIT_BYTES 8192 − DISPATCH_OVERRIDES_RESERVED_BYTES 5632）です。完全な仕様は issue のコメントに記載してください。
• シークレットなし：タスクの契約は自己完結させ、シークレットを含めないでください。

組織間： リポジトリの所有者と選択した認証情報は別々の入力です。CLI のデフォルト org 以外では、まずグローバルオプションで認証情報を明示的に選択してください：pylot --org <Org> context <Org>/<repo> …。スコープを指定しない組織間の呼び出しで単に 403 forbidden が返っても、リポジトリ、プレイブック、または機能が利用できないことの証明にはなりません。認可の問題と判断する前に、リポジトリの org を指定して再試行してください。pylot auth status では、どの org に認証情報があるか確認できます。

ミッションを監視する

pylot missions list                      # recent missions
pylot missions view <job-id>             # full detail
pylot missions logs <job-id> --follow    # tail CloudWatch logs

終端ステータス：done、failed、cancelled、timeout。

シークレットの検出

pylot secrets tree                       # full secrets tree
pylot secrets get <path>                 # bundle keys + fingerprints (no values)

会話に読み込む：pylot conversations resources-add <conv-id> type=secret ref=pylot/<path>

アセット

S3 はありません。アセット API を使います。スクリーンショット、長いレポート、録画など、永続化が必要なものはすべて pylot assets を通してください。直接書き込んだり、別の場所へのリンクを使ったりしてはいけません。機能ブランチ上の raw.githubusercontent.com も、固定の S3 キーも使わないでください。ブランチや保持期間が終了すると、どちらも無効になります。証跡については、ホスティングと永続性に関するルールを参照してください。

3 つの保持期間 — 作成を始める前に、用途に合うものを選んでください。

保持期間	用途	方法
一時的な作業データ	このターン中にまだ編集を続けている下書き	何もしない — ターン内にとどめます
再開可能なチェックポイント	ターン終了後も保持する必要がある非公開の下書き／レポート	presign --conversation <id> → PUT → finalize（finalize が受け取るのは --sha256／--size のみで、scope フラグはありません）
公開済みアーティファクト	人間または別のリポジトリに見せる証拠（スクリーンショット、PR の証明など）	以下の presign → finalize → publish の手順をすべて実行します

チェックポイントの代わりや再試行手段として、安易に publish --conversation <id> を使わないでください。これは visibility: public を設定するため、非公開の下書きを意図している場合はプライバシーの後退になります。所有者は presign 時に --conversation <id> で既に決まっているため、チェックポイントには別途「会話に添付する」手順はありません。

チェックポイントの保持期間は evidence_class に紐づいておらず、特別な TTL 免除もありません。retention_policy は既定で無期限なので、明示的に指定しても何も変わりません。ただし、ステージングでは、すべてのアセット（クラスや retention_policy の値を問いません）が 30 日後に自動的に期限切れになります。これは API の外部にある S3 オブジェクトライフサイクルルールであり、アセットごとの上書きはできません。ステージングのチェックポイントはステージング環境での一時的なものとして扱ってください。ターンの境界を越えて保持するには役立ちますが、レポートが完成した後にアーティファクトを昇格させる代わりにはなりません。ポリシーの詳細は保持を参照してください。

一時的な作業データは永続化されません。通常の関数の戻り値が破棄されるよりも唐突にターンが終了することがあります（その障害の概要についてはLambda Freeze Conventionを参照してください）。曖昧な「残りが少ない」という感覚を待たず、具体的なきっかけを基準にしてください。会話に context capacity システムメッセージが表示された場合（issue #944 によるとコンテキストの約 90% で発生します）、そのターンが最後のチャンスです。他のことをする前に、手元の内容を非公開の会話アセットとしてチェックポイントしてください。そのメッセージがまだ表示されていなくても、レポートが未完成のままターンを終了しようとしているなら、同様にチェックポイントしてください。警告は最後の安全策であり、表示されるまで待ってよいという許可ではありません。

Pylot のアセットライフサイクル全体には CLI を使ってください。CLI 以外で行う唯一の操作は、有効期間の短い署名付きオブジェクト URL への直接の PUT です。curl で Pylot ゲートウェイのアセットエンドポイントを呼び出してはいけません。

FILE=/path/to/evidence.png
CONTENT_TYPE=image/png
SIZE=$(wc -c < "$FILE" | tr -d ' ')
if command -v sha256sum >/dev/null 2>&1; then
  SHA256=$(sha256sum "$FILE" | awk '{print $1}')
else
  SHA256=$(shasum -a 256 "$FILE" | awk '{print $1}')
fi

# Choose the ownership scope required by the destination: --repo, --job, or --conversation.
PRESIGN=$(pylot assets presign \
  --content-type "$CONTENT_TYPE" --size "$SIZE" \
  --repo <org/repo> --filename "$(basename "$FILE")" \
  --evidence-class visual --retention-policy <repo-policy>)  # use the retention policy required by the owning repo (e.g. indefinite, 90d)
ASSET_ID=$(printf '%s' "$PRESIGN" | jq -r '.asset_id')
UPLOAD_URL=$(printf '%s' "$PRESIGN" | jq -r '.upload_url')

# The presigned URL carries its own credentials; do not add a Pylot auth header.
curl -fsS -X PUT "$UPLOAD_URL" -H "Content-Type: $CONTENT_TYPE" --data-binary @"$FILE" && \
  pylot assets finalize "$ASSET_ID" --sha256 "$SHA256" --size "$SIZE"

visual は、永続的なレビュー用証拠として使うスクリーンショットや録画の証拠クラスです。所有するリポジトリで定められた保持ポリシーと証拠ポリシーを使用してください。意図的な場合を除き、一時的な会話画像を恒久的な証拠として分類しないでください。

確定後は、送信先に応じた動詞を使ってください。

pylot assets view "$ASSET_ID"                              # metadata + temporary GET URL
pylot assets attach "$ASSET_ID" --mission "$PYLOT_JOB_ID" # private mission evidence
pylot assets publish "$ASSET_ID"                          # public capability URL
pylot assets publish "$ASSET_ID" --conversation <id> --alt "description"
pylot assets unpublish "$ASSET_ID"                         # revoke public capability URL

公開すると public_url が返されます。まず通常の公開を行ってください。--override-policy を追加するのは、所有するポリシーが監査済みの例外を明示的に求めている場合、またはサーバーから該当するポリシー制限が返された場合に限ります。ポリシーを回避するために、先回りして使ってはいけません。会話への公開では、アセットの公開と添付の両方が行われます。attach --mission は公開せずに、非公開のミッション証拠を記録します。6 つすべてのライフサイクル操作 — presign、finalize、view、attach、publish、unpublish — は引き続きゲートウェイ操作であり、pylot assets を通して実行する必要があります。

チーム設定

1 つのコマンド、1 回の往復、確認可能な証拠 — PATCH 後にサーバーから読み戻した値を出力します（#3094）：

pylot teams config <team> deploy.release_mode=ship   # dotted-path set + read-back
pylot teams config <team> budget_daily_usd=600
pylot teams get <team> --fields deploy,cron          # scoped read of stored config
pylot teams update <team> key=value [...]            # multi-field PATCH (no read-back print)

変更可能なフィールド（サーバーで検証されます。400 エラーでは、現在有効な項目が valid_fields として一覧表示されます）： budget_daily_usd enabled org chains provider_chain cron fargate fargate_size deploy operators worker_images repos distill_enabled context_warn_pct context_hard_pct slack_channels。

読み戻しの保証：サーバーが保存できないフィールドは 400 エラーで拒否されます — 受け付けて破棄されることはありません（この往復をコーパステストで検証しています。この理由により、チームレベルの skills は対象から削除されました。オペレーターのスキルは operators.<role>.skills にあります）。書き込みが「成功」したのに読み戻しが null の場合は、 バグです — 報告してください。工夫したペイロードで再試行しないでください。

Runner の契約

名前が -runner で終わるスキルは、devbox の外部から実行され、devbox を必要とします。これが定義のすべてです。 呼び出し元がどこにいるかは関係ありません。cron 上の Pylot オペレーターでも、この Mac 上のこのセッションから ゲートウェイ経由で devbox を起動する場合でも同じです。次のことに注意してください。

• Runner がエンジン自体を実行することはありません。devbox を起動または指定し、 プロンプトを送信し、ポーリングして検証し、結果を報告します。エンジンの手順をインラインで実行していることに気づいたら、 使っているスキルが間違っています。
• Runner は devbox 内にエンジンスキルがインストールされていることを前提とします（たとえば、 improve-code-quality-runner にはワーカー内の improve-code-quality と test-in-staging が必要です）。現在、この依存関係は Runner の前提条件に記載されているだけで、 インストールする仕組みはありません。対象リポジトリに同梱されている場合に限り、ワーカーにエンジンがあります。 Pylot のフロントマター契約とワーカー起動時のインストールが導入されるまで（fellowship-dev/pylot#3540）は、 Runner を実行する前に対象リポジトリの .claude/skills/ を確認してください。
• エンジンにはサフィックスがなく、ゲートウェイへのアクセスなしで、どのチェックアウト内でも動作する必要があります。 スケジュールに従ってワーカーを起動するだけのラッパーも Runner です。これらは pylot-skills 内で非公開のままにしてください。
• pylot skills list --kind runner が Runner のフィルター契約です。

事前確認とディスパッチ

ディスパッチする前に、次のことを確認してください。

• 認証済み CLI から Pylot に接続できること。
• 現在のチーム、ロール、スキルのルート、リポジトリ、ワーカーイメージ、予算が、 選択したモードに対応していること。
• 関連する自動化が作業と重複したり、競合したりしないこと。
• タスクの契約が自己完結していて、シークレットを含まず、使用するスキルを明示していること。

CLI 経由でディスパッチし、返されたミッションまたはワーカーの識別子を保持してください。 未加工のゲートウェイ呼び出しや、文書化されていないローカル状態で代用しないでください。証拠やアセットについては、 pylot-cli に従ってください。ここでそのライフサイクルを再現しないでください。 大規模なリモート作業では、ブランチ／ベース、Git の ID、証拠の可視性を事前に確定し、 許可された永続的なチェックポイントを小規模に作成して早期に証明してください。 公開が阻まれていると判明するまで何時間も作業を積み重ねないでください。 以前に付与された範囲内の認可を維持してください。ツールによる実際の拒否と、エージェントによる解釈を区別し、 後者については最新の証拠を使って調査してください。 復旧後またはコンパクション後は、申告された阻害要因を、実際のツールの応答と受け付けられたタスクに照らして確認してください。 名前の付いたモデルツールが見つからないからといって、インストール済み CLI が利用できないことにはなりません。 利用可能なシェルからヘルプを確認してください。長々とした引き継ぎの説明ではなく、 具体的で範囲を限定したアクション、維持された権限、明示的な成果物の保存先をもって作業を再開してください。 実際のアクセス拒否を覆してはいけません。

ワーカー — 起動、操作、停止

ワーカーは、対象リポジトリを実行する Fargate devbox です。所有権はスコープで決まります。 spawn と list では --mission と --conversation のどちらか一方だけが必要です。 ワーカー単位の動詞は --mission を指定するか、スコープなしの /workers/:wid ルートにフォールバックします。 イメージ CLI のバージョンはさまざまなので、--help でフラグを確認してください。

1. リポジトリの事前確認

pylot devboxes project <org/repo>    # → task_def{family,revision}, required_env_ok

task_def がない場合、イメージは一度もビルドされておらず、起動時に CannotPullContainerError が発生します。まずビルドしてください：pylot deploy build-worker <org/repo> --wait （管理者資格情報が必要です。オペレーターは403になります。§6を参照）。起動失敗は型付きで返されます： 404 no_project／no_repo（リポジトリがどのチームのdevbox設定にもない）、409 ミッションが すでに終了状態、422 provider_required、502 ECS／シークレット。

2. 再利用、再開、新規起動を選択する

同じ進行中の成果物について次の作業を行う場合は、まず記録されている ワーカー、スコープ、タスクARN、完了したターンを確認してください。以下の確認後、 実行中で正常なdevboxと、そのネイティブコンテキストを再利用してください。新しいラウンドを始めることだけを理由に、 新規起動したり、新しいネイティブセッションを開始したりしてはいけません。他の所有者のボックスを借用したり、 互換性のないリポジトリ、実行ID、未完了のターンを再利用したりしてはいけません。

• ウォーム再利用： 前のターンが完了しており、ネイティブIDが維持され、ワークスペース／アプリケーションの確認にも引き続き合格する場合は、記録されたワーカーで作業を続けます。
• 再開： そのワーカーが停止している場合は、§4の検証済みスナップショットと永続的な復元手順を使用し、その後、ネイティブの継続性とアプリケーションの準備状況を確認します。
• 新規起動： 互換性のある再利用可能なワーカーがない場合、または明示的な復旧判断で必要とされる場合は、新しいボックスを使用します。再利用が適さなかった理由を記録してください。

ウォーム再利用は、許可された作業時間と予算の範囲内にしてください。アクティブな作業が終わったら、アイドル状態にする時間を短くし、確認後に停止することを優先してください。計測結果を良くするためにキープアライブを追加したり、TTLを延長したり、コンピュートを一晩中稼働させたりしてはいけません。リソースの稼働時間と割り当てられたCPU／メモリは、計測された請求額と分けて記録してください。割り当て量の見積もりは請求額ではありません。

# inside a mission — your own job
pylot workers spawn --mission "$PYLOT_JOB_ID" repo=<org/repo>
# from a conversation — name= is the human-readable pretty name (tag pylot:name)
pylot workers spawn --conversation "$CONV_ID" repo=<org/repo> name=<short-purpose>

# from a local session (a laptop running `pylot auth login`, no mission context):
pylot devboxes spawn <org/repo> --idle-ttl 3600 name=<short-purpose>   # standalone box, the default
pylot devboxes view <task-arn>                                          # wait for RUNNING before the first prompt
# persistent-conversation variant — capture only the id so the session credential is never printed
CONV_ID=$(pylot conversations create --org <org> --team <team> --repos <repo-name> --title "<task>" | jq -r .id)
pylot devboxes connect <task-arn>      # → ssh_command; drive by SSH when direct command control beats prompting

201 → {worker_id, task_arn, last_status}。起動処理はPROVISIONING → RUNNING（約1～2分）で進みます。 プロンプトはサーバー側でキューに入り、コンテナ内のデーモンが起動すると一度だけ取得されるため、早めに送信したプロンプトが失われることはありません。RUNNINGの確認が必要な場合は、 pylot workers list --mission "$PYLOT_JOB_ID"でライブのecs_statusを確認できます（単一ワーカーのviewでは確認できません）。name=が適用されるのは会話のパスのみです。

3. 実行する

pylot workers prompt <wid> --mission "$PYLOT_JOB_ID" "<text>"     # 202 {turn_seq} | 409 busy|stopped
pylot workers prompt <wid> --mission "$PYLOT_JOB_ID" --wait --timeout 3600 "<text>"
pylot workers view   <wid> --mission "$PYLOT_JOB_ID"              # turn_state, turn_seq, last_result, last_exit_code
pylot workers output <wid> --mission "$PYLOT_JOB_ID"              # result text only
pylot workers logs   <wid> --mission "$PYLOT_JOB_ID"              # CloudWatch tail (--mission required)

turn_stateがidle／error／reapedであり、かつturn_seqが プロンプトから返されたseq以上であれば、ターンは完了です。その場合に限り、last_resultを信頼してください。--waitは5秒ごとにポーリングし、最大900秒まで待機します（--timeoutで変更可能）。終了状態がidle以外の場合は、ゼロ以外で終了します。--followはコンテナログをstderrにストリーミングし、--waitが必要です。 ターン中にdevboxが停止した場合は、last_exit_code: -1でreapedとなるため、ループが永久に停止しなくなることはありません。フェーズ間では、次のプロンプトを送る前に出力を読み取ってください。失敗したフェーズを土台にしてはいけません。last_resultがない場合は、元のlast_outputを証拠として保持し、成功した結果を捏造してはいけません。 prompt --waitがシェルの終了ステータス0を返し、ワーカーがidleであっても、last_exit_codeとネイティブの継続性に関する失敗理由を確認してください。これらの状態は、プロバイダーのターン失敗を伴うことがあります。プロバイダーの終了コードがゼロ以外の場合や、継続性の失敗が明示されている場合、そのフェーズは失敗です。出力を保持し、次のプロンプトを送る前、または成功を主張する前に、失敗を解決してください。

同じ範囲内のタスクを続けるには、前のターンが完了した後、同じワーカーIDに次のプロンプトを送信してください。スコープ、ワーカーID、session_id、完了したturn_seq、全出力を保持してください。ターンの合格が証明するのはそのターンの結果です。アプリケーションの準備完了を確認するには、目的のビルド、テスト、実行中のサービス、機能確認が引き続き必要です。ワーカーがidleであることだけを根拠に、準備完了と報告してはいけません。

ラウンド間の安全な更新

ソースを更新する前に、対象リポジトリと実際のチェックアウトパス、現在のブランチ／HEAD と上流、ステージ済み、未ステージ、未追跡の状態、およびリンクされたワークツリーの状態を確認してください。たとえば、対象のチェックアウトから次を実行します。

git rev-parse --show-toplevel
git branch --show-current
git rev-parse HEAD
git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' # absent upstream needs an explicit target
git status --short --untracked-files=all
git diff --stat
git diff --cached --stat
git worktree list --porcelain

認証情報を含む URL を公開せずに、リモートのリポジトリ識別情報を検証してください。必要に応じて関連する差分を非公開で確認し、シークレットや無関係な作業を出力しないでください。変更のある状態は保持すべき作業であり、起動失敗ではありません。検証済みのリモートに対して git fetch <remote> を実行し、ブランチ、インデックス、ワークツリーを変更せずに、取り込まれるコミットを確認してください。自動的に pull、reset、stash、clean、ブランチ切り替え、rebase を行わないでください。それが意図した状態であれば、現在のソースで作業を続けてください。クリーンなチェックアウトが意図したブランチにあり、現在の HEAD が明示的に検証した対象の祖先であることを確認し、取り込まれる範囲を確認した後に限り、早送りしてください（git merge --ff-only <verified-target>）。分岐している場合、変更がある場合、または意図したブランチが異なる場合は、インベントリを保持し、他者の作業を移動または破棄せずに統合計画を決めてください。

コードのみのコミットによって、健全な環境が無効になることはありません。変更された入力を、リポジトリの準備完了要件と照合してください。依存関係ロック、ランタイム／イメージ、起動／サービス設定、スキーマ／マイグレーション、および必須の設定変更は、以前の確認結果を無効にする可能性があります。これらの入力が変更された場合は、影響を受けるセットアップまたは準備状況のチェックを実行してください。フィンガープリントが不明な場合は検証が必要です。準備状況を更新するためだけに、破壊的なセットアップを再実行したり、データベースを作り直したりしないでください。次のラウンドの準備ができたと宣言する前に、必須のサービスの健全性を確認し、実用的なタスク操作（該当する場合は対象を絞ったチェックとブラウザー／ジョブのフロー）を実行してください。キャッシュと影響を受けない準備状況の証拠は再利用しつつ、リポジトリで必須のサービスゲート全体を維持し、ソースとランタイムのリビジョンを記録してください。

リモートのスラッシュコマンドを呼び出す前に、ワーカーにインストール済みのコマンドとスキル、およびリポジトリの指示を一覧表示するよう、通常のテキストで確認プロンプトを送信してください。ローカルスキルはリモートにはインストールされていません。ハーネスが終了コード 0 を報告した場合でも、Unknown command の結果はターンの失敗です。

考古学的な調査なしで修正できる、2 つの起動失敗：

• プロンプトがキューに入ったまま、view に queued → idle、last_exit_code: -1、session_id: null、凍結した heartbeat_at が表示され、/ecs/pylot-workers に [worker-prompt-daemon] の起動ログがない → ワーカーイメージがプロンプトデーモン導入前のものです。pylot deploy build-worker <org/repo> を実行して再起動してください。
• ターンが 403 unknown job ／ unknown devbox worker で失敗する → プロキシプリンシパルのリグレッションです。ワーカー行の job_id を確認し、ゲートウェイに報告してください。

pylot workers prompt --help に --wait ／ --follow ／ output がない場合、このコンテナの CLI はそれらが導入される前のものです。スリープループで view をポーリングするか、§7 を使用してください。

チャット／Lambda ランタイムでは、--wait でブロックする余裕はありません。ビジーポーリングは絶対に行わないでください。プロンプトを送信し、起床をスケジュール（Async Wake Pattern を参照）してから、次のターンで view を再確認してください。

4. 停止（破壊的操作）と再開

pylot workers stop   <wid> --mission "$PYLOT_JOB_ID" --force
pylot workers resume <wid> --mission "$PYLOT_JOB_ID" --wait --timeout 900
# Observe the acknowledged attempt without initiating another restore.
pylot workers restore-status <wid> --attempt <restore-attempt-uuid> --wait --timeout 900

--force は必須です。これがないと CLI は停止を拒否します。誰かが作業中のボックスを停止する前に、人に確認してください。停止操作は冪等です。スキルの実行が終わったら、必ずミッションワーカーを停止してください（完了時の回収は最後の保険であり、計画ではありません）。会話所有の開発ボックスは停止時にスナップショットを作成します。ミッションワーカーのスナップショットはオプトインで、デフォルトでは OFF です（コスト管理のため）。そのため、フラグが有効だと分かっていない限り、ミッションワーカーの停止は最終処理として扱ってください。停止する前に、完了したターンの出力全体を回収してください。停止によって last_output が切り詰められたスナップショットのトランスクリプトに置き換わる可能性があります。stopped: true は復旧できることを意味しません。resume に頼る前に、snapshot_status: verified を必須としてください。停止の受領情報とスナップショットのステータス／理由を保持してください。スナップショットの作成に失敗した場合やスナップショットがない場合は、楽観的に再開できると主張するのではなく、明示的に復旧方法を判断してください。 永続復元には CLI 0.9.14 以降と、非同期復元に対応したゲートウェイが必要です。 開始前に pylot workers resume --help で --wait を、pylot workers restore-status --help で復元状況の確認方法を確認してください。古い CLI やワーカーイメージでは、これらの動作が利用できるとは限りません。

Resume は、永続化された復元試行を 1 回開始します。restore_status: pending を含む HTTP 202 は受理を示すものであり、復元の成功を示すものではありません。CLI が終了コード 0 で終了した場合も同様です。直ちに worker_id、restore_attempt_id、スナップショット ID、取得できる場合は復元先の task_arn、元のスコープをタスクチェックポイントに保存してください。--wait は短いステータス取得で、その復元試行を監視します。タイムアウトや監視接続の切断によって、復元がキャンセルされることはありません。保存したワーカー ID と復元試行 ID を使って restore-status で再接続してください。待機がタイムアウトしたからといって、resume の POST を繰り返さないでください。受理応答が失われた場合は、別の開始が安全かどうかを判断する前に、restore-status <wid> とワーカーの状態を調べて復元試行の ID を特定してください。ランタイムの復元期限とクリーンアップのライフサイクルは、CLI の監視タイムアウトとは独立しています。ステータスの監視によって復元試行の整合性を確認して完了状態にでき、失敗または期限切れの復元先の停止を含め、クリーンアップを進められます。ただし、新たな復元は開始しません。cleanup_pending の理由を保存し、監視のタイムアウトや StopTask の受理を停止完了とみなさず、終了状態になるまでクリーンアップを確認してください。

ステータスに保存済みのワーカーと復元試行が引き続き示され、restore_status が succeeded で、復元レシートがその復元試行とスナップショットに一致し、復元先のタスクが RUNNING の場合に限り、完了を受け入れてください。新しいタスク ARN を保存し、停止した復元元の ARN を使って処理を続けないでください。ステータスが failed の場合、または ID が一致しない場合は、記録された理由を調べ、次のプロンプトや再試行の前に復旧方法を解決する必要があります。ゲートウェイの復元成功は復元が成功したことを示しますが、ワークスペース、ネイティブコンテキスト、アプリケーションの準備状態については、以下の確認も必要です。

スタンドアロンの devbox では、次を使用してください。

pylot devboxes resume <stopped-task-arn> --wait --timeout 900
# Use the destination task_arn from the completed attempt for subsequent calls.
pylot devboxes view <destination-task-arn>
pylot devboxes connect <destination-task-arn>

devboxes resume --wait は、完了した復元試行の復元先 ARN を追跡し、その復元先が RUNNING になって到達可能になるまで待機します。監視がタイムアウトした場合は、前述のとおり保存済みの worker_id と restore_attempt_id を使って workers restore-status で状態を確認し、その復元先を確認して接続してください。デーモンに到達できるだけでは、アプリケーションのサービスが準備できているとは限りません。

ネイティブコンテキストの継続性はプロバイダーごとに異なります。 ゲートウェイの session_id はドライブループを識別するものであり、Codex のネイティブスレッドを示すものではありません。ネイティブな Codex の継続性を備えたワーカーイメージでは、ゲートウェイセッションと thread.started の ID の対応関係を ~/.codex に保存し、その同じネイティブスレッドを再開する必要があります。--last に置き換えたり、別のセッションから ID を推測したり、ロールアウトが見つからない場合に黙って新規に開始したりしないでください。ソースが対応しているバインディングは $HOME/.codex/pylot-worker-sessions/<sha256-of-gateway-session-id>.json です。保存済みのプロバイダー／認証情報の経路とパスを比較するため、ゲートウェイ ID、thread_id、identity フィールドのみを確認してください。ロールアウト履歴の生データや認証情報の値を出力してはいけません。続行する前に、同じ実行 ID（プロバイダー、プロバイダーの種類、認証情報の参照先、実際の作業ディレクトリ、ネイティブホーム）であることを確認してください。同じプロバイダーと認証情報の経路内であればモデルの変更はサポートされています。モデルの変更だけを互換性がない理由とみなすのではなく、各ターンで使用したモデルを記録してください。 Claude は独自のセッション／履歴と --resume のセマンティクスを使用します。Codex の ID に関する規則を Claude に適用したり、いずれかのプロバイダーで他方の履歴を再開できると想定したりしないでください。

1. 停止する前に、ワーカーとゲートウェイのセッション ID、プロバイダー／ネイティブの識別情報を示す証拠、完了したターンの順序、結果全体、未完了の作業チェックポイントを保持してください。認証情報、環境変数、生のネイティブ履歴を出力せずに、パスと識別子を記録してください。
2. 検証済みのスナップショットを取得した後、同じスコープで同じワーカー IDを再開してください。上記と同じ復元試行を、成功が検証されるまで監視してください。新しいタスク ARN が割り当てられるのは想定どおりです。次のプロンプトを送る前に、復元されたワークスペースとネイティブセッションの証拠を確認してください。session_id が変わっていないことだけでは不十分です。
3. 次の範囲を限定したプロンプトをそのワーカーに送ってください。ターンの順序が進んだことと、プロバイダーが保存済みのネイティブ履歴を再開したことを確認してください（たとえば、以前のターンにあった固有のタスク情報を、再度伝えなくても思い出せること）。結果を取得し、準備完了と判断する前に、アプリケーションの機能チェックを完了してください。

ソース側でサポートされていても、公開済みのワーカーイメージにその機能が含まれているとは限りません。ネイティブな継続性を主張する前に、イメージ／バージョンと、実際に観測された再開動作を確認してください。 ネイティブマッピングやロールアウトを一度も保存していない古い Codex ワーカーでは、ゲートウェイのセッション ID から失われた履歴を推測することはできません。ファイルシステムと出力の証拠を保持し、履歴が失われていることを報告したうえで、新しいセッションへの明示的な移行または復旧の判断を行ってください。その移行をネイティブ再開と呼んではいけません。 会話の削除は破壊的な操作です。明示的に依頼されない限り、決して削除しないでください。

5. 複数ボックスでの作業 — あなたがメッセージバスです

ボックス同士が直接やり取りすることはありません。事前確認を行い、目的が異なる名前を付けてリポジトリごとに 1 つずつ起動し、手作業で中継してください。workers view で A を確認 → 重要な証拠（リクエスト ID、スタックトレース、ペイロードの形式）を抽出 → その情報を付けて B に workers prompt を送信します。中継するコンテキストは小さく、事実に限定してください。ボックスはそれぞれ独自の環境変数バンドルを持っているため、ボックス間でシークレットを渡してはいけません。ボックスを 2 つ使うと予算の消費速度も 2 倍になります。そのため、両方のリポジトリでコードまたはログへのアクセスが本当に必要な場合に限り、2 つ目を起動してください。

6. 認証情報で呼び出せるもの

機能ゲートが作動するのは、ミッションコンテナが使用するオペレーター JWT（PYLOT_OPERATOR_TOKEN。PYLOT_DISPATCH_TOKEN としてエイリアスされています）に対してのみです。オペレーターはすべてのオペレーター機能を持つため、ゲートが確認するのは、ルートがマッピングされているかどうかだけです。ミッションスコープのワーカールートはマッピングされていますが、スコープのないルートはマッピングされていません。

例外 — セッション JWT（$PYLOT_API_TOKEN）：次の会話スコープのルートは、org:member ティアでマッピングされており（route-capability.mts:224-229）、セッション JWT で到達できます。機能ゲートはこれらのリクエストを通過させ、各ハンドラーがサーバー側で独自の認可を適用します。

ルート	以降	認証境界
POST /conversations/:id/slack-post	#2622	ハンドラー：組織メンバー
POST /conversations/:id/slack-pickup	#2622	ハンドラー：組織メンバー
POST /conversations/:id/admin-action	#2891	ハンドラー：turn-trigger 経由の組織管理者チェック
POST /conversations/:id/admin-action/confirm	#2891	ハンドラー：turn-trigger 経由の組織管理者チェック

セッション JWT を受け付ける会話スコープのルートは、これらだけです。それ以外のすべての会話スコープのルートと、すべての /admin/* ルートは、設計どおり、セッション JWT では引き続き 403 になります。

呼び出し	ミッションオペレーター	Devbox ワーカー · ローカルの pylot auth login
workers spawn/list/view/prompt/output/stop/resume/logs に --mission を指定	はい	はい
同じ動詞を --mission なしで使用（スコープなしの /workers/:wid）	403	はい
workers restore-status（GET による参照。--mission フラグなし）	はい、自分のワーカー	はい
workers spawn/list --conversation	403	はい
devboxes projects、devboxes project <org/repo>	はい	はい
devboxes spawn/view/connect/delete/list	403	はい
deploy build-worker、deploy promote	403	はい
deploy status <build_id>	はい	はい

ゲートによる 403 の応答は {"error":"forbidden","reason":"capability_required","capability":"unknown"} です。オペレーター JWT 以外では機能ゲートは適用されませんが、組織スコープのトークンにはハンドラーレベルの組織制限が引き続き適用されます。ミッション内では、指定可能な動詞には必ず --mission "$PYLOT_JOB_ID" を指定してください。 restore-status は、認可済みの GET 参照ルートで保存済みのワーカー ID と試行 ID を使用します。前述のとおり、既存の試行を照合し、クリーンアップを実行できます。

7. 使用可能な CLI がない場合のフォールバック

イメージに pylot が含まれていないコンテナ、または必要な動詞を使うには古すぎるコンテナでのみ使用してください。PYLOT_JOB_ID、PYLOT_API/PYLOT_GATEWAY_URL、PYLOT_DISPATCH_TOKEN は、オペレーターコンテナとミッションワーカーコンテナの両方に設定されています。

AUTH=(-H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" -H "Content-Type: application/json")
BASE="${PYLOT_API:-$PYLOT_GATEWAY_URL}/missions/${PYLOT_JOB_ID}/workers"

WID=$(curl -s --max-time 90 -X POST "${AUTH[@]}" -d "{\"repo\":\"$REPO\"}" "$BASE" \
      | python3 -c 'import sys,json; print(json.load(sys.stdin).get("worker_id",""))')
SEQ=$(curl -s --max-time 30 -X POST "${AUTH[@]}" -d "{\"prompt\":\"$PROMPT\"}" "$BASE/$WID/prompt" \
      | python3 -c 'import sys,json; print(json.load(sys.stdin).get("turn_seq",""))')
# poll GET "$BASE/$WID" until turn_state=idle AND turn_seq=$SEQ, then read last_output
curl -s --max-time 30 -X POST "${AUTH[@]}" "$BASE/$WID/stop" >/dev/null 2>&1 || true

§2–4 と同じルートで、同じセマンティクスです。CLI がある場合は、そちらを優先してください。トランスポートと信頼できる情報源を一元化できます。

実行を監視する

ワーカーまたはプロンプトを開始したら、受理されて起動中であることを確認するため、ただちに簡潔なステータス確認を1回行います。キュー待ちやプロビジョニング中は、まだ実行中ではありません。 完了イベント、または終端状態になったときだけセッションを起こすデタッチされたステータスモニターを優先します。定期確認が必要な場合は、状況に応じて10～30分間隔にします。結果が予想される時期や既知の障害がある場合は約10分、順調に進んでいる1時間程度の実装やテスト作業では20～30分にします。状態に変化がなく健全であれば、次の待機時間を延ばします。追加のプロンプトを出してはいけません。具体的な起動時または障害の診断に限り、短い間隔で確認します。タスクごとのフォローアップ担当は最大1人とし、別のセッションが引き継いだら元のフォローアップを一時停止します。また、完了時、または安全な作業を妨げる判断が必要になった時点で一時停止します。自動化エラーや安全性の拒否が発生したら、繰り返し再試行するのではなく、調査して停止します。同じブロックされた処理を繰り返し起動したり、回避するために経路を変更したりしてはいけません。

工場が安全に続行できないことを示す証拠がある場合に限り、介入します。たとえば、タスクの契約内容に重大な曖昧さがある場合、回復不能な実行状況にある場合、または結果がスコープや安全性に違反する場合です。永続化されたリモート状態からの再開を優先します。通常の実装について指導したり、単に不完全な成果物を書き直したり、繰り返し発生する工場の不具合に対してセッション内だけの回避策を構築したりしてはいけません。

終端結果を検証する

プロセスが正常に終了したことは、納品物の完成を意味しません。タスクのスコープに照らして、要求された成果を独立して検証します。

• 終端ミッション状態、レポート、コストに矛盾がないこと。
• 期待されるブランチまたは PR が、正しいターゲットとスコープで存在すること。
• PR の主張が、実際の差分および記録されたチェック結果と一致すること。
• レビューの提案と残っているリスクが確認できること。
• デリバリータスクでは、レビューでの指摘が解決され、承認済みのリリース作業がターゲット環境のワークフロー受け入れを経て進み、デプロイ済みのリビジョンと実行時の証拠が確認できること。PR またはワーカーの完了は中間結果です。
• 添付された証拠に、意図された Pylot アセットフローを通じてアクセスできること。
• 実行リソースが停止しているか、意図された終端状態になっていること。

ワーカー完了後に残るデリバリー作業の責任は、コーディネーターが担います。明示的に PR のみを対象とするタスクは、検証済みの PR をもって完了できます。検証によって再利用可能な不具合が見つかった場合は、ここで回避策を講じるのではなく、その不具合を管理するスキルを修正します。

指摘の登録 — 生の gh issue create は決して使わない

ミッション、ステージ、レビューのいずれかで見つけた自動化による指摘（バグ、ギャップ、フォローアップ）はすべて、各オペレーターのこのスキルに付属する次のヘルパーを通します。

FF="${PYLOT_WORKSPACE:-$HOME/.claude}/skills/pylot-cli/scripts/file-finding.sh"
bash "$FF" --repo <org/repo> --title "<title>" --search "<root-cause terms>" \
  --body-file <evidence.md> [--severity P0|P1|P2|P3] [--incident] [--blocking] [--label <l>]...

このヘルパーは、担当者ルール（2026-10-06、課題の流入を抑制）を適用します。

1. --search（根本原因：シンボル、ファイル、エラーテキスト、またはフィンガープリント）に一致するオープンな課題がある場合、新しい課題を作成せず、コメントを追加します。
2. P0/P1 ではなく、インシデントでも PR またはリリースをブロックするものでもない指摘は、リポジトリのローリング方式の Weekly findings digest — YYYY-Www 課題（ラベル digest）に、タイトルごとに1回コメントとして追加します。新しい週のダイジェストが、前の週のものをクローズします。
3. 1回の指摘登録実行で新規作成できる課題は、全リポジトリ合計で最大3件です（FINDING_CYCLE。既定値はミッション ID）。P0 と --incident は上限の対象外です。上限を超える指摘はダイジェストに追加します。

ヘルパーは commented N、digest N <reason>、または created N を出力します。その番号を引用してください。--dry-run を指定すると、何も書き込みません。ヘルパーがない場合は、同じ3つのルールを手動で適用します。対象外：固定ラベルでステージが管理する追跡課題（ラベルごとに1件）と、クローズ済み課題の再オープン。

CLI 経由の GitHub 認証

pylot auth login は、組織ごとの認証情報を ~/.pylot/credentials に保存します。 pylot auth git-token --repo <org>/<repo> は、選択されたプリンシパルでそのエンドポイントが許可されている場合に、1 回限りの短命な App インストールトークンを発行します。デバイス認証ブローカーへのログインは Pylot サービスの認証であり、現在の許可リストには Git トークンの発行が含まれていません。コネクターを利用した Buddy クラウドのセットアップでは、対象のリポジトリに対して、呼び出しごとに PYLOT_GH_AUTH_MODE=inherited gh ... を使用してください。コネクターの準備状況と Pylot トークンの由来は、別々の受け入れ基準として扱ってください。 App は組織全体にアクセスできますが、発行される各トークンの対象は指定した 1 つのリポジトリに限定されます。そのトークンで gh repo list の結果が少なくても、それは App の制限ではありません。別のリポジトリには、別のトークンを発行してください。リポジトリに「pylot support がない」とは、そのリポジトリの devbox 設定がない（チームに所属していない、ワーカーイメージがない）という意味であり、App がアクセスできないという意味ではありません。セッション全体に適用される GH_TOKEN をエクスポートしないでください。 App トークンでは、ユーザー固有の画面（GitHub 通知など）を読み取れません。そうした情報には、ログイン済みの gh ID またはイベント台帳のルーティングが必要です。シークレットはプロンプトやペイロードに絶対に含めないでください。pylot secrets を使用し、環境変数名を参照してください。

Git には認証情報ヘルパーが必要です。gh には、呼び出しごとに独自のトークンシムが必要です。リポジトリを指定したコマンドで両方を検証してください。マネージドクラウド環境では、送信プロキシが呼び出し元から渡された GitHub 認証を置き換えていないか確認してください。無効なトークンを意図的に使ってもプライベートリポジトリの読み取りに成功する場合、それは Pylot トークンでアクセスできた証拠にはなりません。サポートされている環境設定を通じて認証情報のルーティングを解決し、プロキシと TLS の設定を維持したうえで、実際のリポジトリの読み取りとプッシュを再度行ってから認証を受け入れてください。インストールやトークンの発行だけでは、十分な証拠になりません。

会話からの組織セットアップ（admin-action）

pylot#2978 が必要です — ワーカーをここに誘導する前に、pylot convo admin-action がワーカーイメージに含まれている必要があります。確認するには、コンテナ内で pylot convo admin-action --help が成功する必要があります。

セッション JWT のスコープは [dispatch, missions:read, heartbeat] です。設計上、/admin/* ルートは常に 403 を返します。/conversations/:id/admin-action は別の認可境界（§6 の例外テーブルを参照）で、セッション JWT を受け付けます。このエンドポイントは、ターンをトリガーしたメッセージの送信者を通じて、サーバー側で組織管理者の認可を強制します。

主な手順

# auto-detects $CONVERSATION_ID from environment
pylot convo admin-action <op> [key=value ...]

# explicit conversation id override
pylot convo admin-action <op> --conversation <id> [key=value ...]

# confirm a staged (confirm-tier) operation after org admin replies
pylot convo admin-confirm <code>

# reject a pending confirm-tier operation
pylot convo admin-confirm <code> --reject

操作

操作の一覧は固定されています。この表にない値はすべて 400 を返します。 操作引数に認証情報や API キーを渡さないでください。ゲートウェイは 400 を返し、何も保存されません（強制的な境界として、認証情報に見える引数は明示的に拒否されます）。

op	tier	effect
setup-status	読み取り（会話のメンバー全員）	オンボーディングの状態：App のインストール、チーム、リポジトリの紐付けとワーカーイメージの有無、目標、オペレーター／スキル、プロバイダーチェーン、予算
team-create	即時（組織管理者の依頼者）	この組織にチームを作成
team-rename	即時（組織管理者の依頼者）	チーム名を変更
repos-add	即時（組織管理者の依頼者）	リポジトリをチームに紐付け。応答にはワーカーイメージの有無を含む
goals-set	即時（組織管理者の依頼者）	チームの目標を設定（ストアの auto-pylot ステージ 00 が読み取る）
operator-add	即時（組織管理者の依頼者）	チームにオペレーターを作成
skill-assign	即時（組織管理者の依頼者）	オペレーターにスキルを割り当て
instructions-set	即時（組織管理者の依頼者）	オペレーターへの指示を設定
org-update	確認	組織の設定（Slack のデフォルトチーム、max_concurrent、…）
budget-set	確認（支出）	チームの日次予算上限
provider-assign	確認（モデル／支出のルーティング）	既存のプラットフォームプロバイダーチェーンを組織／チームに割り当て

確認が必要な操作のフロー

確認が必要な操作（org-update、budget-set、provider-assign）はまずステージングされ、その後、組織の管理者の返信によって承認されます。承認者の身元は、その人自身の会話ターンによって証明され、ワーカーから渡されるものではありません。

1. pylot convo admin-action <confirm-op> [args] → ゲートウェイが 202 {code, summary} を返します
2. ワーカーがユーザーに伝えます：「組織の管理者が10分以内に confirm <CODE> と返信する必要があります。」 （summary には変更内容が正確に記載されるため、そのまま伝えてください。）
3. 組織の管理者が返信します。承認ターンのメッセージ送信者自身によって、身元が証明されます。
4. pylot convo admin-confirm <CODE>（承認ターン内で呼び出し）→ 200、実行済み。
5. 拒否または期限切れの場合：pylot convo admin-confirm <CODE> --reject で保留中の操作を取り消します。期限切れのコード（10分超過）は 410 を返し、実行されることはありません。

エラー

エラー	意味	ユーザー向けの案内
no_human_trigger	ターンに人間の送信者がいません（スケジュールされた起動、自動化）	人間のメッセージによって開始された会話ターンから再試行してください
unlinked_slack	送信者の Slack アカウントが GitHub アカウントにリンクされていません	Slack アプリの設定で GitHub アカウントをリンクするようユーザーに依頼してください
not_org_admin	リンクされた GitHub アカウントはこの組織の管理者ではありません	即時操作にはスレッド内の組織管理者が必要です。確認が必要な操作は誰でもステージングできますが、確認は組織管理者が行う必要があります
terminal_only	操作に認証情報またはシークレット値が必要です	ターミナル CLI を使用してください。認証情報を会話経由で送信することはできません
code_expired	確認コードの発行から10分以上経過しています	元の操作を再実行して、新しいコードを取得してください

移行期間中の curl フォールバック（#2978 より前のイメージのみ）

コンテナイメージが pylot convo admin-action より前のものである場合にのみ使用してください。 チャットワーカーのコンテナでは $CONVERSATION_ID が設定されています。$PYLOT_API_TOKEN （セッション JWT）を使用してください。$PYLOT_DISPATCH_TOKEN は使用しないでください（オペレータートークンでは、このエンドポイントは意図的に 403 を返します。ここで使用するのは、pylot#2979 で修正される誤った動作そのものです）。

# immediate op
curl -s -X POST \
  -H "Authorization: Bearer $PYLOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"op\":\"$OP\"}" \
  "${PYLOT_API:-$PYLOT_GATEWAY_URL}/conversations/$CONVERSATION_ID/admin-action"

# confirm a staged op (after org admin replies with the code)
curl -s -X POST \
  -H "Authorization: Bearer $PYLOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"code\":\"$CODE\"}" \
  "${PYLOT_API:-$PYLOT_GATEWAY_URL}/conversations/$CONVERSATION_ID/admin-action/confirm"

自動化

pylot automations list           # inventory with run stats
pylot automations get <name>     # single rule detail

リポジトリごとの対象範囲：一覧の出力から only_repos／skip_repos をフィルタリングしてください。

自動化が実行する組織固有の管理者向けランブックは、このスキルではなく、その組織のリポジトリドキュメントとチームのプレイブック（pylot context <org/repo>）にあります。

指標と注釈

CLI 0.9.12 以降が必要です。

pylot measures list                                  # stored measures with latest version and grains
pylot measures points <measure> --grain day|week|month [--since] [--until] [--measure-version] [--scope <scope_ref>]
                                                     # read one measure series
pylot measures put --file points.json                # upsert a batch of points ({"points": [...]})
pylot annotations add --kind deploy|pause|incident|change|skill_update --start <iso> [--end <iso>] --label <text> \
  [--affects a,b] [--scope <scope_ref>] [--detail <text>] [--source-ref <ref>]
                                                     # record a dated event; no --end = an instant, --end = a period
pylot annotations list [--since] [--until] [--affects <measure>] [--include-superseded]
                                                     # annotations overlapping a range
pylot annotations supersede <id> --by <id>           # replace a wrong annotation (the log is append-only)

指標の定義、注釈の付与、チャート化、Objectives の評価方法については、pylot-objectives スキルを使用してください。

Slack チャネルのルーティング

メッセージのルーティング先として、Slack チャネルをチームに紐付けます。複数のチャネルを同じチームに紐付けることができます（多対1）。CLI が主なインターフェイスであり、同等の UI はありません。

# Bind a channel to a team (additive; channel must already be known to the bot)
pylot teams channels bind <channel-id> --team <team> [--org <org>]

# List all Slack channels with their bound team (null = unbound)
pylot teams channels list [--org <org>]

# Set the org-level fallback team for unbound channels
pylot orgs set-slack-default <team> --org <org>

# Clear the org-level fallback team
pylot orgs clear-slack-default --org <org>

デフォルトチームへのフォールバック：明示的な紐付けのないチャネルに Slack メッセージが届いた場合、組織レベルのデフォルトチームが設定されていれば、そのチームにルーティングされます。組織のデフォルトが設定されていない場合、紐付けのないチャネルからのメッセージは破棄されます。

非同期ウェイクパターン

--context conversation_id=… を指定してディスパッチすると、ミッションの終了時と PR のライフサイクルに応じて自動的にウェイクします。 セルフウェイクのフォールバック：pylot conversations wakes-add <conv-id> in_seconds=300 content="check X" ウェイクは一度に1つだけ設定し、重ねずに再スケジュールしてください。