Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -1065,13 +1065,21 @@ as soon as the workflow is on `main`.
**The early exit.** A run woken by `workflow_run` on a fleet that is **not paused** exits
before the organisation scan when both hold: an earlier run of this workflow that
succeeded was created in the same clock slot of `BUDGET_BREAKER_MIN_INTERVAL_MIN` minutes
(default 2; `0` switches the early exit off; a failed run covers nothing, because it may
(default 10; `0` switches the early exit off; a failed run covers nothing, because it may
have ended before its scan), and this repository shows no quota marker created in that
slot (one listing instead of one per repository). It is slots, not "the previous run
finished less than two minutes ago", because a run that exits early is itself a previous
finished less than N minutes ago", because a run that exits early is itself a previous
run: under a steady stream of wake-ups that rule would exit early for ever, while the
first run to look in a slot always decides. The earlier runs are listed with the read
credential (the repository is public, so the workflow's `permissions:` are unchanged).
The default was two minutes when the trigger was added and was raised to ten after the
first 84 minutes of real runs (2026-10-11): 309 runs were created, 115 executed, and a slot
of two minutes meant up to 30 organisation scans an hour on the maintainer login's shared
API quota. With ten, event wake-ups cause at most 6. A scheduled run always scans, so each
scheduled tick that is delivered adds one (up to 6 more an hour; two were delivered in the
first 13 hours). A quota marker posted in this repository still
makes the next run decide at once; one posted only in another repository is read by the
first run of the next slot, so up to ten minutes later.
The early exit never applies to a scheduled run, never while the fleet is paused by
anyone (so it cannot delay a resume), and never when the earlier runs, the slot or this
repository's markers could not be read: then the run decides. Its one cost: a marker
Expand Down Expand Up @@ -1283,7 +1291,7 @@ as soon as the workflow is on `main`.
- **Tuning** (repository variables, all optional): `BUDGET_BREAKER_MIN_ITEMS`,
`BUDGET_BREAKER_WINDOW_MIN`, `BUDGET_BREAKER_PROBE_HOURS` (the pause length when no reset
time is known, default 2), `BUDGET_BREAKER_MIN_HOLD_MIN` and
`BUDGET_BREAKER_MIN_INTERVAL_MIN` (the early exit's slot, default 2, `0` for off). Keep
`BUDGET_BREAKER_MIN_INTERVAL_MIN` (the early exit's slot, default 10, `0` for off). Keep
the minimum hold at or above the window: otherwise the markers that caused a pause can
still be inside the window when it lifts.
- **Guard rails for editors.** The workflow's triggers are `schedule` and `workflow_run`
Expand Down
8 changes: 4 additions & 4 deletions scripts/budget_breaker.sh
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@
# the decision's settings (scripts/lib/budget-breaker.sh)
# BUDGET_BREAKER_MIN_INTERVAL_MIN
# length of the early exit's clock slot, minutes
# (default 2; 0 switches the early exit off)
# (default 10; 0 switches the early exit off)
# GITHUB_EVENT_NAME what woke the run (set by the runner; the name
# only, see "THE WAKE-UP IS NOT AN INPUT")
# GITHUB_WORKFLOW_REF / GITHUB_RUN_ID
Expand Down Expand Up @@ -240,12 +240,12 @@ report_previous_run() {
# be read means "decide": the lookup of the earlier runs, the slot, the listing
# of this repository's markers.
exit_early_if_covered() {
local interval="${BUDGET_BREAKER_MIN_INTERVAL_MIN:-2}" slot earlier recent fresh
local interval="${BUDGET_BREAKER_MIN_INTERVAL_MIN:-10}" slot earlier recent fresh
Comment thread
don-petry marked this conversation as resolved.
Resolved
# A scheduled run is the backstop and always decides.
[ "$EVENT" = "workflow_run" ] || return 0
if ! [[ "$interval" =~ ^[0-9]{1,4}$ ]]; then
bbw_warn "BUDGET_BREAKER_MIN_INTERVAL_MIN is not a whole number of minutes; using 2"
interval=2
bbw_warn "BUDGET_BREAKER_MIN_INTERVAL_MIN is not a whole number of minutes; using 10"
interval=10
fi
interval="$((10#$interval))"
[ "$interval" -gt 0 ] || return 0
Expand Down
37 changes: 29 additions & 8 deletions tests/dev-lead/unit/test_budget_breaker_writer.bats
Original file line number Diff line number Diff line change
Expand Up @@ -172,8 +172,11 @@ seed_runs() { printf '%s\n' "$@" | jq -cs '.' > "$MOCK_DIR/runs.json"; }

# woken_by <event> [<now_offset_sec>] — the run as the runner starts it: the
# event's name, this workflow's file and this run's id. The clock moves to NOW
# + offset; NOW is the start of a two-minute slot, so offset 90 is inside the
# slot that starts at `ts 0`.
# + offset; NOW is the start of a ten-minute slot (and so of a two-minute and a
# one-minute one), so offset 90 is inside the slot that starts at `ts 0` for
# every slot length these tests use. The guard keeps a change to NOW from moving
# that boundary unnoticed.
(( NOW % 600 == 0 )) || { echo "NOW must be a multiple of 600 (the default slot)" >&2; exit 1; }
OWN_RUN_ID=9000
woken_by() {
export GITHUB_EVENT_NAME="$1"
Expand Down Expand Up @@ -2302,11 +2305,13 @@ FAILED DELETE AGENTS_PAUSE_UNTIL" ]
armed
fi
woken_by workflow_run 90
# Created ten seconds into the two-minute slot this run is in.
# Created ten seconds into the slot this run is in (ten minutes, the
# default). The quota markers are all in another repository (seed_quota),
# so this is also the accepted cost: such markers wait for the next slot.
seed_runs "$(wrun 8001 success 10 25)"
run bash "$SCRIPT"
[ "$status" -eq 0 ] || { echo "$mode: status=$status $output"; false; }
[[ "$output" == *"budget-breaker: early exit: an earlier run was created in this 2 min slot (since $(ts 0)) and acme/.github-private shows no quota marker since; no scan, no decision"* ]] \
[[ "$output" == *"budget-breaker: early exit: an earlier run was created in this 10 min slot (since $(ts 0)) and acme/.github-private shows no quota marker since; no scan, no decision"* ]] \
|| { echo "$mode: $output"; false; }
[[ "$output" != *"decision:"* ]]
[[ "$output" != *"quota markers read"* ]]
Expand All @@ -2319,7 +2324,7 @@ FAILED DELETE AGENTS_PAUSE_UNTIL" ]
no_notice
grep -qF "| Quota markers | not collected (early exit) |" "$GITHUB_STEP_SUMMARY"
grep -qF "| Decision | not taken this run (early exit) |" "$GITHUB_STEP_SUMMARY"
grep -qF "| Result | no scan: an earlier run covered this 2 min slot (since $(ts 0))" "$GITHUB_STEP_SUMMARY"
grep -qF "| Result | no scan: an earlier run covered this 10 min slot (since $(ts 0))" "$GITHUB_STEP_SUMMARY"
done
[ "$(org_var AGENTS_PAUSED)" = "<absent>" ]
}
Expand Down Expand Up @@ -2528,16 +2533,32 @@ DELETE AGENTS_PAUSE_UNTIL" ]
[[ "$output" != *"early exit"* ]]
[[ "$output" == *"decision: trip (evidence_count=3)"* ]]

export BUDGET_BREAKER_MIN_INTERVAL_MIN=10
export BUDGET_BREAKER_MIN_INTERVAL_MIN=2
run bash "$SCRIPT"
[ "$status" -eq 0 ]
[[ "$output" == *"early exit: an earlier run was created in this 2 min slot (since $(ts 0))"* ]]

# Unset is the default, ten minutes: a run created early in the slot still
# covers a wake-up nine minutes later, and one created before the slot does not.
unset BUDGET_BREAKER_MIN_INTERVAL_MIN
woken_by workflow_run 590
run bash "$SCRIPT"
[ "$status" -eq 0 ]
[[ "$output" == *"early exit: an earlier run was created in this 10 min slot (since $(ts 0))"* ]]
woken_by workflow_run 610
run bash "$SCRIPT"
[ "$status" -eq 0 ]
[[ "$output" != *"early exit"* ]]
[[ "$output" == *"decision: trip (evidence_count=3)"* ]]
run scanned
[ "$status" -eq 0 ]
woken_by workflow_run 90

export BUDGET_BREAKER_MIN_INTERVAL_MIN="2m"
run bash "$SCRIPT"
[ "$status" -eq 0 ]
[[ "$output" == *"::warning::budget-breaker: BUDGET_BREAKER_MIN_INTERVAL_MIN is not a whole number of minutes; using 2"* ]]
[[ "$output" == *"early exit: an earlier run was created in this 2 min slot"* ]]
[[ "$output" == *"::warning::budget-breaker: BUDGET_BREAKER_MIN_INTERVAL_MIN is not a whole number of minutes; using 10"* ]]
[[ "$output" == *"early exit: an earlier run was created in this 10 min slot"* ]]
}

@test "#2259: the slot, the earlier runs and the fresh markers are judged fail open (pure helpers)" {
Expand Down
Loading