git:20261021.933218a to git:20261025.a376884

---

name: using-gc

description: 'Operate Gas City through its own doors: Mayor, doctor and native run state. Use when: Gas City is selected or a gc run looks stuck.'

practices: [team-topologies, design-by-contract]

hexagonal_role: driving-adapter

produces: [gas-city-runtime-evidence]

context_rel:

skill_api_version: 1

user-invocable: true

metadata:

tier: execution

dependencies: []

effects: [operate_gas_city, configure_codex_trust]

canonical_status: canonical

disposition: keep_optional_adapter

---

# Using GC

## The operator lane

- author source intent beads;

- `gc mail` to the Mayor, for work dispatch and for city tending;

- `gc doctor [--fix]`, and supervisor start/stop from outside the city;

- `ao gc prepare|check|recover-affinity`;

- reading run, session, bead, pane and artifact state.

The Mayor authors workflow beads and dispatches them; it owns retries,

re-dispatch and tending for that work. Never create, scale or repair pack-owned

sessions by hand: `gc session new` for a singleton or scaled agent

(`core.control-dispatcher`, role workers) makes a mis-scoped session that

squats the canonical name in `start-pending` and blocks the reconciler from

spawning the real one. Session lifecycle belongs to the reconciler and demand

scaling. Direct `gc sling` is a debugging tool for a city with no live Mayor; a

run started that way has no coordinator, and the operator inherits its tending.

## Version facts

Gas City 1.4 is run-centered. The supervisor serves the dashboard and typed,

paginated session/run APIs. Every graph-owning city or rig scope needs its own

## Prepare and check a rig

Prepare and qualify a rig before its first build with the shipped AgentOps

CLI (no repo checkout required):

```sh

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

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

```

`prepare` verifies the exact official workflow and role pins, stages a

contained maintainer runtime inside the rig's `.gc` directory, links the

AgentOps skills into the city and rig Codex sinks, and pre-seeds Codex

workspace and hook trust for every session directory that exists when it runs.

Hook trust needs the Codex CLI on PATH (or `--codex-bin`). `check` is

read-only, runs no Codex subprocess, and fails before model spend when that

runtime contract is missing or drifted.

Run `prepare`, start the city, then run `prepare` again (it is idempotent)

before dispatching. Two limitations make that order necessary: `check` cannot

see a stale trust hash, so green means trust is recorded, not fresh; and a

session home created after `prepare` is not covered.

[Codex trust pre-seed](references/codex-trust-preseed.md) has the mechanism.

## Hand work to the Mayor

Work enters the city through the Mayor. The caller authors ONE source intent

bead with acceptance, then hands the Mayor its id; the Mayor decomposes,

authors the workflow beads, and dispatches.

```sh

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

```

Pass `push=true open_pr=true` only when the caller and the repository's

delivery policy authorize publishing; otherwise the approved commit stays in its

## Orchestrating through the Mayor: the tending loop

| Verb | Owner | Surface |

|---|---|---|

| Redirect | Mayor | Priority, scope, cancellation, or model/provider changes travel by mail with bead/run ids. The orchestrator never re-slings, edits workflow beads, or patches a live run. |

| Rework | GC first, then Mayor | Failed review findings re-enter the run through its native fix loop (`review_fix_formula`, default `fix-loop-base`); bounded gated retries are `gc converge` loops. Only a TERMINAL `failed`/`canceled` run — or a completed run whose result misses caller acceptance — goes back: mail the Mayor the run id and the failure evidence for re-decompose and relaunch. |

Rework the orchestrator performs by hand (editing a failed run's worktree,

re-slinging its formula, closing its beads) creates a second uncoordinated

author for the same intent; the Mayor's relaunch then races it.

## Stall protocol

First classify the bead.

- Still `ready`, never dispatched: dispatch belongs to the Mayor. Mail it the

bead id, then stop and inspect. Only with no live Mayor is

```sh

```

```sh

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

```

The upstream pack may leave a future affinity-bound step assigned to a session

that has already drain-acked. Diagnose this only from outside the city:

```sh

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

```

The default is a dry run. If every listed assignment is correct, repeat with

`--apply`. The bounded repair only clears the assignee on a currently ready

formula bead whose `gc.session_affinity=require` session is no longer live. It

does not sling, retry, close, restart, or select work.

## Visibility: four layers

1. **Supervisor/run state** — `gc dashboard`, run detail, `gc status`, and

`gc session list --json`. Run detail unifies the stage ladder, structured

transcripts, token rate, and estimated burn rate. A roster may still report

```sh

API="http://127.0.0.1:<port>/v0/city/<city-name>"

```

2. **Bead graph** — `gc bd --rig <rig> ready --json` and `show <id> --json`.

This is workflow-state truth, but a claimed bead cannot reveal a wedged pane.

3. **Pane truth** — `tmux -L <socket> capture-pane -pt <session>`. This exposes

trust prompts, update nags, API/DNS failures, and interactive wedges. A pane

parked on Codex's `Do you trust the contents of this directory?` (or the

later `Press t to trust all` hooks dialog) means that session directory was

not pre-seeded — the workflow queues dispatches as pending with no active

worker and reports no error. Almost always the home was created after the

4. **Health machinery** — `gc doctor`, `gc order history`, storage health, and

events. This proves metabolism, not semantic acceptance.

When layers disagree, trust the more direct observation: pane over roster for a

session wedge, bead/run state over prose for workflow completion.

`gc status` may return a partial `no_agents_running` snapshot while

`gc session list --json` shows a live Mayor or worker. Treat that as an

The caller-owned input bead and the generated workflow root have separate

## Boundaries

- GC quests, runs, attempts, stalls, cancellations, and internal close state

stay in GC. They never become AgentOps Plan, Candidate, RPI, or verdict state.

- A GC close or completed run is not AgentOps completion. Only a fresh Validate

context issues the semantic result or, when requested, persists `verdict.v2`.

- This skill performs no automatic selection, retry, semantic validation, Git,

integration, closure, release, or delivery.