@feigi/fleet-ctl 3.24.8 → 3.24.9

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.
@@ -3,18 +3,18 @@
3
3
  // refill was wired as an EDGE — "a member finished → refill its slot". That
4
4
  // edge dies the moment live implementers reach 0, because 0 implementers emit
5
5
  // no completion event, and "free capacity + a non-empty pool" is a LEVEL
6
- // condition an edge-triggered loop cannot observe once it stops changing. #3:
6
+ // condition an edge-triggered loop cannot observe once it stops changing. Measured:
7
7
  // implementers sat at 0/target with pool 1 and ~57 `ready-for-agent` in supply
8
8
  // until a human asked why nothing was being implemented. No error, no warning.
9
9
  //
10
10
  // So compute the deficit instead of remembering it. Every wake ends in one
11
11
  // invocation (spec 2026-09-24 § 6: record, tick, act, beat), and each prints
12
- // actual/target and a named ACTION per role — `PULL #412 #415`, `DISPATCH
13
- // fix-pr PR#346`, `DISPATCH review PR#350`, `DISPATCH merge-bot`, `HOLD (…)`,
12
+ // actual/target and a named ACTION per role — `PULL #<n> #<n>`, `DISPATCH
13
+ // fix-pr PR#<pr>`, `DISPATCH review PR#<pr>`, `DISPATCH merge-bot`, `HOLD (…)`,
14
14
  // `REFRESHED shortlist: …` — with run-team's guards applied in code rather than
15
15
  // recalled from its table. You cannot forget what a script prints at you.
16
16
  //
17
- // WHERE THE NUMBERS COME FROM — nobody states them (#1803, ADR 0012 Decision 5):
17
+ // WHERE THE NUMBERS COME FROM — nobody states them:
18
18
  //
19
19
  // ledger `.fleet/ledger.md`, read through `ledger.mjs read` so the ledger
20
20
  // keeps one parser, and its member tokens through
@@ -38,13 +38,13 @@
38
38
  // gh The open PRs, by label and by whether they close an issue — the
39
39
  // merge queue, and which PRs are owed a review. Also, for each ticket
40
40
  // holding the implementer row on a tier mismatch, whether its issue
41
- // is CLOSED (`gh issue view`, #2485): a closed ticket's mismatch
41
+ // is CLOSED (`gh issue view`): a closed ticket's mismatch
42
42
  // holds nothing. And, for each in-flight `review=` token whose PR
43
43
  // the open list does not carry, whether that PR is MERGED or
44
44
  // CLOSED (`gh pr view`): a review cannot be running against a
45
45
  // finished PR, so its dangling token holds no reviewer slot.
46
46
  // main The main checkout against the run-start baseline
47
- // `.fleet/main-checkout.sha`, through main-checkout.mjs (#2210).
47
+ // `.fleet/main-checkout.sha`, through main-checkout.mjs.
48
48
  // Anything but `clean` — dirty, unknown, no baseline — prints one
49
49
  // MAIN-CHECKOUT-* line and holds every dispatching row until the
50
50
  // maintainer clears it; it never refuses the tick.
@@ -52,12 +52,12 @@
52
52
  // --guard's verdict on the implementer cells. Printed as the
53
53
  // `router` row and never acted on here: a missing or unreadable
54
54
  // file reads DEFAULT-ONLY, the way the router (not in the tree
55
- // yet; ADR 0016) is to read it. pr-cost.mjs writes the main
55
+ // yet) is to read it. pr-cost.mjs writes the main
56
56
  // workspace's file by default, the one read here.
57
57
  //
58
58
  // The pure half below is `reconcile()` over the counts `deriveRun()` reads off
59
59
  // the ledger; main() does the I/O. Split so the guard table and the reading are
60
- // both unit-testable without a network — fleet-tick.test.mjs.
60
+ // both unit-testable without a network.
61
61
 
62
62
  import { parseMember, parseToken } from "./ledger-grammar.mjs";
63
63
 
@@ -73,7 +73,7 @@ export function reconcile(s) {
73
73
  return [...mainCheckoutHold(s, [implementers(s, rev.left), ...rev.rows, mergeBot(s)]), ...shortlistRows(s), ...routerRows(s)];
74
74
  }
75
75
 
76
- // #2210: a main checkout changed since the run's baseline — or one the tick
76
+ // A main checkout changed since the run's baseline — or one the tick
77
77
  // could not compare — holds every DISPATCHING row: one HOLD per role,
78
78
  // keeping its counts, in place of whatever it would have dispatched. Placed
79
79
  // over the computed rows rather than inside each role, so no role's own
@@ -84,7 +84,7 @@ export function reconcile(s) {
84
84
  // Phase 0 step, so that one asks it to act.
85
85
  const MAIN_CHECKOUT_HOLD = { dirty: "main checkout dirty", absent: "main checkout no baseline" };
86
86
  // The reason a main-checkout answer holds dispatch on, or null for `clean` —
87
- // the one wording the HOLD rows and the folded line (#2307) both carry.
87
+ // the one wording the HOLD rows and the folded line both carry.
88
88
  function mainCheckoutHoldReason(mainCheckout) {
89
89
  const state = mainCheckout?.state ?? "unknown";
90
90
  if (state === "clean") return null;
@@ -103,13 +103,13 @@ function mainCheckoutHold(s, rows) {
103
103
  }
104
104
 
105
105
  // `acts` is on the row, set where the ACTION is chosen: the heartbeat backs off
106
- // on "nothing to act on" and never on "output unchanged" (ADR 0008 §6), and the
106
+ // on "nothing to act on" and never on "output unchanged", and the
107
107
  // branch that picks the ACTION is the one place that knows which it is.
108
108
  const mkRow = (role, actual, target, detail) => (action, { acts = false, extra = "" } = {}) => ({
109
109
  role, actual, target, action, acts, detail: extra ? `${detail} — ${extra}` : detail,
110
110
  });
111
111
 
112
- // The clearing step a tier hold names in its detail (#2255). The tick reads no
112
+ // The clearing step a tier hold names in its detail. The tick reads no
113
113
  // transcript and so does not know the session directory: `<session>` stays a
114
114
  // placeholder the controller fills in, as `<file>` does — one batch file, one
115
115
  // entry per held member (SKILL.md's phase-2 tier check).
@@ -148,16 +148,16 @@ function implementers(s, left) {
148
148
  if (s.draining !== null) return row("HOLD (draining)");
149
149
  // Held until a replacement at the right tier is dispatched (§ 6 §6). The
150
150
  // controller can fix this unattended, so the row asks it to — and names the
151
- // replacement in its detail (#2255), since the step lives otherwise only in
151
+ // replacement in its detail, since the step lives otherwise only in
152
152
  // SKILL.md prose, which is what a compaction loses.
153
153
  if (s.tierMismatch.length) {
154
154
  return row(`HOLD (tier mismatch ${s.tierMismatch.join(" ")})`, { acts: true, extra: replaceStep(s.tierMismatch, s.implNames) });
155
155
  }
156
156
  // Held until tier-check.mjs has run on the newest implementer and written
157
- // its verdict to the ledger (#1398) — a Pull on top of an unchecked
157
+ // its verdict to the ledger — a Pull on top of an unchecked
158
158
  // dispatch repeats whatever it got wrong. Running the check is the
159
159
  // controller's own step, so it is asked to act, with the command in the
160
- // detail (#2255).
160
+ // detail.
161
161
  if (s.tierUnchecked.length) {
162
162
  return row(`HOLD (tier unchecked ${s.tierUnchecked.join(" ")})`, { acts: true, extra: tierCheckStep(s.tierUnchecked) });
163
163
  }
@@ -170,7 +170,7 @@ function implementers(s, left) {
170
170
  // still owed its review after this tick's dispatches AND no reviewer slot is
171
171
  // left for it. A deep backlog with free slots is a reviewer-row DISPATCH on
172
172
  // this same tick, not a reason to idle an implementer; the old
173
- // `backlog >= 2` gate held there and starved implementers (#590's harm).
173
+ // `backlog >= 2` gate held there and starved implementers.
174
174
  // The merge queue never gates this row: a deep ready-to-merge queue adds no
175
175
  // rebases per PR.
176
176
  if (left.unreviewed >= 1 && left.free <= 0) return row("HOLD (review side saturated)");
@@ -184,7 +184,7 @@ function implementers(s, left) {
184
184
  return row("SUGGEST /triage, hold idle");
185
185
  }
186
186
 
187
- // Reviewer units (#1773 §3): an in-flight review = 1, each fix-applier = 1.
187
+ // Reviewer units: an in-flight review = 1, each fix-applier = 1.
188
188
  // Named in priority order — fix-appliers first, then reviews, oldest first —
189
189
  // because finishing what is started beats starting more. Reviews are also
190
190
  // bounded by `--max-reviews`, left at its default (the reviewer cap) since
@@ -204,7 +204,7 @@ function reviewers(s) {
204
204
  const rows = [];
205
205
  if (fixes.length) rows.push(row(`DISPATCH fix-pr ${prs(fixes)}`, { acts: true }));
206
206
  if (reviews.length) rows.push(row(`DISPATCH review ${prs(reviews)}`, { acts: true }));
207
- // #2331: a finisher settled `labelled` on a PR the open list shows without
207
+ // A finisher settled `labelled` on a PR the open list shows without
208
208
  // `ready-to-merge`. One such attempt since the controller's last deliberate
209
209
  // removal gets one fresh finisher; a second one escalates, never a third
210
210
  // dispatch. Finishers take no reviewer slot, so neither waits on the cap.
@@ -237,7 +237,7 @@ function mergeBot(s) {
237
237
  if (s.mergeQueue === 0) return row("IDLE OK");
238
238
  // `ready-to-merge` is the author's sign-off and nothing more. A bot
239
239
  // dispatched against a queue whose candidates are all held — behind a lower
240
- // open PR, or on a conflict merge-bot already refused to force (#2064) —
240
+ // open PR, or on a conflict merge-bot already refused to force —
241
241
  // spends a whole member re-deriving a verdict already recorded.
242
242
  if (s.mergeQueue - s.mergeHeld <= 0) {
243
243
  const why = s.mergeConflictHeld ? "behind a lower PR or on a merge conflict no fix-pr has cleared" : "behind a lower PR";
@@ -250,9 +250,9 @@ function mergeBot(s) {
250
250
  // is actionable — supply arrived. One that changed nothing is not: every idle
251
251
  // heartbeat tick refreshes while the shortlist is short of the cap, and an
252
252
  // unconditionally actionable REFRESHED would pin the beat at its base interval
253
- // on exactly the quiet night ADR 0008 backs off on. A failed refresh IS
253
+ // on exactly the quiet night the heartbeat backs off on. A failed refresh IS
254
254
  // actionable: a blind implementer row backing off tick after identical tick is
255
- // #3's stall exactly.
255
+ // the drained-queue stall this tick exists to end, exactly.
256
256
  function shortlistRows(s) {
257
257
  const r = s.refresh;
258
258
  if (r === null) return [];
@@ -324,8 +324,8 @@ export function formatLines(rows) {
324
324
  }
325
325
 
326
326
  // Does this tick ask the controller for anything? Identity decides whether to
327
- // FOLD the output; only this decides whether to back off (ADR 0008 §6). A tick
328
- // printing `PULL #412` every five minutes because the controller has not acted
327
+ // FOLD the output; only this decides whether to back off. A tick
328
+ // printing `PULL #<n>` every five minutes because the controller has not acted
329
329
  // is byte-identical each time, and backing off there would stretch the
330
330
  // interval while work sat unclaimed.
331
331
  export function actionable(rows) {
@@ -354,19 +354,19 @@ export const PR_MENTION = /\bPR\s*#(\d+)\b/;
354
354
  // shortlist.mjs's own spelling of an Exclusion row and its premises.
355
355
  const EXCLUDED_ROW = /^#[0-9]+[ \t]+excluded(?=[ \t]|$)([\s\S]*)$/;
356
356
  const PREMISE = /\bbehind-(pr|issue):#?([^\s,;]+)/g;
357
- // #1773 §7: `review=wf:<runId>` | `review=member:review-pr-<n>` |
357
+ // `review=wf:<runId>` | `review=member:review-pr-<n>` |
358
358
  // `review=fallback:review-pr-<n>[-b]`, settled dead as `…=failed`; the result
359
359
  // is `reviewed=<head>:<survived>/<refuted>/<unverified>`.
360
360
  const REVIEW = /^review=(?:wf|member|fallback):[^=\s]+(=failed)?$/;
361
361
  export const REVIEWED = /^reviewed=([0-9a-f]{7,40}):(\d+)\/(\d+)\/(\d+)$/i;
362
362
  const HELD = /^held-behind[:-]#?(\d+)$/;
363
- // #2064: merge-bot's durable record that its local-rebase fallback hit a
363
+ // Merge-bot's durable record that its local-rebase fallback hit a
364
364
  // conflict it would not force — written onto the held PR's own row at the
365
365
  // point run-merge-bot.md says to report and halt, and spelled like
366
366
  // `held-behind` so the two read alike. Distinct from an Exclusion, which
367
367
  // gates a ticket's claim; this gates a reviewed PR's merge.
368
368
  const CONFLICT_HOLD = /^conflict-hold[:-]#?(\d+)$/;
369
- // #1398: tier-check.mjs's verdict on an implementer, `tier-ok=<member>:<def>`
369
+ // tier-check.mjs's verdict on an implementer, `tier-ok=<member>:<def>`
370
370
  // or `tier-mismatch=<member>:<def>` — or `tier-unverifiable=<member>:no-transcript`
371
371
  // for a settled member whose transcript was never written.
372
372
  const TIER_VERDICT = /^tier-(ok|mismatch|unverifiable)=([^:\s]+):\S+$/;
@@ -413,7 +413,7 @@ export function currentDispositions(tokens, head) {
413
413
  return best === null ? null : { verdict: best.verdict, member: best.member.name };
414
414
  }
415
415
 
416
- // #2331: `label-off=<finisher-pr-M[-x]>` — written by the controller BEFORE it
416
+ // `label-off=<finisher-pr-M[-x]>` — written by the controller BEFORE it
417
417
  // takes `ready-to-merge` off PR M on purpose (before approving a push; clearing
418
418
  // a label left on a moved head), naming the latest finisher attempt. A missing
419
419
  // label is a finisher's miss only when no such removal accounts for it.
@@ -440,10 +440,10 @@ export function rowNums(text) {
440
440
  // it, so the label shape stays the caller's (gh's `{name}` here, plain names in
441
441
  // compute-board.mjs). A PR's attempts are its `finisher-pr-M` tokens in
442
442
  // `## Dispatched` and on PR M's own rows; a copy on another PR's row is a
443
- // stray (#2329) that neither makes nor masks a miss. Settled anywhere among
443
+ // stray that neither makes nor masks a miss. Settled anywhere among
444
444
  // those is settled. The STRETCH is the attempts whose retry suffix sorts after
445
445
  // the highest one a `label-off=` names — suffix order ("" < "b" < …), never
446
- // row position (#2083). `attempts` is the stretch in suffix order and `outcome`
446
+ // row position. `attempts` is the stretch in suffix order and `outcome`
447
447
  // the outcome of its latest attempt (null while that one is live); a PR whose
448
448
  // stretch is empty is left out.
449
449
  //
@@ -488,7 +488,7 @@ export function latestFinisherAttempts({ rows, dispatched }, unqueued) {
488
488
  return out.sort((a, b) => a.pr - b.pr);
489
489
  }
490
490
 
491
- // #2331: PRs whose latest finisher attempt settled `labelled` while the open
491
+ // PRs whose latest finisher attempt settled `labelled` while the open
492
492
  // list shows no `ready-to-merge` on them. `labelled` lists every attempt in the
493
493
  // stretch that settled so, the count the tick splits one repair from an
494
494
  // escalation on.
@@ -503,7 +503,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
503
503
  // One entry per member name across `## Dispatched` and every row. A member
504
504
  // settled ANYWHERE is settled: `settle` is the only writer of an outcome, and
505
505
  // a bare copy beside it is what a whole-line `row` rewrite leaves behind.
506
- // The one narrowing (#2391): a PR-bound member (`fix-pr-M`, `finisher-pr-M`)
506
+ // The one narrowing: a PR-bound member (`fix-pr-M`, `finisher-pr-M`)
507
507
  // speaks for PR #M alone, so its outcome counts off `## Dispatched` or off
508
508
  // PR #M's own row, never off another PR's — `dispatch` and `settle` write it
509
509
  // onto PR #M's row only, so a settled copy elsewhere is a hand-written stray
@@ -528,7 +528,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
528
528
  const claimed = new Set();
529
529
  const excluded = [];
530
530
  const byPr = new Map();
531
- // tier-check.mjs's verdict tokens (#1398), read off whichever row carries
531
+ // tier-check.mjs's verdict tokens, read off whichever row carries
532
532
  // them: `tier-ok=<member>:<definition>` on a pass, `tier-mismatch=<member>:…`
533
533
  // for a member found mismatched after it had already settled some other way
534
534
  // (a live one is settled `tier-mismatch` instead). Neither parses as a member
@@ -544,7 +544,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
544
544
  // rewrite put back, wherever that rewrite chose. Its landing is read off
545
545
  // the in-place copy (below), and off a bare one only when no row carries
546
546
  // one — settled in `## Dispatched` alone. Only a copy on its own PR's row
547
- // counts, as in the fold (#2329): a settled stray on another PR's row must
547
+ // counts, as in the fold: a settled stray on another PR's row must
548
548
  // not keep the owner's bare copy from landing. A malformed token is skipped
549
549
  // here and refused by the fold below, in row order, as before.
550
550
  const settledInRow = new Set();
@@ -558,8 +558,8 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
558
558
  for (const text of rows) {
559
559
  const { keyNum, pr } = rowNums(text);
560
560
  const where = `row '${text}'`;
561
- // One state per PR, shared by every row that resolves to it (#2283): a
562
- // ticket row settled `impl-658=PR#724` sorts above PR 724's own `#724` row
561
+ // One state per PR, shared by every row that resolves to it: a
562
+ // ticket row settled `impl-<n>=PR#<pr>` sorts above PR <pr>'s own `#<pr>` row
563
563
  // whenever both exist, and either may carry that PR's tokens — ledger.mjs's
564
564
  // memberRowIndex() writes a PR-bound member onto the first row mentioning
565
565
  // its PR and onto `#<pr>` only when none does — so the second row continues
@@ -570,15 +570,15 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
570
570
  // `reviewFixed`: a REVIEW fix-applier landed after the latest
571
571
  // `reviewed=` — one read while no hold stood unresolved. The one read
572
572
  // while a hold did is the conflict fix-applier `ledger.mjs dispatch` named
573
- // a `fleet-implementer-<cell>` (#2299): it rebases and never sees the review file,
574
- // so it clears the hold and answers no survivor (#2328). Each fix-applier
573
+ // a `fleet-implementer-<cell>`: it rebases and never sees the review file,
574
+ // so it clears the hold and answers no survivor. Each fix-applier
575
575
  // does one of those jobs once, so its landing folds once per PR
576
576
  // (`fixLanded`), however many copies of its token the rows carry.
577
577
  // `fixMembers`: every fix-applier on this PR, wherever its token sits —
578
578
  // one still unsettled anywhere holds the PR off fixDue, since `dispatch`
579
579
  // refuses a second live one on the PR.
580
580
  // `reviewedHead`: the latest `reviewed=<head>`. `pastPinHalt`: the latest
581
- // finisher since that review settled `halted:past-pin` (#2083) — any
581
+ // finisher since that review settled `halted:past-pin` — any
582
582
  // later finisher attempt, live or settled, replaces it, and a later
583
583
  // returned review answers it. `unverified`: the latest `reviewed=`'s
584
584
  // unverified count. `dispositions`: every dispositions verdict a fix-pr
@@ -591,7 +591,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
591
591
  };
592
592
  // The finisher-pr token currently deciding `pastPinHalt`, picked by
593
593
  // retry suffix ("" < "b" < "c" …) the same way compute-board.mjs's
594
- // laterAttempt does — never by row-text position (#2083 correction). A
594
+ // laterAttempt does — never by row-text position. A
595
595
  // `-b` retry can sit before an older `halted:past-pin` token after a row
596
596
  // rewrite, and text order must not read the stale one as the live
597
597
  // finisher's replacement. Reset at each `reviewed=`, since `pastPinHalt`
@@ -628,8 +628,8 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
628
628
  // recorded into `members` by the `note` above, so its outcome is this
629
629
  // token's own unless `## Dispatched` or an earlier row already settled
630
630
  // it — never a reason to fall back to the row's own copy. A
631
- // `fix-pr-<M>` speaks for PR #M alone, as a `finisher-pr` does below
632
- // (#2329): `dispatch` and `settle` write it onto PR #M's row only, so a
631
+ // `fix-pr-<M>` speaks for PR #M alone, as a `finisher-pr` does below:
632
+ // `dispatch` and `settle` write it onto PR #M's row only, so a
633
633
  // copy on another PR's row is a hand-written stray this PR reads as
634
634
  // absent, and which lends PR #M's own copies no outcome.
635
635
  if (t.family === "fix-pr" && t.number === pr) {
@@ -679,7 +679,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
679
679
  }
680
680
  // A fresh hold is unresolved whatever settled before it, the way a
681
681
  // fresh `reviewed=` resets `reviewFixed` above. A redundant re-hold
682
- // (merge-bot retrying a PR it has already held, #2064) changes
682
+ // (merge-bot retrying a PR it has already held) changes
683
683
  // nothing a live fix-applier holds off: liveness is not read off
684
684
  // token order.
685
685
  st.conflictOpen = true;
@@ -693,7 +693,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
693
693
  const ex = EXCLUDED_ROW.exec(text);
694
694
  if (ex && keyNum !== null) {
695
695
  const premises = [...ex[1].matchAll(PREMISE)].map(([, kind, target]) => ({ kind, target }));
696
- // ADR 0013 §48: an `excluded` row claims its ticket only while its
696
+ // An `excluded` row claims its ticket only while its
697
697
  // premise still holds. Lifted here only when EVERY premise is a
698
698
  // verifiable, now-closed `behind-pr:#M` — the same rule a
699
699
  // `held-behind` merge hold uses — since a mixed or `behind-issue`
@@ -721,7 +721,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
721
721
  // say whether one exists; a settled member whose transcript was never
722
722
  // written gets `tier-unverifiable=` from it, which clears the hold here.
723
723
  const newest = impls.filter((m, i) => !impls.some((o, j) => j > i && o.number === m.number));
724
- // A mismatch on a ticket whose issue is CLOSED holds nothing (#2485): there
724
+ // A mismatch on a ticket whose issue is CLOSED holds nothing: there
725
725
  // is nothing left for `impl-<N>-b` to replace, and a retired definition can
726
726
  // never re-check. `closed` is the ticket numbers the caller has probed; the
727
727
  // pure fold cannot probe, so none is the default and every mismatch holds.
@@ -776,7 +776,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
776
776
  // a conflict hold no fix-applier has cleared, or a dispositions mismatch
777
777
  // no retry has answered — on a PR still open, with no fix-applier working
778
778
  // it and no newer review running. The first two are answered apart
779
- // (#2328): a landed conflict fix-applier lifts the hold and leaves
779
+ // here: a landed conflict fix-applier lifts the hold and leaves
780
780
  // survivors it never read due for a review one.
781
781
  fixDue: [...byPr.entries()]
782
782
  .filter(([n, st]) => open.has(n)
@@ -785,8 +785,8 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
785
785
  .map(([n]) => n).sort(asc),
786
786
  // Open, not signed off, closing an issue (GitHub's own linked set — a
787
787
  // chore PR closing nothing is review work nobody in the run will ever be
788
- // dispatched against, #590), with no live or returned review on record —
789
- // or (#2083) a returned review its finisher halted `past-pin` against: the
788
+ // dispatched against), with no live or returned review on record —
789
+ // or a returned review its finisher halted `past-pin` against: the
790
790
  // head carries commits no reviewer read, so it is owed a review again
791
791
  // until one is running or has returned. A head that moved past
792
792
  // `reviewed=` with no such halt — a fix-applier's push — stays not due:
@@ -803,13 +803,13 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
803
803
  mergeHeld: queued.filter((p) => heldBehind(state(p.number)) || conflictHeld(state(p.number))).length,
804
804
  // How many of those are conflict holds — the HOLD row's wording, no field.
805
805
  mergeConflictHeld: queued.filter((p) => conflictHeld(state(p.number))).length,
806
- // #2331: finishers settled `labelled` on an open PR without the label.
806
+ // Finishers settled `labelled` on an open PR without the label.
807
807
  unlabelled: unlabelledFinishers({ rows, dispatched },
808
808
  new Set(prs.filter((p) => !isQueued(p)).map((p) => p.number))),
809
809
  // Every PR, open or not, on a conflict hold no fix-applier has cleared —
810
- // the one reading of a hold (#2299): `ledger.mjs dispatch` names a
810
+ // the one reading of a hold: `ledger.mjs dispatch` names a
811
811
  // fix-applier's definition off this list, so it answers the same per-PR
812
- // fold this tick holds the merge on, split rows (#2283) and a settle made
812
+ // fold this tick holds the merge on, split rows and a settle made
813
813
  // anywhere included, rather than re-deriving it from one row's text.
814
814
  conflictHeld: [...byPr.entries()].filter(([, st]) => conflictHeld(st)).map(([n]) => n).sort(asc),
815
815
  // Every PR, open or not, with a returned review: its latest `reviewed=`
@@ -834,7 +834,7 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
834
834
  tierUnchecked,
835
835
  claimed,
836
836
  excluded,
837
- // Who is live, by name, for a MAIN-CHECKOUT line (#2210): every unsettled
837
+ // Who is live, by name, for a MAIN-CHECKOUT line: every unsettled
838
838
  // member token, then each in-flight review by its PR — a `review=wf:`
839
839
  // run carries no member token of its own.
840
840
  live: [
@@ -930,7 +930,7 @@ const GH_TIMEOUT_MS = ghBudget(20, process.env.FLEET_TICK_GH_TIMEOUT);
930
930
  const TIMED_OUT = `timed out after ${GH_TIMEOUT_MS / 1000}s`;
931
931
 
932
932
  // die() shared with the other fleet scripts (writeSync-based, pipe-safe —
933
- // see arg.mjs for the #176/#328/#363 rationale). This file parses its own
933
+ // see arg.mjs for the rationale). This file parses its own
934
934
  // options with node:util's parseArgs rather than arg()/has(), so die() and
935
935
  // the isDigits() rule int() calls are all it shares.
936
936
  const die = makeDie(NAME);
@@ -940,7 +940,7 @@ const die = makeDie(NAME);
940
940
  const OPTIONS = {
941
941
  // Defaults here, not threaded through int(): declared this way they still
942
942
  // go through the guard below, where a hand-passed default went round it.
943
- // 2/6 (#1773): no hard cap on either role, defaults only.
943
+ // No hard cap on either role, defaults only.
944
944
  "implementer-cap": { type: "string", default: "2" },
945
945
  "reviewer-cap": { type: "string", default: "6" },
946
946
  // Reviews in flight at once. Default = the reviewer cap; run-team's own
@@ -969,7 +969,7 @@ function options() {
969
969
  }
970
970
  const int = (name) => {
971
971
  const raw = values[name];
972
- // #878: the digits rule, called rather than restated. Digits, not
972
+ // The digits rule, called rather than restated. Digits, not
973
973
  // Number(): `Number("")` is 0, so `--max-reviews ""` — the shape an unset
974
974
  // shell variable produces — would otherwise read as a real number.
975
975
  if (!isDigits(String(raw).trim())) die(`--${name} must be a non-negative integer, got '${raw}'`);
@@ -999,7 +999,7 @@ function openPrs() {
999
999
  } catch (e) {
1000
1000
  // Never interpolates e.stderr or e.message: execFileSync already forwarded
1001
1001
  // the child's stderr to ours, and Node builds e.message out of it, so
1002
- // either one emits every byte a second time (#176).
1002
+ // either one emits every byte a second time.
1003
1003
  die(`gh pr list failed: ${e.code === "ETIMEDOUT" ? TIMED_OUT : e.code ?? (e.signal ? `killed by ${e.signal}` : `exit ${e.status}`)} — a failed read is not an empty queue`);
1004
1004
  }
1005
1005
  let prs;
@@ -1010,7 +1010,7 @@ function openPrs() {
1010
1010
  }
1011
1011
  // closingIssuesReferences is checked, not defaulted: absent, it would read as
1012
1012
  // an empty list and drop every open PR from review work. headRefOid likewise
1013
- // (#2083): absent, a `halted:past-pin` PR would read as moved forever.
1013
+ // — absent, a `halted:past-pin` PR would read as moved forever.
1014
1014
  if (!Array.isArray(prs) || prs.some((p) => !p || typeof p.number !== "number"
1015
1015
  || !Array.isArray(p.labels) || !Array.isArray(p.closingIssuesReferences)
1016
1016
  || typeof p.headRefOid !== "string")) {
@@ -1054,7 +1054,7 @@ function readLedger() {
1054
1054
  }
1055
1055
 
1056
1056
  // `.fleet/shortlist.json` beside the run's ledger: the workspace from `git
1057
- // rev-parse --git-common-dir`, GIT_DIR/GIT_WORK_TREE scrubbed (#1599) so an
1057
+ // rev-parse --git-common-dir`, GIT_DIR/GIT_WORK_TREE scrubbed so an
1058
1058
  // ambient one cannot answer for another repository. null when unresolvable —
1059
1059
  // read as a missing shortlist, and the refresh then says why it could not run.
1060
1060
  function shortlistPath() {
@@ -1114,7 +1114,7 @@ function liftedPremise(excluded, entries, prs) {
1114
1114
  }
1115
1115
 
1116
1116
  // The tickets, of those holding the implementer row on a tier mismatch, whose
1117
- // issue is CLOSED (#2485): the one live read deriveRun needs to lift a hold
1117
+ // issue is CLOSED: the one live read deriveRun needs to lift a hold
1118
1118
  // whose replacement has nothing left to replace. One `gh issue view` per
1119
1119
  // mismatched ticket, and none when nothing is mismatched. A probe that cannot
1120
1120
  // answer — a nonzero exit, or a reply carrying no issue state — is disclosed
@@ -1208,7 +1208,7 @@ function main() {
1208
1208
  // Beside the shortlist, off the same git probe rather than a second one.
1209
1209
  const router = readCostGuard(listPath === null ? null : join(dirname(listPath), "cost-guard.json"));
1210
1210
 
1211
- // The PRIOR run's liveness, before anything that can refuse — #1597. The gh
1211
+ // The PRIOR run's liveness, before anything that can refuse. The gh
1212
1212
  // read and the ledger read below both exit 2 on failure, and a stall
1213
1213
  // announced after them is a stall a gh outage can silence. The supply it
1214
1214
  // reports is the local shortlist file's, which no outage can take away.
@@ -1256,8 +1256,8 @@ function main() {
1256
1256
  }
1257
1257
  }
1258
1258
 
1259
- // #2210: the main checkout against the run's baseline, on every tick — the
1260
- // backstop for what #1411's guard cannot see. Never a refusal of the tick:
1259
+ // The main checkout against the run's baseline, on every tick — the
1260
+ // backstop for what member-write-guard cannot see. Never a refusal of the tick:
1261
1261
  // every answer but `clean` is a hold on the dispatching rows plus one line
1262
1262
  // saying why, so the rest of the run keeps reporting.
1263
1263
  const mainCheckout = checkMainCheckout();
@@ -1276,13 +1276,13 @@ function main() {
1276
1276
  const prev = readState(path, NAME);
1277
1277
  const digest = createHash("sha256").update(lines.join("\n")).digest("hex");
1278
1278
  const acts = actionable(rows);
1279
- // `ticked`, fleet-tick's own liveness key (#1597 follow-up): written on
1279
+ // `ticked`, fleet-tick's own liveness key: written on
1280
1280
  // every invocation unconditionally — this tick running IS the occurrence.
1281
1281
  writeState(path, NAME, prev, { quiet: acts ? 0 : prev.quiet + 1, digest, ticked: { at: Date.now() } });
1282
1282
 
1283
1283
  // Fold only when BOTH hold: nothing to act on, and nothing new to say. A
1284
1284
  // main-checkout hold still holding dispatch stays named on the folded line
1285
- // (#2307) — not actionable, so it never resets `quiet`, but the one reason
1285
+ // — not actionable, so it never resets `quiet`, but the one reason
1286
1286
  // nothing dispatches must not drop out of view. Outside the digest, which
1287
1287
  // already covers it through the rows.
1288
1288
  if (fold && !acts && digest === prev.digest) {
@@ -1,12 +1,11 @@
1
1
  #!/usr/bin/env node
2
- // The allow-list checker (#1314, #1347). Layer 1 of two (#1298/ADR 0005):
2
+ // The allow-list checker. Layer 1 of two:
3
3
  // this is a STATIC audit of an agent/skill/command file's frontmatter SHAPE,
4
- // before any run exists. Layer 2 (tier-check.mjs, #1345) compares a live
4
+ // before any run exists. Layer 2 (tier-check.mjs) compares a live
5
5
  // dispatch's RESOLVED tier against the declaration; this file never reads a
6
6
  // transcript and never runs anything.
7
7
  //
8
- // Contract, fixed on #1314 and recorded with the key sets on its closing
9
- // comment: three key sets (agents, skills, commands), enforced in BOTH
8
+ // Contract: three key sets (agents, skills, commands), enforced in BOTH
10
9
  // directions — an unknown key is a violation (half a contract leaves an
11
10
  // undocumented addition silent) and a missing REQUIRED key is a
12
11
  // violation — plus a third class, FORBIDDEN: a key that IS documented but
@@ -19,16 +18,16 @@
19
18
  // printed before exiting). Exit 2 for CANNOT-RUN — the allow-list is
20
19
  // missing or unreadable, or a file's frontmatter cannot be parsed at all.
21
20
  // The distinction matters: a missing allow-list must fail LOUDLY rather
22
- // than silently pass with an empty key set (#1314's own wording), which a
21
+ // than silently pass with an empty key set, which a
23
22
  // bare exit-1-on-no-violations would do by accident if a missing file
24
23
  // happened to yield an empty ruleset instead of an error.
25
24
  //
26
25
  // Kind classification is PATH-based, never content-sniffed: an ancestor
27
26
  // segment named `agents`, a `<name>/SKILL.md` under `skills`, or a
28
- // `commands/<name>.md` — the same convention install-root-audit.test.mjs's
29
- // own tree walk and repo-root.mjs's own layout assumptions already use.
30
- // Works whether invoked with a repo-relative path (`plugin/agents/x.md`,
31
- // after #1336's re-nest) or a bare one under a kind directory (check-tracked.sh
27
+ // `commands/<name>.md` — the same convention the test suite's install-root
28
+ // tree walk and repo-root.mjs's own layout assumptions already use.
29
+ // Works whether invoked with a repo-relative path (`plugin/agents/x.md`)
30
+ // or a bare one under a kind directory (check-tracked.sh
32
31
  // hands this xargs-expanded `git ls-files` paths, always repo-relative from
33
32
  // the repo root check-tracked.sh itself runs in).
34
33
  //
@@ -39,7 +38,7 @@
39
38
  // this reader cannot make sense of (no closing fence, a line that is
40
39
  // neither blank nor `key: value`) is CANNOT-RUN, not a violation — a parser
41
40
  // that quietly skipped what it couldn't read would silently pass exactly
42
- // the "frontmatter unparseable" case #1314 named as a hard exit-2.
41
+ // the "frontmatter unparseable" case the contract names as a hard exit-2.
43
42
 
44
43
  import { readFileSync } from "node:fs";
45
44
  import { dirname, join } from "node:path";
@@ -51,7 +50,7 @@ const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
51
50
  const DEFAULT_ALLOWLIST_PATH = join(SCRIPT_DIR, "frontmatter-allowlist.json");
52
51
 
53
52
  // ---------------------------------------------------------------------------
54
- // pure core — unit- and mutation-tested directly (frontmatter-check.test.mjs),
53
+ // pure core — unit- and mutation-tested directly,
55
54
  // no filesystem or process access below this line until main()
56
55
  // ---------------------------------------------------------------------------
57
56
 
@@ -1,5 +1,4 @@
1
- // The run ledger's member grammar (#1799; spec 2026-09-24 § 6 §2, ADR 0012
2
- // Decision 5): a member's token is `<member>` while it is live and
1
+ // The run ledger's member grammar: a member's token is `<member>` while it is live and
3
2
  // `<member>=<outcome>` once settled. `ledger.mjs dispatch` writes the bare
4
3
  // token and `ledger.mjs settle` rewrites it, so a reader derives every
5
4
  // liveness count from the ledger file alone instead of from the controller's
@@ -7,12 +6,12 @@
7
6
  //
8
7
  // A module of its own, not a function inside ledger.mjs, because ledger.mjs is
9
8
  // a CLI that parses argv and exits on import — and `fleet-tick.mjs` is to read
10
- // this same grammar (#1803). A second copy of it there would be two readings
9
+ // this same grammar. A second copy of it there would be two readings
11
10
  // of which members are live, free to drift apart.
12
11
  //
13
12
  // Rows stay freeform text. Only a token whose name part is a member name is
14
13
  // claimed here; everything else a row carries (`class=routine`, `ports=`,
15
- // `ci=`, `held-behind:#M`, merge-bot's `conflict-hold:#<pr>`, #1773's
14
+ // `ci=`, `held-behind:#M`, merge-bot's `conflict-hold:#<pr>`, the
16
15
  // `review=`/`reviewed=` pair, the `→ PR#M` arrow) is not a member and is left
17
16
  // alone.
18
17
 
@@ -29,9 +28,9 @@ const FAMILIES = {
29
28
  // Every family parseMember can yield: MEMBER below is built from this list,
30
29
  // so every family it matches has an entry here by construction.
31
30
  export const MEMBER_FAMILIES = Object.freeze(Object.keys(FAMILIES));
32
- // A finisher halt's causes (#2083): the finisher worked correctly and refused
31
+ // A finisher halt's causes: the finisher worked correctly and refused
33
32
  // to label, which `failed` (it crashed or gave up) does not say. `unreadable`,
34
- // `missing` and `absent` are duty 1's audit-read halts (#1106).
33
+ // `missing` and `absent` are duty 1's audit-read halts.
35
34
  export const HALT_CAUSES = ["live-editor", "rebase", "past-pin", "unreadable", "missing", "absent", "other"];
36
35
  const OUTCOME_PATTERNS = {
37
36
  "PR#M": /^PR#[1-9][0-9]*$/,
@@ -89,7 +88,7 @@ export function nextMergeBot(dispatched) {
89
88
  return `merge-bot-${dispatched.map(parseToken).filter((t) => t?.family === "merge-bot").length + 1}`;
90
89
  }
91
90
 
92
- // #2030: an implementer cell is `<role>-<level>` — an omp role and a thinking
91
+ // An implementer cell is `<role>-<level>` — an omp role and a thinking
93
92
  // level — and each cell is one definition, `fleet-implementer-<cell>`, whose
94
93
  // `model:` is `@<role>:<level>` (spec 2026-09-28 § 2). Nothing is named
95
94
  // `fleet-implementer` alone, so CELL_DEF is the whole implementer family:
@@ -120,7 +119,7 @@ export function drawCell({ session, ticket, policyCell, cells }) {
120
119
  return { cell: E[k - 1], k, K };
121
120
  }
122
121
 
123
- // #1398: the definition an implementer should run under, off its ticket
122
+ // The definition an implementer should run under, off its ticket
124
123
  // row's `tier=` token — none means `fleet-implementer-<POLICY_CELL>`,
125
124
  // `tier=<x>` means `fleet-implementer-<x>`. The value becomes a file
126
125
  // name under `agents/`, so it is held to `[a-z0-9]` words joined by `-`
@@ -129,7 +128,7 @@ export function drawCell({ session, ticket, policyCell, cells }) {
129
128
  // position. A value with no definition behind it (the retired `tier=alt`) is
130
129
  // `ledger.mjs dispatch`'s to refuse: it checks the file exists.
131
130
  //
132
- // Here, not in tier-check.mjs, because two readers must agree on it (#2208):
131
+ // Here, not in tier-check.mjs, because two readers must agree on it:
133
132
  // `ledger.mjs dispatch` prints the definition before the call, and
134
133
  // tier-check.mjs judges the member against it after. Two copies could name
135
134
  // different definitions for one row and fail a dispatch made exactly as
@@ -149,18 +148,18 @@ export function expectedDefinition(rowText) {
149
148
  return `fleet-implementer-${values[0]}`;
150
149
  }
151
150
 
152
- // The agent definition a member is dispatched as (#2208), for a parsed member
151
+ // The agent definition a member is dispatched as, for a parsed member
153
152
  // and the text of the row it works: `ledger.mjs dispatch` prints it so the
154
153
  // `task` call that follows names it off a script's output, not off prose a
155
154
  // compaction drops. A fix-applier on an unresolved conflict hold of its own PR
156
- // is a `fleet-implementer-<POLICY_CELL>` whatever the row's `tier=` (#2299) —
155
+ // is a `fleet-implementer-<POLICY_CELL>` whatever the row's `tier=` —
157
156
  // it rebases the PR, it does not work a ticket at a tier. Any other fix-applier is a review
158
157
  // one and gets null: a generic `task` by design. Whether the hold is
159
158
  // unresolved is `conflictHeld`, the caller's to supply from fleet-tick.mjs's
160
159
  // deriveRun() — the reading the tick holds the merge on, which folds every
161
160
  // row of the PR, never one row's text alone. Throws whatever
162
- // expectedDefinition throws, and on a family this switch has no case for
163
- // (#2330): null is the review fix-applier's deliberate answer, so a
161
+ // expectedDefinition throws, and throws on a family this switch has no case
162
+ // for: null is the review fix-applier's deliberate answer, so a
164
163
  // `default: return null` would print a new family as a generic `task`
165
164
  // without anyone having decided it is one.
166
165
  /** @returns {string|null} the definition name; null only for a review fix-applier. */