@feigi/fleet-ctl 3.118.2 → 3.120.0

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.118.2",
3
+ "version": "3.120.0",
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": {
@@ -1,7 +1,7 @@
1
1
  // The cockpit's raw-input half: everything upstream of computeBoard(). gather()
2
- // reads the ledger, the `gh` issue/PR/repo/merged reads, per-PR CI and the
3
- // member-spend transcripts, and returns exactly the shape computeBoard()
4
- // consumes.
2
+ // reads the ledger, the Label map, the `gh` issue/PR/repo/merged reads, per-PR
3
+ // CI and the member-spend transcripts, and returns exactly the shape
4
+ // computeBoard() consumes.
5
5
  //
6
6
  // Unlike compute-board.mjs this module is NOT pure. gather() performs real I/O
7
7
  // — it spawns `gh`, `ledger.mjs` and `ci-state.mjs` and walks the transcript
@@ -41,6 +41,8 @@ import { readCostGuard } from "./fleet-tick.mjs";
41
41
  import { parseFrontmatter } from "./tier-roles.mjs";
42
42
  import { isImplementer } from "./member-outcomes.mjs";
43
43
  import { validateTable } from "./ticket-router.mjs";
44
+ import { LabelMapUnreadable, readLabelMap } from "./label-map.mjs";
45
+ import { FleetDirUnresolvable } from "./fleet-dir.mjs";
44
46
  // The heartbeat's liveness mark and the controller record beside it, read here
45
47
  // and never written: the heartbeat is the mark's only writer and
46
48
  // `ledger.mjs rotate` the record's. stallOwner() reads the process table to
@@ -875,7 +877,21 @@ export async function carryModelRoles(carried, now, read = readModelRoles) {
875
877
  // receipts the Cell evidence tab reads live. Null, as with `stateFile`, says no
876
878
  // caller named one: that tab is then built from no guard and no receipt, and the
877
879
  // cockpit's `omp` is not asked for `modelRoles`.
878
- export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir = null, scriptDir = SCRIPT_DIR, interval, workspace = null, port = null, spendDir, spendDirExplicit = false, spendSince = null }) {
880
+ //
881
+ // `cwd` is the checkout whose Label map is read, once per gather, through
882
+ // label-map.mjs's reader; it defaults to this process's cwd, where every `gh`
883
+ // read below runs. `labelMapFile` is that map's path when the caller has
884
+ // resolved it already, and is then read in place of `cwd`'s: the reader's
885
+ // own resolution is a synchronous `git rev-parse`, and a serving cockpit's
886
+ // tick shares its event loop with /board.json, which must keep answering a
887
+ // relaunch's identity probe — so board.mjs passes the map in the state
888
+ // directory it resolved at bind time. The map's strings go to
889
+ // computeBoard() as `roles` and the pool read asks for the mapped
890
+ // `ready-for-agent`. A map the reader refuses, or no repository to find one
891
+ // in, is reported on stderr like a failed read, and leaves `roles` null with
892
+ // `labelMapError` saying why: the pool is then not read at all (`poolOk`
893
+ // false), since no string names it.
894
+ export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir = null, scriptDir = SCRIPT_DIR, interval, workspace = null, port = null, spendDir, spendDirExplicit = false, spendSince = null, cwd = process.cwd(), labelMapFile = null }) {
879
895
  // The one read that must not crash the gather: a corrupt/partial board.json
880
896
  // (the fallback safety net itself) is ignored, not fatal. That holds for a
881
897
  // SHAPE fault as much as a parse fault — the guard below rejects the
@@ -957,7 +973,17 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir
957
973
  ? { ...parsedLedger, state: "read" }
958
974
  : { rows: [], filed: [], ruled: [], state: ledgerJson == null ? "unread" : "unparsed" };
959
975
 
960
- const issuesJson = await tryRun("gh", ["issue", "list", "--label", "ready-for-agent",
976
+ let roles = null;
977
+ let labelMapError = null;
978
+ try {
979
+ roles = readLabelMap({ cwd, file: labelMapFile });
980
+ } catch (e) {
981
+ if (!(e instanceof LabelMapUnreadable) && !(e instanceof FleetDirUnresolvable)) throw e;
982
+ labelMapError = e.message;
983
+ console.error(`${NAME}: the Label map could not be read, so POOL and READY are not read: ${labelMapError}`);
984
+ }
985
+
986
+ const issuesJson = roles === null ? null : await tryRun("gh", ["issue", "list", "--label", roles["ready-for-agent"],
961
987
  "--state", "open", "--limit", String(POOL_LIMIT), "--json", "number,title,labels"]);
962
988
  // title: falls back to the same `#<number>` placeholder titleFor() already
963
989
  // uses for an issue it cannot find at all (compute-board.mjs). An unrowed
@@ -1097,6 +1123,7 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir
1097
1123
  const agents = readAgents(scriptDir);
1098
1124
  const modelRoles = stateDir === null ? heldRead(prev?.modelRoles) : await carryModelRoles(prev?.modelRoles, now);
1099
1125
  return { ledger, issues, prs, merged, closed, closedIssues, ci, prev, repo, repoUrl, workspace, port, spend, beat, ticked, acted, controller, stallOwner: stallOwnerOf, poolOk,
1126
+ roles, labelMapError,
1100
1127
  poolCapped, prsCapped, guard, receipts, agents, modelRoles, implementers: [...implementers.values()], routerTable,
1101
1128
  now, interval };
1102
1129
  }
@@ -529,7 +529,8 @@ function render(m) {
529
529
  // POOL's own count is `q.pool` — the same number, except that a
530
530
  // capped pool read makes it `"100+"`, and a header reading a bare 100
531
531
  // beside a footer reading 100+ would be the exact claim the `+` retracts.
532
- h.append(el("span", null, String(name === "POOL" ? q.pool ?? inCol.length : inCol.length)));
532
+ // A pool that was not read is null and shows `?`, never an empty count.
533
+ h.append(el("span", null, String(name === "POOL" ? countOf(q.pool, inCol.length) : inCol.length)));
533
534
  return [h, ...inCol.map(card)];
534
535
  });
535
536
  COLUMNS.forEach((name, i) => {
@@ -550,10 +551,14 @@ function render(m) {
550
551
  // (found by review: capNotice was reachable but unrenderable whenever
551
552
  // ledgerMsg/stallMsg/stale also held).
552
553
  const capMsg = m.capNotice ? "⚠ " + m.capNotice : null;
554
+ // The footer too, for capMsg's reason: a higher-priority banner must not
555
+ // swallow the one line that says POOL and READY were not read.
556
+ const mapMsg = m.labelMapNotice ? "⚠ " + m.labelMapNotice : null;
553
557
  // footer
554
558
  const foot = document.getElementById("footer");
555
559
  foot.innerHTML = "";
556
- foot.append(el("div", null, `pool ${q.pool ?? 0} · supply ${q.supply ?? 0} · review-backlog ${q.reviewBacklog ?? 0}`));
560
+ foot.append(el("div", null, `pool ${countOf(q.pool, 0)} · supply ${countOf(q.supply, 0)} · review-backlog ${q.reviewBacklog ?? 0}`));
561
+ if (mapMsg) foot.append(el("div", null, mapMsg));
557
562
  if (capMsg) foot.append(el("div", null, capMsg));
558
563
  const filed = el("div", "filed", `filed follow-ups (${(m.filed || []).length}): ` +
559
564
  (m.filed || []).map((f) => "#" + f.issue).join(" "));
@@ -588,6 +593,8 @@ function render(m) {
588
593
  showBanner(stallMsg, "dead");
589
594
  } else if (ledgerMsg) {
590
595
  showBanner(ledgerMsg);
596
+ } else if (mapMsg) {
597
+ showBanner(mapMsg);
591
598
  } else if (capMsg) {
592
599
  showBanner(capMsg);
593
600
  } else { banner.style.display = "none"; banner.className = ""; }
@@ -626,6 +633,12 @@ function livenessBanner(l) {
626
633
  return l && l.text ? "⚠ " + l.text : null;
627
634
  }
628
635
 
636
+ // A queue count: `?` for one the board did not read (null), `fallback` for a
637
+ // payload that has no such count at all.
638
+ function countOf(v, fallback) {
639
+ return v === null ? "?" : v ?? fallback;
640
+ }
641
+
629
642
  // Three ledger states, three renderings. `read` refuses an absent ledger
630
643
  // under --require-file now, so gather() can tell "there was no ledger to read"
631
644
  // from "read it, nothing filed yet" from "read it, the answer would not parse".
package/scripts/board.mjs CHANGED
@@ -15,6 +15,7 @@ import { writeFileSync, renameSync, writeSync } from "node:fs";
15
15
  import { defineFlags } from "./arg.mjs";
16
16
  import { NAME, die, warnOnce } from "./board-common.mjs";
17
17
  import { gather, receiptSpendDir } from "./board-gather.mjs";
18
+ import { LABEL_MAP_FILE } from "./label-map.mjs";
18
19
  import { serve, resolveCockpitInstance, cockpitWorkspace } from "./board-server.mjs";
19
20
  // The heartbeat's liveness mark path, taken from the module that owns the
20
21
  // filename rather than spelling `heartbeat.json` a second time. The PATH
@@ -301,6 +302,9 @@ async function main() {
301
302
  // The cost guard, the receipts and the carried `modelRoles` the Cell
302
303
  // evidence tab reads, from the same directory.
303
304
  stateDir: instance.stateDir,
305
+ // The Label map in that directory too, so the reader runs no git probe
306
+ // of its own: the instance has already settled where `.fleet` is.
307
+ labelMapFile: join(instance.stateDir, LABEL_MAP_FILE),
304
308
  workspace: instance.workspace, port: instance.port,
305
309
  interval, ...spendSource(spendDir, instance.stateDir), spendSince,
306
310
  }));
@@ -407,6 +411,12 @@ async function boardTick({ ledgerFile, interval, spendDir, spendSince }) {
407
411
  // the ledger default: a pure join on a directory settled at bind time.
408
412
  stateFile: stateFileIn(stateDir),
409
413
  stateDir,
414
+ // The Label map out of the same state directory, joined rather than
415
+ // resolved: the reader's own resolution is a synchronous git probe,
416
+ // and a tick blocked on it leaves a relaunch's identity probe
417
+ // unanswered. A map `ensure` writes later is still read, since the
418
+ // file is read per tick.
419
+ labelMapFile: join(stateDir, LABEL_MAP_FILE),
410
420
  workspace, port: served,
411
421
  // The operator's --spend-dir, else the receipt as it stands at this
412
422
  // tick, read from the same state directory as the ledger and heartbeat.
@@ -243,14 +243,15 @@ export function parseRow(row) {
243
243
  // ticket: MERGED is terminal, so a merged PR never reopens regardless of
244
244
  // what this run's merged read says — but a ticket retried under a NEW PR
245
245
  // after its earlier one merged gets no such carry-forward; that new PR's
246
- // state is unknown, not MERGED. READY needs the live PR label; any other
247
- // PR, closed-unmerged included, is in REVIEW.
248
- export function deriveColumn(parsed, prState) {
246
+ // state is unknown, not MERGED. READY needs the live PR label, the mapped
247
+ // `ready-to-merge` string `readyToMerge` (null with no Label map, which
248
+ // makes no PR READY); any other PR, closed-unmerged included, is in REVIEW.
249
+ export function deriveColumn(parsed, prState, readyToMerge) {
249
250
  if (parsed.excluded) return "POOL";
250
251
  if (parsed.merged) return "MERGED";
251
252
  if (parsed.pr != null) {
252
253
  if (prState && prState.merged) return "MERGED";
253
- if (prState && prState.labels.includes("ready-to-merge")) return "READY";
254
+ if (prState && prState.labels.includes(readyToMerge)) return "READY";
254
255
  return "REVIEW";
255
256
  }
256
257
  if (parsed.implOutcome === "released" || parsed.implOutcome === "bailed") return null;
@@ -650,8 +651,16 @@ export function issuesOfPrs({ ledger, prs }) {
650
651
  // among issuesOfPrs(). A pr-closed flag needs both: a missing `closed`
651
652
  // flags nothing, and a failed issue read reads as not CLOSED, as closedTickets()
652
653
  // reads its own failed probe.
654
+ // `roles` is the Label map gather() read (every Label role -> the tracker's
655
+ // string), null when it could not be read, with `labelMapError` saying why.
656
+ // With no map no PR is READY and none is known to lack `ready-to-merge`, so
657
+ // `unqueued` is empty rather than every open PR: a PR its finisher labelled
658
+ // would otherwise flag `unlabelled` off a label nobody could name. The
659
+ // finisher flags all read that set, so `finisher:failed` and
660
+ // `finisher:killed` go unflagged too, and `labelMapNotice` says so.
653
661
  export function computeBoard(inputs) {
654
662
  const { ledger, issues, prs, ci, prev, now } = inputs;
663
+ const readyToMerge = inputs.roles?.["ready-to-merge"] ?? null;
655
664
  const prByNum = new Map(prs.map((p) => [p.number, p]));
656
665
  const mergedPrs = new Set(inputs.merged || []);
657
666
  const closedPrs = new Set(inputs.closed || []);
@@ -692,7 +701,8 @@ export function computeBoard(inputs) {
692
701
  claimer.agent = p.agent ?? claimer.agent;
693
702
  claimer.merged ||= p.merged;
694
703
  }
695
- const unqueued = new Set(prs.filter((p) => p.state === "OPEN" && !(p.labels || []).includes("ready-to-merge")).map((p) => p.number));
704
+ const unqueued = readyToMerge === null ? new Set()
705
+ : new Set(prs.filter((p) => p.state === "OPEN" && !(p.labels || []).includes(readyToMerge)).map((p) => p.number));
696
706
  const latestFinishers = new Map(latestFinisherAttempts({ rows, dispatched: ledger.dispatched || [] }, unqueued).map((u) => [u.pr, u.outcome]));
697
707
  // Review state is the PR's, read off the tick's own fold — a card's
698
708
  // PR is its row's latest attempt, whichever row carries that PR's tokens.
@@ -712,7 +722,7 @@ export function computeBoard(inputs) {
712
722
  const prState = p.pr == null ? null
713
723
  : pr ? { open: pr.state === "OPEN", labels: pr.labels || [] }
714
724
  : { open: false, labels: [], merged: mergedPrs.has(p.pr) || carriedMerged(prevTicket, p) };
715
- const column = deriveColumn(p, prState);
725
+ const column = deriveColumn(p, prState, readyToMerge);
716
726
  if (column === null) continue; // released/bailed: the POOL loop below decides
717
727
  rowIssues.add(p.issue);
718
728
  const sinceEnteredStage = stageEntry(prevTicket, column, now);
@@ -771,8 +781,11 @@ export function computeBoard(inputs) {
771
781
  // A capped pool read makes this count a floor, and it says so the way
772
782
  // fleet-tick.mjs's claimed count does — `"100+"`, never a bare 100 that
773
783
  // reads as exact. stall() below receives the same value, so the stall line
774
- // and the footer cannot disagree about it.
775
- const pool = inputs.poolCapped ? `${cardsInPool}+` : cardsInPool;
784
+ // and the footer cannot disagree about it. A pool that was not read (`gh`
785
+ // failed, or no Label map named the label to ask for) is null, never 0: an
786
+ // empty POOL reads as no work.
787
+ const poolOk = inputs.poolOk ?? true;
788
+ const pool = !poolOk ? null : inputs.poolCapped ? `${cardsInPool}+` : cardsInPool;
776
789
 
777
790
  return {
778
791
  generatedAt: now,
@@ -791,6 +804,12 @@ export function computeBoard(inputs) {
791
804
  port: inputs.port ?? null,
792
805
  queue: { pool, supply: pool, reviewBacklog },
793
806
  capNotice: capNotice(inputs),
807
+ // Null when the Label map was read; else what POOL, READY and the
808
+ // finisher flags lack and the reader's reason, which names the derivation
809
+ // step that writes the map.
810
+ labelMapNotice: inputs.roles ? null
811
+ : "no Label map was read, so POOL and READY are unknown and no PR is flagged unlabelled, finisher:failed or finisher:killed"
812
+ + (inputs.labelMapError ? `: ${inputs.labelMapError}` : ""),
794
813
  tickets,
795
814
  filed: (ledger.filed || []).map(splitNumbered),
796
815
  // Not derivable from anything else in this model: a ledger that was never
@@ -830,7 +849,7 @@ export function computeBoard(inputs) {
830
849
  // succeeded, and only gather() — which now sets both — can say otherwise.
831
850
  liveness: stall({ beat: inputs.beat, ticked: inputs.ticked, acted: inputs.acted, controller: inputs.controller }, tickets, pool, {
832
851
  ledgerOk: (ledger.state ?? "read") === "read",
833
- poolOk: inputs.poolOk ?? true,
852
+ poolOk,
834
853
  owner: inputs.stallOwner ?? NO_OWNER,
835
854
  }, now),
836
855
  attention,
@@ -39,6 +39,13 @@
39
39
  // head record names this pin is left as it is — no comment, no label write —
40
40
  // and still answers 0 off the read-back, `added: false`.
41
41
  //
42
+ // `ready-to-merge` above is a Label role (label-map.mjs): the label written,
43
+ // and the one the idempotence check and the read-back look for, is the Label
44
+ // map's string for it, read once from the repository `--repo` names (the cwd
45
+ // when omitted) before step 0. The head record is not a label: its prefix is
46
+ // `ready-to-merge-head:` whatever the map says, the grammar the merge bot
47
+ // parses back.
48
+ //
42
49
  // Stdout is always one JSON line, the receipt:
43
50
  //
44
51
  // {pr, pin, ticketless, releaseLabels, patchAdded, inert, commented, added,
@@ -54,8 +61,8 @@
54
61
  // added this run wrote the label
55
62
  // readBack every label name the step 4 read carried, null if it never ran
56
63
  // firstRead every label name step 1 read carried, null if it never ran
57
- // step on exit 2 only, the step that failed: `pin`, `repo`, or the
58
- // step whose `gh` call failed
64
+ // step on exit 2 only, the step that failed: `pin`, `repo`,
65
+ // `label-map`, or the step whose `gh` call failed
59
66
  // error on exit 2 only, what `gh` (or the invocation) said
60
67
  //
61
68
  // A usage error that never reaches `gh` — a missing or unknown flag — is a
@@ -64,8 +71,10 @@
64
71
  // Exit vocabulary:
65
72
  //
66
73
  // 0 the read-back carries `ready-to-merge`
67
- // 2 the invocation or a `gh` call failed, or the Ticketless test could not
68
- // look — its stderr is in the receipt and on stderr, and no later step ran
74
+ // 2 the invocation or a `gh` call failed, the Label map could not be read
75
+ // (an absent or invalid map's error names `label-map.mjs ensure`), or the
76
+ // Ticketless test could not look — its stderr is in the receipt and on
77
+ // stderr, and no later step ran
69
78
  // 3 the PR does not carry exactly one release label — nothing was written
70
79
  // 4 every write returned 0 and the read-back does not carry the label
71
80
  // 5 a Ticketless PR whose diff is not inert, or whose verdict could not
@@ -79,10 +88,10 @@ import { makeDie, defineFlags, writeAll } from "./arg.mjs";
79
88
  import { inertVerdict } from "./finisher-scope.mjs";
80
89
  import { gitEnv } from "./git-env.mjs";
81
90
  import { LABEL_LIST_ARGS, LABEL_LIST_LIMIT, releaseLabelsDefined, releaseLabelsIn } from "./release-labels.mjs";
91
+ import { readLabelMap } from "./label-map.mjs";
82
92
  import { ticketlessVerdict } from "./ticketless.mjs";
83
93
 
84
94
  const NAME = "finisher-label";
85
- const LABEL = "ready-to-merge";
86
95
 
87
96
  const die = makeDie(NAME);
88
97
  const { arg, numArg, sweep, stray } = defineFlags(die, {
@@ -140,6 +149,15 @@ if (repo !== null && !statSync(repo, { throwIfNoEntry: false })?.isDirectory())
140
149
  fail("repo", `--repo is not a directory: ${repo}`);
141
150
  }
142
151
 
152
+ // The tracker's string for the `ready-to-merge` role, in the repository `gh`
153
+ // runs in.
154
+ let LABEL;
155
+ try {
156
+ LABEL = readLabelMap({ cwd: resolve(repo ?? ".") })["ready-to-merge"];
157
+ } catch (e) {
158
+ fail("label-map", e.message);
159
+ }
160
+
143
161
  // `gh` resolves its repository from the cwd's git remotes, so an ambient
144
162
  // GIT_DIR would retarget every call at another repository.
145
163
  const GH_ENV = gitEnv();
@@ -178,13 +178,11 @@ export function writeLabelMap(map, { cwd = process.cwd() } = {}) {
178
178
  return file;
179
179
  }
180
180
 
181
- // The parsed cache of the repository `cwd` belongs to, with its path. Throws
182
- // LabelMapUnreadable, its message naming `ensure`, when the file is absent or
183
- // does not parse; when it exists and cannot be read, the message names the
184
- // errno as a filesystem fault and its repair before `ensure`.
185
- // FleetDirUnresolvable outside a repository.
186
- function loadCache(cwd) {
187
- const file = fleetFile(LABEL_MAP_FILE, { cwd });
181
+ // The parsed cache at `file`. Throws LabelMapUnreadable, its
182
+ // message naming `ensure`, when the file is absent or does not parse; when it
183
+ // exists and cannot be read, the message names the errno as a filesystem
184
+ // fault and its repair before `ensure`.
185
+ function loadCache(file) {
188
186
  let text;
189
187
  try {
190
188
  text = readFileSync(file, "utf8");
@@ -198,7 +196,7 @@ function loadCache(cwd) {
198
196
  );
199
197
  }
200
198
  try {
201
- return { file, cache: JSON.parse(text) };
199
+ return JSON.parse(text);
202
200
  } catch (e) {
203
201
  throw new LabelMapUnreadable(`the Label map at ${file} does not parse (${e.message}): ${DERIVE}`);
204
202
  }
@@ -212,23 +210,26 @@ const inRoleOrder = (roles) => Object.fromEntries(LABEL_ROLES.map((role) => [rol
212
210
 
213
211
  /**
214
212
  * The `roles` object (every Label role -> its string) of the cache of the
215
- * repository `cwd` belongs to. Throws LabelMapUnreadable, its message naming
216
- * `ensure`, when the cache is absent, does not parse, lacks a role or breaks
217
- * the string rules; when the cache exists and cannot be read (e.g. EACCES,
218
- * EISDIR, ENOTDIR), its message names the errno as a filesystem fault, not a
219
- * map fault, and the repair, then `ensure` as the following step. Throws
220
- * FleetDirUnresolvable outside a repository.
213
+ * repository `cwd` belongs to, or of the cache at `file` when the caller has
214
+ * resolved that path already — then no git probe runs, which is what a
215
+ * caller on an event loop it must not block (the cockpit's tick) needs.
216
+ * Throws LabelMapUnreadable, its message naming `ensure`, when the cache is
217
+ * absent, does not parse, lacks a role or breaks the string rules; when the
218
+ * cache exists and cannot be read (e.g. EACCES, EISDIR, ENOTDIR), its message
219
+ * names the errno as a filesystem fault, not a map fault, and the repair,
220
+ * then `ensure` as the following step. Throws FleetDirUnresolvable outside a
221
+ * repository when no `file` is given.
221
222
  */
222
- export function readLabelMap({ cwd = process.cwd() } = {}) {
223
- const { file, cache } = loadCache(cwd);
224
- const roles = cache?.roles;
223
+ export function readLabelMap({ cwd = process.cwd(), file = null } = {}) {
224
+ const at = file ?? fleetFile(LABEL_MAP_FILE, { cwd });
225
+ const roles = loadCache(at)?.roles;
225
226
  if (!isRecord(roles)) {
226
- throw new LabelMapUnreadable(`the Label map at ${file} holds no \`roles\` object: ${DERIVE}`);
227
+ throw new LabelMapUnreadable(`the Label map at ${at} holds no \`roles\` object: ${DERIVE}`);
227
228
  }
228
229
  const faults = labelStringFaults(roles);
229
230
  if (faults.length) {
230
231
  const why = faults.map(({ role, rule }) => `${role}: ${rule}`).join("; ");
231
- throw new LabelMapUnreadable(`the Label map at ${file} is invalid — ${why}: ${DERIVE}`);
232
+ throw new LabelMapUnreadable(`the Label map at ${at} is invalid — ${why}: ${DERIVE}`);
232
233
  }
233
234
  return inRoleOrder(roles);
234
235
  }
@@ -577,7 +578,7 @@ function readDerivationInputs(cwd) {
577
578
  const live = readLiveLabels({ cwd: top });
578
579
  let cache = null;
579
580
  try {
580
- cache = loadCache(cwd).cache;
581
+ cache = loadCache(fleetFile(LABEL_MAP_FILE, { cwd }));
581
582
  } catch (e) {
582
583
  if (!(e instanceof LabelMapUnreadable)) throw e;
583
584
  // Absent or not parsing is derived again; a cache that exists and cannot
@@ -72,6 +72,7 @@ import { mergeBotVerdicts } from "./report-schema.mjs";
72
72
  import { ownClosingIssues } from "./closing-refs.mjs";
73
73
  import { isTicketless } from "./ticketless.mjs";
74
74
  import { RELEASE_LABELS, LABEL_LIST_ARGS, LABEL_LIST_LIMIT, releaseLabelsIn, releaseLabelsDefined } from "./release-labels.mjs";
75
+ import { LabelMapUnreadable, readLabelMap } from "./label-map.mjs";
75
76
 
76
77
  const NAME = "ledger";
77
78
  // The plugin's own agent definitions — the directory tier-check.mjs reads
@@ -2160,20 +2161,40 @@ function releaseLabelRefusal(member, tickets, refs) {
2160
2161
  return `${missing} and ${closes} — add exactly one, the bump its change calls for: gh pr edit ${pr} --add-label <${RELEASE_LABELS.join("|")}>`;
2161
2162
  }
2162
2163
 
2164
+ // The tracker's string for the `ready-to-merge` Label role, off the Label map
2165
+ // of the repository `dir` belongs to (label-map.mjs). Only the two paths that
2166
+ // compare or list that label read it — `dispatch merge-bot`'s queueSnapshot()
2167
+ // and settle --from-report's finisher and merge-bot checks — so every other
2168
+ // verb runs with no map at all. A map that cannot be read, or no repository
2169
+ // to find one in, is exit 2 under `where`, carrying the reader's message (an
2170
+ // absent or invalid map's names `label-map.mjs ensure`); nothing written.
2171
+ function readyLabel(dir, where) {
2172
+ try {
2173
+ return readLabelMap({ cwd: dir })["ready-to-merge"];
2174
+ } catch (e) {
2175
+ if (!(e instanceof LabelMapUnreadable) && !(e instanceof FleetDirUnresolvable)) throw e;
2176
+ die(`${where}: ${e.message}; nothing written`);
2177
+ }
2178
+ }
2179
+
2163
2180
  // The open `ready-to-merge` PRs, ascending, as gh answers from the ledger's
2164
2181
  // own directory with runCheck()'s environment: the queue a merge bot is
2165
2182
  // dispatched against, recorded on its `## Dispatched` entry. Anything but a
2166
2183
  // JSON array of PR numbers, or an answer filling the limit — gh stops there
2167
- // at exit 0 — could not read the queue: refused, nothing written.
2184
+ // at exit 0 — could not read the queue: refused, nothing written. The label
2185
+ // gh lists by is the Label map's string for the role, see readyLabel().
2168
2186
  function queueSnapshot() {
2169
2187
  const limit = 1000;
2170
- const what = `gh pr list --state open --label ready-to-merge --limit ${limit} --json number`;
2188
+ let dir = dirname(resolve(file));
2189
+ while (!existsSync(dir) && dirname(dir) !== dir) dir = dirname(dir);
2190
+ const ready = readyLabel(dir, "dispatch merge-bot");
2191
+ // An argv, never `what` split on spaces: a mapped string may hold one.
2192
+ const args = ["pr", "list", "--state", "open", "--label", ready, "--limit", String(limit), "--json", "number"];
2193
+ const what = `gh ${args.join(" ")}`;
2171
2194
  const env = { ...process.env, GH_REPO: "" };
2172
2195
  delete env.GIT_DIR;
2173
2196
  delete env.GIT_WORK_TREE;
2174
- let dir = dirname(resolve(file));
2175
- while (!existsSync(dir) && dirname(dir) !== dir) dir = dirname(dir);
2176
- const r = spawnSync("gh", what.split(" ").slice(1), { encoding: "utf8", cwd: dir, env, timeout: 60_000, stdio: ["ignore", "pipe", "pipe"] });
2197
+ const r = spawnSync("gh", args, { encoding: "utf8", cwd: dir, env, timeout: 60_000, stdio: ["ignore", "pipe", "pipe"] });
2177
2198
  const refuse = (why) => die(`dispatch merge-bot: could not read the queue to record — ${what}${why}; nothing written`);
2178
2199
  if (r.status !== 0) {
2179
2200
  const why = cause(r.error && r.error.message, r.stderr);
@@ -2637,6 +2658,11 @@ function recordFiled(id, subject) {
2637
2658
  // conflictHold or refused, or no longer reads
2638
2659
  // OPEN with ready-to-merge
2639
2660
  //
2661
+ // `ready-to-merge` in both rows is the Label map's string for the role, read
2662
+ // by readyLabel() only when one of the two checks runs: on a finisher's
2663
+ // `labelled`, and on a merge bot's report that leaves a PR queued at dispatch
2664
+ // without a verdict.
2665
+ //
2640
2666
  // THE CHECK-STEP RECORD, for `impl-N=PR#M` and `fix-pr-M=applied:<head>`:
2641
2667
  // recipe-check.mjs writes `<reports>/<member>.check.json` on the member's
2642
2668
  // staged tree, and settle requires that it exists and parses, that the Check
@@ -2655,8 +2681,9 @@ function recordFiled(id, subject) {
2655
2681
  // stderr names each failed check; nothing written. Exit 2: the report is
2656
2682
  // absent, unreadable or invalid, a check could not look (a `gh`, `git` or
2657
2683
  // verify-sha.sh call that failed, printed what it was not asked for, or never
2658
- // finished), a merge bot's `## Dispatched` entry records no queued=, or a
2659
- // refusal the bare form makes; nothing written either.
2684
+ // finished), a merge bot's `## Dispatched` entry records no queued=, the
2685
+ // Label map could not be read, or a refusal the bare form makes; nothing
2686
+ // written either.
2660
2687
  //
2661
2688
  // After the settle, in the same write: every `unrecorded` entry goes to `##
2662
2689
  // Filed` the way `filed` records one, for a fix-applier every `deferred`
@@ -2690,7 +2717,6 @@ function mismatch(msg) {
2690
2717
  async function runSettleFromReport() {
2691
2718
  const usage = "usage: ledger.mjs settle <member> --from-report [--reports <dir>]";
2692
2719
  const deriveTestcmd = join(dirname(fileURLToPath(import.meta.url)), "derive-testcmd.sh");
2693
- const ready = "ready-to-merge";
2694
2720
  let member;
2695
2721
  let reports = null;
2696
2722
  for (let k = 0; k < rest.length; k++) {
@@ -2842,6 +2868,7 @@ async function runSettleFromReport() {
2842
2868
  } else if (live.family === "finisher-pr") {
2843
2869
  if (report.outcome === "labelled") {
2844
2870
  outcome = "labelled";
2871
+ const ready = readyLabel(repoDir(), where);
2845
2872
  const pr = prView(live.number, "labels");
2846
2873
  check(`PR #${live.number} carries ${ready}`, pr.labels.some((l) => l?.name === ready));
2847
2874
  check(`labelsReadBack carries ${ready}`, report.labelsReadBack.includes(ready));
@@ -2865,7 +2892,10 @@ async function runSettleFromReport() {
2865
2892
  die(`${where}: ## Dispatched records no queued= for ${member}, so whether its report gives every PR queued at dispatch a verdict cannot be judged — settle it by hand; nothing written`);
2866
2893
  }
2867
2894
  const given = new Set(mergeBotVerdicts(report).map((v) => v.pr));
2868
- for (const pr of queued.filter((n) => !given.has(n))) {
2895
+ const unjudged = queued.filter((n) => !given.has(n));
2896
+ // The map is read only when a queued PR's labels are to be looked at.
2897
+ const ready = unjudged.length > 0 ? readyLabel(repoDir(), where) : null;
2898
+ for (const pr of unjudged) {
2869
2899
  const v = prView(pr, "state,labels");
2870
2900
  const left = v.state !== "OPEN" || !v.labels.some((l) => l?.name === ready);
2871
2901
  check(`PR #${pr}, queued at dispatch, has a verdict in merged, held, conflictHold or refused, or has left the queue`, left);
@@ -34,7 +34,11 @@
34
34
  // main-gain.mjs's own payload — hits, acknowledged removals, edited lines and unchecked
35
35
  // files — or null when it did not run or printed no JSON object; an unusable
36
36
  // payload is still echoed. Stderr: the children's own diagnostics, passed
37
- // straight through and never folded into stdout.
37
+ // straight through and never folded into stdout. A refusal (exit 2 with its
38
+ // reason on stderr: a usage error, a Label map that cannot be read — see THE
39
+ // LABEL MAP below — an `--out` that cannot be written, a gate that failed)
40
+ // prints no JSON line, and one made before any child runs writes no `--out`
41
+ // file.
38
42
  //
39
43
  // Exit vocabulary — the same three-way contract as inflight.sh, prove-merge.sh
40
44
  // and staleness.mjs:
@@ -50,6 +54,7 @@
50
54
  // could-not-evaluate row fires further down instead:
51
55
  //
52
56
  // label `ready-to-merge` absent 1 label-pulled
57
+ // (the Label map's string for the role)
53
58
  // reviewDecision CHANGES_REQUESTED 1 changes-requested
54
59
  // PR head not in {pre, post} and not a 1 head-moved-after-label
55
60
  // proven rebase-carry of pre
@@ -79,6 +84,13 @@
79
84
  // so a conflict-free rebase keeps it. Anything the proof cannot establish —
80
85
  // a missing object, an unresolvable base, a git failure, a merge conflict — is
81
86
  // no carry, and the head row blocks exactly as it does for any other moved head.
87
+ //
88
+ // THE LABEL MAP: `ready-to-merge` is a Label role (label-map.mjs). Its string
89
+ // is read off the Label map once, after the arguments are checked and before
90
+ // any child runs, and the label row compares the PR's labels against that
91
+ // string. A map that cannot be read, or no repository to find one in, is a
92
+ // refusal at exit 2 carrying the reader's message (an absent or invalid map's
93
+ // names `label-map.mjs ensure`); nothing runs.
82
94
 
83
95
  import { spawnSync } from "node:child_process";
84
96
  import { createHash } from "node:crypto";
@@ -87,6 +99,7 @@ import { dirname, join } from "node:path";
87
99
  import { fileURLToPath } from "node:url";
88
100
  import { makeDie, defineFlags, writeAll } from "./arg.mjs";
89
101
  import { gitEnv, mainCheckoutDirFromGitCommonDir } from "./git-env.mjs";
102
+ import { readLabelMap } from "./label-map.mjs";
90
103
 
91
104
  const NAME = "merge-gate";
92
105
 
@@ -129,6 +142,15 @@ const pre = sha("pre", preArg);
129
142
  const post = postArg === null ? null : sha("post", postArg);
130
143
  const heads = new Set([pre, post ?? pre]);
131
144
 
145
+ // The tracker's string for the `ready-to-merge` role. Every refusal here,
146
+ // typed or not, is exit 2: an uncaught throw would exit 1, "blocked".
147
+ let ready;
148
+ try {
149
+ ready = readLabelMap()["ready-to-merge"];
150
+ } catch (e) {
151
+ die(e.message);
152
+ }
153
+
132
154
  // --- rebase-carry proof ----------------------------------------------------
133
155
  // Same net change: `git diff-tree` of each head against its own merge base
134
156
  // with `origin/main`, in the main checkout, compared byte for byte after
@@ -358,7 +380,7 @@ function decide(instruments, prView, mainGain, ciRead, rebaseCarry) {
358
380
  // at ci-state's read is still not one of them.
359
381
  const accepted = rebaseCarry === null ? heads : new Set([...heads, rebaseCarry.accepted]);
360
382
  if (prView !== null) {
361
- if (!prView.labels.some((l) => l.name === "ready-to-merge")) return blocked("label-pulled");
383
+ if (!prView.labels.some((l) => l.name === ready)) return blocked("label-pulled");
362
384
  if (prView.reviewDecision === "CHANGES_REQUESTED") return blocked("changes-requested");
363
385
  if (!accepted.has(prView.headRefOid)) return blocked("head-moved-after-label");
364
386
  }