@feigi/fleet-ctl 3.147.5 → 3.148.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.147.5",
3
+ "version": "3.148.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": {
@@ -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,10 +59,10 @@
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";
@@ -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;
@@ -375,12 +389,57 @@ export function bArmLive(table, objective) {
375
389
  /** 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
390
  export const rowFor = (rows, stratum) => rows[stratum] ?? rows["*"];
377
391
 
392
+ // The fleet's roles by price, cheapest first: the model one step along is the bigger one.
393
+ const ROLES_BY_PRICE = Object.freeze(["smol", "task", "slow"]);
394
+ // The levels a Cell can name, by effort, lowest first: the order a role's ladder is read in.
395
+ const LEVELS = Object.freeze(CELL.source.match(/\)-\(([^)]*)\)/)[1].split("|"));
396
+ const rank = (level) => LEVELS.indexOf(level);
397
+
398
+ /**
399
+ * What this install can run, for the exploration draw: `ladders`, per role, the levels its `modelRoles` target runs
400
+ * at in omp's model catalog, by effort, lowest first ([] for a role that resolves to no model or to one the catalog
401
+ * does not list); `defined`, the Cells an implementer definition exists for. `definitions` is the agents
402
+ * directory's file names.
403
+ */
404
+ export function installOf({ modelRoles, catalog, definitions }) {
405
+ const ladders = Object.fromEntries(ROLES_BY_PRICE.map((role) => {
406
+ const model = resolveRole(role, modelRoles);
407
+ const thinking = model === null ? null : catalogEntry(model, catalog)?.thinking;
408
+ return [role, Array.isArray(thinking) ? LEVELS.filter((l) => thinking.includes(l)) : []];
409
+ }));
410
+ return { ladders, defined: new Set(definitions.map(implementerCell).filter((c) => c !== null)) };
411
+ }
412
+
378
413
  /**
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.
414
+ * The exploration Cells of a group whose `cost` row Cell is `centre`, on `ladders` (installOf's): the role's next
415
+ * level above and next level below on its own ladder, the bigger model's next level below, the smaller model's
416
+ * next level above. A rung a ladder does not hold is absent: there is no level above its top, no bigger model
417
+ * above `slow` and no smaller one below `smol`.
382
418
  */
383
- const drawPool = (table) => (table.burn_in ? STARTING_CELLS : table.cells);
419
+ export function explorationCells(centre, ladders) {
420
+ const [, role, level] = CELL.exec(centre);
421
+ const above = (r) => ladders[r].find((l) => rank(l) > rank(level));
422
+ const below = (r) => ladders[r].findLast((l) => rank(l) < rank(level));
423
+ const at = ROLES_BY_PRICE.indexOf(role);
424
+ const bigger = ROLES_BY_PRICE[at + 1];
425
+ const smaller = ROLES_BY_PRICE[at - 1];
426
+ return [
427
+ [role, above(role)], [role, below(role)],
428
+ [bigger, bigger && below(bigger)], [smaller, smaller && above(smaller)],
429
+ ].filter(([, l]) => l !== undefined).map(([r, l]) => `${r}-${l}`);
430
+ }
431
+
432
+ /**
433
+ * The Cells an exploring Pull may draw, before the guard's tripped Cells leave any out: burn-in draws the starting
434
+ * Cells, whatever `cells` the table holds; a draw after it the exploration Cells around `centre`, the group's `cost`
435
+ * row Cell, that `install` (installOf's) can run — none when the install was not read (null). The fit judges
436
+ * `burn_in` over the same starting Cells, so the Cells that end burn-in are the Cells it draws.
437
+ */
438
+ const drawPool = (table, centre, install) => {
439
+ if (table.burn_in) return STARTING_CELLS;
440
+ if (install === null) return [];
441
+ return explorationCells(centre, install.ladders).filter((c) => install.defined.has(c));
442
+ };
384
443
 
385
444
  /**
386
445
  * What `route` does with one row under one guard, with no per-Pull input.
@@ -388,20 +447,20 @@ const drawPool = (table) => (table.burn_in ? STARTING_CELLS : table.cells);
388
447
  * default cell when there is no guard or the row's Cell is tripped; `reason`
389
448
  * is `guard-missing`, `table-cell-tripped` or `ok`. `draw` is what an
390
449
  * 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.
450
+ * over `cells`: drawPool()'s Cells less the tripped, centred on the `cost`
451
+ * row's Cell for the stratum as the guard leaves it (the default cell when
452
+ * that row's Cell is tripped), whichever objective routes the row. `install`
453
+ * is installOf's answer, or null where it was not read: an every-5th draw
454
+ * then has no Cell. `draw` is null with no guard and when no Cell is left.
395
455
  * @returns {{ policy: string, reason: "guard-missing"|"table-cell-tripped"|"ok", draw: null | { by: "burn-in"|"every-5th", cells: string[] } }}
396
456
  */
397
- export function rowDispatch({ table, guard, objective, stratum }) {
457
+ export function rowDispatch({ table, guard, objective, stratum, install = null }) {
398
458
  if (guard === null) return { policy: POLICY_CELL, reason: "guard-missing", draw: null };
399
459
  const tripped = new Set(guard.tripped);
400
460
  const adjust = (cell) => (tripped.has(cell) ? POLICY_CELL : cell);
401
461
  const row = rowFor(table.rows[objective], stratum);
402
462
  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)));
463
+ const cells = drawPool(table, adjust(rowFor(table.rows.cost, stratum)), install).filter((c) => !tripped.has(c));
405
464
  return {
406
465
  policy: adjust(row),
407
466
  reason: tripped.has(row) ? "table-cell-tripped" : "ok",
@@ -482,23 +541,51 @@ export function sessionDate(session) {
482
541
  return /^(\d{4}-\d{2}-\d{2})T/.exec(session)?.[1] ?? "";
483
542
  }
484
543
 
544
+ const gcd = (a, b) => (b === 0 ? a : gcd(b, a % b));
545
+ const fraction = (n, d) => {
546
+ const g = gcd(n, d);
547
+ return d === g ? `${n / g}` : `${n / g}/${d / g}`;
548
+ };
549
+
550
+ /**
551
+ * The probability that a Pull's Cell was assigned to it, as a fraction that reads back exactly: `1`, or `<n>/<d>` in
552
+ * lowest terms. `cell` is the Cell the Pull runs, `policy` its group's Cell, and `cells` the Cells its draw was over
553
+ * (rowDispatch's), [] where there was none to draw — no guard, every candidate tripped or absent — and the Pull's Cell
554
+ * 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
555
+ * 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
556
+ * 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
557
+ * of the Cells drawn, as under the `speed` Objective, whose Cell can be one of the `cost` row Cell's exploration Cells.
558
+ */
559
+ export function assignmentProb({ burnIn, chainHead, cell, policy, cells }) {
560
+ const K = cells.length;
561
+ if (K === 0) return "1";
562
+ if (burnIn) return fraction(1, K);
563
+ if (chainHead) return "1";
564
+ const atPolicy = cell === policy ? (EXPLORE_EVERY - 1) * K : 0;
565
+ return fraction(atPolicy + (cells.includes(cell) ? 1 : 0), EXPLORE_EVERY * K);
566
+ }
567
+
485
568
  /**
486
569
  * One Pull's routing, by `objective`'s row set. Every input is already read
487
570
  * but the paths the brief names, which `named_lines` reads under `root`, the
488
571
  * checkout. `version` is the install's, `plugin_version` on the row. The
489
572
  * ticket's group is the node the tree's walk ends at (stratumOf), and the row
490
573
  * 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
574
+ * it is centred on the cell the `cost` set routes the group to, whichever set
575
+ * routes the Pull, so a Pull draws the same cell under both. `install` is
576
+ * installOf's answer, or null where it was not read, which leaves an every-5th
577
+ * Pull nothing to draw. A live B Pull
493
578
  * records its sizing verdict and routes as an A Pull does: a label names no
494
579
  * group of the tree. `fallback` is readFitBeside's REASON when `table` is the
495
580
  * 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.
581
+ * went wrong, except beside no guard, where the table routes nothing. The row's
582
+ * `assignment_prob` is the probability the Pull's Cell was assigned with
583
+ * (assignmentProb).
497
584
  * @returns {{ line: string, row: Record<string,string> }}
498
585
  */
499
586
  export function route({
500
587
  session, ticket, arm, implRow, chainHead = false, issue, sizing = null, guard, table, objective, now = Date.now(),
501
- root = process.cwd(), version = installVersion(), fallback = null,
588
+ root = process.cwd(), version = installVersion(), fallback = null, install = null,
502
589
  }) {
503
590
  let reason = null;
504
591
  const degrade = (r) => { reason ??= r; };
@@ -525,7 +612,7 @@ export function route({
525
612
  }
526
613
  }
527
614
 
528
- const dispatch = (o) => rowDispatch({ table, guard, objective: o, stratum });
615
+ const dispatch = (o) => rowDispatch({ table, guard, objective: o, stratum, install });
529
616
  const policyRow = dispatch(objective);
530
617
  const drawRow = dispatch("cost");
531
618
  if (policyRow.reason !== "ok") degrade(policyRow.reason);
@@ -538,10 +625,9 @@ export function route({
538
625
  if (guard !== null) {
539
626
  const exploring = table.burn_in || (implRow % EXPLORE_EVERY === 0 && !chainHead);
540
627
  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");
628
+ if (drawPool(table, drawRow.policy, install).some((c) => guard.tripped.includes(c))) degrade("guard-tripped");
543
629
  if (drawRow.draw !== null) {
544
- // rowDispatch already left the policy Cell out of `cells`: nothing more to withhold.
630
+ // rowDispatch's `cells` never hold the `cost` row's Cell: nothing more to withhold.
545
631
  const d = drawCell({ session, ticket, policyCell: null, cells: drawRow.draw.cells });
546
632
  cell = d.cell;
547
633
  draw = { k: d.k, K: d.K };
@@ -550,11 +636,13 @@ export function route({
550
636
  }
551
637
  }
552
638
  reason ??= "ok";
639
+ const prob = assignmentProb({ burnIn: table.burn_in, chainHead, cell, policy, cells: drawRow.draw?.cells ?? [] });
553
640
 
554
641
  const row = {
555
642
  run_date: sessionDate(session), session, agent: `impl-${ticket}`, ticket: String(ticket),
556
643
  policy_cell: policy, chosen_cell: cell, exploration_draw: draw === null ? "" : `${draw.k}/${draw.K}`,
557
644
  sizing_src: sizingSrc, sizing_pre: sizingPre, router_usd: routerUsd, ...m, objective, plugin_version: version ?? "",
645
+ assignment_prob: prob,
558
646
  };
559
647
  const line = formatRouting({
560
648
  policy, cell, draw, by, stratum,
@@ -900,7 +988,7 @@ function main() {
900
988
  const F = defineFlags(die, {
901
989
  flags: {
902
990
  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",
991
+ sizing: "value", guard: "value", table: "value", pending: "value", "chain-head": "bool", "model-roles": "value", catalog: "value", agents: "value",
904
992
  features: "value", members: "value", verdicts: "value", commit: "value", check: "bool", due: "bool",
905
993
  },
906
994
  positionals: ["route", "fit"],
@@ -913,7 +1001,7 @@ function main() {
913
1001
  die("usage: ticket-router.mjs route … | fit … | --check … — exactly one mode");
914
1002
  }
915
1003
  const allowed = {
916
- route: ["session", "objective", "ticket", "arm", "impl-row", "issue", "sizing", "guard", "table", "pending", "chain-head"],
1004
+ route: ["session", "objective", "ticket", "arm", "impl-row", "issue", "sizing", "guard", "table", "pending", "chain-head", "model-roles", "catalog", "agents"],
917
1005
  fit: ["table", "features", "members", "verdicts", "guard", "commit", "due"],
918
1006
  check: ["check", "table", "features", "members", "verdicts"],
919
1007
  }[mode];
@@ -963,10 +1051,44 @@ function main() {
963
1051
  }
964
1052
  const version = installVersion();
965
1053
  if (version === null) process.stderr.write(`${NAME}: WARNING ${INSTALL_PACKAGE} names no readable version — plugin_version is blank\n`);
1054
+ const guard = readGuard(readJson(guardPath));
1055
+ const chainHead = F.has("chain-head");
1056
+ // Only a Pull past burn-in that may explore reads what the install runs: its draw, or the share it ran at, needs
1057
+ // the group's exploration Cells. A read that fails or does not answer in OMP_READ_TIMEOUT_MS, a `modelRoles` that
1058
+ // is no record and a catalog with no `models` list leave the Pull no Cell to draw, and warn, never the exit; so
1059
+ // does a read that holds nothing to draw: a role that runs at no level, or no implementer definition.
1060
+ let install = null;
1061
+ if (guard !== null && !table.burn_in && !chainHead) {
1062
+ const warn = (what) => process.stderr.write(`${NAME}: WARNING ${what}\n`);
1063
+ const agents = F.arg("agents") ?? join(SCRIPT_DIR, "..", "agents");
1064
+ const kind = (v) => (v === undefined ? "absent" : v === null ? "null" : Array.isArray(v) ? "an array" : `a ${typeof v}`);
1065
+ try {
1066
+ const modelRoles = F.arg("model-roles") === null
1067
+ ? readOmpConfigValue("modelRoles", { timeout: OMP_READ_TIMEOUT_MS })
1068
+ : JSON.parse(readFileSync(F.arg("model-roles"), "utf8"));
1069
+ const catalog = F.arg("catalog") === null
1070
+ ? readOmpModelCatalog({ timeout: OMP_READ_TIMEOUT_MS })
1071
+ : JSON.parse(readFileSync(F.arg("catalog"), "utf8"));
1072
+ if (typeof modelRoles !== "object" || modelRoles === null || Array.isArray(modelRoles)) {
1073
+ throw new Error(`modelRoles is ${kind(modelRoles)}, not a record of role to model`);
1074
+ }
1075
+ if (!Array.isArray(catalog?.models)) throw new Error(`omp's model catalog has no models list (models: ${kind(catalog?.models)})`);
1076
+ install = installOf({ modelRoles, catalog, definitions: readdirSync(agents) });
1077
+ } catch (e) {
1078
+ warn(`cannot read what this install runs: ${e.message} — no exploration Cell is drawn`);
1079
+ }
1080
+ if (install !== null) {
1081
+ const unrun = ROLES_BY_PRICE.filter((role) => install.ladders[role].length === 0);
1082
+ if (unrun.length > 0) {
1083
+ 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`);
1084
+ }
1085
+ if (install.defined.size === 0) warn(`${agents} holds no implementer definition — no exploration Cell is drawn`);
1086
+ }
1087
+ }
966
1088
  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,
1089
+ session, ticket: Number(ticket), arm, implRow: Number(implRowArg), chainHead,
1090
+ issue: readJson(issuePath), sizing: readJson(F.arg("sizing")), guard, table, objective, root, version,
1091
+ fallback: fit?.fallback ?? null, install,
970
1092
  });
971
1093
  const pending = F.arg("pending") ?? join(dirname(guardPath), "ticket-features.pending.tsv");
972
1094
  // The header decision and the append are not atomic and take no lock. That is
@@ -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