@feigi/fleet-ctl 3.47.6 → 3.48.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.47.6",
3
+ "version": "3.48.0",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -0,0 +1,206 @@
1
+ #!/usr/bin/env node
2
+ // The finisher's labelling duty as one command, so its two halves cannot be
3
+ // read as one: the release-label check is a precondition, and a finisher that
4
+ // stopped after it reported `labelled` on a PR that never got the label.
5
+ //
6
+ // finisher-label.mjs --pr <M> --pin <sha> [--repo <dir>]
7
+ //
8
+ // `--pin` is the full 40-hex head the finisher audited; `--repo` is the
9
+ // directory `gh` runs in (it resolves the repository from there), the cwd when
10
+ // omitted. Reached through the Resolver: `~/.fleet/bin/fleet-run
11
+ // finisher-label.mjs ...`.
12
+ //
13
+ // Steps, in this order, each one only if every earlier one held:
14
+ //
15
+ // 1 read the PR's labels and comments and count the release labels,
16
+ // `patch`/`minor`/`major`. Exactly one passes. Zero or several is exit 3
17
+ // and nothing is written. A repo whose label list defines none of the
18
+ // three has nothing to count: the count is skipped and the receipt says
19
+ // `releaseLabels: "undefined-in-repo"`. That list is read only when the
20
+ // PR carries none of them — one on the PR proves it is defined — and a
21
+ // list that fills the limit it was read with proves nothing, so it is
22
+ // exit 2 rather than a skipped count.
23
+ // 2 comment `ready-to-merge-head: <pin>`, the record the merge bot reads as
24
+ // the head the label was applied to — skipped when the newest such
25
+ // comment already names this pin.
26
+ // 3 add the `ready-to-merge` label.
27
+ // 4 read the labels back. Exit 0 only when the read-back carries
28
+ // `ready-to-merge`; `gh pr edit` returning 0 is not that.
29
+ //
30
+ // Idempotent: a PR that already carries `ready-to-merge` and whose newest
31
+ // head record names this pin is left as it is — no comment, no label write —
32
+ // and still answers 0 off the read-back, `added: false`.
33
+ //
34
+ // Stdout is always one JSON line, the receipt:
35
+ //
36
+ // {pr, pin, releaseLabels, commented, added, readBack, exit, firstRead
37
+ // [, step, error]}
38
+ //
39
+ // releaseLabels the release labels the PR carried, or "undefined-in-repo",
40
+ // or null when step 1 never got an answer
41
+ // commented this run posted the head record
42
+ // added this run wrote the label
43
+ // readBack every label name the step 4 read carried, null if it never ran
44
+ // firstRead every label name step 1 read carried, null if it never ran
45
+ // step on exit 2 only, the step that failed: `pin`, `repo`, or the
46
+ // step whose `gh` call failed
47
+ // error on exit 2 only, what `gh` (or the invocation) said
48
+ //
49
+ // A usage error that never reaches `gh` — a missing or unknown flag — is a
50
+ // refusal on stderr with no receipt, as in every other script's `die()`.
51
+ //
52
+ // Exit vocabulary:
53
+ //
54
+ // 0 the read-back carries `ready-to-merge`
55
+ // 2 the invocation or a `gh` call failed — its stderr is in the receipt and
56
+ // on stderr, and no later step ran
57
+ // 3 the PR does not carry exactly one release label — nothing was written
58
+ // 4 every write returned 0 and the read-back does not carry the label
59
+
60
+ import { spawnSync } from "node:child_process";
61
+ import { statSync } from "node:fs";
62
+ import { makeDie, defineFlags, writeAll } from "./arg.mjs";
63
+ import { gitEnv } from "./git-env.mjs";
64
+
65
+ const NAME = "finisher-label";
66
+ const LABEL = "ready-to-merge";
67
+ const RELEASE = ["patch", "minor", "major"];
68
+ const LIST_LIMIT = 1000;
69
+
70
+ const die = makeDie(NAME);
71
+ const { arg, numArg, sweep, stray } = defineFlags(die, {
72
+ flags: { pr: "value", pin: "value", repo: "value" },
73
+ });
74
+
75
+ const USAGE = "usage: finisher-label.mjs --pr <M> --pin <sha> [--repo <dir>]";
76
+
77
+ // The sweep runs before the required-flag check so a misspelt flag is named
78
+ // as that, not buried under a missing-flag usage line.
79
+ sweep();
80
+ stray();
81
+ const pr = numArg("pr");
82
+ const pinArg = arg("pin");
83
+ const repo = arg("repo");
84
+ if (pr === null || pinArg === null) die(USAGE);
85
+
86
+ const receipt = {
87
+ pr,
88
+ pin: pinArg,
89
+ releaseLabels: null,
90
+ commented: false,
91
+ added: false,
92
+ readBack: null,
93
+ exit: 0,
94
+ firstRead: null,
95
+ };
96
+
97
+ function finish(exit, extra = {}, message = null) {
98
+ Object.assign(receipt, extra, { exit });
99
+ writeAll(1, `${JSON.stringify(receipt)}\n`);
100
+ if (message !== null) writeAll(2, `${NAME}: ${message}\n`);
101
+ process.exit(exit);
102
+ }
103
+
104
+ function fail(step, error) {
105
+ finish(2, { step, error }, `${step}: ${error}`);
106
+ }
107
+
108
+ // Full SHAs only: the bot's record grammar is exactly 40 lowercase hex, so a
109
+ // shorter or uppercase pin would be a record it cannot read. Case is folded
110
+ // rather than refused — `ABC…` names the same commit.
111
+ const pin = pinArg.toLowerCase();
112
+ if (!/^[0-9a-f]{40}$/.test(pin)) {
113
+ fail("pin", `--pin needs a full 40-character commit SHA, got ${pinArg}`);
114
+ }
115
+ receipt.pin = pin;
116
+
117
+ // A missing directory makes spawn report ENOENT for `gh` itself, which would
118
+ // blame the binary for a bad --repo.
119
+ if (repo !== null && !statSync(repo, { throwIfNoEntry: false })?.isDirectory()) {
120
+ fail("repo", `--repo is not a directory: ${repo}`);
121
+ }
122
+
123
+ // `gh` resolves its repository from the cwd's git remotes, so an ambient
124
+ // GIT_DIR would retarget every call at another repository.
125
+ const GH_ENV = gitEnv();
126
+
127
+ // stdout parsed, stderr captured: what `gh` said is the receipt's `error`.
128
+ function gh(step, args) {
129
+ const r = spawnSync("gh", args, { encoding: "utf8", env: GH_ENV, stdio: ["ignore", "pipe", "pipe"], ...(repo === null ? {} : { cwd: repo }) });
130
+ if (r.error) fail(step, `could not run gh: ${r.error.message}`);
131
+ if (r.signal) fail(step, `gh was killed by ${r.signal}`);
132
+ if (r.status !== 0) fail(step, (r.stderr ?? "").trim() || `gh exited ${r.status}`);
133
+ return r.stdout;
134
+ }
135
+
136
+ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
137
+
138
+ function ghJson(step, args, shape) {
139
+ const out = gh(step, args);
140
+ let v;
141
+ try {
142
+ v = JSON.parse(out);
143
+ } catch {
144
+ return fail(step, `gh printed no JSON: ${out.slice(0, 200)}`);
145
+ }
146
+ if (!shape(v)) fail(step, `gh printed an unexpected shape: ${out.slice(0, 200)}`);
147
+ return v;
148
+ }
149
+
150
+ const namedList = (v) => Array.isArray(v) && v.every((l) => isObject(l) && typeof l.name === "string");
151
+
152
+ const labelNames = (v) => v.labels.map((l) => l.name);
153
+
154
+ // --- 1: the release-label count -------------------------------------------
155
+ const first = ghJson("read-labels", ["pr", "view", String(pr), "--json", "labels,comments"], (v) =>
156
+ isObject(v) && namedList(v.labels) && Array.isArray(v.comments) && v.comments.every((c) => isObject(c) && typeof c.body === "string" && typeof c.createdAt === "string"));
157
+ const firstLabels = labelNames(first);
158
+ receipt.firstRead = firstLabels;
159
+ const found = RELEASE.filter((r) => firstLabels.includes(r));
160
+
161
+ if (found.length === 0) {
162
+ const defined = ghJson("list-labels", ["label", "list", "--json", "name", "--limit", String(LIST_LIMIT)], namedList).map((l) => l.name);
163
+ if (RELEASE.some((r) => defined.includes(r))) {
164
+ finish(3, { releaseLabels: found }, "the PR carries no release label (patch, minor or major); nothing was written");
165
+ }
166
+ // A list that fills the limit may be cut off before the release labels, so
167
+ // their absence from it proves nothing.
168
+ if (defined.length >= LIST_LIMIT) {
169
+ fail("list-labels", `the repository has ${LIST_LIMIT} or more labels, so the list may be cut off before patch, minor or major`);
170
+ }
171
+ receipt.releaseLabels = "undefined-in-repo";
172
+ } else if (found.length > 1) {
173
+ finish(3, { releaseLabels: found }, `the PR carries more than one release label (${found.join(", ")}); nothing was written`);
174
+ } else {
175
+ receipt.releaseLabels = found;
176
+ }
177
+
178
+ // --- 2: the head record ----------------------------------------------------
179
+ // The newest record wins, the way the merge bot reads it: a matching record
180
+ // older than one naming another head is not the record the bot will act on.
181
+ const RECORD = /^ready-to-merge-head: ([0-9a-f]{40})\s*$/;
182
+ const records = first.comments
183
+ .map((c, i) => ({ i, at: c.createdAt, m: RECORD.exec(c.body) }))
184
+ .filter((c) => c.m !== null)
185
+ .sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : a.i - b.i));
186
+ const recorded = records.length > 0 && records[records.length - 1].m[1] === pin;
187
+ const labelled = firstLabels.includes(LABEL);
188
+
189
+ if (!recorded) {
190
+ gh("comment", ["pr", "comment", String(pr), "--body", `ready-to-merge-head: ${pin}`]);
191
+ receipt.commented = true;
192
+ }
193
+
194
+ // --- 3: the label ----------------------------------------------------------
195
+ if (!(recorded && labelled)) {
196
+ gh("add-label", ["pr", "edit", String(pr), "--add-label", LABEL]);
197
+ receipt.added = true;
198
+ }
199
+
200
+ // --- 4: the read-back ------------------------------------------------------
201
+ const back = ghJson("read-back", ["pr", "view", String(pr), "--json", "labels"], (v) => isObject(v) && namedList(v.labels));
202
+ receipt.readBack = labelNames(back);
203
+ if (!receipt.readBack.includes(LABEL)) {
204
+ finish(4, {}, `the read-back does not carry ${LABEL}`);
205
+ }
206
+ finish(0);
@@ -2173,7 +2173,7 @@ PRs**, because the two causes live at different levels — the budget is one
2173
2173
  account, the payload is one PR:
2174
2174
 
2175
2175
  ```sh
2176
- budget_out= list_out= cap_out= blind= # seed the latches: set -u reads each below before tick 1 ever assigns one
2176
+ budget_out= hidden_out= list_out= cap_out= blind= # seed the latches: set -u reads each below before tick 1 ever assigns one
2177
2177
  pr_cap=200 # the open-PR read's --limit; gh stops there with exit 0 and no warning
2178
2178
  while :; do # one tick
2179
2179
  rl=$(gh api rate_limit --jq '.resources.core.remaining' 2>/dev/null || echo ERR)
@@ -2210,34 +2210,52 @@ while :; do # one tick
2210
2210
  # ceiling of one ci-state.mjs call on the counter `gh api rate_limit`
2211
2211
  # reports, for single-page reads: 2 on the common path, 4 for a PR whose
2212
2212
  # head dropped required jobs.
2213
- # The workflow and run lookups bill a second core bucket that `rate_limit`
2214
- # does not report and this gate does not guard. A shortfall pauses this
2215
- # tick's pass.
2213
+ # A shortfall here, or at the Actions-bucket gate below, pauses this tick's pass.
2216
2214
  if [ "$rl" -lt $((200 + 4 * count)) ]; then
2217
2215
  if [ -z "$budget_out" ]; then
2218
2216
  echo "WATCHER DEGRADED: core REST budget=$rl < $((200 + 4 * count)) needed for $count PRs — CI polling paused, silence is NOT green"
2219
2217
  budget_out=1
2220
2218
  fi
2221
2219
  else
2222
- if [ -n "$budget_out" ]; then
2223
- echo "WATCHER RECOVERED: core budget=$rl — CI polling resumed"
2224
- budget_out=
2225
- fi
2226
- for pr in $(printf '%s\n' "$prs"); do # inline $(...): `for pr in $prs` is ONE iteration under zsh
2227
- st=$(~/.fleet/bin/fleet-run ci-state.mjs --pr "$pr" 2>/dev/null) || : # not-green exits non-zero; the payload is the verdict
2228
- if ! printf '%s' "$st" | jq -e '.verdict and .verdict != "rate-limited"' >/dev/null 2>&1; then
2229
- case " $blind " in *" $pr "*) ;; *) # latch keyed BY PR: this cause is per-PR
2230
- echo "WATCHER DEGRADED: no usable ci-state reading for #$pr — silence is NOT green"
2231
- blind="$blind $pr" ;;
2232
- esac
2233
- continue # inner continue — still reaches the tick sleep
2220
+ # The workflow and run lookups bill a second core bucket that
2221
+ # `rate_limit` does not report. Its count is only in the response
2222
+ # headers of a lookup that bills it: one 1-unit read per tick, 4 units
2223
+ # per listed PR on the same 200 floor. Recovery for both buckets waits
2224
+ # until this gate clears too, so no line says polling resumed while
2225
+ # this one still pauses it.
2226
+ hrl=$(gh api -i 'repos/{owner}/{repo}/actions/workflows?per_page=1' 2>/dev/null | awk 'tolower($1)=="x-ratelimit-remaining:" {sub(/\r$/, "", $2); print $2; exit}')
2227
+ case "$hrl" in ''|*[!0-9]*) hrl=ERR;; esac # a missing header is an outage, not a budget
2228
+ if [ "$hrl" = ERR ] || [ "$hrl" -lt $((200 + 4 * count)) ]; then
2229
+ if [ -z "$hidden_out" ]; then
2230
+ need=; [ "$hrl" = ERR ] || need=" < $((200 + 4 * count)) needed for $count PRs" # an unreadable header has no amount to compare
2231
+ echo "WATCHER DEGRADED: unreported Actions core REST bucket=$hrl$need — CI polling paused, silence is NOT green"
2232
+ hidden_out=1
2233
+ fi
2234
+ else
2235
+ if [ -n "$budget_out" ]; then
2236
+ echo "WATCHER RECOVERED: core budget=$rl — CI polling resumed"
2237
+ budget_out=
2234
2238
  fi
2235
- case " $blind " in *" $pr "*)
2236
- echo "WATCHER RECOVERED: ci-state reading #$pr again — CI polling resumed"
2237
- keep=; for b in $(printf '%s\n' "$blind"); do [ "$b" = "$pr" ] || keep="$keep $b"; done; blind=$keep ;;
2238
- esac
2239
- : # your normal handling of $st for this PR
2240
- done
2239
+ if [ -n "$hidden_out" ]; then
2240
+ echo "WATCHER RECOVERED: unreported Actions core REST bucket=$hrl — CI polling resumed"
2241
+ hidden_out=
2242
+ fi
2243
+ for pr in $(printf '%s\n' "$prs"); do # inline $(...): `for pr in $prs` is ONE iteration under zsh
2244
+ st=$(~/.fleet/bin/fleet-run ci-state.mjs --pr "$pr" 2>/dev/null) || : # not-green exits non-zero; the payload is the verdict
2245
+ if ! printf '%s' "$st" | jq -e '.verdict and .verdict != "rate-limited"' >/dev/null 2>&1; then
2246
+ case " $blind " in *" $pr "*) ;; *) # latch keyed BY PR: this cause is per-PR
2247
+ echo "WATCHER DEGRADED: no usable ci-state reading for #$pr — silence is NOT green"
2248
+ blind="$blind $pr" ;;
2249
+ esac
2250
+ continue # inner continue — still reaches the tick sleep
2251
+ fi
2252
+ case " $blind " in *" $pr "*)
2253
+ echo "WATCHER RECOVERED: ci-state reading #$pr again — CI polling resumed"
2254
+ keep=; for b in $(printf '%s\n' "$blind"); do [ "$b" = "$pr" ] || keep="$keep $b"; done; blind=$keep ;;
2255
+ esac
2256
+ : # your normal handling of $st for this PR
2257
+ done
2258
+ fi
2241
2259
  fi
2242
2260
  fi
2243
2261
  fi
@@ -2263,8 +2281,8 @@ as a CI reading. Require the field, then compare it.
2263
2281
  never one per tick. An unlatched line at a 120s poll gets the Monitor
2264
2282
  auto-stopped for volume during even a two-minute outage, reintroducing the same
2265
2283
  blindness by another route. **Latch each cause at the level its cause lives
2266
- at**: the budget, the open-PR list and that list's cap are one global flag
2267
- each — all three are account-level — but the payload latch is keyed by PR, and a
2284
+ at**: the budget, the unreported Actions bucket, the open-PR list and that
2285
+ list's cap are one global flag each — all account-level — but the payload latch is keyed by PR, and a
2268
2286
  shared scalar for those is an unlatched line wearing a latch's clothes — one
2269
2287
  persistently blind PR alongside one healthy PR re-clears the flag on every tick,
2270
2288
  emitting a DEGRADED and a false RECOVERED pair forever. The recovery line is
@@ -2280,7 +2298,7 @@ probe pairs during exactly the outage it is reporting. Every degraded
2280
2298
  branch above falls through to the same single sleep instead.
2281
2299
 
2282
2300
  **Guard every probe, not just the ones with a verdict field.** The block makes
2283
- *three* API calls, and the third — `gh pr list` — is the one that looks like
2301
+ several API calls, and `gh pr list` is the one that looks like
2284
2302
  plumbing rather than a probe. A non-quota failure there (secondary/abuse limit,
2285
2303
  5xx, network blip, expired token) does not lower `.resources.core.remaining`, so
2286
2304
  the budget gate clears, and an unguarded `for pr in $(gh pr list …)` then
@@ -2306,8 +2324,9 @@ enforce. It latches globally like the list failure but does not pause polling:
2306
2324
  the PRs it did return are real, so the pass still watches them, and the
2307
2325
  DEGRADED line names the rest as unwatched until a pass comes back under the cap.
2308
2326
 
2309
- **The budget is gated twice, and only the second gate announces recovery.** The
2310
- tick-top floor (`200`) covers the probes themselves. Once the open-PR list is
2327
+ **The budget is gated at the floor and again at the pass, and only the pass
2328
+ gates announce recovery.** The tick-top floor (`200`) covers the `rate_limit`
2329
+ and `gh pr list` reads. Once the open-PR list is
2311
2330
  read, the pass gate reserves `200 + 4 × count` core REST units — 4 per listed PR
2312
2331
  on top of the floor, so the reserve grows with the list instead of staying a
2313
2332
  flat 200 that a long list drains mid-pass. The 4 is the measured ceiling of one
@@ -2316,21 +2335,36 @@ flat 200 that a long list drains mid-pass. The 4 is the measured ceiling of one
2316
2335
  to 100 jobs and 100 rules — more pages cost more. That counter is not the only
2317
2336
  core bucket one call bills. The lookups `actions/workflows`,
2318
2337
  `actions/workflows/<id>`, `actions/workflows/<id>/runs` and `actions/runs/<id>`
2319
- bill a second one that `rate_limit` does not report and the gate does not
2320
- guard; the boundary is per route, so `actions/runs/<id>/jobs` is on the gated
2321
- counter. Every response says `X-Ratelimit-Resource: core`, so only the reset
2322
- epoch and the used sequence tell the two apart. An exhausted unreported bucket
2323
- shows up only as per-PR `rate-limited` verdicts, which the blind-PR path
2324
- already latches. A shortfall at either gate pauses the **whole** pass through
2325
- the one budget latch and never polls a prefix of the list: a prefix runs
2338
+ bill a second one that `rate_limit` does not report; the boundary is per route,
2339
+ so `actions/runs/<id>/jobs` is on the reported counter. Every response says
2340
+ `X-Ratelimit-Resource: core`, so only the reset epoch and the used sequence tell
2341
+ the two apart, and the unreported bucket's remaining count is readable only from
2342
+ the `X-Ratelimit-Remaining` header of a call that bills it. **A second pass gate
2343
+ therefore probes it too**: one `gh api -i` read of
2344
+ `actions/workflows?per_page=1` per tick, 1 unit of that bucket (measured
2345
+ 2026-10-13: its remaining count fell by 1 per call while `rate_limit` stood
2346
+ still, and its reset epoch differed from `rate_limit`'s). A `ci-state` call
2347
+ spends 4 units of it on the common path — one `gh run list` and one `gh run view`
2348
+ cost 2 each (measured the same day) — so it is held to the same `200 + 4 × count`
2349
+ reserve. It has its own global latch (`hidden_out`) and its DEGRADED and
2350
+ RECOVERED lines name it, so a pause on this bucket is not misread as the
2351
+ reported budget running low. An unreadable header is an outage here exactly as a
2352
+ non-numeric `rate_limit` read is. The probe runs only when the reported-bucket
2353
+ gate has cleared, so a tick costs at most one probe call. The gate pauses before
2354
+ the per-PR pass, so it never touches the per-PR blind latch: a PR is either not
2355
+ polled — no per-PR line, and one already latched blind stays latched — or polled
2356
+ and reported through that latch alone, never by both. A shortfall at any of
2357
+ these gates pauses the **whole** pass and never polls a prefix of the list: a prefix runs
2326
2358
  in list order, so the same tail PRs would go unread every tick with no line at
2327
2359
  all (never polled, so nothing marks them blind), while the PRs that were polled
2328
- would run dry mid-pass and each emit a blind line. The DEGRADED line from the
2329
- pass gate names the amount it needed and the count it needed it for, so a
2330
- healthy-looking `budget=999` is not read as an outage with no cause. Only the
2331
- pass gate emits the budget RECOVERED line: announcing recovery at the floor
2332
- would report resumption on a tick whose pass gate then pauses it again — a
2333
- DEGRADED/RECOVERED pair every tick.
2360
+ would run dry mid-pass and each emit a blind line. The DEGRADED line from each
2361
+ pass gate names the amount it needed and the count it needed it for — except an
2362
+ unreadable header, which has no amount to compare and prints `bucket=ERR` alone
2363
+ — so a healthy-looking `budget=999` is not read as an outage with no cause. Only the
2364
+ pass gates emit RECOVERED lines, and both only once the pass will actually run:
2365
+ announcing recovery at the floor, or for one bucket while the other still pauses
2366
+ the pass, would report resumption on a tick whose other gate then pauses it
2367
+ again — a DEGRADED/RECOVERED pair every tick.
2334
2368
 
2335
2369
  **Judge `ci-state` on its payload, never its exit code** — the same rule as
2336
2370
  `merge-gate.mjs` applies on the merge path, applied to the watcher. `not-green` is an
@@ -3283,30 +3317,32 @@ a minute apart showed *different* mutants, so a member's report and any single
3283
3317
  silent-destruction ordering above — report it back, do not run it. One
3284
3318
  finisher refused exactly that instruction live, on the grounds it could not
3285
3319
  prove the diff was its own; that was judgement, and this is the rule.
3286
- 3. Add `ready-to-merge` — two steps, each checked on its own, in this order:
3287
- - **(a) Exactly one release label.** Read the PR's labels back
3288
- (`gh pr view <pr> --json labels`) and find **exactly one** release label,
3289
- `patch`/`minor`/`major`. Zero or more than one halts the finisher before
3290
- the label, naming which it found. This is the backstop for a label lost
3291
- wherever it was lost, a hand-created PR included: a `gh pr create` that
3292
- outran its caller's tool timeout leaves the PR open with the flag
3293
- unapplied and no exit status anywhere to notice, and nothing downstream
3294
- re-derives the release label. Count only those three — the PR carries
3295
- other labels, `ready-to-merge` itself among them once you add it, so a PR
3296
- wearing one release label beside them passes unchanged. A repo that
3297
- defines none of the three does not gate on one — `gh label list` settles
3298
- that, and it is no licence to skip the read where they exist.
3299
- - **(b) Add the label:** record the head you audited first —
3300
- `gh pr comment <pr> --body "ready-to-merge-head: <your dispatch pin>"`,
3301
- the full SHA, which the merge bot reads as the head the label was applied
3302
- to — then `gh pr edit <pr> --add-label ready-to-merge`. (a)
3303
- passing labels nothing — it is the precondition, and these commands are
3304
- the duty. Two finishers in one run stopped at (a) and reported
3305
- `labelled` on PRs that sat out of the merge queue.
3306
- 4. Report you the label (its post-add read-back: `gh pr view <pr> --json labels`
3307
- run after 3(b), output as printed), the deferral issue numbers — a
3308
- `filed: #N <subject>` line for every issue duty 2 created, and
3309
- `unrecorded: #N <subject>` for one whose `filed` failed twice — and anything
3320
+ 3. Add `ready-to-merge` by running one script, `finisher-label.mjs` — the
3321
+ release-label check and the label write are one command, because the check
3322
+ reads like the whole duty. Its exit code is the finisher's verdict:
3323
+ `~/.fleet/bin/fleet-run finisher-label.mjs --pr <pr> --pin <your dispatch pin>`,
3324
+ the pin the full SHA. In order, it finds **exactly one** release label,
3325
+ `patch`/`minor`/`major` — zero or more than one is exit 3 before anything is
3326
+ written, naming which it found; then it records the head you audited as a PR
3327
+ comment, which the merge bot reads as the head the label was applied to;
3328
+ then it adds the label and reads the labels back, and exits 0 only when that
3329
+ read-back carries `ready-to-merge`. A failed call is exit 2 and the read-back
3330
+ without the label is exit 4; no step after a failed one runs. The count is
3331
+ the backstop for a label lost wherever it was lost, a hand-created PR
3332
+ included: a `gh pr create` that outran its caller's tool timeout leaves the
3333
+ PR open with the flag unapplied and no exit status anywhere to notice, and
3334
+ nothing downstream re-derives the release label. It counts only those three
3335
+ — the PR carries other labels, `ready-to-merge` itself among them once the
3336
+ script adds it, so a PR wearing one release label beside them passes
3337
+ unchanged. A repo that defines none of the three does not gate on one — the
3338
+ script settles that from the repo's own label list and says
3339
+ `undefined-in-repo` in its receipt. Two finishers in one run stopped at the
3340
+ release-label check and reported `labelled` on PRs that sat out of the merge
3341
+ queue.
3342
+ 4. Report you the label (the script's receipt, the JSON line it printed, as
3343
+ printed), the deferral issue numbers — a `filed: #N <subject>` line for
3344
+ every issue duty 2 created, and `unrecorded: #N <subject>` for one whose
3345
+ `filed` failed twice — and anything
3310
3346
  it halted on — cause and evidence, below, never a bare "head moved". The
3311
3347
  cause is one word of the ledger's `halted:<cause>` vocabulary:
3312
3348
  `live-editor`, `rebase` or `past-pin` from the cause block below,
@@ -3411,21 +3447,26 @@ it reached, so reading that summary alone reads a partial suite as a whole one:
3411
3447
  > cause `other`, with both runs — the mutant's and the unmutated tree's — as
3412
3448
  > evidence; label nothing. A kill's evidence line goes in your report.
3413
3449
 
3414
- **Give the finisher duty 3 verbatim as well, as its two steps.** The finisher's
3450
+ **Give the finisher duty 3 verbatim as well, as one script.** The finisher's
3415
3451
  agent definition carries no duty text, so this brief is the whole of duty 3 it
3416
- sees. Two finishers in one run read the release-label check as the
3417
- whole duty and reported `labelled` on a PR that never got the label:
3418
-
3419
- > **Duty 3 is two steps, and only the second one labels.**
3420
- > (a) `gh pr view <M> --json labels` — confirm exactly one of
3421
- > `patch`/`minor`/`major`. Zero or more than one halts you before the label:
3422
- > name which you found. A repo whose `gh label list` defines none of the three
3423
- > does not gate on one.
3424
- > (b) `gh pr comment <M> --body "ready-to-merge-head: <your dispatch pin>"`
3425
- > (the full SHA), then `gh pr edit <M> --add-label ready-to-merge`. Step (a)
3426
- > passing labels nothing; these commands are the duty.
3427
- > Then run `gh pr view <M> --json labels` once more and put its output in your
3428
- > report: that read-back is what tells the controller the label is on.
3452
+ sees. Two finishers in one run read the release-label check as the whole duty
3453
+ and reported `labelled` on a PR that never got the label, so the check and the
3454
+ label write are one command and the finisher never runs either alone:
3455
+
3456
+ > **Duty 3 is one script, and its exit code is your verdict.**
3457
+ > `~/.fleet/bin/fleet-run finisher-label.mjs --pr <M> --pin <your dispatch pin>`
3458
+ > (the full SHA). It confirms exactly one of `patch`/`minor`/`major` is on the
3459
+ > PR, records the head you audited, adds `ready-to-merge`, and reads the labels
3460
+ > back. Exit 0 is the only code that means the label is on. Exit 3 means the PR
3461
+ > carries zero or more than one release label: you are halted before the label,
3462
+ > and the receipt names which it found. Exit 4 means the read-back does not carry
3463
+ > the label, written or not. Exit 2 means a `gh` call or the invocation
3464
+ > itself failed: report the stderr it printed. Every non-zero exit halts you
3465
+ > with cause `other`, with the receipt as evidence, and you do not run any of
3466
+ > its steps by hand to get past it. A repo whose label list defines none of the
3467
+ > three does not gate on one, and the script says so in its receipt. Put the
3468
+ > receipt, the JSON line it printed, in your report as printed: it is what tells
3469
+ > the controller the label is on.
3429
3470
 
3430
3471
  **Once the label is on, take it off before you approve any push.** The label is a
3431
3472
  verdict on the tree the finisher read, and a GitHub label does not follow the