@feigi/fleet-ctl 3.126.0 → 3.127.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.126.0",
3
+ "version": "3.127.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": {
@@ -36,6 +36,7 @@ import { RECEIPT, RECEIPT_HELD, CLOSEOUT_RECEIPT, OBJECTIVES, isOmpSessionDirNam
36
36
  import { lastSegment } from "./pull-attribution.mjs";
37
37
  import { NAME, warnOnce, execRead } from "./board-common.mjs";
38
38
  import { mergedReadPrs, issuesOfPrs } from "./compute-board.mjs";
39
+ import { repoIdentity } from "./compute-cell-evidence.mjs";
39
40
  import { readCostGuard } from "./fleet-tick.mjs";
40
41
  import { parseFrontmatter } from "./tier-roles.mjs";
41
42
  import { isImplementer } from "./member-outcomes.mjs";
@@ -103,9 +104,9 @@ async function tryRun(cmd, args) {
103
104
  // for the `gh ... list` reads, gather()'s `--prev` read demands
104
105
  // an object, and gather()'s ledger branch takes any shape ledger.mjs emits,
105
106
  // deliberately, for the reason stated there. A shape policy could not be written
106
- // in here anyway: `fallback` is `[]` where the open-PR read calls this and null where the
107
- // ledger read does, so the helper is never told what its caller wanted — only
108
- // that null is not it.
107
+ // in here anyway: `fallback` says only what a caller takes for no answer, so
108
+ // the helper is never told what shape its caller wanted — only that null is
109
+ // not it.
109
110
  //
110
111
  // Reported, and never as "parse failed": the parse succeeded, and keeping the
111
112
  // state a read reached apart from the state it failed at is what the ledger states are for.
@@ -819,6 +820,44 @@ export function readGuardFile(stateDir) {
819
820
  return readCostGuard(join(stateDir, "cost-guard.json"));
820
821
  }
821
822
 
823
+ // The guard file as parsed, for the one alert that compares what the router's
824
+ // reader and the tick's make of the same bytes (`parseGuard`, `costGuardFault`):
825
+ // null when it is missing or will not parse, which both readers refuse alike.
826
+ export function readGuardJson(stateDir) {
827
+ try { return JSON.parse(readFileSync(join(stateDir, "cost-guard.json"), "utf8")); } catch { return null; }
828
+ }
829
+
830
+ // The last close-out's metrics PR, off `.fleet/closeout.json`: `{ number, at }`,
831
+ // `at` the time its `commit-and-pr` step finished (null when the step has none),
832
+ // or null for no receipt, one that will not read or one with no PR. The receipt
833
+ // keeps the PR as `gh pr create` printed it, its url.
834
+ export function readCloseoutPr(stateDir) {
835
+ let receipt;
836
+ try { receipt = JSON.parse(readFileSync(join(stateDir, CLOSEOUT_RECEIPT), "utf8")); } catch { return null; }
837
+ if (!isJsonObject(receipt) || typeof receipt.pr !== "string") return null;
838
+ const number = /(?:\/pull\/|^#?)(\d+)\s*$/.exec(receipt.pr.trim())?.[1];
839
+ if (number === undefined) return null;
840
+ const at = isJsonObject(receipt.steps) && isJsonObject(receipt.steps["commit-and-pr"]) ? receipt.steps["commit-and-pr"].at : null;
841
+ return { number: Number(number), at: typeof at === "string" ? at : null };
842
+ }
843
+
844
+ // The checkout's own router table, `plugin/scripts/router-table.json` under the
845
+ // workspace (the directory `stateDir` is in), as the installed one is read:
846
+ // `{ status: "ok", table }`, `{ status: "missing" }` (no such file: a consumer's
847
+ // checkout) or `{ status: "unreadable", why }`. Never warns: the installed
848
+ // table's read does, and a consumer is not at fault for lacking this file.
849
+ export function readCheckoutTable(stateDir) {
850
+ let text;
851
+ try {
852
+ text = readFileSync(join(dirname(stateDir), "plugin", "scripts", "router-table.json"), "utf8");
853
+ } catch (e) {
854
+ return e.code === "ENOENT" ? { status: "missing" } : { status: "unreadable", why: e.code ?? e.message };
855
+ }
856
+ let table;
857
+ try { table = validateTable(JSON.parse(text)); } catch { return { status: "unreadable", why: "not JSON" }; }
858
+ return table instanceof Error ? { status: "unreadable", why: table.message } : { status: "ok", table };
859
+ }
860
+
822
861
  // The Preview fit metrics-refresh.mjs writes beside the guard,
823
862
  // `.fleet/router-preview.json`: `{ status: "ok", preview }`, `{ status: "missing" }`
824
863
  // or `{ status: "unreadable", why }`. Its `table` is read through `validateTable`,
@@ -915,6 +954,42 @@ export function readObjective(stateDir) {
915
954
  return read.state === "ok" && OBJECTIVES.includes(read.receipt.objective) ? read.receipt.objective : null;
916
955
  }
917
956
 
957
+ // The `docs/metrics` contents call is read at most once in this many
958
+ // milliseconds, as `modelRoles` is: it is one more child spawn and a network
959
+ // round trip per read.
960
+ export const MAIN_METRICS_EVERY_MS = 60_000;
961
+
962
+ // A contents call that has not answered in this many milliseconds is killed and
963
+ // reported as a failed read, for `MODEL_ROLES_TIMEOUT_MS`'s reason.
964
+ export const MAIN_METRICS_TIMEOUT_MS = 10_000;
965
+
966
+ // The blob id of each file main holds under `docs/metrics`:
967
+ // `gh api --hostname <host> repos/<owner>/<name>/contents/docs/metrics`, with
968
+ // `id` the workspace's `{ host, name }` (repoIdentity of `repoUrl`). Never the
969
+ // `repos/{owner}/{repo}` placeholder: in a checkout whose remote is on a
970
+ // GitHub Enterprise host `gh api` sends that to api.github.com, which answers
971
+ // 404. `{ ok: true, value: { blobs } }`, `blobs` null when the host answers 404
972
+ // (main holds no metrics yet), or `{ ok: false, why }`.
973
+ export async function readMainMetrics(id, timeout = MAIN_METRICS_TIMEOUT_MS) {
974
+ const argv = ["api", "--hostname", id.host, `repos/${id.name}/contents/docs/metrics`];
975
+ const r = await execRead("gh", argv, { timeout });
976
+ if (r.error) {
977
+ const message = String(r.error.message ?? "");
978
+ if (/\(HTTP 404\)/.test(message)) return { ok: true, value: { blobs: null } };
979
+ const how = r.code ?? (r.signal ? `killed by ${r.signal}` : `exit ${r.status}`);
980
+ const said = message.split("\n").slice(1).find((l) => l.trim() !== "");
981
+ return { ok: false, why: `gh ${argv.join(" ")} failed (${how}${said ? `: ${said.trim()}` : ""})` };
982
+ }
983
+ let listing;
984
+ try { listing = JSON.parse(r.stdout); } catch { return { ok: false, why: `gh ${argv.join(" ")} printed non-JSON` }; }
985
+ if (!Array.isArray(listing)) return { ok: false, why: `gh ${argv.join(" ")} printed no directory listing` };
986
+ const blobs = {};
987
+ for (const f of listing) {
988
+ if (isJsonObject(f) && f.type === "file" && typeof f.path === "string" && typeof f.sha === "string") blobs[f.path] = f.sha;
989
+ }
990
+ return { ok: true, value: { blobs } };
991
+ }
992
+
918
993
  // `modelRoles` is read at most once in this many milliseconds: it is one more
919
994
  // child spawn per read, and a role changes rarely.
920
995
  export const MODEL_ROLES_EVERY_MS = 60_000;
@@ -952,18 +1027,39 @@ function heldRead(c) {
952
1027
  return okValue && okAt && okError ? { value: c.value, readAt: c.readAt, error: c.error } : null;
953
1028
  }
954
1029
 
955
- // The carried `modelRoles` read, read again only when its last attempt, a
956
- // success or a failure, is a minute old or more. A failed read keeps the value
1030
+ // A carried read, read again only when its last attempt, a success or a
1031
+ // failure, is `every` milliseconds old or more. A failed read keeps the value
957
1032
  // carried, with the failure beside it: `readAt` stays the time the value was read.
958
- export async function carryModelRoles(carried, now, read = readModelRoles) {
959
- const held = heldRead(carried) ?? { value: null, readAt: null, error: null };
1033
+ async function carry(held, now, read, every) {
960
1034
  const lastTried = Math.max(held.readAt ?? -Infinity, held.error?.at ?? -Infinity);
961
1035
  const age = now - lastTried;
962
- if (age >= 0 && age < MODEL_ROLES_EVERY_MS) return held;
1036
+ if (age >= 0 && age < every) return held;
963
1037
  const r = await read();
964
1038
  return r.ok ? { value: r.value, readAt: now, error: null } : { ...held, error: { at: now, message: r.why } };
965
1039
  }
966
1040
 
1041
+ const NO_READ = Object.freeze({ value: null, readAt: null, error: null });
1042
+
1043
+ // The carried `modelRoles` read, read again only when its last attempt, a
1044
+ // success or a failure, is a minute old or more.
1045
+ export async function carryModelRoles(carried, now, read = readModelRoles) {
1046
+ return carry(heldRead(carried) ?? NO_READ, now, read, MODEL_ROLES_EVERY_MS);
1047
+ }
1048
+
1049
+ // The carried `docs/metrics` contents call, the same way: `value` is `{ blobs }`,
1050
+ // `blobs` null for a 404 and otherwise main's blob id by path. A workspace whose
1051
+ // repository the cockpit cannot name has nothing to ask `gh api` about, and says
1052
+ // so as a failed read, with no call.
1053
+ export async function carryMainMetrics(carried, now, repoUrl, read = readMainMetrics) {
1054
+ let held = heldRead(carried);
1055
+ const blobs = held?.value?.blobs;
1056
+ if (held !== null && held.value !== null && !(blobs === null || (isJsonObject(blobs) && Object.values(blobs).every((s) => typeof s === "string")))) held = null;
1057
+ held ??= NO_READ;
1058
+ const id = repoIdentity(repoUrl);
1059
+ if (id === null) return { ...held, error: { at: now, message: "this workspace's repository is not known" } };
1060
+ return carry(held, now, () => read(id), MAIN_METRICS_EVERY_MS);
1061
+ }
1062
+
967
1063
  // `workspace`/`port` are the caller's answers, never read in here:
968
1064
  // resolveCockpitInstance() already decided both, and a second derivation in
969
1065
  // this function could disagree with the one the server actually bound. They
@@ -1110,8 +1206,7 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir
1110
1206
  // but unable to describe itself reads as its number rather than literal
1111
1207
  // `undefined` on the operator's page.
1112
1208
  //
1113
- // Its null fallback, not the open-PR read's `[]` below, is deliberate:
1114
- // this read is the pool's ONLY source, and
1209
+ // Its null fallback is deliberate: this read is the pool's ONLY source, and
1115
1210
  // compute-board.mjs's stall() needs to tell a genuinely empty pool from a
1116
1211
  // `gh` outage the same way it already tells an empty ledger from an unread
1117
1212
  // one — a `[]` fallback collapses both to the identical shape before a
@@ -1137,9 +1232,15 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir
1137
1232
  // only consumer is `pr.state === "OPEN"` (compute-board.mjs), already false
1138
1233
  // for `undefined` exactly as it was for the old "UNKNOWN" sentinel, so the
1139
1234
  // default was inert — pure indirection with no behaviour to show for it.
1140
- const prsParsed = tryParse(prsJson, [], "gh pr list");
1235
+ // A null fallback for the same reason as the pool read's: the Cell evidence
1236
+ // tab must tell a failed read from no open PRs, or a close-out receipt's open
1237
+ // PR reads as not open and the records-not-on-main alert states a cause it
1238
+ // never checked (`prsOk`). Everything else here takes a failed read as no
1239
+ // open PRs, as before.
1240
+ const prsParsed = tryParse(prsJson, null, "gh pr list");
1241
+ const prsOk = prsParsed !== null;
1141
1242
  const prsCapped = hitLimit(prsParsed, OPEN_PR_LIMIT);
1142
- const prs = withNumber(prsParsed, "gh pr list").map((p) => ({
1243
+ const prs = withNumber(prsOk ? prsParsed : [], "gh pr list").map((p) => ({
1143
1244
  number: p.number,
1144
1245
  state: p.state,
1145
1246
  title: p.title,
@@ -1240,16 +1341,23 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir
1240
1341
  // no workspace, so it reads none of the workspace's records and spawns no `omp`
1241
1342
  // either (a guard that reads as missing, no receipts, the read carried as it was).
1242
1343
  const guard = stateDir === null ? { status: "missing" } : readGuardFile(stateDir);
1344
+ const guardJson = stateDir === null ? null : readGuardJson(stateDir);
1243
1345
  const preview = stateDir === null ? { status: "missing" } : readPreviewFile(stateDir);
1346
+ const closeoutPr = stateDir === null ? null : readCloseoutPr(stateDir);
1347
+ const checkoutTable = stateDir === null ? { status: "missing" } : readCheckoutTable(stateDir);
1244
1348
  const receipts = stateDir === null
1245
1349
  ? { phase0: null, closeout: null }
1246
1350
  : { phase0: readMetricsStep(join(stateDir, RECEIPT)), closeout: readMetricsStep(join(stateDir, CLOSEOUT_RECEIPT)) };
1247
1351
  const agents = readAgents(scriptDir);
1248
1352
  const install = readInstall(scriptDir);
1249
1353
  const objective = stateDir === null ? null : readObjective(stateDir);
1250
- const modelRoles = stateDir === null ? heldRead(prev?.modelRoles) : await carryModelRoles(prev?.modelRoles, now);
1354
+ // Read side by side: each has its own 10 s timeout, and one after the other a
1355
+ // tick on which both hang would stall twice as long.
1356
+ const [modelRoles, mainMetrics] = stateDir === null
1357
+ ? [heldRead(prev?.modelRoles), null]
1358
+ : await Promise.all([carryModelRoles(prev?.modelRoles, now), carryMainMetrics(prev?.mainMetrics, now, repoUrl)]);
1251
1359
  return { ledger, issues, prs, merged, closed, closedIssues, ci, prev, repo, repoUrl, workspace, port, spend, beat, ticked, acted, controller, stallOwner: stallOwnerOf, poolOk,
1252
1360
  roles, labelMapError,
1253
- poolCapped, prsCapped, guard, preview, receipts, agents, modelRoles, install, objective, implementers: [...implementers.values()], routerTable,
1361
+ poolCapped, prsOk, prsCapped, guard, guardJson, preview, receipts, closeoutPr, agents, modelRoles, mainMetrics, install, objective, implementers: [...implementers.values()], routerTable, checkoutTable,
1254
1362
  now, interval };
1255
1363
  }
@@ -86,6 +86,8 @@
86
86
  #cells { padding:14px; flex:1 1 0; min-height:200px; overflow-y:auto; }
87
87
  .ce-links { color:var(--dim); margin-bottom:10px; font-size:12px; }
88
88
  .ce-links a { color:var(--blue); text-decoration:none; }
89
+ .ce-alert { border:1px solid var(--amber); border-radius:8px; padding:8px 12px; margin-bottom:12px; background:var(--panel); }
90
+ .ce-alert .ce-verdict { color:var(--amber); }
89
91
  .ce-sec { background:var(--panel); border:1px solid var(--line); border-radius:8px; padding:10px 12px; margin-bottom:12px; }
90
92
  .ce-sec h2 { font-size:11px; letter-spacing:.06em; color:var(--dim); margin:0 0 6px; text-transform:uppercase; }
91
93
  .ce-verdict { font-weight:600; }
@@ -526,11 +528,28 @@ function cePolicy(p) {
526
528
  return sec;
527
529
  }
528
530
 
531
+ // One alert at the top of the Cell evidence tab: its headline, its sentence and
532
+ // any lines under them, such as the two blob ids. The words are the model's.
533
+ function ceAlert(a) {
534
+ const box = ceBox("div", "ce-alert", "cells-alert-" + a.id);
535
+ box.append(el("div", "ce-verdict", "⚠ " + a.headline), el("div", "ce-note", a.sentence));
536
+ for (const line of a.lines || []) box.append(el("div", "ce-source", line));
537
+ return box;
538
+ }
539
+
540
+ // The tab's label, which carries `⚠n` while any alert holds, counted from the
541
+ // same list the tab draws, so an alert shows from Board too.
542
+ function cellsTabLabel(ce) {
543
+ const n = ce && Array.isArray(ce.alerts) ? ce.alerts.length : 0;
544
+ return n > 0 ? `Cell evidence ⚠${n}` : "Cell evidence";
545
+ }
546
+
529
547
  // The Cell evidence tab. The model is `m.cellEvidence`; this only lays it out.
530
548
  // Every Cell and every generation the model names is drawn, so each hash link
531
549
  // the page draws has its target.
532
550
  function renderCells(ce) {
533
551
  const host = document.getElementById("cells");
552
+ document.getElementById("tab-cells").textContent = cellsTabLabel(ce);
534
553
  if (!ce) { host.replaceChildren(el("div", "spend-wrap", "no Cell evidence in this board yet")); return; }
535
554
  const g = ce.guard;
536
555
 
@@ -560,7 +579,7 @@ function renderCells(ce) {
560
579
  dec.append(row);
561
580
  }
562
581
 
563
- host.replaceChildren(links, ...(ce.policy ? [cePolicy(ce.policy)] : []), sec, dec);
582
+ host.replaceChildren(links, ...(ce.alerts || []).map(ceAlert), ...(ce.policy ? [cePolicy(ce.policy)] : []), sec, dec);
564
583
  }
565
584
 
566
585
  function render(m) {
@@ -855,19 +855,29 @@ export function computeBoard(inputs) {
855
855
  }, now),
856
856
  attention,
857
857
  // The Cell evidence tab's model (compute-cell-evidence.mjs), built from the
858
- // guard, the receipts' metrics steps, the definitions, the installed router
859
- // table and package, the live run's Objective and the carried `modelRoles`
860
- // read gather() answered, and this run's Pulls: each card's
858
+ // guard (through the tick's reader, and as parsed, for the readers alert),
859
+ // the receipts' metrics steps and the close-out's PR beside the open PRs, the
860
+ // definitions, the installed router table and package and the checkout's, the
861
+ // live run's Objective and the carried `modelRoles` and `docs/metrics` reads
862
+ // gather() answered, and this run's Pulls: each card's
861
863
  // Cell line, booked As-routed to its Cell. A caller that read none of them
862
864
  // (every hand-built input in this suite) gets the tab's no-guard state:
863
- // computeCellEvidence reads an input left out as nothing read.
865
+ // computeCellEvidence reads an input left out as nothing read. The open PRs
866
+ // are null where gather() says the read failed (`prsOk` false), so the tab
867
+ // reads them as not read rather than as none open; `prsOk` defaults to true
868
+ // absent a signal, as `poolOk` does above.
864
869
  cellEvidence: computeCellEvidence({
865
870
  guard: inputs.guard,
871
+ guardJson: inputs.guardJson,
866
872
  preview: inputs.preview,
867
873
  receipts: inputs.receipts,
874
+ closeoutPr: inputs.closeoutPr,
875
+ openPrs: inputs.prsOk === false ? null : { numbers: (inputs.prs ?? []).map((p) => p.number), capped: inputs.prsCapped === true },
868
876
  agents: inputs.agents,
869
877
  modelRoles: inputs.modelRoles,
878
+ mainMetrics: inputs.mainMetrics,
870
879
  table: inputs.routerTable,
880
+ checkoutTable: inputs.checkoutTable,
871
881
  install: inputs.install,
872
882
  repoUrl: inputs.repoUrl,
873
883
  objective: inputs.objective,
@@ -876,5 +886,8 @@ export function computeBoard(inputs) {
876
886
  // The `omp config get modelRoles` read, carried tick to tick the way `ci`
877
887
  // and `repo` are: `{ value, readAt, error }`, read at most once a minute.
878
888
  modelRoles: inputs.modelRoles ?? null,
889
+ // The `docs/metrics` contents call, carried the same way: `{ value: { blobs },
890
+ // readAt, error }`, main's blob id by path, read at most once a minute.
891
+ mainMetrics: inputs.mainMetrics ?? null,
879
892
  };
880
893
  }
@@ -28,7 +28,8 @@
28
28
 
29
29
  import { isDeepStrictEqual } from "node:util";
30
30
  import { CELL, OBJECTIVES, POLICY_CELL, STRATA } from "./ledger-grammar.mjs";
31
- import { MIN_N, readGuard, rowDispatch } from "./ticket-router.mjs";
31
+ import { costGuardFault } from "./fleet-tick.mjs";
32
+ import { MIN_N, parseGuard, readGuard, rowDispatch } from "./ticket-router.mjs";
32
33
  import { implementerCell, modelsEqual, parseModelRoute, resolveRole } from "./tier-roles.mjs";
33
34
 
34
35
  // The implementer Cells, in the order the guard section draws them. All five are
@@ -351,7 +352,7 @@ function booked(entry, pulls) {
351
352
  // The Cells drawn: the five, then any the guard holds or a card names beyond them.
352
353
  const drawOrder = (held, pulls) => [...new Set([...CELLS, ...held, ...pulls.flatMap((p) => p.targets.map((t) => t.cell)).filter((c) => CELL.test(c))])];
353
354
 
354
- function guardSection(read, receipts, modelRoles, pulls) {
355
+ function guardSection(read, receipts, modelRoles, pulls, recordsNote = null) {
355
356
  const label = readLabel(modelRoles);
356
357
  const refresh = newestRefresh(receipts);
357
358
  const notes = [];
@@ -390,6 +391,7 @@ function guardSection(read, receipts, modelRoles, pulls) {
390
391
  if (refresh !== null && refresh.verb === "failed" && Date.parse(refresh.at) > Date.parse(g.computed_at)) {
391
392
  notes.push(`the newest refresh failed at ${when(refresh.at)}: ${refresh.why}; these figures are from ${when(g.computed_at)}`);
392
393
  }
394
+ if (recordsNote !== null) notes.push(recordsNote);
393
395
  if (label !== null) notes.push(label);
394
396
  return { state, heading, source, notes, cells, footnotes };
395
397
  }
@@ -546,18 +548,43 @@ function rowEntry(table, guard, modelRoles, objective, stratum) {
546
548
  };
547
549
  }
548
550
 
551
+ // Routes now's "installed table behind main's", for the one repository whose
552
+ // checkout holds the table the install is a release of: `label` where the
553
+ // checkout's `fitted_commit` and `n_rows` differ from the installed table's, and
554
+ // `check` where the checkout's table could not be compared. `checkout` is
555
+ // gather's read of the checkout's `plugin/scripts/router-table.json`, `{ status:
556
+ // "ok", table } | { status: "missing" } | { status: "unreadable", why }`, or
557
+ // null where nothing read it. A consumer, whose install names another repository,
558
+ // is never compared.
559
+ function behindMain(source, table, checkout) {
560
+ const none = { label: null, check: null };
561
+ if (!source.same || table === null || checkout == null) return none;
562
+ if (checkout.status === "missing") return { label: null, check: "not checked: this checkout holds no plugin/scripts/router-table.json" };
563
+ if (checkout.status !== "ok") return { label: null, check: `not checked: this checkout's router table was not read: ${checkout.why}` };
564
+ const main = checkout.table;
565
+ const commit = (t) => (t.fitted_commit ? String(t.fitted_commit) : null);
566
+ const mainAt = commit(main);
567
+ const installedAt = commit(table);
568
+ if (mainAt === installedAt && main.n_rows === table.n_rows) return none;
569
+ const on = Number.isInteger(main.n_rows) ? `on ${plural(main.n_rows, "Pull")}` : "on a number of Pulls not checked";
570
+ const fitted = mainAt === null ? "never fitted" : `fitted at ${mainAt.slice(0, 7)} ${on}`;
571
+ const routes = installedAt === null ? "a table never fitted" : installedAt.slice(0, 7);
572
+ return { label: `main's table is ${fitted}; this install routes by ${routes} until the plugin is updated`, check: null };
573
+ }
574
+
549
575
  // The routes-now side of the policy rows: its heading words and every row the
550
576
  // installed table holds, `rows[objective][stratum]` — `*` and each Stratum with a
551
577
  // row of its own. `rows` is null when no table could be read, and each of its
552
578
  // rows then reads `unread`.
553
- function routesNow({ table, guard, modelRoles, install, repoUrl }) {
579
+ function routesNow({ table, guard, modelRoles, install, repoUrl, checkout }) {
554
580
  const source = routesSource(table, install, repoUrl);
581
+ const behind = behindMain(source, table, checkout);
555
582
  const foot = source.same ? [] : [{ mark: "¹", text: "this repository's runs reach routing only through its cost guard, which can hold a Cell back but never picks one" }];
556
583
  return {
557
584
  title: "routes now",
558
- source: { text: source.text + (foot.length ? " ¹" : ""), check: source.check },
585
+ source: { text: source.text + (foot.length ? " ¹" : ""), check: source.check ?? behind.check },
559
586
  heading: routesHeading(table, guard, source),
560
- labels: [],
587
+ labels: behind.label === null ? [] : [behind.label],
561
588
  footnotes: foot,
562
589
  rows: table === null ? null : Object.fromEntries(OBJECTIVES.map((o) => [o,
563
590
  Object.fromEntries(["*", ...STRATA].filter((s) => Object.hasOwn(table.rows[o], s)).map((s) => [s, rowEntry(table, guard, modelRoles, o, s)])),
@@ -741,6 +768,121 @@ function declaredSection(agents, modelRoles) {
741
768
  return { heading: `Declared, not measured: ${n} other member${n === 1 ? "" : "s"}`, members };
742
769
  }
743
770
 
771
+ // ---------------------------------------------------------------------------
772
+ // Alerts: the state of the whole records, shown only while it holds.
773
+ // ---------------------------------------------------------------------------
774
+
775
+ // A blob id as the tab prints it.
776
+ const blob8 = (id) => (typeof id === "string" ? id.slice(0, 8) : String(id));
777
+
778
+ // Whether the close-out receipt's PR is among the open ones: null where that
779
+ // cannot be told — the open PRs not read (`openPrs` null), or a list cut short
780
+ // that does not name it.
781
+ function prIsOpen(pr, openPrs) {
782
+ if (pr === null) return false;
783
+ if (!isRecord(openPrs) || !Array.isArray(openPrs.numbers)) return null;
784
+ if (openPrs.numbers.includes(pr)) return true;
785
+ return openPrs.capped === true ? null : false;
786
+ }
787
+
788
+ // The guard's and the Preview fit's TSV blob ids against main's. `alert` is the
789
+ // alert while the records are not on main, else null; `note`, in its place, is
790
+ // a note under the guard section's heading: a check that could not run is never
791
+ // an alert, so an offline cockpit raises none. `main` is the carried read of
792
+ // `docs/metrics`, `{ value: { blobs }, readAt, error }`, `blobs` null for a 404.
793
+ // A guard that names no blob ids has nothing to compare, and neither has one
794
+ // whose cockpit read nothing (`main` null).
795
+ function recordsAgainstMain({ read, preview, main, closeoutPr, openPrs }) {
796
+ const none = { alert: null, note: null };
797
+ if (main == null || read?.status !== "ok") return none;
798
+ const g = read.guard;
799
+ const unchecked = (why) => ({ alert: null, note: `records against main: not checked: ${why}` });
800
+ if (!isRecord(g.tsv_blobs)) return unchecked("this guard predates the blob ids it needs");
801
+ if (main.error != null) {
802
+ return unchecked(`${main.error.message}; last succeeded ${main.readAt == null ? "never" : when(main.readAt)}`);
803
+ }
804
+ const blobs = isRecord(main.value) ? main.value.blobs : undefined;
805
+ if (blobs === null) return { alert: null, note: "records against main: main holds no metrics yet" };
806
+ if (!isRecord(blobs)) return unchecked("main's docs/metrics not read yet");
807
+
808
+ const mine = preview?.status === "ok" ? preview.preview : null;
809
+ const held = (ids, path) => (isRecord(ids) && Object.hasOwn(ids, path) ? ids[path] : undefined);
810
+ const paths = [...new Set([...Object.keys(g.tsv_blobs), ...(mine === null ? [] : Object.keys(mine.tsv_blobs))])].sort();
811
+ const lines = [];
812
+ let guardDiffers = false;
813
+ let fitDiffers = false;
814
+ for (const path of paths) {
815
+ const onMain = held(blobs, path);
816
+ const guardId = held(g.tsv_blobs, path);
817
+ const fitId = mine === null ? undefined : held(mine.tsv_blobs, path);
818
+ const gd = guardId !== undefined && guardId !== onMain;
819
+ const fd = fitId !== undefined && fitId !== onMain;
820
+ if (!gd && !fd) continue;
821
+ guardDiffers ||= gd;
822
+ fitDiffers ||= fd;
823
+ const said = [guardId === undefined ? null : fitId === guardId ? `the guard and the Preview fit read ${blob8(guardId)}` : `the guard read ${blob8(guardId)}`,
824
+ fitId === undefined || fitId === guardId ? null : `the Preview fit read ${blob8(fitId)}`].filter(Boolean);
825
+ lines.push(`${path}: ${said.join(", ")}; main holds ${onMain === undefined ? "none" : blob8(onMain)}`);
826
+ }
827
+ if (lines.length === 0) return none;
828
+
829
+ const both = guardDiffers && fitDiffers;
830
+ const subject = both ? "the guard and the Preview fit" : guardDiffers ? "the guard" : "the Preview fit";
831
+ const pr = Number.isInteger(closeoutPr?.number) ? closeoutPr.number : null;
832
+ const open = prIsOpen(pr, openPrs);
833
+ const computed = guardDiffers ? g.computed_at : mine.computed_at;
834
+ let sentence;
835
+ if (open === null) {
836
+ return unchecked(isRecord(openPrs)
837
+ ? `the close-out's PR #${pr} is not among the open PRs read, and that list was cut short`
838
+ : `the open PRs were not read, so whether the close-out's PR #${pr} is open is unknown`);
839
+ }
840
+ if (open) {
841
+ const committed = Date.parse(closeoutPr.at);
842
+ if (!Number.isFinite(committed)) return unchecked(`the close-out receipt records no time for PR #${pr}'s commit step`);
843
+ const built = Date.parse(computed);
844
+ if (!Number.isFinite(built)) return unchecked(`the ${guardDiffers ? "guard" : "Preview fit"} records no time it was computed`);
845
+ sentence = built <= committed
846
+ ? `${subject} ${both ? "count" : "counts"} the rows of open PR #${pr}, not on main yet`
847
+ : `${subject} ${both ? "lack" : "lacks"} the rows of open PR #${pr}`;
848
+ } else {
849
+ sentence = `main's records changed after ${when(computed)}; the next phase 0 recomputes`;
850
+ }
851
+ return { alert: { id: "records-not-on-main", headline: "Records not on main", sentence, lines }, note: null };
852
+ }
853
+
854
+ // Pulls that merged with no Ruling, per Cell, off the guard's newest generations.
855
+ function noRulingAlert(read) {
856
+ if (read?.status !== "ok") return null;
857
+ const held = read.guard.cells.map((c) => [c.cell, count(c.no_ruling)]).filter(([, k]) => k !== null && k > 0);
858
+ if (held.length === 0) return null;
859
+ return {
860
+ id: "merged-with-no-ruling",
861
+ headline: `Merged with no Ruling: ${held.map(([cell, k]) => `${cell} ${k}`).join(", ")}`,
862
+ sentence: "each counts as not merged, so n reads low and $ per merged PR high",
863
+ lines: [],
864
+ };
865
+ }
866
+
867
+ // The Router's reader and the tick's reading the same guard file differently:
868
+ // the one that accepts it, and why the other refuses. `json` is the file as
869
+ // parsed, null when missing or unparseable, which both refuse alike.
870
+ function readersAlert(json) {
871
+ if (json == null) return null;
872
+ const router = parseGuard(json);
873
+ const tickWhy = costGuardFault(json);
874
+ const tickAccepts = tickWhy === null;
875
+ if (tickAccepts === router.ok) return null;
876
+ return {
877
+ id: "guard-readers-disagree",
878
+ headline: "Guard readers disagree",
879
+ sentence: tickAccepts
880
+ ? `the tick's reader (readCostGuard) accepts the guard and the Router's (readGuard) refuses it: ${router.why}`
881
+ : `the Router's reader (readGuard) accepts the guard and the tick's (readCostGuard) refuses it: ${tickWhy}`,
882
+ lines: [],
883
+ };
884
+ }
885
+
744
886
  /**
745
887
  * The Cell evidence tab's model. `guard` is `readCostGuard`'s answer, `receipts`
746
888
  * is `{ phase0, closeout }`, each the receipt's `metrics` step `{ status, at,
@@ -758,13 +900,16 @@ function declaredSection(agents, modelRoles) {
758
900
  * read: a missing guard, no receipt, no definitions, no `modelRoles` read, no
759
901
  * Pull, no table, no install, no Objective, no Preview fit.
760
902
  */
761
- export function computeCellEvidence({ guard, receipts, agents, modelRoles = null, pulls = [], table = null, install = null, repoUrl = null, objective = null, preview = null }) {
903
+ export function computeCellEvidence({ guard, receipts, agents, modelRoles = null, pulls = [], table = null, install = null, repoUrl = null, objective = null, preview = null,
904
+ guardJson = null, mainMetrics = null, closeoutPr = null, openPrs = null, checkoutTable = null }) {
762
905
  const routed = guard?.status === "ok" ? readGuard(guard.guard) : null;
763
- const routes = routesNow({ table, guard: routed, modelRoles, install, repoUrl });
906
+ const routes = routesNow({ table, guard: routed, modelRoles, install, repoUrl, checkout: checkoutTable });
764
907
  const favours = evidenceFavours({ preview, guard, routed, table, modelRoles, mark: superscript(routes.footnotes.length + 1) });
908
+ const records = recordsAgainstMain({ read: guard, preview, main: mainMetrics, closeoutPr, openPrs });
765
909
  return {
910
+ alerts: [records.alert, noRulingAlert(guard), readersAlert(guardJson)].filter((a) => a !== null),
766
911
  policy: policyRowsView({ sides: [routes, favours], objective }),
767
- guard: guardSection(guard, receipts, modelRoles, pulls),
912
+ guard: guardSection(guard, receipts, modelRoles, pulls, records.note),
768
913
  declared: declaredSection(agents, modelRoles),
769
914
  };
770
915
  }
@@ -527,8 +527,29 @@ export function routerRows(s) {
527
527
  return row("OK", `${others.length ? others.map(vs).join("; ") : `baseline ${b.cell} ${usd(b.mean_usd)}, n=${b.n}`}; ${age}`);
528
528
  }
529
529
 
530
- // pr-cost.mjs's guard file, read as the router is to read it: anything but a
531
- // well-formed, self-consistent verdict is not one.
530
+ // What pr-cost.mjs's guard file must be for the tick to read it as a verdict, as
531
+ // the first thing it lacks, or null for a file that is one: anything but a
532
+ // well-formed, self-consistent verdict is not one. `guard` is the parsed file.
533
+ export function costGuardFault(guard) {
534
+ if (guard === null || typeof guard !== "object" || Array.isArray(guard)) return "not a JSON object";
535
+ const cellShaped = (c) => c && typeof c.cell === "string" && Number.isInteger(c.n)
536
+ && (c.mean_usd === null || typeof c.mean_usd === "number") && (c.fail_rate === null || typeof c.fail_rate === "number");
537
+ const cellWords = "a Cell entry with a string `cell`, an integer `n`, and a `mean_usd` and `fail_rate` that are numbers or null";
538
+ if (!["ok", "tripped", "none"].includes(guard.verdict)) return "`verdict` is not ok, tripped or none";
539
+ if (typeof guard.computed_at !== "string") return "`computed_at` is not a string";
540
+ if (!cellShaped(guard.baseline)) return `\`baseline\` is not ${cellWords}`;
541
+ if (!Array.isArray(guard.cells)) return "`cells` is not a list";
542
+ if (!guard.cells.every(cellShaped)) return `a \`cells\` entry is not ${cellWords}`;
543
+ if (!Number.isInteger(guard.min_n)) return "`min_n` is not an integer";
544
+ if (!Array.isArray(guard.tripped) || !guard.tripped.every((c) => typeof c === "string")) return "`tripped` is not a list of Cell names";
545
+ // The verdict is "tripped" exactly when a cell is named, and only a reported cell can be named.
546
+ if ((guard.verdict === "tripped") !== (guard.tripped.length > 0)) return "`verdict` and `tripped` disagree";
547
+ if (!guard.tripped.every((c) => guard.cells.some((x) => x.cell === c))) return "`tripped` names a Cell that `cells` does not report";
548
+ if (!(guard.retire === undefined || typeof guard.retire === "boolean")) return "`retire` is not a boolean";
549
+ return null;
550
+ }
551
+
552
+ // pr-cost.mjs's guard file, read as the router is to read it.
532
553
  export function readCostGuard(path) {
533
554
  if (path === null) return { status: "missing" };
534
555
  let text;
@@ -539,16 +560,7 @@ export function readCostGuard(path) {
539
560
  }
540
561
  let guard;
541
562
  try { guard = JSON.parse(text); } catch { return { status: "unreadable", why: "not JSON" }; }
542
- const cellShaped = (c) => c && typeof c.cell === "string" && Number.isInteger(c.n)
543
- && (c.mean_usd === null || typeof c.mean_usd === "number") && (c.fail_rate === null || typeof c.fail_rate === "number");
544
- const ok = guard && ["ok", "tripped", "none"].includes(guard.verdict) && typeof guard.computed_at === "string"
545
- && cellShaped(guard.baseline) && Array.isArray(guard.cells) && guard.cells.every(cellShaped) && Number.isInteger(guard.min_n)
546
- && Array.isArray(guard.tripped) && guard.tripped.every((c) => typeof c === "string")
547
- // The verdict is "tripped" exactly when a cell is named, and only a reported cell can be named.
548
- && (guard.verdict === "tripped") === (guard.tripped.length > 0)
549
- && guard.tripped.every((c) => guard.cells.some((x) => x.cell === c))
550
- && (guard.retire === undefined || typeof guard.retire === "boolean");
551
- return ok ? { status: "ok", guard } : { status: "unreadable", why: "not a guard verdict" };
563
+ return costGuardFault(guard) === null ? { status: "ok", guard } : { status: "unreadable", why: "not a guard verdict" };
552
564
  }
553
565
 
554
566
  export function formatLines(rows) {
@@ -14,7 +14,7 @@
14
14
  import { readdirSync, readFileSync, statSync } from "node:fs";
15
15
  import { join, basename, dirname } from "node:path";
16
16
 
17
- import { readOmpSession, normalizeModel, parseMemberName } from "./member-record.mjs";
17
+ import { readOmpSession, normalizeModel, parseMemberName, stampMs } from "./member-record.mjs";
18
18
  import { isOmpSessionDirName } from "./ledger-grammar.mjs";
19
19
  import { stripLevel } from "./tier-roles.mjs";
20
20
  import { reportFamily, reportStatus, defaultScratch } from "./report-files.mjs";
@@ -132,10 +132,12 @@ export const HALT_MS = 60 * 60 * 1000;
132
132
 
133
133
  // The controller transcript's entry instants, in epoch ms, or a string naming
134
134
  // why they cannot be had. It is not a member transcript, so a line is read for
135
- // its timestamp alone. An unparseable LAST line is a write in progress and is
136
- // skipped, as the member fold skips it; an unparseable line before it is lost
137
- // data that may have been the entry breaking a stretch, so a halt there could
138
- // not be told from the run writing, and the instants are unknown.
135
+ // its timestamp alone, under the member fold's own stamp rule (stampMs): a
136
+ // line whose stamp fails it is no instant. An unparseable LAST line is a
137
+ // write in progress and is skipped, as the member fold skips it; an
138
+ // unparseable line before it is lost data that may have been the entry
139
+ // breaking a stretch, so a halt there could not be told from the run
140
+ // writing, and the instants are unknown.
139
141
  function controllerStamps(sessionDir) {
140
142
  let text;
141
143
  try { text = readFileSync(join(dirname(sessionDir), `${basename(sessionDir)}.jsonl`), "utf8"); }
@@ -147,7 +149,7 @@ function controllerStamps(sessionDir) {
147
149
  let d;
148
150
  try { d = JSON.parse(lines[i]); }
149
151
  catch { if (i !== lines.length - 1) return "an unparseable controller transcript line"; continue; }
150
- const ms = typeof d?.timestamp === "string" ? Date.parse(d.timestamp) : NaN;
152
+ const ms = stampMs(d?.timestamp);
151
153
  if (Number.isFinite(ms)) stamps.push(ms);
152
154
  }
153
155
  return stamps;
@@ -368,8 +368,8 @@ export function foldOmpTranscript(jsonlText, filePath) {
368
368
  let input = 0, cacheWrite = 0, cacheWrite1h = 0, cacheRead = 0, output = 0, cost = 0, turns = 0;
369
369
  let sawCost = false, unsplit = false, unpriced = false;
370
370
  let malformedNonLastLines = 0;
371
- // Entries that carry a `timestamp` from which no finite instant was read;
372
- // an entry with no `timestamp` at all is ordinary and not counted.
371
+ // Entries that carry a `timestamp` that is no stamp under stampMs; an entry
372
+ // with no `timestamp` at all is ordinary and not counted.
373
373
  let unparseableStamps = 0;
374
374
  // What the transcript's END says, read for the `ending` column: the last
375
375
  // assistant turn's stopReason, whether a model fell back, whether the
@@ -393,7 +393,7 @@ export function foldOmpTranscript(jsonlText, filePath) {
393
393
  try { d = JSON.parse(raw); }
394
394
  catch { if (i !== lines.length - 1) malformedNonLastLines++; continue; }
395
395
  assertOmpShaped(d, filePath);
396
- const ms = typeof d.timestamp === "string" ? Date.parse(d.timestamp) : NaN;
396
+ const ms = stampMs(d.timestamp);
397
397
  if (Number.isFinite(ms)) stamps.push(ms);
398
398
  else if (Object.hasOwn(d, "timestamp")) unparseableStamps++;
399
399
  if (d.type === "custom" && d.customType === "session_exit") {
@@ -450,10 +450,10 @@ export function foldOmpTranscript(jsonlText, filePath) {
450
450
  if (d.type === "message" && m?.role === "user" && messageText(m).trimStart().startsWith("[budget notice]")) budgetNotice = true;
451
451
  }
452
452
  if (partFirst !== null) workParts.push([partFirst, partLast]);
453
- // `wall_s` is the span of the parseable stamps, latest minus earliest, so it
454
- // does not depend on file order and cannot go negative; an unparseable
455
- // stamp is skipped, and a transcript with none spans 0. `startedAt` is the
456
- // same earliest stamp as an ISO string, or null when none parsed.
453
+ // `wall_s` is the span of the stamps stampMs accepts, latest minus
454
+ // earliest, so it does not depend on file order and cannot go negative; any
455
+ // other stamp is skipped, and a transcript with none spans 0. `startedAt` is
456
+ // the same earliest stamp as an ISO string, or null when none was accepted.
457
457
  let earliest = Infinity, latest = -Infinity;
458
458
  for (const t of stamps) { if (t < earliest) earliest = t; if (t > latest) latest = t; }
459
459
  const span = stamps.length ? (latest - earliest) / 1000 : 0;
@@ -484,6 +484,18 @@ export function foldOmpTranscript(jsonlText, filePath) {
484
484
  };
485
485
  }
486
486
 
487
+ // A transcript entry's `timestamp` as epoch ms, or NaN when it is no stamp.
488
+ // The one stamp rule for every transcript reader: a string in the ECMAScript
489
+ // date-time form with a time of day and an explicit zone —
490
+ // `YYYY-MM-DDTHH:mm`, optional `:ss` and fractional seconds, then `Z` or
491
+ // `±HH:mm` — that Date.parse reads as a finite instant. Date.parse alone
492
+ // also reads strings such as "1" or "2026" as instants, a date-only string
493
+ // has no time of day, and a zone-less one depends on the host's time zone.
494
+ const STAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/;
495
+ export function stampMs(timestamp) {
496
+ return typeof timestamp === "string" && STAMP_RE.test(timestamp) ? Date.parse(timestamp) : NaN;
497
+ }
498
+
487
499
  // The report files one transcript tool call writes, as { file, content } with
488
500
  // `file` the written path's basename: the `write` tool's arguments, or each
489
501
  // report a `bash` call writes with a heredoc (`heredocReportWrites`). Only a
@@ -234,17 +234,30 @@ function readJson(path) {
234
234
  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
235
235
  }
236
236
 
237
- /** `cost-guard.json` reduced to what the router reads, or null when missing or unparseable. */
238
- export function readGuard(raw) {
239
- if (raw === null || typeof raw !== "object" || !Array.isArray(raw.tripped) || !Array.isArray(raw.cells)) return null;
237
+ /**
238
+ * `cost-guard.json` as the router reads it: `{ ok: true, guard }`, reduced to
239
+ * what the router reads, or `{ ok: false, why }` when it refuses the file. `raw` is the parsed
240
+ * file, `null` for one that is missing or will not parse.
241
+ */
242
+ export function parseGuard(raw) {
243
+ if (raw === null || typeof raw !== "object") return { ok: false, why: "not a JSON object" };
244
+ if (!Array.isArray(raw.tripped)) return { ok: false, why: "`tripped` is not a list" };
245
+ if (!Array.isArray(raw.cells)) return { ok: false, why: "`cells` is not a list" };
240
246
  const tripped = raw.tripped.map((t) => (typeof t === "string" ? t : t?.cell));
241
- if (tripped.some((t) => typeof t !== "string" || !CELL.test(t))) return null;
247
+ const bad = tripped.findIndex((t) => typeof t !== "string" || !CELL.test(t));
248
+ if (bad !== -1) return { ok: false, why: `\`tripped\` names ${JSON.stringify(raw.tripped[bad])}, which is not a Cell` };
242
249
  const n = {};
243
250
  for (const c of raw.cells) {
244
- if (typeof c?.cell !== "string" || !Number.isFinite(c?.n)) return null;
251
+ if (typeof c?.cell !== "string" || !Number.isFinite(c?.n)) return { ok: false, why: "a `cells` entry has no string `cell` or no finite `n`" };
245
252
  n[c.cell] = c.n;
246
253
  }
247
- return { tripped: [...new Set(tripped)].sort(), n, window_start: typeof raw.window_start === "string" ? raw.window_start : null };
254
+ return { ok: true, guard: { tripped: [...new Set(tripped)].sort(), n, window_start: typeof raw.window_start === "string" ? raw.window_start : null } };
255
+ }
256
+
257
+ /** `cost-guard.json` reduced to what the router reads, or null when missing or unparseable. */
258
+ export function readGuard(raw) {
259
+ const r = parseGuard(raw);
260
+ return r.ok ? r.guard : null;
248
261
  }
249
262
 
250
263
  /** The sizing verdict on a live B Pull: `{ stratum, src, label, usd }`, or null when it is unusable. */