@feigi/fleet-ctl 3.24.2 → 3.24.3

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.
@@ -1,9 +1,9 @@
1
1
  // Pure board-model builder. No I/O and no clock read — `now` is passed in, so
2
2
  // dwell/staleness is deterministic and unit-testable. board.mjs does the gh/
3
3
  // ledger I/O and calls computeBoard(); every stage-derivation and flag decision
4
- // lives here and is exercised by compute-board.test.mjs (`node --test`).
4
+ // lives here and is exercised by its unit tests (`node --test`).
5
5
  //
6
- // #1597, #1820, #1839: the THREE imports this module takes, all pure ones.
6
+ // The THREE imports this module takes, all pure ones.
7
7
  // fleet-state.mjs owns the heartbeat's `beat` key, and the rule for reading
8
8
  // that key travels with it rather than being copied here. That module's own
9
9
  // I/O (its path probe, its file read) is never called from this file; only
@@ -16,26 +16,27 @@
16
16
  // from it for the same reason — one grammar, one reader, so the cockpit and
17
17
  // fleet-tick.mjs cannot disagree about which members are live.
18
18
  // fleet-tick.mjs owns a row's PR reading, PR_MENTION, and a row with no impl
19
- // token is read through it (#1820 amendment 2a, below) so both readers name
20
- // the same PR for the same text, for a row that carries a PR-bound signal —
19
+ // token is read through it (see the paragraph below on a row with no `impl`
20
+ // token) so both readers name the same PR for the same text, for a row that
21
+ // carries a PR-bound signal —
21
22
  // an unsignaled row (no mention, no PR-bound member, no review=/reviewed=)
22
23
  // still gets pr: null here while fleet-tick.mjs's own row-key fallback keys
23
- // it to its ticket number regardless; see the amendment note below. The
24
+ // it to its ticket number regardless; see the same paragraph below. The
24
25
  // regex is all this file takes from it: the tick's I/O and main() never run
25
26
  // here, main() being guarded on argv[1].
26
27
  import { assessBeat, isStalled, stallReport } from "./fleet-state.mjs";
27
28
  import { parseToken, HALT_CAUSES } from "./ledger-grammar.mjs";
28
29
  import { PR_MENTION, REVIEWED, latestFinisherAttempts } from "./fleet-tick.mjs";
29
30
 
30
- // A ledger row is freeform, controller-authored text. Two real examples:
31
- // #332 impl-332=PR#344 → PR#344 → MERGED 73b356de
32
- // #324 impl-324=PR#346 → PR#346 · fix-pr-346 · ruled:6-applies · held-behind:#313
31
+ // A ledger row is freeform, controller-authored text. Two example shapes:
32
+ // #<n> impl-<n>=PR#<m> → PR#<m> → MERGED 73b356de
33
+ // #<n> impl-<n>=PR#<m> → PR#<m> · fix-pr-<m> · ruled:6-applies · held-behind:#<k>
33
34
  // Extract by token, never by position — the controller reorders and appends
34
35
  // tokens freely. Unknown text is ignored, never fatal.
35
36
  //
36
- // Member tokens are ledger-grammar.mjs's (#1820). On a row that has one, the
37
+ // Member tokens are ledger-grammar.mjs's. On a row that has one, the
37
38
  // row's latest `impl` attempt decides the card — the greatest retry suffix,
38
- // wherever it sits (#1843, laterAttempt below): live → IMPLEMENTING, `=PR#M`
39
+ // wherever it sits (laterAttempt below): live → IMPLEMENTING, `=PR#M`
39
40
  // → that PR decides, `=released`/`=bailed` → no card of
40
41
  // the row's own (the POOL loop shows the ticket if it is still
41
42
  // `ready-for-agent`), `=killed`/`=tier-mismatch` → IMPLEMENTING with that
@@ -46,7 +47,7 @@ import { PR_MENTION, REVIEWED, latestFinisherAttempts } from "./fleet-tick.mjs";
46
47
  // nothing enforces that order, so on such a row the arrow is never a value
47
48
  // either reader may rely on.
48
49
  //
49
- // #1820 amendment 2a: a row with no `impl` token at all has no outcome to
50
+ // A row with no `impl` token at all has no outcome to
50
51
  // read, so it takes the tick's reading. `ledger.mjs dispatch <pr> fix-pr-<pr>` /
51
52
  // `finisher-pr-<pr>` appends `#<pr> <member>` for a PR this run's
52
53
  // implementers did not open. Once such a row carries a PR-bound signal — a
@@ -57,7 +58,7 @@ import { PR_MENTION, REVIEWED, latestFinisherAttempts } from "./fleet-tick.mjs";
57
58
  // A member settled anywhere on the row is settled — a bare copy beside
58
59
  // `<member>=<outcome>` is what a whole-line `row` rewrite leaves.
59
60
  //
60
- // #2083: a PR whose latest finisher attempt settled `halted:<cause>` carries
61
+ // A PR whose latest finisher attempt settled `halted:<cause>` carries
61
62
  // that outcome as a severity-4 flag while the PR sits in REVIEW. The halt is
62
63
  // the finisher working correctly — it refused to label — so the PR has no
63
64
  // `ready-to-merge` until the controller resolves the cause; the flag is what
@@ -66,7 +67,7 @@ import { PR_MENTION, REVIEWED, latestFinisherAttempts } from "./fleet-tick.mjs";
66
67
  // `## Dispatched` tokens): a live `-b` after the halt clears it, and a later
67
68
  // attempt settled anywhere replaces it.
68
69
  //
69
- // #2331: a PR whose finisher settled `labelled` while the open list shows no
70
+ // A PR whose finisher settled `labelled` while the open list shows no
70
71
  // `ready-to-merge` on it carries a severity-4 `unlabelled` flag in REVIEW —
71
72
  // fleet-tick.mjs's own reading (unlabelledFinishers: the latest attempt since
72
73
  // the last `label-off=`), off the same `## Dispatched` and row tokens the tick
@@ -80,12 +81,12 @@ import { PR_MENTION, REVIEWED, latestFinisherAttempts } from "./fleet-tick.mjs";
80
81
  // dispatches nothing for these; the flag is what puts the PR in front of a
81
82
  // human. The names are not the bare `killed` flag, which is the implementer's.
82
83
  //
83
- // A PR's review is not a member (#1773 §7): `review=wf:<runId>` is a Workflow
84
+ // A PR's review is not a member: `review=wf:<runId>` is a Workflow
84
85
  // with nobody to name, while `review=member:<name>` and
85
86
  // `review=fallback:<name>` name a runner member, live until the token is
86
87
  // settled `=failed` or a later `reviewed=` records its result.
87
88
  //
88
- // #1820 amendment 5a: a `review=` token puts the PR under review only while
89
+ // A `review=` token puts the PR under review only while
89
90
  // it is live. A settled `review=…=failed` is a dead review and the PR is owed
90
91
  // one again, as run-team SKILL.md defines review-due and as fleet-tick.mjs's
91
92
  // `reviewedAny` reads the token: the PR is owed none while the row carries
@@ -105,7 +106,7 @@ const PREMISE = /\bbehind-(pr|issue):#?([^\s,;]+)/g;
105
106
  // what each kind means and how `=failed` settles it.
106
107
  const REVIEW = /^review=(wf|member|fallback):([^=\s]+?)(=failed)?$/;
107
108
 
108
- // #1843: which of two well-formed impl tokens is the later attempt for THIS
109
+ // Which of two well-formed impl tokens is the later attempt for THIS
109
110
  // row's ticket. A token whose number matches the row's own ticket always
110
111
  // outranks one that does not: a retry suffix only orders attempts on ONE
111
112
  // number (ledger-grammar.mjs's MEMBER regex comment — "Attempts on one
@@ -158,8 +159,8 @@ export function parseRow(row) {
158
159
  const finishers = []; // well-formed finisher tokens, for the row's PR below
159
160
  let anyImpl = false;
160
161
  let prMember = false;
161
- let review = false; // any review= token: a PR-bound signal (amendment 2a)
162
- let reviewLive = false; // one not settled `=failed` (amendment 5a)
162
+ let review = false; // any review= token: a PR-bound signal on a row with no impl token
163
+ let reviewLive = false; // one not settled `=failed`: a live review
163
164
  let reviewed = false;
164
165
  let reviewedHead = null;
165
166
  let runners = [];
@@ -194,7 +195,7 @@ export function parseRow(row) {
194
195
  }
195
196
  } else if (tok.startsWith("reviewed=")) {
196
197
  reviewed = true;
197
- // (#2083) The head that review actually read — the cockpit's own copy
198
+ // The head that review actually read — the cockpit's own copy
198
199
  // of fleet-tick.mjs's `reviewedHead`, needed below to tell a past-pin
199
200
  // halt already answered by this review apart from one still owed a
200
201
  // fresh one.
@@ -208,7 +209,7 @@ export function parseRow(row) {
208
209
  const implOutcome = lastImpl ? (implOutcomes.get(lastImpl.name) ?? null) : null;
209
210
  const prM = implOutcome && /^PR#(\d+)$/.exec(implOutcome);
210
211
  let pr = prM ? Number(prM[1]) : null;
211
- // #1820 amendment 2a: a row with NO impl token — a malformed one still
212
+ // A row with NO impl token — a malformed one still
212
213
  // counts, since that row's key is a ticket — is keyed, once THIS row
213
214
  // carries a PR-bound signal, the way fleet-tick.mjs's PR_MENTION-then-
214
215
  // row-key logic would: its first PR_MENTION (itself a signal), else the
@@ -249,7 +250,7 @@ export function parseRow(row) {
249
250
  // released or bailed implementer: the ticket went back to the tracker, and the
250
251
  // POOL loop shows it if it is still `ready-for-agent`). An Exclusion is POOL.
251
252
  // MERGED is an explicit `MERGED <sha>` token or, failing one, `prState.merged`
252
- // — gh's answer for a row PR absent from the open list, or (#1841) a
253
+ // — gh's answer for a row PR absent from the open list, or a
253
254
  // carry-forward of the previous board's MERGED for that SAME PR on that
254
255
  // ticket: MERGED is terminal, so a merged PR never reopens regardless of
255
256
  // what this run's merged read says — but a ticket retried under a NEW PR
@@ -276,7 +277,7 @@ export const STALE_MS = {
276
277
  READY: 15 * 60 * 1000,
277
278
  };
278
279
 
279
- // An Exclusion's badges are its premises, `excluded:#880` for a number and
280
+ // An Exclusion's badges are its premises, `excluded:#<n>` for a number and
280
281
  // `excluded:<branch>` for a branch name, and nothing else: it is supply, so no
281
282
  // dwell clock and no cause applies. isBadge() keeps them out of `attention`.
282
283
  export function deriveFlags(parsed, ctx) {
@@ -352,7 +353,7 @@ function splitNumbered(line) {
352
353
  return m ? { issue: Number(m[1]), subject: m[2] } : { issue: null, subject: line };
353
354
  }
354
355
 
355
- // The stall surface, or null when there is nothing to say. #1597.
356
+ // The stall surface, or null when there is nothing to say.
356
357
  //
357
358
  // The two facts the report needs beyond the mark itself — what is claimed and
358
359
  // whether the pool still has supply — are read off THIS model rather than
@@ -386,7 +387,7 @@ function stall(beat, ticked, tickets, pool, { ledgerOk, poolOk }, now) {
386
387
  return { ...verdict, claimed, supply, text: stallReport(verdict, { claimed, supply }) };
387
388
  }
388
389
 
389
- // #2108: which of gather()'s `gh ... list` reads came back exactly as long as
390
+ // Which of gather()'s `gh ... list` reads came back exactly as long as
390
391
  // its own `--limit` — and so may have been cut there, gh saying nothing — as
391
392
  // one rendered line, or null when neither did. The pool's count carries its
392
393
  // own `n+` besides (computeBoard below); this line is for what a count cannot
@@ -401,7 +402,7 @@ function capNotice({ poolCapped, prsCapped }) {
401
402
  return parts.length ? parts.join("; ") : null;
402
403
  }
403
404
 
404
- // #1841: the previous board already showed this SAME PR MERGED on this
405
+ // The previous board already showed this SAME PR MERGED on this
405
406
  // ticket. MERGED is terminal, so that verdict stands whatever this run's
406
407
  // merged read says. Keyed on the PR, not just the ticket: a ticket retried
407
408
  // under a NEW PR after its earlier one merged carries no MERGED verdict
@@ -412,7 +413,7 @@ function carriedMerged(prevTicket, p) {
412
413
  return prevTicket?.column === "MERGED" && prevTicket.pr === p.pr;
413
414
  }
414
415
 
415
- // #1840: the row PRs whose merged status gather() has to ask gh about this
416
+ // The row PRs whose merged status gather() has to ask gh about this
416
417
  // tick — exactly those computeBoard() would consult `merged` for and cannot
417
418
  // already place: a row PR absent from the open list `prs`, on a row that is
418
419
  // not an Exclusion (always POOL), carries no `MERGED <sha>` token, has a PR
@@ -441,15 +442,15 @@ export function mergedReadPrs({ ledger, prs, prev }) {
441
442
  return [...need].sort((a, b) => a - b);
442
443
  }
443
444
 
444
- // `merged` (#1820) is gh's list of merged PR numbers, consulted only for a row
445
+ // `merged` is gh's list of merged PR numbers, consulted only for a row
445
446
  // PR absent from the open list `prs`; absent means none known, and a PR in
446
447
  // neither list (closed unmerged, or a failed read) keeps REVIEW — unless
447
- // (#1841) carriedMerged() holds for it, in which case it stays MERGED
448
+ // carriedMerged() holds for it, in which case it stays MERGED
448
449
  // whether this run's merged read failed outright or simply succeeded
449
450
  // without listing it. A PR that IS in the open list is never eligible for
450
451
  // this carry-forward — only the "absent from both `prs` and (maybe)
451
452
  // `merged`" branch below ever consults it. gather() asks gh only about
452
- // mergedReadPrs()'s set (#1840), so `merged` never lists more than that.
453
+ // mergedReadPrs()'s set, so `merged` never lists more than that.
453
454
  export function computeBoard(inputs) {
454
455
  const { ledger, issues, prs, ci, prev, now } = inputs;
455
456
  const prByNum = new Map(prs.map((p) => [p.number, p]));
@@ -492,8 +493,8 @@ export function computeBoard(inputs) {
492
493
  });
493
494
  }
494
495
 
495
- // A wayfinder:* ticket is documentation-only regardless of its triage role
496
- // (#1331): candidates.mjs's dispatch scan never surfaces one even carrying
496
+ // A wayfinder:* ticket is documentation-only regardless of its triage role:
497
+ // candidates.mjs's dispatch scan never surfaces one even carrying
497
498
  // `ready-for-agent`, so this POOL column must not either, or an
498
499
  // undispatchable ticket inflates the operator's read of available work.
499
500
  // Filtered HERE rather than out of gather()'s gh query: `issues` also feeds
@@ -515,8 +516,8 @@ export function computeBoard(inputs) {
515
516
  .sort((a, b) => severity(b.flags) - severity(a.flags));
516
517
 
517
518
  // Backlog is a PR nobody has reviewed and nobody is reviewing: no live
518
- // `review=` (#1820 amendment 5a — a settled `=failed` one is no review), no
519
- // `reviewed=`, and no live fix-applier or finisher on the row — or (#2083)
519
+ // `review=` (a settled `=failed` one is no review), no
520
+ // `reviewed=`, and no live fix-applier or finisher on the row — or
520
521
  // a returned review whose finisher halted `past-pin` against a head it
521
522
  // never read: owed again until the head catches up to what `reviewed=`
522
523
  // recorded, the same rule fleet-tick.mjs's reviewDue reads off headRefOid
@@ -530,7 +531,7 @@ export function computeBoard(inputs) {
530
531
  return t.column === "REVIEW" && !p.underReview && (!p.reviewed || pastPinBacklog(p));
531
532
  }).length;
532
533
  const cardsInPool = tickets.filter((t) => t.column === "POOL").length;
533
- // #2108: a capped pool read makes this count a floor, and it says so the way
534
+ // A capped pool read makes this count a floor, and it says so the way
534
535
  // fleet-tick.mjs's claimed count does — `"100+"`, never a bare 100 that
535
536
  // reads as exact. stall() below receives the same value, so the stall line
536
537
  // and the footer cannot disagree about it.
@@ -541,13 +542,13 @@ export function computeBoard(inputs) {
541
542
  interval: inputs.interval ?? 15,
542
543
  repo: inputs.repo ?? null,
543
544
  repoUrl: inputs.repoUrl ?? null,
544
- // #1584: which workspace this board describes and which port served it.
545
+ // Which workspace this board describes and which port served it.
545
546
  // Pass-through, exactly like repo/repoUrl above and for the same reason —
546
547
  // resolveCockpitInstance() answers both at the gather boundary, and this
547
548
  // module reads no cwd, no git and no socket, so it cannot re-derive either
548
549
  // and must not try. Defaulted to null rather than left undefined: a
549
550
  // missing key and a null one are the same value to a reader in JS but not
550
- // in the JSON on disk, and #1585's launch handshake reads `workspace` off
551
+ // in the JSON on disk, and the launch handshake reads `workspace` off
551
552
  // that JSON — a dropped key would make every board anonymous to it.
552
553
  workspace: inputs.workspace ?? null,
553
554
  port: inputs.port ?? null,
@@ -557,7 +558,7 @@ export function computeBoard(inputs) {
557
558
  filed: (ledger.filed || []).map(splitNumbered),
558
559
  // Not derivable from anything else in this model: a ledger that was never
559
560
  // read, one read empty, and one whose payload would not parse all reduce to
560
- // the same empty lists, which is the collapse #816 names. gather() is the
561
+ // the same empty lists. gather() is the
561
562
  // only caller that can tell them apart, so it says so and this carries the
562
563
  // answer to the page. Defaulted rather than required — every other caller
563
564
  // of computeBoard builds its inputs by hand and means a ledger it read.
@@ -569,7 +570,7 @@ export function computeBoard(inputs) {
569
570
  // which would read as "this run was free", and shows the error, which is
570
571
  // a bug the operator has to act on.
571
572
  spend: inputs.spend ?? null,
572
- // #1597. Telemetry beside `spend`, and under the same rule: a liveness
573
+ // Telemetry beside `spend`, and under the same rule: a liveness
573
574
  // input can only ever POPULATE or OMIT this field, and nothing above it
574
575
  // reads `inputs.beat` — no column, no flag, no dwell clock, no attention
575
576
  // row. A dead controller does not move a ticket; it means nobody is