@feigi/fleet-ctl 3.24.1 → 3.24.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.24.1",
3
+ "version": "3.24.2",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
package/scripts/arg.mjs CHANGED
@@ -2,8 +2,8 @@
2
2
  // has(), sweep(), stray(), the three refusal rules
3
3
  // isFlagLike()/hasEqualsForm()/isDigits(), and writeAll() — the short-write
4
4
  // and EAGAIN retry loop every script's own stdout/stderr write routes
5
- // through (#1549).
6
- // #367: was five drifting copies of arg(), three of has(), seven of die() in
5
+ // through.
6
+ // These helpers were five drifting copies of arg(), three of has(), seven of die() in
7
7
  // two incompatible shapes — one paste behind on any guard fix. One copy now;
8
8
  // a fix to the contract lands here once and reaches every caller that routes
9
9
  // through the helper it fixes.
@@ -18,16 +18,16 @@
18
18
  // argv reader cannot call arg()/has() at all, because those refuse under a
19
19
  // GENERATED message ("--<name> needs a value") and such a reader exists
20
20
  // precisely to refuse under its own ("--file needs a path"). ledger.mjs
21
- // splices --file/--require-file out of argv itself (#362) and
21
+ // splices --file/--require-file out of argv itself and
22
22
  // member-outcomes.mjs reads its own --file, so both were out of arg()'s
23
23
  // reach — and both answered that by copying the expression, which is a
24
24
  // requirement recorded where nothing executes it.
25
25
  //
26
- // #567 closed that: the rules are stated once, as isFlagLike() and
26
+ // That gap is closed: the rules are stated once, as isFlagLike() and
27
27
  // hasEqualsForm() below, and BOTH readers import and call them while keeping
28
28
  // their own wording. No script now restates one of these rules as a value
29
29
  // guard instead of calling it. That is executed, not documented —
30
- // shared-refusal.test.mjs reds when a copy is re-inlined, including one
30
+ // a test reds when a copy is re-inlined, including one
31
31
  // re-inlined behaviour-identically, which no behavioural test can see. Read
32
32
  // the current division with `grep -n 'from "./arg.mjs"'
33
33
  // scripts/*.mjs | grep -v test` rather than trusting a list
@@ -51,7 +51,7 @@
51
51
  // importing this file refuses its command line through a die() bound from
52
52
  // here, and a module that binds none has no command line to refuse a flag on
53
53
  // — review-core.mjs, which imports isDigits alone and is itself imported by
54
- // review-eval.mjs, joined the `scripts/*.mjs` glob when #1763 renamed it from
54
+ // review-eval.mjs, joined the `scripts/*.mjs` glob when it was renamed from
55
55
  // `.js`. A future script that refuses WITHOUT makeDie falls out of this grep;
56
56
  // that is the price of the filter, named here rather than hidden. Read that output
57
57
  // for the roster — the scripts this header names exemplify a way of
@@ -60,8 +60,8 @@
60
60
  // fleet-tick.mjs is the one script still outside arg()/has(), and
61
61
  // deliberately: it parses its flags with node:util's parseArgs, so its
62
62
  // unknown-flag, required-flag and range refusals are a separate edit site on
63
- // its own terms. Its integer guard is no longer one of them — #878 gave the
64
- // digits grammar its own predicate (isDigits() below) precisely because
63
+ // its own terms. Its integer guard is no longer one of them — the digits
64
+ // grammar has its own predicate (isDigits() below) precisely because
65
65
  // isFlagLike() cannot express it, and int() now calls that instead of
66
66
  // hand-writing the third spelling. What stays fleet-tick's own there is the
67
67
  // `String(raw).trim()` its input needs and the wording of its refusal, not
@@ -82,15 +82,15 @@
82
82
 
83
83
  import { writeSync } from "node:fs";
84
84
 
85
- // #1549: ONE write-retry loop, not three. Resuming a short write and waiting
85
+ // ONE write-retry loop, not three. Resuming a short write and waiting
86
86
  // out an EAGAIN are properties of the FD, not of any one caller, so die()
87
87
  // below, ci-state.mjs's verdict writes and staleness.mjs's verdict() all
88
88
  // route through writeAll() instead of each hand-rolling the same
89
89
  // while/try/subarray. They were three independent copies held in step by a
90
90
  // comment reading "mirrors emit()" and by nothing executable — which is
91
91
  // exactly how one of them (ci-state.mjs's emit()) stayed the only one with no
92
- // retry cap at all. board.mjs's fault() is the fourth site and is #1547's to
93
- // move, not this file's.
92
+ // retry cap at all. board.mjs's fault() is the fourth site, and it stays
93
+ // outside this file deliberately — its own comment says why.
94
94
  const MAX_EAGAIN_RETRIES = 200;
95
95
 
96
96
  // Shared across every retry: Atomics.wait never writes or notifies it, so one
@@ -104,7 +104,7 @@ const IDLE = new Int32Array(new SharedArrayBuffer(4));
104
104
  // full — the state an fd reaches once a stream has been initialised on it
105
105
  // (console.error does that to fd 2) and enough output is queued behind it. It
106
106
  // either SHORT-WRITES, returning the count it managed and throwing nothing at
107
- // all, silently truncating with no diagnostic for a catch to see (#885/#889);
107
+ // all, silently truncating with no diagnostic for a catch to see;
108
108
  // or it throws EAGAIN. So this resumes from writeSync's own return value
109
109
  // until the buffer is empty, and reads EAGAIN as "momentarily full", waiting
110
110
  // 1ms for the reader rather than treating it as failure. The wait is what
@@ -112,7 +112,7 @@ const IDLE = new Int32Array(new SharedArrayBuffer(4));
112
112
  // bare `continue` burned a full core for the whole stall where the 1ms wait
113
113
  // burned almost none, both delivering the same bytes.
114
114
  //
115
- // The EAGAIN retry is CAPPED (#889). Uncapped, a reader that stays open but
115
+ // The EAGAIN retry is CAPPED. Uncapped, a reader that stays open but
116
116
  // never drains — not merely a slow one — spins here forever, and every caller
117
117
  // is one whose whole job is to finish and report an exit code, so an
118
118
  // indefinite hang trades that guarantee away. Past the cap this gives up on
@@ -141,7 +141,7 @@ export function writeAll(fd, text) {
141
141
  return true;
142
142
  }
143
143
 
144
- // die() is writeSync, not console.error (#176/#328/#363). On a pipe,
144
+ // die() is writeSync, not console.error. On a pipe,
145
145
  // process.stderr.write is ASYNC and process.exit() discards whatever is
146
146
  // still queued — a large forwarded child stderr (gh's own) eats the refusal
147
147
  // line that follows it, because the refusal is queued last and dropped
@@ -158,9 +158,9 @@ export function makeDie(name) {
158
158
  // The try covers the TEMPLATE as well as the write, and that is the whole
159
159
  // of its job: uncaught, a throwing msg — or anything escaping writeAll —
160
160
  // skips process.exit(2) and drops the process to Node's default exit 1,
161
- // inverting the caller's own exit-code contract (#299/#328). Hoisting the
161
+ // inverting the caller's own exit-code contract. Hoisting the
162
162
  // string out to writeAll's argument list reintroduces precisely that,
163
- // which is why the pin in candidates.test.mjs requires it to sit inside.
163
+ // which is why a test pin requires it to sit inside.
164
164
  // writeAll's false return is ignored on purpose, and says no more than
165
165
  // this function always promised: the message may be lost, the exit code
166
166
  // may not.
@@ -173,7 +173,7 @@ export function makeDie(name) {
173
173
  };
174
174
  }
175
175
 
176
- // #61/#169: a flag given with no value must never read as the flag being
176
+ // A flag given with no value must never read as the flag being
177
177
  // absent. Every arg()-reading call site falls back with `||`/`??`, so a
178
178
  // trailing flag used to silently substitute a default — the malformed
179
179
  // invocation reading as a successful one.
@@ -183,19 +183,19 @@ export function makeDie(name) {
183
183
  // `--flag=value` form `indexOf` cannot see (`arg()` would otherwise report
184
184
  // the flag absent and the caller would fall back exactly as if it were).
185
185
  // Rejecting a `--`-prefixed value does forfeit a real capability — a value
186
- // that legitimately starts with `--` — and staleness.mjs (#238) is a caller
186
+ // that legitimately starts with `--` — and staleness.mjs is a caller
187
187
  // that can want one: its `--gone`/`--present` value is a string quoted out of
188
- // a ticket, and #240's is `--label ready-for-agent`. Refusing loudly here
188
+ // a ticket, such as `--label ready-for-agent`. Refusing loudly here
189
189
  // still beats silently taking the next flag as this one's value, so this
190
- // guard itself does not bend for it. staleness.mjs (#818) instead opts a
190
+ // guard itself does not bend for it. staleness.mjs instead opts a
191
191
  // caller in per flag with its own end-of-options separator, `--gone --
192
192
  // '<value>'`, read before arg() ever sees the value — bare, with no `--`
193
193
  // immediately before it, this refusal still stands unchanged.
194
- // #567: the two predicates immediately below ARE those rules, exported so a
194
+ // The two predicates immediately below ARE those rules, exported so a
195
195
  // caller that cannot route through arg()/has() consumes them instead of
196
196
  // copying the expression — the header above says which callers and why.
197
197
  // isDigits(), further down, is a third export on the same terms for a
198
- // different rule (#878); these two are the ones this paragraph is about.
198
+ // different rule; these two are the ones this paragraph is about.
199
199
  //
200
200
  // What travels is the RULE, never the refusal text: each caller keeps its own
201
201
  // die() wording, which is the constraint that made copying look necessary in
@@ -204,7 +204,7 @@ export function makeDie(name) {
204
204
  // flag they typed and not the grammar behind it.
205
205
  //
206
206
  // Plain exports, not factories, because neither takes a script NAME — one is a
207
- // predicate over a value, the other over an argv. That is also why #467's
207
+ // predicate over a value, the other over an argv. That is also why a
208
208
  // proposed makeCli(NAME) collapse of makeDie/makeArg/makeHas cannot absorb
209
209
  // them whichever way it lands: those three exist to BIND a name, and these
210
210
  // have no name to bind.
@@ -237,7 +237,7 @@ export function makeArg(die) {
237
237
  };
238
238
  }
239
239
 
240
- // #364: a boolean flag written --name=value must refuse, not read as
240
+ // A boolean flag written --name=value must refuse, not read as
241
241
  // absent — same fail-open class as arg()'s `=` guard above, but
242
242
  // boolean-specific wording: there is no value to take, so "needs a
243
243
  // space-separated value" would lie.
@@ -248,7 +248,7 @@ export function makeHas(die) {
248
248
  };
249
249
  }
250
250
 
251
- // #878: the digits rule, stated once. #840 closed a non-numeric `--pr` in
251
+ // The digits rule, stated once. A non-numeric `--pr` was first closed in
252
252
  // ci-state.mjs alone, and the identical shape stayed live in its siblings.
253
253
  // Measured on the pre-fix tree against a stub `gh` that ANSWERS, the way a
254
254
  // real one does for a branch ref: `diff-stats.mjs --pr abc` reached
@@ -266,13 +266,14 @@ export function makeHas(die) {
266
266
  // payload field. Its members are ci-state.mjs, diff-stats.mjs and
267
267
  // pr-overlap.mjs, and all three now route through numArg() below. A sweep for
268
268
  // the flag NAME finds two of the three, which is how the third stayed open
269
- // through #840's review.
269
+ // through that first fix's review.
270
270
  //
271
271
  // Stated here rather than a third time at the call sites, because the
272
272
  // invariant had no single expression: ci-state.mjs spelled it `/^[0-9]+$/`
273
273
  // while fleet-tick.mjs's int() spells it `/^\d+$/` over a parseArgs value,
274
- // each with its own wording. #367 overturned #169's "no shared module" ruling
275
- // to stop exactly this drift, and a fourth spelling IS the drift.
274
+ // each with its own wording. This shared module exists, over an earlier "no
275
+ // shared module" ruling, to stop exactly this drift, and a fourth spelling IS
276
+ // the drift.
276
277
 
277
278
  // `+`, so the empty string is not a number. arg() already refuses that value
278
279
  // through isFlagLike, but this predicate's other consumers do not read argv
@@ -300,7 +301,7 @@ export function makeHas(die) {
300
301
  // this same invariant (claim-ticket.sh, inflight.sh, release-ticket.sh,
301
302
  // drop-merged-label.sh) carries an extra `0?*` clause that refuses them, and
302
303
  // this rule deliberately does not adopt it — tightening here would refuse a
303
- // `--pr 007` that #840's shipped guard accepts, which is a behaviour change
304
+ // `--pr 007` that the already-shipped guard accepts, which is a behaviour change
304
305
  // dressed as a de-duplication.
305
306
  //
306
307
  // A plain export rather than a factory, for the reason isFlagLike and
@@ -322,8 +323,9 @@ export function isDigits(value) {
322
323
  // header's "what travels is the RULE, never the refusal text", applied to a
323
324
  // product whose two refusals genuinely differ in that respect.
324
325
  //
325
- // This also discharges #840's placement rule structurally instead of
326
- // positionally. That guard had to sit BELOW ci-state.mjs's usage die because
326
+ // This also discharges the original ci-state.mjs guard's placement rule
327
+ // structurally instead of positionally. That guard had to sit BELOW
328
+ // ci-state.mjs's usage die because
327
329
  // RegExp.test coerces `null` to "null": hoisted above it, an omitted `--pr`
328
330
  // was answered with a complaint about a number and the usage line never
329
331
  // printed. numArg() only ever tests a value it actually read, so the refusal
@@ -343,14 +345,15 @@ function readNum(die, arg, name) {
343
345
  return Number(raw);
344
346
  }
345
347
 
346
- // #365: the guards above all answer "was this flag given well?", and none of
348
+ // The guards above all answer "was this flag given well?", and none of
347
349
  // them can answer "was a flag given that nothing reads?". A MISSPELLED name is
348
350
  // simply never looked for, so `ci-state.mjs --pr 5 --basee main` computed a
349
351
  // real verdict against the DEFAULT base and exited 0/1 with no refusal — the
350
- // same fail-open harm as #61/#169, reached from the other side: not an absent
351
- // value, an unread flag. It bites hardest where the caller is markdown re-read
352
- // by a model each run (ci-state.mjs, candidates.mjs), and #173 already recorded
353
- // one landing: a doc naming `--label` where the flag is `--require-label`.
352
+ // same fail-open harm as a valueless flag reading as absent, reached from the
353
+ // other side: not an absent value, an unread flag. It bites hardest where the
354
+ // caller is markdown re-read by a model each run (ci-state.mjs,
355
+ // candidates.mjs), and one landing is already on record: a doc naming
356
+ // `--label` where the flag is `--require-label`.
354
357
  //
355
358
  // Only `--`-prefixed tokens are its business. Everything else is positional and
356
359
  // is not — board.mjs's `build`/`serve` subcommands, and every valued flag's
@@ -358,7 +361,7 @@ function readNum(die, arg, name) {
358
361
  // above refuses `--base --other` outright, so there is nothing to skip over and
359
362
  // no need to know here which names take a value.
360
363
  //
361
- // #463: that leftover class — a bare or single-dash token nothing reads,
364
+ // That leftover class — a bare or single-dash token nothing reads,
362
365
  // `ci-state.mjs --pr 42 basee main` or `-basee` — is not this function's fix,
363
366
  // and stays out of scope here for the same reason board.mjs's subcommands are:
364
367
  // this sweep still refuses ONLY a `--`-prefixed token, unchanged.
@@ -384,7 +387,7 @@ function readNum(die, arg, name) {
384
387
  // needs a value"; both exit 2, both name a real error, both refuse before gh.
385
388
  //
386
389
  // candidates.mjs deliberately does NOT route through this. It accepts no
387
- // positionals, so its parseArgs (#173) additionally refuses a bare
390
+ // positionals, so its parseArgs additionally refuses a bare
388
391
  // `candidates.mjs ready-for-agent` — which this cannot, board.mjs's
389
392
  // subcommands being exactly that shape. Strictly stronger there; leave it.
390
393
  //
@@ -393,9 +396,9 @@ function readNum(die, arg, name) {
393
396
  // DATA — `check
394
397
  // "--require-file silently absent when value missing"` works today and is the
395
398
  // shape of issue titles in this repo — so this sweep would refuse working
396
- // invocations, which #365's own AC calls worse than the bug. #584 NARROWED
397
- // that gap without routing through this sweep, rather than closing it, and
398
- // #1161 narrowed it again: ledger.mjs's own refuseStrayInCheckTail() is read on
399
+ // invocations, which is worse than the bug. ledger.mjs NARROWED that gap
400
+ // without routing through this sweep, rather than closing it, and later
401
+ // narrowed it again: ledger.mjs's own refuseStrayInCheckTail() is read on
399
402
  // `check`'s tail ALONE, and refuses a `--`-prefixed token there only when it
400
403
  // shares that tail with something else — the shape an unquoted stray flag
401
404
  // makes, never the shape a one-argument subject makes — so a subject that
@@ -405,7 +408,7 @@ function readNum(die, arg, name) {
405
408
  // tracker query, so `the --basee flag is unread` is queried as `unread basee
406
409
  // flag`.
407
410
  //
408
- // #1744 widened refuseStrayInCheckTail() again, past `--`-prefixed tokens: it
411
+ // refuseStrayInCheckTail() was widened again, past `--`-prefixed tokens: it
409
412
  // also refuses a bare ONE-dash spelling of ledger.mjs's own flag names
410
413
  // (`-require-file` for `--require-file`), matched by name rather than
411
414
  // prefix, still only when the tail carries something besides it. ledger.mjs
@@ -414,13 +417,13 @@ function readNum(die, arg, name) {
414
417
  //
415
418
  // `check` alone, on a documented-convention test that ledger.mjs states once
416
419
  // on refuseStrayInCheckTail() itself, with the docs and the measurement behind
417
- // it (#1161) — not restated here, and not restated at its call site either.
420
+ // it — not restated here, and not restated at its call site either.
418
421
  // What guards the other three instead is ledger.mjs's refuseStrayInId(), a
419
422
  // bare prefix test on the id slot ahead of the tail, where a `--` token is
420
423
  // never data.
421
424
  //
422
425
  // It is the LENGTH gate that spares the legitimate case, not the prefix test
423
- // — refuseStrayInId()'s id-slot prefix test is now `startsWith("-")` (#1678),
426
+ // — refuseStrayInId()'s id-slot prefix test is now `startsWith("-")`,
424
427
  // no longer the same one this sweep uses (`startsWith("--")`). The id slot
425
428
  // can take the stricter single-dash test because no free text ever lives
426
429
  // there — a legitimate id is bare digits, optionally `#`-prefixed. This
@@ -429,10 +432,10 @@ function readNum(die, arg, name) {
429
432
  // above can't either. A prefix test with no length gate was measured
430
433
  // refusing the legitimate subject.
431
434
  //
432
- // #584 does not make this file's cost disappear; it buys a smaller version of
435
+ // That narrowing does not make this file's cost disappear; it buys a smaller version of
433
436
  // the same cost. An unquoted subject carrying a `--` word is a working
434
437
  // invocation ledger.mjs's `check` now refuses too: `check the --basee flag is
435
- // unread` answered at exit 0 before #584 and exits 2 after it. The residual
438
+ // unread` answered at exit 0 before that narrowing and exits 2 after it. The residual
436
439
  // that stays open and owned is a lone stray with no subject beside it, still
437
440
  // taken as the subject, which ledger.mjs's own comment prices.
438
441
  function refuseUnknown(die, known) {
@@ -443,19 +446,19 @@ function refuseUnknown(die, known) {
443
446
  }
444
447
  }
445
448
 
446
- // #463: sweep() above only ever refuses a `--`-prefixed token — deliberately,
449
+ // sweep() above only ever refuses a `--`-prefixed token — deliberately,
447
450
  // per its own comment, because staying ignorant of which names take a value
448
451
  // is what keeps it from having to refuse board.mjs's `build`/`serve` or any
449
452
  // flag's own value. That leaves the OTHER half of "was a flag given that
450
453
  // nothing reads?" open: a bare word or a single dash, which sweep's
451
454
  // `startsWith("--")` check was never going to catch — `ci-state.mjs --pr 42
452
455
  // basee main` runs the compare against the DEFAULT base and reports a real,
453
- // wrong verdict at exit 0/1, the same fail-open harm as #365 reached from the
454
- // positional side rather than the misspelled-flag side. `-basee` is the
456
+ // wrong verdict at exit 0/1, the same fail-open harm sweep() closes, reached
457
+ // from the positional side rather than the misspelled-flag side. `-basee` is the
455
458
  // likelier typo of the two, since the caller plainly meant a flag.
456
459
  //
457
- // Widening sweep's own bound past `--` cannot fix this — #365's triage ruling
458
- // is explicit that the sweep must never refuse tokens outside it, and
460
+ // Widening sweep's own bound past `--` cannot fix this — the sweep is ruled
461
+ // never to refuse tokens outside that bound, and
459
462
  // board.mjs's subcommands are exactly the shape a widened sweep would catch
460
463
  // by mistake. Nor can `startsWith("-")`: it refuses a legitimate negative
461
464
  // value such as `--spend-since -1`, which arg() accepts today. The only way
@@ -495,7 +498,7 @@ function refuseStrays(die, flags, positionals) {
495
498
  }
496
499
  }
497
500
 
498
- // #1077: ONE declaration of a script's flags, and every reader bound to it.
501
+ // ONE declaration of a script's flags, and every reader bound to it.
499
502
  // `flags` maps each name to "value" or "bool"; `positionals` is the grammar
500
503
  // refuseStrays() above accepts ahead of the flags (board.mjs's
501
504
  // `build`/`serve`). One key per flag, so a name cannot be declared both ways.
@@ -526,7 +529,7 @@ function refuseStrays(die, flags, positionals) {
526
529
  // That refusal goes through die() at exit 2, never a thrown Error: exit 1 is
527
530
  // a verdict in ci-state.mjs (not green), merge-gate.mjs (blocked) and
528
531
  // tier-roles.mjs (check failed), which is the inversion makeDie() exists to
529
- // prevent (#299/#328). It is worded `bug:` because only the script's own
532
+ // prevent. It is worded `bug:` because only the script's own
530
533
  // source can reach it — no command line can make a correct table disagree
531
534
  // with a correct read.
532
535
  //
@@ -540,7 +543,7 @@ function refuseStrays(die, flags, positionals) {
540
543
  // the needle.
541
544
  //
542
545
  // The TABLE, by contrast, is copied once here, before anything derives from
543
- // it (#2114): sweep() takes its names at construction while the other readers
546
+ // it: sweep() takes its names at construction while the other readers
544
547
  // look a name up per call, so a caller mutating its own `flags` object
545
548
  // afterwards would leave arg() accepting a name sweep() refuses. With the
546
549
  // copy, no reader sees a later mutation, and no kind the construction check
@@ -548,10 +551,10 @@ function refuseStrays(die, flags, positionals) {
548
551
  // object stays its own, unchanged — the line gitEnv() in git-env.mjs holds
549
552
  // for its caller's `base` too.
550
553
  //
551
- // #2172 review: `flags` not being a plain object at all — `null`, or absent
554
+ // `flags` not being a plain object at all — `null`, or absent
552
555
  // because a caller typed `{ flag: {...} }` instead of `{ flags: {...} }` and
553
556
  // this destructures it to `undefined` — used to throw a TypeError straight
554
- // out of `Object.keys(undefined)`, before #2114 introduced the copy below.
557
+ // out of `Object.keys(undefined)`, before the copy below was introduced.
555
558
  // `{ ...undefined }` and `{ ...null }` both spread to `{}` without
556
559
  // complaint, so the copy would otherwise turn a loud construction-time crash
557
560
  // into a silently empty flag table whose every read fails later, elsewhere,
@@ -19,8 +19,8 @@
19
19
  // reduction that did not apply, a capped result). 3 = the query succeeded,
20
20
  // returned at least one row, and every row was removed by the to-spec
21
21
  // filter — distinct from 1 so a caller such as run-team's phase 0 can say
22
- // "the only labeled items are specs, run to-tickets" instead of "no work"
23
- // (#64). Exit 3 describes the FINAL query attempt only — with
22
+ // "the only labeled items are specs, run to-tickets" instead of "no work".
23
+ // Exit 3 describes the FINAL query attempt only — with
24
24
  // `--allow-fallback`, a labeled all-specs pass that falls back to a
25
25
  // genuinely empty unfiltered pass is exit 1, not 3; the drop count is never
26
26
  // carried across the two attempts.
@@ -32,7 +32,7 @@ import { makeDie, makeArg, makeHas } from "./arg.mjs";
32
32
  const NAME = "candidates";
33
33
 
34
34
  // die()/arg()/has() shared with the other fleet scripts — see arg.mjs for
35
- // the fail-open (#61/#169/#364) and pipe-safety (#176/#328/#363) rationale.
35
+ // the fail-open and pipe-safety rationale.
36
36
  // No caller of THIS file is a hand-typed CLI. Two are markdown re-read by a
37
37
  // model each run (next-ticket/SKILL.md, run-team/SKILL.md), which is why a
38
38
  // malformed invocation is more plausible here than the shared guard's shape
@@ -54,14 +54,14 @@ const limit = Number(arg("limit") ?? 500);
54
54
  if (!Number.isInteger(limit) || limit < 1) die(`--limit must be a positive integer, got '${arg("limit")}'`);
55
55
 
56
56
  // The accepted flag set, declared once, and the only check on flag NAMES.
57
- // Nothing checked them until #173: an unrecognised flag was ignored, so
57
+ // Before this check, an unrecognised flag was ignored, so
58
58
  // `--label ready-for-agent` — the spelling run-team's own phase 0 rule carried
59
59
  // — ran the UNFILTERED query at exit 0, the widening `--require-label` exists
60
60
  // to prevent.
61
61
  //
62
62
  // Runs BELOW the value guards, deliberately: where both would refuse — notably
63
63
  // `--require-label` and `--limit` given with no value — arriving second leaves
64
- // the refusal to #169's wording above rather than Node's. Nothing above emits
64
+ // the refusal to arg()'s wording above rather than Node's. Nothing above emits
65
65
  // output or runs a query, so refusing this late is still refusing before gh.
66
66
  //
67
67
  // The catch is unconditional, and THAT is the guard. Testing `e.code` for
@@ -96,8 +96,9 @@ try {
96
96
 
97
97
  if (allowFallback && !requireLabel) die("--allow-fallback is meaningless without --require-label");
98
98
 
99
- // #175's other half, and the half the fix below newly makes possible: the
100
- // label is QUOTED into the search term, so a `"` inside it closes that quote
99
+ // The label quoting's other half, and the half that quoting (query() below)
100
+ // newly makes possible: the label is QUOTED into the search term, so a `"`
101
+ // inside it closes that quote
101
102
  // early and the remainder becomes free text — the same misparse, with the fix
102
103
  // applied. A `\` breaks the same term from the other side, because GitHub
103
104
  // DOES honour `\"` as an escaped quote inside a qualifier: measured against
@@ -108,7 +109,7 @@ if (allowFallback && !requireLabel) die("--allow-fallback is meaningless without
108
109
  // having eaten the closing quote and swallowed the whole following qualifier.
109
110
  // Doubling does not escape it. Here the label term is LAST, so a trailing
110
111
  // backslash leaves its value unterminated and the query answers zero rows at
111
- // HTTP 200, no error — #175's silent empty, with the fix applied. Neither
112
+ // HTTP 200, no error — the unquoted label's silent empty, with the fix applied. Neither
112
113
  // character can be represented, so refuse both at exit 2 ("the query broke")
113
114
  // rather than send a query whose empty answer would read as exit 1.
114
115
  if (requireLabel && /["\\]/.test(requireLabel)) die(`--require-label cannot contain a double quote or a backslash, got '${requireLabel}'`);
@@ -117,7 +118,7 @@ if (requireLabel && /["\\]/.test(requireLabel)) die(`--require-label cannot cont
117
118
  // GitHub's search has no `-label:"wayfinder:*"` — and none is quoted despite
118
119
  // the colon each value carries. Measured 2026-09-08 against feigi/fleet-plugin:
119
120
  // negating `wayfinder:map` alone excludes exactly one more issue than the
120
- // unfiltered open count, and that issue is #1292 — a colon inside a label
121
+ // unfiltered open count — a colon inside a label
121
122
  // value is parsed as part of the label, not as a delimiter that ends it early
122
123
  // and spills the remainder into free text, the failure mode `label:"…"`
123
124
  // quoting exists for a SPACE (see `query()`'s comment below). Stated as a
@@ -133,7 +134,7 @@ const EXCLUDE =
133
134
  "-label:in-progress -label:onhold -label:wontfix -label:needs-triage -label:needs-info -label:wayfinder:map -label:wayfinder:research -label:wayfinder:prototype -label:wayfinder:grilling -label:wayfinder:task";
134
135
  // `d` walks the body line by line rather than one regex over the whole
135
136
  // string, because RE2 (gojq's engine — gh applies `--jq` with gojq, not the
136
- // system jq this file's own tests stub; see #63) has no lookahead, so
137
+ // system jq this file's own tests stub) has no lookahead, so
137
138
  // "capture every ref up to the next heading" cannot be expressed as a single
138
139
  // pattern. A heading line (`^#{1,6}[ \t]`) toggles a running "inside a
139
140
  // blocking section" flag on when its text DECLARES one: any of the verb
@@ -144,15 +145,15 @@ const EXCLUDE =
144
145
  // `:` aside. The noun form cannot be given the verb forms' tolerance:
145
146
  // `## Dependency injection` is an ordinary section title in a code repo, and
146
147
  // arming on it would turn every `#N` in its bullets into a blocker the body
147
- // never declared (#439 — the noun form is the heading #208's brief used, and
148
- // the gate named the verbs alone, so that section opened nothing).
148
+ // never declared. The noun form cannot be dropped either: a real brief headed
149
+ // its section with it, and a gate naming the verbs alone opened nothing there.
149
150
  //
150
151
  // Either form may carry EMPHASIS, which markdown puts outside the words:
151
152
  // `## **Dependencies**` names a dependency exactly as `## Dependencies` does,
152
153
  // and read without the `\*` runs it armed no section at all, so every ref its
153
- // bullets declared was dropped — exit 0, nothing on stderr, #439's silent
154
+ // bullets declared was dropped — exit 0, nothing on stderr, a silent
154
155
  // wrong admission reached through this gate rather than through the inline
155
- // label separator #439 widened (#1031). The runs are
156
+ // label separator. The runs are
156
157
  // `\**` rather than `\*{0,2}` because `*`, `**` and `***` are all emphasis a
157
158
  // heading is written with, and the noun form needs one on EACH side of its
158
159
  // optional colon: markdown closes the bold before it (`**Dependencies**:`)
@@ -162,8 +163,7 @@ const EXCLUDE =
162
163
  // the runs go AROUND it, and they match asterisks ONLY, so
163
164
  // `## **Dependency injection**` still arms nothing. Widen either run to a
164
165
  // general wildcard and that heading arms, which is the whole distinction the
165
- // anchor exists to hold; candidates.test.mjs pins both directions, on both
166
- // engines.
166
+ // anchor exists to hold; a test pins both directions, on both engines.
167
167
  //
168
168
  // `after` is an inline label only, because `## After the migration` is
169
169
  // ordinary narrative and arming on it invents a blocker, while a heading that
@@ -182,7 +182,7 @@ const EXCLUDE =
182
182
  // match. The separator is a combined `[\s*]*` run rather than asterisk groups
183
183
  // flanking the colon: those groups sat ahead of the separating whitespace, so
184
184
  // they matched only asterisks flush against the phrase, and a space before the
185
- // bold — where markdown actually puts it — dropped the ref (#439). Both passes
185
+ // bold — where markdown actually puts it — dropped the ref. Both passes
186
186
  // are strictly line-local, which the removed `(?:depends on|…)\s+#\d+` regex
187
187
  // was not: its `\s+` crossed newlines, so a
188
188
  // phrase ending one line with its ref opening the next was collected and now
@@ -192,20 +192,20 @@ const EXCLUDE =
192
192
  // restriction above closes. A ref elsewhere in the body — not under a
193
193
  // heading section, not after a label — is not collected: neither pass reaches
194
194
  // it. Verified against real gojq (`go install
195
- // github.com/itchyny/gojq/cmd/gojq@v0.12.19`) on every form in
196
- // candidates.test.mjs's dependency-forms fixtures, not only the system jq the
195
+ // github.com/itchyny/gojq/cmd/gojq@v0.12.19`) on every form in the
196
+ // suite's dependency-forms fixtures, not only the system jq the
197
197
  // STUB there execs. The engines now agree on every one of those forms,
198
198
  // including the ones that used to split. The separator is `[\t \p{Zs}*]*`
199
199
  // and not `[\s*]*`, so `Blocked by:<U+00A0>#12` collects `[12]` under BOTH
200
200
  // engines where it used to collect `[12]` under Oniguruma and `[]` under RE2
201
- // — #383 ruled the ref a real blocker, because GFM renders that line as
201
+ // — the ref is ruled a real blocker, because GFM renders that line as
202
202
  // `Blocked by: #12` and autolinks the ref, so a reader sees a dependency and
203
203
  // an admission gate must not miss one. Since no fixture splits any more, the
204
204
  // gated tests can no longer identify their engine by disagreement: the STUB
205
205
  // records which binary it executed and they assert that recording is gojq.
206
206
  // The per-position rulings are set out above the JQ declaration below.
207
207
  //
208
- // `depmiss` is the diagnostic half (#1032), and it is deliberately LOOSER
208
+ // `depmiss` is the diagnostic half, and it is deliberately LOOSER
209
209
  // than the gate: any heading MENTIONING the concept that the gate did not
210
210
  // arm. The gate's own pattern is named `armed` and both halves call it, so
211
211
  // "did not arm" is the exact complement of what opened the section rather
@@ -234,10 +234,10 @@ const EXCLUDE =
234
234
  // because the only whitespace that would disturb the line this prints is the
235
235
  // CR of a CRLF body (what GitHub's web textarea writes), and a regex there
236
236
  // would buy cosmetics at the price of one more regex position to rule on and
237
- // keep portable (#383). `dh` never reaches stdout: the payload is stripped of it
238
- // at the `JSON.stringify` below, because this is a stderr signal and #1032
239
- // rules a payload field out of scope.
240
- // ENGINE-PORTABLE CLASSES (#383). The program below contains no `\\s`, `\\d` or
237
+ // keep portable. `dh` never reaches stdout: the payload is stripped of it
238
+ // at the `JSON.stringify` below, because this is a stderr signal and a
239
+ // payload field is ruled out of scope.
240
+ // ENGINE-PORTABLE CLASSES. The program below contains no `\\s`, `\\d` or
241
241
  // `\\b`: every position spells an explicit class. It has to, because the suite
242
242
  // applies this expression with system jq (Oniguruma, all three Unicode-aware)
243
243
  // while gh applies it with its embedded gojq (Go RE2, where `\\s` is
@@ -267,7 +267,7 @@ const EXCLUDE =
267
267
  // Unlike `armed`/`depmiss` above, this one also has to recognize a
268
268
  // BARE marker-only heading — no title text follows, so `[ \t]` alone
269
269
  // never matches it, and the old open section wrongly kept collecting
270
- // refs past it (#383 over-collection). GFM still renders a bare `##`
270
+ // refs past it (over-collection). GFM still renders a bare `##`
271
271
  // as a real (empty) `<h2>`, so it must still close the section: `$`
272
272
  // admits end-of-line, `\r?` admits the same position just before a
273
273
  // CRLF line's trailing `\r` (the one `split("\n")` leaves behind).
@@ -307,18 +307,18 @@ const EXCLUDE =
307
307
  // escaping below — jq's `\\p{Zs}` is `\\\\p{Zs}` in this JS source string.
308
308
  //
309
309
  // Measured over 24 fixtures on jq-1.7.1-apple and gojq 0.12.19: zero splits.
310
- // candidates.test.mjs pins the rows that used to split, on both engines, and
310
+ // The suite pins the rows that used to split, on both engines, and
311
311
  // proves which engine each gated test actually reached.
312
312
  //
313
- // NATIVE EDGES (#1741). `d` is the UNION of the body scan above and the
313
+ // NATIVE EDGES. `d` is the UNION of the body scan above and the
314
314
  // numbers on the issue's native "blocked by" edges, which ride the same
315
- // query as gh's `blockedBy` field — no extra round trip, the cost #58
316
- // deferred them on — merged and sorted by the final `unique`. Union, not
315
+ // query as gh's `blockedBy` field — no extra round trip, the cost they were
316
+ // once deferred on — merged and sorted by the final `unique`. Union, not
317
317
  // replacement: to-tickets still writes blockers only as body text, and a
318
318
  // hand-written body can name a blocker nobody wired as an edge, so dropping
319
319
  // the scan would silently un-block both. The edges close the opposite miss:
320
- // #593's body chains `**#531**` behind a parenthetical the scan cannot
321
- // cross, and only its native edge carries #531. `d` stays RAW — a closed
320
+ // a body can chain its blocker as `**#N**` behind a parenthetical the scan
321
+ // cannot cross, and then only the native edge carries it. `d` stays RAW — a closed
322
322
  // blocker's number is kept although the edge carries its state, exactly as
323
323
  // the scan keeps one, because the consumers (run-team / next-ticket step 2)
324
324
  // judge openness and a `d` whose two halves meant different things would
@@ -389,7 +389,7 @@ const JQ =
389
389
 
390
390
  function query(label) {
391
391
  // The label is a VALUE in GitHub's query language, not part of its syntax,
392
- // so it is quoted rather than interpolated raw (#175). Unquoted, a value
392
+ // so it is quoted rather than interpolated raw. Unquoted, a value
393
393
  // ends at the FIRST SPACE and every word after it becomes a free-text term
394
394
  // instead — measured 2026-08-17, `label:ready-for-agent candidates` returns
395
395
  // strictly fewer issues here than `label:ready-for-agent`, and on
@@ -398,7 +398,7 @@ function query(label) {
398
398
  // the narrowed result as the label's own answer, and an empty one as exit 1,
399
399
  // "the query worked and there is no work" — against a queue that is not
400
400
  // empty. Reachable wherever a repo remapped its triage labels, which
401
- // docs/agents/triage-labels.md exists to invite. Stated as relationships
401
+ // a per-repo triage-label mapping exists to invite. Stated as relationships
402
402
  // rather than counts on purpose: the queue churns hourly, so a pinned digit
403
403
  // is wrong within a day and reads as the fix having regressed.
404
404
  //
@@ -511,7 +511,7 @@ function refuseIfCapped(rows, description) {
511
511
  // worth a fence parser: every drop is logged by number, so a false positive is
512
512
  // loud rather than silent.
513
513
  //
514
- // #65: two shapes the predicate leaves undecided by accident, now decided.
514
+ // Two shapes the predicate leaves undecided by accident, now decided.
515
515
  // Depth is `#{2,6}`, not `##` — two or more `#`, not exactly two, and capped
516
516
  // where CommonMark caps an ATX heading, same as `depnums`' own `#{1,6}` above:
517
517
  // a line of seven `#` is not a heading and must not read as the signature.
@@ -526,7 +526,7 @@ function refuseIfCapped(rows, description) {
526
526
  // tagged). The separator between marker and text is `[ \t]+` — horizontal
527
527
  // whitespace only, not `\s+` — so a heading can never span a line break: a
528
528
  // body whose line is exactly `##` with `User Stories` starting the next
529
- // line no longer reads as the same heading. That is also #383's ruling for
529
+ // line no longer reads as the same heading. That is also the ruling for
530
530
  // this position, on GFM's own rule: only a space or a tab opens a heading, so
531
531
  // `##<U+00A0>User Stories` renders as a PARAGRAPH and is not a spec at all.
532
532
  //
@@ -538,7 +538,7 @@ function refuseIfCapped(rows, description) {
538
538
  // the `\r` of a CRLF body — what GitHub's web textarea writes — and leak that
539
539
  // spec silently. It is spelled out rather than left as `\s*` because `\s` is
540
540
  // the one construct here whose meaning changes with the engine (Oniguruma
541
- // reads it Unicode-aware, RE2 as `[\t\n\f\r ]`), and #383 ruled the position
541
+ // reads it Unicode-aware, RE2 as `[\t\n\f\r ]`), and the position is ruled
542
542
  // by what GFM renders: `## User Stories` padded with U+00A0, EM SPACE or
543
543
  // IDEOGRAPHIC SPACE are all real `<h2>`s, so all three are still to-spec specs
544
544
  // and all three are dropped. `\p{Zs}` is exactly "renders as a blank" and both
@@ -548,8 +548,8 @@ function refuseIfCapped(rows, description) {
548
548
  // is not dropped. Before the ruling this position diverged — a U+00A0-padded
549
549
  // heading was a spec under the system jq the suite execs and NOT one under the
550
550
  // gojq gh applies, so in production dropSpecs never fired and the spec shipped
551
- // as a claimable ticket. Pinned against real gojq in candidates.test.mjs,
552
- // which now also pins which engine it reached.
551
+ // as a claimable ticket. Pinned against real gojq by a test that also pins
552
+ // which engine it reached.
553
553
  //
554
554
  // This is the ONLY line of defence — nothing downstream catches a spec. A
555
555
  // leaked one is decided and needs no human hands, so it passes both of phase
@@ -561,7 +561,7 @@ function refuseIfCapped(rows, description) {
561
561
  // unfiltered query is a SUPERSET of the labeled one, and every spec dropped in
562
562
  // pass 1 is dropped again in pass 2. Unattributed, that reads as the same spec
563
563
  // counted twice; named, a reader can tell "2 drops, 1 spec, seen both passes"
564
- // from "2 drops, 2 specs" at a glance. Deliberately not deduplicated — #133.
564
+ // from "2 drops, 2 specs" at a glance. Deliberately not deduplicated.
565
565
  function dropSpecs(rows, pass) {
566
566
  const kept = [];
567
567
  for (const { spec, ...rest } of rows) {
@@ -582,13 +582,13 @@ refuseIfCapped(rows, requireLabel ? ` with label:${requireLabel}` : "");
582
582
  // After refuseIfCapped, never before: filtering first can shrink the array below
583
583
  // `limit` and the cap check would stop seeing a truncated list. Before the
584
584
  // emptiness test below, never after: a queue whose every row was filtered out
585
- // IS an empty queue — see #60. Telling that case apart from a genuinely empty
586
- // one, for a caller reading only the exit code, is #64 — closed by exit 3 at
585
+ // IS an empty queue. Telling that case apart from a genuinely empty
586
+ // one, for a caller reading only the exit code, is exit 3's job — set at
587
587
  // the foot of this file, which is what the raw count below is captured for.
588
588
  // Raw count captured just before the filter that can empty `rows` out, so
589
589
  // `allFilteredOut` below can tell "nothing came back" from "rows came back
590
590
  // and the filter ate them all". Reassigned wholesale in the fallback branch,
591
- // never OR'd/summed with pass 1's value — #64's edge case is exactly a pass 1
591
+ // never OR'd/summed with pass 1's value — exit 3's edge case is exactly a pass 1
592
592
  // all-filtered (raw>0) whose fallback pass is genuinely empty (raw=0), which
593
593
  // must read as the fallback's own facts (exit 1), not a merge of the two.
594
594
  const rawCount1 = rows.length;
@@ -614,7 +614,7 @@ if (rows.length === 0 && allowFallback && requireLabel) {
614
614
  // next-ticket step 2), not here, and to-tickets publishes chains blockers-first
615
615
  // so lower numbers are the blockers anyway. `d` covers every body form
616
616
  // to-tickets publishes — heading + list, bold/inline label, the original bare
617
- // phrasings — see #58, and GitHub's native blocked-by edges too (#1741), so
617
+ // phrasings — and GitHub's native blocked-by edges too, so
618
618
  // a chain wired only as edges reaches this sort with its blockers in `d`.
619
619
  // Native sub-issue links are still not read: parent/child is hierarchy, not
620
620
  // blocking, so a blocker recorded only as one reaches it with none.
@@ -622,7 +622,7 @@ rows.sort((a, b) => a.n - b.n);
622
622
 
623
623
  for (const r of rows) {
624
624
  console.error(` #${r.n} [${r.l.join(",")}] ${r.t}${r.d.length ? ` deps:${r.d.join(";")}` : ""}`);
625
- // #1032. A SECOND line, never a field on the row above: that row's format is
625
+ // A SECOND line, never a field on the row above: that row's format is
626
626
  // what phase 0 reads and it stays byte-identical, `deps:` suppressed on an
627
627
  // empty list and all. Indented under the row it belongs to, and repeating
628
628
  // `#N` so a reader who greps the wording still gets the candidate with it.
@@ -650,8 +650,8 @@ for (const r of rows) {
650
650
  //
651
651
  // `dh` is dropped here rather than never collected: the heading text exists
652
652
  // only inside gh's process, where the reduction runs, so the only way to it is
653
- // a field on the row — and #1032 rules a payload field out of scope, the
654
- // stderr signal being the whole of what it asks for. Here, and not in
653
+ // a field on the row — and a payload field is ruled out of scope, the
654
+ // stderr signal being the whole of what this diagnostic asks for. Here, and not in
655
655
  // `dropSpecs`' destructure where the row's other stderr-only field (`spec`)
656
656
  // leaves the payload: that runs BEFORE the per-candidate lines above, which
657
657
  // are what `dh` is for. A replacer, not a rebuilt array: it drops the key
@@ -662,7 +662,7 @@ console.log(JSON.stringify(rows, (k, v) => (k === "dh" ? undefined : v)));
662
662
 
663
663
  // Exit 1 for a successful query with no survivors, exit 3 when those zero
664
664
  // survivors are the filter's doing rather than the query's — see the
665
- // exit-code contract in the file header (#64). `allFilteredOut` already
665
+ // exit-code contract in the file header. `allFilteredOut` already
666
666
  // describes only the final attempt (see above), so no further branching on
667
667
  // requireLabel/allowFallback is needed here.
668
668
  //
@@ -2,37 +2,36 @@
2
2
  // two exports, one per half of the same spawn. `gitEnv()` builds the env the
3
3
  // git child is given; `workspaceDirFromGitCommonDir()` turns what the most
4
4
  // common of those children answers with, `rev-parse --git-common-dir`, into
5
- // the workspace directory a run's files live under. The first half is #1599's
6
- // reasoning, below; the second is #1658's, beside its own function.
5
+ // the workspace directory a run's files live under. The first half's
6
+ // reasoning is below; the second's sits beside its own function.
7
7
  //
8
8
  // GIT_DIR and GIT_WORK_TREE outrank both the child's cwd and an explicit `-C`
9
- // argument — measured directly (#1599): a `git rev-parse`/`ls-files` call
9
+ // argument — measured directly: a `git rev-parse`/`ls-files` call
10
10
  // pointed at a repository via `cwd` or `-C` still answers for whichever
11
11
  // repository an ambient GIT_DIR or GIT_WORK_TREE names, silently, often at
12
- // exit 0. #1020 closed the identical class in every shell script under this
13
- // directory with one line, `unset GIT_DIR GIT_WORK_TREE`; there is no shell
14
- // to unset in here, so the child's env has to be built instead — and #1020's
15
- // own EXEMPT reasons for net.sh/worktree.sh ("a library... unset there would
12
+ // exit 0. The shell scripts under this directory close the identical class
13
+ // with one line, `unset GIT_DIR GIT_WORK_TREE`; there is no shell to unset in
14
+ // here, so the child's env has to be built instead — and the reasons
15
+ // net.sh/worktree.sh are exempt from that line ("a library... unset there would
16
16
  // reach back into the caller's environment") do not transfer: a spawned
17
17
  // child's env object is already private to it, never the calling process's.
18
18
  //
19
19
  // `fleet-state.mjs`'s `statePath()` and `ledger.mjs`'s tracker-query probe
20
20
  // each spell the same three lines inline — `{ ...process.env }` then two
21
- // `delete`s — predating this module, and #1599's own body cites exactly that
22
- // duplication as the reason a THIRD hand-spelled copy (its own measured
23
- // hazard, `ledger.mjs`'s `defaultLedgerPath()`) should not become a fourth.
21
+ // `delete`s — predating this module, and that duplication is exactly the
22
+ // reason a THIRD hand-spelled copy (the hazard measured here, `ledger.mjs`'s
23
+ // `defaultLedgerPath()`) should not become a fourth.
24
24
  // A shared helper also turns "does this call scrub the ambient vars" back
25
25
  // into a one-name grep, `gitEnv(`, the way `unset GIT_DIR GIT_WORK_TREE` is
26
- // one for shell — see `ambient-git-vars-mjs-prose.test.mjs`.
26
+ // one for shell.
27
27
  //
28
28
  // The two pre-existing inline sites are deliberately NOT migrated to call
29
- // this. Neither is in #1599's scope — its own body excludes
30
- // `fleet-state.mjs`'s `statePath()` by name (already fixed and covered, by
31
- // PR #1598), and `ledger.mjs`'s tracker-query scrub is likewise already
32
- // measured and covered (`ledger.test.mjs`, "an inherited GIT_DIR or GH_REPO
33
- // cannot retarget the query…") — and touching either to satisfy a detector
34
- // would be churn with no behavioural change. `ambient-git-vars-mjs-prose.test.mjs`
35
- // carries both of them by name instead of by import.
29
+ // this. Both are already fixed and covered by tests of their own —
30
+ // `fleet-state.mjs`'s `statePath()`, and `ledger.mjs`'s tracker-query scrub
31
+ // ("an inherited GIT_DIR or GH_REPO cannot retarget the query…") — and
32
+ // touching either to satisfy a detector would be churn with no behavioural
33
+ // change. The suite's census of ambient-var scrubs carries both of them by
34
+ // name instead of by import.
36
35
 
37
36
  import { realpathSync } from "node:fs";
38
37
  import { dirname, resolve } from "node:path";
@@ -65,11 +64,11 @@ export function gitEnv(overrides = {}, base = process.env) {
65
64
  // from the checkout root agree about the run's single ledger, its single
66
65
  // heartbeat and its single board.
67
66
  //
68
- // Three callers hand-spelled that resolution, one apiece, before #1658:
67
+ // Three callers hand-spelled that resolution, one apiece, before this function:
69
68
  // `ledger.mjs`'s `defaultLedgerPath()`, `fleet-state.mjs`'s `statePath()` and
70
69
  // `board.mjs`'s `resolveCockpitInstance()` — and `fleet-state.mjs`'s own
71
70
  // comment had already written down the trigger ("if a third file ever needs
72
- // this, the resolution itself should move"), which #1656's addition tripped.
71
+ // this, the resolution itself should move"), which the third caller's arrival tripped.
73
72
  // What is NOT shared is the part each caller owns: the filename it joins on
74
73
  // (`ledger.md`, `heartbeat.json`, `.fleet`), the wording of the warning it
75
74
  // degrades with, and what its own degraded answer is. Hence the seam: this
@@ -100,9 +99,9 @@ export function gitEnv(overrides = {}, base = process.env) {
100
99
  * than a path; a trailing newline riding on a real answer would be discarded
101
100
  * by `dirname()` anyway, together with the rest of the final segment.
102
101
  *
103
- * `canonicalise` is OPT-IN, and deliberately so (#1658). Only `board.mjs`
102
+ * `canonicalise` is OPT-IN, and deliberately so. Only `board.mjs`
104
103
  * takes it: a symlinked route to one workspace derives a SECOND port and a
105
- * second state directory for a cockpit already being served (#1582), so the
104
+ * second state directory for a cockpit already being served, so the
106
105
  * cockpit's key has to be the canonical form. `ledger.mjs` and
107
106
  * `fleet-state.mjs` do not — both PRINT the path they resolve (the ledger in
108
107
  * `check`'s JSON, both in their degrade warnings), and realpath would change
@@ -7,21 +7,21 @@
7
7
  // with it. What the premise costs is a precondition: there has to be a `.git`
8
8
  // at or above the file. A checkout and a worktree both have one; a bare `git
9
9
  // archive` extraction does not. Review specialists used to measure the suite in
10
- // exactly such an extraction, which cost this repo 19 silent declines per run
11
- // (#1056); since that ticket the review snapshot is `git init`ed and committed
10
+ // exactly such an extraction, which cost this repo 19 silent declines per run;
11
+ // since then the review snapshot is `git init`ed and committed
12
12
  // at cut time, so the declines below are no longer the review's normal path.
13
13
  // They remain the answer for any OTHER repo-less tree — a hand-cut archive, a
14
14
  // tarball unpacked in CI — which is why the guard stays rather than becoming
15
15
  // dead weight.
16
16
  //
17
- // Before #1149 each file paid that cost as a bare module-scope `execFileSync`
17
+ // Before this module, each file paid that cost as a bare module-scope `execFileSync`
18
18
  // whose failure escaped. Node cannot attribute a throw during module
19
19
  // evaluation to any test, so it synthesised one entry at line 1 of the file and
20
20
  // the run showed a single failure in place of the file's real tests — a
21
21
  // diagnostic that reads like a regression in the tree under test rather than an
22
22
  // environment missing a repository.
23
23
  //
24
- // #1339 found the second way "there has to be a `.git`" is not the same
24
+ // There is a second way "there has to be a `.git`" is not the same
25
25
  // question as "there has to be THIS repository": git's discovery walk answers
26
26
  // with whatever working tree it finds first, and nothing about that answer
27
27
  // says it is fleet-plugin's own tree rather than an ambient repository the
@@ -33,11 +33,11 @@
33
33
  // through it.
34
34
  //
35
35
  // The first fix here compared the resolved root's OWN `.claude-plugin/
36
- // plugin.json` name against this file's — and #1354's review measured that a
36
+ // plugin.json` name against this file's — and a review measured that a
37
37
  // DIFFERENT checkout of this same plugin, sitting above some unrelated caller
38
38
  // directory, still passed: same name, wrong tree. The second fix required the
39
39
  // running script to be somewhere INSIDE the resolved root — and that review
40
- // measured it regresses #1339's OWN shape: pre-cutover, an installed copy
40
+ // measured it regresses the ambient-repository case's OWN shape: pre-cutover, an installed copy
41
41
  // under the harness's own plugin cache genuinely sat inside the operator's
42
42
  // dotfiles checkout, which was exactly the ambient repository the bug is about.
43
43
  // Containment is not identity either. What repoRoot now insists on is
@@ -46,10 +46,10 @@
46
46
  // must both be tracked by `root`'s OWN git (`git ls-files --error-unmatch`).
47
47
  // An installed plugin's cache directory sits inside the operator's dotfiles
48
48
  // checkout but is never committed there, so it fails; a real checkout, a
49
- // worktree, a `plugin/`-nested layout after #1336, and a vendored copy inside
49
+ // worktree, a `plugin/`-nested layout, and a vendored copy inside
50
50
  // a monorepo all pass, because in each of those the file genuinely IS part of
51
51
  // that repository's own tracked tree. The self-relative manifest lookup is
52
- // what survives #1336's planned re-nesting of the payload under `plugin/`: a
52
+ // what survived the payload's re-nesting under `plugin/`: a
53
53
  // hardcoded `root/.claude-plugin/plugin.json` breaks the moment the manifest
54
54
  // moves a level deeper, while `dirname(thisFile)/../.claude-plugin/
55
55
  // plugin.json` does not care where `root` (the git toplevel) ends up relative
@@ -68,14 +68,15 @@
68
68
  // binary at all. A repository may well be
69
69
  // present; what is missing is an answer. A
70
70
  // probe that could not look must never read as
71
- // an answer — that is #1149's own defect, and
72
- // buying a skip with it would reproduce it
73
- // inside its own fix. `repoRoot` THROWS here,
71
+ // an answer: buying a skip with it would
72
+ // reproduce that defect inside the guard
73
+ // written against it. `repoRoot` THROWS here,
74
74
  // which is the loud module-load failure the
75
- // pre-#1149 code produced for these.
75
+ // earlier bare-`execFileSync` code produced
76
+ // for these.
76
77
  // the root answers, but its identity, not non-emptiness, not name
77
78
  // own git does not TRACK this equality, and not mere containment either
78
- // file or this file's own (#1339, then #1354 twice): a root that
79
+ // file or this file's own (each measured failing): a root that
79
80
  // manifest merely names the same plugin, contains an
80
81
  // untracked copy, or answers non-empty for
81
82
  // some other reason, is still a stranger's
@@ -92,7 +93,7 @@
92
93
  // skipping; each caller's own non-vacuity
93
94
  // guard is what judges it. The
94
95
  // wrong-repository half of this used to live
95
- // here too, before #1339 moved it up into the
96
+ // here too, before it moved up into the
96
97
  // identity check above, where it can throw
97
98
  // loudly instead of waiting on each caller's
98
99
  // guard to notice.
@@ -131,9 +132,10 @@ const NO_REPOSITORY_ANYWHERE = /not a git repository \(or any /;
131
132
  * caller resolved. Relative to `cwd` would ask the wrong question, since
132
133
  * `cwd` is exactly the thing under test; relative to a resolved `root` would
133
134
  * have to guess how many levels separate the manifest from the git toplevel,
134
- * and #1336 is about to change that answer. This guesses nothing — wherever
135
- * this file is copied (a checkout, a worktree, an installed plugin cache, and
136
- * after #1336 a `plugin/` subdirectory), its own manifest is always exactly
135
+ * and the payload's re-nesting under `plugin/` already changed that answer
136
+ * once. This guesses nothing — wherever
137
+ * this file is copied (a checkout, a worktree, an installed plugin cache, or
138
+ * a `plugin/` subdirectory), its own manifest is always exactly
137
139
  * one directory up from it.
138
140
  */
139
141
  function ownManifestPath() {
@@ -180,7 +182,7 @@ export function ownPluginName() {
180
182
  * nearest the pathspec itself (measured: from an unrelated cwd, the same
181
183
  * absolute path is reported "outside repository at <that other repo>").
182
184
  *
183
- * GIT_DIR scrubbed (#1599, gitEnv()): measured, an ambient GIT_DIR answers
185
+ * GIT_DIR scrubbed (gitEnv()): measured, an ambient GIT_DIR answers
184
186
  * for a DIFFERENT repository regardless of `cwd` — `ls-files
185
187
  * --error-unmatch` on a path this file's OWN repository genuinely tracks
186
188
  * then exits 1 "did not match any file(s) known to git", a false negative
@@ -206,7 +208,7 @@ function isTrackedBy(root, path) {
206
208
  * than an ambient repository the caller's directory happened to nest under.
207
209
  *
208
210
  * Containment (is the running script somewhere INSIDE `root`?) was tried
209
- * first and is not enough — it regresses #1339's own measured shape. There,
211
+ * first and is not enough — it regresses the ambient-repository case's own measured shape. There,
210
212
  * pre-cutover, self was under the harness's own plugin cache at
211
213
  * `fleet-plugin/fleet/0.1.1/scripts/repo-root.mjs`, and `root` resolved to
212
214
  * that cache's own parent dotfiles directory, which genuinely CONTAINED self
@@ -218,7 +220,7 @@ function isTrackedBy(root, path) {
218
220
  * working tree is exactly as much a stranger as no copy at all. This also
219
221
  * accepts every tree that legitimately IS this file's own — this checkout, a
220
222
  * worktree, a
221
- * `plugin/`-nested layout after #1336, even a vendored copy inside a larger
223
+ * `plugin/`-nested layout, even a vendored copy inside a larger
222
224
  * monorepo — because in every one of those cases the file is actually
223
225
  * COMMITTED to that repository's index, which an ambient-but-unrelated
224
226
  * repository's cache directory never is.
@@ -286,13 +288,13 @@ function dotGitAtOrAbove(cwd) {
286
288
  *
287
289
  * A working tree that IS found is not returned on the strength of being
288
290
  * found — `assertOwnRoot` checks it is this plugin's own before it ever
289
- * reaches a caller (#1339). A non-empty wrong root throws exactly as loudly as
291
+ * reaches a caller. A non-empty wrong root throws exactly as loudly as
290
292
  * an unanswerable one; the old guard against it lived only in each caller's
291
293
  * non-vacuity check on `trackedShellScripts`, which a non-empty foreign
292
294
  * answer sailed straight through.
293
295
  */
294
296
  export function repoRoot(cwd) {
295
- // GIT_DIR/GIT_WORK_TREE scrubbed (#1599, gitEnv()): measured from a
297
+ // GIT_DIR/GIT_WORK_TREE scrubbed (gitEnv()): measured from a
296
298
  // subdirectory of a real working tree (the realistic shape — `cwd` here is
297
299
  // wherever the calling script happens to live, rarely the root itself) —
298
300
  // an ambient GIT_DIR alone answers `--show-toplevel` with `cwd` ITSELF, not
@@ -338,8 +340,8 @@ export function skipWithoutRepo(root, subject) {
338
340
  // file at the path, for any reader — rather than a failure to look: nothing
339
341
  // there at all (ENOENT); a file standing where one of the path's own
340
342
  // directories should be (ENOTDIR); and a symlink that loops, or chains past the
341
- // kernel's link limit (ELOOP), which no reader can ever open a file through
342
- // (#1950). `root` is git's own resolved toplevel, so every link counted toward
343
+ // kernel's link limit (ELOOP), which no reader can ever open a file through.
344
+ // `root` is git's own resolved toplevel, so every link counted toward
343
345
  // that limit is one inside the tracked path itself — a fact about the tree,
344
346
  // not about where the checkout sits.
345
347
  //
@@ -371,7 +373,7 @@ function isRegularFile(path) {
371
373
  * Every file tracked in the working tree at `root` that `pathspecs` match,
372
374
  * repo-relative — the one discovery rule behind all three exports below, so what
373
375
  * `root` must be and which repository answers cannot drift apart between
374
- * them (#1751). `caller` is the export's own name, for the refusal.
376
+ * them. `caller` is the export's own name, for the refusal.
375
377
  *
376
378
  * `root` must be a real root — call it only where `repoRoot` answered. A `null`
377
379
  * root is rejected rather than absorbed into an empty list: `execFileSync`
@@ -390,13 +392,13 @@ function isRegularFile(path) {
390
392
  * checked out on disk), a file standing where the path's own directory was.
391
393
  * Every caller reads each path it is handed, and one absent path in the answer
392
394
  * aborted that read with a raw ENOENT, leaving every real finding in every
393
- * other file unreported (#1910). Passing over it lets nothing ship unswept: a
395
+ * other file unreported. Passing over it lets nothing ship unswept: a
394
396
  * deletion that is committed does not ship, and one that is not is swept again
395
397
  * in any checkout that has the file; a link with no file behind it has no text
396
398
  * to sweep. A path the probe could not look at is not one of these — it
397
399
  * throws, as NO_REGULAR_FILE_THERE says.
398
400
  *
399
- * GIT_DIR scrubbed (#1599, gitEnv()): measured, an ambient GIT_DIR silently
401
+ * GIT_DIR scrubbed (gitEnv()): measured, an ambient GIT_DIR silently
400
402
  * substitutes a DIFFERENT repository's tracked list for `root`'s own — the
401
403
  * caller's non-vacuity guard cannot see this, since the wrong list is
402
404
  * routinely non-empty. GIT_WORK_TREE is inert here (measured, for `*.sh` and
@@ -465,7 +467,7 @@ const NODE_SHEBANG = /^#!\s*(?:\S*\/)?(?:env(?:\s+(?:-(?:u|-unset|C|-chdir)(?:=\
465
467
  const SHEBANG_BYTES = 256;
466
468
 
467
469
  // The most of a first line ever read, and the length at which one is not a
468
- // node shebang (#1941). Reading on to the end of the line however long read a
470
+ // node shebang. Reading on to the end of the line however long read a
469
471
  // tracked `#!` file holding no newline into memory whole to answer a boolean —
470
472
  // measured, 300 MiB of one peaked above 1.1 GiB, and one past the longest
471
473
  // string V8 builds (~512 MiB) threw ERR_STRING_TOO_LONG out of the whole
@@ -476,9 +478,10 @@ const SHEBANG_BYTES = 256;
476
478
  // Linux, on a prefix naming node — is one no author writes.
477
479
  //
478
480
  // A cap, not a verdict on the bytes before it: those are not judged at all,
479
- // so this is never the prefix verdict #1887 retired. Refused rather than
481
+ // so this is never a prefix verdict, the kind hasNodeShebang() refuses to
482
+ // give. Refused rather than
480
483
  // thrown, because one pathological tracked file must not abort every sweep's
481
- // listing (#1910); rather than listed, because a sweep reads each listed file
484
+ // listing; rather than listed, because a sweep reads each listed file
482
485
  // whole, which would move the unbounded read, not remove it.
483
486
  const SHEBANG_MAX_BYTES = 4096;
484
487
 
@@ -488,7 +491,7 @@ const SHEBANG_MAX_BYTES = 4096;
488
491
  * first read and grows past it only for a longer line, never past
489
492
  * SHEBANG_MAX_BYTES: a first line that long or longer, newline not counted, is
490
493
  * not one, and nothing past the cap is read. A verdict on the prefix one read
491
- * holds parts from the line's own both ways (#1887): it misses a `node` past
494
+ * holds parts from the line's own both ways: it misses a `node` past
492
495
  * its end, reads `nodemon` cut after its `node` as `node` at the end of the
493
496
  * line, and decodes a character it cuts in half as U+FFFD. A file that does
494
497
  * not open with `#!` is decided on that first read however long its first
@@ -530,7 +533,7 @@ function hasNodeShebang(path, buf) {
530
533
  * Every tracked file this repository ships that the consumer's own `node`
531
534
  * executes, in the working tree at `root`, repo-relative: each `*.mjs`, and
532
535
  * any other file whose first line is a node shebang — the extensionless
533
- * entrypoints `fleet-run`, `fleet-bootstrap` and `fleet-provenance` (#1855).
536
+ * entrypoints `fleet-run`, `fleet-bootstrap` and `fleet-provenance`.
534
537
  * A shebang decides, never an extension alone: `plugin/workflows/*.js` is ESM
535
538
  * a harness runs and plain node never loads, and carries none. Test files —
536
539
  * `*.test.mjs`, the one naming this repository gives them — are not shipped,