@feigi/fleet-ctl 3.159.0 → 3.160.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.159.0",
3
+ "version": "3.160.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": {
@@ -461,8 +461,8 @@ function ceEntry(e) {
461
461
 
462
462
  // The heading of the view of the Fit: its failed-Fit flag first, then its
463
463
  // source line, the check it could not make, how a Pull is dispatched, its
464
- // labels and model-change notices, burn-in progress, the tripped Cells and the
465
- // model-name line, where each is set.
464
+ // labels and model-change notices, burn-in progress, the tripped Cells, the
465
+ // Cells the install does not run and the model-name line, where each is set.
466
466
  function ceFitHeading(p) {
467
467
  const box = el("div");
468
468
  if (p.flag) { const flag = el("div", "ce-alert"); flag.append(el("div", "ce-verdict", p.flag)); box.append(flag); }
@@ -476,6 +476,10 @@ function ceFitHeading(p) {
476
476
  for (const c of p.burnIn.cells) box.append(el("div", "ce-cand", `${c.cell} · ${c.n} of ${c.of} merged PRs`));
477
477
  }
478
478
  if (p.tripped) box.append(el("div", "ce-note", p.tripped));
479
+ if (p.unrunnable) {
480
+ box.append(el("div", "ce-note", p.unrunnable.heading));
481
+ for (const c of p.unrunnable.cells) box.append(el("div", "ce-cand", c.text));
482
+ }
479
483
  if (p.modelLine) box.append(el("div", "ce-note ce-amber", p.modelLine));
480
484
  return box;
481
485
  }
@@ -366,6 +366,15 @@ function reasonWords(r, table) {
366
366
  const named = r.tripped.length === 1 ? `${row}'s ${r.tripped[0]}` : `${row}'s Cell (one of ${r.tripped.join(", ")})`;
367
367
  return [part(`${named} tripped${drawn ? "" : ": default Cell"}`, { href: rowHref(r, table) })];
368
368
  }
369
+ case "table-cell-unrunnable": {
370
+ // The Routing keeps the Cells the install does not run, not which of them the row named: the installed table's
371
+ // row for the group says, when it names one of them. A row Cell with no definition is in no list, which can
372
+ // then be empty.
373
+ const rowCell = table === null ? undefined : (table.rows[r.objective][r.stratum] ?? table.rows[r.objective]["*"]);
374
+ const cell = r.unrunnable.includes(rowCell) ? rowCell : r.unrunnable.length === 1 ? r.unrunnable[0] : null;
375
+ const named = cell !== null ? `${row}'s ${cell}` : r.unrunnable.length === 0 ? `${row}'s Cell` : `${row}'s Cell (one of ${r.unrunnable.join(", ")})`;
376
+ return [part(`${named} unrunnable here${drawn ? "" : ": default Cell"}`, { href: rowHref(r, table) })];
377
+ }
369
378
  case "guard-tripped":
370
379
  return [part(drawn ? `left out as tripped: ${r.tripped.join(", ")}` : "every other Cell tripped: no draw")];
371
380
  case "guard-missing": return [part("no cost guard yet: default Cell only")];
@@ -17,7 +17,9 @@
17
17
  // lays out the Cell the table plus the workspace's guard route to and why
18
18
  // (ticket-router.mjs's rowDispatch, the function `route` itself calls), with
19
19
  // every candidate's verdict and range, and for each group the Cells it draws
20
- // over; above them, burn-in progress, the Cells the guard has tripped, a notice
20
+ // over; above them, burn-in progress, the Cells the guard has tripped and,
21
+ // apart from them, the Cells the install does not run (each with its role, the
22
+ // model the role resolves to and the levels that model runs), a notice
21
23
  // for each starting Cell whose model changed and restarted burn-in, and a flag
22
24
  // while the newest refit failed and an older Fit, or the starting table, routes.
23
25
  // The receipts' newest `metrics` step is what the guard section quotes when there
@@ -35,7 +37,7 @@
35
37
  import { isDeepStrictEqual } from "node:util";
36
38
  import { CELL, OBJECTIVES, POLICY_CELL, STARTING_CELLS } from "./ledger-grammar.mjs";
37
39
  import { costGuardFault } from "./fleet-tick.mjs";
38
- import { MIN_N, installOf, parseGuard, readGuard, rowDispatch } from "./ticket-router.mjs";
40
+ import { MIN_N, defaultCellOf, installOf, parseGuard, readGuard, rowDispatch, startingCellsOf, unrunnableCells } from "./ticket-router.mjs";
39
41
  import { implementerCell, modelsEqual, parseModelRoute, resolveRole } from "./tier-roles.mjs";
40
42
 
41
43
  // The implementer Cells, in the order the guard section draws them: one per
@@ -487,29 +489,38 @@ function failedFitFlag(step, p) {
487
489
  return `this run's Fit failed at ${when(step.at)}: ${why}; ${routes}`;
488
490
  }
489
491
 
490
- // How a Pull is dispatched, for every group alike: what `route` does under the guard.
491
- function dispatchHeading(table, guard) {
492
- if (guard === null) return `no cost guard: every Pull runs at ${POLICY_CELL}, the default Cell`;
492
+ // How a Pull is dispatched, for every group alike: what `route` does under the guard and the install
493
+ // (installOf's, or null where it was not read).
494
+ function dispatchHeading(table, guard, install) {
495
+ if (guard === null) return `no cost guard: every Pull runs at ${defaultCellOf(install)}, the default Cell`;
493
496
  if (table === null) return null;
494
497
  if (table.burn_in) return "burn-in: every Pull is drawn over the starting Cells the guard has not tripped";
495
498
  return "every 5th Pull that is no chain head is drawn over its group's exploration Cells; the rest run the group's Cell";
496
499
  }
497
500
 
498
- // Merged PRs per starting Cell, against MIN_N: the counts burn-in is judged on —
501
+ // Merged PRs per counted starting Cell, against MIN_N: the counts burn-in is judged on —
499
502
  // the Fit's own guard counts while the Fit routes, the cost guard's while the
500
- // starting table does. Null with neither to count from. The heading follows the
503
+ // starting table does. Null with neither to count from. The Cells counted are
504
+ // the ones the Fit recorded, or the install this cockpit reads runs while the
505
+ // starting table routes (countedStartingCells); the heading says which set it
506
+ // counted and which starting Cells it left out as unrunnable. It follows the
501
507
  // routing table's `burn_in`, and says "ended" only of counts that all reach
502
508
  // MIN_N: a Fit sets its flag off its own counts, but the starting table's flag
503
509
  // is its own, whatever the cost guard counts since.
504
- function burnInProgress(p, guard, table) {
510
+ function burnInProgress(p, guard, table, inst) {
505
511
  const n = p !== null ? p.table.guard.n : guard?.n;
506
512
  if (!isRecord(n)) return null;
507
- const cells = STARTING_CELLS.map((cell) => ({ cell, n: count(n[cell]) ?? 0, of: MIN_N }));
513
+ const counted = countedStartingCells(p, inst);
514
+ const left = STARTING_CELLS.filter((c) => !counted.includes(c));
515
+ const subset = left.length > 0;
516
+ const cells = counted.map((cell) => ({ cell, n: count(n[cell]) ?? 0, of: MIN_N }));
508
517
  const done = cells.filter((c) => c.n >= MIN_N).length;
509
- const tally = `${done} of ${cells.length} starting Cells ${done === 1 ? "has" : "have"} the ${MIN_N} merged PRs each needs`;
518
+ const kind = subset ? "runnable starting" : "starting";
519
+ const out = subset ? `; ${list(left)} unrunnable` : "";
520
+ const tally = `${done} of ${cells.length} ${kind} Cells ${done === 1 ? "has" : "have"} the ${MIN_N} merged PRs each needs${out}`;
510
521
  if (table === null || table.burn_in) return { heading: `burn-in: ${tally}`, cells };
511
522
  const heading = done === cells.length
512
- ? `burn-in ended: every starting Cell has its ${MIN_N} merged PRs`
523
+ ? `burn-in ended: every ${kind} Cell has its ${MIN_N} merged PRs${out}`
513
524
  : `no burn-in: the starting table routes without it, though only ${tally}`;
514
525
  return { heading, cells };
515
526
  }
@@ -520,14 +531,29 @@ function trippedWords(guard) {
520
531
  return guard.tripped.length === 0 ? "the cost guard has tripped no Cell" : `tripped by the cost guard: ${list(guard.tripped)}`;
521
532
  }
522
533
 
523
- // A notice for each starting Cell whose role's model changed and so restarted
534
+ // The starting Cells burn-in counts, in their order: the set the Fit recorded
535
+ // while a Fit routes — every starting Cell for a Fit that records none, as
536
+ // every Fit did — else those the cockpit's own install read runs, all three
537
+ // while it has none.
538
+ function countedStartingCells(p, inst) {
539
+ return p === null ? startingCellsOf(inst.install) : fitStartingCells(p.table);
540
+ }
541
+
542
+ // The starting Cells a Fit's table records, in their order: all three for a table that records none, or none usable.
543
+ function fitStartingCells(table) {
544
+ const recorded = table.starting_cells;
545
+ const valid = Array.isArray(recorded) && recorded.length > 0 && recorded.every((c) => STARTING_CELLS.includes(c));
546
+ return valid ? STARTING_CELLS.filter((c) => recorded.includes(c)) : [...STARTING_CELLS];
547
+ }
548
+
549
+ // A notice for each counted starting Cell whose role's model changed and so restarted
524
550
  // burn-in: the Fit holds an older generation of it in the root group, and its
525
551
  // newest generation is short of MIN_N merged PRs in the counts the Fit judged
526
552
  // burn-in on. None while the starting table routes, which holds no estimates.
527
553
  function modelChanges(p) {
528
554
  if (p === null || !p.table.burn_in) return [];
529
555
  const root = isRecord(p.table.estimates?.["*"]) ? p.table.estimates["*"] : {};
530
- return STARTING_CELLS.flatMap((cell) => {
556
+ return fitStartingCells(p.table).flatMap((cell) => {
531
557
  const e = root[cell];
532
558
  const older = isRecord(e?.older) ? Object.keys(e.older) : [];
533
559
  const k = count(p.table.guard.n[cell]) ?? 0;
@@ -550,6 +576,21 @@ function installFrom(modelRoles, catalog, agents) {
550
576
  return { install: installOf({ modelRoles: modelRoles.value, catalog: catalog.value, definitions: agents.list.map((a) => a.file) }), why: null, note };
551
577
  }
552
578
 
579
+ // The Cells this install does not run, apart from the tripped ones, each with its role, the model the role resolves
580
+ // to and the levels that model runs: `{ heading, cells: [{ cell, role, model, levels, text }] }`. While the install
581
+ // has not been read the heading says so, and no Cell is named.
582
+ function unrunnableView(inst) {
583
+ if (inst.install === null) return { heading: `unrunnable Cells: not checked: ${inst.why}`, cells: [] };
584
+ const cells = unrunnableCells(inst.install).map((cell) => {
585
+ const role = CELL.exec(cell)[1];
586
+ const model = inst.install.models[role];
587
+ const levels = inst.install.ladders[role];
588
+ return { cell, role, model, levels, text: `${cell} · modelRoles.${role} → ${model ?? "no model"} runs ${levels.join(", ") || "none"}` };
589
+ });
590
+ const heading = cells.length === 0 ? "the install runs every Cell it has a definition for" : `not run by this install: ${list(cells.map((c) => c.cell))}`;
591
+ return { heading, cells };
592
+ }
593
+
553
594
  // The Cells a group draws over, in words: rowDispatch's draw, which is centred on
554
595
  // the group's `cost` row Cell whichever Objective routes the Pull. Null with no
555
596
  // guard, when nothing is drawn.
@@ -557,7 +598,11 @@ function exploringWords(table, guard, stratum, inst) {
557
598
  if (guard === null) return null;
558
599
  if (!table.burn_in && inst.install === null) return `exploring: not checked: ${inst.why}`;
559
600
  const rd = rowDispatch({ table, guard, objective: "cost", stratum, install: inst.install });
560
- if (table.burn_in) return rd.draw === null ? "draws nothing: every starting Cell is tripped" : `drawn over ${list(rd.draw.cells)}`;
601
+ if (table.burn_in) {
602
+ if (rd.draw !== null) return `drawn over ${list(rd.draw.cells)}`;
603
+ const orUnrunnable = unrunnableCells(inst.install).some((c) => STARTING_CELLS.includes(c)) ? " or unrunnable" : "";
604
+ return `draws nothing: every starting Cell is tripped${orUnrunnable}`;
605
+ }
561
606
  const words = rd.draw === null ? "exploring nothing: no exploration Cell this install runs is left untripped" : `exploring ${list(rd.draw.cells)}`;
562
607
  return inst.note === null ? words : `${words}; ${inst.note}`;
563
608
  }
@@ -584,16 +629,19 @@ function intervalWords(range, objective) {
584
629
  return `95% interval [${one(range[0])}, ${one(range[1])}]`;
585
630
  }
586
631
 
587
- // One row of the routing table under the guard: the Cell it routes to and why,
588
- // the row's own Cell where the guard holds it back, and each candidate's n (null
589
- // where the table carries no count), verdict and interval.
590
- function rowEntry(table, guard, modelRoles, objective, stratum) {
591
- const rd = rowDispatch({ table, guard, objective, stratum });
632
+ // One row of the routing table under the guard and the install: the Cell it
633
+ // routes to and why, the row's own Cell where the guard holds it back or the
634
+ // install does not run it (`install` is installOf's answer, null where the
635
+ // cockpit has not read one), and each candidate's n (null where the table
636
+ // carries no count), verdict and interval.
637
+ function rowEntry(table, guard, modelRoles, objective, stratum, install) {
638
+ const rd = rowDispatch({ table, guard, objective, stratum, install });
592
639
  const row = table.rows[objective][stratum];
593
640
  const record = isRecord(table.reasons?.[objective]?.[stratum]) ? table.reasons[objective][stratum] : null;
594
641
  const estimates = isRecord(table.estimates?.[stratum]) ? table.estimates[stratum] : {};
595
- const held = row === rd.policy ? null
596
- : rd.reason === "guard-missing" ? `${row} held: no cost guard` : `${row} tripped`;
642
+ const held = rd.reason === "table-cell-unrunnable" ? `${row} unrunnable here`
643
+ : row === rd.policy ? null
644
+ : rd.reason === "guard-missing" ? `${row} held: no cost guard` : `${row} tripped`;
597
645
  return {
598
646
  cell: rd.policy,
599
647
  held,
@@ -647,7 +695,9 @@ function groupOf(stratum) {
647
695
  * readCostGuard's answer and `routed` readGuard's for the same file, null when
648
696
  * the router reads none; `step` the receipts' newest `metrics` step that tried
649
697
  * a refit; `agents`, `modelRoles` and `catalog` the cockpit's own reads, which
650
- * say what this install runs for each group's exploration Cells; `objective`
698
+ * say what this install runs: each group's exploration Cells, the Cells it
699
+ * does not run, and the starting Cells burn-in counts while the starting table
700
+ * routes; `objective`
651
701
  * the live run's, or null. Each Objective's lines are the table's groups in
652
702
  * the table's order, the tree's root first; every line has an anchor the
653
703
  * `#cells/row/<objective>/<stratum>` link lands on. A candidate's generation
@@ -668,7 +718,7 @@ function fitView({ fit, starting, guard, routed, modelRoles, catalog, agents, st
668
718
  const mark = "¹";
669
719
  const inst = installFrom(modelRoles, catalog, agents);
670
720
  const entry = (o, s) => {
671
- const e = rowEntry(table, routed, modelRoles, o, s);
721
+ const e = rowEntry(table, routed, modelRoles, o, s, inst.install);
672
722
  return { ...e, candidates: e.candidates.map((c) => ({ ...c, nMark: s === "*" && differ.includes(c.cell) ? mark : null })) };
673
723
  };
674
724
  // A group's exploration Cells are centred on its `cost` row whichever
@@ -698,11 +748,12 @@ function fitView({ fit, starting, guard, routed, modelRoles, catalog, agents, st
698
748
  title: "The Fit that routes this run",
699
749
  flag: failedFitFlag(step, p),
700
750
  source,
701
- heading: dispatchHeading(table, routed),
751
+ heading: dispatchHeading(table, routed, inst.install),
702
752
  labels,
703
753
  notices: modelChanges(p),
704
- burnIn: burnInProgress(p, routed, table),
754
+ burnIn: burnInProgress(p, routed, table, inst),
705
755
  tripped: trippedWords(routed),
756
+ unrunnable: unrunnableView(inst),
706
757
  modelLine,
707
758
  footnotes: differ.length === 0 ? [] : [{ mark, text: `${list(differ)}: the guard counts merges by GitHub's state, the Fit by Rulings, and the Fit admits only drawn or rule-sized Pulls` }],
708
759
  objectives,
@@ -1036,10 +1036,16 @@ export function drawCell({ session, ticket, policyCell, cells }) {
1036
1036
  // STRATUM the group's rule path BRIEF the brief's chars
1037
1037
  // CRITERIA the criteria count PARENT a Slice's parent issue
1038
1038
  // SIZED arm B's sizing label OBJECTIVE cost | speed
1039
- // TRIPPED the guard's tripped Cells REASON the first thing that went wrong
1039
+ // TRIPPED the guard's tripped Cells UNRUNNABLE the Cells the install does not run
1040
+ // REASON the first thing that went wrong
1040
1041
  // DRAW and BY are `-` together (no draw); so are BRIEF and CRITERIA (no issue
1041
- // read), and PARENT is `-` with them. A line written before PARENT was a part
1042
- // carries none, and reads as `PARENT=-`.
1042
+ // read), and PARENT is `-` with them. UNRUNNABLE lists every Cell with an
1043
+ // implementer definition whose level its role's model does not run, sorted and
1044
+ // each once — a list out of that order is no Routing — `-` for none; it is
1045
+ // worked out when the Pull is routed and is no guard verdict. A
1046
+ // line written before PARENT was a part carries none, and reads as `PARENT=-`;
1047
+ // one written before UNRUNNABLE was a part carries none, and reads as
1048
+ // `UNRUNNABLE=-`.
1043
1049
  //
1044
1050
  // STRATUM names the group the Pull was routed to — the router table's node the
1045
1051
  // walk ended at — by its rule path. `*` is the root, the group of every ticket
@@ -1062,11 +1068,12 @@ export const isRulePath = (x) => typeof x === "string" && RULE_PATH.test(x);
1062
1068
  export const OBJECTIVES = Object.freeze(["cost", "speed"]);
1063
1069
  const DRAWN_BY = Object.freeze(["burn-in", "every-5th"]);
1064
1070
  export const ROUTING_REASONS = Object.freeze([
1065
- "ok", "no-issue-json", "no-sizing", "guard-missing", "guard-tripped", "table-cell-tripped", "fit-missing", "fit-unreadable", "fit-invalid",
1071
+ "ok", "no-issue-json", "no-sizing", "guard-missing", "guard-tripped", "table-cell-tripped", "table-cell-unrunnable", "fit-missing", "fit-unreadable", "fit-invalid",
1066
1072
  ]);
1067
1073
  const SIZINGS = Object.freeze(["light", "heavy"]);
1068
- const ROUTING_KEYS = Object.freeze(["POLICY", "CELL", "DRAW", "BY", "STRATUM", "BRIEF", "CRITERIA", "PARENT", "SIZED", "OBJECTIVE", "TRIPPED", "REASON"]);
1074
+ const ROUTING_KEYS = Object.freeze(["POLICY", "CELL", "DRAW", "BY", "STRATUM", "BRIEF", "CRITERIA", "PARENT", "SIZED", "OBJECTIVE", "TRIPPED", "UNRUNNABLE", "REASON"]);
1069
1075
  const PARENT_AT = ROUTING_KEYS.indexOf("PARENT");
1076
+ const UNRUNNABLE_AT = ROUTING_KEYS.indexOf("UNRUNNABLE");
1070
1077
  const ISSUE = /^[1-9][0-9]*$/;
1071
1078
  const COUNT = /^(?:0|[1-9][0-9]*)$/;
1072
1079
  const DRAW = /^([1-9][0-9]*)\/([1-9][0-9]*)$/;
@@ -1075,14 +1082,16 @@ const DRAW = /^([1-9][0-9]*)\/([1-9][0-9]*)$/;
1075
1082
  * A Routing line read into its parts, or null when it is not one.
1076
1083
  * @returns {null | { policy: string, cell: string, draw: null | { k: number, K: number }, by: null | string,
1077
1084
  * stratum: string, brief: null | number, criteria: null | number, parent: null | number, sized: null | string,
1078
- * objective: string, tripped: string[], reason: string }}
1085
+ * objective: string, tripped: string[], unrunnable: string[], reason: string }}
1079
1086
  */
1080
1087
  export function parseRouting(line) {
1081
1088
  if (typeof line !== "string") return null;
1082
1089
  const words = line.split(" ");
1083
- // A line written before PARENT was a part is one word short; one that holds
1084
- // PARENT= and lacks another key instead fails the per-key check.
1085
- if (words.length === ROUTING_KEYS.length - 1) words.splice(PARENT_AT, 0, "PARENT=-");
1090
+ // A line written before UNRUNNABLE was a part is one word short of the keys, and one written before PARENT
1091
+ // too is two short; each reads with the key it lacks as `-`. A line that holds PARENT= and lacks another
1092
+ // key instead fails the per-key check.
1093
+ if (words.length === ROUTING_KEYS.length - 2) words.splice(PARENT_AT, 0, "PARENT=-");
1094
+ if (words.length === ROUTING_KEYS.length - 1) words.splice(UNRUNNABLE_AT, 0, "UNRUNNABLE=-");
1086
1095
  if (words.length !== ROUTING_KEYS.length) return null;
1087
1096
  const v = {};
1088
1097
  for (const [i, key] of ROUTING_KEYS.entries()) {
@@ -1091,7 +1100,9 @@ export function parseRouting(line) {
1091
1100
  }
1092
1101
  const opt = (x, ok) => (x === "-" ? null : ok(x) ? x : undefined);
1093
1102
  const count = (x) => (x === "-" ? null : COUNT.test(x) ? Number(x) : undefined);
1094
- const tripped = v.TRIPPED === "-" ? [] : v.TRIPPED.split(",");
1103
+ const cellList = (x) => (x === "-" ? [] : x.split(","));
1104
+ const tripped = cellList(v.TRIPPED);
1105
+ const unrunnable = cellList(v.UNRUNNABLE);
1095
1106
  const d = DRAW.exec(v.DRAW);
1096
1107
  const r = {
1097
1108
  policy: CELL.test(v.POLICY) ? v.POLICY : undefined,
@@ -1105,6 +1116,7 @@ export function parseRouting(line) {
1105
1116
  sized: opt(v.SIZED, (x) => SIZINGS.includes(x)),
1106
1117
  objective: OBJECTIVES.includes(v.OBJECTIVE) ? v.OBJECTIVE : undefined,
1107
1118
  tripped: tripped.every((c) => CELL.test(c)) ? tripped : undefined,
1119
+ unrunnable: unrunnable.every((c, i) => CELL.test(c) && (i === 0 || unrunnable[i - 1] < c)) ? unrunnable : undefined,
1108
1120
  reason: ROUTING_REASONS.includes(v.REASON) ? v.REASON : undefined,
1109
1121
  };
1110
1122
  if (Object.values(r).includes(undefined)) return null;
@@ -1115,12 +1127,13 @@ export function parseRouting(line) {
1115
1127
  }
1116
1128
 
1117
1129
  /** The Routing line for parsed parts; throws on parts no Routing line can carry, so nothing writes one parseRouting refuses. */
1118
- export function formatRouting({ policy, cell, draw, by, stratum, brief, criteria, parent, sized, objective, tripped, reason }) {
1130
+ export function formatRouting({ policy, cell, draw, by, stratum, brief, criteria, parent, sized, objective, tripped, unrunnable, reason }) {
1119
1131
  const none = (x) => (x === null ? "-" : String(x));
1132
+ const cells = (xs) => (xs.length === 0 ? "-" : xs.join(","));
1120
1133
  const line = [
1121
1134
  `POLICY=${policy}`, `CELL=${cell}`, `DRAW=${draw === null ? "-" : `${draw.k}/${draw.K}`}`, `BY=${none(by)}`,
1122
1135
  `STRATUM=${stratum}`, `BRIEF=${none(brief)}`, `CRITERIA=${none(criteria)}`, `PARENT=${none(parent)}`, `SIZED=${none(sized)}`,
1123
- `OBJECTIVE=${objective}`, `TRIPPED=${tripped.length === 0 ? "-" : tripped.join(",")}`, `REASON=${reason}`,
1136
+ `OBJECTIVE=${objective}`, `TRIPPED=${cells(tripped)}`, `UNRUNNABLE=${cells(unrunnable)}`, `REASON=${reason}`,
1124
1137
  ].join(" ");
1125
1138
  if (parseRouting(line) === null) throw new Error(`not a Routing: ${line}`);
1126
1139
  return line;
@@ -4,13 +4,17 @@
4
4
  // corpus written before its latest columns, refresh the cost guard over it, then
5
5
  // write the Fit beside that guard.
6
6
  //
7
- // metrics-refresh.mjs [--repo <dir>] [--no-fit]
7
+ // metrics-refresh.mjs [--repo <dir>] [--no-fit] [--model-roles <path>] [--catalog <path>]
8
8
  //
9
9
  // --repo the workspace whose `.fleet/` and `docs/metrics/` the duties read
10
10
  // and write; default the main checkout of the repository the cwd is
11
11
  // in, where the router script appends its pending rows
12
12
  // --no-fit the duties only, no Fit: close-out passes it, so a run computes
13
13
  // one Fit, at its phase 0, and each close-out's rows route the next run
14
+ // --model-roles, --catalog
15
+ // the files holding `modelRoles` and omp's model catalog, read in
16
+ // place of omp's own, as for `ticket-router.mjs route`; the Fit
17
+ // reads them to count the starting Cells the install runs
14
18
  //
15
19
  // DRAIN. `ticket-router.mjs route` appends one row per Pull to
16
20
  // `.fleet/ticket-features.pending.tsv`; this moves them into
@@ -81,13 +85,18 @@
81
85
  // file. A split stands in the `table` once it has passed at two consecutive
82
86
  // Fits on the same input or inputs, and is gone at the first Fit it fails;
83
87
  // the next Fit reads the previous one's `gate` from the file this one
84
- // replaces, which is all it carries forward. The Fit is a pure function of
85
- // the records, the guard, the prior and that `gate`: the TSVs at the recorded
86
- // blob ids, the guard and the prior fit to the same table again. So a Fit
87
- // whose `records` are the previous one's is no look at the gate: it keeps
88
- // that one's `passed` and `stands`, and a phase 0 run again over records that
89
- // have not changed neither advances a split's count nor resets it. With no
90
- // records it is the starting table's fit, as any other. It is called
88
+ // replaces, which is all it carries forward. Burn-in holds until every
89
+ // starting Cell the install runs has its merged PRs, and the `table` records
90
+ // that set as `starting_cells`: the install is read as `ticket-router.mjs
91
+ // route` reads it — live, or from the files `--model-roles <path>` and
92
+ // `--catalog <path>` name — and a read that fails warns on stderr and counts
93
+ // all three starting Cells. The Fit is a pure function of the records, the
94
+ // guard, the prior, that set and that `gate`: the TSVs at the recorded blob
95
+ // ids, the guard, the prior and the recorded set fit to the same table again.
96
+ // So a Fit whose `records` are the previous one's is no look at the gate: it
97
+ // keeps that one's `passed` and `stands`, and a phase 0 run again over records
98
+ // that have not changed neither advances a split's count nor resets it. With
99
+ // no records it is the starting table's fit, as any other. It is called
91
100
  // in-process because a fit has no verdict for an exit status to carry. It
92
101
  // never fails the run: an error prints `metrics-refresh: fit: failed — <why>`,
93
102
  // leaves the old file in place, so the run routes by the last Fit that
@@ -114,7 +123,7 @@ import { COLUMNS as MEMBER_COLUMNS, ENDINGS, isImplementer, parseTsv as parseMem
114
123
  import { blobId } from "./pr-cost.mjs";
115
124
  import { FEATURE_COLUMNS, parseFeatures } from "./pull-attribution.mjs";
116
125
  import { REPORT_STATUSES } from "./report-files.mjs";
117
- import { DEFAULT_TABLE, FIT_FILE, INSTALL_PACKAGE, fitTree, installVersion, readGuard, validateTable } from "./ticket-router.mjs";
126
+ import { DEFAULT_TABLE, FIT_FILE, INSTALL_PACKAGE, fitTree, installVersion, readGuard, readInstall, startingCellsOf, validateTable } from "./ticket-router.mjs";
118
127
  import { parseTierOutcomes } from "./tier-outcomes.mjs";
119
128
 
120
129
  const NAME = "metrics-refresh";
@@ -317,10 +326,12 @@ function previousGate(repo) {
317
326
  // The Fit over `repo`'s working-tree TSVs and `written`, the guard file the
318
327
  // guard duty just wrote (parsed), with the router table at `tablePath` as its
319
328
  // prior, written to `.fleet/router-fit.json` through a temp file and a rename.
320
- // Throws on anything it cannot read, fit or write, before the rename, so the
329
+ // Burn-in counts `startingCells`, the starting Cells the install runs — all
330
+ // three when none is named — which the Fit's `table` records. Throws on anything
331
+ // it cannot read, fit or write, before the rename, so the
321
332
  // old file stays as it was: a Fit that throws is no look at the split gate,
322
333
  // and the next one reads the gate the old file holds.
323
- export function writeFit(repo, written, { tablePath = DEFAULT_TABLE, packagePath = INSTALL_PACKAGE, now = new Date() } = {}) {
334
+ export function writeFit(repo, written, { tablePath = DEFAULT_TABLE, packagePath = INSTALL_PACKAGE, now = new Date(), startingCells } = {}) {
324
335
  const guard = readGuard(written);
325
336
  if (guard === null) throw new Error(`${GUARD} is not a guard the router reads`);
326
337
  let prior;
@@ -341,7 +352,7 @@ export function writeFit(repo, written, { tablePath = DEFAULT_TABLE, packagePath
341
352
  const members = read(MEMBERS, parseMemberTsv);
342
353
  const verdicts = read(TIERS, parseTierOutcomes);
343
354
  const features = read(FEATURES, parseFeatures);
344
- const { table, gate } = fitTree({ prior, features, members, verdicts, guard, previous });
355
+ const { table, gate } = fitTree({ prior, features, members, verdicts, guard, previous, startingCells });
345
356
  // The tree the gate grew is the one `route` will read it through.
346
357
  const valid = validateTable(table);
347
358
  if (valid instanceof Error) throw valid;
@@ -368,11 +379,17 @@ export function writeFit(repo, written, { tablePath = DEFAULT_TABLE, packagePath
368
379
 
369
380
  // The Fit as the run calls it: only beside a guard the guard duty wrote, and
370
381
  // never a failure of the run — its error is a line, and the exit stays as it was.
371
- function fit(repo, written) {
382
+ // `sources` name the files the install read takes in place of omp's own (ticket-router.mjs's
383
+ // readInstall): burn-in counts the starting Cells that install runs, all three when it cannot be read.
384
+ function fit(repo, written, sources) {
372
385
  if (written === null) return say(`fit: skipped, no guard written — ${FIT} left as it is`);
386
+ const { install, why } = readInstall(sources);
387
+ if (install === null) {
388
+ process.stderr.write(`${NAME}: WARNING cannot read what this install runs: ${why} — burn-in counts all three starting Cells\n`);
389
+ }
373
390
  let p;
374
391
  try {
375
- p = writeFit(repo, written);
392
+ p = writeFit(repo, written, { startingCells: startingCellsOf(install) });
376
393
  } catch (e) {
377
394
  return say(`fit: failed — ${e.message}`);
378
395
  }
@@ -381,7 +398,7 @@ function fit(repo, written) {
381
398
 
382
399
  function main() {
383
400
  const die = makeDie(NAME);
384
- const F = defineFlags(die, { flags: { repo: "value", "no-fit": "bool" } });
401
+ const F = defineFlags(die, { flags: { repo: "value", "no-fit": "bool", "model-roles": "value", catalog: "value" } });
385
402
  F.sweep();
386
403
  F.stray();
387
404
  let repo = F.arg("repo") === null ? null : resolve(F.arg("repo"));
@@ -404,7 +421,7 @@ function main() {
404
421
  return;
405
422
  }
406
423
  }
407
- if (!F.has("no-fit")) fit(repo, written);
424
+ if (!F.has("no-fit")) fit(repo, written, { modelRoles: F.arg("model-roles"), catalog: F.arg("catalog") });
408
425
  }
409
426
 
410
427
  if (isCLI(import.meta.url)) main();
@@ -13,7 +13,7 @@
13
13
  // grammar): `POLICY=<cell> CELL=<cell> DRAW=<k/K|-> BY=<burn-in|every-5th|->
14
14
  // STRATUM=<rule path> BRIEF=<chars|-> CRITERIA=<n|-> PARENT=<N|->
15
15
  // SIZED=<light|heavy|-> OBJECTIVE=<cost|speed> TRIPPED=<cell,…|->
16
- // REASON=<reason>`,
16
+ // UNRUNNABLE=<cell,…|-> REASON=<reason>`,
17
17
  // routing by the objective's row set, and appends the Pull's
18
18
  // ticket-features row to the pending TSV (by default
19
19
  // `ticket-features.pending.tsv` beside `--guard`, in the run's `.fleet/`).
@@ -30,16 +30,25 @@
30
30
  // an unreadable/invalid table: the caller does not dispatch then. With no
31
31
  // `--session`, the session is the one the phase-0 receipt
32
32
  // `.fleet/phase0.json` records, and with no `--objective` the objective
33
- // is; a receipt that records none is exit 2. A Pull past burn-in that is
34
- // no chain head reads what the install runs, for its group's exploration
35
- // Cells: `modelRoles` (`omp config get modelRoles --json`, or the file
33
+ // is; a receipt that records none is exit 2. Every Pull reads what the
34
+ // install runs, burn-in, chain head and a missing guard included:
35
+ // `modelRoles` (`omp config get modelRoles --json`, or the file
36
36
  // `--model-roles` names, holding that record), omp's model catalog
37
37
  // (`omp models --json`, or the file `--catalog` names) and the
38
38
  // implementer definitions in the agents directory beside the script
39
- // (or `--agents`). A read that fails, or that `omp` does not answer
40
- // within OMP_READ_TIMEOUT_MS, warns and leaves the Pull no Cell to draw;
41
- // a read that leaves a role no level to run at, or finds no implementer
42
- // definition, warns too.
39
+ // (or `--agents`). A Cell whose level its role's model does not run is
40
+ // unrunnable (installOf, unrunnableCells): it is worked out from that read
41
+ // on each Pull and kept in neither the guard nor the table, and `route`
42
+ // routes around it — a row naming one routes the default Cell (REASON
43
+ // `table-cell-unrunnable`), it is drawn in no draw, and the Pull's
44
+ // `UNRUNNABLE` lists every defined Cell the install does not run. omp
45
+ // lowers a level its model does not run silently, so a Pull dispatched at
46
+ // one would run at another level.
47
+ // A read that fails, or that `omp` does not answer within
48
+ // OMP_READ_TIMEOUT_MS, warns and checks no Cell against the install: the
49
+ // Pull's policy and burn-in Cells go out unchecked, an every-5th draw has
50
+ // none to draw, and `UNRUNNABLE` is `-`; a read that leaves a role no
51
+ // level to run at, or finds no implementer definition, warns too.
43
52
  // The script never touches the network: the issue, the sizing verdict and
44
53
  // the guard are files the caller wrote, and the install reads ask the local `omp`.
45
54
 
@@ -61,6 +70,8 @@ import { catalogEntry, implementerCell, readOmpConfigValue, readOmpModelCatalog,
61
70
  const NAME = "ticket-router";
62
71
  const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
63
72
  export const DEFAULT_TABLE = join(SCRIPT_DIR, "router-table.json");
73
+ // The implementer definitions the install ships: the directory an install read names the Cells of unless told another.
74
+ export const AGENTS_DIR = join(SCRIPT_DIR, "..", "agents");
64
75
  // The install's own package.json, whose `version` names the plugin a Pull was routed by.
65
76
  export const INSTALL_PACKAGE = join(SCRIPT_DIR, "..", "package.json");
66
77
 
@@ -72,10 +83,9 @@ const OMP_READ_TIMEOUT_MS = 10_000;
72
83
  // The fit's adoption floor (merged PRs per side) and margin.
73
84
  export const MIN_N = 20;
74
85
  const ADOPT_RATIO = 0.75;
75
- // The starting Cells short of MIN_N merged PRs in a guard's `n`, each with its
76
- // count, in their order: burn-in holds while any is. A Cell the guard has no
77
- // count for has 0.
78
- const shortStartingCells = (n) => STARTING_CELLS.map((c) => [c, n[c] ?? 0]).filter(([, k]) => k < MIN_N);
86
+ // Whether any starting Cell of `cells` (startingCellsOf's: the starting Cells the install runs) is short of MIN_N
87
+ // merged PRs in a guard's `n`: burn-in holds while any is. A Cell the guard has no count for has 0.
88
+ const anyStartingCellShort = (n, cells) => cells.some((c) => (n[c] ?? 0) < MIN_N);
79
89
  const KINDS = new Set(["bug", "enhancement", "documentation"]);
80
90
  const DAY_MS = 86_400_000;
81
91
 
@@ -354,6 +364,11 @@ export function validateTable(t) {
354
364
  }
355
365
  }
356
366
  if (typeof t.burn_in !== "boolean") return bad("`burn_in` is not a boolean");
367
+ // The starting Cells burn-in counted, which a Fit records and the starting table does not.
368
+ const sc = t.starting_cells;
369
+ if (sc !== undefined && (!Array.isArray(sc) || sc.length === 0 || new Set(sc).size !== sc.length || !sc.every((c) => STARTING_CELLS.includes(c)))) {
370
+ return bad("`starting_cells` is not a non-empty list of starting Cells, each once");
371
+ }
357
372
  const cl = t.classifier;
358
373
  if (cl === null || typeof cl !== "object") return bad("`classifier` is not an object");
359
374
  if (cl.b !== null && cl.b !== "haiku" && cl.b !== "jev") return bad("`classifier.b` is not null, \"haiku\" or \"jev\"");
@@ -384,18 +399,55 @@ const LEVELS = Object.freeze(CELL.source.match(/\)-\(([^)]*)\)/)[1].split("|"));
384
399
  const rank = (level) => LEVELS.indexOf(level);
385
400
 
386
401
  /**
387
- * What this install can run, for the exploration draw: `ladders`, per role, the levels its `modelRoles` target runs
388
- * at in omp's model catalog, by effort, lowest first ([] for a role that resolves to no model or to one the catalog
389
- * does not list); `defined`, the Cells an implementer definition exists for. `definitions` is the agents
390
- * directory's file names.
402
+ * What this install can run: `ladders`, per role, the levels its `modelRoles` target runs at in omp's model catalog,
403
+ * by effort, lowest first ([] for a role that resolves to no model or to one the catalog does not list); `models`,
404
+ * per role, the model it resolves to (null for a role that resolves to none); `defined`, the Cells an implementer
405
+ * definition exists for. `definitions` is the agents directory's file names. A Cell whose level its role's ladder
406
+ * lacks is unrunnable here (isRunnable): omp would lower the level silently.
391
407
  */
392
408
  export function installOf({ modelRoles, catalog, definitions }) {
409
+ const models = Object.fromEntries(ROLES_BY_PRICE.map((role) => [role, resolveRole(role, modelRoles)]));
393
410
  const ladders = Object.fromEntries(ROLES_BY_PRICE.map((role) => {
394
- const model = resolveRole(role, modelRoles);
395
- const thinking = model === null ? null : catalogEntry(model, catalog)?.thinking;
411
+ const thinking = models[role] === null ? null : catalogEntry(models[role], catalog)?.thinking;
396
412
  return [role, Array.isArray(thinking) ? LEVELS.filter((l) => thinking.includes(l)) : []];
397
413
  }));
398
- return { ladders, defined: new Set(definitions.map(implementerCell).filter((c) => c !== null)) };
414
+ return { ladders, models, defined: new Set(definitions.map(implementerCell).filter((c) => c !== null)) };
415
+ }
416
+
417
+ /**
418
+ * Whether `install` (installOf's, or null where it was not read) runs `cell`: its level is on its role's ladder. An
419
+ * install that was not read holds nothing unrunnable, so every Cell is runnable there. Throws on a string that is no
420
+ * Cell, which no install can answer for.
421
+ */
422
+ export function isRunnable(install, cell) {
423
+ const parsed = CELL.exec(cell);
424
+ if (parsed === null) throw new TypeError(`isRunnable: ${JSON.stringify(cell)} is not a Cell`);
425
+ return install === null || install.ladders[parsed[1]].includes(parsed[2]);
426
+ }
427
+
428
+ /** Every Cell `install` has an implementer definition for and does not run, sorted; none where it was not read. */
429
+ export const unrunnableCells = (install) => (install === null ? [] : [...install.defined].filter((c) => !isRunnable(install, c)).sort());
430
+
431
+ /**
432
+ * The starting Cells `install` runs, in their order: the Cells burn-in counts and draws. All three where the install
433
+ * was not read, and where it runs none of them, so that an install that cannot run them is no reason to end burn-in.
434
+ */
435
+ export function startingCellsOf(install) {
436
+ const runs = STARTING_CELLS.filter((c) => isRunnable(install, c));
437
+ return runs.length > 0 ? runs : [...STARTING_CELLS];
438
+ }
439
+
440
+ /**
441
+ * The Cell a Pull runs where the router holds no row's Cell back: POLICY_CELL while `install` (installOf's, or null)
442
+ * runs it, else the nearest level of its role that the install runs and has an implementer definition for — downward
443
+ * first, the direction omp lowers to, then upward. POLICY_CELL again when its role has no such level.
444
+ */
445
+ export function defaultCellOf(install) {
446
+ if (isRunnable(install, POLICY_CELL)) return POLICY_CELL;
447
+ const [, role, level] = CELL.exec(POLICY_CELL);
448
+ const usable = install.ladders[role].filter((l) => install.defined.has(`${role}-${l}`));
449
+ const at = usable.findLast((l) => rank(l) < rank(level)) ?? usable.find((l) => rank(l) > rank(level));
450
+ return at === undefined ? POLICY_CELL : `${role}-${at}`;
399
451
  }
400
452
 
401
453
  /**
@@ -418,10 +470,11 @@ export function explorationCells(centre, ladders) {
418
470
  }
419
471
 
420
472
  /**
421
- * The Cells an exploring Pull may draw, before the guard's tripped Cells leave any out: burn-in draws the starting
422
- * Cells, whatever `cells` the table holds; a draw after it the exploration Cells around `centre`, the group's `cost`
423
- * row Cell, that `install` (installOf's) can run — none when the install was not read (null). The fit judges
424
- * `burn_in` over the same starting Cells, so the Cells that end burn-in are the Cells it draws.
473
+ * The Cells an exploring Pull may draw, before the guard's tripped Cells and the install's unrunnable ones leave any
474
+ * out: burn-in draws the starting Cells, whatever `cells` the table holds; a draw after it the exploration Cells
475
+ * around `centre`, the group's `cost` row Cell, that `install` (installOf's) can run — none when the install was not
476
+ * read (null). The fit judges `burn_in` over the starting Cells the install runs, so the Cells that end burn-in are
477
+ * the Cells it draws.
425
478
  */
426
479
  const drawPool = (table, centre, install) => {
427
480
  if (table.burn_in) return STARTING_CELLS;
@@ -431,27 +484,33 @@ const drawPool = (table, centre, install) => {
431
484
 
432
485
  /**
433
486
  * What `route` does with one row under one guard, with no per-Pull input.
434
- * `guard` is readGuard's answer or null. `policy` is the row's Cell, or the
435
- * default cell when there is no guard or the row's Cell is tripped; `reason`
436
- * is `guard-missing`, `table-cell-tripped` or `ok`. `draw` is what an
487
+ * `guard` is readGuard's answer or null. `install` is installOf's answer, or
488
+ * null where it was not read: no Cell is unrunnable there, and an every-5th
489
+ * draw has no Cell. `policy` is the row's Cell, or the default cell
490
+ * (defaultCellOf) when there is no guard, the row's Cell is tripped or the
491
+ * row's Cell is unrunnable; `reason` is `guard-missing`,
492
+ * `table-cell-unrunnable`, `table-cell-tripped` or `ok`, a Cell both
493
+ * unrunnable and tripped being `table-cell-unrunnable`. `draw` is what an
437
494
  * exploring Pull picks from — `by` `burn-in` (every Pull) or `every-5th` —
438
- * over `cells`: drawPool()'s Cells less the tripped, centred on the `cost`
439
- * row's Cell for the stratum as the guard leaves it (the default cell when
440
- * that row's Cell is tripped), whichever objective routes the row. `install`
441
- * is installOf's answer, or null where it was not read: an every-5th draw
442
- * then has no Cell. `draw` is null with no guard and when no Cell is left.
443
- * @returns {{ policy: string, reason: "guard-missing"|"table-cell-tripped"|"ok", draw: null | { by: "burn-in"|"every-5th", cells: string[] } }}
495
+ * over `cells`: drawPool()'s Cells less the tripped and the unrunnable,
496
+ * centred on the `cost` row's Cell for the stratum as the guard and the
497
+ * install leave it (the default cell when that row's Cell is tripped or
498
+ * unrunnable), whichever objective routes the row. `draw` is null with no
499
+ * guard and when no Cell is left.
500
+ * @returns {{ policy: string, reason: "guard-missing"|"table-cell-unrunnable"|"table-cell-tripped"|"ok", draw: null | { by: "burn-in"|"every-5th", cells: string[] } }}
444
501
  */
445
502
  export function rowDispatch({ table, guard, objective, stratum, install = null }) {
446
- if (guard === null) return { policy: POLICY_CELL, reason: "guard-missing", draw: null };
503
+ const fallback = defaultCellOf(install);
504
+ if (guard === null) return { policy: fallback, reason: "guard-missing", draw: null };
447
505
  const tripped = new Set(guard.tripped);
448
- const adjust = (cell) => (tripped.has(cell) ? POLICY_CELL : cell);
506
+ const unrunnable = (cell) => !isRunnable(install, cell);
507
+ const adjust = (cell) => (tripped.has(cell) || unrunnable(cell) ? fallback : cell);
449
508
  const row = rowFor(table.rows[objective], stratum);
450
509
  const by = table.burn_in ? "burn-in" : "every-5th";
451
- const cells = drawPool(table, adjust(rowFor(table.rows.cost, stratum)), install).filter((c) => !tripped.has(c));
510
+ const cells = drawPool(table, adjust(rowFor(table.rows.cost, stratum)), install).filter((c) => !tripped.has(c) && !unrunnable(c));
452
511
  return {
453
512
  policy: adjust(row),
454
- reason: tripped.has(row) ? "table-cell-tripped" : "ok",
513
+ reason: unrunnable(row) ? "table-cell-unrunnable" : tripped.has(row) ? "table-cell-tripped" : "ok",
455
514
  draw: cells.length > 0 ? { by, cells } : null,
456
515
  };
457
516
  }
@@ -561,8 +620,9 @@ export function assignmentProb({ burnIn, chainHead, cell, policy, cells }) {
561
620
  * set's row for it routes the Pull. The exploration draw ignores the objective:
562
621
  * it is centred on the cell the `cost` set routes the group to, whichever set
563
622
  * routes the Pull, so a Pull draws the same cell under both. `install` is
564
- * installOf's answer, or null where it was not read, which leaves an every-5th
565
- * Pull nothing to draw. A live B Pull
623
+ * installOf's answer, or null where it was not read, which checks no Cell
624
+ * against the install and leaves an every-5th Pull nothing to draw. The
625
+ * Routing's `UNRUNNABLE` is unrunnableCells(install). A live B Pull
566
626
  * records its sizing verdict and routes as an A Pull does: a label names no
567
627
  * group of the tree. `fallback` is readFitBeside's REASON when `table` is the
568
628
  * starting table standing in for a Fit, else null: it is the first thing that
@@ -636,7 +696,7 @@ export function route({
636
696
  policy, cell, draw, by, stratum,
637
697
  brief: metrics === null ? null : Number(metrics.brief_chars), criteria: metrics === null ? null : Number(metrics.criteria),
638
698
  parent: m.parent === "" ? null : Number(m.parent),
639
- sized: sizingPre === "" ? null : sizingPre, objective, tripped: guard?.tripped ?? [], reason,
699
+ sized: sizingPre === "" ? null : sizingPre, objective, tripped: guard?.tripped ?? [], unrunnable: unrunnableCells(install), reason,
640
700
  });
641
701
  return { line, row };
642
702
  }
@@ -883,17 +943,25 @@ function judgeSpeedRow(pulls, cells, tripped, costCell) {
883
943
  * row of its own (the root always has one), from that row's cell, the base when
884
944
  * the record has no cell; a node with none holds its parent's `speed` row and
885
945
  * an `unjudged` record. `cells` is the prior's: the fit adds no Cell. `burn_in`
886
- * holds until every starting Cell has MIN_N merged PRs on its newest generation
887
- * (`guard.n`, which starts again at 0 when a role's model changes): no other
888
- * Cell the table holds ends it or holds it, whatever its merged PRs.
946
+ * holds until every Cell of `startingCells` has MIN_N merged PRs on its newest
947
+ * generation (`guard.n`, which starts again at 0 when a role's model changes):
948
+ * no other Cell the table holds ends it or holds it, whatever its merged PRs.
949
+ * `startingCells` are the starting Cells the install runs (startingCellsOf) —
950
+ * all three when absent — and the table records them as `starting_cells`, so
951
+ * the records, the guard, the prior and that set fit the same table again.
952
+ * Throws on a `startingCells` that is empty, which would end burn-in on no
953
+ * count at all, or that names a Cell that is no starting Cell.
889
954
  */
890
- export function fitTable({ prior, features, members, verdicts, guard }) {
955
+ export function fitTable({ prior, features, members, verdicts, guard, startingCells = STARTING_CELLS }) {
891
956
  const window = guard.window_start ?? prior.window_start ?? null;
892
- return tableOver({ prior, ...fitPulls({ features, members, verdicts, window }), guard, window });
957
+ return tableOver({ prior, ...fitPulls({ features, members, verdicts, window }), guard, window, startingCells });
893
958
  }
894
959
 
895
960
  // The table over the tree `prior.splits` holds, from the fit's Pulls (fitPulls') booked to its groups.
896
- function tableOver({ prior, units: unbooked, order, guard, window }) {
961
+ function tableOver({ prior, units: unbooked, order, guard, window, startingCells }) {
962
+ if (startingCells.length === 0 || !startingCells.every((c) => STARTING_CELLS.includes(c))) {
963
+ throw new Error(`startingCells is not a non-empty list of starting Cells: ${JSON.stringify(startingCells)}`);
964
+ }
897
965
  const nodes = treeNodes(prior.splits);
898
966
  const units = book(unbooked, prior);
899
967
  const { estimates, pulls } = estimate(units, order, nodes);
@@ -918,7 +986,8 @@ function tableOver({ prior, units: unbooked, order, guard, window }) {
918
986
  window_start: window,
919
987
  n_rows: units.length,
920
988
  cells: prior.cells,
921
- burn_in: shortStartingCells(guard.n).length > 0,
989
+ burn_in: anyStartingCellShort(guard.n, startingCells),
990
+ starting_cells: [...startingCells],
922
991
  splits: prior.splits,
923
992
  rows,
924
993
  classifier: prior.classifier,
@@ -1026,14 +1095,41 @@ function growTree({ prior, units, order, tripped, previous }) {
1026
1095
  * of the last Fit that computed, or null where there is none; the rest is fitTable's. A split stands in the table
1027
1096
  * once it has passed the gate at two consecutive Fits on the same input or inputs, over other records each time — a
1028
1097
  * Fit over the records the last one searched is no look, and keeps what that one found — and is gone from it at the
1029
- * first Fit it fails; that Fit's `gate` is the whole of what the next one reads of this.
1098
+ * first Fit it fails; that Fit's `gate` is the whole of what the next one reads of this. `startingCells` is
1099
+ * fitTable's.
1030
1100
  * @returns {{ table: object, gate: { records: string, scored: number, left_out: number, best: object|null, passed: string[], stands: string[] } }}
1031
1101
  */
1032
- export function fitTree({ prior, features, members, verdicts, guard, previous = null }) {
1102
+ export function fitTree({ prior, features, members, verdicts, guard, previous = null, startingCells = STARTING_CELLS }) {
1033
1103
  const window = guard.window_start ?? prior.window_start ?? null;
1034
1104
  const fitted = fitPulls({ features, members, verdicts, window });
1035
1105
  const { gate, splits } = growTree({ prior, ...fitted, tripped: new Set(guard.tripped), previous });
1036
- return { table: tableOver({ prior: { ...prior, splits }, ...fitted, guard, window }), gate };
1106
+ return { table: tableOver({ prior: { ...prior, splits }, ...fitted, guard, window, startingCells }), gate };
1107
+ }
1108
+
1109
+ /**
1110
+ * What the install runs, off `modelRoles` (`omp config get modelRoles --json`, or the JSON file `modelRoles` names),
1111
+ * omp's model catalog (`omp models --json`, or the JSON file `catalog` names) and the implementer definitions in the
1112
+ * `agents` directory: `{ install, why: null }` with installOf's answer, or `{ install: null, why }` where a read fails
1113
+ * or does not answer in OMP_READ_TIMEOUT_MS, `modelRoles` is no record or the catalog has no `models` list. Never
1114
+ * throws.
1115
+ */
1116
+ export function readInstall({ modelRoles: modelRolesPath = null, catalog: catalogPath = null, agents = AGENTS_DIR } = {}) {
1117
+ const kind = (v) => (v === undefined ? "absent" : v === null ? "null" : Array.isArray(v) ? "an array" : `a ${typeof v}`);
1118
+ try {
1119
+ const modelRoles = modelRolesPath === null
1120
+ ? readOmpConfigValue("modelRoles", { timeout: OMP_READ_TIMEOUT_MS })
1121
+ : JSON.parse(readFileSync(modelRolesPath, "utf8"));
1122
+ const catalog = catalogPath === null
1123
+ ? readOmpModelCatalog({ timeout: OMP_READ_TIMEOUT_MS })
1124
+ : JSON.parse(readFileSync(catalogPath, "utf8"));
1125
+ if (typeof modelRoles !== "object" || modelRoles === null || Array.isArray(modelRoles)) {
1126
+ throw new Error(`modelRoles is ${kind(modelRoles)}, not a record of role to model`);
1127
+ }
1128
+ if (!Array.isArray(catalog?.models)) throw new Error(`omp's model catalog has no models list (models: ${kind(catalog?.models)})`);
1129
+ return { install: installOf({ modelRoles, catalog, definitions: readdirSync(agents) }), why: null };
1130
+ } catch (e) {
1131
+ return { install: null, why: e.message };
1132
+ }
1037
1133
  }
1038
1134
 
1039
1135
  // ---------------------------------------------------------------------------
@@ -1096,36 +1192,24 @@ function main() {
1096
1192
  if (version === null) process.stderr.write(`${NAME}: WARNING ${INSTALL_PACKAGE} names no readable version — plugin_version is blank\n`);
1097
1193
  const guard = readGuard(readJson(guardPath));
1098
1194
  const chainHead = F.has("chain-head");
1099
- // Only a Pull past burn-in that may explore reads what the install runs: its draw, or the share it ran at, needs
1100
- // the group's exploration Cells. A read that fails or does not answer in OMP_READ_TIMEOUT_MS, a `modelRoles` that
1101
- // is no record and a catalog with no `models` list leave the Pull no Cell to draw, and warn, never the exit; so
1102
- // does a read that holds nothing to draw: a role that runs at no level, or no implementer definition.
1103
- let install = null;
1104
- if (guard !== null && !table.burn_in && !chainHead) {
1105
- const warn = (what) => process.stderr.write(`${NAME}: WARNING ${what}\n`);
1106
- const agents = F.arg("agents") ?? join(SCRIPT_DIR, "..", "agents");
1107
- const kind = (v) => (v === undefined ? "absent" : v === null ? "null" : Array.isArray(v) ? "an array" : `a ${typeof v}`);
1108
- try {
1109
- const modelRoles = F.arg("model-roles") === null
1110
- ? readOmpConfigValue("modelRoles", { timeout: OMP_READ_TIMEOUT_MS })
1111
- : JSON.parse(readFileSync(F.arg("model-roles"), "utf8"));
1112
- const catalog = F.arg("catalog") === null
1113
- ? readOmpModelCatalog({ timeout: OMP_READ_TIMEOUT_MS })
1114
- : JSON.parse(readFileSync(F.arg("catalog"), "utf8"));
1115
- if (typeof modelRoles !== "object" || modelRoles === null || Array.isArray(modelRoles)) {
1116
- throw new Error(`modelRoles is ${kind(modelRoles)}, not a record of role to model`);
1117
- }
1118
- if (!Array.isArray(catalog?.models)) throw new Error(`omp's model catalog has no models list (models: ${kind(catalog?.models)})`);
1119
- install = installOf({ modelRoles, catalog, definitions: readdirSync(agents) });
1120
- } catch (e) {
1121
- warn(`cannot read what this install runs: ${e.message} — no exploration Cell is drawn`);
1195
+ // Every Pull reads what the install runs: which Cells it runs gates the row's Cell and each draw, and the Cells it
1196
+ // draws after burn-in are the group's exploration Cells. A read that fails or does not answer in OMP_READ_TIMEOUT_MS,
1197
+ // a `modelRoles` that is no record and a catalog with no `models` list leave the Pull's Cells unchecked and its
1198
+ // every-5th draw empty, and warn, never the exit; so does a read that holds nothing to run: a role that runs at no
1199
+ // level, no implementer definition, or no level of the default Cell's role that is both run and defined.
1200
+ const warn = (what) => process.stderr.write(`${NAME}: WARNING ${what}\n`);
1201
+ const agents = F.arg("agents") ?? AGENTS_DIR;
1202
+ const { install, why } = readInstall({ modelRoles: F.arg("model-roles"), catalog: F.arg("catalog"), agents });
1203
+ if (install === null) {
1204
+ warn(`cannot read what this install runs: ${why} — no Cell is checked against it and no exploration Cell is drawn`);
1205
+ } else {
1206
+ const unrun = ROLES_BY_PRICE.filter((role) => install.ladders[role].length === 0);
1207
+ if (unrun.length > 0) {
1208
+ warn(`this install runs ${unrun.join(", ")} at no level (modelRoles names no model for it, or one omp's catalog lists at none) — no Cell of ${unrun.length === 1 ? "that role" : "those roles"} is routed or drawn`);
1122
1209
  }
1123
- if (install !== null) {
1124
- const unrun = ROLES_BY_PRICE.filter((role) => install.ladders[role].length === 0);
1125
- if (unrun.length > 0) {
1126
- warn(`this install runs ${unrun.join(", ")} at no level (modelRoles names no model for it, or one omp's catalog lists at none) — no exploration Cell of ${unrun.length === 1 ? "that role" : "those roles"} is drawn`);
1127
- }
1128
- if (install.defined.size === 0) warn(`${agents} holds no implementer definition — no exploration Cell is drawn`);
1210
+ if (install.defined.size === 0) warn(`${agents} holds no implementer definition — no exploration Cell is drawn`);
1211
+ if (!isRunnable(install, POLICY_CELL) && defaultCellOf(install) === POLICY_CELL) {
1212
+ warn(`no level of ${POLICY_CELL}'s role runs here with an implementer definition — ${POLICY_CELL} stays the default Cell`);
1129
1213
  }
1130
1214
  }
1131
1215
  const { line, row } = route({
@@ -25,15 +25,15 @@
25
25
  // silently (`claude-haiku-4-5` has no `max`, so `@smol:max` would run
26
26
  // at something else), tier-check would then read a level the
27
27
  // definition never declared, and every row the definition ran would
28
- // be inadmissible. The one exception is an implementer definition
29
- // whose cell the router never selects (not in the router table's
30
- // `cells`, in no row of either objective's `rows` set, and not the
31
- // policy cell): a cell can be defined before the router may pick it,
32
- // so its mismatch is a notice. The router table is `router-table.json`
33
- // beside this script, or the file `--table <path>` names; one that
34
- // cannot be read, or that lacks a `cells` array or a `rows` object of
35
- // row sets of cell names, refuses. A target the catalog does not list cannot be checked, so it
36
- // fails too;
28
+ // be inadmissible. An implementer definition is the exception: the
29
+ // router works out which Cells its install does not run and routes
30
+ // around them, so one whose level its role's model does not run is
31
+ // a notice (`cell <cell> unrunnable: modelRoles.<role> → <model> runs
32
+ // <levels|none>`), never a violation — unless `slow` runs at no level
33
+ // at all, which leaves the default Cell nowhere to run. That holds
34
+ // whatever other definitions the directory has. Every other
35
+ // definition keeps the violation. A target the catalog does not list
36
+ // cannot be checked, so it fails too;
37
37
  // (e) `modelRoles.slow`/`modelRoles.task` resolving to the same model is
38
38
  // flagged as a notice — legal, but every `slow-*` cell then measures
39
39
  // the same model as its `task-*` twin;
@@ -55,7 +55,7 @@ import { join, dirname } from "node:path";
55
55
  import { fileURLToPath } from "node:url";
56
56
  import { isCLI } from "./is-cli.mjs";
57
57
  import { makeDie, defineFlags } from "./arg.mjs";
58
- import { CELL_DEF, POLICY_CELL } from "./ledger-grammar.mjs";
58
+ import { CELL_DEF } from "./ledger-grammar.mjs";
59
59
 
60
60
  const NAME = "tier-roles";
61
61
  const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
@@ -138,23 +138,6 @@ export function implementerCell(file) {
138
138
  return CELL_DEF.test(name) ? name.slice("fleet-implementer-".length) : null;
139
139
  }
140
140
 
141
- // The cells the router can select from a parsed router table: the pool it
142
- // explores (`cells`), the cell each row of each objective's set names (`rows`
143
- // values) and the policy cell, which every Pull falls back to whatever the
144
- // table says. An Error saying why when the table lacks a `cells` array of
145
- // names or a `rows` object of row sets of names — a table that cannot be read
146
- // must refuse, never quietly make every cell non-routable.
147
- export function routableCells(table) {
148
- const bad = (why) => new Error(`router table: ${why}`);
149
- if (!isJsonObject(table)) return bad("not a JSON object");
150
- if (!Array.isArray(table.cells) || !table.cells.every((c) => typeof c === "string")) return bad("`cells` is not an array of cell names");
151
- const sets = isJsonObject(table.rows) ? Object.values(table.rows) : null;
152
- if (sets === null || !sets.every((set) => isJsonObject(set) && Object.values(set).every((c) => typeof c === "string"))) {
153
- return bad("`rows` is not an object of row sets of cell names");
154
- }
155
- return new Set([POLICY_CELL, ...table.cells, ...sets.flatMap((set) => Object.values(set))]);
156
- }
157
-
158
141
  // Tolerates a role value written without its provider prefix — omp's
159
142
  // `resolvedModelIdentity` is always provider-prefixed, a plain `modelRoles`
160
143
  // entry may not be.
@@ -246,12 +229,10 @@ function kindOf(v) {
246
229
  // The operator's install (`modelRoles`, omp's model `catalog`, and any
247
230
  // leftover `task.agentModelOverrides`) against what the fleet's own
248
231
  // definitions need. `violations` stop a run; `notices` never do —
249
- // they flag a hazard (two roles' cells measuring one model) that is legal
250
- // configuration, just probably not what the operator meant. `routable` is
251
- // the set `routableCells` returns: the router never selects an implementer
252
- // definition outside it, so an unsupported level there is a notice; `null`
253
- // is no table at all, and then every definition is held to the level check.
254
- export function checkRoutes({ agentsDir, agentsSource = `--agents ${agentsDir}`, modelRoles, overrides, catalog, routable = null }) {
232
+ // they flag a hazard (two roles' cells measuring one model, an implementer
233
+ // Cell its role's model does not run) that is legal configuration, just
234
+ // probably not what the operator meant.
235
+ export function checkRoutes({ agentsDir, agentsSource = `--agents ${agentsDir}`, modelRoles, overrides, catalog }) {
255
236
  const violations = [];
256
237
  const notices = [];
257
238
  const usedBy = {}; // role -> [{ file, level }, ...]
@@ -315,14 +296,16 @@ export function checkRoutes({ agentsDir, agentsSource = `--agents ${agentsDir}`,
315
296
  continue;
316
297
  }
317
298
  const efforts = entry.thinking ?? [];
299
+ const runs = efforts.join(", ") || "none";
318
300
  for (const { file, level } of usedBy[role]) {
319
301
  if (efforts.includes(level)) continue;
320
- const mismatch = `${file}: level ${level} is not one modelRoles.${role}'s target ${model} runs at (thinking: ${efforts.join(", ") || "none"})`;
321
302
  const cell = implementerCell(file);
322
- if (routable !== null && cell !== null && !routable.has(cell)) {
323
- notices.push(`${mismatch} — cell ${cell} is not one the router selects; omp would clamp this level silently once it does`);
303
+ // An implementer Cell its role's model does not run is routed around, never dispatched: a notice, unless `slow`
304
+ // runs at no level at all, which leaves the default Cell nowhere to run.
305
+ if (cell !== null && !(role === "slow" && efforts.length === 0)) {
306
+ notices.push(`cell ${cell} unrunnable: modelRoles.${role} → ${model} runs ${runs}`);
324
307
  } else {
325
- violations.push(`${mismatch} — omp would clamp it silently`);
308
+ violations.push(`${file}: level ${level} is not one modelRoles.${role}'s target ${model} runs at (thinking: ${runs}) — omp would clamp it silently`);
326
309
  }
327
310
  }
328
311
  }
@@ -385,7 +368,6 @@ const { arg, numArg, has, sweep, stray } = defineFlags(die, {
385
368
  overrides: "value",
386
369
  "model-roles": "value",
387
370
  catalog: "value",
388
- table: "value",
389
371
  "max-concurrency": "value",
390
372
  },
391
373
  });
@@ -423,7 +405,7 @@ function main() {
423
405
  stray();
424
406
 
425
407
  const check = has("check");
426
- if (!check) die("--check --in-flight <B> is required (usage: tier-roles.mjs --check --in-flight <B> [--agents <dir>] [--model-roles <path>] [--overrides <path>] [--catalog <path>] [--table <path>] [--max-concurrency <path>])");
408
+ if (!check) die("--check --in-flight <B> is required (usage: tier-roles.mjs --check --in-flight <B> [--agents <dir>] [--model-roles <path>] [--overrides <path>] [--catalog <path>] [--max-concurrency <path>])");
427
409
 
428
410
  // numArg() is the fleet's digits rule (arg.mjs): `0x5`, `1e1`, ` 5`, `5.0`
429
411
  // and `+5` are refused where `Number()` would have read a bound the caller
@@ -438,23 +420,12 @@ function main() {
438
420
  const overrides = loadJsonObject(arg("overrides"), ...config("task.agentModelOverrides"), "overrides");
439
421
  const modelRoles = loadJsonObject(arg("model-roles"), ...config("modelRoles"), "model-roles");
440
422
  const catalog = loadJsonObject(arg("catalog"), readOmpModelCatalog, "omp models --json", "catalog");
441
- const tablePath = arg("table") ?? join(SCRIPT_DIR, "router-table.json");
442
- let table;
443
- try {
444
- table = JSON.parse(readFileSync(tablePath, "utf8"));
445
- } catch (e) {
446
- die(`cannot read the router table ${tablePath}: ${e.message}`);
447
- }
448
- const routable = routableCells(table);
449
- if (routable instanceof Error) die(`${tablePath}: ${routable.message}`);
450
-
451
423
  const { violations, notices } = checkRoutes({
452
424
  agentsDir,
453
425
  agentsSource: agentsFlag === null ? `the default agents directory ${agentsDir}` : undefined,
454
426
  modelRoles,
455
427
  overrides,
456
428
  catalog,
457
- routable,
458
429
  });
459
430
  const notice = semaphoreNotice({ inFlight: inFlightBound, read: readMaxConcurrency(arg("max-concurrency")) });
460
431
  if (notice !== null) notices.push(notice);
@@ -250,7 +250,7 @@ terminating in exactly one dispatch or an empty shortlist:
250
250
  7. **Route, row, then dispatch** — `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run ticket-router.mjs route
251
251
  --session <session> --ticket <N> --arm <A|B> --impl-row <k>[ --chain-head] --issue
252
252
  <scratch>/impl-<N>/issue.json --guard .fleet/cost-guard.json` prints the Pull's
253
- Routing, `POLICY=… CELL=… DRAW=… BY=… STRATUM=… BRIEF=… CRITERIA=… PARENT=… SIZED=… OBJECTIVE=… TRIPPED=… REASON=…`
253
+ Routing, `POLICY=… CELL=… DRAW=… BY=… STRATUM=… BRIEF=… CRITERIA=… PARENT=… SIZED=… OBJECTIVE=… TRIPPED=… UNRUNNABLE=… REASON=…`
254
254
  (the router's arguments paragraph below the list says what each argument is);
255
255
  then `ledger.mjs row <N> "<member>[ · tier=<CELL>]" --routing "<that line>"`,
256
256
  `<member>` the name the Pull printed, `tier=<CELL>` exactly when `DRAW` is not `-`, which writes the row and files