Gate reasons and run endings

A lookup page for the codes you see in hand-off comments, in the room and in maku status. Why the gate works this way: the merge gate.

Terms

The decision rows

The gate reads a pull request whose CI has run, row by row; the first “no” hands it to a human. With no class live or shadow in the repository, it reads nothing and hands off as merge_gate_off.

    flowchart TB
  subgraph s1["Agent PR in AwaitingCI · rows 1–3"]
    direction LR
    base(["1–2c: secret scan,<br/>fence, required checks,<br/>test contract"])
    base -->|"red"| fix["fix run (up to fixRuns),<br/>then escalate"]
    base -->|"green"| pb(["3: policy-bot:<br/>main green?"])
    pb -->|"no"| ho1["AwaitingHuman: reason,<br/>one action, decision record"]
  end
  subgraph s2["Row 4"]
    direction LR
    back["AwaitingHuman:<br/>approve the current head"] --> appr(["4: a maintainer approved<br/>the current head?"])
    appr -->|"yes, approveToMerge"| amerge["merger merges it<br/>factory/approved-merge<br/>→ Done"]
  end
  subgraph s3["Rows 5–8"]
    direction LR
    cls(["5: class live<br/>or shadow?"]) -->|"yes"| rows(["6–8: reviewer verdict,<br/>head reported, trailer,<br/>files, size, shape,<br/>holdouts, oracle"])
    cls -->|"neither"| ho2["AwaitingHuman"]
    rows -->|"a row fails"| ho2
  end
  subgraph s4["Rows 9–12: a live class"]
    direction LR
    brk(["9: breaker clear?<br/>10: under the daily caps?"]) -->|"yes"| push(["12: every push<br/>the agents App's?"])
    brk -->|"no"| ho3["AwaitingHuman"]
    push -->|"no"| ho3
    push -->|"yes"| merge["merger merges<br/>the decided head<br/>factory/auto-merged:class<br/>→ Verifying"]
  end
  shadow["record shadow_would_arm<br/>paused= capped= read,<br/>nothing armed"]
  s1 -->|"3: yes"| s2
  s2 -->|"4: no"| s3
  s3 -->|"all hold, live"| s4
  s3 -->|"all hold, shadow"| shadow
  

A shadow class skips rows 9 and 10: it records shadow_would_arm whatever the breaker and the day’s count say, and its record notes what they read. Row 8 reads GitHub’s own file list, and only once every other row would merge. Maku’s merge gate documents each reason’s next step.

Settings

Example (the reference host), from tooling/base/agent-factory/helm-values-configmap.yaml:

A class can set a lower maxPerDay of its own. Every other key: harness reference.

Hand-off reasons

The common reasons and your move are on the hand-off. A hand-off goes back to the gate by itself when its cause clears:

No approval returns these nine. Fix the pull request, or read it and use the bypass: not_agent_authored, gate_path, contract_modified, not_owned, steering_path, foreign_trailer, not_mergeable, changes_requested, human_commit_in_pr. One exception: a changes_requested hand-off returns on an approval once no maintainer’s newest review still requests changes.

Run endings by role

What each role starts on and how its run can end. The switches are per class, under loops.<class> and repositories[].classes.<class>.

A failing named check is never met. A run with no scoper handoff runs the implementer unscoped.

The decision record

Every decision that is not a wait appends one hidden line to its comment, with what each row read. Hand-offs post it on the issue; shadow decisions post it on the pull request. An example record:

<!-- agent-factory-decision head=67dfa768 class=docs decision=human:class_unarmed files=-/0 lines=-/0 shape=- holdout=- oracle=- age=- evidence=- paused=- capped=- reviewer=glm-5.3 -->

- means unread, never 0: a refusal leaves the rows after it unread. merge_gate_off, ledger_truncated and the waits’ own endings (ci_cancelled, ci_wait_expired) carry no record. To count and replay records, see run auto-merge safely.