@feigi/fleet-ctl 3.124.0 → 3.125.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.124.0",
3
+ "version": "3.125.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": {
@@ -49,6 +49,12 @@
49
49
  // nothing. Missing or unparsable is depth 0 and a
50
50
  // refresh, never a refusal: the depth only ever bounds PULLs
51
51
  // downward. A file with no `dropped` names no drops.
52
+ // labels `.fleet/labels.json` beside the shortlist, read once through
53
+ // label-map.mjs's reader: the ready-to-merge role's string picks
54
+ // the queued set out of the open PRs, and the in-progress role's
55
+ // string is the label the claimed count queries. A map that
56
+ // cannot be read refuses the tick once the stall report has
57
+ // printed, that report reading the claimed count unknown.
52
58
  // gh The open PRs, by label, by owner (author and draft flag), by
53
59
  // whether they close an issue, by GitHub's `mergeable`, and by
54
60
  // head and body — the merge queue, which PRs are owed a review,
@@ -993,7 +999,13 @@ export const pastPinDue = (st, head) => st !== undefined && st.pastPinHalt && !s
993
999
  // The states a PR-state probe answers: anything else is no answer.
994
1000
  const PR_STATES = ["OPEN", "MERGED", "CLOSED"];
995
1001
 
996
- export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, closed = new Set(), prStates = new Map()) {
1002
+ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queuedLabel, closed = new Set(), prStates = new Map()) {
1003
+ // `queuedLabel` is the tracker's string for the `ready-to-merge` role, from
1004
+ // the Label map the caller read (label-map.mjs) — this fold reads no cache.
1005
+ // A caller with no open PRs to fold has no queue to read and passes none.
1006
+ if (prs.length > 0 && typeof queuedLabel !== "string") {
1007
+ throw new TypeError("deriveRun: queuedLabel — the Label map's string for ready-to-merge — is required once there are open PRs");
1008
+ }
997
1009
  const open = new Set(prs.map((p) => p.number));
998
1010
  const { members, byPr, verdicts, claimed, excluded } = foldLedger({ rows, dispatched }, open);
999
1011
  // `## Retired` lines as every reader reads them: a line's name before its
@@ -1078,7 +1090,7 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, closed
1078
1090
  const owedReplacement = newest.filter(owesReplacement).map((m) => m.name);
1079
1091
  const owedCounted = newest.filter((m) => owesReplacement(m) && !closed.has(m.number)).map((m) => m.name);
1080
1092
  const inFlightImpl = newest.filter((m) => m.outcome === null && !closing.has(m.number)).length + owedCounted.length;
1081
- const isQueued = (p) => p.labels.some((l) => l && l.name === "ready-to-merge");
1093
+ const isQueued = (p) => p.labels.some((l) => l && l.name === queuedLabel);
1082
1094
  const queued = prs.filter(isQueued);
1083
1095
  const asc = (a, b) => a - b;
1084
1096
  const state = (n) => byPr.get(n);
@@ -1542,6 +1554,7 @@ import { makeDie, isDigits } from "./arg.mjs";
1542
1554
  import { gitEnv } from "./git-env.mjs";
1543
1555
  import { ghAliasedRead } from "./gh-aliased-read.mjs";
1544
1556
  import { fleetFile, FleetDirUnresolvable, scratchRoot } from "./fleet-dir.mjs";
1557
+ import { LABEL_MAP_FILE, LabelMapUnreadable, readLabelMap } from "./label-map.mjs";
1545
1558
  import { statePath, readState, writeState, assessBeat, isStalled, isReported, stallReport, stallOwner } from "./fleet-state.mjs";
1546
1559
  import { checkMainCheckout, describe } from "./main-checkout.mjs";
1547
1560
  import { readRunReceipt, phase0Gate, IN_FLIGHT_DEFAULT } from "./phase0-receipt.mjs";
@@ -1766,18 +1779,20 @@ function readLedger() {
1766
1779
  }
1767
1780
 
1768
1781
  // `.fleet/shortlist.json` beside the run's ledger, through fleet-dir.mjs's
1769
- // fleetFile(). null when unresolvable — read as a missing shortlist, and the
1770
- // refresh then says why it could not run. Announced here first: a missing
1782
+ // fleetFile(), as `{ path, fault }`. `path` is null when unresolvable — read as
1783
+ // a missing shortlist, and the refresh then says why it could not run — and
1784
+ // `fault` is then the probe's message, so the Label map beside it is refused
1785
+ // off this probe rather than a second one. Announced here first: a missing
1771
1786
  // shortlist is also what an empty queue looks like, and "outside a
1772
1787
  // repository" is not "no candidates yet". main() calls this once per tick,
1773
1788
  // so a workspace that stays unresolvable warns once per tick.
1774
1789
  function shortlistPath() {
1775
1790
  try {
1776
- return fleetFile("shortlist.json");
1791
+ return { path: fleetFile("shortlist.json"), fault: null };
1777
1792
  } catch (e) {
1778
1793
  if (!(e instanceof FleetDirUnresolvable)) throw e;
1779
1794
  console.error(`${NAME}: WARNING ${e.message}; reading the shortlist as missing`);
1780
- return null;
1795
+ return { path: null, fault: e.message };
1781
1796
  }
1782
1797
  }
1783
1798
 
@@ -2030,13 +2045,14 @@ function applyTierChecks(members, session) {
2030
2045
  return wrote;
2031
2046
  }
2032
2047
 
2033
- // How many tickets a dead run stranded. `in-progress` is the claim label
2034
- // claim-ticket.sh adds and candidates.mjs's query EXCLUDES — which is why a
2035
- // stranded ticket is invisible to the next run's scans, and why this count is
2036
- // the actionable half of the report. null for unknown, never 0: a failed query
2037
- // reporting "0 claimed" says the dead run stranded nothing.
2038
- function claimed() {
2039
- const r = spawnSync("gh", ["issue", "list", "--label", "in-progress", "--state", "open",
2048
+ // How many tickets a dead run stranded. The in-progress role is the claim
2049
+ // label claim-ticket.sh adds and candidates.mjs's query EXCLUDES — which is why
2050
+ // a stranded ticket is invisible to the next run's scans, and why this count is
2051
+ // the actionable half of the report. `label` is the Label map's string for it.
2052
+ // null for unknown, never 0: a failed query reporting "0 claimed" says the dead
2053
+ // run stranded nothing.
2054
+ function claimed(label) {
2055
+ const r = spawnSync("gh", ["issue", "list", "--label", label, "--state", "open",
2040
2056
  "--limit", String(CLAIMED_LIMIT), "--json", "number", "--jq", "length"], { encoding: "utf8", timeout: GH_TIMEOUT_MS });
2041
2057
  if (r.error || r.status !== 0) {
2042
2058
  // Disclosed, not dropped: a real gh failure must be distinguishable from
@@ -2054,6 +2070,18 @@ function claimed() {
2054
2070
  return n === CLAIMED_LIMIT ? `${n}+` : n;
2055
2071
  }
2056
2072
 
2073
+ // The claimed count the stall report prints: the in-progress string's query
2074
+ // when the Label map was read, else unknown (null) with the map's own message
2075
+ // on stderr — never 0. `map` is main()'s `{ ok: true, labels }` or
2076
+ // `{ ok: false, fault }`.
2077
+ function claimedCount(map) {
2078
+ if (!map.ok) {
2079
+ console.error(`${NAME}: ${map.fault} — claimed ticket count unknown`);
2080
+ return null;
2081
+ }
2082
+ return claimed(map.labels["in-progress"]);
2083
+ }
2084
+
2057
2085
  // What the controller record's process is now, for the phase-0 gate: `none`
2058
2086
  // with no record, else judgeRecord()'s answer. A process table that cannot
2059
2087
  // be read is `unreadable`, said on stderr under the caller's `name`: a
@@ -2077,14 +2105,14 @@ export function controllerState(controller, name = NAME) {
2077
2105
  // only about the tickets whose keyed PR read CLOSED or could not be read: OPEN
2078
2106
  // and MERGED print nothing whatever the issue says. A ledger it cannot read
2079
2107
  // refuses the tick.
2080
- function readRun(prs) {
2108
+ function readRun(prs, queuedLabel) {
2081
2109
  try {
2082
2110
  const ledger = readLedger();
2083
- const run = deriveRun(ledger, prs);
2111
+ const run = deriveRun(ledger, prs, queuedLabel);
2084
2112
  const states = prStates(run.reviewsOffList, run.prKeyed);
2085
2113
  const surfacing = run.prKeyed.filter((k) => states.get(k.pr) !== "OPEN" && states.get(k.pr) !== "MERGED").map((k) => k.n);
2086
2114
  const closed = closedTickets(run.tierMismatch, run.owedReplacement, surfacing);
2087
- return deriveRun(ledger, prs, closed, states);
2115
+ return deriveRun(ledger, prs, queuedLabel, closed, states);
2088
2116
  } catch (e) {
2089
2117
  if (e instanceof LedgerError) die(e.message);
2090
2118
  throw e;
@@ -2173,9 +2201,32 @@ function readPulls(scratch, heads, { session, now, staleMinutes }) {
2173
2201
  return out;
2174
2202
  }
2175
2203
 
2204
+ // The Label map beside the shortlist, as `{ ok: true, labels }` or
2205
+ // `{ ok: false, fault }`: an unresolvable workspace is refused off
2206
+ // shortlistPath()'s own probe, and a map that cannot be read with the
2207
+ // reader's message, which names `label-map.mjs ensure`.
2208
+ function labelMapBeside({ path, fault }) {
2209
+ if (path === null) return { ok: false, fault };
2210
+ try {
2211
+ return { ok: true, labels: readLabelMap({ file: join(dirname(path), LABEL_MAP_FILE) }) };
2212
+ } catch (e) {
2213
+ if (!(e instanceof LabelMapUnreadable)) throw e;
2214
+ return { ok: false, fault: e.message };
2215
+ }
2216
+ }
2217
+
2176
2218
  function main() {
2177
2219
  const { fold, apply, state: path, liveness, scratch: scratchFlag, session: sessionFlag, noTranscriptAfter, pullStaleMinutes, ...caps } = options();
2178
- const listPath = shortlistPath();
2220
+ const shortlist = shortlistPath();
2221
+ const listPath = shortlist.path;
2222
+ // The tracker's strings for the two roles the tick reads: `ready-to-merge`
2223
+ // (the queued set) and `in-progress` (the claimed count), read once here from
2224
+ // the Label map beside the shortlist. A map that cannot be read is held
2225
+ // until the stall report below has printed — it reads no map for anything
2226
+ // but the claimed count, which it then reports unknown — and refuses the
2227
+ // tick after it: with no strings the queue is unknown, never empty, and the
2228
+ // claimed count is unknown, never 0.
2229
+ const map = labelMapBeside(shortlist);
2179
2230
  const current = readShortlist(listPath);
2180
2231
  // Beside the shortlist, off the same git probe rather than a second one.
2181
2232
  const router = readCostGuard(listPath === null ? null : join(dirname(listPath), "cost-guard.json"));
@@ -2203,9 +2254,11 @@ function main() {
2203
2254
  if (!priorState.degraded) writeState(path, NAME, priorState, { ticked: { at: tickedAt } });
2204
2255
  if (isReported(verdict)) {
2205
2256
  console.log(stallReport(verdict, isStalled(verdict)
2206
- ? { claimed: claimed(), supply: current.scanned, owner: stallOwner(priorState.controller, NAME) }
2257
+ ? { claimed: claimedCount(map), supply: current.scanned, owner: stallOwner(priorState.controller, NAME) }
2207
2258
  : {}));
2208
2259
  }
2260
+ if (!map.ok) die(`${map.fault} — the queued set and the claimed count cannot be read, so the run cannot be reconciled`);
2261
+ const { labels } = map;
2209
2262
 
2210
2263
  // This run's phase 0, off its receipt: unfinished holds the same rows the
2211
2264
  // main checkout does, and never refuses the tick either. Judged against
@@ -2230,7 +2283,7 @@ function main() {
2230
2283
  // lines are the exception, printed as each duty runs: they say what was
2231
2284
  // done, which is true whether or not the reconcile after them lands.
2232
2285
  const prs = openPrs();
2233
- let run = readRun(prs);
2286
+ let run = readRun(prs, labels["ready-to-merge"]);
2234
2287
 
2235
2288
  // The main checkout against the run's baseline, on every tick — the
2236
2289
  // backstop for what member-write-guard cannot see. Never a refusal of the tick:
@@ -2259,7 +2312,7 @@ function main() {
2259
2312
  ...caps, ...run, heads: unclaimed(current.entries, run), supply: current.scanned, dropped: current.dropped,
2260
2313
  shortlistStatus: current.status, refresh: null, mainCheckout, phase0, router,
2261
2314
  }), run.tierUnchecked);
2262
- if (unchecked.length && applyTierChecks(unchecked, phase0.session)) run = readRun(prs);
2315
+ if (unchecked.length && applyTierChecks(unchecked, phase0.session)) run = readRun(prs, labels["ready-to-merge"]);
2263
2316
  }
2264
2317
 
2265
2318
  // The scratch root of the report files and the Pull records alike.
@@ -357,7 +357,6 @@ function createdPrNumbers(text) {
357
357
  // numbers in first-seen order.
358
358
  export function foldOmpTranscript(jsonlText, filePath) {
359
359
  let model = null, thinking = null, task = null, resolvedModelIdentity = null, agent = null;
360
- let firstTs = null;
361
360
  // For the `work_s` column (member-outcomes.mjs): every timestamped entry's
362
361
  // instant, and the member's working parts — each run of timestamped entries
363
362
  // between two `session_exit` entries, as [first, last] in epoch ms. The
@@ -368,6 +367,9 @@ export function foldOmpTranscript(jsonlText, filePath) {
368
367
  let input = 0, cacheWrite = 0, cacheWrite1h = 0, cacheRead = 0, output = 0, cost = 0, turns = 0;
369
368
  let sawCost = false, unsplit = false, unpriced = false;
370
369
  let malformedNonLastLines = 0;
370
+ // Entries that carry a `timestamp` from which no finite instant was read;
371
+ // an entry with no `timestamp` at all is ordinary and not counted.
372
+ let unparseableStamps = 0;
371
373
  // What the transcript's END says, read for the `ending` column: the last
372
374
  // assistant turn's stopReason, whether a model fell back, whether the
373
375
  // session exited cleanly, whether a budget notice reached the member, and
@@ -390,9 +392,9 @@ export function foldOmpTranscript(jsonlText, filePath) {
390
392
  try { d = JSON.parse(raw); }
391
393
  catch { if (i !== lines.length - 1) malformedNonLastLines++; continue; }
392
394
  assertOmpShaped(d, filePath);
393
- let ms = NaN;
394
- if (typeof d.timestamp === "string") { firstTs ??= d.timestamp; ms = Date.parse(d.timestamp); }
395
+ const ms = typeof d.timestamp === "string" ? Date.parse(d.timestamp) : NaN;
395
396
  if (Number.isFinite(ms)) stamps.push(ms);
397
+ else if (Object.hasOwn(d, "timestamp")) unparseableStamps++;
396
398
  if (d.type === "custom" && d.customType === "session_exit") {
397
399
  sessionExit = true;
398
400
  if (partFirst !== null) workParts.push([partFirst, partLast]);
@@ -449,10 +451,12 @@ export function foldOmpTranscript(jsonlText, filePath) {
449
451
  if (partFirst !== null) workParts.push([partFirst, partLast]);
450
452
  // `wall_s` is the span of the parseable stamps, latest minus earliest, so it
451
453
  // does not depend on file order and cannot go negative; an unparseable
452
- // stamp is skipped, and a transcript with none spans 0.
454
+ // stamp is skipped, and a transcript with none spans 0. `startedAt` is the
455
+ // same earliest stamp as an ISO string, or null when none parsed.
453
456
  let earliest = Infinity, latest = -Infinity;
454
457
  for (const t of stamps) { if (t < earliest) earliest = t; if (t > latest) latest = t; }
455
458
  const span = stamps.length ? (latest - earliest) / 1000 : 0;
459
+ const startedAt = stamps.length ? new Date(earliest).toISOString() : null;
456
460
  return {
457
461
  model, thinking, task, resolvedModelIdentity, agent,
458
462
  input, cacheWrite, cacheRead, output,
@@ -470,8 +474,9 @@ export function foldOmpTranscript(jsonlText, filePath) {
470
474
  wallS: Math.round(span),
471
475
  entries,
472
476
  malformedNonLastLines,
477
+ unparseableStamps,
473
478
  openedPrs: [...openedPrs],
474
- startedAt: firstTs,
479
+ startedAt,
475
480
  stamps, workParts,
476
481
  reportWrites,
477
482
  lastStopReason, providerFallback, sessionExit, budgetNotice,
@@ -915,6 +920,7 @@ export function readOmpSession(sessionDir, activity = null) {
915
920
  lastStopReason: folded.lastStopReason, providerFallback: folded.providerFallback,
916
921
  sessionExit: folded.sessionExit, budgetNotice: folded.budgetNotice,
917
922
  malformedNonLastLines: folded.malformedNonLastLines,
923
+ unparseableStamps: folded.unparseableStamps,
918
924
  hasYield: existsSync(file.replace(/\.jsonl$/, ".md")),
919
925
  timed: folded.stamps.length > 0, workParts: folded.workParts,
920
926
  } });
@@ -67,8 +67,13 @@
67
67
  // so each is one rotate carried.
68
68
  // Exit 0 answered; 2 a list that did not answer — a gh or git failure, a
69
69
  // list at its cap, which may hold more than it showed, a worktree path
70
- // whose presence cannot be told, or a ledger that cannot be read. Never read
71
- // 2 as nothing stranded.
70
+ // whose presence cannot be told, or a ledger that cannot be read — and no
71
+ // valid Label map (the reader's message names label-map.mjs `ensure`). Never
72
+ // read 2 as nothing stranded.
73
+ //
74
+ // `in-progress` above is a Label role (label-map.mjs): the Label map's string
75
+ // for it is the one the issue list is filtered by and the one a claim's
76
+ // labels are compared against. The map is read once, at the start of main().
72
77
 
73
78
  import { spawnSync } from "node:child_process";
74
79
  import { realpathSync, statSync } from "node:fs";
@@ -77,12 +82,13 @@ import { fileURLToPath } from "node:url";
77
82
  import { makeDie, writeAll } from "./arg.mjs";
78
83
  import { gitEnv } from "./git-env.mjs";
79
84
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
85
+ import { LABEL_MAP_FILE, LabelMapUnreadable, readLabelMap } from "./label-map.mjs";
80
86
  import { readState, stateFileIn } from "./fleet-state.mjs";
81
87
  import { liveOnLedger } from "./ledger-grammar.mjs";
82
88
 
83
89
  const NAME = "stranded";
84
90
  const die = makeDie(NAME);
85
- const LABEL = "in-progress";
91
+ const ROLE = "in-progress";
86
92
  const LIMIT = 1000;
87
93
  const GH_TIMEOUT_MS = 20_000;
88
94
  const GIT_TIMEOUT_MS = 20_000;
@@ -287,6 +293,15 @@ function main() {
287
293
  if (!(e instanceof FleetDirUnresolvable)) throw e;
288
294
  die(e.message);
289
295
  }
296
+ // The tracker's string for the in-progress role. A map that cannot be read
297
+ // is exit 2 like every list that did not answer — never an empty claim list.
298
+ let label;
299
+ try {
300
+ label = readLabelMap({ file: join(fleetDir, LABEL_MAP_FILE) })[ROLE];
301
+ } catch (e) {
302
+ if (!(e instanceof LabelMapUnreadable)) throw e;
303
+ die(e.message);
304
+ }
290
305
  const checkout = dirname(fleetDir);
291
306
 
292
307
  // readState() announces a file it could not use on stderr and returns no
@@ -298,8 +313,8 @@ function main() {
298
313
 
299
314
  // An ancestor's in-progress claims are not listed, so neither list is asked
300
315
  // for them: the open PR list waits for the first claim that needs it.
301
- const issues = ancestor ? [] : ghList(`list of open ${LABEL} issues`, [
302
- "issue", "list", "--label", LABEL, "--state", "open", "--json", "number,title,url,closedByPullRequestsReferences",
316
+ const issues = ancestor ? [] : ghList(`list of open ${ROLE} issues`, [
317
+ "issue", "list", "--label", label, "--state", "open", "--json", "number,title,url,closedByPullRequestsReferences",
303
318
  ]);
304
319
  let openPrs = null;
305
320
  const open = () => {
@@ -391,7 +406,7 @@ function main() {
391
406
  if (ancestor) why += `, and so is whether ${c.slug} is the earlier run's live member — check it against carried`;
392
407
  } else {
393
408
  if (issue.state !== "OPEN") continue;
394
- if (issue.labels.some((l) => l.name === LABEL)) continue;
409
+ if (issue.labels.some((l) => l.name === label)) continue;
395
410
  const found = prsFor(issue, segment(c.n));
396
411
  if (found.held.length > 0) {
397
412
  heldLog(c.n, found.held);