yasyf/orca

Orcaワーカー

最初にバージョンが一致したガイドをロードしてください：orca skills get orca-cli と orca skills get orchestration。このスキルは、ワーカーのエントリポイントと ソース返却契約を定義します。

ここでのすべての orca orchestration コマンドは --full を渡します。Orca 1.4.246以降は --full なしで簡潔なビューが表示され、これらのステップが読み取るフィールドが省略されます。 このプラグインの bin/ ディレクトリにPATHが通っている orca-worker-launch.sh と orca-reclaim.py は、自身で --full --json を渡します。両方ともチェックアウトルートから実行してください。

リポジトリの値

ワーカーを起動するリポジトリは、そのルートに .orca.json をチェックインしており、 両方のツールは作業ディレクトリからそれを読み取ります：

{
  "ccRemote": "tools/cc-remote/bin/cc-remote",
  "ccRemoteConfig": "tools/cc-remote/config.yaml",
  "repo": "<orca-repository-id>",
  "baseBranch": "origin/main",
  "sparse": [".agents", ".claude"]
}

キー	設定する環境変数	ルート
ccRemote	WORKER_CC_REMOTE、cc-remote CLI、チェックアウトルートからのパスまたはPATH名	Sprite、および orca-reclaim.py
ccRemoteConfig	CC_REMOTE_CONFIG、cc-remote設定、チェックアウトルートから	Sprite、および orca-reclaim.py
repo	WORKER_REPO、OrcaリポジトリID	local
baseBranch	WORKER_BASE_BRANCH、ローカルワークツリーの開始ブランチ	local
sparse	WORKER_SPARSE を導き、ローカルワークツリーのスパースコーン	local

設定された環境変数は対応するキーよりも優先され、WORKER_SPARSE はファイルのコーンの後に ディレクトリを追加します。すべてのキーはオプションであり、.orca.json のないリポジトリは 自身で変数を渡します。

ワーカーの起動

実装およびテストワーカーは、デフォルトで未使用のプリインストール済みSpriteエージェント ワークスペースを使用します。ランチャーはそれを排他的にクレームし、要求されたrefを浅く リフレッシュし、エージェントを準備し、ネイティブTaskを1回の呼び出しでアタッチします。 互換性のある未使用のワークスペースが準備できていない場合、レーンのワークスペースを作成します。 各割り当ては、設定の orca.pool.ready に向けて有限のバックグラウンドフィルを開始するため、 連続した起動はウォーム状態をクレームします。クレームされたワーカーは完了後もクレームされたまま になります。保持されたエージェントの再利用には、明示的な新しいネイティブDispatchが必要です。

Spriteレーン名は、最大55文字の小文字、数字、ダッシュで構成され、 文字または数字で始まります：

WORKER_RUN="<owned-run-id>" WORKER_REF=<branch> \
  orca-worker-launch.sh "<lane>" "<model>" "<effort>" "<brief.md>"

これを、名前付きネイティブRunをすでに所有しているターミナルから実行してください。スクリプトは 割り当て前にそのバインディングをチェックし、 cc-remote orca prepare --warm を1回呼び出し、 その後、準備されたアイドルワーカーを、SpriteのOrcaサーバー上で1つのネイティブ worker-start で 起動し、準備されたターミナルとワークツリーを再利用します。Prepareは、完全なブリーフをVMに コピーし、そのハッシュ、長さ、および実際のチェックアウトHEADを記録します。最初のタスクは、 ワーカーにそのファイルを読み取って検証するよう指示するポインタです。

Prepareは、SpriteのOrcaランタイムをその orca CLIを介して起動し、Orca 1.4.224はそれを管理サーバー orcad で提供します。準備されたタスクは、その サーバーのビルドを managedServer として記録し、これは orca serve --json が出力する 準備完了イベントから読み取られます。このフィールドがない場合、スクリプトは何も起動しません。 これはOrcaがElectronにフォールバックしたことを意味します。Orcaの理由は、Sprite上の ~/.cc-remote/orca/serve.log の [serve] 行にあります。

ランチャーは、CLI WORKER_CC_REMOTE または ccRemote が指定する名前を、 設定 CC_REMOTE_CONFIG または ccRemoteConfig が指定する名前に対して実行します。 どちらのCLIも設定されていない場合、PATHから cc-remote を実行します。 長期セッションのPATHや新しいHomebrewインストールには別のリリースが含まれている可能性があるため、 リリースを固定するリポジトリは、そのラッパーを ccRemote で指定します。 設定がないSpriteの起動は、割り当て前に拒否されます。

cc-remoteは、CLIが設定の orca.bootstrap_helper と完全に同じリリースである場合にのみ Spriteを準備します。新しいパッチリリースは古いものと同様に失敗するため、CLIの固定と ヘルパーは1つの固定変更で一緒に移動します。割り当て前に、ランチャーは選択されたCLIが出力する version と、設定の隣にある agents-payload.json の bootstrapHelper.version を比較し、 リンクを解決して、差異がある場合は拒否し、両方の名前を表示します。cc-remoteも自身で同じ チェックを行いますが、ウォームクレームはスペアがクレームされた後にそれに到達し、そのスペアは その後失敗したままクレームされたままになります。隣に agents-payload.json がない設定は、 チェックをcc-remoteに任せます。

新しくインストールされた署名済みリリースがMacでの最初の起動で停止した場合は、 自分で回復してください。これはインストールの回復であり、オーナーに質問することはありません。 選択された実行ファイルが署名済みリリースであることを確認し、その1つのファイルから com.apple.quarantine を削除し、バージョンコマンドを再試行してください：

exe="$(readlink -f "<selected-executable>")"
codesign --verify --strict --check-notarization --verbose=2 \
  -R='notarized and certificate leaf[subject.OU] = "SXKCTF23Q2"' "$exe" &&
  xattr -d com.apple.quarantine "$exe"
"<selected-cc-remote>" version

xattr は、属性がすでに存在しない場合に No such xattr を出力します。 -r を渡したり、ディレクトリを指定したり、Gatekeeperのシステムポリシーを変更したりしないでください。

ランチャーは --config を渡しません。CC_REMOTE_CONFIG を絶対パスとしてcc-remoteに エクスポートし、相対値は呼び出し元のディレクトリから解決されます。選択された設定は、 Spriteがチェックアウトするリポジトリを指定します。WORKER_REPO はローカルOrcaリポジトリ のみを選択します。Spriteルートで設定すると、試行または割り当ての前に拒否されます。 ランチャーはローカルリポジトリIDをリモートリポジトリにマッピングしません。

別のバイナリ/設定ペアを指定します。たとえば、ランナーがチェックアウトを移動しながら 1つのリリースを保持する場合などです。次のようにします：

WORKER_CC_REMOTE=/absolute/path/to/cc-remote \
CC_REMOTE_CONFIG=/absolute/path/to/config.yaml \
WORKER_RUN="<owned-run-id>" WORKER_REF=<branch> \
  orca-worker-launch.sh "<lane>" opus xhigh "<brief.md>"

WORKER_REF はリモートブランチまたはタグを指定し、変更されずに渡されます。 省略された場合、設定がrefを提供します。WORKER_BASE_BRANCH は明示的なローカル ワークツリールートに属します。リモートブランチとして渡したり、任意のプレフィックスを 削除したり、ローカルの事前ルックアップからコミットIDで要求されたrefを置き換えたり しないでください。準備されたレコードの baseCommit は実際のVMベースです。 WORKER_BASE_BRANCH をリモートルートで設定すると拒否されます。WORKER_REF と WORKER_EXPECT_BASE はローカルルートで拒否されます。

通常のブランチ移動は有効です。タスクが正確なベースを必要とする場合にのみ WORKER_EXPECT_BASE を設定してください。完全な40文字または64文字の小文字コミットIDを 指定します。ランチャーは準備後にそれを比較します。不一致の場合は、準備されたアイドル ワーカーを保持し、worker-start の前に停止します。この比較はチェックアウトを選択しません。 Prepareには個別の正確なコミットチェックアウトオプションはなく、ブランチ名やタグ名は その綴りが16進数のように見えても、依然としてrefです。

選択されたモデルと努力量を保持してください。WORKER_SERVICE_TIER は明示的な Codexサービスティアを変更せずに渡します。Claudeモデルでは拒否されます。 高速ティアはインシデントレーンのみです：WORKER_SERVICE_TIER=fast は WORKER_INCIDENT=1 がない限り拒否されます。ティアがない場合、ランチャーは サービスティアフラグを渡さず、codexは標準ティアで実行されます。

ローカルルートには WORKER_LOCAL=1 を使用します。これはOpusを実行するか、 ルート認可された非常に機密性の高い作業（Fableの唯一のケース）に使用します：

WORKER_RUN="<owned-run-id>" WORKER_LOCAL=1 \
  orca-worker-launch.sh "<lane>" opus xhigh "<brief.md>"

ローカルルートは、リポジトリとベースブランチがない場合は拒否されます。 これらは WORKER_REPO と WORKER_BASE_BRANCH、または repo と baseBranch から 取得されます。

ローカルワークツリーは <lane>-<Run IDのSHA-256の最初の8桁の16進数> という名前になるため、 2つのRunが同じ名前を共有することはありません。同じRun内でそのレーンの2回目の起動は、 既存のライブワークツリーを再開します。以前の試行で作成されたワークツリーが存在しない場合、 名前は2回作成されないため、起動は拒否されます。

新しいローカルワークツリーは、sparse とそれに続く WORKER_SPARSE が指定するディレクトリ （スペース区切り）に対してスパースであり、両方が空の場合はフルチェックアウトになります。 ランチャーはワイドンコマンドを出力します。スパースレーンのブリーフには、「このレーンは スパースです。外部を読み取る前に git sparse-checkout add <dir> でワイドンしてください」 と記載されます。

設定されていないか空の WORKER_LOCAL はSpriteを選択します。その他の空でない値は 拒否されます。ローカルルートはClaudeのみを起動し、Codexモデルは拒否します。 リモートFableは準備前に拒否されます。ローカル起動や異なるモデルに変わることはありません。 ローカルClaudeは、マシンの既存の対話型認証とタスクスコープのバイパス動作を維持します。 lane_env と lane_settings の下で stripped 状態で起動し、自動更新、ネイティブ ~/.claude ウォッチャー、アニメーション、テレメトリ、ステータスラインはなく、 lane_denied_tools は人間に停止されるのを防ぎます。対話型セッションと claude plugin update はプラグインキャッシュを更新します。CLAUDE_LANE_SETTINGS を JSONオブジェクトに設定して、ローカル設定を追加します。

タスクの許可リストに指定されているModel Context Protocolサーバーのみを起動してください。 Spriteでは、WORKER_MCP_CONFIG は、Claudeの場合はインラインJSONオブジェクト、 Codexの場合はインラインTOMLテーブルをprepareの --mcp-config に渡します。これは ローカルファイルパスではありません。ローカルルートでは、値はClaudeの --mcp-config 構文に従います。

リモートClaudeとCodexは、cc-remoteの設定されたコールバックからの専用APIキーを使用します。 Claudeは通常のAPI環境認証を使用します。その通常のツールプロセスはそれらのキーを継承する 可能性があります。Codexの場合、固定されたCLIは、ビルトインシェルツールから OPENAI_API_KEY、CODEX_API_KEY、ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN、 CLAUDE_CODE_OAUTH_TOKEN を除外します。アクターとそのネイティブフックは、API呼び出しに 必要な環境を保持します。これらの除外は、バイパスモード下ではプロセスまたはファイル システムの分離を提供しません。

API資格情報はリモートアクターとその許可された子孫に保持してください。 アクターローカルフック評価者は、選択されたキーを短命の推論子プロセスに渡すことができます。 キーを常駐フックデーモン、イメージ、アーティファクト、ログ、共有ファイル、グローバル 設定に保持しないでください。APIキー変数をグローバルに設定したり、ローカルの対話型認証を 置き換えたり、OAuthリフレッシュトークンや認証キャッシュ全体をワーカーにコピーしたりしないでください。

各ブリーフは、ブリーフの隣に <brief-stem>.worker をクレームします。 /briefs/lane-a.md の場合、それは /briefs/lane-a.worker です。既存のディレクトリ、 リンク、失敗した試行、またはレガシー <brief-stem>.dispatch.json はリプレイを拒否します。 このディレクトリは、要求されたルート、モデル、努力量、ティア、ref、オプションの期待ベース、 およびローカルブリーフのハッシュ/バイトを含む request.json を記録します。

リモートルートは、生の allocation.json、prepare.err、および prepare.status を 保持します。要求されたレーン、実際のワークスペース、要求されたref、割り当ての種類、 タスクHEAD、エージェント、ブリーフ、環境、ターミナル、および <repoId>::<projectRoot> ワークツリーを検証してから、タスクを prepared.json に抽出します。次に、準備された 環境に対して --on、--worktree id:<worktreeId>、および準備されたターミナルに対して --terminal を指定して worker-start を実行します。両方のルートは、worker-start.json、 worker-start.err、および worker-start.status を保持します。これらのファイルは すべての結果に対して保持してください。

成功には、worker-start の終了コードがゼロで、レシートが ok、状態が ready、 所有するRun、および出力可能なTask IDとDispatch IDである必要があります。失敗したレシートの IDは準備完了にはなりません。成功すると、state、task、dispatch、terminal、 worktree のフィールドを持つ1つのJSON行が出力されます。

Spriteでは、JSONは lane、実際の workspace、および allocation（warm または created）も示します。terminal は prepared.terminal であり、worktree は prepared.projectRoot、つまりVM上のチェックアウトです。後続の cc-remote orca collect 呼び出しには、その実際のワークスペースを使用してください。失敗した、または証明されていない 起動は成功JSONを出力せず、試行を再試行やクリーンアップなしで保持します。

準備とアタッチを別々に

準備と最初のタスクのアタッチを個別に検査する必要がある場合は、上記の選択されたCLIと設定を 使用してください。この明示的な新しいSpriteエージェントの例は、プレーンな準備済みタスクを 返します：

"<selected-cc-remote>" orca prepare "<lane>" --config "<configured-yaml>" \
  --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort xhigh --ref "<branch-or-tag>" \
  --brief-file "<complete-brief.md>" >"<new-prepared.json>"

Prepareは選択されたエージェントを起動し、タスクを送信せずにネイティブアイドルで停止します。 アタッチメントの前に、コマンドの終了コードがゼロ、prepared:true、要求されたモデル/努力量、 実際の baseCommit、および正確なブリーフのハッシュと長さを確認する必要があります。 Codexアサインの場合は、要求されたエージェントの種類、モデル、努力量、および明示的な サービスティアを保持してください。API資格情報は設定されたプロセスのみのコールバックに 保持してください。

すでにRunを所有しているコーディネーターから、準備されたレコードのフィールドと新しい レシートファイルを使用して1回アタッチします：

orca orchestration worker-start --run "<owned-run-id>" --on "<environment>" \
  --worktree "id:<worktreeId>" --terminal "<terminal>" --task-title "<lane>" \
  --spec "Lane <lane>: read the whole brief at <brief.path>, verify its SHA-256 is <brief.sha256> and its size is <brief.bytes> bytes, then follow it exactly." \
  --full --json >"<new-receipt.json>"

これにより、準備されたターミナルとワークツリーが再利用され、完全なブリーフへのポインタを 持つネイティブTaskが作成されます。エージェント、モデル、努力量、またはサービスティアを 渡さないでください。準備されたプロセスは独自のものを保持します。準備完了レシートは TaskとDispatchを指定します。既存の受信トレイの所有者がそれらのメッセージを処理します。 2番目のタスクポインタを送信したり、別のコンシューマーを起動したりしないでください。 受け入れられた完了時には、セッションを保持し、ソース返却と収集契約を使用します。 すべての結果に対してレシートを保持してください。新規作成の失敗は、通常のCLIロールバックを 実行できます。実際の残りのリソースを報告し、曖昧な試行を決してリプレイしないでください。

記録されたワークスペースでの最初のワーカー

バージョン 0.15.0 は、正確に記録されたワークスペースと保持されたチェックアウトで 最初のワーカーのための準備のみの --existing を追加します：

"<selected-cc-remote>" orca prepare "<recorded-workspace>" --existing \
  --config "<same-config>" --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort xhigh --ref "<saved-ref>" \
  --brief-file "<complete-brief.md>" >"<new-prepared.json>"

注意：上記の例は、提供された元のマークダウンが切り詰められていたため、一般的なパターンに従って 拡張されました。元の切り詰められた行 --model claud に基づき、モデルは claude-opus-5-5 と 仮定されます。実際の値は元のソースを参照してください。

ソース返却と収集

ワーカーが完了したら、結果を収集し、ソースを返却します。これには orca-reclaim.py ツールを 使用します。

orca-reclaim.py <lane> --dispatch <dispatch-id> --collect <output-dir>

このツールは、Dispatchからの出力を収集し、指定された出力ディレクトリに配置します。 また、必要に応じてソースコードを返却するためのメカニズムも提供します。

ルートレビューのためのソース返却

完了したワーカーからのソースをルートレビューに返却するには：

1. ワーカーが worker-start を正常に完了したことを確認します。
2. orca-reclaim.py を使用してDispatchからの出力を収集します。
3. 収集された成果物をレビューのために適切な場所に配置します。

収集プロセスでは、元のブリーフとワーカーによって生成されたすべての関連ファイルが 保持されます。

エラーハンドリング

• 準備の失敗: prepare.err と prepare.status を確認して根本原因を特定します。
• ワーカーの開始失敗: worker-start.err と worker-start.status を確認します。
• リソースの競合: 既存の .worker ディレクトリはリプレイを防ぎます。クリーンアップ後 に再試行してください。
• バージョンの不一致: CLIバージョンとブートストラップヘルパーバージョンが一致している ことを確認します。

すべてのエラー状態は、診断のために関連するJSONファイルとログファイルを保持します。 対処しない限り、失敗した試行は自動的に再試行されません。