name: using-gc\ndescription: 'Operate Gas City through its Mayor, registry packs and native run state. Use when: the caller explicitly selects Gas City; factory completion does not replace independent judgment.'\npractices: [team-topologies, design-by-contract]\nhexagonal_role: driving-adapter\nconsumes: [explicit-packets]\nproduces: [gas-city-runtime-evidence]\ncontext_rel:
\nUse Gas City only when the caller explicitly selects it. Treat it as a\nreplaceable execution adapter, not a correctness or completion boundary.\nThe adapter cannot select AgentOps semantics, issue a binding verdict, or turn factory completion into delivery or validation proof.
\nAgentOps supports both Gas City and the\nAgentic Coding Flywheel as external\nsoftware-factory runtimes. Use this skill only for Gas City. If the caller\nselects the Flywheel, switch to using-flywheel\nand its native workflow instead of wrapping it in Gas City.
\nAgentOps supplies skills and evidence contracts to either factory. It does not\nneed its own Gas City formula or role pack. Install or link AgentOps skills into\nthe provider runtime before starting workers; the upstream Mayor, coordinator,\nand workers can then discover and select plan, implement, test,\nvalidate, and other AgentOps skills normally.
Gas City 1.4 is run-centered. The supervisor serves the dashboard and typed,\npaginated session/run APIs. Every graph-owning city or rig scope needs its own\ncore.control-dispatcher; that deterministic worker advances formula control\nbeads. Agent workers claim routed work. The upstream gc.mayor skill is the\nguided coordinator; gc.run-operator launches and supervises formulas.
The normal AgentOps path is:
\ngascity workflow and rig-role imports.build-basic,\ncontinuation, review, or implementation formula that matches the available\nartifacts.Prepare and qualify a rig before its first build with the shipped AgentOps\nCLI (no repo checkout required):
\nao gc prepare --city /path/to/city --rig /path/to/rig\nao gc check --city /path/to/city --rig /path/to/rig\nThe command verifies the exact official workflow and role pins, snapshots the\nupstream validation scripts and schemas unchanged inside the rig's .gc\nruntime, installs only small AgentOps-owned wrappers at the formula check\npaths, selects an existing Python that can import PyYAML, and links the\nAgentOps skills into the city and rig Codex sinks. Skills come from the\nenclosing AgentOps checkout when one is present, otherwise from the installed\nskills root; pass --skills-source to pin a different directory. It never\nmodifies the GC binary, cache, formulas, roles, or upstream pack. check\nissues only native inspection commands, writes no adapter files, and fails\nbefore model spend when that runtime contract is missing or drifted.
prepare also pre-seeds Codex trust for every session directory that exists\nwhen it runs — the city and rig roots, each .gc/agents/** session home, and\neach rig worktree root — so a Codex session in one of those directories does\nnot block on the interactive trust dialog. Both persisted layers are seeded in\n$CODEX_HOME/config.toml: workspace trust ([projects.\"<dir>\"] trust_level = \"trusted\"), without which Codex silently reports that directory as having no\nhooks at all, and per-hook trust\n([hooks.state.\"<hooks.json>:<event>:<m>:<h>\"] trusted_hash = \"sha256:...\"),\nwhich is what the pack's per-provider .codex/hooks.json would otherwise\nprompt for. Hook digests are read back from Codex's own hooks/list, never\nrecomputed.
Trust is judged by value, not by the presence of a table. prepare appends\nonly entries that are missing and refuses, naming the entry, when one exists\nbut does not confer trust — an explicit trust_level = \"untrusted\", a hook\nCodex reports as changed since it was trusted, a recorded hook Codex still\nrejects, or a hook recorded enabled = false (a disabled hook is not a trusted\nworking hook). It never overwrites an operator decision, and re-running is a\nno-op. It also fails rather than continue if Codex returns an empty or\nunrecognized hook list. The trust store itself is never edited in place: the\nmerged content is parsed in memory first, then installed with the CLI's durable\natomic writer, so no failure path can leave a partially written Codex config.
ao gc check verifies the same pre-seed from local state only — it runs no\nCodex subprocess and writes nothing, deriving each expected hook key from the\ndirectory's own hooks.json — and names the specific deficient directory or\nhook using the same rule prepare seeds to.
Two named limitations.
\ncheck cannot detect a stale hash. Because it never asks Codex, a\nrecorded trusted_hash that no longer matches the hook's current content\nreads as satisfied and still raises the trust dialog in a real session. Only\nprepare sees that — Codex reports the hook as changed and prepare\nrefuses. A green check therefore means \"trust is recorded\", not \"trust is\nfresh\".prepare are not covered. Discovery is by\nfilesystem marker, so the guarantee covers session directories that exist at\nprepare time. A session home Gas City materializes later still carries\nuntrusted hooks on its first spawn; prepare names the configured agents\nthat have no home yet.The operational rule that follows from both: run prepare, start the city,\nthen run prepare again (it is idempotent) before dispatching.
The built-in main registry catalogs official packs. The community registry is\noptional configuration:
gc pack registry list\ngc pack registry refresh\ngc pack registry search --all\ngc pack registry show main:gascity\ngc pack registry add community https://registry.gascity.com/registry.toml\ngc pack registry search --registry community --all\nsearch reads the local registry cache; show reports release provenance and\nexact import commands. gc import add declares a source/version, and gc import install resolves it into packs.lock. Prefer an exact accepted release for\nreproducible cities.
AgentOps prefers the official gascity build pack, the workflow family visible\nin the public Maintainer City factory. The current accepted reference is\ngascity 0.1.6 at commit\n3b3b89f2011e06d84459aa7bea1552382f13930a:
https://factory.gascity.com;build-basic, build-from-*, implement, review, issue, and PR\nflows;gc.run-operator, gc.implementation-worker, planners,\nreviewers, and publisher;core.control-dispatcher;gc.mayor skill.Install the workflow pack at city scope and its sibling roles pack on every rig\nthat runs work, following the exact commands returned by\ngc pack registry show main:gascity. Keep the stock gc.* namespace; do not\nnest or rename the roles behind an AgentOps pack.
Work enters the city through the Mayor. The caller authors ONE source intent\nbead with acceptance, then hands the Mayor its id — the Mayor decomposes,\nauthors the workflow beads, and dispatches. The caller never runs gc sling\nitself; an operator-slung run bypasses the coordinator that owns retries,\nre-dispatch, and tending for that workflow.
gc bd create \"Add a --json flag to the export command\"\ngc mail send mayor -s \"Build ago-XXXX\" \\\n -m \"Decompose and launch build-basic for bead ago-XXXX with push=true open_pr=true.\" --notify\nOr, in an interactive Mayor session:
\nUse skill gc.mayor\nDirect gc sling remains a debugging tool for a city with no live Mayor; a\nrun started that way has no coordinator and the operator inherits its tending.
AgentOps skills are tools available to those factory agents, not a replacement\nworkflow. Explicitly name a skill in the bead or prompt when its behavior is\nrequired. The current upstream decomposition does not automatically propagate a\nfree-form Required Skills section from the caller-owned source bead into every\ngenerated work item. Inspect the decomposition before implementation; put a\nrequired skill name on the actual work item or worker prompt when its use is an\nacceptance condition. Skill presence and skill invocation are different facts.
Before starting its orchestrator, run once per city:
\ngc doctor --fix\ngc import install\ngc supervisor stop --wait # macOS when an older direct supervisor remains\ngc start\nThen confirm:
\ngc version reports 1.4.0 from the intended path;gc doctor has no blocking failures;core.control-dispatcher;packs.lock resolve;ao gc check accepts the contained maintainer runtime and\nAgentOps skill links;gc binary;A stale registered city may block every start. Repair that city with gc doctor --fix, or explicitly unregister it if it is intentionally retired.
Retire an old HQ/canary by exact registered name or path, without stopping the\nmachine-wide supervisor needed by its replacement:
\ngc cities --json\ngc stop /path/to/old-city --timeout 45s\ngc unregister /path/to/old-city\ngc cities --json\nunregister fails rather than silently accepting an unknown target. Preserve\nthe city directory until its Beads state is backed up or confirmed disposable.\nCreate the replacement from the upstream Gas City template, install its pinned\nimports, and verify it with gc cities --json, gc --city <new-city> status,\nand gc --city <new-city> doctor --json.
After handing intent to the Mayor, the orchestrator runs five verbs. Each verb\nhas one owner; crossing owners is the recurring failure class this section\nexists to stop.
\n| Verb | \nOwner | \nSurface | \n
|---|---|---|
| Monitor | \norchestrator | \n$API/runs/census and $API/runs/<run-id> on a fixed cadence, plus gc mail inbox for Mayor replies. failed > 0 in the census, a run in failed/canceled, or unread Mayor mail is the act signal; everything else is a tick. | \n
| Observe | \norchestrator | \nOn an act signal, walk the visibility layers in order — census, run detail, bead graph, session roster, pane truth — and stop at the first layer that explains. Do not start at pane truth. | \n
| Nudge | \norchestrator, once | \nA ready bead: dispatch once to its gc.run_target. A routed bead with a live session: gc session wake <run_target> once. A second nudge on the same subject means the diagnosis is wrong — mail the Mayor instead. | \n
| Redirect | \nMayor | \nPriority, 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. | \n
| Rework | \nGC first, then Mayor | \nFailed 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. | \n
Rework the orchestrator performs by hand (editing a failed run's worktree,\nre-slinging its formula, closing its beads) creates a second uncoordinated\nauthor for the same intent; the Mayor's relaunch then races it.
\nFirst classify the bead.
\nStill ready: dispatch it once to its gc.run_target, then stop and inspect.
Already routed/in progress: re-slinging is a NO-OP. Wake its owning worker\nonce:
\ngc session wake <run_target>\nThen capture the exact tmux pane named by session state and run gc doctor.\nNever repair a city from inside that city.
Never create pack-owned sessions by hand. gc session new for a singleton or\nscaled agent (core.control-dispatcher, role workers) makes a mis-scoped\nsession that squats the canonical name in start-pending and blocks the\nreconciler from spawning the real one — extending the exact stall being\nrepaired. Session lifecycle belongs to the reconciler and demand scaling.\nWhen the city itself needs tending (a stalled reconciler, sessions that never\nleave draining, model or provider rewiring), send the request to the Mayor:
gc mail send mayor -s \"<subject>\" -m \"<request with bead ids>\" --notify\nThe upstream pack may leave a future affinity-bound step assigned to a session\nthat has already drain-acked. Diagnose this only from outside the city:
\nao gc recover-affinity --city /path/to/city --rig /path/to/rig\nThe default is a dry run. If every listed assignment is correct, repeat with\n--apply. The bounded repair only clears the assignee on a currently ready\nformula bead whose gc.session_affinity=require session is no longer live. It\ndoes not sling, retry, close, restart, or select work.
Supervisor/run state — gc dashboard, run detail, gc status, and\ngc session list --json. Run detail unifies the stage ladder, structured\ntranscripts, token rate, and estimated burn rate. A roster may still report\nactive while a provider is wedged.
Programmatic run status comes from the supervisor's typed run API — the\nsame data the dashboard renders. gc status prints the API base; neither\ngc status --json nor any other CLI subcommand carries run objects.
API=\"http://127.0.0.1:<port>/v0/city/<city-name>\"\ncurl -s \"$API/runs/<run-id>\" # {run_id, title, status, target, scope, started_at, updated_at}\ncurl -s \"$API/runs/census\" # {status_counts: {pending, active, waiting, canceling, completed, failed, canceled, skipped}}\nPoll run status and census for progress; a nonzero failed count is the\nfirst machine-readable failure signal. The dashboard's run page\n(/city/<city-name>/runs/<run-id>) is the human view of the same objects.
Bead graph — gc bd --rig <rig> ready --json and show <id> --json.\nThis is workflow-state truth, but a claimed bead cannot reveal a wedged pane.
Pane truth — tmux -L <socket> capture-pane -pt <session>. This exposes\ntrust prompts, update nags, API/DNS failures, and interactive wedges. A pane\nparked on Codex's Do you trust the contents of this directory? (or the\nlater Press t to trust all hooks dialog) means that session directory was\nnot pre-seeded — the workflow queues dispatches as pending with no active\nworker and reports no error. Almost always the home was created after the\nlast ao gc prepare; re-run prepare, then restart that session.\nao gc check names the untrusted directory or hook before you spend a\ndispatch on it. Gas City also appears to auto-answer this dialog by sending\nkeys into the pane, so a wedge may clear on its own — treat that as a race\nyou do not want to depend on, not as a reason to skip the pre-seed.
Health machinery — gc doctor, gc order history, storage health, and\nevents. This proves metabolism, not semantic acceptance.
When layers disagree, trust the more direct observation: pane over roster for a\nsession wedge, bead/run state over prose for workflow completion.
\ngc status may return a partial no_agents_running snapshot while\ngc session list --json shows a live Mayor or worker. Treat that as an\nobservability disagreement, not permission to restart. Use session and pane\ntruth for liveness, bead/run state for workflow progress, and Doctor for\nmetabolism. A supervisor with abnormal CPU, a timed-out native stop, or a\nrecurring hook rewrite remains an upstream operational defect; this helper\nreports it but never kills or patches GC processes.
The caller-owned input bead and the generated workflow root have separate\nlifecycles. A successful build-basic run may close its workflow root while\nleaving the input bead open. Likewise, push=false and open_pr=false produce\na successful no-op publish while the approved commit remains in its source\nanchor worktree. Neither state is semantic completion by itself.
verdict.v2.gc mail (work dispatch and city tending both go to the Mayor),\ngc doctor [--fix], supervisor start/stop from outside,\nao gc prepare|check|recover-affinity, and reading state. The Mayor authors\nworkflow beads and dispatches; creating, scaling, or repairing pack-owned\nsessions by hand is outside the lane, and the reconciler owns session\nlifecycle.