@feigi/fleet-ctl 3.111.0 → 3.112.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.111.0",
3
+ "version": "3.112.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": {
@@ -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
+ }
@@ -781,9 +781,10 @@ export function nextRetry(name, names) {
781
781
  export const CELL = /^(slow|task|smol)-(minimal|low|medium|high|xhigh|max)$/;
782
782
  export const CELL_DEF = new RegExp(`^fleet-implementer-${CELL.source.slice(1)}`);
783
783
 
784
- // The cell a row with no `tier=` runs at: `policy_cell`, `slow-high` on every
785
- // Pull until the router's table picks one per stratum. Exported so
786
- // ticket-router.mjs defaults to the same cell this file maps a bare row to.
784
+ // The cell a row with neither `tier=` nor `cell=` runs at: `policy_cell`,
785
+ // `slow-high` on every Pull until the router's table picks one per stratum.
786
+ // Exported so ticket-router.mjs defaults to the same cell this file maps a
787
+ // bare row to.
787
788
  export const POLICY_CELL = "slow-high";
788
789
 
789
790
  // The Exploration Pull's draw: uniform over every cell but
@@ -804,13 +805,18 @@ export function drawCell({ session, ticket, policyCell, cells }) {
804
805
  }
805
806
 
806
807
  // The definition an implementer is dispatched under, off its ticket
807
- // row's `tier=` token — none means `fleet-implementer-<POLICY_CELL>`,
808
- // `tier=<x>` means `fleet-implementer-<x>`. The value becomes a file
808
+ // row's cell token — none means `fleet-implementer-<POLICY_CELL>`,
809
+ // `tier=<x>` or `cell=<x>` means `fleet-implementer-<x>`. `tier=` is the
810
+ // cell a draw picked (a row carrying one is a drawn Pull, which `implRow`
811
+ // reads); `cell=` is the cell the router printed for a Pull it routed without
812
+ // a draw, and reads as no draw. When a row carries both, `tier=` decides: it
813
+ // is the replacement's cell `ledger.mjs token` writes. The value becomes a file
809
814
  // name under `agents/`, so it is held to `[a-z0-9]` words joined by `-`
810
- // rather than joined into a path as written, and two different `tier=`
811
- // values on one row name no single definition — refused, never resolved by
812
- // position. A value with no definition behind it (the retired `tier=alt`) is
813
- // `ledger.mjs dispatch`'s to refuse: it checks the file exists.
815
+ // rather than joined into a path as written, and two different values
816
+ // of the deciding token on one row name no single definition — refused,
817
+ // never resolved by position. A value with no definition behind it (the
818
+ // retired `tier=alt`) is `ledger.mjs dispatch`'s to refuse: it checks the file
819
+ // exists.
814
820
  //
815
821
  // Here, not in tier-check.mjs, because two readers must agree on it:
816
822
  // `ledger.mjs dispatch` prints the definition before the call and records
@@ -820,16 +826,36 @@ export function drawCell({ session, ticket, policyCell, cells }) {
820
826
  // definitions for one row and fail a dispatch made exactly as printed.
821
827
  const TIER_SUFFIX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
822
828
 
829
+ const tokenValues = (rowText, name) =>
830
+ String(rowText ?? "").split(/\s+/).filter((t) => t.startsWith(`${name}=`)).map((t) => t.slice(name.length + 1));
831
+
823
832
  /** Every `tier=` value a row's text carries, in order, duplicates kept. */
824
833
  export function tierValues(rowText) {
825
- return String(rowText ?? "").split(/\s+/).filter((t) => t.startsWith("tier=")).map((t) => t.slice("tier=".length));
834
+ return tokenValues(rowText, "tier");
835
+ }
836
+
837
+ /** Every `cell=` value a row's text carries, in order, duplicates kept. */
838
+ export function cellValues(rowText) {
839
+ return tokenValues(rowText, "cell");
840
+ }
841
+
842
+ /**
843
+ * The token that decides a row's cell, and its values: `tier=` when the row
844
+ * carries one, else `cell=`. Values are empty on a row with neither, and
845
+ * `name` then names no token the row carries.
846
+ * @returns {{name: "tier"|"cell", values: string[]}}
847
+ */
848
+ export function decidingCell(rowText) {
849
+ const tiers = tierValues(rowText);
850
+ return tiers.length > 0 ? { name: "tier", values: tiers } : { name: "cell", values: cellValues(rowText) };
826
851
  }
827
852
 
828
853
  export function expectedDefinition(rowText) {
829
- const values = [...new Set(tierValues(rowText))];
854
+ const { name, values: all } = decidingCell(rowText);
855
+ const values = [...new Set(all)];
830
856
  if (values.length === 0) return `fleet-implementer-${POLICY_CELL}`;
831
- if (values.length > 1) throw new Error(`row carries conflicting tier= tokens (${values.map((v) => `tier=${v}`).join(", ")}) — fix the row with \`ledger.mjs row\``);
832
- if (!TIER_SUFFIX.test(values[0])) throw new Error(`tier=${values[0]} is not a definition suffix — expected [a-z0-9] words joined by '-' — fix the row with \`ledger.mjs row\``);
857
+ if (values.length > 1) throw new Error(`row carries conflicting ${name}= tokens (${values.map((v) => `${name}=${v}`).join(", ")}) — fix the row with \`ledger.mjs row\``);
858
+ if (!TIER_SUFFIX.test(values[0])) throw new Error(`${name}=${values[0]} is not a definition suffix — expected [a-z0-9] words joined by '-' — fix the row with \`ledger.mjs row\``);
833
859
  return `fleet-implementer-${values[0]}`;
834
860
  }
835
861
 
@@ -58,7 +58,7 @@ import { fileURLToPath } from "node:url";
58
58
  import { spawnSync, execFileSync } from "node:child_process";
59
59
  import { makeDie, isFlagLike, hasEqualsForm, isDigits, writeAll } from "./arg.mjs";
60
60
  import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
61
- import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, settledOnLedger, retiredOnLedger, retiredName, readRetired, agentDefinition, expectedDefinition, CELL, POLICY_CELL, tierValues, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, HALT_CAUSES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, BRIEFS, briefsArchiveName, memberRole, parseDispatchedEntry, dispatchedEntry, headerRe, escapeText, ledgerSection, nextReviewerName } from "./ledger-grammar.mjs";
61
+ import { parseMember, parseToken, memberTokens, nextMergeBot, nextRetry, liveOnLedger, settledOnLedger, retiredOnLedger, retiredName, readRetired, agentDefinition, expectedDefinition, CELL, POLICY_CELL, tierValues, cellValues, decidingCell, rowPr, rowWriteRefusal, isReviewToken, addedReviewToken, newSplitRow, splitRowClause, added, premisesOf, MEMBER_FAMILIES, HALT_CAUSES, ROWS, DISPATCHED, FILED, RULED, DRAIN, RETIRED, RECEIPT, archiveStamp, receiptArchiveName, CLOSEOUT_RECEIPT, closeoutArchiveName, BRIEFS, briefsArchiveName, memberRole, parseDispatchedEntry, dispatchedEntry, headerRe, escapeText, ledgerSection, nextReviewerName } from "./ledger-grammar.mjs";
62
62
  import { deriveRun, LedgerError, labelOffMember, HELD, CONFLICT_HOLD, PARKED } from "./fleet-tick.mjs";
63
63
  import { stateFileIn, readState, writeState, assessBeat, stallsAt } from "./fleet-state.mjs";
64
64
  import { processSource, ancestry, controllerOf, judgeController, ProcUnreadable } from "./proc.mjs";
@@ -748,11 +748,14 @@ if (cmd === "read") {
748
748
  // rewrite alike; a well-formed token, live or settled, still goes through.
749
749
  const malformed = memberTokens(line).find((t) => t.error !== null);
750
750
  if (malformed) die(`row ${key}: malformed member token '${malformed.name}=${malformed.outcome}' — ${malformed.error}`);
751
- // `tier=` names the implementer cell an exploration Pull dispatched, so its
752
- // value must be a cell token: a retired or misspelt tier written here would
753
- // only be refused later, by `dispatch`, after the claim.
754
- const badTier = tierValues(line).find((v) => !CELL.test(v));
755
- if (badTier !== undefined) die(`row ${key}: 'tier=${badTier}' is not tier=<cell> — a cell is <slow|task|smol>-<level>`);
751
+ // `tier=` names the implementer cell an exploration Pull dispatched, and
752
+ // `cell=` the cell a Pull the router routed without a draw did, so each value
753
+ // must be a cell token: a retired or misspelt one written here would only be
754
+ // refused later, by `dispatch`, after the claim.
755
+ for (const [name, values] of [["tier", tierValues(line)], ["cell", cellValues(line)]]) {
756
+ const bad = values.find((v) => !CELL.test(v));
757
+ if (bad !== undefined) die(`row ${key}: '${name}=${bad}' is not ${name}=<cell> — a cell is <slow|task|smol>-<level>`);
758
+ }
756
759
  // A Pull's cell binds its implementer until that member settles; see
757
760
  // cellChangeRefusal(). A new row binds nothing yet.
758
761
  const i = data.rows.findIndex((r) => r.split(/\s/)[0] === key);
@@ -2226,14 +2229,14 @@ async function runDispatch() {
2226
2229
 
2227
2230
  // The definition the `task` call names, printed so the controller reads it
2228
2231
  // off this output rather than recalling it from prose a compaction drops.
2229
- // An implementer's comes off its row's `tier=`, the same function
2230
- // tier-check.mjs falls back to for an entry with no record, and `dispatch`
2231
- // records what it prints on the member's `## Dispatched` entry, which
2232
- // tier-check judges the member against — so a row that names no single
2233
- // definition, or names one with no file under `agents/` (a well-formed
2234
- // `tier=` whose definition has not shipped: a `task` call naming it cannot
2235
- // resolve), is refused here, before the member is live, not discovered by
2236
- // the check after the call.
2232
+ // An implementer's comes off its row's `tier=`, else its `cell=`, the same
2233
+ // function tier-check.mjs falls back to for an entry with no record, and
2234
+ // `dispatch` records what it prints on the member's `## Dispatched` entry,
2235
+ // which tier-check judges the member against — so a row that names no
2236
+ // single definition, or names one with no file under `agents/` (a
2237
+ // well-formed `tier=` or `cell=` whose definition has not shipped: a `task`
2238
+ // call naming it cannot resolve), is refused here, before the member is
2239
+ // live, not discovered by the check after the call.
2237
2240
  //
2238
2241
  // A fix-applier is `fleet-fix-applier` for every kind of work — review,
2239
2242
  // conflict hold, dispositions retry — so its definition reads nothing off
@@ -2287,15 +2290,18 @@ async function runDispatch() {
2287
2290
  const failures = labelled === null ? closing.failures : [...closing.failures, labelled];
2288
2291
  if (failures.length > 0) die(`${member.name}: ${failures.join("; ")} — not dispatching ${member.name}`);
2289
2292
  }
2290
- // Every error caught here carries its own cause and remedy — a row's `tier=`
2293
+ // Every error caught here carries its own cause and remedy — a row's `tier=` or `cell=`
2291
2294
  // (fix it with `ledger.mjs row`) for an implementer, a family
2292
2295
  // ledger-grammar.mjs has no definition case for otherwise — so this
2293
2296
  // refusal's tail names neither.
2294
2297
  let agent;
2295
2298
  try {
2296
- agent = agentDefinition(member, i === -1 ? "" : data.rows[i]);
2299
+ const row = i === -1 ? "" : data.rows[i];
2300
+ agent = agentDefinition(member, row);
2297
2301
  if (member.family === "impl" && !existsSync(join(AGENTS_DIR, `${agent}.agent.md`))) {
2298
- throw new Error(`row #${member.number}'s tier= names ${agent}, which has no agents/${agent}.agent.md — fix the row with \`ledger.mjs row\``);
2302
+ const { name, values } = decidingCell(row);
2303
+ const cause = values.length === 0 ? `row #${member.number} has no tier= or cell=, so it runs the policy cell ${agent}` : `row #${member.number}'s ${name}= names ${agent}`;
2304
+ throw new Error(`${cause}, which has no agents/${agent}.agent.md — fix the row with \`ledger.mjs row\``);
2299
2305
  }
2300
2306
  } catch (e) {
2301
2307
  die(`${member.name}: ${e.message} — not dispatching ${member.name}`);
@@ -2925,10 +2931,11 @@ function badLabelOff(words) {
2925
2931
  });
2926
2932
  }
2927
2933
 
2928
- // The cell a row's implementer runs at — its `tier=`, or POLICY_CELL on a row
2929
- // with none — read the way `dispatch` reads it: null for a row whose `tier=`
2930
- // values conflict or name no agents/<definition>.agent.md, which `dispatch`
2931
- // refuses, so such a row has no draw to bind.
2934
+ // The cell a row's implementer runs at — its `tier=`, else its `cell=`, or
2935
+ // POLICY_CELL on a row with neither — read the way `dispatch` reads it: null
2936
+ // for a row whose deciding values conflict or name no
2937
+ // agents/<definition>.agent.md, which `dispatch` refuses, so such a row has no
2938
+ // draw to bind.
2932
2939
  function runnableCell(rowText) {
2933
2940
  let definition;
2934
2941
  try {
@@ -2937,7 +2944,7 @@ function runnableCell(rowText) {
2937
2944
  return null;
2938
2945
  }
2939
2946
  if (!existsSync(join(AGENTS_DIR, `${definition}.agent.md`))) return null;
2940
- return tierValues(rowText)[0] ?? POLICY_CELL;
2947
+ return definition.slice("fleet-implementer-".length);
2941
2948
  }
2942
2949
 
2943
2950
  // The member a row's cell binds, while it has not settled, else null: the
@@ -2966,7 +2973,7 @@ function cellChangeRefusal(oldLine, line) {
2966
2973
  if (oldLine === null) return null;
2967
2974
  const cell = runnableCell(oldLine);
2968
2975
  if (cell === null) return null;
2969
- const tiers = [...new Set(tierValues(line))];
2976
+ const tiers = [...new Set(decidingCell(line).values)];
2970
2977
  const to = tiers.length === 0 ? POLICY_CELL : tiers.join(" and ");
2971
2978
  if (to === cell) return null;
2972
2979
  const member = unsettledImplementer(oldLine);
@@ -2991,7 +2998,8 @@ function withTier(line, tok) {
2991
2998
  // then dedupe against), and the row's ` · ` separator are no token. A member
2992
2999
  // token is `dispatch`'s or `settle`'s, a review token `review`'s. A word
2993
3000
  // shaped like a member that the grammar cannot parse, a `tier=` that is not
2994
- // a cell, a `tier=` naming a second tier in one call, a `held-behind`,
3001
+ // a cell, a `tier=` naming a second tier in one call, any `cell=` (the row
3002
+ // step's, never a token), a `held-behind`,
2995
3003
  // `conflict-hold` or `parked` token the tick cannot read, and a lone `→` — an
2996
3004
  // arrow with no PR beside it points at nothing — are refused. Every other
2997
3005
  // word is a freeform token.
@@ -3026,6 +3034,9 @@ function tokenRefusal(tok, earlier) {
3026
3034
  return `names a second tier — this call already names tier=${other}, and a row names one`;
3027
3035
  }
3028
3036
  }
3037
+ if (tok.startsWith("cell=")) {
3038
+ return "is the cell the Pull's row step wrote for a Pull routed without a draw — a replacement's cell is `tier=<cell>`";
3039
+ }
3029
3040
  if (tok === "→") return "is the row's arrow, which is written with the PR it points at — ledger.mjs row writes the whole line";
3030
3041
  if (badLabelOff([tok]) !== undefined) return LABEL_OFF_UNKNOWN;
3031
3042
  return null;
package/scripts/pull.mjs CHANGED
@@ -135,7 +135,7 @@ import { isDigits, makeDie } from "./arg.mjs";
135
135
  import { FleetDirUnresolvable, fleetFile } from "./fleet-dir.mjs";
136
136
  import { gitEnv } from "./git-env.mjs";
137
137
  import { isCLI } from "./is-cli.mjs";
138
- import { EXCLUDED_REASON, memberTokens, premisesOf, pullEnded, tierValues } from "./ledger-grammar.mjs";
138
+ import { EXCLUDED_REASON, POLICY_CELL, memberTokens, premisesOf, pullEnded, tierValues } from "./ledger-grammar.mjs";
139
139
  import { sessionFromReceipt } from "./phase0-receipt.mjs";
140
140
  import { briefPaths, briefText, defang, outOfScope, strandedRuling, ticketText } from "./ticket-text.mjs";
141
141
 
@@ -217,7 +217,8 @@ const isImplRow = (row) => memberTokens(row).some((t) => t.family === "impl");
217
217
  /**
218
218
  * The `--impl-row` the router is given: the row count the Pull creates — or,
219
219
  * while an exploration assignment is rolling (the latest row 5k and every row
220
- * after it carry no `tier=`), that row's number.
220
+ * after it carry no `tier=`: a `cell=` is a routed Pull's cell, not a draw), that
221
+ * row's number.
221
222
  */
222
223
  export function implRow(rows) {
223
224
  const impl = rows.filter(isImplRow);
@@ -964,7 +965,10 @@ class Pull {
964
965
  stage_row() {
965
966
  const { st } = this;
966
967
  const { cell, draw, reason } = st.route;
967
- const text = `${st.member}${draw === "-" ? "" : ` · tier=${cell}`}${reason === "ok" ? "" : ` · route=${reason}`}`;
968
+ // `tier=` marks a draw; a Pull routed without one still dispatches at the
969
+ // cell the router printed, carried as `cell=` so the row reads as undrawn.
970
+ const carrier = draw !== "-" ? ` · tier=${cell}` : cell !== POLICY_CELL ? ` · cell=${cell}` : "";
971
+ const text = `${st.member}${carrier}${reason === "ok" ? "" : ` · route=${reason}`}`;
968
972
  const r = this.script("row", "ledger.mjs", ["row", String(st.ticket), text]);
969
973
  if (r.status !== 0) return this.stop(withText(`ledger.mjs row failed (${r.how})`, r));
970
974
  st.stage = "render";
@@ -58,7 +58,7 @@
58
58
  // ledger's terms, not the caller's: the definition it should have
59
59
  // run under is the one its `## Dispatched` entry recorded at dispatch
60
60
  // (`agent=`, read through `ledger.mjs read`), falling back for an entry
61
- // without one to its ticket row's `tier=` token (ledger-grammar.mjs's
61
+ // without one to its ticket row's `tier=` or `cell=` token (ledger-grammar.mjs's
62
62
  // `expectedDefinition` — the same function `ledger.mjs dispatch` prints the
63
63
  // definition from), the agent type
64
64
  // it was actually dispatched as is
@@ -481,7 +481,7 @@ function main() {
481
481
  die(`batch entry missing member/agentFile: ${JSON.stringify(raw)}`);
482
482
  }
483
483
  if (impl && raw.agentFile) {
484
- die(`${raw.member}: an impl- entry carries no agentFile — its definition is the one its ## Dispatched entry recorded at dispatch, else the one its ledger row's tier= token names`);
484
+ die(`${raw.member}: an impl- entry carries no agentFile — its definition is the one its ## Dispatched entry recorded at dispatch, else the one its ledger row's tier= token, or cell= when it has none, names`);
485
485
  }
486
486
  const hasJobRecord = raw.resolvedModel && raw.resolvedThinkingLevel;
487
487
  let frontmatter = null, transcriptText = null, ticket = null, definition = null;
@@ -72,13 +72,15 @@ One line per ticket, rewritten in place (`ledger.mjs row <ticket> <text>`; `ledg
72
72
  #<t5> excluded · behind-issue:#<t3>
73
73
  ```
74
74
 
75
+ A row's cell is its `tier=` (the cell a draw picked), else its `cell=` (the cell the router printed for a Pull it routed without a draw, like `#<t6> impl-<t6> · cell=task-high`; `row` writes it, `token` refuses it), else the policy cell, `slow-high`.
76
+
75
77
  ## Writing before dispatch
76
78
 
77
79
  A member that dies between spawn and write is invisible — and members die in batches.
78
80
 
79
81
  `dispatch merge-bot` also records the queue the bot is dispatched against: its `## Dispatched` entry carries `queued=<pr>,<pr>…` (`queued=none` for an empty queue), the open `ready-to-merge` PRs gh lists at that moment. A gh that cannot answer refuses the dispatch, nothing written. `settle merge-bot-<n> --from-report` judges the bot's report against that queue, not against anything the report names: a PR from it that is still open and carries the label, with no verdict in `merged`, `held`, `conflictHold` or `refused`, fails the settle at exit 3, naming the PR, and an entry without `queued=` cannot be judged (exit 2) — settle that bot by hand.
80
82
 
81
- `dispatch impl-<N>` also records the definition it prints: the implementer's `## Dispatched` entry ends with `agent=<definition>` (`agent=fleet-implementer-<cell>`), and `ledger.mjs read` prints it under `agents`, by member name. tier-check judges the implementer against that record, falling back to the row's `tier=` for an entry without one, so a `tier=` replaced after the implementer settled does not change what it is judged against. `settle` and `rotate` keep the word with its entry. A value that is not `[a-z0-9]` words joined by `-` makes the entry malformed, and the ledger is refused.
83
+ `dispatch impl-<N>` also records the definition it prints: the implementer's `## Dispatched` entry ends with `agent=<definition>` (`agent=fleet-implementer-<cell>`), and `ledger.mjs read` prints it under `agents`, by member name. tier-check judges the implementer against that record, falling back to the row's `tier=` (else `cell=`) for an entry without one, so a `tier=` replaced after the implementer settled does not change what it is judged against. `settle` and `rotate` keep the word with its entry. A value that is not `[a-z0-9]` words joined by `-` makes the entry malformed, and the ledger is refused.
82
84
 
83
85
  ## filed and ruled
84
86
 
@@ -110,4 +112,4 @@ The ledger half reports its own readability as its own field, `ledger.ok`, the p
110
112
 
111
113
  ## Adding a token
112
114
 
113
- Token additions go through `ledger.mjs token`. `ledger.mjs token <key> <token>…` adds a token and keeps every token already on the row. A `tier=` replaces the row's `tier=` instead and keeps every other token; while the row's implementer has not settled, `token` and `row` both refuse a write that changes the row's cell. Re-typing the row with `row` replaces the whole line, so it drops the tokens you do not restate.
115
+ Token additions go through `ledger.mjs token`. `ledger.mjs token <key> <token>…` adds a token and keeps every token already on the row. A `tier=` replaces the row's `tier=` instead and keeps every other token, a `cell=` beside it included, which the `tier=` then overrides; while the row's implementer has not settled, `token` and `row` both refuse a write that changes the row's cell. Re-typing the row with `row` replaces the whole line, so it drops the tokens you do not restate.
@@ -149,7 +149,7 @@ Each member's outcome arrives as its own job status. Settle (CONTEXT.md § Coord
149
149
 
150
150
  ## The implementer's tier is the definition's
151
151
 
152
- The tier lives in that definition's frontmatter (`agents/fleet-implementer-<cell>.agent.md`; `slow-high`, the policy cell, for a row with no `tier=`), which is what an omitted `model` takes first — the session's tier applies only when the definition names none, and a member dispatched with `model` set does not get the declared tier back. Omitting `model` is therefore still the mechanism; what changed is that the tier it resolves to is now declared and pinned rather than inherited by accident. Keep `name: impl-<N>`: the name is what makes a member, and both the spend classifier and `member-outcomes.mjs` read it.
152
+ The tier lives in that definition's frontmatter (`agents/fleet-implementer-<cell>.agent.md`; `slow-high`, the policy cell, for a row with no `tier=` or `cell=`), which is what an omitted `model` takes first — the session's tier applies only when the definition names none, and a member dispatched with `model` set does not get the declared tier back. Omitting `model` is therefore still the mechanism; what changed is that the tier it resolves to is now declared and pinned rather than inherited by accident. Keep `name: impl-<N>`: the name is what makes a member, and both the spend classifier and `member-outcomes.mjs` read it.
153
153
 
154
154
  ## The merge bot's tier buys nothing its backstop does not cover
155
155
 
@@ -252,7 +252,9 @@ terminating in exactly one dispatch or an empty shortlist:
252
252
  `POLICY=… CELL=… DRAW=… STRATUM=… OBJECTIVE=… REASON=…` (the router's arguments paragraph below the list
253
253
  says what each argument is); then `ledger.mjs row <N> "impl-<N>[ · tier=<CELL>][ · route=<REASON>]"`,
254
254
  `tier=<CELL>` exactly when `DRAW` is not `-`; then the dispatch at once: claim
255
- what you are about to dispatch; dispatch what you have just claimed. Router
255
+ what you are about to dispatch; dispatch what you have just claimed. A Pull
256
+ routed without a draw writes `cell=<CELL>` instead, unless `CELL` is the policy
257
+ cell, `slow-high`, which a row with neither runs. Router
256
258
  exit 2 → no row and no dispatch: release the claim (`release-ticket.sh`, SKILL.md's
257
259
  Failure handling row for a claim abandoned mid-run) and emit an event, a probe that could not look — a table the router
258
260
  refuses refuses every Pull.
@@ -261,7 +263,8 @@ terminating in exactly one dispatch or an empty shortlist:
261
263
  row count the Pull creates — or, while an assignment is rolling (the latest
262
264
  row 5k and every row after it carry no `tier=`), that row's number;
263
265
  `--chain-head` marks a ticket another open ticket sequences after, which is
264
- what rolls it. `--arm` is `A` for an even ticket number and `B` for an odd
266
+ what rolls it. A `cell=` is no draw: a row carrying one and no `tier=` still
267
+ rolls. `--arm` is `A` for an even ticket number and `B` for an odd
265
268
  one; a B Pull routes exactly as an A one until the table opens arm B.
266
269
  `--session` is this run's own session directory. The router routes by the
267
270
  row set of the run's Objective, `OBJECTIVE`, which it reads off the phase-0
@@ -399,7 +402,8 @@ the `render` command to run first, and refuses once the
399
402
  run is draining: drain stops supply. It also refuses a row whose `tier=`
400
403
  names no single definition — two different values, or one that is not a
401
404
  definition suffix — or names one with no `agents/<definition>.agent.md`,
402
- before the member is live; fix the row with `row` first. Once every refusal
405
+ before the member is live; fix the row with `row` first. A row with no `tier=`
406
+ is held to the same through its `cell=`. Once every refusal
403
407
  has passed, `dispatch` deletes the member's prior report,
404
408
  `<scratch>/reports/<member>.json`, when its brief's sidecar names an absolute
405
409
  `scratch`, so a prior run's report cannot settle this one. A sidecar naming
@@ -436,8 +440,12 @@ policy cell is the `cost` row set's, so the draw is the same under both. While t
436
440
  true every Pull draws, over every cell, the policy cell included. An
437
441
  Exploration Pull records `tier=<cell>` in the row, and a replacement inherits the row's tier —
438
442
  written at the Pull's row step, ahead of `ledger.mjs dispatch`, which reads it
439
- and prints `fleet-implementer-<cell>` as the `agent` to dispatch; a row with
440
- no `tier=` runs the policy cell. The Pull's cell binds the row's implementer
443
+ and prints `fleet-implementer-<cell>` as the `agent` to dispatch. A Pull the
444
+ router routes without a draw records the cell it printed as `cell=<cell>`
445
+ instead, and dispatches there the same way; `cell=` is no draw, so a row
446
+ carrying it and no `tier=` still reads as "the draw has not happened yet",
447
+ and a draw skipped on a chain head still passes to the next Pull. A `tier=` on the row decides over a
448
+ `cell=`. A row with neither runs the policy cell. The Pull's cell binds the row's implementer
441
449
  (its newest, on a resumed or re-Pulled row):
442
450
  `ledger.mjs row` and `ledger.mjs token` refuse a write that changes it until that implementer has
443
451
  settled. Once it has, a replacement may run at another cell, set with