@feigi/fleet-ctl 3.111.1 → 3.112.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.111.1",
3
+ "version": "3.112.1",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -67,9 +67,12 @@ export const READ_OPTS = { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 };
67
67
  // `err.code` (measured: `3`, a number), where the sync one carried `ENOENT` /
68
68
  // `ENOBUFS` there and the exit code in `status`, and board-gather.mjs's runCiState()
69
69
  // reads all three to tell those causes apart.
70
- export function execRead(cmd, args) {
70
+ //
71
+ // `opts` joins READ_OPTS for one read, e.g. a `timeout`: a child killed by it
72
+ // is reported like any other kill, its `signal` set.
73
+ export function execRead(cmd, args, opts = {}) {
71
74
  return new Promise((resolve) => {
72
- execFile(cmd, args, READ_OPTS, (err, stdout, stderr) => {
75
+ execFile(cmd, args, { ...READ_OPTS, ...opts }, (err, stdout, stderr) => {
73
76
  if (stderr) process.stderr.write(stderr);
74
77
  resolve(err
75
78
  ? {
@@ -28,15 +28,17 @@
28
28
  // running server; either way it has to follow the next run's receipt.
29
29
  // `--spend-dir <path>` overrides the receipt outright.
30
30
 
31
- import { readFileSync, existsSync, statSync } from "node:fs";
31
+ import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
32
32
  import { computeSpend, attributeTools, mergeTools } from "./compute-spend.mjs";
33
33
  import {
34
34
  isOmpSessionDirName, ompSessionTranscripts, foldOmpTranscript, ompMemberRecord,
35
35
  } from "./member-record.mjs";
36
36
  import { readReceipt } from "./phase0-receipt.mjs";
37
- import { RECEIPT } from "./ledger-grammar.mjs";
37
+ import { RECEIPT, CLOSEOUT_RECEIPT } from "./ledger-grammar.mjs";
38
38
  import { NAME, warnOnce, execRead } from "./board-common.mjs";
39
39
  import { mergedReadPrs, issuesOfPrs } from "./compute-board.mjs";
40
+ import { readCostGuard } from "./fleet-tick.mjs";
41
+ import { parseFrontmatter } from "./tier-roles.mjs";
40
42
  // The heartbeat's liveness mark and the controller record beside it, read here
41
43
  // and never written: the heartbeat is the mark's only writer and
42
44
  // `ledger.mjs rotate` the record's. stallOwner() reads the process table to
@@ -659,6 +661,101 @@ function readOmpSpend(dir, sinceMs) {
659
661
  return { agents, toolTables, skipped, damaged };
660
662
  }
661
663
 
664
+ // The Cell evidence tab's reads. Each is the whole of one input, kept apart from
665
+ // gather() so a test drives it alone; none of them throws, and a failure is
666
+ // reported in the value, which the tab words.
667
+
668
+ // The guard in the cockpit's own state directory, through the reader the tick
669
+ // judges the file by: only a guard it accepts shows figures.
670
+ export function readGuardFile(stateDir) {
671
+ return readCostGuard(join(stateDir, "cost-guard.json"));
672
+ }
673
+
674
+ // A receipt's `metrics` step, `{ status, at, output }`, or null: no receipt, one
675
+ // that will not read, or one with no such step. Both receipts, `phase0.json` and
676
+ // `closeout.json`, carry `steps: { <name>: { status, at, output } }` and nothing
677
+ // else in common (phase0-receipt.mjs's readReceipt requires a `run` and a
678
+ // `session` that close-out's does not have), so only that is read.
679
+ export function readMetricsStep(path) {
680
+ let receipt;
681
+ try { receipt = JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
682
+ const step = isJsonObject(receipt) && isJsonObject(receipt.steps) ? receipt.steps.metrics : null;
683
+ if (!isJsonObject(step) || typeof step.status !== "string") return null;
684
+ return { status: step.status, at: step.at, output: typeof step.output === "string" ? step.output : "" };
685
+ }
686
+
687
+ // The installed definitions, `../agents/*.agent.md` from the script's directory:
688
+ // `{ list: [{ file, model }], error }`. `model` is the file's own `model:` value,
689
+ // null where it has none. A directory that cannot be listed is `error`, not an
690
+ // empty list: no definitions read is not no definitions.
691
+ export function readAgents(scriptDir) {
692
+ const dir = join(scriptDir, "..", "agents");
693
+ let files;
694
+ try {
695
+ files = readdirSync(dir).filter((f) => f.endsWith(".agent.md"));
696
+ } catch (e) {
697
+ return { list: [], error: `${dir}: ${e.code ?? e.message}` };
698
+ }
699
+ const list = [];
700
+ for (const file of files) {
701
+ try {
702
+ list.push({ file, model: parseFrontmatter(readFileSync(join(dir, file), "utf8")).model });
703
+ } catch (e) {
704
+ return { list: [], error: `${join(dir, file)}: ${e.code ?? e.message}` };
705
+ }
706
+ }
707
+ return { list, error: null };
708
+ }
709
+
710
+ // `modelRoles` is read at most once in this many milliseconds: it is one more
711
+ // child spawn per read, and a role changes rarely.
712
+ export const MODEL_ROLES_EVERY_MS = 60_000;
713
+
714
+ // A `modelRoles` read that has not answered in this many milliseconds is killed
715
+ // and reported as a failed read: gather() awaits it inside the tick, so a hung
716
+ // `omp` would otherwise hold every tick after it, not just this tab's.
717
+ export const MODEL_ROLES_TIMEOUT_MS = 10_000;
718
+
719
+ // `omp config get modelRoles --json`, in the cockpit's own environment, which can
720
+ // differ from the controller's. `{ ok: true, value }` with the record, or
721
+ // `{ ok: false, why }`.
722
+ export async function readModelRoles(timeout = MODEL_ROLES_TIMEOUT_MS) {
723
+ const argv = ["config", "get", "modelRoles", "--json"];
724
+ const r = await execRead("omp", argv, { timeout });
725
+ if (r.error) {
726
+ const how = r.code ?? (r.signal ? `killed by ${r.signal}` : `exit ${r.status}`);
727
+ return { ok: false, why: `omp ${argv.join(" ")} failed (${how})` };
728
+ }
729
+ let value;
730
+ try { value = JSON.parse(r.stdout)?.value; } catch { return { ok: false, why: `omp ${argv.join(" ")} printed non-JSON` }; }
731
+ if (!isJsonObject(value)) return { ok: false, why: `omp ${argv.join(" ")} printed no modelRoles record` };
732
+ return { ok: true, value };
733
+ }
734
+
735
+ // A carried `{ value, readAt, error }` read, as a previous board.json holds it, or
736
+ // null when it is anything else: the file can be hand-edited or older than this
737
+ // shape, and a carried value nobody validated is a value the page would trust.
738
+ // `error` is `{ at, message }` or null.
739
+ function heldRead(c) {
740
+ if (!isJsonObject(c)) return null;
741
+ const okValue = c.value === null || isJsonObject(c.value);
742
+ const okAt = c.readAt === null || Number.isFinite(c.readAt);
743
+ const okError = c.error === null || (isJsonObject(c.error) && Number.isFinite(c.error.at) && typeof c.error.message === "string");
744
+ return okValue && okAt && okError ? { value: c.value, readAt: c.readAt, error: c.error } : null;
745
+ }
746
+
747
+ // The carried `modelRoles` read, read again only when its last attempt, a
748
+ // success or a failure, is a minute old or more. A failed read keeps the value
749
+ // carried, with the failure beside it: `readAt` stays the time the value was read.
750
+ export async function carryModelRoles(carried, now, read = readModelRoles) {
751
+ const held = heldRead(carried) ?? { value: null, readAt: null, error: null };
752
+ const lastTried = Math.max(held.readAt ?? -Infinity, held.error?.at ?? -Infinity);
753
+ const age = now - lastTried;
754
+ if (age >= 0 && age < MODEL_ROLES_EVERY_MS) return held;
755
+ const r = await read();
756
+ return r.ok ? { value: r.value, readAt: now, error: null } : { ...held, error: { at: now, message: r.why } };
757
+ }
758
+
662
759
  // `workspace`/`port` are the caller's answers, never read in here:
663
760
  // resolveCockpitInstance() already decided both, and a second derivation in
664
761
  // this function could disagree with the one the server actually bound. They
@@ -684,7 +781,12 @@ function readOmpSpend(dir, sinceMs) {
684
781
  // belongs to serve()'s HTTP server, which shares this process — see execRead's
685
782
  // note in board-common.mjs for what the synchronous version cost. `build` awaits it and is
686
783
  // otherwise unchanged: one gather per process, nothing else waiting on it.
687
- export async function gather({ ledgerFile, prevFile, stateFile = null, scriptDir = SCRIPT_DIR, interval, workspace = null, port = null, spendDir, spendDirExplicit = false, spendSince = null }) {
784
+ //
785
+ // `stateDir` is the workspace's `.fleet` directory, where the cost guard and the
786
+ // receipts the Cell evidence tab reads live. Null, as with `stateFile`, says no
787
+ // caller named one: that tab is then built from no guard and no receipt, and the
788
+ // cockpit's `omp` is not asked for `modelRoles`.
789
+ export async function gather({ ledgerFile, prevFile, stateFile = null, stateDir = null, scriptDir = SCRIPT_DIR, interval, workspace = null, port = null, spendDir, spendDirExplicit = false, spendSince = null }) {
688
790
  // The one read that must not crash the gather: a corrupt/partial board.json
689
791
  // (the fallback safety net itself) is ignored, not fatal. That holds for a
690
792
  // SHAPE fault as much as a parse fault — the guard below rejects the
@@ -887,7 +989,19 @@ export async function gather({ ledgerFile, prevFile, stateFile = null, scriptDir
887
989
  // stalled, so a healthy board reads none. computeBoard() words it.
888
990
  const now = Date.now();
889
991
  const stallOwnerOf = isStalled(assessBeat({ beat, ticked, acted, controller, now })) ? stallOwner(controller, NAME) : null;
992
+ // The Cell evidence tab's inputs. Every file again on every tick, nothing
993
+ // cached, the rule of every read here; the one exception is `modelRoles`, one
994
+ // child spawn, carried from the previous board and read again at most once a
995
+ // minute. `stateDir` is the workspace's `.fleet`: a caller that names none names
996
+ // no workspace, so it reads none of the workspace's records and spawns no `omp`
997
+ // either (a guard that reads as missing, no receipts, the read carried as it was).
998
+ const guard = stateDir === null ? { status: "missing" } : readGuardFile(stateDir);
999
+ const receipts = stateDir === null
1000
+ ? { phase0: null, closeout: null }
1001
+ : { phase0: readMetricsStep(join(stateDir, RECEIPT)), closeout: readMetricsStep(join(stateDir, CLOSEOUT_RECEIPT)) };
1002
+ const agents = readAgents(scriptDir);
1003
+ const modelRoles = stateDir === null ? heldRead(prev?.modelRoles) : await carryModelRoles(prev?.modelRoles, now);
890
1004
  return { ledger, issues, prs, merged, closed, closedIssues, ci, prev, repo, repoUrl, workspace, port, spend, beat, ticked, acted, controller, stallOwner: stallOwnerOf, poolOk,
891
- poolCapped, prsCapped,
1005
+ poolCapped, prsCapped, guard, receipts, agents, modelRoles,
892
1006
  now, interval };
893
1007
  }
@@ -10,7 +10,7 @@
10
10
  * { box-sizing: border-box; }
11
11
  /* The page is the window's height: header, banner, attention strip, the tab
12
12
  strip and footer keep their natural height and never shrink; the open
13
- tab's pane (#board or #spend, the other is hidden) takes the rest, and
13
+ tab's pane (#board, #cells or #spend, the others are hidden) takes the rest, and
14
14
  each board column scrolls on its own past that. The panes' min-height is
15
15
  the floor for a window too short for the fixed parts — they then overflow
16
16
  body and the PAGE scrolls, rather than squeezing the columns to nothing or
@@ -74,6 +74,28 @@
74
74
  @keyframes flash { from { box-shadow:0 0 0 2px var(--blue); background:#12233a; } to { box-shadow:0 0 0 2px transparent; } }
75
75
  footer .filed { margin-top:4px; }
76
76
  #spend { padding:14px; flex:1 1 0; min-height:200px; overflow-y:auto; }
77
+ #cells { padding:14px; flex:1 1 0; min-height:200px; overflow-y:auto; }
78
+ .ce-links { color:var(--dim); margin-bottom:10px; font-size:12px; }
79
+ .ce-links a { color:var(--blue); text-decoration:none; }
80
+ .ce-sec { background:var(--panel); border:1px solid var(--line); border-radius:8px; padding:10px 12px; margin-bottom:12px; }
81
+ .ce-sec h2 { font-size:11px; letter-spacing:.06em; color:var(--dim); margin:0 0 6px; text-transform:uppercase; }
82
+ .ce-verdict { font-weight:600; }
83
+ .ce-verdict.trips { color:var(--amber); }
84
+ .ce-source, .ce-note, .ce-foot, .ce-dim { color:var(--dim); font-size:12px; }
85
+ .ce-note { margin-top:2px; }
86
+ .ce-entry { border-top:1px solid var(--line); margin-top:10px; padding-top:8px; }
87
+ .ce-hd { display:flex; gap:10px; flex-wrap:wrap; align-items:baseline; }
88
+ .ce-cell { font-weight:600; }
89
+ .ce-amber { color:var(--amber); }
90
+ .ce-gen { margin:4px 0 0 0; padding:2px 0; }
91
+ .ce-older { margin:2px 0 0 18px; color:var(--dim); }
92
+ .ce-fig { display:flex; gap:8px; flex-wrap:wrap; font-size:12px; }
93
+ .ce-lbl { color:var(--dim); min-width:9em; }
94
+ .ce-beside { color:var(--dim); }
95
+ .ce-foot { margin-top:8px; }
96
+ #cells-declared summary { cursor:pointer; color:var(--dim); }
97
+ .ce-member { display:flex; gap:10px; flex-wrap:wrap; font-size:12px; margin:2px 0 0 18px; }
98
+ .ce.flash { animation:flash 1.2s ease-out 1; }
77
99
  .spend-wrap { background:var(--panel); border:1px solid var(--line); border-radius:8px; padding:10px 12px; }
78
100
  .spend-hd { display:flex; align-items:baseline; gap:10px; margin-bottom:8px; }
79
101
  .spend-hd h2 { font-size:11px; letter-spacing:.06em; color:var(--dim); margin:0; text-transform:uppercase; }
@@ -95,8 +117,9 @@
95
117
  <header><h1 id="heading">🛰 fleet cockpit</h1><span id="age"></span></header>
96
118
  <div id="stale-banner"></div>
97
119
  <div id="attention"></div>
98
- <nav id="tabs"><a id="tab-board" class="on" href="#board" aria-current="page">Board</a><a id="tab-tokens" href="#tokens">Tokens</a></nav>
120
+ <nav id="tabs"><a id="tab-board" class="on" href="#board" aria-current="page">Board</a><a id="tab-cells" href="#cells">Cell evidence</a><a id="tab-tokens" href="#tokens">Tokens</a></nav>
99
121
  <div id="board"></div>
122
+ <div id="cells" hidden></div>
100
123
  <div id="spend" hidden></div>
101
124
  <footer id="footer"></footer>
102
125
  <script>
@@ -123,37 +146,56 @@ let repoUrl = null; // full repo URL from the model (carries the host) — PR li
123
146
  const TITLE = "fleet cockpit";
124
147
  function boardTitle(repo) { return repo ? `${TITLE} — ${repo}` : TITLE; }
125
148
 
126
- // Where a URL hash lands: which tab is open, and which card (an issue number,
127
- // as a string) to bring into view on it. The router's whole decision, as a
128
- // value with no DOM or location touched, so it is liftable out of the source
129
- // the way spendView is. It closes over nothing, for the same reason.
149
+ // Where a URL hash lands: which tab is open, and what to bring into view on it.
150
+ // The router's whole decision, as a value with no DOM or location touched, so
151
+ // it is liftable out of the source the way spendView is. It closes over
152
+ // nothing, for the same reason.
130
153
  //
131
- // Every hash the page draws is a tab (`#board`, `#tokens`) or a card on the
132
- // Board (`#board/<issue>`). Anything else — no hash, a tab the page does not
133
- // have, a target the tab does not have — lands on Board's top, or the named
134
- // tab's top, never on a blank page and never on an error.
154
+ // Every hash the page draws is a tab (`#board`, `#cells`, `#tokens`), a card on
155
+ // the Board (`#board/<issue>`, the issue number as a string) or a place on Cell
156
+ // evidence: a section (`#cells/guard`, `#cells/declared`), a Cell
157
+ // (`#cells/<cell>`) or one of its generations (`#cells/<cell>@<generation>`).
158
+ // Anything else — no hash, a tab the page does not have, a target the tab does
159
+ // not have — lands on Board's top, or the named tab's top, never on a blank
160
+ // page and never on an error.
135
161
  function routeHash(hash) {
136
162
  const [tab, target, ...more] = String(hash).replace(/^#/, "").split("/");
137
163
  if (tab === "board") return { tab, target: more.length === 0 && /^[1-9]\d*$/.test(target) ? target : null };
164
+ if (tab === "cells") {
165
+ const place = /^(guard|declared|(slow|task|smol)-(minimal|low|medium|high|xhigh|max)(@[^\s/@]+)?)$/;
166
+ return { tab, target: more.length === 0 && place.test(target ?? "") ? target : null };
167
+ }
138
168
  if (tab === "tokens") return { tab, target: null };
139
169
  return { tab: "board", target: null };
140
170
  }
141
171
 
172
+ // The element a route's target names: a card on Board, a section, a Cell or a
173
+ // generation on Cell evidence.
174
+ function anchorId(tab, target) {
175
+ if (tab === "board") return "card-" + target;
176
+ return target === "guard" || target === "declared" ? "cells-" + target : "cell-" + target;
177
+ }
178
+
142
179
  // Each tab, and the pane it opens.
143
- const PANES = { board: "board", tokens: "spend" };
180
+ const PANES = { board: "board", cells: "cells", tokens: "spend" };
144
181
 
145
- // Which card is still owed a scroll. The cards are rebuilt every tick, so a
182
+ // Which target is still owed a scroll. The cards are rebuilt every tick, so a
146
183
  // hash that arrives before the first render (a reload, a pasted link) cannot
147
184
  // scroll yet: it waits here for the render.
148
185
  let rendered = false;
149
186
  let pending = null;
150
187
 
151
- // The card flashing now, and when it started. A tick rebuilds every card, so
152
- // the flash lives here rather than on a node the next tick throws away.
153
- // FLASH_MS is `.card.flash`'s animation duration.
188
+ // The element flashing now (by id), and when it started. A tick rebuilds every
189
+ // card and every entry, so the flash lives here rather than on a node the next
190
+ // tick throws away. FLASH_MS is `.card.flash`'s animation duration, and
191
+ // `.ce.flash`'s.
154
192
  const FLASH_MS = 1200;
155
193
  let flashing = null;
156
194
 
195
+ // Whether "Declared, not measured" is open. A tick rebuilds it, and an open
196
+ // section that closed itself every 15 seconds would not stay open to be read.
197
+ let declaredOpen = false;
198
+
157
199
  const el = (t, cls, txt) => { const e = document.createElement(t); if (cls) e.className = cls; if (txt != null) e.textContent = txt; return e; };
158
200
  const mins = (ms) => Math.floor((Date.now() - ms) / 60000);
159
201
 
@@ -306,6 +348,107 @@ function renderSpend(sp) {
306
348
  host.append(wrap);
307
349
  }
308
350
 
351
+ // A rebuilt element picks a flash up where it was, not from the start.
352
+ function resumeFlash(node) {
353
+ const age = flashing && flashing.id === node.id ? Date.now() - flashing.at : Infinity;
354
+ if (age < FLASH_MS) flash(node, age);
355
+ }
356
+
357
+ // An anchored element on the tab: the target of a hash link, flashing if it is
358
+ // the one that was just arrived at.
359
+ function ceBox(tag, cls, id) {
360
+ const box = el(tag, "ce " + cls);
361
+ if (id) { box.id = id; resumeFlash(box); }
362
+ return box;
363
+ }
364
+
365
+ // One figure of a Cell's generation: its label, its words, what sits beside it
366
+ // and the footnote marks on it. Every word is the model's (compute-cell-evidence.mjs).
367
+ function ceFigure(label, text, beside = [], marks = []) {
368
+ const row = el("div", "ce-fig");
369
+ row.append(el("span", "ce-lbl", label), el("span", null, text));
370
+ for (const b of beside) row.append(el("span", "ce-beside", "· " + b));
371
+ if (marks.length) row.append(el("span", "ce-beside", marks.join(", ")));
372
+ return row;
373
+ }
374
+
375
+ // A generation with figures: the three, under its own anchor.
376
+ function ceGeneration(f) {
377
+ const box = ceBox("div", "ce-gen", f.anchor);
378
+ box.append(
379
+ ceFigure("merged PRs", f.merged.text, f.merged.beside, f.merged.marks),
380
+ ceFigure("fail rate", f.failRate.text, f.failRate.beside),
381
+ ceFigure("$ per merged PR", f.usd.text),
382
+ );
383
+ return box;
384
+ }
385
+
386
+ // An older generation, nested under its Cell and marked not judged.
387
+ function ceOlder(o) {
388
+ const box = ceBox("div", "ce-older", o.anchor);
389
+ box.append(el("div", null, `${o.generation} · ${o.mark}`),
390
+ ceFigure("merged PRs", o.merged), ceFigure("fail rate", o.failRate), ceFigure("$ per merged PR", o.usd));
391
+ return box;
392
+ }
393
+
394
+ // One Cell's entry: its header line, then its figures or "no figures yet".
395
+ function ceEntry(e) {
396
+ const box = ceBox("div", "ce-entry", e.anchor);
397
+ const hd = el("div", "ce-hd");
398
+ hd.append(el("span", "ce-cell", e.cell));
399
+ if (e.baseline) hd.append(el("span", "badge", "baseline"));
400
+ if (e.judged) hd.append(el("span", "ce-dim", e.judged));
401
+ hd.append(el("span", "ce-dim", e.route.text));
402
+ if (e.route.flag) hd.append(el("span", "ce-amber", e.route.flag));
403
+ if (e.route.label) hd.append(el("span", "ce-amber", e.route.label));
404
+ box.append(hd);
405
+ if (e.figures) box.append(ceGeneration(e.figures));
406
+ else {
407
+ const none = ceBox("div", "ce-gen", e.none.anchor);
408
+ none.append(el("span", "ce-dim", e.none.text));
409
+ if (e.none.marks.length) none.append(el("span", "ce-beside", " " + e.none.marks.join(", ")));
410
+ box.append(none);
411
+ }
412
+ for (const o of e.older) box.append(ceOlder(o));
413
+ return box;
414
+ }
415
+
416
+ // The Cell evidence tab. The model is `m.cellEvidence`; this only lays it out.
417
+ // Every Cell and every generation the model names is drawn, so each hash link
418
+ // the page draws has its target.
419
+ function renderCells(ce) {
420
+ const host = document.getElementById("cells");
421
+ if (!ce) { host.replaceChildren(el("div", "spend-wrap", "no Cell evidence in this board yet")); return; }
422
+ const g = ce.guard;
423
+
424
+ const links = el("div", "ce-links");
425
+ for (const [href, text] of [["#cells/guard", "the guard"], ["#cells/declared", "declared, not measured"]]) {
426
+ if (links.children.length) links.append(document.createTextNode(" · "));
427
+ const a = el("a", null, text);
428
+ a.href = href;
429
+ links.append(a);
430
+ }
431
+
432
+ const sec = ceBox("section", "ce-sec", "cells-guard");
433
+ sec.append(el("h2", null, "The guard: what it holds each Cell to"), el("div", "ce-verdict " + g.state, g.heading));
434
+ if (g.source) sec.append(el("div", "ce-source", g.source));
435
+ for (const n of g.notes) sec.append(el("div", "ce-note", n));
436
+ for (const e of g.cells) sec.append(ceEntry(e));
437
+ for (const f of g.footnotes) sec.append(el("div", "ce-foot", `${f.mark} ${f.text}`));
438
+
439
+ const dec = ceBox("details", "ce-sec", "cells-declared");
440
+ dec.open = declaredOpen;
441
+ dec.addEventListener("toggle", () => { declaredOpen = dec.open; });
442
+ dec.append(el("summary", null, ce.declared.heading));
443
+ for (const m of ce.declared.members) {
444
+ const row = el("div", "ce-member");
445
+ row.append(el("span", null, m.name), el("span", "ce-dim", m.declared ?? "no Declared tier"), el("span", null, m.route));
446
+ dec.append(row);
447
+ }
448
+
449
+ host.replaceChildren(links, sec, dec);
450
+ }
451
+
309
452
  function render(m) {
310
453
  // A ticket whose column is none of COLUMNS matches no column's filter below
311
454
  // and would vanish from the board with nothing said. Throwing before any
@@ -368,6 +511,7 @@ function render(m) {
368
511
  col.replaceChildren(...next[i]);
369
512
  });
370
513
  renderSpend(m.spend);
514
+ renderCells(m.cellEvidence);
371
515
  // Computed here, ahead of the footer, not only inside the banner
372
516
  // arm below. The banner is a single slot behind a stale/stall/ledger
373
517
  // priority chain (next section): whenever any of those also fires on the
@@ -491,9 +635,7 @@ function card(t) {
491
635
  for (const f of t.flags || []) meta.append(el("span", "badge flag", f));
492
636
  if (t.ruling) meta.append(el("span", "badge", "ruled:" + t.ruling));
493
637
  c.append(meta);
494
- // A card rebuilt mid-flash picks the flash up where it was, not from the start.
495
- const age = flashing && flashing.issue === String(t.issue) ? Date.now() - flashing.at : Infinity;
496
- if (age < FLASH_MS) flash(c, age);
638
+ resumeFlash(c);
497
639
  return c;
498
640
  }
499
641
 
@@ -510,8 +652,8 @@ function warn(msg) {
510
652
  showBanner(msg);
511
653
  }
512
654
 
513
- // Opens the tab the hash names and settles the card it targets. The two
514
- // panes stay in the page either way, so a tick keeps filling both.
655
+ // Opens the tab the hash names and settles the target it names. Every pane
656
+ // stays in the page either way, so a tick keeps filling all of them.
515
657
  function applyHash() {
516
658
  const r = routeHash(location.hash);
517
659
  for (const [t, pane] of Object.entries(PANES)) {
@@ -525,22 +667,24 @@ function applyHash() {
525
667
  settle();
526
668
  }
527
669
 
528
- // The arrival: the target card scrolls into view and flashes once; no target,
529
- // or a target no card on the board carries, lands on the tab's top. Taken
530
- // off `pending` first, so a later tick never scrolls the page again; nothing
670
+ // The arrival: the target scrolls into view and flashes once; no target, or a
671
+ // target nothing on the page carries, lands on the tab's top. Taken off
672
+ // `pending` first, so a later tick never scrolls the page again; nothing
531
673
  // settles before the first render.
532
674
  function settle() {
533
675
  if (!pending || !rendered) return;
534
- const { target } = pending;
676
+ const { tab, target } = pending;
535
677
  pending = null;
536
- const hit = target && document.getElementById("card-" + target);
678
+ const hit = target && document.getElementById(anchorId(tab, target));
537
679
  if (!hit) {
538
680
  window.scrollTo(0, 0);
539
- document.getElementById("spend").scrollTop = 0;
681
+ document.getElementById(PANES[tab]).scrollTop = 0;
540
682
  return;
541
683
  }
684
+ // "Declared, not measured" opens on click and on a link to it.
685
+ if (hit.id === "cells-declared") { hit.open = true; declaredOpen = true; }
542
686
  hit.scrollIntoView({ block: "center" });
543
- flashing = { issue: target, at: Date.now() };
687
+ flashing = { id: hit.id, at: Date.now() };
544
688
  flash(hit, 0);
545
689
  }
546
690
 
package/scripts/board.mjs CHANGED
@@ -298,6 +298,9 @@ async function main() {
298
298
  // worktree names the run's real beat instead of a file that is not
299
299
  // there.
300
300
  stateFile: stateFileIn(instance.stateDir),
301
+ // The cost guard, the receipts and the carried `modelRoles` the Cell
302
+ // evidence tab reads, from the same directory.
303
+ stateDir: instance.stateDir,
301
304
  workspace: instance.workspace, port: instance.port,
302
305
  interval, ...spendSource(spendDir, instance.stateDir), spendSince,
303
306
  }));
@@ -403,6 +406,7 @@ async function boardTick({ ledgerFile, interval, spendDir, spendSince }) {
403
406
  // for. Re-derived per tick rather than closed over, exactly like
404
407
  // the ledger default: a pure join on a directory settled at bind time.
405
408
  stateFile: stateFileIn(stateDir),
409
+ stateDir,
406
410
  workspace, port: served,
407
411
  // The operator's --spend-dir, else the receipt as it stands at this
408
412
  // tick, read from the same state directory as the ledger and heartbeat.
@@ -35,6 +35,7 @@
35
35
  import { assessBeat, isStalled, isReported, stallReport, NO_OWNER } from "./fleet-state.mjs";
36
36
  import { parseToken, rowPr, premisesOf, HALT_CAUSES, REVIEW } from "./ledger-grammar.mjs";
37
37
  import { latestFinisherAttempts, foldLedger, pastPinDue } from "./fleet-tick.mjs";
38
+ import { computeCellEvidence } from "./compute-cell-evidence.mjs";
38
39
 
39
40
  // A ledger row is freeform, controller-authored text. Two example shapes:
40
41
  // #<n> impl-<n>=PR#<m> → PR#<m> → MERGED 73b356de
@@ -641,5 +642,19 @@ export function computeBoard(inputs) {
641
642
  owner: inputs.stallOwner ?? NO_OWNER,
642
643
  }, now),
643
644
  attention,
645
+ // The Cell evidence tab's model (compute-cell-evidence.mjs), built from the
646
+ // guard, the receipts' metrics steps, the definitions and the carried
647
+ // `modelRoles` read gather() answered. A caller that read none of them
648
+ // (every hand-built input in this suite) gets the tab's no-guard state:
649
+ // computeCellEvidence reads an input left out as nothing read.
650
+ cellEvidence: computeCellEvidence({
651
+ guard: inputs.guard,
652
+ receipts: inputs.receipts,
653
+ agents: inputs.agents,
654
+ modelRoles: inputs.modelRoles,
655
+ }),
656
+ // The `omp config get modelRoles` read, carried tick to tick the way `ci`
657
+ // and `repo` are: `{ value, readAt, error }`, read at most once a minute.
658
+ modelRoles: inputs.modelRoles ?? null,
644
659
  };
645
660
  }
@@ -0,0 +1,407 @@
1
+ // The cockpit's Cell evidence tab, as a value: computeCellEvidence() turns what
2
+ // gather() read (the cost guard, the receipts' `metrics` steps, the installed
3
+ // definitions, the carried `modelRoles` read) into the model the page lays out.
4
+ // Pure, like compute-board.mjs, which calls it and puts the answer in
5
+ // `board.json` as `cellEvidence`: no file, no process, no clock. Every word the
6
+ // tab shows is built here, so a test pins it where it is made and the page only
7
+ // places it.
8
+ //
9
+ // What this part holds is the guard section: what the cost guard holds each
10
+ // implementer Cell to, from the guard file and nothing recomputed, and "Declared,
11
+ // not measured". Figures show only from a guard `readCostGuard` (fleet-tick.mjs,
12
+ // the reader the tick judges the file by) accepts; `guard` here is that reader's
13
+ // own answer, `{ status: "ok", guard }` or `{ status: "missing" | "unreadable" }`.
14
+ //
15
+ // A figure the guard file lacks reads "not checked", never 0: the file written
16
+ // before the per-Cell counts existed carries only `n`, `mean_usd`, `fail_rate`
17
+ // and `untimed` per Cell, and each count the file does not carry is named as not
18
+ // checked where its figure would show.
19
+
20
+ import { CELL } from "./ledger-grammar.mjs";
21
+ import { implementerCell, modelsEqual, parseModelRoute, resolveRole } from "./tier-roles.mjs";
22
+
23
+ // The implementer Cells, in the order the guard section draws them. All five are
24
+ // drawn in every state: a card or a rescue can name any of them, and no link may
25
+ // point at nothing. A Cell the guard holds beyond these is drawn after them
26
+ // rather than left out.
27
+ export const CELLS = Object.freeze(["slow-high", "task-high", "smol-high", "slow-medium", "task-max"]);
28
+
29
+ const MINUS = "−";
30
+ const SUPERSCRIPT = "⁰¹²³⁴⁵⁶⁷⁸⁹";
31
+ const superscript = (n) => String(n).replace(/\d/g, (d) => SUPERSCRIPT[d]);
32
+
33
+ // A figure's count, or null when the file does not carry it as one.
34
+ const count = (v) => (Number.isInteger(v) && v >= 0 ? v : null);
35
+ const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
36
+
37
+ // An ISO time, or epoch milliseconds, to the minute; a string that is no time as it came.
38
+ function when(t) {
39
+ const d = new Date(t);
40
+ return Number.isNaN(d.getTime()) ? String(t) : `${d.toISOString().slice(0, 16).replace("T", " ")}Z`;
41
+ }
42
+
43
+ // A difference in tenths, with its sign: the minus is U+2212, as in the spec's own
44
+ // figures. Rounded half away from zero, so −43.75 reads −43.8 as +43.75 reads +43.8.
45
+ const tenths = (x) => Math.sign(x) * Math.round(Math.abs(x) * 10);
46
+ const signed = (t, unit) => `${t < 0 ? MINUS : "+"}${(Math.abs(t) / 10).toFixed(1)}${unit}`;
47
+ // failed/claims in tenths of a percent, off the counts, and as a percentage to one place.
48
+ const rateTenths = (failed, claims) => Math.round((failed * 1000) / claims);
49
+ const ratePct = (failed, claims) => (rateTenths(failed, claims) / 10).toFixed(1);
50
+ // A rate the guard file stored, 0–1, as a percentage to one place.
51
+ const storedPct = (rate) => `${(Math.round(rate * 1000) / 10).toFixed(1)}%`;
52
+
53
+ // The generation a model identity names, put on the scale of a judged
54
+ // generation, which member-outcomes.mjs's dispatchModel strips of its provider
55
+ // and its level: this drops the provider only, so the model it is handed must
56
+ // already be level-free, as resolveRole's answer is.
57
+ const generationOf = (model) => String(model).split("/").at(-1);
58
+
59
+ // ---------------------------------------------------------------------------
60
+ // The Tier route: the cockpit's own `modelRoles`, a carried `{ value, readAt, error }`.
61
+ // ---------------------------------------------------------------------------
62
+
63
+ // What the carried read says about itself, for the heading and beside each Tier
64
+ // route: null while the last read stands, else the words for a failing or an unread one.
65
+ function readLabel(modelRoles) {
66
+ const failure = modelRoles?.error ?? null;
67
+ if (modelRoles?.value == null) {
68
+ return failure === null
69
+ ? "not checked: modelRoles not read yet"
70
+ : `not checked: modelRoles not read yet; reading fails: ${failure.message}`;
71
+ }
72
+ return failure === null ? null : `as read at ${when(modelRoles.readAt)}; reading fails: ${failure.message}`;
73
+ }
74
+
75
+ // The model `<role>` resolves to under the carried read: a model name, `null`
76
+ // when the role is unset, `undefined` when there is no read to ask.
77
+ function routeModel(role, modelRoles) {
78
+ if (!isRecord(modelRoles?.value)) return undefined;
79
+ return resolveRole(role, modelRoles.value);
80
+ }
81
+
82
+ // "Tier route: <model> · <level>" for a role and a level, and what it cannot be
83
+ // compared with. `generation` is the generation the Cell is judged on, when it has one.
84
+ function tierRoute(role, level, generation, modelRoles) {
85
+ const label = readLabel(modelRoles);
86
+ const model = routeModel(role, modelRoles);
87
+ if (model === undefined) return { model: null, text: "Tier route: not checked", label, flag: null };
88
+ if (model === null) return { model: null, text: `modelRoles.${role} unset: omp picks the model`, label, flag: "not checked" };
89
+ const differs = generation != null && !modelsEqual(model, generation);
90
+ return {
91
+ model,
92
+ text: `Tier route: ${model} · ${level}`,
93
+ label,
94
+ flag: differs ? "⚑ differs from the judged generation" : null,
95
+ };
96
+ }
97
+
98
+ // ---------------------------------------------------------------------------
99
+ // No guard: the newest `metrics` step of the phase 0 and close-out receipts.
100
+ // ---------------------------------------------------------------------------
101
+
102
+ // `step` is `{ status, at, output }` or null. A step that has not run carries no
103
+ // refresh to quote.
104
+ const ran = (step) => step != null && step.status !== "pending" && Number.isFinite(Date.parse(step.at));
105
+
106
+ // metrics-refresh's own line from a step's output: the cost-guard duty's, else
107
+ // the last of its lines, else the output's first line. Its own prefix, the
108
+ // "skipped," and the note that the file was left as it was are dropped; the rest
109
+ // is quoted as written. Found anywhere in a line, not at its start: a failed
110
+ // close-out step glues its headline to the first line of the script's output.
111
+ function refreshLine(output) {
112
+ const text = String(output ?? "");
113
+ const own = /metrics-refresh: cost guard( failed)?: ([^\n]*)/.exec(text);
114
+ const last = [...text.matchAll(/metrics-refresh: ([^\n]*)/g)].at(-1);
115
+ const line = own ? (own[1] ? own[2] : own[2].replace(/^skipped, /, "")) : last ? last[1] : text.split("\n").find((l) => l.trim()) ?? "";
116
+ return line.trim().replace(/; \S*cost-guard\.json left as it is$/, "");
117
+ }
118
+
119
+ // The newest `metrics` step of the two receipts, with the verb its status and
120
+ // line give it: `{ verb, at, why }`, or null when neither receipt has run one.
121
+ function newestRefresh(receipts) {
122
+ const steps = [receipts?.phase0, receipts?.closeout].filter(ran);
123
+ if (steps.length === 0) return null;
124
+ const step = steps.reduce((a, b) => (Date.parse(b.at) > Date.parse(a.at) ? b : a));
125
+ const why = refreshLine(step.output);
126
+ const verb = step.status === "failed" ? "failed" : /metrics-refresh: cost guard: skipped,/.test(step.output ?? "") ? "skipped" : "ran";
127
+ return { verb, at: step.at, why };
128
+ }
129
+
130
+ // ---------------------------------------------------------------------------
131
+ // The guard section.
132
+ // ---------------------------------------------------------------------------
133
+
134
+ // The per-Cell fields the guard file gained, by the words that name them in a label.
135
+ const FIELD_WORDS = [
136
+ ["n_claims", "claim counts"], ["n_failed", "failure counts"], ["by_hand", "by-hand count"], ["left_out", "left-out count"],
137
+ ["pending", "pending count"], ["excluded", "no-Admissible-row count"], ["unpriced", "unpriced count"], ["untimed", "untimed count"],
138
+ ];
139
+
140
+ // Merged PRs against `min_n`. A Cell is judged only while the baseline has
141
+ // `min_n` merged PRs itself: below that the guard holds nothing back, whatever a
142
+ // Cell's own n.
143
+ function mergedFigure(e, g, isBase) {
144
+ const n = e.n;
145
+ const min = g.min_n;
146
+ const base = g.baseline.cell;
147
+ const judged = isBase || g.verdict !== "none";
148
+ const text = n >= min
149
+ ? judged ? `${n} ≥ ${min} ✓` : `${n} ≥ ${min}: not judged until ${base} has ${min}`
150
+ : `${n} of ${min}: not judged`;
151
+ const beside = [];
152
+ const unchecked = [];
153
+ for (const [key, words] of [["left_out", "left out"], ["pending", "pending"]]) {
154
+ const k = count(e[key]);
155
+ if (k === null) unchecked.push(words);
156
+ else if (k > 0) beside.push(`${k} ${words}`);
157
+ }
158
+ return { text, beside, unchecked };
159
+ }
160
+
161
+ // The fail rate with its gap to the baseline's and to the floor, worked from the
162
+ // claim and failure counts. Whole counts and the integer cross-product are what
163
+ // the guard itself judges by (`underFloor`), so a gap near the floor reads the
164
+ // way the guard rules; a rounded rate never enters it.
165
+ function failFigure(e, g, baseEntry, isBase) {
166
+ const claims = count(e.n_claims);
167
+ const failed = count(e.n_failed);
168
+ const trip = count(g.trip_points);
169
+ const base = g.baseline.cell;
170
+ const beside = [];
171
+ const hand = count(e.by_hand);
172
+ if (hand === null) beside.push("Rulings given by hand: not checked");
173
+ else if (hand > 0) beside.push(`${hand} of ${e.n} Rulings given by hand`);
174
+
175
+ if (claims === null || failed === null) {
176
+ const stored = typeof e.fail_rate === "number" ? storedPct(e.fail_rate) : null;
177
+ return { text: stored === null ? "no fail rate yet" : `${stored} · gap and floor: not checked`, beside };
178
+ }
179
+ if (claims === 0) return { text: "no fail rate yet: no claims", beside };
180
+ const rate = `${ratePct(failed, claims)}%`;
181
+ if (isBase) {
182
+ return { text: trip === null ? `${rate} · the floor: not checked` : `${rate} · the floor is ${((rateTenths(failed, claims) + trip * 10) / 10).toFixed(1)}%`, beside };
183
+ }
184
+ const bClaims = count(baseEntry?.n_claims);
185
+ const bFailed = count(baseEntry?.n_failed);
186
+ if (bClaims === null || bFailed === null) return { text: `${rate} · gap: not checked: ${base} has no counts`, beside };
187
+ if (bClaims === 0) return { text: `${rate} · no gap: ${base} has no claims`, beside };
188
+ // (failed/claims − bFailed/bClaims) × 100, from the counts.
189
+ const num = (failed * bClaims - bFailed * claims) * 100;
190
+ const den = claims * bClaims;
191
+ const gap = signed(tenths(num / den), " pts");
192
+ if (trip === null) return { text: `${rate} · ${gap} on ${base} · the floor: not checked`, beside };
193
+ const margin = (trip * den - num) / den;
194
+ const floor = margin > 0 ? `${(tenths(margin) / 10).toFixed(1)} pts inside the floor` : `${(tenths(-margin) / 10).toFixed(1)} pts past the floor`;
195
+ return { text: `${rate} · ${gap} on ${base} · ${floor}`, beside };
196
+ }
197
+
198
+ // $ per merged PR, against the baseline's.
199
+ function usdFigure(e, g, isBase) {
200
+ const base = g.baseline.cell;
201
+ if (typeof e.mean_usd !== "number") return { text: "no merged PR yet: no $ per merged PR" };
202
+ const usd = `$${e.mean_usd.toFixed(2)}`;
203
+ if (isBase) return { text: usd };
204
+ const b = g.baseline.mean_usd;
205
+ if (typeof b !== "number" || b === 0) return { text: `${usd} · no comparison: ${base} has no $ per merged PR` };
206
+ return { text: `${usd} · ${signed(tenths(((e.mean_usd - b) / b) * 100), "%")} on ${base}` };
207
+ }
208
+
209
+ // An older generation's figures: printed, never compared, so no gap, no floor,
210
+ // no judged mark. The same counts are not repeated: only what it merged, how it failed and what it cost.
211
+ function olderRow(cell, o) {
212
+ const n = count(o.n_merged) ?? count(o.n);
213
+ const claims = count(o.n_claims);
214
+ const failed = count(o.n_failed);
215
+ const rate = claims === null || failed === null
216
+ ? typeof o.fail_rate === "number" ? storedPct(o.fail_rate) : "no fail rate yet"
217
+ : claims === 0 ? "no fail rate yet" : `${ratePct(failed, claims)}%`;
218
+ return {
219
+ generation: o.generation,
220
+ anchor: `cell-${cell}@${o.generation}`,
221
+ mark: "not judged",
222
+ merged: n === null ? "merged PRs: not checked" : `${n} merged PRs`,
223
+ failRate: rate,
224
+ usd: typeof o.mean_usd === "number" ? `$${o.mean_usd.toFixed(2)}` : "no $ per merged PR",
225
+ };
226
+ }
227
+
228
+ // The footnotes one entry's figure needs: the sentence under the section and the
229
+ // mark on the figure. The middle column is the words the merged figure names as
230
+ // "not checked" when the file does not carry that count.
231
+ const NOTES = [
232
+ ["excluded", "no Admissible row", (cell, k) => `${cell}: ${k} drawn here have no Admissible row: they ran under another Cell, at another effort, or with no model on record, so they count in no Cell's figures`],
233
+ ["unpriced", "unpriced", (cell, k) => `${cell}: ${k} unpriced: part of their Spend can't be booked`],
234
+ ["untimed", "untimed", (cell, k) => `${cell}: ${k} untimed: a member's work time isn't on record`],
235
+ ];
236
+
237
+ function footnotesFor(cell, e, notes) {
238
+ const marks = [];
239
+ const unchecked = [];
240
+ for (const [key, words, text] of NOTES) {
241
+ const k = count(e[key]);
242
+ if (k === null) unchecked.push(words);
243
+ else if (k > 0) {
244
+ const mark = superscript(notes.length + 1);
245
+ notes.push({ mark, text: text(cell, k) });
246
+ marks.push(mark);
247
+ }
248
+ }
249
+ return { marks, unchecked };
250
+ }
251
+
252
+ // One Cell's entry: its header line, its three figures (or "no figures yet"), its older generations.
253
+ function guardEntry(cell, g, byCell, modelRoles, notes) {
254
+ const e = byCell.get(cell) ?? null;
255
+ const isBase = cell === g.baseline.cell;
256
+ const parsed = CELL.exec(cell);
257
+ const [role, level] = parsed ? [parsed[1], parsed[2]] : [null, null];
258
+ const generation = e !== null && typeof e.generation === "string" && e.generation !== "" ? e.generation : null;
259
+ const route = role === null
260
+ ? { model: null, text: "no Tier route: not a Cell the fleet defines", label: null, flag: null }
261
+ : tierRoute(role, level, generation, modelRoles);
262
+ const entry = {
263
+ cell,
264
+ anchor: `cell-${cell}`,
265
+ baseline: isBase,
266
+ judged: generation === null ? null : `judged on ${generation}`,
267
+ route,
268
+ figures: null,
269
+ none: null,
270
+ older: e !== null && Array.isArray(e.older)
271
+ ? e.older.filter((o) => isRecord(o) && typeof o.generation === "string" && o.generation !== "").map((o) => olderRow(cell, o))
272
+ : [],
273
+ };
274
+
275
+ if (generation === null) {
276
+ // No figures: not in the guard, or in it with no Pull that has a generation.
277
+ const model = route.model === null ? null : generationOf(route.model);
278
+ const marks = e === null ? [] : footnotesFor(cell, e, notes).marks;
279
+ entry.none = {
280
+ text: `no figures yet for ${model ?? cell}`,
281
+ generation: model,
282
+ anchor: model === null ? null : `cell-${cell}@${model}`,
283
+ marks,
284
+ };
285
+ return entry;
286
+ }
287
+
288
+ const baseEntry = byCell.get(g.baseline.cell) ?? null;
289
+ const merged = mergedFigure(e, g, isBase);
290
+ const { marks, unchecked } = footnotesFor(cell, e, notes);
291
+ const checks = [...merged.unchecked, ...unchecked];
292
+ entry.figures = {
293
+ generation,
294
+ anchor: `cell-${cell}@${generation}`,
295
+ merged: { text: merged.text, beside: [...merged.beside, ...(checks.length ? [`${checks.join(", ")}: not checked`] : [])], marks },
296
+ failRate: failFigure(e, g, baseEntry, isBase),
297
+ usd: usdFigure(e, g, isBase),
298
+ };
299
+ return entry;
300
+ }
301
+
302
+ // The verdict state's words and the source line under them.
303
+ function guardHeading(g) {
304
+ const state = g.verdict === "none" ? "holds-nothing-back" : g.verdict === "tripped" ? "trips" : "trips-nothing";
305
+ const heading = state === "holds-nothing-back"
306
+ ? `holds no Cell back until ${g.baseline.cell} has ${g.min_n} merged PRs: it has ${g.baseline.n}`
307
+ : state === "trips" ? `trips ${g.tripped.join(", ")}` : "trips nothing";
308
+ const trip = count(g.trip_points);
309
+ const source = [
310
+ "this repository's runs",
311
+ `computed ${when(g.computed_at)}`,
312
+ typeof g.window_start === "string" ? `window from ${g.window_start}` : "window: not checked",
313
+ `min ${g.min_n} merged PRs`,
314
+ trip === null ? "floor: not checked" : `floor ${trip} pts over ${g.baseline.cell}`,
315
+ ].join(" · ");
316
+ return { state, heading, source };
317
+ }
318
+
319
+ function guardSection(read, receipts, modelRoles) {
320
+ const label = readLabel(modelRoles);
321
+ const refresh = newestRefresh(receipts);
322
+ const notes = [];
323
+ const footnotes = [];
324
+
325
+ if (read?.status !== "ok") {
326
+ // No guard the tick's reader accepts: never an alert. A refresh that fails
327
+ // every time, a fresh workspace and a lost file are all this state.
328
+ if (read?.status === "unreadable") notes.push(`cost-guard.json unreadable: ${read.why}`);
329
+ notes.push(refresh === null
330
+ ? receipts?.phase0 == null && receipts?.closeout == null
331
+ ? "no phase 0 or close-out receipt here"
332
+ : "no metrics refresh has run in the receipts here"
333
+ : `${refresh.verb} at ${when(refresh.at)}: ${refresh.why}`);
334
+ if (label !== null) notes.push(label);
335
+ const byCell = new Map();
336
+ const stub = { baseline: { cell: "slow-high" } };
337
+ return {
338
+ state: "no-guard",
339
+ heading: "no cost guard",
340
+ source: null,
341
+ notes,
342
+ cells: CELLS.map((cell) => guardEntry(cell, stub, byCell, modelRoles, footnotes)),
343
+ footnotes,
344
+ };
345
+ }
346
+
347
+ const g = read.guard;
348
+ const { state, heading, source } = guardHeading(g);
349
+ const byCell = new Map(g.cells.map((c) => [c.cell, c]));
350
+ const order = [...CELLS, ...g.cells.map((c) => c.cell).filter((c) => !CELLS.includes(c))];
351
+ const cells = order.map((cell) => guardEntry(cell, g, byCell, modelRoles, footnotes));
352
+
353
+ const missing = FIELD_WORDS.filter(([key]) => g.cells.some((c) => count(c[key]) === null)).map(([, words]) => words);
354
+ if (missing.length > 0) notes.push(`not checked: this guard predates the ${missing.join(", ")}`);
355
+ if (refresh !== null && refresh.verb === "failed" && Date.parse(refresh.at) > Date.parse(g.computed_at)) {
356
+ notes.push(`the newest refresh failed at ${when(refresh.at)}: ${refresh.why}; these figures are from ${when(g.computed_at)}`);
357
+ }
358
+ if (label !== null) notes.push(label);
359
+ return { state, heading, source, notes, cells, footnotes };
360
+ }
361
+
362
+ // ---------------------------------------------------------------------------
363
+ // Declared, not measured.
364
+ // ---------------------------------------------------------------------------
365
+
366
+ // Every definition but the implementer Cells', each with its Declared tier and
367
+ // the Tier route that tier resolves to under the cockpit's own `modelRoles`.
368
+ // `agents` is `{ list: [{ file, model }], error }`; `error` is why the
369
+ // definitions could not be listed, and then there is no list to count.
370
+ function declaredSection(agents, modelRoles) {
371
+ if (agents?.error) {
372
+ return { heading: `Declared, not measured: the definitions could not be read: ${agents.error}`, members: [] };
373
+ }
374
+ const members = (agents?.list ?? [])
375
+ .filter((a) => implementerCell(a.file) === null)
376
+ .map((a) => {
377
+ const name = a.file.replace(/\.agent\.md$/, "");
378
+ const declared = typeof a.model === "string" ? a.model.replace(/^(["'])(.*)\1$/, "$2") : null;
379
+ const { role, level } = parseModelRoute(declared);
380
+ let route;
381
+ if (declared === null) route = "no Declared tier";
382
+ else if (role === null) route = "Declared tier is not a route";
383
+ else {
384
+ const model = routeModel(role, modelRoles);
385
+ route = model === undefined ? "not checked" : model === null ? `modelRoles.${role} unset: omp picks the model` : `${model} · ${level}`;
386
+ }
387
+ return { name, declared, route };
388
+ })
389
+ .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
390
+ const n = members.length;
391
+ return { heading: `Declared, not measured: ${n} other member${n === 1 ? "" : "s"}`, members };
392
+ }
393
+
394
+ /**
395
+ * The Cell evidence tab's model. `guard` is `readCostGuard`'s answer, `receipts`
396
+ * is `{ phase0, closeout }`, each the receipt's `metrics` step `{ status, at,
397
+ * output }` or null, `agents` is `{ list: [{ file, model }], error }`, and
398
+ * `modelRoles` the carried `{ value, readAt, error }` or null — `error` being
399
+ * `{ at, message }`. An input left out reads as nothing read: a missing guard,
400
+ * no receipt, no definitions, no `modelRoles` read.
401
+ */
402
+ export function computeCellEvidence({ guard, receipts, agents, modelRoles = null }) {
403
+ return {
404
+ guard: guardSection(guard, receipts, modelRoles),
405
+ declared: declaredSection(agents, modelRoles),
406
+ };
407
+ }