@feigi/fleet-ctl 3.147.5 → 3.148.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feigi/fleet-ctl",
3
- "version": "3.147.5",
3
+ "version": "3.148.1",
4
4
  "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -532,14 +532,19 @@ function routesHeading(table, guard, source) {
532
532
  }
533
533
 
534
534
  // One row's dispatch, in the words a heading or a row carries: what `route` does
535
- // with a Pull on it under the guard, from rowDispatch.
535
+ // with a Pull on it under the guard, from rowDispatch. Past burn-in the draw is
536
+ // over the group's exploration Cells that this install runs and the guard has
537
+ // not tripped. The cockpit does not read the install, so it names them without
538
+ // counting them, and without claiming one is left: with none, `route` draws
539
+ // nothing.
536
540
  function dispatchWords(table, rd, row) {
537
541
  const tripped = rd.reason === "table-cell-tripped" ? `the row's ${row} tripped` : null;
538
542
  if (rd.reason === "guard-missing") return `${POLICY_CELL} only`;
539
543
  if (rd.draw?.by === "burn-in") {
540
544
  return `drawn over ${plural(rd.draw.cells.length, "Cell")}: ${rd.draw.cells.join(", ")}${tripped ? `; ${tripped}, so its policy Cell is ${POLICY_CELL}` : ""}`;
541
545
  }
542
- const fifth = rd.draw === null ? "no draw: no other Cell is left" : "every 5th Pull drawn over the rest";
546
+ const fifth = table.burn_in ? "no draw: no other Cell is left"
547
+ : "every 5th Pull drawn over the group's exploration Cells, if the install runs one the guard has not tripped";
543
548
  return `${tripped ? `${POLICY_CELL}, ${tripped}` : "the row's Cell"}; ${fifth}`;
544
549
  }
545
550
 
@@ -19,7 +19,7 @@
19
19
  // rows the next drain finds already there, so a second run changes nothing.
20
20
  // A corpus written before a column the pending file carries — one the row
21
21
  // grammar names, `objective`, `parent`, `named_paths`, `named_lines`, `dirs`,
22
- // `title` or `plugin_version` — gains that column, blank on every row it
22
+ // `title`, `plugin_version` or `assignment_prob` — gains that column, blank on every row it
23
23
  // already holds. A pending file begun before one of them drains its rows
24
24
  // blank in it.
25
25
  // A pending file that is empty, or blank lines only, is removed with its own
@@ -98,11 +98,15 @@ import { DATE, isDerivedNote, rulingFor, rulingsByTicket } from "./tier-outcomes
98
98
  // or lies outside the checkout; `dirs` the number of distinct directories they
99
99
  // span. Those three are blank when the brief names no path. `title` is the
100
100
  // issue's title, and `plugin_version` the install's `package.json` `version`.
101
+ // `assignment_prob` is the probability the router assigned the Pull its
102
+ // `chosen_cell` with, written as a fraction that reads back exactly: `1`, or
103
+ // `<n>/<d>` in lowest terms (ticket-router.mjs's assignmentProb). Blank is
104
+ // unknown, a row written before the column: never a probability of 1 or 0.
101
105
  export const FEATURE_COLUMNS = Object.freeze([
102
106
  "run_date", "session", "agent", "ticket", "policy_cell", "chosen_cell", "exploration_draw",
103
107
  "sizing_src", "sizing_pre", "router_usd", "brief_chars", "criteria", "comments", "age_days",
104
108
  "paths", "test_paths", "xrefs", "kind", "objective", "parent",
105
- "named_paths", "named_lines", "dirs", "title", "plugin_version",
109
+ "named_paths", "named_lines", "dirs", "title", "plugin_version", "assignment_prob",
106
110
  ]);
107
111
  export const OPTIONAL_COLUMNS = new Set(FEATURE_COLUMNS.slice(FEATURE_COLUMNS.indexOf("objective")));
108
112
 
@@ -8,6 +8,7 @@
8
8
  // --impl-row <k> --issue <issue.json> --guard <cost-guard.json>
9
9
  // [--sizing <sizing.json>] [--table <router-table.json>]
10
10
  // [--chain-head] [--pending <tsv>]
11
+ // [--model-roles <json>] [--catalog <json>] [--agents <dir>]
11
12
  // Prints one line, the Pull's Routing (ledger-grammar.mjs owns its
12
13
  // grammar): `POLICY=<cell> CELL=<cell> DRAW=<k/K|-> BY=<burn-in|every-5th|->
13
14
  // STRATUM=<rule path> BRIEF=<chars|-> CRITERIA=<n|-> PARENT=<N|->
@@ -29,7 +30,16 @@
29
30
  // an unreadable/invalid table: the caller does not dispatch then. With no
30
31
  // `--session`, the session is the one the phase-0 receipt
31
32
  // `.fleet/phase0.json` records, and with no `--objective` the objective
32
- // is; a receipt that records none is exit 2.
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
36
+ // `--model-roles` names, holding that record), omp's model catalog
37
+ // (`omp models --json`, or the file `--catalog` names) and the
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.
33
43
  // fit --table <json> --features <tsv> --members <tsv> --verdicts <tsv>
34
44
  // --guard <cost-guard.json> --commit <rev> [--due]
35
45
  // Re-fits the table from the three TSVs as committed at `--commit` (read
@@ -49,17 +59,17 @@
49
59
  // not hold exits 2 naming the `git fetch` that brings it.
50
60
  //
51
61
  // The script never touches the network: the issue, the sizing verdict and
52
- // the guard are files the caller wrote, and a fitted commit is fetched by the
53
- // caller.
62
+ // the guard are files the caller wrote, a fitted commit is fetched by the
63
+ // caller, and the install reads ask the local `omp`.
54
64
 
55
- import { readFileSync, writeFileSync, renameSync, appendFileSync, mkdirSync, statSync, realpathSync } from "node:fs";
65
+ import { readFileSync, readdirSync, writeFileSync, renameSync, appendFileSync, mkdirSync, statSync, realpathSync } from "node:fs";
56
66
  import { spawnSync } from "node:child_process";
57
67
  import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
58
68
  import { fileURLToPath } from "node:url";
59
69
  import { isDeepStrictEqual } from "node:util";
60
70
  import { isCLI } from "./is-cli.mjs";
61
71
  import { gitEnv } from "./git-env.mjs";
62
- import { makeDie, defineFlags } from "./arg.mjs";
72
+ import { makeDie, defineFlags, isDigits } from "./arg.mjs";
63
73
  import { CELL, OBJECTIVES, POLICY_CELL, STARTING_CELLS, drawCell, formatRouting, isRulePath, parseMember } from "./ledger-grammar.mjs";
64
74
  import { objectiveFromReceipt, sessionFromReceipt } from "./phase0-receipt.mjs";
65
75
  import { parseTsv as parseMemberTsv } from "./member-outcomes.mjs";
@@ -68,6 +78,7 @@ import {
68
78
  } from "./pull-attribution.mjs";
69
79
  import { RulingError, parseTierOutcomes } from "./tier-outcomes.mjs";
70
80
  import { LINE_REF, briefPaths, briefText } from "./ticket-text.mjs";
81
+ import { catalogEntry, implementerCell, readOmpConfigValue, readOmpModelCatalog, resolveRole } from "./tier-roles.mjs";
71
82
 
72
83
  const NAME = "ticket-router";
73
84
  const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
@@ -77,6 +88,9 @@ export const INSTALL_PACKAGE = join(SCRIPT_DIR, "..", "package.json");
77
88
 
78
89
  // Exploration cadence after burn-in: the Pull that creates `impl-` row 5k.
79
90
  const EXPLORE_EVERY = 5;
91
+ // An `omp` install read that has not answered in this many milliseconds is killed and warns as a failed read: the
92
+ // Pull runs `route` with no timeout of its own, so a hung `omp` would otherwise hang the Pull.
93
+ const OMP_READ_TIMEOUT_MS = 10_000;
80
94
  // The fit's adoption floor (merged PRs per side), margin, and cadence.
81
95
  export const MIN_N = 20;
82
96
  const ADOPT_RATIO = 0.75;
@@ -232,9 +246,11 @@ export function namedLines(named, root) {
232
246
  // ticket of the cut's kind goes to `kind=<cut>` and any other to
233
247
  // `kind!=<cut>`. A ticket that lacks the input a split reads — its issue was not
234
248
  // read, or its column is blank — goes no further than that node, and the
235
- // node's own row routes it. Every node, inner nodes and root included, holds a
236
- // `cost` row and a `speed` row of its own, and its estimates and reasons. A
237
- // table with no split is the one-node tree: `*` routes every ticket.
249
+ // node's own row routes it. A number input's column that is neither blank nor a
250
+ // plain count (digits alone) is bad input: the walk refuses it. Every node,
251
+ // inner nodes and root included, holds a `cost` row and a `speed` row of its
252
+ // own, and its estimates and reasons. A table with no split is the one-node
253
+ // tree: `*` routes every ticket.
238
254
 
239
255
  const SEP = "&";
240
256
  // Each input a split may read, and what it reads as: the columns of a ticket-features row that are known at
@@ -246,15 +262,24 @@ const INPUTS = Object.freeze({
246
262
  parent: "number", kind: "kind",
247
263
  });
248
264
 
249
- /** What a ticket holds for `input` — a number, or a kind — or null where it lacks it: its issue was not read, or its column is blank. */
265
+ /**
266
+ * What a ticket holds for `input` — a number, or a kind — or null where it lacks it: its issue was not read, or its
267
+ * column is blank. Throws `AttributionError` on a number input's column that is neither blank nor a plain count: digits
268
+ * alone, as `issueMetrics` writes one, with no sign, exponent, radix prefix, fraction or space, and few enough to read
269
+ * as a finite number.
270
+ */
250
271
  function inputOf(input, m) {
251
272
  // A row whose issue was not read has blank metrics, `brief_chars` among them: it holds none of the inputs.
252
273
  if (m.brief_chars === undefined || m.brief_chars === "") return null;
253
274
  const s = m[input] ?? "";
254
275
  if (input === "kind") return s === "" ? null : s;
255
- if (input === "parent" && s === "") return 0;
256
- const n = s === "" ? NaN : Number(s);
257
- return Number.isFinite(n) ? n : null;
276
+ if (s === "") return input === "parent" ? 0 : null;
277
+ const n = isDigits(s) ? Number(s) : NaN;
278
+ if (!Number.isFinite(n)) {
279
+ const row = m.ticket === undefined ? "a ticket-features row" : `ticket #${m.ticket}: a ticket-features row`;
280
+ throw new AttributionError(`${row}'s ${input} is '${s}', which a split reads, expected a plain count or blank`);
281
+ }
282
+ return n;
258
283
  }
259
284
 
260
285
  const child = (node, test) => (node === "*" ? test : `${node}${SEP}${test}`);
@@ -375,12 +400,57 @@ export function bArmLive(table, objective) {
375
400
  /** The row a group routes by: its own, else the `*` row's — as a name no node of the table holds does, such as a group a Routing filed under another table names. */
376
401
  export const rowFor = (rows, stratum) => rows[stratum] ?? rows["*"];
377
402
 
403
+ // The fleet's roles by price, cheapest first: the model one step along is the bigger one.
404
+ const ROLES_BY_PRICE = Object.freeze(["smol", "task", "slow"]);
405
+ // The levels a Cell can name, by effort, lowest first: the order a role's ladder is read in.
406
+ const LEVELS = Object.freeze(CELL.source.match(/\)-\(([^)]*)\)/)[1].split("|"));
407
+ const rank = (level) => LEVELS.indexOf(level);
408
+
409
+ /**
410
+ * What this install can run, for the exploration draw: `ladders`, per role, the levels its `modelRoles` target runs
411
+ * at in omp's model catalog, by effort, lowest first ([] for a role that resolves to no model or to one the catalog
412
+ * does not list); `defined`, the Cells an implementer definition exists for. `definitions` is the agents
413
+ * directory's file names.
414
+ */
415
+ export function installOf({ modelRoles, catalog, definitions }) {
416
+ const ladders = Object.fromEntries(ROLES_BY_PRICE.map((role) => {
417
+ const model = resolveRole(role, modelRoles);
418
+ const thinking = model === null ? null : catalogEntry(model, catalog)?.thinking;
419
+ return [role, Array.isArray(thinking) ? LEVELS.filter((l) => thinking.includes(l)) : []];
420
+ }));
421
+ return { ladders, defined: new Set(definitions.map(implementerCell).filter((c) => c !== null)) };
422
+ }
423
+
424
+ /**
425
+ * The exploration Cells of a group whose `cost` row Cell is `centre`, on `ladders` (installOf's): the role's next
426
+ * level above and next level below on its own ladder, the bigger model's next level below, the smaller model's
427
+ * next level above. A rung a ladder does not hold is absent: there is no level above its top, no bigger model
428
+ * above `slow` and no smaller one below `smol`.
429
+ */
430
+ export function explorationCells(centre, ladders) {
431
+ const [, role, level] = CELL.exec(centre);
432
+ const above = (r) => ladders[r].find((l) => rank(l) > rank(level));
433
+ const below = (r) => ladders[r].findLast((l) => rank(l) < rank(level));
434
+ const at = ROLES_BY_PRICE.indexOf(role);
435
+ const bigger = ROLES_BY_PRICE[at + 1];
436
+ const smaller = ROLES_BY_PRICE[at - 1];
437
+ return [
438
+ [role, above(role)], [role, below(role)],
439
+ [bigger, bigger && below(bigger)], [smaller, smaller && above(smaller)],
440
+ ].filter(([, l]) => l !== undefined).map(([r, l]) => `${r}-${l}`);
441
+ }
442
+
378
443
  /**
379
- * The Cells an exploring Pull may draw, before the guard's tripped Cells (and, after burn-in, the policy Cell) leave
380
- * any out: burn-in draws the starting Cells, whatever `cells` the table holds, and a draw after it the table's own.
381
- * The fit judges `burn_in` over the same starting Cells, so the Cells that end burn-in are the Cells it draws.
444
+ * The Cells an exploring Pull may draw, before the guard's tripped Cells leave any out: burn-in draws the starting
445
+ * Cells, whatever `cells` the table holds; a draw after it the exploration Cells around `centre`, the group's `cost`
446
+ * row Cell, that `install` (installOf's) can run — none when the install was not read (null). The fit judges
447
+ * `burn_in` over the same starting Cells, so the Cells that end burn-in are the Cells it draws.
382
448
  */
383
- const drawPool = (table) => (table.burn_in ? STARTING_CELLS : table.cells);
449
+ const drawPool = (table, centre, install) => {
450
+ if (table.burn_in) return STARTING_CELLS;
451
+ if (install === null) return [];
452
+ return explorationCells(centre, install.ladders).filter((c) => install.defined.has(c));
453
+ };
384
454
 
385
455
  /**
386
456
  * What `route` does with one row under one guard, with no per-Pull input.
@@ -388,20 +458,20 @@ const drawPool = (table) => (table.burn_in ? STARTING_CELLS : table.cells);
388
458
  * default cell when there is no guard or the row's Cell is tripped; `reason`
389
459
  * is `guard-missing`, `table-cell-tripped` or `ok`. `draw` is what an
390
460
  * exploring Pull picks from — `by` `burn-in` (every Pull) or `every-5th` —
391
- * over `cells`: drawPool()'s Cells less the tripped, and on an every-5th draw
392
- * less the `cost` row's Cell for the stratum too, as the guard leaves it (the
393
- * default cell when that row's Cell is tripped), whichever objective routes
394
- * the row. It is null with no guard and when no Cell is left to draw.
461
+ * over `cells`: drawPool()'s Cells less the tripped, centred on the `cost`
462
+ * row's Cell for the stratum as the guard leaves it (the default cell when
463
+ * that row's Cell is tripped), whichever objective routes the row. `install`
464
+ * is installOf's answer, or null where it was not read: an every-5th draw
465
+ * then has no Cell. `draw` is null with no guard and when no Cell is left.
395
466
  * @returns {{ policy: string, reason: "guard-missing"|"table-cell-tripped"|"ok", draw: null | { by: "burn-in"|"every-5th", cells: string[] } }}
396
467
  */
397
- export function rowDispatch({ table, guard, objective, stratum }) {
468
+ export function rowDispatch({ table, guard, objective, stratum, install = null }) {
398
469
  if (guard === null) return { policy: POLICY_CELL, reason: "guard-missing", draw: null };
399
470
  const tripped = new Set(guard.tripped);
400
471
  const adjust = (cell) => (tripped.has(cell) ? POLICY_CELL : cell);
401
472
  const row = rowFor(table.rows[objective], stratum);
402
473
  const by = table.burn_in ? "burn-in" : "every-5th";
403
- const left = drawPool(table).filter((c) => !tripped.has(c));
404
- const cells = table.burn_in ? left : left.filter((c) => c !== adjust(rowFor(table.rows.cost, stratum)));
474
+ const cells = drawPool(table, adjust(rowFor(table.rows.cost, stratum)), install).filter((c) => !tripped.has(c));
405
475
  return {
406
476
  policy: adjust(row),
407
477
  reason: tripped.has(row) ? "table-cell-tripped" : "ok",
@@ -482,23 +552,51 @@ export function sessionDate(session) {
482
552
  return /^(\d{4}-\d{2}-\d{2})T/.exec(session)?.[1] ?? "";
483
553
  }
484
554
 
555
+ const gcd = (a, b) => (b === 0 ? a : gcd(b, a % b));
556
+ const fraction = (n, d) => {
557
+ const g = gcd(n, d);
558
+ return d === g ? `${n / g}` : `${n / g}/${d / g}`;
559
+ };
560
+
561
+ /**
562
+ * The probability that a Pull's Cell was assigned to it, as a fraction that reads back exactly: `1`, or `<n>/<d>` in
563
+ * lowest terms. `cell` is the Cell the Pull runs, `policy` its group's Cell, and `cells` the Cells its draw was over
564
+ * (rowDispatch's), [] where there was none to draw — no guard, every candidate tripped or absent — and the Pull's Cell
565
+ * was certain. A burn-in Pull draws, chain head or not, so it is 1/K over the K Cells drawn. After burn-in a chain head
566
+ * never explores, so it is 1. Any other Pull's Cell is the sum of the two ways to it: the share left (4/5) when it is
567
+ * the group's Cell, and the exploring share times 1/K when the draw holds it — both for a group Cell that is also one
568
+ * of the Cells drawn, as under the `speed` Objective, whose Cell can be one of the `cost` row Cell's exploration Cells.
569
+ */
570
+ export function assignmentProb({ burnIn, chainHead, cell, policy, cells }) {
571
+ const K = cells.length;
572
+ if (K === 0) return "1";
573
+ if (burnIn) return fraction(1, K);
574
+ if (chainHead) return "1";
575
+ const atPolicy = cell === policy ? (EXPLORE_EVERY - 1) * K : 0;
576
+ return fraction(atPolicy + (cells.includes(cell) ? 1 : 0), EXPLORE_EVERY * K);
577
+ }
578
+
485
579
  /**
486
580
  * One Pull's routing, by `objective`'s row set. Every input is already read
487
581
  * but the paths the brief names, which `named_lines` reads under `root`, the
488
582
  * checkout. `version` is the install's, `plugin_version` on the row. The
489
583
  * ticket's group is the node the tree's walk ends at (stratumOf), and the row
490
584
  * set's row for it routes the Pull. The exploration draw ignores the objective:
491
- * it leaves out the cell the `cost` set routes the group to, whichever set
492
- * routes the Pull, so a Pull draws the same cell under both. A live B Pull
585
+ * it is centred on the cell the `cost` set routes the group to, whichever set
586
+ * routes the Pull, so a Pull draws the same cell under both. `install` is
587
+ * installOf's answer, or null where it was not read, which leaves an every-5th
588
+ * Pull nothing to draw. A live B Pull
493
589
  * records its sizing verdict and routes as an A Pull does: a label names no
494
590
  * group of the tree. `fallback` is readFitBeside's REASON when `table` is the
495
591
  * starting table standing in for a Fit, else null: it is the first thing that
496
- * went wrong, except beside no guard, where the table routes nothing.
592
+ * went wrong, except beside no guard, where the table routes nothing. The row's
593
+ * `assignment_prob` is the probability the Pull's Cell was assigned with
594
+ * (assignmentProb).
497
595
  * @returns {{ line: string, row: Record<string,string> }}
498
596
  */
499
597
  export function route({
500
598
  session, ticket, arm, implRow, chainHead = false, issue, sizing = null, guard, table, objective, now = Date.now(),
501
- root = process.cwd(), version = installVersion(), fallback = null,
599
+ root = process.cwd(), version = installVersion(), fallback = null, install = null,
502
600
  }) {
503
601
  let reason = null;
504
602
  const degrade = (r) => { reason ??= r; };
@@ -525,7 +623,7 @@ export function route({
525
623
  }
526
624
  }
527
625
 
528
- const dispatch = (o) => rowDispatch({ table, guard, objective: o, stratum });
626
+ const dispatch = (o) => rowDispatch({ table, guard, objective: o, stratum, install });
529
627
  const policyRow = dispatch(objective);
530
628
  const drawRow = dispatch("cost");
531
629
  if (policyRow.reason !== "ok") degrade(policyRow.reason);
@@ -538,10 +636,9 @@ export function route({
538
636
  if (guard !== null) {
539
637
  const exploring = table.burn_in || (implRow % EXPLORE_EVERY === 0 && !chainHead);
540
638
  if (exploring) {
541
- const policyCell = table.burn_in ? null : drawRow.policy;
542
- if (drawPool(table).some((c) => c !== policyCell && guard.tripped.includes(c))) degrade("guard-tripped");
639
+ if (drawPool(table, drawRow.policy, install).some((c) => guard.tripped.includes(c))) degrade("guard-tripped");
543
640
  if (drawRow.draw !== null) {
544
- // rowDispatch already left the policy Cell out of `cells`: nothing more to withhold.
641
+ // rowDispatch's `cells` never hold the `cost` row's Cell: nothing more to withhold.
545
642
  const d = drawCell({ session, ticket, policyCell: null, cells: drawRow.draw.cells });
546
643
  cell = d.cell;
547
644
  draw = { k: d.k, K: d.K };
@@ -550,11 +647,13 @@ export function route({
550
647
  }
551
648
  }
552
649
  reason ??= "ok";
650
+ const prob = assignmentProb({ burnIn: table.burn_in, chainHead, cell, policy, cells: drawRow.draw?.cells ?? [] });
553
651
 
554
652
  const row = {
555
653
  run_date: sessionDate(session), session, agent: `impl-${ticket}`, ticket: String(ticket),
556
654
  policy_cell: policy, chosen_cell: cell, exploration_draw: draw === null ? "" : `${draw.k}/${draw.K}`,
557
655
  sizing_src: sizingSrc, sizing_pre: sizingPre, router_usd: routerUsd, ...m, objective, plugin_version: version ?? "",
656
+ assignment_prob: prob,
558
657
  };
559
658
  const line = formatRouting({
560
659
  policy, cell, draw, by, stratum,
@@ -900,7 +999,7 @@ function main() {
900
999
  const F = defineFlags(die, {
901
1000
  flags: {
902
1001
  session: "value", objective: "value", ticket: "value", arm: "value", "impl-row": "value", issue: "value",
903
- sizing: "value", guard: "value", table: "value", pending: "value", "chain-head": "bool",
1002
+ sizing: "value", guard: "value", table: "value", pending: "value", "chain-head": "bool", "model-roles": "value", catalog: "value", agents: "value",
904
1003
  features: "value", members: "value", verdicts: "value", commit: "value", check: "bool", due: "bool",
905
1004
  },
906
1005
  positionals: ["route", "fit"],
@@ -913,7 +1012,7 @@ function main() {
913
1012
  die("usage: ticket-router.mjs route … | fit … | --check … — exactly one mode");
914
1013
  }
915
1014
  const allowed = {
916
- route: ["session", "objective", "ticket", "arm", "impl-row", "issue", "sizing", "guard", "table", "pending", "chain-head"],
1015
+ route: ["session", "objective", "ticket", "arm", "impl-row", "issue", "sizing", "guard", "table", "pending", "chain-head", "model-roles", "catalog", "agents"],
917
1016
  fit: ["table", "features", "members", "verdicts", "guard", "commit", "due"],
918
1017
  check: ["check", "table", "features", "members", "verdicts"],
919
1018
  }[mode];
@@ -963,10 +1062,44 @@ function main() {
963
1062
  }
964
1063
  const version = installVersion();
965
1064
  if (version === null) process.stderr.write(`${NAME}: WARNING ${INSTALL_PACKAGE} names no readable version — plugin_version is blank\n`);
1065
+ const guard = readGuard(readJson(guardPath));
1066
+ const chainHead = F.has("chain-head");
1067
+ // Only a Pull past burn-in that may explore reads what the install runs: its draw, or the share it ran at, needs
1068
+ // the group's exploration Cells. A read that fails or does not answer in OMP_READ_TIMEOUT_MS, a `modelRoles` that
1069
+ // is no record and a catalog with no `models` list leave the Pull no Cell to draw, and warn, never the exit; so
1070
+ // does a read that holds nothing to draw: a role that runs at no level, or no implementer definition.
1071
+ let install = null;
1072
+ if (guard !== null && !table.burn_in && !chainHead) {
1073
+ const warn = (what) => process.stderr.write(`${NAME}: WARNING ${what}\n`);
1074
+ const agents = F.arg("agents") ?? join(SCRIPT_DIR, "..", "agents");
1075
+ const kind = (v) => (v === undefined ? "absent" : v === null ? "null" : Array.isArray(v) ? "an array" : `a ${typeof v}`);
1076
+ try {
1077
+ const modelRoles = F.arg("model-roles") === null
1078
+ ? readOmpConfigValue("modelRoles", { timeout: OMP_READ_TIMEOUT_MS })
1079
+ : JSON.parse(readFileSync(F.arg("model-roles"), "utf8"));
1080
+ const catalog = F.arg("catalog") === null
1081
+ ? readOmpModelCatalog({ timeout: OMP_READ_TIMEOUT_MS })
1082
+ : JSON.parse(readFileSync(F.arg("catalog"), "utf8"));
1083
+ if (typeof modelRoles !== "object" || modelRoles === null || Array.isArray(modelRoles)) {
1084
+ throw new Error(`modelRoles is ${kind(modelRoles)}, not a record of role to model`);
1085
+ }
1086
+ if (!Array.isArray(catalog?.models)) throw new Error(`omp's model catalog has no models list (models: ${kind(catalog?.models)})`);
1087
+ install = installOf({ modelRoles, catalog, definitions: readdirSync(agents) });
1088
+ } catch (e) {
1089
+ warn(`cannot read what this install runs: ${e.message} — no exploration Cell is drawn`);
1090
+ }
1091
+ if (install !== null) {
1092
+ const unrun = ROLES_BY_PRICE.filter((role) => install.ladders[role].length === 0);
1093
+ if (unrun.length > 0) {
1094
+ 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`);
1095
+ }
1096
+ if (install.defined.size === 0) warn(`${agents} holds no implementer definition — no exploration Cell is drawn`);
1097
+ }
1098
+ }
966
1099
  const { line, row } = route({
967
- session, ticket: Number(ticket), arm, implRow: Number(implRowArg), chainHead: F.has("chain-head"),
968
- issue: readJson(issuePath), sizing: readJson(F.arg("sizing")), guard: readGuard(readJson(guardPath)), table, objective, root, version,
969
- fallback: fit?.fallback ?? null,
1100
+ session, ticket: Number(ticket), arm, implRow: Number(implRowArg), chainHead,
1101
+ issue: readJson(issuePath), sizing: readJson(F.arg("sizing")), guard, table, objective, root, version,
1102
+ fallback: fit?.fallback ?? null, install,
970
1103
  });
971
1104
  const pending = F.arg("pending") ?? join(dirname(guardPath), "ticket-features.pending.tsv");
972
1105
  // The header decision and the append are not atomic and take no lock. That is
@@ -1022,10 +1155,10 @@ function main() {
1022
1155
  }
1023
1156
  return sha;
1024
1157
  };
1025
- // The join throws on a features row it cannot date, a booked member row whose `cost` or `work_s` is not a number, and a
1026
- // ruling of a windowed Pull's ticket it cannot place — for `fit` and `--check` too on a Pull the fit then skips
1027
- // as a live B classifier's, since every windowed Pull is booked before that skip. Anything else it throws is a
1028
- // bug, never bad input, so it surfaces with its stack.
1158
+ // The join throws on a features row it cannot date or whose column a split reads holds no plain count, a booked
1159
+ // member row whose `cost` or `work_s` is not a number, and a ruling of a windowed Pull's ticket it cannot place —
1160
+ // for `fit` and `--check` too on a Pull the fit then skips as a live B classifier's, since every windowed Pull is
1161
+ // booked before that skip. Anything else it throws is a bug, never bad input, so it surfaces with its stack.
1029
1162
  const joined = (fit) => {
1030
1163
  try { return fit(); } catch (e) {
1031
1164
  if (!(e instanceof RulingError || e instanceof AttributionError)) throw e;
@@ -168,17 +168,20 @@ export function modelsEqual(a, b) {
168
168
  // defaults, global config, project settings, `--config` overlays, runtime
169
169
  // overrides — measured for the retired pool-preflight.mjs) —
170
170
  // `modelRoles.slow` dotted into a record is `Unknown setting` on this box,
171
- // so a record-valued key is always read whole. Never writes.
172
- export function readOmpConfigValue(key) {
173
- return readOmpJson(["config", "get", key, "--json"]).value;
171
+ // so a record-valued key is always read whole. Never writes. `timeout`, in
172
+ // milliseconds, kills a read that has not answered and throws as a failed read;
173
+ // none by default.
174
+ export function readOmpConfigValue(key, { timeout } = {}) {
175
+ return readOmpJson(["config", "get", key, "--json"], timeout).value;
174
176
  }
175
177
 
176
178
  // omp's model catalog, `{ models: [{ selector, thinking, … }] }` — `selector`
177
179
  // is `<provider>/<id>`, `thinking` the efforts the model runs at, `null` for
178
180
  // a model with none (measured, omp 18: `anthropic/claude-haiku-4-5` →
179
181
  // minimal…xhigh, `anthropic/claude-opus-5-5` → low…max). Never refreshes.
180
- export function readOmpModelCatalog() {
181
- return readOmpJson(["models", "--json"]);
182
+ // `timeout` as for readOmpConfigValue.
183
+ export function readOmpModelCatalog({ timeout } = {}) {
184
+ return readOmpJson(["models", "--json"], timeout);
182
185
  }
183
186
 
184
187
  // A plain JSON object — not null, an array or a scalar. Every read here
@@ -188,12 +191,13 @@ function isJsonObject(v) {
188
191
  return typeof v === "object" && v !== null && !Array.isArray(v);
189
192
  }
190
193
 
191
- function readOmpJson(argv) {
194
+ function readOmpJson(argv, timeout) {
192
195
  const cmd = `omp ${argv.join(" ")}`;
193
196
  let out;
194
197
  try {
195
- out = execFileSync("omp", argv, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 });
198
+ out = execFileSync("omp", argv, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024, timeout });
196
199
  } catch (e) {
200
+ if (e.code === "ETIMEDOUT") throw new Error(`${cmd} did not answer in ${timeout} ms`);
197
201
  throw new Error(`${cmd} failed: ${e.stderr || e.message}`);
198
202
  }
199
203
  let parsed;
@@ -282,7 +282,18 @@ unparseable or not a valid table routes by the starting table beside the
282
282
  script, and `REASON` says so (`fit-missing`, `fit-unreadable`, `fit-invalid`).
283
283
  A missing or unreadable `.fleet/cost-guard.json` routes the
284
284
  default cell only (`REASON=guard-missing`), burn-in included, whatever the Fit
285
- holds. On the ledger the
285
+ holds. Past burn-in an exploring Pull draws over its group's exploration
286
+ Cells, around the group's `cost` row Cell: its role one effort level up and
287
+ one down, the bigger model one level lower, the smaller model one level
288
+ higher — those this install runs (a definition, at a level omp's catalog lists
289
+ for the role's `modelRoles` model, both read by the router) and the guard has
290
+ not tripped. The router writes the Pull's ticket-features row with
291
+ `assignment_prob`, the probability its Cell was assigned with: in burn-in 1
292
+ over the Cells drawn; past it 4/5 at the group's Cell, 1/5 of 1 over the Cells
293
+ drawn on an exploring Pull, the two summed for a group Cell the draw also holds
294
+ (under `speed` the row's Cell can be one of the `cost` row Cell's exploration
295
+ Cells), and 1 where no Cell could be drawn (a chain head, no guard, no
296
+ candidate left). On the ledger the
286
297
  whole line, `REASON` with it, is the Pull's `## Routed` entry; a row carries no
287
298
  `route=` (an older row's `route=<REASON>` still reads).
288
299
 
@@ -446,9 +457,9 @@ controller's probe could not look.
446
457
  **Every 5th Pull by ledger count goes at an exploration cell.** Count the `impl-`
447
458
  rows in `.fleet/ledger.md` at Pull time; the Pull that creates row 5, 10, 15 …
448
459
  is an Exploration Pull, and the router draws its cell: `k = 1 +
449
- (sha256("<session>\t<ticket>")[0:8] mod K)` over the routing table's
450
- `cells` minus the policy cell, in token order. Under either Objective that
451
- policy cell is the `cost` row set's, so the draw is the same under both. While the table's `burn_in` is
460
+ (sha256("<session>\t<ticket>")[0:8] mod K)` over the group's exploration Cells
461
+ this install runs and the guard has not tripped, in token order. Under either
462
+ Objective they are the ones around the `cost` row set's Cell, so the draw is the same under both. While the table's `burn_in` is
452
463
  true every Pull draws, over the starting cells (the three models at `high`) the
453
464
  guard has not tripped, the policy cell included; a cell the table lists beyond
454
465
  them is never drawn. An