@feigi/fleet-ctl 3.158.10 → 3.158.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.158.10",
3
+ "version": "3.158.12",
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": {
@@ -34,7 +34,7 @@
34
34
  // argv[1].
35
35
  import { assessBeat, isStalled, isReported, stallReport, NO_OWNER } from "./fleet-state.mjs";
36
36
  import { parseToken, rowPr, premisesOf, HALT_CAUSES, REVIEW, CELL, POLICY_CELL, parseRoutedEntry, tierValues, cellValues, isRulePath } from "./ledger-grammar.mjs";
37
- import { latestFinisherAttempts, foldLedger, pastPinDue } from "./fleet-tick.mjs";
37
+ import { latestFinisherAttempts, foldLedger, reviewOwed as reviewOwedState } from "./fleet-tick.mjs";
38
38
  import { computeCellEvidence } from "./compute-cell-evidence.mjs";
39
39
  import { admissibleRow, lastSegment } from "./pull-attribution.mjs";
40
40
  import { dispatchModel } from "./member-outcomes.mjs";
@@ -101,7 +101,9 @@ import { implementerCell, modelsEqual } from "./tier-roles.mjs";
101
101
  // `review=…=failed` is a dead review and the PR is owed one again, as run-team
102
102
  // SKILL.md defines review-due and as fleet-tick.mjs's `reviewedAny` reads the
103
103
  // token: the PR is owed none while any row naming it carries ANY live
104
- // `review=` — wherever it sits, not only as the last one — or any `reviewed=`.
104
+ // `review=` — wherever it sits, not only as the last one — or any `reviewed=`;
105
+ // nor is it owed one while a fix-applier or finisher on it is live
106
+ // (fleet-tick.mjs's `reviewHeld`, which the board reads through `reviewOwed`).
105
107
  // A `review=` token outside the grammar is read as live by foldLedger's
106
108
  // lenient mode, which the board reads the PR's state through; the strict tick
107
109
  // refuses that ledger outright instead, and the board flags the row.
@@ -708,13 +710,7 @@ export function computeBoard(inputs) {
708
710
  const latestFinishers = new Map(latestFinisherAttempts({ rows, dispatched: ledger.dispatched || [] }, unqueued).map((u) => [u.pr, u.outcome]));
709
711
  // Review state is the PR's, read off the tick's own fold — a card's
710
712
  // PR is its row's latest attempt, whichever row carries that PR's tokens.
711
- const liveMember = (names) => [...names].some((n) => fold.members.get(n).outcome === null);
712
- const reviewOwed = (prNum) => {
713
- const st = fold.byPr.get(prNum);
714
- if (st === undefined) return true;
715
- if (st.inFlight || liveMember(st.fixMembers) || liveMember(st.finishers)) return false;
716
- return !st.reviewedAny || pastPinDue(st, prByNum.get(prNum)?.headRefOid);
717
- };
713
+ const reviewOwed = (prNum) => reviewOwedState(fold.byPr.get(prNum), fold.members, prByNum.get(prNum)?.headRefOid);
718
714
  const rowIssues = new Set();
719
715
  const tickets = [];
720
716
 
@@ -775,7 +771,7 @@ export function computeBoard(inputs) {
775
771
  // a returned review whose finisher halted `past-pin` against a head it
776
772
  // never read: owed again until the head catches up to what `reviewed=`
777
773
  // recorded, the same rule fleet-tick.mjs's reviewDue reads off headRefOid
778
- // (pastPinDue). A PR absent from the open list (closed, not yet MERGED)
774
+ // (`reviewOwed`). A PR absent from the open list (closed, not yet MERGED)
779
775
  // reads as an unmatched head, never as answered — silence is not review.
780
776
  // Counted once per PR, off the per-PR fold, however many cards name it.
781
777
  const reviewBacklog = new Set(tickets.filter((t) => t.column === "REVIEW" && reviewOwed(t.pr)).map((t) => t.pr)).size;
@@ -859,7 +859,18 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
859
859
  // landing pushed nothing, and a member settled `failed` or `killed`, or
860
860
  // still live, never lands: none of them moves it.
861
861
  // `ledger.mjs settle --from-report` checks a fix-applier's `no-op`
862
- // against it.
862
+ // against it. A review never overlaps a fix-applier or finisher on its PR
863
+ // (`reviewHeld` below: the tick's reviewDue reads it through `reviewOwed`
864
+ // and fixDue waits on reviewDue, and the ledger's `review` and `dispatch`
865
+ // refuse its two halves), so a `reviewed=` never lands
866
+ // after a fix-applier's push it did not read; the position rule above
867
+ // assumes that, and assumes no row rewrite moves a settled fix-pr token
868
+ // across a `reviewed=`. A push that no fleet member is recorded as making
869
+ // and that no review read — a hand push, or an implementer pushing after
870
+ // its PR opened — still leaves `fleetHead` below the branch, so the next
871
+ // `no-op` settle exits 3.
872
+ // `openLaunch`: the open launch's `review=…` token — a review of the PR is
873
+ // in flight while it is non-null — null when none.
863
874
  // `pastPinHalt`: the latest
864
875
  // finisher since that review settled `halted:past-pin` — any
865
876
  // later finisher attempt, live or settled, replaces it, and a later
@@ -871,7 +882,7 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
871
882
  // implementer on a row resolving to it — one still unsettled holds the
872
883
  // CONFLICT line off, since it may be pushing to the branch right now.
873
884
  const st = (pr !== null && byPr.get(pr)) || {
874
- inFlight: false, reviewedAny: false, survived: 0, unverified: 0, reviewFixed: false,
885
+ openLaunch: null, reviewedAny: false, survived: 0, unverified: 0, reviewFixed: false,
875
886
  fixMembers: new Set(), fixLanded: new Set(), conflictLanded: new Set(), fixFailed: new Set(),
876
887
  conflictOpen: false, reviewedHead: null, reviewedRun: null, fleetHead: null, fleetRetry: null, pastPinHalt: false, dispositions: [], workers: new Set(),
877
888
  finishers: new Set(), parked: [],
@@ -953,19 +964,19 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
953
964
  const m = REVIEW.exec(tok);
954
965
  if (!m && lenient) {
955
966
  malformed.add(i);
956
- st.inFlight = true;
967
+ st.openLaunch = tok;
957
968
  st.reviewedAny = true;
958
969
  continue;
959
970
  }
960
971
  if (!m) throw new LedgerError(`${where}: '${tok}' is not review=wf:<runId> | member:review-pr-<n>, optionally =failed`);
961
- st.inFlight = !m.groups.failed;
972
+ st.openLaunch = m.groups.failed ? null : tok;
962
973
  if (!m.groups.failed) st.reviewedAny = true;
963
974
  } else if (tok.startsWith("reviewed=")) {
964
975
  const m = REVIEWED.exec(tok);
965
976
  if (!m && lenient) {
966
977
  malformed.add(i);
967
978
  latestFinisher = null;
968
- Object.assign(st, { inFlight: false, reviewedAny: true, reviewFixed: false, pastPinHalt: false, fixFailed: new Set() });
979
+ Object.assign(st, { openLaunch: null, reviewedAny: true, reviewFixed: false, pastPinHalt: false, fixFailed: new Set() });
969
980
  continue;
970
981
  }
971
982
  if (!m && REVIEWED_RUNLESS.test(tok)) {
@@ -976,7 +987,7 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
976
987
  latestFinisher = null;
977
988
  const head = m[1].toLowerCase();
978
989
  Object.assign(st, {
979
- inFlight: false, reviewedAny: true, survived: Number(m[2]), unverified: Number(m[4]), reviewFixed: false,
990
+ openLaunch: null, reviewedAny: true, survived: Number(m[2]), unverified: Number(m[4]), reviewFixed: false,
980
991
  reviewedHead: head, reviewedRun: m[5], fleetHead: head, fleetRetry: null, pastPinHalt: false, fixFailed: new Set(),
981
992
  });
982
993
  } else if (labelOffMember(tok) === null) {
@@ -1027,17 +1038,48 @@ export function foldLedger({ rows, dispatched }, open, { lenient = false } = {})
1027
1038
  }
1028
1039
  if (pr !== null) byPr.set(pr, st);
1029
1040
  }
1041
+ // A PR-bound fix-applier or finisher is on its PR off `## Dispatched` as
1042
+ // well as off its own PR's row: one whose row token a whole-line `row`
1043
+ // rewrite dropped is still on the PR, live until something settles it.
1044
+ for (const e of dispatched) {
1045
+ const t = parseToken(e);
1046
+ const st = t && !t.error && (t.family === "fix-pr" || t.family === "finisher-pr") ? byPr.get(t.number) : undefined;
1047
+ if (st === undefined) continue;
1048
+ (t.family === "fix-pr" ? st.fixMembers : st.finishers).add(t.name);
1049
+ }
1030
1050
  return { members, byPr, verdicts, claimed, excluded, malformed };
1031
1051
  }
1032
1052
 
1033
1053
  // A PR whose latest finisher halted `past-pin` against a returned review owes
1034
1054
  // a fresh one while its head is still past what that review read: a
1035
1055
  // `reviewed=` head (7-40 hex) prefix-matching gh's full headRefOid is the head
1036
- // that review read, and there is nothing more to review. `st` is a `byPr`
1037
- // state, `undefined` for a PR no row names.
1038
- export const pastPinDue = (st, head) => st !== undefined && st.pastPinHalt && !st.inFlight && st.reviewedHead !== null
1056
+ // that review read, and there is nothing more to review. `st` is a defined
1057
+ // `byPr` state with no review in flight: `reviewOwed` asks only once
1058
+ // `reviewHeld` has ruled one out.
1059
+ const pastPinDue = (st, head) => st.pastPinHalt && st.reviewedHead !== null
1039
1060
  && !String(head).toLowerCase().startsWith(st.reviewedHead);
1040
1061
 
1062
+ // The fix-appliers and finishers on a PR still live, as names: every one
1063
+ // `st` (a `byPr` state) holds that `members` — the fold's merged records —
1064
+ // does not read as settled. A member settled anywhere is settled; a PR-bound
1065
+ // one counts only off `## Dispatched` and its own PR's row, as the fold reads it.
1066
+ export const liveFixers = (st, members) => [...st.fixMembers, ...st.finishers].filter((n) => members.get(n).outcome === null);
1067
+
1068
+ // Whether a PR is held out of review: a review of it is in flight, or a
1069
+ // fix-applier or finisher on it is live. `st` is a `byPr` state, `undefined`
1070
+ // for a PR no row names, which nothing holds. The tick's `reviewDue` and the
1071
+ // board's backlog read this one gate through `reviewOwed`, and `ledger.mjs
1072
+ // review` and `dispatch` refuse the two halves of it.
1073
+ export const reviewHeld = (st, members) => st !== undefined && (st.openLaunch !== null || liveFixers(st, members).length > 0);
1074
+
1075
+ // Whether a PR is owed a review: not held out of review (`reviewHeld`), and
1076
+ // with no review on record, or a returned one its finisher halted `past-pin`
1077
+ // against while `head` is still past what it read (`pastPinDue`). `st` is a
1078
+ // `byPr` state, `undefined` for a PR no row names, which is owed one. The
1079
+ // tick's `reviewDue` and the board's backlog read this one rule.
1080
+ export const reviewOwed = (st, members, head) => st === undefined
1081
+ || (!reviewHeld(st, members) && (!st.reviewedAny || pastPinDue(st, head)));
1082
+
1041
1083
  // The states a PR-state probe answers: anything else is no answer.
1042
1084
  const PR_STATES = ["OPEN", "MERGED", "CLOSED"];
1043
1085
 
@@ -1151,8 +1193,8 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1151
1193
  // `mergeable` value: UNKNOWN is read again next tick, and a PR merely behind
1152
1194
  // is the merge bot's server-side update — with no hold on record yet and
1153
1195
  // nobody on it who may be pushing. A queued one is the merge bot's while one
1154
- // is live: its own rebase fallback records the hold. A review in flight is no
1155
- // reason to wait, since fixDue already waits for it to return.
1196
+ // is live: its own rebase fallback records the hold. A review in flight or
1197
+ // owed is no reason to wait, since fixDue already waits for it to return.
1156
1198
  const working = (st) => anyLive(st.workers);
1157
1199
  const mergeBotLive = live("merge-bot");
1158
1200
  const conflicting = prs.filter((p) => p.mergeable === "CONFLICTING" && byPr.has(p.number)
@@ -1190,11 +1232,27 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1190
1232
  // hold and leaves findings it never read due for a review one.
1191
1233
  const fixOwed = ([n, st]) => open.has(n)
1192
1234
  && (((st.survived > 0 || st.unverified > 0) && !st.reviewFixed) || conflictHeld(st) || mismatchDue(st))
1193
- && !fixRunning(st) && !st.inFlight;
1235
+ && !fixRunning(st) && st.openLaunch === null;
1194
1236
  // The PRs owed a fix-applier, split below by `fixEscalated` into `fixDue`
1195
1237
  // and `fixEscalate`, as `conflicting` is into `conflicts` and
1196
1238
  // `conflictEscalate`.
1197
1239
  const owed = [...byPr.entries()].filter(fixOwed);
1240
+ // Open, not signed off, owned (openPrs() reads that off the PR's author
1241
+ // and draft flag; a PR closing no issue is as due as one closing one),
1242
+ // and owed a review (`reviewOwed`): not held out of review (`reviewHeld`:
1243
+ // a review in flight, or a fix-applier or finisher on it live), with no
1244
+ // returned review on record — or a returned review its finisher halted
1245
+ // `past-pin` against: the
1246
+ // head carries commits no reviewer read, so it is owed a review again
1247
+ // until one is running or has returned. A head that moved past
1248
+ // `reviewed=` with no such halt — a fix-applier's push — stays not due:
1249
+ // finisher duty 2 verifies what it applied. A PR owed a review is owed no
1250
+ // fix-applier until it returns: the review reads the head before any fix
1251
+ // lands, and a fix-applier's push is never re-reviewed.
1252
+ const reviewDue = prs
1253
+ .filter((p) => !isQueued(p) && p.owned && reviewOwed(state(p.number), members, p.headRefOid))
1254
+ .map((p) => p.number).sort(asc);
1255
+ const owedReview = new Set(reviewDue);
1198
1256
  // A `review=` token with no `reviewed=` after it reads as in flight, and the
1199
1257
  // ledger alone never says otherwise: a review whose own `reviewed=` write
1200
1258
  // never landed stays in flight after its PR merges, counting as a review unit
@@ -1202,7 +1260,7 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1202
1260
  // finished, and a finished PR has no review running against it. A PR on the
1203
1261
  // open list is open whatever the probe says, and none is the default, so a
1204
1262
  // PR nobody has asked about keeps its review live.
1205
- const reviewing = [...byPr.entries()].filter(([, st]) => st.inFlight);
1263
+ const reviewing = [...byPr.entries()].filter(([, st]) => st.openLaunch !== null);
1206
1264
  const finished = (n) => prStates.get(n) === "MERGED" || prStates.get(n) === "CLOSED";
1207
1265
  const liveReviews = reviewing.filter(([n]) => open.has(n) || !finished(n));
1208
1266
  const unsettled = all.filter((m) => m.outcome === null).map((m) => m.name);
@@ -1237,8 +1295,9 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1237
1295
  reviewsOffList: reviewing.filter(([n]) => !open.has(n)).map(([n]) => n).sort(asc),
1238
1296
  // Each PR a fix-applier is owed on (`fixOwed`), unless two fix-appliers
1239
1297
  // have settled `failed` on it since its latest review with none landed
1240
- // after them: that PR is `fixEscalate`'s instead.
1241
- fixDue: owed.filter(([, st]) => !fixEscalated(st)).map(([n]) => n).sort(asc),
1298
+ // after them — that PR is `fixEscalate`'s instead — or it is itself owed
1299
+ // a review (`reviewDue`), which comes first.
1300
+ fixDue: owed.filter(([n, st]) => !fixEscalated(st) && !owedReview.has(n)).map(([n]) => n).sort(asc),
1242
1301
  // Each PR a fix-applier would be owed on but for two `failed` since its
1243
1302
  // latest review, `{pr, members}` ascending, `members` the counted ones:
1244
1303
  // the reviewers row escalates it, dispatching nothing.
@@ -1250,18 +1309,8 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1250
1309
  // with no open list, as `conflictHeld` does.
1251
1310
  fixFailed: [...byPr.entries()].filter(([, st]) => fixEscalated(st))
1252
1311
  .map(([n, st]) => ({ pr: n, members: fixFailures(st) })).sort((a, b) => a.pr - b.pr),
1253
- // Open, not signed off, owned (openPrs() reads that off the PR's author
1254
- // and draft flag; a PR closing no issue is as due as one closing one),
1255
- // with no live or returned review on record —
1256
- // or a returned review its finisher halted `past-pin` against: the
1257
- // head carries commits no reviewer read, so it is owed a review again
1258
- // until one is running or has returned. A head that moved past
1259
- // `reviewed=` with no such halt — a fix-applier's push — stays not due:
1260
- // finisher duty 2 verifies what it applied.
1261
- reviewDue: prs
1262
- .filter((p) => !isQueued(p) && p.owned
1263
- && (!state(p.number)?.reviewedAny || pastPinDue(state(p.number), p.headRefOid)))
1264
- .map((p) => p.number).sort(asc),
1312
+ // The PRs owed a review (`reviewDue` above).
1313
+ reviewDue,
1265
1314
  mergeQueue: queued.length,
1266
1315
  // A conflict hold lifts only once a fix-applier after it has SETTLED
1267
1316
  // `applied:`/`no-op` — never on dispatch alone.
@@ -75,7 +75,7 @@ import { makeDie, isFlagLike, hasEqualsForm, isDigits, writeAll } from "./arg.mj
75
75
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
76
76
  import { readReceipt } from "./phase0-receipt.mjs";
77
77
  import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, settledOnLedger, retiredOnLedger, retiredName, readRetired, agentDefinition, expectedDefinition, CELL, POLICY_CELL, tierValues, cellValues, decidingCell, rowPr, rowNums, rowWriteRefusal, isReviewToken, addedReviewToken, isDispositionsWord, gateVerdictWriter, gateVerdictRefusal, settledMemberRefusal, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, HALT_CAUSES, ROWS, DISPATCHED, ROUTED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, BRIEFS, briefsArchiveName, memberRole, parseDispatchedEntry, dispatchedEntry, parseRouting, parseRoutedEntry, routedEntry, headerRe, escapeText, ledgerSection, nextReviewerName, isOmpSessionDirName } from "./ledger-grammar.mjs";
78
- import { deriveRun, LedgerError, labelOffMember, CONFLICT_HOLD, PARKED } from "./fleet-tick.mjs";
78
+ import { deriveRun, foldLedger, liveFixers, LedgerError, labelOffMember, CONFLICT_HOLD, PARKED } from "./fleet-tick.mjs";
79
79
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
80
80
  import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
81
81
  import { attemptLock, releaseLockFile, reapPathOf } from "./pid-lock.mjs";
@@ -2387,6 +2387,19 @@ function queueSnapshot() {
2387
2387
  return [...new Set(prs)].sort((a, b) => a - b);
2388
2388
  }
2389
2389
 
2390
+ // The tick's per-PR fold of `rows` and this ledger's `## Dispatched` — `byPr`
2391
+ // states and the merged `members` — the one reading the tick's review gate
2392
+ // (`reviewHeld`) and its fix gate read. A ledger the fold refuses dies as
2393
+ // `refusal(message)` says, exit 2.
2394
+ function prFold(rows, refusal) {
2395
+ try {
2396
+ return foldLedger({ rows, dispatched: data.dispatched }, new Set());
2397
+ } catch (e) {
2398
+ if (!(e instanceof LedgerError)) throw e;
2399
+ die(refusal(e.message));
2400
+ }
2401
+ }
2402
+
2390
2403
  async function runDispatch() {
2391
2404
  const usage = "usage: ledger.mjs dispatch <ticket|pr> <member>, or dispatch merge-bot";
2392
2405
  if (rest.length === 0 || rest.length > 2) die(usage);
@@ -2507,8 +2520,17 @@ async function runDispatch() {
2507
2520
  // `failed` since its latest review with none landed after them — read off
2508
2521
  // the tick's own fold, the one its `ESCALATE fix-failed` row reads, so a
2509
2522
  // hand-dispatched one is refused like the tick's. A new review restarts the
2510
- // count.
2523
+ // count. Before that, no fix-applier on a PR a review of which is in
2524
+ // flight, read off the same fold (`openLaunch`): a review comes before any
2525
+ // fix, and the tick holds `fixDue` back the same way.
2511
2526
  if (member.family === "fix-pr") {
2527
+ const st = prFold(data.rows, (why) => `${why} — fleet-tick.mjs refuses this ledger, so ${member.name}'s review state cannot be read off it; fix it with \`ledger.mjs row\` before dispatching`)
2528
+ .byPr.get(member.number);
2529
+ if (st !== undefined && st.openLaunch !== null) {
2530
+ die(`${member.name}: a review of PR #${member.number} is in flight (${st.openLaunch}) — a fix-applier never overlaps a review of its PR; `
2531
+ + `wait for its result (\`ledger.mjs review ${member.number} --result <path>\`), or settle its launch failed: `
2532
+ + `\`ledger.mjs review ${member.number} ${st.openLaunch}=failed\` — not dispatching ${member.name}`);
2533
+ }
2512
2534
  const failed = tickFold("fix-applier failure count").fixFailed.find((f) => f.pr === member.number);
2513
2535
  if (failed !== undefined) {
2514
2536
  die(`${member.name}: ${failed.members.join(", ")} settled failed on PR #${member.number} since its latest review — the fleet dispatches no third fix-applier; `
@@ -3279,7 +3301,9 @@ function reviewResultToken(pr, path, scratchArg) {
3279
3301
  // A result token the PR's rows already carry is not written again: with no
3280
3302
  // launch in the call, exit 0 with nothing written. The whole ledger before
3281
3303
  // and after is judged by rowWriteRefusal() under the lock, and a refusal
3282
- // writes nothing. The receipt names the derived token as `reviewed`, with
3304
+ // writes nothing. A write that leaves a new launch open is refused while a
3305
+ // fix-applier or finisher on the PR is live, read off the tick's fold:
3306
+ // a review never overlaps either. The receipt names the derived token as `reviewed`, with
3283
3307
  // `written` saying whether this call put it on the row, and its `next` is the
3284
3308
  // runner name the PR's next launch takes as the ledger stands after the
3285
3309
  // write, null with every letter taken.
@@ -3342,6 +3366,20 @@ function runReview() {
3342
3366
  const after = created ? [...data.rows, line] : data.rows.with(i, line);
3343
3367
  const refusal = rowWriteRefusal(data.rows, after, oldLine, line, retired);
3344
3368
  if (refusal !== null) die(`review #${prNum}: ${refusal}`);
3369
+ // A launch this write leaves open starts a review that reads the head
3370
+ // before a live fix-applier or finisher on the PR pushes, and its
3371
+ // `reviewed=` would then sit after that push's token. Settling a launch
3372
+ // `=failed`, recording a result, or a launch with its own result in the same
3373
+ // call leave none open, so none is refused.
3374
+ if (tokens.some((tok) => tok.startsWith("review=") && !tok.endsWith("=failed"))) {
3375
+ const fold = prFold(after, (why) => `review #${prNum}: ${why} — fleet-tick.mjs refuses this ledger, so the members live on PR #${prNum} cannot be read off it; fix it with \`ledger.mjs row\`; nothing written`);
3376
+ const st = fold.byPr.get(prNum);
3377
+ const live = st?.openLaunch ? liveFixers(st, fold.members) : [];
3378
+ if (live.length > 0) {
3379
+ die(`review #${prNum}: ${live.join(", ")} is still live on PR #${prNum} — a review never overlaps a fix-applier or finisher on its PR; `
3380
+ + `\`ledger.mjs settle ${live[0]} <outcome>\` or wait for its report before launching the review; nothing written`);
3381
+ }
3382
+ }
3345
3383
  data.rows = after;
3346
3384
  save(data);
3347
3385
  const key = rowKey(line);
@@ -223,11 +223,10 @@ Record each ruling with `ledger.mjs ruled <pr> <decision>`, one line with its re
223
223
 
224
224
  ### Dispatching the members a wake names
225
225
 
226
- - **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, with `ledger.mjs review <pr> <token>`: the tick counts in-flight reviews off the ledger and nowhere else. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). The runner writes the result file and reports its path.
227
- 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.
226
+ - **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, with `ledger.mjs review <pr> <token>`, which refuses a launch while a fix-applier or finisher on the PR is live: the tick counts a row with `review=` and no `reviewed=` as a live review unit, unless gh reports its PR MERGED or CLOSED. `scratch` is the scratch root itself, never a `pr<N>` partition (`references/reviewers.md`). The runner writes the result file and reports its path.
228
227
  - **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, and a refuter report that surfaces to you is its to retrieve, never yours to scan or pass on. On a PR carrying `ready-to-merge`, its push moves the head after the label: a fresh finisher, per **Failure handling**.
229
- - **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. 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; a second `failed` since its latest review escalates. It answers the hold and nothing else: review findings the row also carries get a review `DISPATCH fix-pr PR#<M>` once it lands.
230
- - **Then dispatch a red-check fixer** — on a `check`-job `failure` bound to the PR's current head that is not **solely** staleness (the five-condition note in `agents/fleet-fix-applier.agent.md`). 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 `fix-failed` PR, row or not; act as on the row. Never 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; a red before any review still gets its review first. The tick prints no `DISPATCH` for it: reconcile it yourself, always after the review. The finisher gate applies to it as to a fix-applier. Settle it `applied:<head>` once a fix is pushed; `no-op` only when the red is not its to fix — a flake that passes on rerun, or staleness — with nothing pushed, never for "could not fix"; `failed` when it cannot reach green (**Failure handling**).
228
+ - **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. Same slot, 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. 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; a second `failed` since its latest review escalates. It answers the hold and nothing else: review findings the row also carries get a review `DISPATCH fix-pr PR#<M>` once it lands. It waits for a review the PR is owed or has running; `ledger.mjs dispatch` refuses one while a review is in flight.
229
+ - **Then dispatch a red-check fixer** — on a `check`-job `failure` bound to the PR's current head that is not **solely** staleness (the five-condition note in `agents/fleet-fix-applier.agent.md`). 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 `fix-failed` PR, row or not; act as on the row. Never while a review is owed or running on the PR (`ledger.mjs dispatch` refuses one in flight) or a review fix-applier on it is live or owes its report — a dispositions mismatch awaiting its retry and a conflict hold awaiting its fix-applier included. The tick prints no `DISPATCH` for it: reconcile it yourself, always after the review. The finisher gate applies to it as to a fix-applier. Settle it `applied:<head>` once a fix is pushed; `no-op` only when the red is not its to fix — a flake that passes on rerun, or staleness — with nothing pushed, never for "could not fix"; `failed` when it cannot reach green (**Failure handling**).
231
230
  - **The merge bot.** Named `merge-bot-<n>`; `ledger.mjs dispatch merge-bot` numbers it. Render `--member merge-bot-<n> --n <n> --scratch <scratch>`. Dispatch with the printed agent, omit `model`, and dispatch on the first `ready-to-merge` label without waiting for the finisher report.
232
231
  - **The finisher.** Its render and receives are in `references/finisher.md`.
233
232
 
@@ -748,7 +747,7 @@ decides the rest — two resolve automatically, every other one escalates:
748
747
  | Cause | Resolution |
749
748
  |---|---|
750
749
  | `live-editor` | **Automatic.** Ask the live member **by name** for its report, wait for it, then dispatch `finisher-pr-<M>-b` at the current head. If the head moved in the meantime, resolve it as `past-pin` instead. |
751
- | `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's launch as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner the next free letter `review` names, and its result reaches a fresh finisher through the same gate. |
750
+ | `past-pin` | **Automatic, through the tick: re-review.** The head carries commits no reviewer read. The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record its launch as any review's (`ledger.mjs review <M>`, the next free letter `review` names); its result reaches a fresh finisher through the same gate. |
752
751
  | `rebase` | **Escalate** — comment and flag, nothing more. The report's `evidence.replay` reads `pure` only when `git range-diff origin/main <pin> HEAD` pairs every pinned commit with an unchanged one; `changed` (a commit dropped, edited or added, or a stale `origin/main`) or `unknown` means read `evidence.rangeDiff` before acting, and `evidence.remote.state` says whether that head is on the PR. No automatic rule until a live halt shows the case recurring. |
753
752
  | `stray` | **Escalate** — comment and flag; nothing pushes it automatically. Read `evidence.cherry`, `.content` and `.remote`. Push or discard is yours, or the maintainer's if they cannot settle it. A pushed stray is unreviewed: `ledger.mjs review <M>` first. |
754
753
  | `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
@@ -805,7 +804,7 @@ Match the failure to its row in the table below and run that response; where the
805
804
  | SHA not on expected branch | Flag, do not enqueue, report |
806
805
  | Implementer bails before implementing | Act by the report's `bailCause` as the **Relabel causes** table says, then refill (**What a wake owes beyond its call**) |
807
806
  | Implementer blocked or ambiguous *mid-implementation* | Free the slot. A `blocked` report settles on the **Implementer report** wake, no label moved; with no report, `ledger.mjs settle impl-<N> blocked`, its Ending still `hollow`. Leave `in-progress`, report — the ticket is not In flight and waits for a human; its `NEED derive-recipe` is phase 0's mid-run trigger |
808
- | `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 |
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 |
809
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 |
810
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 |
811
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 |
@@ -28,8 +28,11 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
28
28
  - `DISPATCH fix-pr PR#<M> …` — a fix-applier per PR, for a review's survived or unverified findings,
29
29
  a dispositions mismatch no retry has answered, or a `conflict-hold:#<M>` — the merge bot's, or one you recorded off a `CONFLICT` line (**The fix-applier**). Printed
30
30
  ahead of reviews on purpose: finishing what is started beats starting more.
31
+ It never names a PR that is owed a review or has one running, and
32
+ `ledger.mjs dispatch` refuses one while a review is in flight.
31
33
  - `DISPATCH review PR#<M> …` — a review per PR, oldest first, off your turn
32
- (**The reviewer**).
34
+ (**The reviewer**). It never names a PR with a live fix-applier or
35
+ finisher, and `ledger.mjs review` refuses a launch while one is live.
33
36
  - `DISPATCH merge-bot` — the next `merge-bot-<n>` (**The merge bot**). The `<scratch>` its brief takes is the absolute `scratch-root.mjs` output, and the bot writes only under `<scratch>/pr<N>/merge-bot-<n>/`.
34
37
  - `DISPATCH finisher PR#<M> …` — a finisher settled `labelled`, yet the open
35
38
  list shows PR M without `ready-to-merge`, and no `label-off=` (references/ledger.md)
@@ -59,7 +62,7 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
59
62
  every hold. A review in flight does not stop the
60
63
  line: `fix-due` waits for the review to return. It prints under a
61
64
  main-checkout hold and a drain too, since it writes a record and dispatches
62
- nothing.
65
+ nothing. `fix-due` waits the same for a review the PR is owed.
63
66
  - `ESCALATE conflict PR#<M> …` — PR M reads CONFLICTING again after two
64
67
  conflict fix-appliers landed on it: a rebase treadmill. Comment on the PR
65
68
  and flag it for a human; write no hold and dispatch no fix-applier. Not