gt agents state --help documents itself under a command name that does not exist, and three shipped patrol formulas call the wrong name
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:
idle:climbs without bound (observedidle: 2 -> 3, never reset).- Backoff pins at its cap (
--backoff-max, 15m in our config). await-signalreturnsEFFORT: reducedpermanently.EFFORT: reducedis defined by these same formulas to SKIP steps — inmol-deacon-patrolthat includes the Dolt-health check and thedaemon.logread.
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
- Correct the usage strings in
gt agents stateto the plural form. This is the one that matters. - Correct the three formula call sites.
- Consider accepting
gt agentas 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.
Source: gastownhall/gastown