@feigi/fleet-ctl 3.117.1 → 3.118.1

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.117.1",
3
+ "version": "3.118.1",
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": {
@@ -13,6 +13,13 @@
13
13
  // widen — ready-for-human tickets need a human to brainstorm first, and an
14
14
  // unattended fleet has no channel to one.
15
15
  //
16
+ // The flag names a Label role (label-map.mjs), never a label string. The
17
+ // role, and the five roles the query excludes, are resolved through the
18
+ // Label map once, after the arguments are checked and before any query. An
19
+ // unknown role is bad args, and a run with no valid map is a query that
20
+ // could not be built: both are exit 2 below, never 1, the map's refusal
21
+ // carrying the reader's message, which names `label-map.mjs ensure`.
22
+ //
16
23
  // Exit-code contract — the whole interface for a caller that reads no
17
24
  // stderr: 0 = survivors, JSON array on stdout (under `--with-dropped`, the
18
25
  // envelope described below). 1 = the query succeeded and returned no rows at
@@ -37,6 +44,7 @@
37
44
  import { execFileSync } from "node:child_process";
38
45
  import { parseArgs } from "node:util";
39
46
  import { makeDie, makeArg, makeHas } from "./arg.mjs";
47
+ import { LABEL_ROLES, readLabelMap } from "./label-map.mjs";
40
48
 
41
49
  const NAME = "candidates";
42
50
 
@@ -107,23 +115,39 @@ try {
107
115
 
108
116
  if (allowFallback && !requireLabel) die("--allow-fallback is meaningless without --require-label");
109
117
 
110
- // The label quoting's other half, and the half that quoting (query() below)
111
- // newly makes possible: the label is QUOTED into the search term, so a `"`
112
- // inside it closes that quote
113
- // early and the remainder becomes free text — the same misparse, with the fix
114
- // applied. A `\` breaks the same term from the other side, because GitHub
115
- // DOES honour `\"` as an escaped quote inside a qualifier: measured against
116
- // feigi/claude-config 2026-08-17, negating a label no issue carries is a
117
- // no-op, so `-label:"zzz" label:"ready-for-agent"` returns the same count as
118
- // `label:"ready-for-agent"` alone — while `-label:"zzz\" label:"ready-for-agent"`
119
- // returns the count for `ready-for-agent` as FREE TEXT instead, the backslash
120
- // having eaten the closing quote and swallowed the whole following qualifier.
121
- // Doubling does not escape it. Here the label term is LAST, so a trailing
122
- // backslash leaves its value unterminated and the query answers zero rows at
123
- // HTTP 200, no error — the unquoted label's silent empty, with the fix applied. Neither
124
- // character can be represented, so refuse both at exit 2 ("the query broke")
125
- // rather than send a query whose empty answer would read as exit 1.
126
- if (requireLabel && /["\\]/.test(requireLabel)) die(`--require-label cannot contain a double quote or a backslash, got '${requireLabel}'`);
118
+ // `--require-label` takes a Label role; anything else is a usage refusal,
119
+ // checked before the map is read so a mistyped flag refuses alike with a map
120
+ // or without one.
121
+ if (requireLabel && !LABEL_ROLES.includes(requireLabel)) {
122
+ die(`--require-label takes a Label role (${LABEL_ROLES.join(", ")}), got '${requireLabel}'`);
123
+ }
124
+
125
+ // The Label map, read once. query() below QUOTES every mapped string into its
126
+ // search term, so a `"` inside one would close that quote early and the
127
+ // remainder become free text. A `\` breaks the same term from the other
128
+ // side, because GitHub DOES honour `\"` as an escaped quote inside a
129
+ // qualifier: measured against feigi/claude-config 2026-08-17, negating a
130
+ // label no issue carries is a no-op, so `-label:"zzz" label:"ready-for-agent"`
131
+ // returns the same count as `label:"ready-for-agent"` alone — while
132
+ // `-label:"zzz\" label:"ready-for-agent"` returns the count for
133
+ // `ready-for-agent` as FREE TEXT instead, the backslash having eaten the
134
+ // closing quote and swallowed the whole following qualifier. Doubling does
135
+ // not escape it. Neither character can be represented, and the reader
136
+ // refuses a map holding either (label-map.mjs's VALID STRINGS). Every
137
+ // refusal here, typed or not, is exit 2 ("the query broke"): an uncaught
138
+ // throw would exit 1, which reads as "no rows".
139
+ let roles;
140
+ try {
141
+ roles = readLabelMap();
142
+ } catch (e) {
143
+ die(e.message);
144
+ }
145
+ // The string the labeled query requires; null for the unfiltered query.
146
+ const label = requireLabel ? roles[requireLabel] : null;
147
+
148
+ // The roles whose issues no query returns, the labeled one or the unfiltered
149
+ // fallback, in the order query() negates their mapped strings.
150
+ const EXCLUDED_ROLES = ["in-progress", "onhold", "wontfix", "needs-triage", "needs-info"];
127
151
 
128
152
  // The five `wayfinder:*` terms are separate `-label:` clauses, not a wildcard —
129
153
  // GitHub's search has no `-label:"wayfinder:*"` — and none is quoted despite
@@ -137,12 +161,11 @@ if (requireLabel && /["\\]/.test(requireLabel)) die(`--require-label cannot cont
137
161
  // comment gives it below: the queue churns hourly, so a digit is wrong within
138
162
  // a day and reads as a regression. Quoting every value anyway would cost
139
163
  // nothing (`-label:"wayfinder:map"` measured identical: same one-issue
140
- // exclusion, same issue) — left unquoted here because an unconditional
141
- // quote-everything rule belongs at the one call site building every label
142
- // term (`query()` below), and EXCLUDE is a static literal no caller
143
- // assembles.
144
- const EXCLUDE =
145
- "-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";
164
+ // exclusion, same issue) — left unquoted here because these are not Label
165
+ // roles: the map never names them, so they stay one literal, while query()
166
+ // quotes every term it builds from the map.
167
+ const WAYFINDER_EXCLUDE =
168
+ "-label:wayfinder:map -label:wayfinder:research -label:wayfinder:prototype -label:wayfinder:grilling -label:wayfinder:task";
146
169
  // `d` walks the body line by line rather than one regex over the whole
147
170
  // string, because RE2 (gojq's engine — gh applies `--jq` with gojq, not the
148
171
  // system jq this file's own tests stub) has no lookahead, so
@@ -399,7 +422,8 @@ const JQ =
399
422
  ' dh:((.body//"")|depmiss)}]\n';
400
423
 
401
424
  function query(label) {
402
- // The label is a VALUE in GitHub's query language, not part of its syntax,
425
+ // Every label string the map supplies — the required one and each excluded
426
+ // role's — is a VALUE in GitHub's query language, not part of its syntax,
403
427
  // so it is quoted rather than interpolated raw. Unquoted, a value
404
428
  // ends at the FIRST SPACE and every word after it becomes a free-text term
405
429
  // instead — measured 2026-08-17, `label:ready-for-agent candidates` returns
@@ -422,7 +446,9 @@ function query(label) {
422
446
  // needing none is a measured no-op (`label:ready-for-agent` and
423
447
  // `label:"ready-for-agent"` agree here), so one unconditional form beats a
424
448
  // predicate that has to stay in step with GitHub's parser to stay correct.
425
- const search = label ? `${EXCLUDE} label:"${label}"` : EXCLUDE;
449
+ // The unfiltered query (label null) carries every exclusion too.
450
+ const exclude = `${EXCLUDED_ROLES.map((role) => `-label:"${roles[role]}"`).join(" ")} ${WAYFINDER_EXCLUDE}`;
451
+ const search = label ? `${exclude} label:"${label}"` : exclude;
426
452
  const args = [
427
453
  "issue", "list",
428
454
  "--state", "open",
@@ -501,8 +527,8 @@ function query(label) {
501
527
  // shortlist that silently omits work — "no silent caps" is the rule this
502
528
  // enforces. Applied verbatim to BOTH the labeled query and the fallback
503
529
  // query below — the fallback result was previously never re-checked, so
504
- // --require-label <nonexistent> --allow-fallback could ship a silently
505
- // truncated unfiltered list.
530
+ // `--require-label ready-for-human --allow-fallback`, against a queue holding
531
+ // no `ready-for-human` issue, could ship a silently truncated unfiltered list.
506
532
  function refuseIfCapped(rows, description) {
507
533
  if (rows.length === limit) {
508
534
  die(
@@ -592,9 +618,9 @@ function dropSpecs(rows, pass) {
592
618
  return { kept, dropped };
593
619
  }
594
620
 
595
- let rows = query(requireLabel);
596
- console.error(` ${rows.length} candidate(s)${requireLabel ? ` with label:${requireLabel}` : ""}`);
597
- refuseIfCapped(rows, requireLabel ? ` with label:${requireLabel}` : "");
621
+ let rows = query(label);
622
+ console.error(` ${rows.length} candidate(s)${label ? ` with label:${label}` : ""}`);
623
+ refuseIfCapped(rows, label ? ` with label:${label}` : "");
598
624
  // After refuseIfCapped, never before: filtering first can shrink the array below
599
625
  // `limit` and the cap check would stop seeing a truncated list. Before the
600
626
  // emptiness test below, never after: a queue whose every row was filtered out
@@ -609,11 +635,11 @@ refuseIfCapped(rows, requireLabel ? ` with label:${requireLabel}` : "");
609
635
  // must read as the fallback's own facts (exit 1), not a merge of the two.
610
636
  const rawCount1 = rows.length;
611
637
  let dropped;
612
- ({ kept: rows, dropped } = dropSpecs(rows, requireLabel ? `label:${requireLabel}` : "unfiltered"));
638
+ ({ kept: rows, dropped } = dropSpecs(rows, label ? `label:${label}` : "unfiltered"));
613
639
  let allFilteredOut = rawCount1 > 0 && rows.length === 0;
614
640
 
615
- if (rows.length === 0 && allowFallback && requireLabel) {
616
- console.error(`${NAME}: empty with label:${requireLabel}; --allow-fallback given, retrying unfiltered`);
641
+ if (rows.length === 0 && allowFallback && label) {
642
+ console.error(`${NAME}: empty with label:${label}; --allow-fallback given, retrying unfiltered`);
617
643
  rows = query(null);
618
644
  console.error(` ${rows.length} candidate(s) unfiltered`);
619
645
  refuseIfCapped(rows, " unfiltered (fallback)");
@@ -10,7 +10,9 @@
10
10
  // oldest-first and never re-ranked. Its row count is `scanned`, the
11
11
  // supply the tick reports; the rows its to-spec filter removed are
12
12
  // `dropped`, which counts toward nothing and is carried so an empty or
13
- // short shortlist still names them.
13
+ // short shortlist still names them. `ready-for-agent` there is a Label
14
+ // role, which candidates.mjs resolves through the Label map; this file
15
+ // reads the map for nothing else.
14
16
  // 2. The dependency scan on each row's `d`: an open blocker drops the ticket
15
17
  // (next-ticket step 2). A blocker that is itself a candidate is open by
16
18
  // construction — candidates.mjs queries `--state open` — so only the rest
@@ -41,7 +43,9 @@
41
43
  // full read at best and two members on one ticket at worst.
42
44
  //
43
45
  // What REFUSES instead (exit 2), leaving the previous file exactly as it was: a
44
- // scan that did not answer, a ledger that could not be read, a workspace that
46
+ // scan that did not answer (a missing or invalid Label map among its causes,
47
+ // whose reason candidates.mjs's last stderr line carries onto this refusal's
48
+ // own line), a ledger that could not be read, a workspace that
45
49
  // could not be resolved, a file that could not be written. An empty shortlist
46
50
  // written in any of those cases would read as "no work". Exit 0 is the file
47
51
  // written, an empty shortlist included — the empty queue is an answer. Never
@@ -58,8 +62,8 @@
58
62
  // of it; stdout carries the same object plus `file`.
59
63
  //
60
64
  // The ledger is read through `ledger.mjs read`, never parsed here, so the
61
- // ledger keeps one parser. candidates.mjs's stderr passes straight through —
62
- // the per-candidate lines phase 0 always read, the dependency-heading
65
+ // ledger keeps one parser. candidates.mjs's stderr is relayed whole once it
66
+ // exits — the per-candidate lines phase 0 always read, the dependency-heading
63
67
  // notice among them. inflight.sh's and gh's are captured and summarised, one
64
68
  // line per dropped ticket.
65
69
 
@@ -75,7 +79,7 @@ import { premisesOf } from "./ledger-grammar.mjs";
75
79
  const NAME = "shortlist";
76
80
  const die = makeDie(NAME);
77
81
  const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
78
- const LABEL = "ready-for-agent";
82
+ const ROLE = "ready-for-agent";
79
83
  // The states that lift a premise or clear a blocker. `gh pr view` answers
80
84
  // OPEN, CLOSED or MERGED; `gh issue view` answers OPEN or CLOSED for an issue
81
85
  // and the PR's own state for a PR number — so one set serves every probe here.
@@ -153,15 +157,23 @@ function shortlistPath() {
153
157
  }
154
158
 
155
159
  function scan() {
156
- const r = spawnSync(process.execPath, [join(SCRIPT_DIR, "candidates.mjs"), "--require-label", LABEL, "--with-dropped"], {
157
- encoding: "utf8", maxBuffer: MAX_BUFFER, stdio: ["ignore", "pipe", "inherit"],
160
+ const r = spawnSync(process.execPath, [join(SCRIPT_DIR, "candidates.mjs"), "--require-label", ROLE, "--with-dropped"], {
161
+ encoding: "utf8", maxBuffer: MAX_BUFFER, stdio: ["ignore", "pipe", "pipe"],
158
162
  });
163
+ // Captured, then relayed whole before anything else is said, so this
164
+ // stderr still carries every line candidates.mjs wrote, in its order.
165
+ if (r.stderr) writeAll(2, r.stderr);
159
166
  if (r.error) die(`candidates.mjs did not run: ${how(r)}`);
160
167
  // Exit 1 (an empty queue) and exit 3 (every row a to-spec spec) are both the
161
168
  // empty answer. Exit 1 is also Node's own code for a crash, so the payload
162
169
  // decides: it must parse, with no rows.
163
170
  if (r.status !== 0 && r.status !== 1 && r.status !== 3) {
164
- die(`candidates.mjs ${r.signal ? `killed by ${r.signal}` : `exited ${r.status}`} — the scan did not answer, so there is no shortlist to write`);
171
+ // A refusal's cause is candidates.mjs's own last line — a missing Label
172
+ // map's names `label-map.mjs ensure` — and the tick keeps only the LAST
173
+ // line of this stderr for its REFRESH FAILED row, so the cause rides on
174
+ // this one rather than sitting above it. A kill has no such line.
175
+ const cause = r.signal ? "" : lastLine(r.stderr);
176
+ die(`candidates.mjs ${r.signal ? `killed by ${r.signal}` : `exited ${r.status}`} — the scan did not answer, so there is no shortlist to write${cause ? `: ${cause}` : ""}`);
165
177
  }
166
178
  let out;
167
179
  try {