@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.
- package/package.json +1 -1
- package/scripts/ci-state.mjs +25 -26
- package/scripts/compute-spend.mjs +22 -22
- package/scripts/diff-stats.mjs +12 -12
- package/scripts/fleet-heartbeat.mjs +9 -9
- package/scripts/fleet-state.mjs +15 -15
- package/scripts/fleet-tick.mjs +63 -63
- package/scripts/frontmatter-check.mjs +10 -11
- package/scripts/ledger-grammar.mjs +12 -13
- package/scripts/member-outcomes.mjs +8 -9
- package/scripts/merge-gate.mjs +2 -4
- package/scripts/pr-overlap.mjs +31 -30
- package/scripts/shortlist.mjs +6 -8
- package/scripts/staleness.mjs +21 -21
- package/scripts/tier-check.mjs +14 -14
- package/scripts/tier-roles.mjs +12 -12
package/scripts/fleet-tick.mjs
CHANGED
|
@@ -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.
|
|
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
|
|
13
|
-
// fix-pr PR
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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"
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
|
328
|
-
// printing `PULL
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
|
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
|
|
562
|
-
// ticket row settled `impl
|
|
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
|
|
574
|
-
// so it clears the hold and answers no survivor
|
|
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`
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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
|
-
//
|
|
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
|
|
789
|
-
// or
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
|
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
|
-
//
|
|
1260
|
-
// backstop for what
|
|
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
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
29
|
-
//
|
|
30
|
-
// Works whether invoked with a repo-relative path (`plugin/agents/x.md
|
|
31
|
-
//
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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>`,
|
|
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
|
|
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
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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=`
|
|
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
|
|
163
|
-
//
|
|
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. */
|