@feigi/fleet-ctl 3.148.2 → 3.149.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.
@@ -45,11 +45,11 @@ Nothing else names that head. A commit's dates are when it was made, not when it
45
45
 
46
46
  **Route `current` — the recorded head is the current head — is the normal case, and it proceeds untouched** — label applied, head unchanged, merge goes ahead exactly as it did before this gate existed.
47
47
 
48
- **Route `gate` — the recorded head is not the current head — is not refused on sight: it may be a rebase-carry, and the merge gate decides.** The label binds to the change the finisher audited, not to one SHA: a rewrite that leaves the PR's net change byte-identical — a conflict-free rebase onto a newer `main` — keeps it, and anything a push adds, drops or edits does not, whenever it was pushed and however its commits are dated. So, in the main checkout after a plain `git fetch origin`, run step 3's gate now, before step 1, with `--pre <record>` and no `--post`. **`rebaseCarry` null → refuse:** report `head-moved-after-label-#<pr>` and stop on that PR. Leave the label where it is — you audited nothing and removing another member's verdict is not yours to do. What clears it is a **fresh** finisher against the new head; the first audit does not transfer, because it verified a different tree. Non-null → the current head carries the labelled head's change: `--pre` stays the labelled head on every later gate run, step 1's `pre` must read `rebaseCarry.accepted` (any other head is a push since the proof — refuse with `head-moved-after-label-#<pr>`), and your report names the carry as `rebase-carry-#<pr>` with both SHAs.
48
+ **Route `gate` — the recorded head is not the current head — is not refused on sight: it may be a rebase-carry, and the merge gate decides.** The label binds to the change the finisher audited, not to one SHA: a rewrite that leaves the PR's net change byte-identical — a conflict-free rebase onto a newer `main` — keeps it, and anything a push adds, drops or edits does not, whenever it was pushed and however its commits are dated. So, in the main checkout after a plain `git fetch origin`, run step 3's gate now, before step 1, with `--pre <record>` and no `--post`. **`rebaseCarry` null → refuse:** report `head-moved-after-label-#<pr>` and stop on that PR. Leave the label where it is — you audited nothing and removing another member's verdict is not yours to do; your report's settle takes it off before the fresh finisher. What clears it is a **fresh** finisher against the new head; the first audit does not transfer, because it verified a different tree. Non-null → the current head carries the labelled head's change: `--pre` stays the labelled head on every later gate run, step 1's `pre` must read `rebaseCarry.accepted` (any other head is a push since the proof — refuse with `head-moved-after-label-#<pr>`), and your report names the carry as `rebase-carry-#<pr>` with both SHAs.
49
49
 
50
50
  **Route `timeline` — no record, a hand-added label or one applied before its labeller recorded a head — falls back to the timeline, which can refuse a moved head but never name the labelled one.** The command has already read it, `gh api repos/{owner}/{repo}/issues/<pr>/timeline?per_page=100 --paginate`, and printed the verdict as `timeline: {label, verdict, after}`, `label` the Label map's string for `ready-to-merge`. Run the command before `gh pr update-branch`, on this route too: your own rebase lands commits after the label by construction, so once you have rebased this read can no longer tell your commits from someone else's.
51
51
 
52
- `verdict` is `moved` when a `committed` or `head_ref_force_pushed` event follows the last `labeled` event for that string, `after` listing those events as `<event> <sha>`; otherwise `clean`. **`moved` with no record → refuse:** report `head-moved-after-label-#<pr>` and stop on that PR, the label left where it is — nothing names a head the label was applied to, so no carry can be proven. **`clean` is the normal case, and it proceeds untouched.** A timeline with no `labeled` event for that string has no verdict: the label is on the PR, so a read that never saw it applied came back empty or wrong, and the command exits 2 with `step` `read-timeline`.
52
+ `verdict` is `moved` when a `committed` or `head_ref_force_pushed` event follows the last `labeled` event for that string, `after` listing those events as `<event> <sha>`; otherwise `clean`. **`moved` with no record → refuse:** report `head-moved-after-label-#<pr>` and stop on that PR, the label left where it is for your report's settle to take off — nothing names a head the label was applied to, so no carry can be proven. **`clean` is the normal case, and it proceeds untouched.** A timeline with no `labeled` event for that string has no verdict: the label is on the PR, so a read that never saw it applied came back empty or wrong, and the command exits 2 with `step` `read-timeline`.
53
53
 
54
54
  Record the head before you rebase — the `head` the command printed, read before anything moved it — because step 3 hands it to the merge gate as `--pre` and nothing later can reconstruct it. Where step 1 runs, that is its `pre`; on an already-current PR it is simply the head you merge. After a carry, `--pre` is the labelled head instead.
55
55
 
@@ -142,7 +142,7 @@ For each labeled PR, lowest first:
142
142
 
143
143
  **Why the ref and not `headRefOid`: during the PR object's lag both operands go stale in the SAME direction, so that compare fails OPEN as readily as it fails closed.** The false STOP is the visible half — the worktree holds the rebased head, the PR object still holds the pre-rebase sha, and a correct tree comes back `worktree-diverged-#<pr>`, costing a pass. The silent half is the one that ships: a worktree that has not fetched since the rebase sits on that same pre-rebase sha, so BOTH sides read it, the check reads **Equal**, and this fallback verifies a tree the remote no longer has while step 4 merges the head it does — a green measured against a tree no merge will take, which is the exact failure the STOP arm below exists to prevent, reached through the arm that passes. Measured at the sibling site (`run-team/SKILL.md` phase 1) in a scratch repo: a clone unfetched since the rebase resolved `origin/<branch>` to the pre-rebase commit with its subject unchanged, while `git ls-remote origin refs/heads/<branch>` read the true tip from that same clone. **Re-reading `headRefOid` on a settle window does not reach that half at all** — it fires only where the two disagree — which is why the operand changes here rather than the verdict gaining a window.
144
144
 
145
- **Unequal → `git fetch origin` and read the ref once more, then decide on that second reading. Bounded at one re-read, never a third.** Neither operand is a cached value, so a stable second reading cannot flip the verdict; what the re-read is for is the ref MOVING while you verify, which is live here because one way into this fallback is a step-1 poll whose cap ran out with the ref unmoved, and that call is async — it can land a moment after you gave up on it. The two readings differ → the head is not settled and the audit behind the label verified a tree that is already gone, so **refuse: report `head-moved-after-label-#<pr>` and stop**, label untouched, the same verdict and the same remedy — a fresh finisher against the new head — the gate above reaches for a head that moved after the audit. Do not read a third time; that is the unbounded wait step 1 had to be written out of. The two readings agree → the mismatch is real and belongs to one of the two arms below. **`Equal` is not among the outcomes a surviving mismatch can reach**: a worktree that is not on the branch ref never passes this check, whatever the PR object says.
145
+ **Unequal → `git fetch origin` and read the ref once more, then decide on that second reading. Bounded at one re-read, never a third.** Neither operand is a cached value, so a stable second reading cannot flip the verdict; what the re-read is for is the ref MOVING while you verify, which is live here because one way into this fallback is a step-1 poll whose cap ran out with the ref unmoved, and that call is async — it can land a moment after you gave up on it. The two readings differ → the head is not settled and the audit behind the label verified a tree that is already gone, so **refuse: report `head-moved-after-label-#<pr>` and stop**, the label left for your report's settle to take off, the same verdict and the same remedy — a fresh finisher against the new head — the gate above reaches for a head that moved after the audit. Do not read a third time; that is the unbounded wait step 1 had to be written out of. The two readings agree → the mismatch is real and belongs to one of the two arms below. **`Equal` is not among the outcomes a surviving mismatch can reach**: a worktree that is not on the branch ref never passes this check, whatever the PR object says.
146
146
 
147
147
  **Ahead or behind is the `unique` verdict of `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run unique-in-upstream.mjs --worktree <worktree> --upstream origin/<branch>`, run after that fetch — not the sha compare.** A rebase orphans the pre-rebase head, so the ref does not carry the worktree's commits BY SHA even where it carries every patch in them; read the mismatch as "commits the ref lacks" and a worktree holding no work of its own answers yes and takes the STOP. Patch equivalence is the question, and the verdict is not a raw `git cherry` line: a patch id ignores position and whitespace, so an unpushed commit that repeats a change the branch carries elsewhere in the file, or differs from it by whitespace alone, reads `-` there and the STOP would not fire. The script reads `unique` true when `git cherry` shows a `+`, `origin/<branch>..HEAD` holds a merge commit, or merging HEAD into `origin/<branch>` conflicts or makes a tree other than the branch's own: `"unique": true` → ahead; `"unique": false` → behind, a worktree the rebase superseded included — unless its branch carried a merge commit the rebase dropped. The worktree still holds that merge, so it reads `"unique": true` with `merges` above 0, `content.paths` empty and every `listing` line `-`, and takes the STOP as ahead though it holds no work of its own; say in the report that the merge is all it holds. Exit 2 is no verdict — the read failed and the error is named — and is not behind: take the STOP, report `worktree-diverged-#<pr>` and quote the error.
148
148
 
@@ -209,7 +209,7 @@ For each labeled PR, lowest first:
209
209
 
210
210
  Each `reason` is a fact the gate now enforces, not a step you run:
211
211
 
212
- - **`head-moved-after-label`** — the PR head is neither `pre` nor `post`, nor a head whose net change the gate proved identical to `pre`'s (`rebaseCarry`, which names both). **Any third SHA is a push that landed while you waited on CI, and no CI check can see it**: `ci-state.mjs` selects the run whose `headSha` equals the *current* PR head (`scripts/ci-state.mjs`, the `r.headSha === prHead` filter), so a member's push plus its own green run satisfies every CI check while the audit behind the label belongs to a tree that is gone. A carry is proven only for the head `gh pr view` read; a different head at `ci-state`'s own read is still this row. The remedy is a fresh finisher against the new head, label untouched.
212
+ - **`head-moved-after-label`** — the PR head is neither `pre` nor `post`, nor a head whose net change the gate proved identical to `pre`'s (`rebaseCarry`, which names both). **Any third SHA is a push that landed while you waited on CI, and no CI check can see it**: `ci-state.mjs` selects the run whose `headSha` equals the *current* PR head (`scripts/ci-state.mjs`, the `r.headSha === prHead` filter), so a member's push plus its own green run satisfies every CI check while the audit behind the label belongs to a tree that is gone. A carry is proven only for the head `gh pr view` read; a different head at `ci-state`'s own read is still this row. The remedy is a fresh finisher against the new head: the bot leaves the label, and its report's settle takes it off before that finisher.
213
213
  - **`main-gain-removed:<path>`** — merging this head would remove lines `main` gained after the PR's work began: lines a later merge landed, deleted by a branch commit that every rebase since has replayed without a conflict, so no conflict preview and no `origin/main...HEAD` read is sure to show them. `mainGain.hits[]` names each file, the landing key (`#<n>` for a merged PR, else the landing commit's 12-character SHA), the removed lines, each hunk that held any of them (`hunks[]`: the line numbers, the `added` lines the removed tokens were compared against, and the `missing` tokens with counts, a blank line's token written `"\n"`), and the `ack` line to copy. Skip the PR, leave the label alone, and report `main-gain-removed:<path>-#<pr>` with the hit list and the keys. Never restore the lines yourself — the removal may be deliberate. It clears when the PR stops removing them or its body carries `main-gain-removal: <path> <key> - <why>` for every hit; the gate reads the body each run, so editing it is enough. An acknowledged removal is listed in `mainGain.acknowledged[]` and the gate passes it — name each one, with its reason, in your report. Your report's `refused[]` entry for the PR carries the gate's `reason` as it printed it, `main-gain-removed:<path>`, and the gate's `--out` file above stays where the gate wrote it: the controller parks the PR off that entry, at the `head` and `bodyDigest` that file records the gate refused, and no merge bot is dispatched on the PR's account until its head or its body changes — though a bot dispatched for another queued PR may still evaluate it again.
214
214
 
215
215
  Each hit line carries a `kind`: `modified` when the hunk that removed it also adds lines, none of which claimed it as an in-place edit, or `deleted` when the hunk only removes lines. The gate clears a gained line, lists it in `mainGain.edited[]` with the `rule` that cleared it, and passes it, by three rules. `line`: a removed line edited in place that keeps every token of its text, one entry per line. `hunk`: every removed line of a hunk that adds lines — gained and older lines alike, a blank line counting as one blank token — has its tokens among the hunk's added lines, as a re-wrap does, so the gained lines no `line` entry covers clear together. `retracted #N`: the hunk rule fails only because the PR deleted a forward reference to a ticket it closes (`once #N lands`, `until #N ships` and the like), so the reference's tokens are dropped from the removed side and the one token after it may differ from an added token in case alone; `N` lists every closing issue its removed phrases named, and a PR that only refers to the ticket (`Refs #N`) gets no such clearing. A `hunk` or `retracted #N` entry is one per cleared hunk: `line` is its first cleared gained line, `text` the cleared lines joined with a newline and `replacement` the added lines compared. Tokens never cross hunks, and a hunk that only removes lines is never cleared, so a `deleted` line is always a hit. The gate reads which issues the PR closes from the references `--closing-refs` carries, echoed as `closes`, `null` when they could not be read, which turns the retraction rule off.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.148.2",
3
+ "version": "3.149.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": {
@@ -78,8 +78,20 @@
78
78
  // entry whose reason is `main-gain-removed:<path>`, bound to the head
79
79
  // and body digest the bot's gate reading `<scratch>/pr<pr>/<merge-bot-n>/ci.json`
80
80
  // records it refused, unless the rows already carry it (a reading that
81
- // is missing or is not that refusal is a NEED, nothing written), then
82
- // `settle --from-report`.
81
+ // is missing or is not that refusal is a NEED, nothing written).
82
+ // For each `refused[]` entry whose reason is `head-moved-after-label`
83
+ // the label comes off, as `label-off <pr>` below does, unless the
84
+ // ledger already holds the bot settled (a replayed report never takes
85
+ // off a label put back since), or the PR is not open, no longer
86
+ // carries `ready-to-merge`, or its newest
87
+ // `ready-to-merge-head:` record names its current head (a newer audit
88
+ // covers it); then one PR comment names the bot, the recorded head (or
89
+ // that there is none) and the PR's head, skipped when the PR already
90
+ // carries it. A PR that cannot be read is a NEED, nothing written; a
91
+ // comment that fails to post is a NEED carrying its text, since the
92
+ // label is off by then and no re-run reaches the comment again. The
93
+ // bot itself leaves the label alone; the fresh finisher dispatches
94
+ // onto a PR with none. Then `settle --from-report`.
83
95
  // Every other refusal reason writes nothing. The reap and the reclaim
84
96
  // run under the tick's `--apply`.
85
97
  // The reap and the reclaim run once for every merge bot settled `done`, always, even when the pass merged nothing, and again on the next tick after an `APPLY FAILED` line, and on every tick while this run has no controller record to remember the pass by.
@@ -112,6 +124,22 @@
112
124
  // label <pr>
113
125
  // No write: a `ready-to-merge` label was seen, and the tick is the whole
114
126
  // of the event.
127
+ // label-off <pr>
128
+ // Takes `ready-to-merge` off PR <pr> and is unconditional: its caller
129
+ // decides that the label comes off. It names the attempt whose label
130
+ // comes off — the latest `finisher-pr-<pr>[-x]` that settled `labelled`
131
+ // after the highest attempt a `label-off=` already names, read off the
132
+ // rows and `## Dispatched` as the tick reads them — and writes
133
+ // `ledger.mjs token <pr> label-off=<attempt>`, no token when no attempt
134
+ // settled `labelled` (a hand label) or a token already names it. Then
135
+ // `gh pr edit <pr> --remove-label` and a read of the PR's labels. The
136
+ // token always lands before the removal. A refused token write, a
137
+ // failed removal, or a read-back that does not answer or still carries
138
+ // the label, is a `NEED label-off PR #<pr> …` naming this command, the
139
+ // label left on when the token is refused; a re-run removes the label
140
+ // and adds no second token. A latest attempt still live is a NEED once
141
+ // the label is off: no token can name it yet, so run the command again
142
+ // once it settles.
115
143
  // conflict <pr>
116
144
  // The tick's `CONFLICT` line for the PR, recorded: `ledger.mjs token
117
145
  // <pr> conflict-hold:#<pr>`, no note beside it (`token` refuses any
@@ -200,8 +228,9 @@ import { gitEnv } from "./git-env.mjs";
200
228
  import { isCLI } from "./is-cli.mjs";
201
229
  import { LabelMapUnreadable, readLabelMap } from "./label-map.mjs";
202
230
  import { BRIEFS, REVIEW, REVIEWED, REVIEWER, dispositionsToken, memberTokens, nextReviewerName, parseDispatchedEntry, parseMember, parseToken, readRetired, rowNums } from "./ledger-grammar.mjs";
203
- import { NO_TRANSCRIPT_AFTER_DEFAULT, PARKS, controllerState, foldLedger, parkedToken } from "./fleet-tick.mjs";
231
+ import { NO_TRANSCRIPT_AFTER_DEFAULT, PARKS, controllerState, foldLedger, latestFinisherAttempts, parkedToken } from "./fleet-tick.mjs";
204
232
  import { phase0Gate, readRunReceipt, tickCaps } from "./phase0-receipt.mjs";
233
+ import { newestHeadRecord } from "./ready-to-merge-head.mjs";
205
234
  import { defaultScratch, readReportIn, reportsDir } from "./report-files.mjs";
206
235
  import { readRecipe } from "./recipe-read.mjs";
207
236
  import { readState, statePath } from "./fleet-state.mjs";
@@ -222,6 +251,7 @@ const KINDS = {
222
251
  "review-failed": { args: ["<pr>", "<launch>"], pr: true },
223
252
  ci: { args: ["<pr>"], pr: true },
224
253
  label: { args: ["<pr>"], pr: true },
254
+ "label-off": { args: ["<pr>"], pr: true },
225
255
  conflict: { args: ["<pr>"], pr: true },
226
256
  heartbeat: { args: [] },
227
257
  drain: { args: [], flag: "--reason \"<reason>\"" },
@@ -336,6 +366,18 @@ class Event {
336
366
  this.note(`${what} refused (${r.how})`);
337
367
  }
338
368
 
369
+ // `ledger.mjs token <pr> <tok>`, noted, or refused as refuse() keeps it.
370
+ // False when the ledger refused it.
371
+ token(pr, tok) {
372
+ const w = node("ledger.mjs", ["token", String(pr), tok]);
373
+ if (w.status !== 0) {
374
+ this.refuse(`token #${pr} ${tok}`, w);
375
+ return false;
376
+ }
377
+ this.note(`#${pr} ${tok}`);
378
+ return true;
379
+ }
380
+
339
381
  report(member) {
340
382
  return readReportIn(reportsDir(this.scratch), member);
341
383
  }
@@ -391,15 +433,16 @@ class Event {
391
433
  return { labels: (v.labels ?? []).map((l) => l?.name), bodies: v.comments.map((c) => String(c?.body ?? "").trim()), state: v.state ?? null };
392
434
  }
393
435
 
394
- // `gh <noun> comment <n> --body <body>` unless `seen` already holds it.
395
- comment(noun, n, body, seen, what) {
436
+ // `gh <noun> comment <n> --body <body>` unless `seen` already holds it. A
437
+ // failed post is a NEED, `remedy` appended when the caller can name one.
438
+ comment(noun, n, body, seen, what, remedy = null) {
396
439
  if (seen.bodies.includes(body.trim())) {
397
440
  this.note(`${what} already on #${n}`);
398
441
  return true;
399
442
  }
400
443
  const r = gh([noun, "comment", String(n), "--body", body]);
401
444
  if (r.status !== 0) {
402
- this.need(`${what} #${n} — gh ${noun} comment failed: ${said(r)}`);
445
+ this.need(`${what} #${n} — gh ${noun} comment failed: ${said(r)}${remedy === null ? "" : `; ${remedy}`}`);
403
446
  return false;
404
447
  }
405
448
  this.note(`${what} posted on #${n}`);
@@ -669,10 +712,130 @@ function mergeBotReport(ev, member) {
669
712
  const read = ev.report(member);
670
713
  for (const { pr, reason } of read.state === "ok" ? read.report.refused : []) {
671
714
  if (PARKS.test(reason)) park(ev, member, pr, reason);
715
+ else if (reason === MOVED) movedAfterLabel(ev, member, pr);
672
716
  }
673
717
  ev.settle(member);
674
718
  }
675
719
 
720
+ // The refusal reason of a head no carry proves, which ends the label.
721
+ const MOVED = "head-moved-after-label";
722
+
723
+ // PR `pr`'s state, labels, head and comments as one `gh pr view`, or null
724
+ // when gh could not answer (the NEED, named `what`, is printed here).
725
+ function prView(ev, pr, what) {
726
+ const r = gh(["pr", "view", String(pr), "--json", "state,labels,headRefOid,comments"]);
727
+ let v = null;
728
+ if (r.status === 0) {
729
+ try {
730
+ v = JSON.parse(r.stdout);
731
+ } catch {
732
+ // Falls through to the NEED below.
733
+ }
734
+ }
735
+ const isObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
736
+ if (!isObject(v) || typeof v.state !== "string" || !Array.isArray(v.labels) || !v.labels.every((l) => typeof l?.name === "string")
737
+ || !/^[0-9a-f]{40}$/.test(v.headRefOid) || !Array.isArray(v.comments)
738
+ || !v.comments.every((c) => isObject(c) && typeof c.body === "string" && typeof c.createdAt === "string")) {
739
+ ev.need(`${what} — gh pr view ${pr} did not answer a PR (${r.status === 0 ? `unexpected shape: ${r.stdout.trim().slice(0, 120)}` : said(r)})`);
740
+ return null;
741
+ }
742
+ return { state: v.state, labels: v.labels.map((l) => l.name), head: v.headRefOid, comments: v.comments, bodies: v.comments.map((c) => c.body.trim()) };
743
+ }
744
+
745
+ // A merge bot's `head-moved-after-label` refusal ends the label: PR `pr` is
746
+ // taken off the queue for a fresh finisher, unless the ledger already holds
747
+ // the bot settled — a replayed report, which must not take off a label put
748
+ // back since — or the PR is no longer open, no longer carries the label, or
749
+ // its newest `ready-to-merge-head:` record
750
+ // names its current head (a newer audit covers it — labelled-head.mjs's route
751
+ // `current`). Then one comment names the bot, the recorded head and the
752
+ // PR's head, skipped when the PR already carries it. A comment that fails to
753
+ // post is a NEED carrying its text: the label is off by then, so no re-run
754
+ // reaches the comment again.
755
+ function movedAfterLabel(ev, member, pr) {
756
+ const what = `take-off PR #${pr} ${MOVED}`;
757
+ if (settledOutcome(ev.ledger, member) !== null) {
758
+ ev.note(`#${pr} ${MOVED}: ${member} already settled, label left`);
759
+ return;
760
+ }
761
+ const ready = ev.labels["ready-to-merge"];
762
+ const view = prView(ev, pr, `${what} — if it is open and labelled, run fleet-event.mjs label-off ${pr}`);
763
+ if (view === null) return;
764
+ if (view.state !== "OPEN") {
765
+ ev.note(`#${pr} ${MOVED}: not open, label left`);
766
+ return;
767
+ }
768
+ if (!view.labels.includes(ready)) {
769
+ ev.note(`#${pr} ${MOVED}: no ${ready} on it, nothing to take off`);
770
+ return;
771
+ }
772
+ const record = newestHeadRecord(view.comments);
773
+ if (record === view.head) {
774
+ ev.note(`#${pr} ${MOVED}: its newest head record names its head, label left`);
775
+ return;
776
+ }
777
+ if (!takeLabelOff(ev, pr)) return;
778
+ const headline = `${member} refused this PR \`${MOVED}\`; \`${ready}\` came off for a fresh finisher`;
779
+ const heads = [`recorded head: ${record ?? "none recorded"}`, `PR head: ${view.head}`];
780
+ const body = `**${headline}.**\n\n${heads.map((h) => `- ${h}`).join("\n")}`;
781
+ ev.comment("pr", pr, body, view, `${MOVED} comment`,
782
+ `the label is already off, so no re-run posts it: comment it by hand — ${headline} (${heads.join("; ")})`);
783
+ }
784
+
785
+ // `label-off=<attempt>` on PR `pr`'s row, then `ready-to-merge` off the PR,
786
+ // read back. The attempt is the latest `finisher-pr-<pr>[-x]` that settled
787
+ // `labelled`, read as the tick reads attempts — after the highest attempt a
788
+ // `label-off=` already names — so none is written for a label no finisher
789
+ // applied, nor a second for an attempt a token already names. The token lands
790
+ // before the removal. False when the label could not be taken off: a NEED
791
+ // naming the command is printed, beside the token's own refusal when the
792
+ // ledger refused it.
793
+ // A latest attempt still live is a NEED once the label is off: no token can
794
+ // name it yet, and should it settle `labelled` the tick would read the
795
+ // removal as its miss, so the command is to be run again once it settles.
796
+ function takeLabelOff(ev, pr) {
797
+ const ready = ev.labels["ready-to-merge"];
798
+ const again = `run fleet-event.mjs label-off ${pr} again`;
799
+ const stretch = latestFinisherAttempts(ev.ledger, new Set([pr]))[0];
800
+ const attempt = stretch?.attempts.filter((a) => a.outcome === "labelled").at(-1)?.name;
801
+ const live = stretch?.outcome === null ? stretch.attempts.at(-1).name : null;
802
+ if (attempt === undefined) {
803
+ ev.note(`#${pr}: no finisher attempt settled labelled since the last label-off=, none written`);
804
+ } else {
805
+ const tok = `label-off=${attempt}`;
806
+ if (!ev.token(pr, tok)) {
807
+ ev.need(`label-off PR #${pr} — the ledger refused ${tok}, so ${ready} is left on; ${again}`);
808
+ return false;
809
+ }
810
+ }
811
+ const e = gh(["pr", "edit", String(pr), "--remove-label", ready]);
812
+ if (e.status !== 0) {
813
+ ev.need(`label-off PR #${pr} — gh pr edit failed: ${said(e)}; ${again}`);
814
+ return false;
815
+ }
816
+ const back = gh(["pr", "view", String(pr), "--json", "labels"]);
817
+ let labels = null;
818
+ if (back.status === 0) {
819
+ try {
820
+ const l = JSON.parse(back.stdout).labels;
821
+ if (Array.isArray(l) && l.every((x) => typeof x?.name === "string")) labels = l.map((x) => x.name);
822
+ } catch {
823
+ // Read as no answer below.
824
+ }
825
+ }
826
+ if (labels === null) {
827
+ ev.need(`label-off PR #${pr} — the read-back of its labels did not answer (${back.status === 0 ? "unexpected shape" : said(back)}); ${again}`);
828
+ return false;
829
+ }
830
+ if (labels.includes(ready)) {
831
+ ev.need(`label-off PR #${pr} — it still carries ${ready} after the removal; ${again}`);
832
+ return false;
833
+ }
834
+ ev.note(`#${pr} ${ready} taken off`);
835
+ if (live !== null) ev.need(`label-off PR #${pr} — ${live} is still live, so no label-off= names it; once it settles, ${again}`);
836
+ return true;
837
+ }
838
+
676
839
  // `ledger.mjs token <pr> parked=<head>:<body digest>:<reason>` for a refusal
677
840
  // only a human edit clears, bound to the head and body the gate refused: the
678
841
  // bot's own gate reading, `<scratch>/pr<pr>/<member>/ci.json` (run-merge-bot.md
@@ -702,9 +865,7 @@ function park(ev, member, pr, reason) {
702
865
  ev.note(`#${pr} already ${tok}`);
703
866
  return;
704
867
  }
705
- const w = node("ledger.mjs", ["token", String(pr), tok]);
706
- if (w.status === 0) ev.note(`#${pr} ${tok}`);
707
- else ev.refuse(`token #${pr} ${tok}`, w);
868
+ ev.token(pr, tok);
708
869
  }
709
870
 
710
871
  // `p` with its symlinks resolved, or as written when it does not exist yet.
@@ -814,9 +975,7 @@ function ci(ev, pr) {
814
975
  ev.note(`#${pr} already ${tok}`);
815
976
  return;
816
977
  }
817
- const w = node("ledger.mjs", ["token", String(pr), tok]);
818
- if (w.status === 0) ev.note(`#${pr} ${tok}`);
819
- else ev.refuse(`token #${pr} ${tok}`, w);
978
+ ev.token(pr, tok);
820
979
  }
821
980
 
822
981
  // A second hold on a row that already answered one is the same word spelled
@@ -834,9 +993,7 @@ function conflict(ev, pr) {
834
993
  ev.note(`#${pr} conflict hold refused (row already holds)`);
835
994
  return;
836
995
  }
837
- const w = node("ledger.mjs", ["token", String(pr), tok]);
838
- if (w.status === 0) ev.note(`#${pr} ${tok}`);
839
- else ev.refuse(`token #${pr} ${tok}`, w);
996
+ ev.token(pr, tok);
840
997
  }
841
998
 
842
999
  function drain(ev, reason) {
@@ -1016,6 +1173,7 @@ function main() {
1016
1173
  else if (kind === "review-result") reviewResult(ev, pr, args[1]);
1017
1174
  else if (kind === "review-failed") reviewFailed(ev, pr, args[1]);
1018
1175
  else if (kind === "ci") ci(ev, pr);
1176
+ else if (kind === "label-off") takeLabelOff(ev, pr);
1019
1177
  else if (kind === "conflict") conflict(ev, pr);
1020
1178
  else if (kind === "drain") drain(ev, reason);
1021
1179
  else if (kind === "undrain") undrain(ev, reason);
@@ -665,10 +665,11 @@ export function currentDispositions(tokens, run) {
665
665
  return best === null ? null : { verdict: best.verdict, member: best.member.name };
666
666
  }
667
667
 
668
- // `label-off=<finisher-pr-M[-x]>` — written by the controller BEFORE it
669
- // takes `ready-to-merge` off PR M on purpose (before approving a push; clearing
670
- // a label left on a moved head), naming the latest finisher attempt. A missing
671
- // label is a finisher's miss only when no such removal accounts for it.
668
+ // `label-off=<finisher-pr-M[-x]>` — written by `fleet-event.mjs label-off M`
669
+ // BEFORE it takes `ready-to-merge` off PR M on purpose (before approving a
670
+ // push; a merge bot's `head-moved-after-label` refusal), naming the attempt
671
+ // that settled `labelled`. A missing label is a finisher's miss only when no
672
+ // such removal accounts for it.
672
673
  // `undefined` for a token that is not a label-off at all, null for one naming
673
674
  // no finisher-pr member — `ledger.mjs row` refuses that one at write time, and
674
675
  // deriveRun refuses a hand-written one.
@@ -214,7 +214,7 @@ function defaultLedgerPath() {
214
214
  }
215
215
 
216
216
  // What `row` and `token` say of a `label-off=` naming no finisher this run has.
217
- const LABEL_OFF_UNKNOWN = "names no finisher-pr member this run has dispatched or recorded — label-off=<finisher-pr-M[-x]>, the latest finisher attempt, before taking ready-to-merge off PR M";
217
+ const LABEL_OFF_UNKNOWN = "names no finisher-pr member this run has dispatched or recorded — label-off=<finisher-pr-M[-x]>, the attempt that settled labelled, before taking ready-to-merge off PR M (fleet-event.mjs label-off M writes it)";
218
218
 
219
219
  const argv = process.argv.slice(2);
220
220
  // Both flags are read by EXACT token below (`indexOf`), so the `--flag=value`
@@ -2180,23 +2180,30 @@ async function closingRefusals(member, { tickets, ruling, tsv }) {
2180
2180
  return { refs: closed, failures };
2181
2181
  }
2182
2182
 
2183
- // The finisher gate's release-label check for the PR `member` finishes: the
2184
- // PR carries exactly one release label, or its repository defines none, as
2185
- // finisher-label.mjs counts them before it labels. `tickets` are the tickets
2186
- // rulingOf() found settled implementer tokens naming the PR for, and `refs`
2187
- // the issues closingRefusals() read it closing, its own suggestion-band
2188
- // record aside. Returns the refusal, or null.
2183
+ // The finisher gate's label checks for the PR `member` finishes: the PR
2184
+ // carries no `ready-to-merge` — a finisher runs on an unlabelled PR, and the
2185
+ // label comes off with `fleet-event.mjs label-off`, which names the attempt
2186
+ // that applied it — and exactly one release label, or its repository defines
2187
+ // none, as finisher-label.mjs counts them before it labels. `tickets` are the
2188
+ // tickets rulingOf() found settled implementer tokens naming the PR for, and
2189
+ // `refs` the issues closingRefusals() read it closing, its own
2190
+ // suggestion-band record aside. Returns the refusal, or null.
2189
2191
  // A Ticketless PR (ticketless.mjs's isTicketless) with none is not refused:
2190
2192
  // finisher-label.mjs adds `patch` to it. A repository label list that may be
2191
2193
  // cut off still refuses it, as finisher-label.mjs refuses it then too. Any
2192
2194
  // other PR's bump is not picked here, and neither is which of several labels
2193
2195
  // stays. A read the check needs dies, naming the labels it could not read,
2194
2196
  // and writes nothing.
2195
- function releaseLabelRefusal(member, tickets, refs) {
2197
+ function labelRefusal(member, tickets, refs) {
2196
2198
  const pr = member.number;
2197
2199
  const where = `dispatch ${member.name}`;
2198
- const { prLabels, repoLabels } = checkReaders(where);
2199
- const found = releaseLabelsIn(prLabels(pr));
2200
+ const { prLabels, repoLabels, repoDir } = checkReaders(where);
2201
+ const labels = prLabels(pr);
2202
+ const ready = readyLabel(repoDir(), where);
2203
+ if (labels.includes(ready)) {
2204
+ return `PR #${pr} carries ${ready} — a finisher runs on a PR without it: run \`fleet-event.mjs label-off ${pr}\`, then dispatch ${member.name} again`;
2205
+ }
2206
+ const found = releaseLabelsIn(labels);
2200
2207
  if (found.length === 1) return null;
2201
2208
  if (found.length > 1) return `PR #${pr} carries more than one release label (${found.join(", ")}) — exactly one may stay, and which is not picked here`;
2202
2209
  const defined = releaseLabelsDefined(repoLabels());
@@ -2213,12 +2220,13 @@ function releaseLabelRefusal(member, tickets, refs) {
2213
2220
  }
2214
2221
 
2215
2222
  // The tracker's string for the `ready-to-merge` Label role, off the Label map
2216
- // of the repository `dir` belongs to (label-map.mjs). Only the two paths that
2217
- // compare or list that label read it — `dispatch merge-bot`'s queueSnapshot()
2218
- // and settle --from-report's finisher and merge-bot checks — so every other
2219
- // verb runs with no map at all. A map that cannot be read, or no repository
2220
- // to find one in, is exit 2 under `where`, carrying the reader's message (an
2221
- // absent or invalid map's names `label-map.mjs ensure`); nothing written.
2223
+ // of the repository `dir` belongs to (label-map.mjs). Only the paths that
2224
+ // compare or list that label read it — `dispatch merge-bot`'s queueSnapshot(),
2225
+ // `dispatch finisher-pr-M`'s labelRefusal() and settle --from-report's
2226
+ // finisher and merge-bot checks — so every other verb runs with no map at all.
2227
+ // A map that cannot be read, or no repository to find one in, is exit 2 under
2228
+ // `where`, carrying the reader's message (an absent or invalid map's names
2229
+ // `label-map.mjs ensure`); nothing written.
2222
2230
  function readyLabel(dir, where) {
2223
2231
  try {
2224
2232
  return readLabelMap({ cwd: dir })["ready-to-merge"];
@@ -2404,9 +2412,9 @@ async function runDispatch() {
2404
2412
  // waits on its ruling, its tier-outcomes row, written while the PR is open
2405
2413
  // and its review evidence still in scratch; see rulingOf(). Last, the
2406
2414
  // PR's closing references must match that ruling and exclude its own
2407
- // suggestion-band record, and the PR must carry exactly one release label,
2408
- // both read off gh from the ledger's repository; see closingRefusals() and
2409
- // releaseLabelRefusal(). Refused here, before anything is written, so no
2415
+ // suggestion-band record, and the PR must carry no `ready-to-merge` and
2416
+ // exactly one release label, all read off gh from the ledger's repository; see closingRefusals() and
2417
+ // labelRefusal(). Refused here, before anything is written, so no
2410
2418
  // check can be skipped by forgetting to run it.
2411
2419
  if (member.family === "finisher-pr") {
2412
2420
  const fold = tickFold("conflict hold and dispositions verdict");
@@ -2420,8 +2428,8 @@ async function runDispatch() {
2420
2428
  const ruled = await rulingOf(member.number);
2421
2429
  if (ruled.refusal !== null) die(`${member.name}: ${ruled.refusal} — not dispatching ${member.name}`);
2422
2430
  const closing = await closingRefusals(member, ruled);
2423
- const labelled = releaseLabelRefusal(member, ruled.tickets, closing.refs);
2424
- const failures = labelled === null ? closing.failures : [...closing.failures, labelled];
2431
+ const labelFailure = labelRefusal(member, ruled.tickets, closing.refs);
2432
+ const failures = labelFailure === null ? closing.failures : [...closing.failures, labelFailure];
2425
2433
  if (failures.length > 0) die(`${member.name}: ${failures.join("; ")} — not dispatching ${member.name}`);
2426
2434
  }
2427
2435
  // Every error caught here carries its own cause and remedy — a row's `tier=` or `cell=`
@@ -2730,7 +2738,8 @@ function recordFiled(id, subject) {
2730
2738
  // `ready-to-merge` in both rows is the Label map's string for the role, read
2731
2739
  // by readyLabel() only when one of the two checks runs: on a finisher's
2732
2740
  // `labelled`, and on a merge bot's report that leaves a PR queued at dispatch
2733
- // without a verdict.
2741
+ // without a verdict. Outside settle, `dispatch finisher-pr-M` reads it too,
2742
+ // to refuse a finisher onto a labelled PR (labelRefusal()).
2734
2743
  //
2735
2744
  // THE CHECK-STEP RECORD, for `impl-N=PR#M` and `fix-pr-M=applied:<head>`:
2736
2745
  // recipe-check.mjs writes `<reports>/<member>.check.json` on the member's
@@ -133,6 +133,7 @@ Run each as `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run flee
133
133
  | Merge-bot pass report | `fleet-event.mjs merge-bot-report merge-bot-<n>` |
134
134
  | CI run terminal | `fleet-event.mjs ci <pr>` |
135
135
  | Label seen (persistent Monitor) | `fleet-event.mjs label <pr>` |
136
+ | Label to come off before an approved push | `fleet-event.mjs label-off <pr>` |
136
137
  | `CONFLICT` line | `fleet-event.mjs conflict <pr>` |
137
138
  | Alarm (a [fleet-alarm] turn) | `fleet-event.mjs heartbeat` |
138
139
  | Drain | `fleet-event.mjs drain --reason "<reason>"` |
@@ -630,10 +631,9 @@ finisher again.
630
631
  **A final report is not proof the member stopped.** **The standing CI facts are
631
632
  in the fix-applier body, not in per-event messages.**
632
633
 
633
- **Once the label is on, take it off before you approve any push.** Write `label-off=<latest finisher attempt>` onto the PR's row first
634
- (`ledger.mjs token <PR number> label-off=<latest finisher attempt>`, which keeps
635
- every token the row already has, see references/ledger.md), then
636
- remove the label (`gh pr edit <pr> --remove-label "<ready-to-merge string>"`, the string `show ready-to-merge` prints), then approve. Then
634
+ **Once the label is on, take it off before you approve any push.** Run
635
+ `fleet-event.mjs label-off <pr>` first: it writes `label-off=<the attempt that settled labelled>`
636
+ onto the PR's row, removes the label and reads the PR's labels back, then approve. Then
637
637
  dispatch a **fresh** finisher against the new head; the first audit does not
638
638
  transfer, since it verified a different tree. See references/finisher.md.
639
639
 
@@ -807,7 +807,7 @@ Match the failure to its row in the table below and run that response; where the
807
807
  | `review-pr` workflow throws or returns no tree | Retry once under the next letter (`review-pr-<pr#>-b`); still failing, report and leave the PR at review-due. Never enqueue the PR as reviewed — the workflow is not a member, so no other row here covers it |
808
808
  | Reviewer, fix-applier or red-check fixer cannot reach green | Report, leave the PR unlabeled, free the slot — the last two settle `failed`; a wake's `NEED derive-recipe` is phase 0's mid-run trigger; a second `failed` fix-applier since review escalates |
809
809
  | Merge bot finds the worktree ahead of the PR head **on the local-rebase fallback** | `worktree-diverged-#<pr>`, PR stays queued. Read the stray commit; push-or-discard is yours, and the maintainer's if the evidence cannot settle it |
810
- | Merge bot finds the head moved after `ready-to-merge` was applied | The label binds to the head's net change, not to one SHA: a proven rebase-carry keeps the label — the bot proceeds and reports `rebase-carry-#<pr>` with the labelled and accepted SHAs, and nothing is dispatched. Any other move is `head-moved-after-label-#<pr>`, PR stays queued, label untouched. Dispatch a **fresh** finisher against the new head — the first audit verified a different tree |
810
+ | Merge bot finds the head moved after `ready-to-merge` was applied | The label binds to the head's net change, not to one SHA: a proven rebase-carry keeps the label — the bot proceeds and reports `rebase-carry-#<pr>` with the labelled and accepted SHAs, and nothing is dispatched. Any other move is `head-moved-after-label-#<pr>`: the bot leaves the label alone, and its report's settle takes it off (`label-off=` on the row, then one PR comment). Dispatch a **fresh** finisher against the new head — the first audit verified a different tree |
811
811
  | Merge bot cannot resolve a rebase safely | Stop that PR, report, continue. On a conflict the bot has already appended `conflict-hold:#<pr>` to the PR's row; the tick prints `DISPATCH fix-pr PR#<pr>` and holds the merge until that fix-applier settles. A PR that conflicts before any bot reaches it is the tick's `CONFLICT PR#<pr>` line, whose hold you record |
812
812
  | Merge bot's gate refuses on its instrument re-check (`instrument-set-changed` or `instruments-unanswerable`, exit 2) | Report `<reason>-#<pr>` with what it printed, PR stays queued, label untouched. Do not re-run the gate |
813
813
  | Merge bot's CI wait reaches its per-PR time bound with the run's `status` still not `completed` | The bot skips that PR and reports `ci-wait-timeout-#<pr>` with the run id and its status. PR stays queued, label untouched |
@@ -121,6 +121,7 @@ and will act on it. Relay everything — reversals too — then dispatch.
121
121
  No flag skips it: a PR `append` refuses is fixed on the ledger, as at close-out.
122
122
  - **The PR's closing references match its ruling and exclude its own suggestion-band record** → `ledger.mjs dispatch` reads the PR's `closingIssuesReferences` from `gh pr view <M>` before it dispatches any finisher, counting only those in the PR's own repository: a reference into another repository closes none of this repository's tickets, whatever its number. When the ruled row says `closed_own_ticket=yes`, each ticket a settled `impl-<N>=PR#<M>` token names must be closed by the body (`Closes #<N>`); when it says `no`, none may be, and no reference may be the PR's own suggestion-band record. A blank verdict is refused until it is set. A refusal names the PR and the ticket. The controller repairs the body itself with `gh pr edit <M> --body-file <file>`, then dispatches the finisher again. A `gh` read that fails refuses the dispatch and writes nothing.
123
123
  - **The PR carries exactly one release label** → `ledger.mjs dispatch` reads the PR's labels from `gh pr view <M>` before it dispatches any finisher, and refuses unless exactly one of `patch`, `minor` and `major` is among them — the count `finisher-label.mjs` makes before it labels. A repository whose label list defines none of the three is not gated. A Ticketless PR with none is not refused: `finisher-label.mjs` adds `patch` to it before its count. Any other PR with none is refused naming the tickets it closes, and any PR with several naming the labels found — the bump, or which label stays, is not picked for the controller. The controller adds or removes the label itself, then dispatches the finisher again. A `gh` read that fails or answers malformed refuses the dispatch, saying the labels could not be read, and writes nothing.
124
+ - **The PR carries no `ready-to-merge`** → the same `gh pr view <M>` read of the PR's labels answers it, and `ledger.mjs dispatch` refuses any finisher while the label is on, writing nothing and naming `fleet-event.mjs label-off <M>`. A finisher runs on an unlabelled PR: the label a merge bot's `head-moved-after-label` refusal left comes off with its report's settle, and the command takes off any other. A repair finisher's PR lacks the label by definition, so it passes.
124
125
 
125
126
  A PR known to conflict cannot merge, and a finisher on it would race the conflict fix-applier rebasing it. That is why the conflict-hold refusal SKILL.md describes exists.
126
127
 
@@ -307,7 +308,10 @@ in it, per `references/isolation.md`, **A reused worktree may lack the runner**.
307
308
  The label is a
308
309
  verdict on the tree the finisher read, and a GitHub label does not follow the
309
310
  branch — on one PR it survived a push and came to sit on a commit nobody had
310
- audited. The token is how the tick tells your
311
+ audited. `fleet-event.mjs label-off <pr>` takes it off: it writes
312
+ `label-off=<attempt>` onto the PR's row, the attempt being the latest finisher
313
+ that settled `labelled`, removes the label and reads the PR's labels back. The
314
+ token is how the tick tells your
311
315
  removal from a finisher that never labelled — a tick run between a removal and
312
316
  its token re-dispatches a finisher into your take-off window. The label goes
313
317
  before the approval because removing the artifact the merge bot gates on is
@@ -316,9 +320,10 @@ observed holding until after an abort message arrived.
316
320
 
317
321
  When a push moves the PR off its labelled head, the merge bot refuses the new
318
322
  head on its own (`run-merge-bot.md`, **The labelled head**), so your take-off
319
- is not the only guard — but its refusal costs a pass and leaves the label
320
- lying, which is yours to clear either way, the same way: `label-off=` first,
321
- then the removal.
323
+ is not the only guard. The bot leaves the label where it is, and its report's
324
+ settle clears it — the same command, then one PR comment — before the fresh
325
+ finisher, which `ledger.mjs dispatch` refuses to start on a PR that still
326
+ carries the label.
322
327
 
323
328
  ## A final report is not proof the member stopped
324
329
 
@@ -94,7 +94,7 @@ A member that dies between spawn and write is invisible — and members die in b
94
94
 
95
95
  ## Label-off and conflict holds
96
96
 
97
- `label-off=<finisher-pr-M[-x]>` is written before you take `ready-to-merge` off PR M on purpose (taking it off before you approve a push, or clearing one left on a moved head), naming that PR's latest finisher attempt: the tick reads a missing label as a finisher's miss only after the last attempt a `label-off=` names, so without it your own removal reads as one.
97
+ `label-off=<finisher-pr-M[-x]>` is written by `fleet-event.mjs label-off M` before it takes `ready-to-merge` off PR M on purpose (before you approve a push, or when a merge bot's `head-moved-after-label` refusal settles), naming the attempt that settled `labelled`: the tick reads a missing label as a finisher's miss only after the last attempt a `label-off=` names, so without it a removal reads as one. A PR whose rows hold no attempt that settled `labelled` (a hand label) gets none.
98
98
 
99
99
  `ci=<run-id>:<attempt>:<conclusion>` is a row token the same way, and so is `conflict-hold:#<pr>` — written by the merge bot itself (`run-merge-bot.md` step 1), or by you off the tick's `CONFLICT` line, naming the row's own PR. It is not an Exclusion: that gates a ticket's claim, this a PR's merge.
100
100
 
@@ -193,6 +193,6 @@ A mismatch on a ticket whose issue is already CLOSED holds nothing: the tick pro
193
193
 
194
194
  - **The reviewer.** **Dispatch the review, never wait on it, and act when its result lands. That is the default path.** `DISPATCH review PR#<M>`: a `task` member named `review-pr-<pr#>`, agent `fleet-review-runner`, its prompt the five args `pr`, `branch`, `worktree`, `testCmd` and `scratch`. Record `review=member:review-pr-<pr#>` on the PR's row before the call. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). Write the `review=` token with `ledger.mjs review <pr> <token>`; `ledger.mjs` refuses a bad grammar. The tick names every PR owed one, oldest first, and each gets one review, once per PR. The tick counts in-flight reviews off the ledger and nowhere else, so a review you launched and never recorded is one it names again. The runner writes the result file and reports its path and `reviewed=` token.
195
195
  A row with `review=` and no `reviewed=` is a review in flight, and the tick counts it as a live review unit unless gh reports its PR MERGED or CLOSED.
196
- - **The fix-applier.** `DISPATCH fix-pr PR#<M>` on a `reviewed=` count that survived or unverified findings, with no fix-applier live: name `fix-pr-<pr#>` (the next suffix if that name is on record), never the PR's implementer; render with `dispatch-prompt.mjs render fix-applier --kind review --member fix-pr-<pr#> …`, then record `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch, the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>` in that brief is the absolute path `scratch-root.mjs` printed. Its rulings are the fix-applier body's (`agents/fleet-fix-applier.agent.md`); you hold none. It holds every finding and you hold none, so there is nothing for you to rank, relay or pre-rule — and a report from a refuter it spawns that surfaces to you is its to retrieve, never yours to scan or pass on. It answers the hold and nothing else: survived or unverified findings of a returned review the row also carries stay unanswered through its settle, so the tick prints `DISPATCH fix-pr PR#<M>` again once it lands, and that one is a review fix-applier, dispatched as above. On a PR carrying `ready-to-merge`, the push moves the head after the label, so the next merge bot refuses it `head-moved-after-label-#<M>`: a fresh finisher, per **Failure handling**.
196
+ - **The fix-applier.** `DISPATCH fix-pr PR#<M>` on a `reviewed=` count that survived or unverified findings, with no fix-applier live: name `fix-pr-<pr#>` (the next suffix if that name is on record), never the PR's implementer; render with `dispatch-prompt.mjs render fix-applier --kind review --member fix-pr-<pr#> …`, then record `ledger.mjs dispatch <pr#> fix-pr-<pr#>` before the call. Its brief carries the PR number, the worktree abs path, the PR's branch, the same `testCmd` you passed the review, and the **path** `<scratch>/pr<pr>/<run>/review.json`, `<run>` off the PR's latest `reviewed=` — never the findings. Every `<scratch>` in that brief is the absolute path `scratch-root.mjs` printed. Its rulings are the fix-applier body's (`agents/fleet-fix-applier.agent.md`); you hold none. It holds every finding and you hold none, so there is nothing for you to rank, relay or pre-rule — and a report from a refuter it spawns that surfaces to you is its to retrieve, never yours to scan or pass on. It answers the hold and nothing else: survived or unverified findings of a returned review the row also carries stay unanswered through its settle, so the tick prints `DISPATCH fix-pr PR#<M>` again once it lands, and that one is a review fix-applier, dispatched as above. On a PR carrying `ready-to-merge`, the push moves the head after the label, so the next merge bot refuses it `head-moved-after-label-#<M>` and its report's settle takes the label off; then a fresh finisher, per **Failure handling**.
197
197
  - **The conflict hold.** `DISPATCH fix-pr PR#<M>` on a conflict hold: the row carries an unresolved `conflict-hold:#<M>`, the merge bot's or one you recorded off the tick's `CONFLICT` line. It is the same slot with a different job, and no review file to hand over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is on record; render with `dispatch-prompt.mjs render fix-applier --kind conflict --member <name> …`; dispatch with the `agent` `ledger.mjs dispatch` printed, in the PR's existing worktree. Read the definition off that output (`fleet-fix-applier` whatever the row's `tier=`), never recall it. Settle `applied:<head>`, or `no-op` if no conflict was left, which lifts the merge hold; a dispatched-but-live one does not, and `failed`/`killed` leave the PR fix-due for a replacement, but a second `failed` since the PR's latest review escalates (`ESCALATE fix-failed`).
198
198
  - **Then dispatch a red-check fixer** — on a `check`-job `failure` bound to the PR's current head that is not **solely** staleness: a `rebase-check` red, or heavy jobs `skipped`, that comes only off the behind-count gets no fixer (the five-condition note in `agents/fleet-fix-applier.agent.md` establishes that). Name `fix-pr-<M>`, or the next free suffix; render with `dispatch-prompt.mjs render fix-applier --kind red-check --member <name> …`, record with `ledger.mjs dispatch <pr#> <name>` before the call, and dispatch with the printed `agent` in the PR's existing worktree. `dispatch` refuses one on a PR where two fix-appliers have settled `failed` since its latest review with none landed after them, whether or not the tick prints `ESCALATE fix-failed` for it — it prints that row only while the PR is owed a fix-applier: handle that refusal as the row. While a review or a review fix-applier on the PR is live or still owes its report — a dispositions mismatch awaiting its retry and a conflict hold awaiting its fix-applier included — the red-check fixer does not fire: their push starts a new run, and a fixer racing them would work on a SHA that is still moving. The common case, the implementer's own first CI firing turning red before any review exists, still dispatches the review against that head as normal. The tick prints no `DISPATCH` for it, so you reconcile it yourself, and it always goes after the review, never before. It is told outright not to watch, poll or wait for CI: your persistent Monitor owns the next run on the pushed head, and the finisher gate — review returned AND fix-applier report sent — applies to this member the same way. Settle it `applied:<head>` once a fix is pushed. Settle it `no-op` only when the red turns out not to be this member's to fix — a flake that passes on rerun, or staleness — with nothing pushed; `no-op` counts as landed, so it never stands for "could not fix". Settle it `failed` when it cannot reach green, which the **Failure handling** row "Reviewer, fix-applier or red-check fixer cannot reach green" covers. Its three dispatch edges are under **The finisher gate**; their rationale is in `references/member-lifecycle.md` (The red-check fixer's three edges).