Skip to content

121. Steering on by default, with per-harness and per-repository opt-out ​

Date: 2026-11-02

Status ​

Accepted

ADR 0106 refers to this ADR as the decision that turns steering on by default.

Companion decisions:

  • ADR 0117 (proposed): what a steer is and what it may carry.
  • ADR 0118 (proposed): runtime delivery.
  • ADR 0119 (proposed): the GitHub Actions change signal.
  • ADR 0120 (proposed): receipts for absorbed steers in host-written run metadata.

Context ​

ADR 0117 (proposed) defines steering, the delivery of freshly admitted entity updates into a running cycle, as an optional fast path inside an ADR 0144 cycle. It leaves open whether a harness steers when its configuration does not mention steering.

The origin issue for this work, #6957, sets steering on by default in its validation criteria: a harness that sets steer: {enabled: false} keeps the ADR 0106 behaviour, where later events wait for the next run.

This ADR aims to formalize that default, the switches that turn steering off, how those switches compose across layers, and the per-cycle steer limit.

Options ​

Opt-in per harness (rejected) ​

Steering is off unless a harness turns it on. Every harness that does not mention steering, which is most of them, keeps the cost of stale output.

On by default, with opt-out (chosen) ​

Every eligible harness steers unless it, or its repository, turns steering off. A harness whose agent does not act on the steer envelope (ADR 0117) must be found and opted out.

Decision ​

We adopt steering on by default, with a per-harness and a per-repository opt-out and a per-cycle max_steers limit, to give every eligible harness the steering gains without a per-harness edit.

After ADR 0144, what steering still adds is avoiding stale output from a turn that finishes on old state, redirecting work in flight, and covering event-only harnesses on GitHub Actions where ADR 0144 opens no listener. Those gains apply to every harness.

SwitchWhereEffect
steer: {enabled: false}HarnessSteering off for that harness
steer: {enabled: false}Repository configurationSteering off for every harness in the repository
steer: {max_steers: N}HarnessAt most N steers per cycle

Composition ​

  • Any false wins. An explicit enabled: false in any configuration layer turns steering off, and no other layer can turn it back on. The layers are every base harness in the base: chain, the child harness, its forge overrides and CEL-guarded overlays (ADR 0088, ADR 0112), the repository's .fullsend/config.base.yaml and .fullsend/config.yaml (ADR 0069), and managed repository configuration (ADR 0122). steer composes by restriction, unlike the fields those ADRs override by the later layer.
  • Tuning never re-enables. A steer block merges field by field. A block that sets only tuning fields, such as max_steers, or an empty steer: {}, leaves enabled as the other layers set it. If no layer sets enabled, steering is on.
  • Dropping an opt-out is a relaxation. Removing an effective enabled: false from repository configuration counts as a relaxation under the ADR 0122 pre-write safety gate, which rejects it unless the manifest declares it.
  • Not before readiness. The default applies only once the ADR 0117 dependencies are in place, including the per-steer pre-script gate.

The max_steers limit ​

  • Layer. A harness field only, composed across the harness layers above (base harnesses, child harness, forge overrides, overlays): the lowest value wins. Repository configuration does not accept it and rejects it as an unknown key.
  • Default 3. Each steer costs a model turn, sandbox time, and, on a push, a host-side fetch and bundle upload. Three covers a three-push local iteration during one cycle (push 1 starts the cycle and pushes 2 and 3 take two steer slots, leaving one slot for another push or comment); rapid pushes between checks coalesce into one steer, and the next cycle picks up anything beyond. To be revisited after the first release.
  • Range 1 to 9999, checked per layer. Each layer is validated as written, before composition, so an invalid value in one layer is an error even when another layer sets a lower one. Omitted is distinct from 0; 0, negative numbers, values above 9999, non-integers, and unknown keys under steer fail validation. The upper bound comes from the four-digit steer directory names in steer envelope v1 (proposed with ADR 0117). Use enabled: false, not 0, to turn steering off.

Harnesses that need action ​

  • Agent does not act on the envelope. The harness opts out with enabled: false.
  • Harness has a pre-script. Under ADR 0117 every steer passes the pre-script gate, and a pre-script that does not write steer_checked=true never lets a steer through. Such a harness does not steer until its pre-script is updated. Until then, enabled: false avoids the attempts that ADR 0117 runs and then declines.
  • Pre-script reads ADR 0120 receipts. For records, an acknowledged steer proves delivery, not action, so a pre-script that skips work on record receipts relies on its agent acting on steers; a harness whose agent does not act on the envelope must not skip on record receipts. For head moves, the host sets result_head_sha only when the cycle's validated output proved the agent worked on the steered head (ADR 0117), so an agent that ignores Head: leaves result_head_sha at the initial head and the follow-up cycle still runs for the new head.

What an operator sees ​

Steering posts nothing on the entity when it is off or declines. The cycle's trace records the effective enabled and max_steers values with the layer that set each, any readiness blocker, and, for each declined attempt, the ADR 0117 step and reason.

Forge scope ​

The default applies wherever ADR 0117 steers a running cycle: through ADR 0144 events and wakes on any forge where ADR 0144 is implemented, and on GitHub Actions also through the ADR 0119 run-record signal. That signal reads GitHub Actions run records only, so on GitLab and Forgejo the switches govern ADR 0144 wakes alone. Jira and other non-forge entities do not steer, because entity-context-snapshot v1 does not stage them, so the switches have no effect on them.

Consequences ​

  • Every eligible harness without a pre-script steers on the release that enables steering, without a per-harness edit. A harness with a pre-script steers once its pre-script writes steer_checked=true.
  • Harnesses whose agents do not act on the steer envelope must opt out before that release. Otherwise updates delivered to them are acknowledged but not acted on until the next cycle.
  • A steered sandbox stays up longer, so the default adds VM time on every harness that has not opted out.
  • The new steer fields need entries in the harness and configuration references when steering is implemented.