@feigi/fleet-ctl 3.31.1 → 3.32.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.
@@ -35,7 +35,7 @@ argument-hint: [pr-number]
35
35
 
36
36
  **`skipped` is not `passed`**. When the currency check fails, the heavy jobs report `skipped` — they did **not** execute. A board of `check: success` / currency `failure` / three `skipped` reads as "nearly green" and is in fact *three required suites unverified*. That is not grounds to withhold the label (see below), but if you label under it, say the label rests on the checks that actually ran plus your own verification — never call it "CI green".
37
37
 
38
- **Do NOT rebase to label**, and do not require a zero behind-count. Your green proves the diff is sound *against the base it was tested on* — that is what the label attests, and it does not expire. Requiring currency forces a full CI cycle every time any sibling lands (six wasted cycles in one run) and re-establishes nothing the merge bot will not. Rebase only when pushing a change, or when the bot bounces it back.
38
+ **Do NOT rebase to label**, and do not require a zero behind-count. Your green proves the diff is sound *against the base it was tested on* — that is what the label attests, and it does not expire. Requiring currency forces a full CI cycle every time any sibling lands (six wasted cycles in one run) and re-establishes nothing the merge bot will not. Rebase only when pushing a change, or when the PR is put on a conflict hold — the bot bouncing it back, or the controller recording one off the tick's `CONFLICT` line once GitHub reads the PR CONFLICTING.
39
39
 
40
40
  Three claims, none substituting for another: **run-binding** (this green belongs to this SHA) · **your green** (correct against its base) · **the bot's post-rebase green** (still correct against current `main`). Only the third catches a sibling renaming a symbol you use — a rebase can apply cleanly and still break the build, which is why it is the bot's job and not yours.
41
41
 
@@ -85,7 +85,7 @@ What this gate deliberately does not answer. It does not ask *who* audited — a
85
85
 
86
86
  For each labeled PR clearing the hold rule, lowest first:
87
87
 
88
- **Before step 1, check the ledger for an unresolved conflict hold on this PR.** Read the ticket row that names it — the same lookup step 4 below uses (`ledger.mjs read`). A `conflict-hold:#<pr>` token with no `fix-pr-<n>` settled (`applied:`/`no-op`) *after* it — reading the row left to right, past whatever dispatched after the LATEST hold token — is unresolved: a fix-applier already owns this PR's conflict, from this pass or an earlier one. **Skip it**: do not rebase, do not touch the row, do not report `rebase-fallback-#<pr>` again. Report `conflict-held-#<pr>` and move to the next labeled PR. Only once a fix-applier dispatched after the hold has settled does it clear — proceed through the sequence below as normal from there.
88
+ **Before step 1, check the ledger for an unresolved conflict hold on this PR.** Read the ticket row that names it — the same lookup step 4 below uses (`ledger.mjs read`). A `conflict-hold:#<pr>` token with no `fix-pr-<n>` settled (`applied:`/`no-op`) *after* it — reading the row left to right, past whatever dispatched after the LATEST hold token — is unresolved: a fix-applier already owns this PR's conflict, whether the hold came from this pass, an earlier one, or the controller off the tick's `CONFLICT` line. **Skip it**: do not rebase, do not touch the row, do not report `rebase-fallback-#<pr>` again. Report `conflict-held-#<pr>` and move to the next labeled PR. Only once a fix-applier dispatched after the hold has settled does it clear — proceed through the sequence below as normal from there.
89
89
 
90
90
  1. If the PR is behind `origin/main`, update it **server-side first**: `gh pr update-branch <pr> --rebase`. That's an API call, not a push — no local git command runs, so the force-push classifier denial this step used to hit (`git push --force-with-lease`, judged and intermittently denied per invocation — 2 allowed / 2 denied on byte-identical invocations in one session) never enters. The call is async, so this is two blocks. The fire block reads the head the rebase starts from and makes the call, in seconds:
91
91
 
@@ -194,7 +194,7 @@ For each labeled PR clearing the hold rule, lowest first:
194
194
 
195
195
  **A repo that gates on currency cannot merge from this path — and this one does.** The fallback leaves the remote head behind `origin/main` on purpose, which is the exact condition `rebase-check` fails on: `.github/workflows/ci.yml` checks out `pull_request.head.sha` and exits 1 when the merge-base is not the base tip. It is an expected job, so `ci-state.mjs` reports non-green, step 3's gate never opens, and `mergeStateStatus` cannot read `CLEAN` either. The four checks above are still the honest verification of the *content*, but they do not clear that gate. So here the fallback **ends without merging**: report `rebase-fallback-#<pr>` as blocked and hand it back — choosing between resolving the conflict and turning `allow_update_branch` on is a human's call. Step 4's merge is reachable from this path only where no expected job gates on currency.
196
196
 
197
- **When that hand-back is a conflict, record it on the ledger before you report — your report is gone when you exit, and nothing else durable says the PR is stuck.** It is a conflict when the fallback's local rebase stopped on conflicting paths, whether you then resolved them for verification or aborted: nothing on this path pushes, so the remote head still carries the conflict either way. Not when the server-side rebase failed only because `allow_update_branch` is off and the local rebase applied clean — there is nothing for a fix-applier to resolve. The stopped rebase already named the conflicting paths — read them before you resolve or abort (`git -C <worktree> diff --name-only --diff-filter=U`) — so a later auditor can tell what collided from the row text alone, without re-reading this report. Append the hold to the ticket row that names the PR — the row whose first `PR#` mention is `PR#<pr>`, or the row keyed `#<pr>` when none does — as one rewrite of that row's own text, never a bare line — **unless it already carries one unresolved.** Read the row fresh (below) before writing: if its last `conflict-hold:#<pr>` has no `fix-pr-<n>` settled after it, the row already says what you are about to say — a duplicate write teaches the tick nothing new, and once a fix-applier already working the first hold settles in place before your copy, the tick reads your copy as a fresh hold that settle never cleared. Report `rebase-fallback-#<pr>` and stop there; only write when the row's last hold (if any) has a settled fix-pr after it, or carries no hold at all.
197
+ **When that hand-back is a conflict, record it on the ledger before you report — your report is gone when you exit, and nothing else durable says the PR is stuck: the controller records a hold off the tick's `CONFLICT` line only for a PR no live merge bot owns.** It is a conflict when the fallback's local rebase stopped on conflicting paths, whether you then resolved them for verification or aborted: nothing on this path pushes, so the remote head still carries the conflict either way. Not when the server-side rebase failed only because `allow_update_branch` is off and the local rebase applied clean — there is nothing for a fix-applier to resolve. The stopped rebase already named the conflicting paths — read them before you resolve or abort (`git -C <worktree> diff --name-only --diff-filter=U`) — so a later auditor can tell what collided from the row text alone, without re-reading this report. Append the hold to the ticket row that names the PR — the row whose first `PR#` mention is `PR#<pr>`, or the row keyed `#<pr>` when none does — as one rewrite of that row's own text, never a bare line — **unless it already carries one unresolved.** Read the row fresh (below) before writing: if its last `conflict-hold:#<pr>` has no `fix-pr-<n>` settled after it, the row already says what you are about to say — a duplicate write teaches the tick nothing new, and once a fix-applier already working the first hold settles in place before your copy, the tick reads your copy as a fresh hold that settle never cleared. Report `rebase-fallback-#<pr>` and stop there; only write when the row's last hold (if any) has a settled fix-pr after it, or carries no hold at all.
198
198
 
199
199
  ```bash
200
200
  ~/.fleet/bin/fleet-run ledger.mjs read # the row: `#<key> <text>`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.31.1",
3
+ "version": "3.32.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": {
@@ -25,8 +25,9 @@
25
25
  // it once recorded only that someone was dispatched. Live
26
26
  // implementers, live reviewer units (in-flight `review=` plus
27
27
  // unsettled `fix-pr-`), the merge bot (`## Dispatched`), merge
28
- // holds (`held-behind:#M`, and merge-bot's own
29
- // `conflict-hold:#<pr>`), tier mismatches and the drain marker
28
+ // holds (`held-behind:#M`, and `conflict-hold:#<pr>`, written by
29
+ // the merge bot or by the controller off a `CONFLICT` line),
30
+ // tier mismatches and the drain marker
30
31
  // all come off it. A missing ledger is a fresh run: zero rows.
31
32
  // shortlist `.fleet/shortlist.json`, shortlist.mjs's output, resolved against
32
33
  // the git common dir as ledger.mjs resolves the ledger. Its
@@ -35,8 +36,9 @@
35
36
  // `scanned` is the supply. Missing or unparsable is depth 0 and a
36
37
  // refresh, never a refusal: the depth only ever bounds PULLs
37
38
  // downward.
38
- // gh The open PRs, by label and by whether they close an issue — the
39
- // merge queue, and which PRs are owed a review. Also, for each ticket
39
+ // gh The open PRs, by label, by whether they close an issue and by
40
+ // GitHub's `mergeable` — the merge queue, which PRs are owed a
41
+ // review, and which conflict. Also, for each ticket
40
42
  // holding the implementer row on a tier mismatch, whether its issue
41
43
  // is CLOSED (`gh issue view`): a closed ticket's mismatch
42
44
  // holds nothing. And, for each in-flight `review=` token whose PR
@@ -70,7 +72,16 @@ import { parseMember, parseToken, rowPr, premisesOf } from "./ledger-grammar.mjs
70
72
  // reads what they leave: the slots this tick's own dispatches fill.
71
73
  export function reconcile(s) {
72
74
  const rev = reviewers(s);
73
- return [...mainCheckoutHold(s, [implementers(s, rev.left), ...rev.rows, mergeBot(s)]), ...shortlistRows(s), ...routerRows(s)];
75
+ // The conflict rows only ask the controller to write a record — never to
76
+ // dispatch — so they stand outside the main-checkout hold: the fix-applier a
77
+ // conflict hold leads to obeys the hold through its own role's row.
78
+ return [
79
+ ...mainCheckoutHold(s, [implementers(s, rev.left), ...rev.rows]),
80
+ ...rev.conflictRows,
81
+ ...mainCheckoutHold(s, [mergeBot(s)]),
82
+ ...shortlistRows(s),
83
+ ...routerRows(s),
84
+ ];
74
85
  }
75
86
 
76
87
  // A main checkout changed since the run's baseline — or one the tick
@@ -220,6 +231,24 @@ function reviewers(s) {
220
231
  unlabelledRows.push(row(`ESCALATE unlabelled ${prs(stuck.map((u) => u.pr))}`,
221
232
  { extra: `${names(stuck)} settled labelled since the last label-off; still no ready-to-merge` }));
222
233
  }
234
+ // An open PR the run tracks that GitHub reads CONFLICTING, with no hold on
235
+ // record and nobody working it: the controller writes the hold the merge
236
+ // bot would, and the tick turns it into `DISPATCH fix-pr` from then on.
237
+ // Past two landed conflict fix-appliers it is a treadmill, handed to a human
238
+ // instead — no hold, no fix-applier. Neither row takes a reviewer slot, and
239
+ // neither stands aside for IDLE OK: that row is the one a hold replaces. They
240
+ // are returned beside `rows`, not among them, so a main-checkout hold never
241
+ // turns a record-only line into a HOLD.
242
+ const conflictRows = [];
243
+ if (s.conflicts.length) {
244
+ const record = s.conflicts.map((n) => `~/.fleet/bin/fleet-run ledger.mjs row <key> "<text> · conflict-hold:#${n} (conflict: mergeable=CONFLICTING)" on the row naming PR#${n}`);
245
+ conflictRows.push(row(`CONFLICT ${prs(s.conflicts)}`,
246
+ { acts: true, extra: `GitHub reads CONFLICTING; ~/.fleet/bin/fleet-run ledger.mjs read, then ${record.join("; ")}` }));
247
+ }
248
+ if (s.conflictEscalate.length) {
249
+ conflictRows.push(row(`ESCALATE conflict ${prs(s.conflictEscalate)}`,
250
+ { extra: "GitHub reads CONFLICTING again after two conflict fix-appliers landed; comment on the PR and flag it for a human — no hold, no fix-applier" }));
251
+ }
223
252
  if (!rows.length) {
224
253
  const owed = s.fixDue.length + s.reviewDue.length;
225
254
  if (owed && free <= 0) rows.push(row("AT CAP"));
@@ -227,7 +256,7 @@ function reviewers(s) {
227
256
  else if (!unlabelledRows.length) rows.push(row("IDLE OK"));
228
257
  }
229
258
  rows.push(...unlabelledRows);
230
- return { rows, left: { unreviewed: s.reviewDue.length - reviews.length, free } };
259
+ return { rows, conflictRows, left: { unreviewed: s.reviewDue.length - reviews.length, free } };
231
260
  }
232
261
 
233
262
  function mergeBot(s) {
@@ -346,11 +375,11 @@ export class LedgerError extends Error {}
346
375
  const REVIEW = /^review=(?:wf|member|fallback):[^=\s]+(=failed)?$/;
347
376
  export const REVIEWED = /^reviewed=([0-9a-f]{7,40}):(\d+)\/(\d+)\/(\d+)$/i;
348
377
  const HELD = /^held-behind[:-]#?(\d+)$/;
349
- // Merge-bot's durable record that its local-rebase fallback hit a
350
- // conflict it would not force — written onto the held PR's own row at the
351
- // point run-merge-bot.md says to report and halt, and spelled like
352
- // `held-behind` so the two read alike. Distinct from an Exclusion, which
353
- // gates a ticket's claim; this gates a reviewed PR's merge.
378
+ // The durable record that a PR conflicts — written onto the held PR's own
379
+ // row by the merge bot, when its local-rebase fallback hits a conflict it would
380
+ // not force, or by the controller off this tick's `CONFLICT` line — and
381
+ // spelled like `held-behind` so the two read alike. Distinct from an
382
+ // Exclusion, which gates a ticket's claim; this gates a PR's merge.
354
383
  const CONFLICT_HOLD = /^conflict-hold[:-]#?(\d+)$/;
355
384
  // tier-check.mjs's verdict on an implementer, `tier-ok=<member>:<def>`
356
385
  // or `tier-mismatch=<member>:<def>` — or `tier-unverifiable=<member>:no-transcript`
@@ -582,10 +611,13 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
582
611
  // unverified count. `dispositions`: every dispositions verdict a fix-pr
583
612
  // member of this PR carries, whatever head it answers — the gate picks
584
613
  // by head and retry suffix, never by where a token sits.
614
+ // `workers`: every fix-applier and finisher bound to this PR, and every
615
+ // implementer on a row resolving to it — one still unsettled holds the
616
+ // CONFLICT line off, since it may be pushing to the branch right now.
585
617
  const st = (pr !== null && byPr.get(pr)) || {
586
618
  inFlight: false, reviewedAny: false, survived: 0, unverified: 0, reviewFixed: false,
587
619
  fixMembers: new Set(), fixLanded: new Set(), conflictLanded: new Set(), held: [],
588
- conflictOpen: false, reviewedHead: null, pastPinHalt: false, dispositions: [],
620
+ conflictOpen: false, reviewedHead: null, pastPinHalt: false, dispositions: [], workers: new Set(),
589
621
  };
590
622
  // The finisher-pr token currently deciding `pastPinHalt`, picked by
591
623
  // retry suffix ("" < "b" < "c" …) the same way compute-board.mjs's
@@ -599,6 +631,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
599
631
  const t = parseToken(tok);
600
632
  if (t) {
601
633
  note(t, where, pr);
634
+ if ((t.bound === "pr" && t.number === pr) || t.family === "impl") st.workers.add(t.name);
602
635
  // A settled `failed`/`killed` fix-applier leaves review findings or a
603
636
  // conflict unfixed and no successor dispatched — the PR stays fix-due
604
637
  // for a `-b` replacement. Only a live attempt, or one that actually
@@ -733,7 +766,21 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
733
766
  const state = (n) => byPr.get(n);
734
767
  const heldBehind = (st) => (st?.held ?? []).some((n) => open.has(n));
735
768
  const conflictHeld = (st) => st !== undefined && st.conflictOpen;
736
- const fixRunning = (st) => [...st.fixMembers].some((n) => members.get(n).outcome === null);
769
+ const anyLive = (names) => [...names].some((n) => members.get(n).outcome === null);
770
+ const fixRunning = (st) => anyLive(st.fixMembers);
771
+ // An open PR the ledger tracks that GitHub reads CONFLICTING — no other
772
+ // `mergeable` value: UNKNOWN is read again next tick, and a PR merely behind
773
+ // is the merge bot's server-side update — with no hold on record yet and
774
+ // nobody on it who may be pushing. A queued one is the merge bot's while one
775
+ // is live: its own rebase fallback records the hold. A review in flight is no
776
+ // reason to wait, since fixDue already waits for it to return.
777
+ const working = (st) => anyLive(st.workers);
778
+ const mergeBotLive = live("merge-bot");
779
+ const conflicting = prs.filter((p) => p.mergeable === "CONFLICTING" && byPr.has(p.number)
780
+ && !conflictHeld(state(p.number)) && !working(state(p.number)) && !(isQueued(p) && mergeBotLive > 0));
781
+ // Two conflict fix-appliers landed on it, ever, and it conflicts again: a
782
+ // treadmill.
783
+ const treadmill = (p) => state(p.number).conflictLanded.size >= 2;
737
784
  // The latest review's dispositions verdict is a mismatch no later fix-applier
738
785
  // has answered: the verdict is the highest-suffixed one, and no fix-applier
739
786
  // with a higher suffix has landed. A landed one is awaiting its own check, so
@@ -764,7 +811,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
764
811
  return {
765
812
  implLive: live("impl"),
766
813
  fixLive: live("fix-pr"),
767
- mergeBotLive: live("merge-bot"),
814
+ mergeBotLive,
768
815
  reviewsLive: liveReviews.length,
769
816
  // The in-flight reviews of PRs the open list does not carry: the ones
770
817
  // `finished` could retire, so the caller asks gh about these and no others.
@@ -806,10 +853,15 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
806
853
  new Set(prs.filter((p) => !isQueued(p)).map((p) => p.number))),
807
854
  // Every PR, open or not, on a conflict hold no fix-applier has cleared —
808
855
  // the one reading of a hold: `ledger.mjs dispatch` names a
809
- // fix-applier's definition off this list, so it answers the same per-PR
810
- // fold this tick holds the merge on, split rows and a settle made
811
- // anywhere included, rather than re-deriving it from one row's text.
856
+ // fix-applier's definition and refuses a finisher off this list, so it
857
+ // answers the same per-PR fold this tick holds the merge on, split rows
858
+ // and a settle made anywhere included, rather than re-deriving it from
859
+ // one row's text.
812
860
  conflictHeld: [...byPr.entries()].filter(([, st]) => conflictHeld(st)).map(([n]) => n).sort(asc),
861
+ // Each `conflicting` PR: a hold for the controller to record, or — past
862
+ // two landed conflict fix-appliers — a PR for a human.
863
+ conflicts: conflicting.filter((p) => !treadmill(p)).map((p) => p.number).sort(asc),
864
+ conflictEscalate: conflicting.filter(treadmill).map((p) => p.number).sort(asc),
813
865
  // Every PR, open or not, with a returned review: its latest `reviewed=`
814
866
  // head and counts, the dispositions verdict currently answering that
815
867
  // head, and every fix-applier on the PR still unsettled (`fixLive`) — a
@@ -904,6 +956,9 @@ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
904
956
  // nothing in the result says so, so it refuses — "no silent caps", same rule
905
957
  // candidates.mjs enforces on its own query.
906
958
  const PR_LIMIT = 200;
959
+ // GitHub's `mergeable` values. One outside them is a drifted enum, refused
960
+ // rather than read as not conflicting.
961
+ const MERGEABLE_STATES = ["MERGEABLE", "CONFLICTING", "UNKNOWN"];
907
962
  // Claimed tickets read per stall report. Same "no silent caps" rule as
908
963
  // PR_LIMIT above, resolved the other way: the read below cannot REFUSE at the
909
964
  // cap, because refusing would suppress the one announcement a dead run leaves
@@ -993,7 +1048,7 @@ function openPrs() {
993
1048
  let out;
994
1049
  try {
995
1050
  out = execFileSync("gh", ["pr", "list", "--state", "open", "--limit", String(PR_LIMIT),
996
- "--json", "number,labels,closingIssuesReferences,headRefOid"], { encoding: "utf8", timeout: GH_TIMEOUT_MS });
1051
+ "--json", "number,labels,closingIssuesReferences,headRefOid,mergeable"], { encoding: "utf8", timeout: GH_TIMEOUT_MS });
997
1052
  } catch (e) {
998
1053
  // Never interpolates e.stderr or e.message: execFileSync already forwarded
999
1054
  // the child's stderr to ours, and Node builds e.message out of it, so
@@ -1008,11 +1063,13 @@ function openPrs() {
1008
1063
  }
1009
1064
  // closingIssuesReferences is checked, not defaulted: absent, it would read as
1010
1065
  // an empty list and drop every open PR from review work. headRefOid likewise
1011
- // — absent, a `halted:past-pin` PR would read as moved forever.
1066
+ // — absent, a `halted:past-pin` PR would read as moved forever — and
1067
+ // mergeable: absent or outside GitHub's MergeableState enum, no PR would ever
1068
+ // read CONFLICTING.
1012
1069
  if (!Array.isArray(prs) || prs.some((p) => !p || typeof p.number !== "number"
1013
1070
  || !Array.isArray(p.labels) || !Array.isArray(p.closingIssuesReferences)
1014
- || typeof p.headRefOid !== "string")) {
1015
- die("gh pr list did not return {number,labels,closingIssuesReferences,headRefOid} rows");
1071
+ || typeof p.headRefOid !== "string" || !MERGEABLE_STATES.includes(p.mergeable))) {
1072
+ die("gh pr list did not return {number,labels,closingIssuesReferences,headRefOid,mergeable} rows, mergeable one of MERGEABLE, CONFLICTING, UNKNOWN");
1016
1073
  }
1017
1074
  if (prs.length === PR_LIMIT) {
1018
1075
  die(`exactly ${PR_LIMIT} open PRs — the list is capped and may be truncated. Raise PR_LIMIT; a backlog that silently drops PRs is not a reconcile.`);
@@ -13,7 +13,7 @@
13
13
  //
14
14
  // Rows stay freeform text. Only a token whose name part is a member name is
15
15
  // claimed here; everything else a row carries (`class=routine`, `ports=`,
16
- // `ci=`, `held-behind:#M`, merge-bot's `conflict-hold:#<pr>`, the
16
+ // `ci=`, `held-behind:#M`, `conflict-hold:#<pr>`, the
17
17
  // `review=`/`reviewed=` pair, the `→ PR#M` arrow) is not a member and is left
18
18
  // alone.
19
19
 
@@ -1771,15 +1771,22 @@ function runDispatch() {
1771
1771
  const held = member.family === "fix-pr" && tickFold("definition").conflictHeld.includes(member.number);
1772
1772
 
1773
1773
  // A finisher labels its PR `ready-to-merge`, so it is recorded only once
1774
- // the PR's current dispositions verdict is ok — read off the tick's own
1775
- // per-PR fold, the same latest `reviewed=` head the tick reads — and no
1776
- // fix-applier on the PR is still live. A PR whose latest review counts no
1777
- // survived and no unverified finding had nothing for a fix-applier to rule
1778
- // on, and one never reviewed has no review file: neither is gated on a
1779
- // verdict. Refused here, before anything is written, so the check cannot
1780
- // be skipped by forgetting to run it.
1774
+ // the PR sits on no conflict hold a fix-applier has yet to clear — a PR
1775
+ // known to conflict cannot merge, and a finisher would race the fix-applier
1776
+ // rebasing it — and once its current dispositions verdict is ok — both read
1777
+ // off the tick's own per-PR fold, the verdict at the same latest `reviewed=`
1778
+ // head the tick reads — and no fix-applier on the PR is still live. A PR
1779
+ // whose latest review counts no survived and no unverified finding had
1780
+ // nothing for a fix-applier to rule on, and one never reviewed has no
1781
+ // review file: neither is gated on a verdict. Refused here, before anything
1782
+ // is written, so the check cannot be skipped by forgetting to run it.
1781
1783
  if (member.family === "finisher-pr") {
1782
- const review = tickFold("dispositions verdict").reviewed.find((r) => r.pr === member.number);
1784
+ const fold = tickFold("conflict hold and dispositions verdict");
1785
+ if (fold.conflictHeld.includes(member.number)) {
1786
+ die(`${member.name}: PR #${member.number} is on a conflict hold no fix-applier has cleared — dispatch fix-pr-${member.number}[-<x>] `
1787
+ + `and let it settle applied:/no-op, then dispatch the finisher again — not dispatching ${member.name}`);
1788
+ }
1789
+ const review = fold.reviewed.find((r) => r.pr === member.number);
1783
1790
  const refusal = dispositionsRefusal(member.number, review);
1784
1791
  if (refusal !== null) die(`${member.name}: ${refusal} — not dispatching ${member.name}`);
1785
1792
  }
@@ -23,9 +23,9 @@
23
23
  // 3. Real tests must be shown to have executed, by at least one of:
24
24
  // - the count proof: `--count-line` is a literal the run's own output
25
25
  // must contain (text off the runner's summary line, read off a
26
- // previous run), carrying `--test-count`, a positive integer, as its
27
- // one number. `tests 0` is a failed proof however honestly the runner
28
- // reports it.
26
+ // previous run), carrying `--test-count`, a positive integer no larger
27
+ // than Number.MAX_SAFE_INTEGER, as its one number. `tests 0` is a
28
+ // failed proof however honestly the runner reports it.
29
29
  // - the mutation proof: the unmutated run must be green; `--mutate` is a
30
30
  // shell command that must change a tracked file (the deliberate
31
31
  // failing mutation of one test, or of the code one test covers) — run
@@ -145,6 +145,11 @@ function parseArgs(argv) {
145
145
  if ("--test-count" in a && !isDigits(a["--test-count"])) {
146
146
  throw cannot(`--test-count must be a whole number, got '${a["--test-count"]}'`);
147
147
  }
148
+ // Past Number.MAX_SAFE_INTEGER the cache can store a count other than the
149
+ // one claimed, or none at all, while the line's exact match still holds.
150
+ if ("--test-count" in a && !Number.isSafeInteger(Number(a["--test-count"]))) {
151
+ throw cannot(`--test-count must be at most ${Number.MAX_SAFE_INTEGER}, got '${a["--test-count"]}'`);
152
+ }
148
153
  if (("--mutate" in a) !== ("--mutation" in a)) throw cannot("--mutate and --mutation go together");
149
154
  return {
150
155
  repo,
@@ -1543,7 +1543,7 @@ for a token on a ticket's line — never a hand edit.
1543
1543
  | Finisher report (failed / killed) | `ledger.mjs settle finisher-pr-<M>=failed` for a finisher that crashed or gave up, `=killed` for one that was killed; no label, and the tick prints no dispatch for it. The cockpit flags the PR `finisher:failed` / `finisher:killed` at severity 4 and you resolve it by hand (**Resolving a finisher that died**, below) |
1544
1544
  | Label seen (persistent Monitor) | nothing to record |
1545
1545
  | CI run terminal | `ci=<run-id>:<attempt>:<conclusion>` on the row; then the finisher gate (below) |
1546
- | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n>=done`; `reap.sh --apply`. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — that token is the bot's, never `reap.sh`'s.) |
1546
+ | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n>=done`; `reap.sh --apply`. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — a token the bot wrote in this pass, never one `reap.sh` writes.) |
1547
1547
  | Drain | `ledger.mjs drain "<reason>"`; release the claims (below); `settle impl-<N>=released` |
1548
1548
  | Heartbeat | nothing to record |
1549
1549
 
@@ -1708,7 +1708,7 @@ depth** guard table applied in code. Act on each line as it reads:
1708
1708
  - `SUGGEST /triage, hold idle` — nothing is admissible after the refresh.
1709
1709
  Suggest, never run (**Queue depth**).
1710
1710
  - `DISPATCH fix-pr PR#<M> …` — a fix-applier per PR, for a review's survived or unverified findings,
1711
- a dispositions mismatch no retry has answered, or a merge bot's `conflict-hold:#<M>` (**Reviewers**). Printed
1711
+ a dispositions mismatch no retry has answered, or a `conflict-hold:#<M>` — the merge bot's, or one you recorded off a `CONFLICT` line (**Reviewers**). Printed
1712
1712
  ahead of reviews on purpose: finishing what is started beats starting more.
1713
1713
  - `DISPATCH review PR#<M> …` — a review per PR, oldest first, off your turn
1714
1714
  (**Reviewers**).
@@ -1727,6 +1727,25 @@ depth** guard table applied in code. Act on each line as it reads:
1727
1727
  third. Not actionable; the maintainer's, through the cockpit's `unlabelled`
1728
1728
  flag and the comment the repair finisher's report left (**Finisher report**
1729
1729
  row above).
1730
+ - `CONFLICT PR#<M> …` — GitHub reads PR M `mergeable=CONFLICTING`, the ledger
1731
+ tracks it, no conflict hold stands on it, no fix-applier, finisher or
1732
+ implementer on it is live, and, if it carries `ready-to-merge`, no merge bot
1733
+ is live: a queued PR is the bot's while one runs, and its own fallback records
1734
+ the hold. Record the hold the merge bot's way (`run-merge-bot.md` step 1): run
1735
+ `ledger.mjs read`, then rewrite the row naming PR M with `ledger.mjs row <key>
1736
+ "<text> · conflict-hold:#<M> (conflict: mergeable=CONFLICTING)"` — `<text>` is
1737
+ everything after the key, verbatim. The row's detail prints that step for
1738
+ each PR it names. Then run the tick: the hold reads as `DISPATCH fix-pr
1739
+ PR#<M>`, a conflict fix-applier (**A `DISPATCH fix-pr PR#<M>` on a conflict
1740
+ hold**), and that row obeys every hold. A review in flight does not stop the
1741
+ line: `fix-due` waits for the review to return. It prints under a
1742
+ main-checkout hold and a drain too, since it writes a record and dispatches
1743
+ nothing.
1744
+ - `ESCALATE conflict PR#<M> …` — PR M reads CONFLICTING again after two
1745
+ conflict fix-appliers landed on it: a rebase treadmill. Comment on the PR
1746
+ and flag it for a human; write no hold and dispatch no fix-applier. Not
1747
+ actionable; it repeats while the PR reads CONFLICTING and clears once it
1748
+ stops, closes or merges.
1730
1749
  - `HOLD (…)` — the row is held and says why: draining, a tier mismatch, an
1731
1750
  unchecked tier, a saturated review side, `--max-reviews` in flight, or every
1732
1751
  queued merge candidate held behind a lower PR or on a conflict hold no
@@ -2248,8 +2267,9 @@ holds every finding and you hold none, so there is nothing for you to rank,
2248
2267
  relay or pre-rule — and a report from a refuter it spawns that surfaces to you
2249
2268
  is its to retrieve, never yours to scan or pass on.
2250
2269
 
2251
- **A `DISPATCH fix-pr PR#<M>` on a conflict hold** — the row carries the merge
2252
- bot's unresolved `conflict-hold:#<M>` (`run-merge-bot.md` step 1's fallback) —
2270
+ **A `DISPATCH fix-pr PR#<M>` on a conflict hold** — the row carries an
2271
+ unresolved `conflict-hold:#<M>`, the merge bot's (`run-merge-bot.md` step 1's
2272
+ fallback) or one you recorded off the tick's `CONFLICT` line —
2253
2273
  is the same slot with a different job, and no review file to hand
2254
2274
  over. Name it `fix-pr-<M>`, or the next suffix (`-b`, `-c` …) when that name is
2255
2275
  already on record — `dispatch` refuses a reused one — and dispatch it with the
@@ -2267,9 +2287,10 @@ what lifts the tick's merge hold; a dispatched-but-live one does not, and
2267
2287
  hold and nothing else: survived or unverified findings of a returned review the row also carries
2268
2288
  stay unanswered through its settle, so the tick prints `DISPATCH fix-pr
2269
2289
  PR#<M>` again once it lands, and that one — `dispatch` now prints `null` —
2270
- is a review fix-applier, dispatched as above. The push moves the
2271
- head after `ready-to-merge`, so the next merge bot refuses it
2272
- `head-moved-after-label-#<M>`: a fresh finisher, per **Failure handling**.
2290
+ is a review fix-applier, dispatched as above. On a PR carrying
2291
+ `ready-to-merge`, the push moves the head after the label, so the next merge
2292
+ bot refuses it `head-moved-after-label-#<M>`: a fresh finisher, per **Failure
2293
+ handling**.
2273
2294
 
2274
2295
  **A `DISPATCH fix-pr PR#<M>` on a dispositions mismatch** — the PR's row carries
2275
2296
  `dispositions-mismatch=<member>:<head>` for its latest review, and no later
@@ -2670,6 +2691,13 @@ the earlier round's verdict while the fix-applier answering the new round is
2670
2691
  still working; once its check has run, its verdict, from the higher suffix, is
2671
2692
  the current one.
2672
2693
 
2694
+ **It refuses a finisher, too, while the PR sits on a conflict hold no
2695
+ fix-applier has cleared** — the same per-PR fold the tick prints `DISPATCH
2696
+ fix-pr` off, ahead of the dispositions verdict. A PR known to conflict cannot
2697
+ merge, and a finisher on it would race the conflict fix-applier rebasing it.
2698
+ Dispatch that fix-applier, let it settle `applied:`/`no-op`, then dispatch the
2699
+ finisher again.
2700
+
2673
2701
  **An unanswered question from the member is an outbox item, and it blocks
2674
2702
  dispatch with the same weight as a ruling you have already made.** It does not
2675
2703
  feel like one — you have decided nothing yet, so the outbox reads empty — but a
@@ -3714,7 +3742,7 @@ Plan it as a PR the run's own merge queue lands, never as an edit-and-continue.
3714
3742
  | 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 |
3715
3743
  | Merge bot's gate finds the merge would remove lines `main` gained after the PR's work began (`main-gain-removed:<path>`, exit 1) | Relay `main-gain-removed:<path>-#<pr>` to a human with the hit list and the acknowledgement keys the bot printed. PR stays queued, label untouched, nothing written to the ledger, and no member is dispatched to restore the lines — the removal may be deliberate. It clears when the PR stops removing them or its body carries `main-gain-removal: <path> <key> - <why>` for each hit |
3716
3744
  | Merge bot's gate cannot answer the main-gain check (`main-gain-unanswerable`, exit 2) | Report `main-gain-unanswerable-#<pr>` with what it printed, PR stays queued, label untouched |
3717
- | 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 |
3745
+ | 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 |
3718
3746
  | 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 |
3719
3747
  | Member silent or truncated | Send to ping or resume — same unit of work; see the state machine below |
3720
3748
  | Member idle with work outstanding | Read the PR first, *then* ping. Idle ≠ done |
@@ -3851,9 +3879,9 @@ when the result lands. A row with `review=` and no `reviewed=` is a review in
3851
3879
  flight, and the tick counts it against the reviewer cap unless gh reports its PR
3852
3880
  MERGED or CLOSED. `ci=<run-id>:<attempt>:<conclusion>`
3853
3881
  and `held-behind:#<lower>` are row tokens the same way (Phase 3), and so is
3854
- `conflict-hold:#<pr>` — the one row token the merge bot writes itself, naming
3855
- the row's own PR (`run-merge-bot.md` step 1). It is not an Exclusion: that
3856
- gates a ticket's claim, this a reviewed PR's merge. `label-off=<finisher-pr-M[-x]>`
3882
+ `conflict-hold:#<pr>` — written by the merge bot itself (`run-merge-bot.md`
3883
+ step 1), or by you off the tick's `CONFLICT` line, naming the row's own PR. It
3884
+ is not an Exclusion: that gates a ticket's claim, this a PR's merge. `label-off=<finisher-pr-M[-x]>`
3857
3885
  is yours, written before you take `ready-to-merge` off PR M on purpose (taking
3858
3886
  it off before you approve a push, or clearing one left on a moved head),
3859
3887
  naming that PR's latest finisher attempt: the tick reads a missing label as a