#4835·gastown

gt agents state --help documents itself under a command name that does not exist, and three shipped patrol formulas call the wrong name

Author: stefanhk-harmanCreated Sep 9, 2026Updated Sep 9, 2026
Labelsstatus/needs-triage

Summary

gt agents state prints its own usage using gt agent state — singular. There is no gt agent command. Every shipped patrol formula copied the name from the help text, so the only reset for the idle: counter never runs.

The self-documenting wrong name

$ gt agents state --help
OPERATIONS:
  Get all labels (default):
    gt agent state <agent-bead>
  Set a label:
    gt agent state <agent-bead> --set idle=0
$ gt agent state hq-deacon --set idle=0
Error: unknown command "agent" for "gt"

The three call sites

Shipped formulas, gt 1.1.0:

file line call
mol-deacon-patrol.formula.toml 1216 gt agent state hq-deacon --set idle=0
mol-witness-patrol.formula.toml 70 gt agent state {{prefix}}-{{rig}}-witness --set idle=0
mol-refinery-patrol.formula.toml 1019 gt agent state YOUR_AGENT_BEAD --set idle=0

Fixing the call sites alone is not sufficient — the help text is what regenerates the defect for the next formula author.

Impact: it silently shrinks what the patrol inspects

This is not a cosmetic naming bug. gt mol step await-signal increments idle: on every timeout, and the command above is the only documented reset. So:

  1. idle: climbs without bound (observed idle: 2 -> 3, never reset).
  2. Backoff pins at its cap (--backoff-max, 15m in our config).
  3. await-signal returns EFFORT: reduced permanently.
  4. EFFORT: reduced is defined by these same formulas to SKIP steps — in mol-deacon-patrol that includes the Dolt-health check and the daemon.log read.

Steps 1–4 compound: a broken counter reset permanently downgrades what the watchdog looks at. On 2026-09-09 those two skipped steps were exactly the ones that surfaced an orphaned-bd connection leak (#4820) and a 22-hour backup outage on our town. An agent following the molecule verbatim reaches step 4 and inspects less every cycle thereafter, with no error anywhere.

It fails loudly per-invocation and suggests agents, so a human recovers immediately. An agent executing the step as written does not.

Same three formulas define the Witness and Refinery patrols, so all three long-running agents degrade identically.

Suggested fix

  1. Correct the usage strings in gt agents state to the plural form. This is the one that matters.
  2. Correct the three formula call sites.
  3. Consider accepting gt agent as a hidden alias, since the wrong name is now in shipped formulas and in any town that copied them.

Environment

gt 1.1.0 (Homebrew), macOS 15 / Darwin 25.6.0, bd 1.2.2.