using-gc

Using Gas City — the operator loop

Gas City (gc, the gastownhall/gascity engine) is a blessed, coexisting orchestration substrate for city-shaped work: durable agents in their own tmux sessions, work as beads in a gc-managed bd/dolt store, an orchestrator that spawns/retries/drives formula graphs outside your session and survives your session dying. AgentOps composes its verification membrane on top as the agentops-membrane pack — the fail-closed, cross-family, verdict-bound close door stock gc lacks (see gc-membrane).

Settled doctrine: stock gc is the substrate; AgentOps is the membrane. Use gc's orchestration wholesale (store, DAG, worktrees, pools, orders, dashboard, doctor). Never rebuild it. The membrane is the one add-on.

Critical Constraints

• gc coexists BESIDE NTM/ao — it is NOT a swap for NTM and there is no runtime=gc in AgentOps (severed, soc-2rtm0). No gc subcommand lives under the ao CLI, ever. This skill routes to gc's own native surface (gc status --json, gc events, gc doctor --json, gc session …) and never wraps it. Why: operator-selected substrates remain replaceable instead of leaking into the product CLI.
• LAW 0 applies inside a city: gc's builtin claude provider defaults to print_args = ["-p"] (headless title-gen + gc prompt sinks). Every city MUST set [providers.claude] print_args = [] (and the same on antigravity), guarded by the law0-print-args doctor check. Why: print mode burns metered API quota and is forbidden on this host.
• The membrane never merges. CONFIRMED closes the quest bead; a human merges the branch. No convenience crosses that line. Why: verification authority and integration authority remain separate.
• Use the current agent and local shell unless the operator explicitly selects a city or one of its portable lanes. Why: reading this entrypoint does not auto-start GC, NTM, Agent Mail, or managed agents.
• WARN|FAIL|REFUTED -> AUTO-REDO: consult the pawl, preserve the verdict/findings, and let the bounded city redo route run. Why: a negative quest verdict is loop evidence, not a human andon or permission to hand-close.
• BREAKER -> HOLD -> ONE-HELPER; HELPER-UNSTUCK -> AUTO-REDO. Hold the quest and use one bounded local-shell helper to inspect city/store/lane health. Why: one recovery pass can separate substrate failure from a real acceptance stop.
• HELPER-ESCALATE -> HUMAN; REFUSAL-LANE|EXPLICIT-JUDGMENT|EXHAUSTED-BUDGET -> HUMAN. Why: exhausted attempts, risk acceptance, merge authority, or unresolved refusal belongs to the operator.

Optional portable lanes

Inside an explicitly selected city, a bounded quest role may delegate through the same AgentOps ports used elsewhere:

• AgentWorker (cli/internal/agentworker/types.go) for a worker whose workspace, role, lifecycle, artifacts, and retirement are portable;
• ReviewLanePort (cli/internal/ports/review_lane.go) for one immutable, fresh, read-only reviewer result handed back to the GC membrane;
• AgentMailPort only when multiple live delegated actors need identity, reservations, acknowledgements, or handoff.

The owners remain agent-native and pawl-review; NTM is one possible worker adapter. These are optional partnership edges, never hard dependencies or automatic fallbacks. GC still owns the quest store/supervision and its membrane still owns the close door. GC and NTM each operate when the other is absent.

When to use / when to skip

Use: standing up a city; slinging and tending quests; a lane is stalled, wedged, or draining; reading verdicts; city admin (doctor, orders, backup, binary rebuild); deciding whether a city is healthy.

Skip: in-session parallel fan-out (→ swarm); unattended bead-queue work on portable NTM worker panes (→ agent-native + ntm); choosing an automation shape at all (→ automation-shape-routing). City-shaped multi-quest work is an operator choice, not an auto-route.

The four jobs (JIT references)

Job	Read	You're done when
Stand up a correct city	scripts/install-gc-city.sh <city-dir> (one command; automates + enforces the whole contract — fail-hard version pins, native store, LAW-0, gap-A materialization, sessions verified, doctor gate). Manual fallback: references/standup.md	gc doctor green incl. law0-print-args + membrane-health; gc status --json shows NativeDoltStore
Run the quest loop	this file, below	quest bead closed on CONFIRMED; human merged
Admin a running city	references/admin.md	doctor green cadence; backups; binary current
Troubleshoot a stall	references/troubleshooting.md	the symptom row's move resolved it

The day-to-day loop

All commands assume the city env: source <city>/env.sh (sets GC_HOME, PATH shim, gc wrapper). Never operate a city with a bare gc against the wrong GC_HOME — check gc status header names YOUR city.

1. Shape the quest (move 1 — intake). A quest = a slug dir with a default-FAIL acceptance contract. Scaffold deterministically:

membrane/scaffold-quest.sh <slug> --ask "<one-line build ask>"   # CONTRACT.md (default-FAIL), test.sh (red), impl.sh placeholder

The builder never reads CONTRACT.md (the gate reads it from main only); the builder reads test.sh. Write the contract in city-relative or quest-relative frame consistently — frame mismatch produces unsatisfiable review findings (see troubleshooting §9).

2. Sling it. One motion creates the work and routes it:

gc sling agentops-membrane.builder "<quest title>" --on membrane-quest \
  --var quest=<slug> --var task="<build task text>"

(Text-sling creates the quest bead from the title and attaches the workflow — no separate bd create needed.)

The reconciler spawns the builder session on its own tick (healthy: ~10–15 s). Nothing to babysit — the control dispatcher advances the workflow.

3. Watch through gc's native surface (never poll panes):

gc events --follow            # live stream; run_id/step_ref correlate a quest
gc status --json | jq .beads  # store health: NativeDoltStore + eligible
gc doctor --json              # full health; membrane checks included
tmux -L <socket> ls           # session inventory (read-only glance)

4. The close gate fires on the check step. The control dispatcher (not an agent) runs membrane/close-gate.sh: routes ONLY diff + contract to ≥2 cross-family reviewer lanes via gc session submit, then the deterministic finalizer rules:

Disposition	What happens
CONFIRMED	gate closes the ralph step with the ENGINE fingerprint; workflow finalizes pass; human merges
REFUTED (hard)	builder respawned with the findings — bounded self-redo
DEGRADED (transient)	lane retried; never converted into a false REFUTE

Attempt semantics (native graph.v2, corrected 2026-07-06): gc's dispatcher never reads gc.failure_class on this path — EVERY failed check consumes one of max_attempts (now 5), transient DEGRADED included. Budget = ~2 transport flakes + 3 real refute rounds. The failure_class stamp is evidence for humans, not retry-budget control.

Never touch a bead with gc.kind=ralph — that is the engine-owned gate bead (it shares the build step's title). An agent closing it bypasses the membrane entirely; the fork finalizer rejects such closes (engine attempt_log fingerprint required), and the formula's recovery snippet filters it, but the rule stands for humans too.

5. Read the verdict at <city>/membrane/<quest>/pawl-verdict.json (schema pawl-verdict.v1; per-round history at pawl-verdict-round-N.json + lane-<family>-round-N.json): check disposition, refuters[].family (must be ≥2 distinct families for CONFIRMED), nonce (anti-replay), findings. On REFUTED, the redo path is automatic — never hand-close the quest bead.

Observability gotcha: the check path emits ZERO gc events — watch the ralph gate bead's gc.attempt_log metadata (one entry per round, gate log embedded), or set GC_WORKFLOW_TRACE=<file> for the dispatch trace. The check runs in the SUPERVISOR process, so workspace env does not reach it; supervisor plist env does.

Lane failover (degraded-diversity mode): if the agy/gemini lane is dead (auth outage), keep the quorum at 2 distinct REVIEWER families with the pack's opus-verifier, a fresh-context claude lane. Explicit tradeoff: one reviewer then shares the BUILDER family (the default posture excludes it); session isolation still gives author≠judge, and it beats single-family review or burning attempts on DEGRADE. Temporary — restore agy when healed. Set [workspace.env] MEMBRANE_LANE2_TARGET = "agentops-membrane.opus-verifier"

• MEMBRANE_LANE2_FAMILY = "claude", add its [[named_session]], and bounce the supervisor. Restore agy when healed — three families beat two.

Roll outcomes into the tracker (read-only, never a sync): scripts/gc-outcomes-report.sh <city> — closed work with outcomes/commits + open work; paste relevant lines into a bead note.

6. Converge. A run has converged when: quest bead CLOSED on CONFIRMED, verdict artifact valid, branch handed to a human. A run has stalled when a lane sits idle across a round transition — go straight to the troubleshooting ladder; the two moves that matter most are non-obvious:

• A draining/idle interactive pane is recovered ONLY by gc session submit <target> <text> — gc session kill, reset, and raw tmux send-keys all fail. If the pane is busy and doesn't consume the submit, Esc-interrupt it, then submit again.
• A codex/agy lane wedged at startup is the provider trust modal — pre-trust via a city-scoped CODEX_HOME seed (codex) or one interactive provider run (agy). Until cleared the lane DEGRADES (correctly — never a false REFUTE).

Output Specification

Artifact directory: <city>/membrane/<quest>/ for quest-local membrane evidence.

Filename convention: terminal output uses pawl-verdict-round-<N>.json plus latest pawl-verdict.json; lane inputs use lane-<family>-round-<N>.json; degradation uses review-attempt-round-<N>.json.

Serialization/schema format: terminal verdicts are closed pawl-verdict.v1 JSON; transient transport evidence is gc-review-attempt.v1 and never substitutes for a terminal verdict.

Validator command: with VERDICT=<city>/membrane/<quest>/pawl-verdict.json, run python3 -m jsonschema -i "$VERDICT" schemas/pawl-verdict.v1.schema.json, then require two distinct refuters[].family values for CONFIRMED.

Downstream handoff: pass city/quest ids, native-store and doctor status, verdict path/round/disposition/nonce, distinct reviewer families, findings, attempt budget, branch, and the explicit human merge action.

Quality Checklist

• The operator explicitly selected GC and the commands target the intended GC_HOME.
• NativeDoltStore, law0-print-args, and membrane health are green before slinging work.
• The quest contract is default-FAIL and uses one consistent path frame.
• Terminal verdict JSON passes the closed schema; degradation is never treated as judgment.
• CONFIRMED has the required distinct reviewer-family evidence and engine fingerprint.
• REFUTED/DEGRADED follows bounded automatic retry; no quest or ralph bead is hand-closed.
• The membrane closes only the quest; branch merge remains an explicit human action.
• WARN/FAIL/REFUTED consulted the pawl before any human andon.

Non-goals

Don't wrap or re-implement gc events/gc costs/gc doctor/gc dashboard/ gc session/gc mail — point at them. Don't build stall-detection infra (gc orders + events + dashboard already do it; the membrane keepalive order is the one addition). Don't gate anything on gc costs (usage facts are absent for sub-backed providers — it would fail-open). Don't auto-merge, ever.

Scenarios

Scenario: Recover a stalled reviewer lane
  Given a membrane city whose reviewer pane sits idle in draining and the round is not advancing
  When the operator runs gc session submit <lane> with a keepalive line
  Then the pane consumes the delivery and the round advances
  And gc session kill, gc session reset, and raw tmux send-keys were never used

Scenario: Stand up a correct native city
  Given a host with bd matching gc's linked beads library and dolt at the managed floor
  When the operator follows references/standup.md end to end
  Then bd context reports dolt_mode server and gc status --json reports NativeDoltStore
  And gc doctor is green including law0-print-args and membrane-health

Scenario: A REFUTED verdict routes to bounded redo, not a manual close
  Given a quest whose pawl-verdict.json shows disposition REFUTED
  When the operator reads the verdict
  Then the builder respawn consumes one bounded attempt and the quest bead is never hand-closed

Scenario: The gate bead is engine-owned
  Given a workflow whose ralph gate bead shares the build step title
  When any agent or operator identifies their step bead
  Then beads with gc.kind=ralph are excluded and never closed by hand
  And a gate bead closed without the engine attempt_log fingerprint cannot finalize the workflow as pass