@feigi/fleet-ctl 3.158.39 → 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.
@@ -2,7 +2,7 @@
2
2
  // Phase 0 as one command: the run's start sequence, in order, with a receipt.
3
3
  //
4
4
  // phase0.mjs [--session <dir>] [--in-flight n] [--objective cost|speed]
5
- // [--spend-dir <dir>]
5
+ // [--merge | --no-merge] [--spend-dir <dir>]
6
6
  // [--workflow <name> | --declare-no-ci]
7
7
  //
8
8
  // The session directory is `--session`, else `PI_ARTIFACTS_DIR`, which omp
@@ -125,7 +125,7 @@
125
125
  // THE RECEIPT is `.fleet/phase0.json` (resolved through fleet-dir.mjs, so a
126
126
  // worktree and the main checkout name one file):
127
127
  //
128
- // { run, session, scratch, inFlight, objective, pluginVersion,
128
+ // { run, session, scratch, inFlight, objective, merge, pluginVersion,
129
129
  // steps: { <name>: { status, at, output } } }
130
130
  //
131
131
  // `status` is ok, pending, failed, drift or unanswered; `at` an ISO time;
@@ -142,6 +142,14 @@
142
142
  // default when it records none — and a resume whose `--objective` names the
143
143
  // other one exits 2 naming both, leaving the receipt as it was. A resumed
144
144
  // receipt recording a value that is not an Objective exits 3 naming it.
145
+ // `merge` is whether the run's merge bot merges: `false` under `--no-merge`,
146
+ // `true` under `--merge` or with neither (MERGE_DEFAULT in
147
+ // phase0-receipt.mjs). `--merge` and `--no-merge` together exit 2. Like the
148
+ // Objective it is fixed for the run: a resumed receipt keeps the one it
149
+ // records — `true` when it records none — and a resume that names the other
150
+ // one exits 2 naming both, leaving the receipt as it was. A resumed receipt
151
+ // recording a value that is not a boolean exits 3 naming it. The tick reads
152
+ // it from this receipt and from no flag of its own.
145
153
  // `pluginVersion` is the version the pin recorded, null when it recorded
146
154
  // none; a resumed receipt keeps it.
147
155
  //
@@ -207,7 +215,7 @@ import { isCLI } from "./is-cli.mjs";
207
215
  import { GH_LOGIN_ARGS, isOwnedPr, loginOf, ownershipReadable } from "./owned-pr.mjs";
208
216
  import { OBJECTIVES, RECEIPT, RECEIPT_HELD, archiveStamp, receiptArchiveName, rowNums } from "./ledger-grammar.mjs";
209
217
  import { ancestry, controllerOf, processSource, ProcUnreadable } from "./proc.mjs";
210
- import { IN_FLIGHT_DEFAULT, OBJECTIVE_DEFAULT } from "./phase0-receipt.mjs";
218
+ import { IN_FLIGHT_DEFAULT, MERGE_DEFAULT, OBJECTIVE_DEFAULT } from "./phase0-receipt.mjs";
211
219
  import { readRecipe } from "./recipe-read.mjs";
212
220
  import { gather, recordChanges, refusedLine, unclosedRecords } from "./run-records.mjs";
213
221
 
@@ -707,7 +715,7 @@ function main() {
707
715
  const die = makeDie(NAME);
708
716
  const F = defineFlags(die, {
709
717
  flags: {
710
- session: "value", "in-flight": "value", objective: "value",
718
+ session: "value", "in-flight": "value", objective: "value", merge: "bool", "no-merge": "bool",
711
719
  "spend-dir": "value", workflow: "value", "declare-no-ci": "bool",
712
720
  },
713
721
  });
@@ -747,6 +755,8 @@ function main() {
747
755
  const inFlight = positive("in-flight") ?? IN_FLIGHT_DEFAULT;
748
756
  const named = F.arg("objective");
749
757
  if (named !== null && !OBJECTIVES.includes(named)) die(`--objective needs ${OBJECTIVES.join(" or ")}, got ${named}`);
758
+ if (F.has("merge") && F.has("no-merge")) die("--merge and --no-merge are alternatives, not a pair");
759
+ const mergeNamed = F.has("no-merge") ? false : F.has("merge") ? true : null;
750
760
  if (F.has("declare-no-ci") && !absent("workflow")) die("--workflow and --declare-no-ci are alternatives, not a pair");
751
761
  const ci = F.has("declare-no-ci") ? "CI: declared absent (--declare-no-ci)" : absent("workflow") ? null : `CI: workflow ${F.arg("workflow")} (--workflow)`;
752
762
  const spendDir = absent("spend-dir") ? null : resolve(F.arg("spend-dir"));
@@ -812,6 +822,20 @@ function main() {
812
822
  die(`--objective ${named}: this run's receipt ${receiptPath} records the objective ${kept}, fixed for the run — run phase 0 again without --objective, or with --objective ${kept}`);
813
823
  }
814
824
  const objective = kept ?? named ?? OBJECTIVE_DEFAULT;
825
+ // The merge switch is fixed for the run the same way: a resumed receipt's
826
+ // stands, and one that records none resumes as merge. One recording
827
+ // anything but a boolean is refused, never read as merge.
828
+ if (resumed && previous.merge !== undefined && typeof previous.merge !== "boolean") {
829
+ process.stderr.write(`${NAME}: this run's receipt ${receiptPath} records merge ${JSON.stringify(previous.merge)}, which is not true or false — set it to the value this run began with and re-run\n`);
830
+ process.exitCode = 3;
831
+ return;
832
+ }
833
+ const keptMerge = resumed ? previous.merge ?? MERGE_DEFAULT : null;
834
+ if (keptMerge !== null && mergeNamed !== null && mergeNamed !== keptMerge) {
835
+ const flag = (m) => (m ? "--merge" : "--no-merge");
836
+ die(`${flag(mergeNamed)}: this run's receipt ${receiptPath} records ${keptMerge ? "merge" : "no-merge"}, fixed for the run — run phase 0 again without ${flag(mergeNamed)}, or with ${flag(keptMerge)}`);
837
+ }
838
+ const merge = keptMerge ?? mergeNamed ?? MERGE_DEFAULT;
815
839
  if (rotated && !resumed) {
816
840
  if (existsSync(held)) {
817
841
  process.stderr.write(`${NAME}: cannot hold the previous run's receipt for the rotation: ${held} already holds another\n`);
@@ -822,7 +846,7 @@ function main() {
822
846
  }
823
847
 
824
848
  const pluginVersion = resumed && typeof previous.pluginVersion === "string" ? previous.pluginVersion : null;
825
- const receipt = { run: resumed ? previous.run : null, session, scratch, inFlight, objective, pluginVersion, steps: {} };
849
+ const receipt = { run: resumed ? previous.run : null, session, scratch, inFlight, objective, merge, pluginVersion, steps: {} };
826
850
  for (const name of STEP_NAMES) {
827
851
  // `alarm` checks the omp running this invocation, so its `ok` is never carried.
828
852
  const was = resumed && name !== "alarm" ? previous.steps[name] : undefined;
@@ -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);