@feigi/fleet-ctl 3.118.2 → 3.119.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.119.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,
@@ -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