using-gc

GC を使う

Gas City は、呼び出し元が明示的に選択した場合にのみ使用します。正しさや完了を判定する境界ではなく、交換可能な実行アダプターとして扱ってください。 このアダプターでは、AgentOps のセマンティクスを選択したり、拘束力のある判定を下したり、ファクトリーの完了を納品や検証の証明にしたりすることはできません。

オペレーターの操作範囲

都市でオペレーターが実行できる操作は、次のものに限定されます。

• ソース意図を表す bead を作成する。
• 作業の割り当てと都市の管理のために、gc mail で Mayor に連絡する。
• ルーティングされた bead のワーカーが停止した場合に、gc session wake <run_target> を一度実行する。
• 都市の外部から gc doctor [--fix] を実行し、スーパーバイザーを起動・停止する。
• ao gc prepare|check|recover-affinity を実行する。
• run、session、bead、pane、artifact の状態を読み取る。

Mayor はワークフロー bead を作成して作業を割り当てます。また、その作業の再試行、再割り当て、管理を担います。pack が所有する session を手動で作成、拡張、修復してはいけません。シングルトンまたは拡張されたエージェント（core.control-dispatcher、ロールワーカー）に対して gc session new を実行すると、スコープが誤った session が作成され、start-pending 状態で正規の名前を占有し、reconciler が本来の session を起動できなくなります。session のライフサイクルは reconciler と需要に応じたスケーリングが担います。直接の gc sling は、稼働中の Mayor がいない都市でのデバッグ用ツールです。この方法で開始した run にはコーディネーターがいないため、その管理はオペレーターが引き継ぎます。

まずファクトリーを選ぶ

AgentOps は、外部ソフトウェアファクトリーのランタイムとして Gas City と Agentic Coding Flywheel の両方をサポートします。このスキルは Gas City にのみ使用してください。呼び出し元が Flywheel を選択した場合は、Gas City でラップするのではなく、ネイティブのワークフローに従ってください。

AgentOps は、どちらのファクトリーにもスキルとエビデンスの契約を提供します。AgentOps 専用の Gas City formula やロール pack は不要です。ワーカーを起動する前に、AgentOps のスキルをプロバイダーのランタイムにインストールするか、リンクしてください。そうすれば、上流の Mayor、コーディネーター、ワーカーは通常どおり plan、implement、test、validate などの AgentOps スキルを見つけて選択できます。

バージョン情報

2026-10-04 時点の状況：gascity の pin（0.1.6、commit 3b3b89f2011e06d84459aa7bea1552382f13930a）は ao gc が適用する commit であり、レジストリの 0.1.6 リリースと一致します。このスキルに記載されている Gas City 1.4.0 のコマンド情報は、このリリースについて再検証されていません。gc version が 1.4.0 以外を報告する場合は、コマンドに依存する前に gc <command> --help でそれぞれ確認してください。

Gas City 1.4 の運用モデル

Gas City 1.4 は run を中心に動作します。スーパーバイザーは、ダッシュボードと、型付きのページ分割された session/run API を提供します。グラフを所有する各 city または rig のスコープには、それぞれ独自の core.control-dispatcher が必要です。この決定的なワーカーが formula の制御 bead を進めます。エージェントワーカーはルーティングされた作業を引き受けます。上流の gc.mayor スキルはガイド付きコーディネーターであり、gc.run-operator は formula を起動して監督します。

通常の AgentOps の手順は次のとおりです。

1. 上流の gascity ワークフローと rig-role の import をインストールし、バージョンを固定します。
2. プロジェクトを rig として追加し、標準のメンテナンス用ランタイムを準備して、AgentOps のスキルをそのプロバイダーの session から見えるようにします。
3. 呼び出し元が所有するソース意図 bead を作成し、その ID を Mayor に渡します。Mayor はワークフロー bead を作成し、利用可能な artifact に合った上流の build-basic、継続、レビュー、または実装の formula を割り当てます。
4. run、session、bead、artifact、判定の状態を読み取ります。チャットや pane の文章から完了を推測してはいけません。

リグを準備して確認する

初回ビルドの前に、同梱の AgentOps CLI を使ってリグを準備し、適格性を確認します（リポジトリのチェックアウトは不要です）。

ao gc prepare --city /path/to/city --rig /path/to/rig
ao gc check --city /path/to/city --rig /path/to/rig

prepare は、正確な公式ワークフローとロールのピン留めを検証し、リグの .gc ディレクトリ内に隔離されたメンテナーランタイムをステージングし、AgentOps スキルを city とリグの Codex シンクにリンクし、実行時に存在するすべてのセッションディレクトリに対して Codex のワークスペースとフックの信頼を事前登録します。フックの信頼には、Codex CLI が PATH 上にある必要があります（または --codex-bin を指定します）。check は読み取り専用で、Codex サブプロセスを実行せず、そのランタイム契約が欠落しているか、ドリフトしている場合は、モデルの利用料金が発生する前に失敗します。

prepare を実行し、city を起動してから、ディスパッチの前にもう一度 prepare を実行してください（冪等です）。この順序が必要なのは、2 つの制約があるためです。check では古い信頼ハッシュを検出できないため、成功している場合に確認できるのは信頼が記録済みであることだけで、最新であることは確認できません。また、prepare の実行後に作成されたセッションホームは対象外です。 Codex の信頼の事前登録にその仕組みが記載されています。

推奨パックとレジストリ

組み込みの main レジストリには、公式パックが登録されています。コミュニティレジストリの設定は任意です。

gc pack registry list
gc pack registry refresh
gc pack registry search --all
gc pack registry show main:gascity
gc pack registry add community https://registry.gascity.com/registry.toml
gc pack registry search --registry community --all

search はローカルのレジストリキャッシュを読み取ります。show はリリースの出所と正確なインポートコマンドを表示します。gc import add はソースとバージョンを宣言し、gc import install はそれを解決して packs.lock に登録します。再現性のある city を構築するには、承認済みの正確なリリースを使用してください。

AgentOps では、公開されている Maintainer City ファクトリーで確認できるワークフローファミリーの、次の承認済みリファレンスにある公式 gascity ビルドパックを推奨しています。

• ダッシュボード：https://factory.gascity.com；
• ワークフロー：build-basic、build-from-*、implement、review、issue、PR の各フロー；
• 標準リグのロール：gc.run-operator、gc.implementation-worker、プランナー、レビュー担当者、パブリッシャー；
• スコープ内のフォーミュラ制御：core.control-dispatcher；
• ガイド付きの調整：上流の gc.mayor スキル。

city スコープにはワークフローパックをインストールし、作業を実行するすべてのリグには、その姉妹ロールパックをインストールしてください。gc pack registry show main:gascity が返す正確なコマンドに従ってください。標準の gc.* 名前空間を維持し、ロールを AgentOps パックの中に入れたり、名前を変更したりしないでください。

Mayor に作業を引き渡す

作業は Mayor を通じて city に入ります。呼び出し元は受け入れ条件を記載したソースインテントのビードを 1 つ作成し、その ID を Mayor に渡します。Mayor が作業を分解してワークフローのビードを作成し、ディスパッチします。

gc bd create "Add a --json flag to the export command"
gc mail send mayor -s "Build ago-XXXX" \
  -m "Decompose and launch build-basic for bead ago-XXXX with push=false open_pr=false." --notify

公開が呼び出し元とリポジトリのデリバリーポリシーで許可されている場合に限り、push=true open_pr=true を渡してください。それ以外の場合、承認済みのコミットはソースアンカーのワークツリーに留まります。

または、対話型の Mayor セッションで次のようにします。

Use skill gc.mayor

AgentOps スキルは、これらのファクトリーエージェントが利用できるツールであり、ワークフローの代わりではありません。その動作が必要な場合は、ビードまたはプロンプトでスキルを明示的に指定してください。現在の上流の分解処理では、呼び出し元が所有するソースビードの自由記述の Required Skills セクションは、生成されるすべての作業項目に自動的には引き継がれません。実装の前に分解結果を確認し、スキルの使用が受け入れ条件である場合は、実際の作業項目またはワーカーのプロンプトに必要なスキル名を記載してください。スキルが存在することと、スキルが呼び出されることは別の事実です。

既存の都市を 1.4 にアップグレードする

オーケストレーターを起動する前に、都市ごとに一度だけ実行します。

gc doctor --fix
gc import install
gc supervisor stop --wait   # macOS when an older direct supervisor remains
gc start

次に、以下を確認します。

• gc version が、意図したパスから 1.4.0 を報告すること。
• gc doctor にブロッキングエラーがないこと。
• グラフを所有する各リグに、停止されていない core.control-dispatcher があること。
• インポートと packs.lock が解決されること。
• ao gc check が、内包されたメンテナーランタイムと AgentOps スキルのリンクを受け入れること。
• macOS では、スーパーバイザーの LaunchAgent が、選択した gc バイナリと同じ実行ファイルを参照すること。
• 古いスタンドアロンダッシュボードのブックマークやリバースプロキシが削除されていること。

古い登録済み都市がすべての起動を妨げることがあります。その都市で gc doctor --fix を実行して修復するか、意図的に廃止する場合は明示的に登録を解除してください。

古い HQ／canary を正確な登録名またはパスで廃止します。後継に必要なマシン全体のスーパーバイザーは停止しないでください。

gc cities --json
gc stop /path/to/old-city --timeout 45s
gc unregister /path/to/old-city
gc cities --json

unregister は、未知の対象を黙って受け入れるのではなく、失敗します。Beads の状態をバックアップするか、破棄しても問題ないと確認するまで、都市のディレクトリを保持してください。アップストリームの Gas City テンプレートから後継を作成し、固定されたインポートをインストールして、gc cities --json、gc --city <new-city> status、gc --city <new-city> doctor --json で検証します。

Mayor を介したオーケストレーション：テンダリングループ

Mayor に意図を伝えた後、オーケストレーターは 5 つの動詞を実行します。各動詞の担当は 1 つです。担当者間の越境は、このセクションで防止しようとしている、繰り返し発生する失敗パターンです。

動詞	担当者	窓口
監視	オーケストレーター	一定の間隔で $API/runs/census と $API/runs/<run-id> を確認し、Mayor の返信は gc mail inbox で確認します。国勢調査で failed > 0 の場合、実行が failed／canceled の場合、または Mayor からの未読メールがある場合は対応シグナルです。それ以外はティックです。
観察	オーケストレーター	対応シグナルがあったら、可視性レイヤーを順番にたどります。国勢調査、実行の詳細、ビードグラフ、セッション一覧、ペインの状態の順です。原因を説明できる最初のレイヤーで確認を止めます。ペインの状態から調べ始めてはいけません。
ナッジ	オーケストレーターが 1 回	ルーティング済みのビードにアクティブなセッションがある場合は、gc session wake <run_target> を 1 回実行します。誰もディスパッチしていない ready 状態のビードは、その ID をメールで Mayor に伝えます。ディスパッチは Mayor が行います。同じ対象への 2 回目のナッジが必要なら、診断が間違っています。代わりに Mayor へメールしてください。
リダイレクト	Mayor	優先度、スコープ、キャンセル、モデル／プロバイダーの変更は、ビード／実行 ID とともにメールで伝えます。オーケストレーターが再スリングしたり、ワークフローのビードを編集したり、実行中の実行にパッチを適用したりしてはいけません。
やり直し	まず GC、次に Mayor	失敗したレビューの指摘は、実行に組み込まれた修正ループ（review_fix_formula、デフォルトは fix-loop-base）を通じて再投入します。制限付きのゲート付き再試行は gc converge ループで行います。ターミナル状態が failed／canceled の実行、または完了していても結果が呼び出し元の受け入れ条件を満たさない実行に限り、差し戻します。再分解と再起動のために、実行 ID と失敗の証拠を Mayor にメールしてください。

オーケストレーターが手作業でやり直す（失敗した実行のワークツリーを編集する、その式を再スリングする、そのビードをクローズする）と、同じ意図を扱う、連携されていない 2 つ目の担当者が生まれます。その結果、Mayor による再起動と競合します。

停滞への対処プロトコル

まず bead を分類します。

• ready のままで、一度もディスパッチされていない場合：ディスパッチは Mayor の役割です。bead id を Mayor にメールで送り、その後、状況を確認します。稼働中の Mayor がいない場合に限り、gc sling <run_target> <bead-id> を一度実行することがデバッグ用の代替手段となり、その後はオペレーターがその実行の管理を引き継ぎます。

• すでにルーティング済み、または進行中の場合：再度 sling しても NO-OP です。所有するワーカーを一度起こします。

  gc session wake <run_target>
  

次に、セッション状態で指定された正確な tmux ペインを取得し、gc doctor を実行します。Codex の信頼確認ダイアログが表示されたままのペインは、そのホームで事前シードが行われていないことを意味します（下記のペインの実態を参照）。その都市の内部から都市を修復してはいけません。停滞への対処として gc session new を実行してはいけません。その理由は上記のオペレーター用レーンで説明しています。

一度起こしても停滞が解消しない場合、または都市自体の管理が必要な場合（リコンサイラーの停滞、セッションが draining から抜けない、モデルやプロバイダーの再配線）は、bead id または run id を添えて Mayor に依頼を送ります。

gc mail send mayor -s "<subject>" -m "<request with bead ids>" --notify

アップストリームのパックにより、将来のアフィニティ制約付きステップが、すでに drain-ack したセッションに割り当てられたままになることがあります。これは都市の外部からのみ診断してください。

ao gc recover-affinity --city /path/to/city --rig /path/to/rig

デフォルトではドライランが実行されます。表示された割り当てがすべて正しい場合は、--apply を付けて再実行してください。この範囲を限定した修復では、gc.session_affinity=require のセッションが稼働していない場合に、現在 ready 状態にある formula bead の担当者のみを解除します。sling、再試行、クローズ、再起動、作業の選択は行いません。

可視性：4 つのレイヤー

1. Supervisor／実行状態 — gc dashboard、実行の詳細、gc status、および gc session list --json。実行の詳細では、ステージの流れ、構造化された トランスクリプト、トークンレート、推定消費レートが統合されています。プロバイダーが 応答しなくなっていても、ロスターではアクティブと報告される場合があります。

   プログラムから取得する実行ステータスは、Supervisor の型付き実行 API から取得します。 ダッシュボードが表示するデータと同じものです。gc status は API のベース URL を表示します。 gc status --json を含め、どの CLI サブコマンドも実行オブジェクトを返しません。

   API="http://127.0.0.1:<port>/v0/city/<city-name>"
   curl -s "$API/runs/<run-id>"   # {run_id, title, status, target, scope, started_at, updated_at}
   curl -s "$API/runs/census"     # {status_counts: {pending, active, waiting, canceling, completed, failed, canceled, skipped}}
   

   進捗を確認するには、実行ステータスとセンサスをポーリングします。failed の数が 0 以外であれば、 それが機械可読な最初の失敗シグナルです。ダッシュボードの実行ページ （/city/<city-name>/runs/<run-id>）は、同じオブジェクトを人が確認するための画面です。

2. Bead グラフ — gc bd --rig <rig> ready --json および show <id> --json。 これはワークフロー状態の正確な情報源ですが、claim 済みの Bead からはペインの応答停止を 検出できません。

3. ペインの実態 — tmux -L <socket> capture-pane -pt <session>。これにより、 信頼を求めるプロンプト、更新の通知、API／DNS の失敗、対話中の応答停止を確認できます。 ペインに Codex の Do you trust the contents of this directory?（または後から表示される Press t to trust all フックのダイアログ）が表示されたままの場合、そのセッションディレクトリは 事前にシードされていません。ワークフローはディスパッチを保留としてキューに入れ、アクティブな ワーカーがいない状態でエラーも報告しません。ほとんどの場合、最後の ao gc prepare の後に ホームが作成されています。prepare を再実行してから、そのセッションを再起動してください。 ao gc check は、ディスパッチを実行する前に、信頼されていないディレクトリまたはフックを 示します。Gas City はペインにキーを送信してこのダイアログに自動応答するようにも見えるため、 応答停止が自然に解消する場合があります。これを頼りにしたくない競合状態として扱い、 事前シードを省略する理由にしないでください。

4. ヘルス管理機構 — gc doctor、gc order history、ストレージのヘルス状態、 イベント。これは代謝を確認するものであり、意味的な受け入れを確認するものではありません。

レイヤー間で食い違いがある場合は、より直接的な観測結果を優先してください。セッションの応答停止には ロスターよりペインを、ワークフローの完了には説明文より Bead／実行状態を優先します。

gc status が部分的な no_agents_running スナップショットを返す一方で、 gc session list --json には稼働中の Mayor またはワーカーが表示されることがあります。 これは可観測性の食い違いとして扱い、再起動してよいという許可とは見なさないでください。 稼働状況にはセッションとペインの実態を、ワークフローの進捗には Bead／実行状態を、 代謝には Doctor を使ってください。異常な CPU 使用率、タイムアウトしたネイティブ停止、 または繰り返し発生するフックの書き換えがある Supervisor は、引き続き上流の運用上の不具合です。 このヘルパーはそれを報告しますが、GC プロセスを終了したり、パッチを適用したりすることはありません。

呼び出し元が所有する入力 Bead と、生成されたワークフローのルートは、それぞれ別のライフサイクルを 持ちます。build-basic の実行が成功すると、入力 Bead をオープンのままにしてワークフローのルートを クローズすることがあります。同様に、push=false と open_pr=false の場合、承認済みコミットが ソースアンカーのワークツリーに残ったまま、公開処理は成功扱いの何もしない操作になります。 いずれの状態も、それだけでは意味的な完了を示しません。

境界

• GC のクエスト、実行、試行、停滞、キャンセル、内部のクローズ状態は GC 内に留まります。 AgentOps の Plan、Candidate、RPI、または判定の状態になることはありません。
• GC のクローズや実行の完了は、AgentOps の完了を意味しません。意味的な結果を出すのは、 新しい Validate コンテキストのみです。要求された場合は、verdict.v2 も永続化します。
• このスキルは、自動選択、再試行、意味的検証、Git 操作、統合、クローズ、リリース、 デリバリーを実行しません。
• 上記のオペレーターの担当範囲以外は、すべて Mayor またはリコンサイラーの担当です。