@feigi/fleet-ctl 3.147.4 → 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.4",
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
 
package/scripts/evict.mjs CHANGED
@@ -21,7 +21,8 @@
21
21
  // `wt_op_state` reads, which reap.sh reads too;
22
22
  // - this script's own cwd is inside it;
23
23
  // - a live member token holds it (below);
24
- // - it carries the mark already;
24
+ // - it carries the mark and ignores nothing but the runner, or its ignored
25
+ // paths cannot be listed;
25
26
  // - `git status --porcelain -uall` in it is non-empty;
26
27
  // - HEAD moved or a restore ran in it within IDLE_MS: the newer of the
27
28
  // newest entry of the tree's own HEAD reflog (`logs/HEAD` in its admin
@@ -31,7 +32,10 @@
31
32
  // - anything about it cannot be read — its `.git`, its admin dir, a status,
32
33
  // a reflog. A worktree listing that cannot be read keeps the whole
33
34
  // `.worktrees/` directory, with that reason.
34
- // Every other candidate is evicted.
35
+ // Every other candidate is evicted. A tree that carries the mark and still
36
+ // holds ignored paths — a removal that partly failed, a restore's partial
37
+ // install, a restore still installing, an install by hand — meets the rest of
38
+ // those rules like an unmarked one, and when none holds it is evicted again.
35
39
  //
36
40
  // LIVE TOKENS. The ledger's live tokens (ledger-grammar.mjs's liveOnLedger())
37
41
  // of the members that work a claim tree's ticket or PR — `impl-<N>`,
@@ -49,11 +53,13 @@
49
53
  // an absent ledger is no live token. Only ENOENT is absence.
50
54
  //
51
55
  // `--apply` judges each tree to evict again, writes the mark (EVICTED, a file
52
- // in the tree's git admin dir), then removes every ignored path but the
53
- // runner through reclaim-scratch.mjs's one removal sequence. Tracked files,
54
- // HEAD, the branch and the registration are not touched. Best-effort per
55
- // tree: a tree whose mark cannot be written, or a path in it that cannot be
56
- // removed, lands in `failed` and keeps its mark; the sweep goes on.
56
+ // in the tree's git admin dir) unless the tree carries it already, then removes
57
+ // every ignored path but the runner through reclaim-scratch.mjs's one removal
58
+ // sequence. Tracked files, HEAD, the branch and the registration are not
59
+ // touched. Best-effort per tree: a tree whose mark cannot be written, or a path
60
+ // in it that cannot be removed, lands in `failed`; the sweep goes on. A mark
61
+ // written stays as written, and a path that cannot be removed is tried again,
62
+ // and named in `failed` again, on every sweep until it is gone.
57
63
  //
58
64
  // Prints ONE JSON line:
59
65
  // {"applied","ledger":<abs path|null>,"evicted":[{"path","reason","ignored"}],
@@ -73,11 +79,14 @@
73
79
  // inside the repository only against origin/main, so the tree's own change, a
74
80
  // tree behind origin/main or a later word of the command can each produce it.
75
81
  // A status that is not empty BEFORE it refuses in words of its own, before
76
- // anything runs: that change is no Install step's. Only once the status after
77
- // it is empty does it write the restore time (RESTORED) and then remove the
78
- // mark; every refusal leaves the mark. A tree with no mark refuses: there is
79
- // nothing to restore. Without `--apply` it runs nothing and prints the command
80
- // it would run. Prints
82
+ // anything runs: that change is no Install step's. Once the checks ahead of
83
+ // the Install step pass, and before it starts, it writes the restore time
84
+ // (RESTORED), so the tree is held for IDLE_MS from the restore's start; a time
85
+ // that cannot be written refuses before the Install step runs. Only once the
86
+ // status after the Install step is empty does it remove the mark; every
87
+ // refusal leaves the mark. A tree with no mark refuses: there is nothing to
88
+ // restore. Without `--apply` it runs nothing and prints the command it would
89
+ // run. Prints
81
90
  // `{"applied","worktree","install"}`; exit 0 restored (or would), 2 refused.
82
91
  //
83
92
  // That install sequence is `installIn()`, exported: finisher-tree.mjs runs the
@@ -314,7 +323,17 @@ function judge(w, ctx) {
314
323
  if (held !== null) return { kept: held };
315
324
  const mark = evictionMark(w.path);
316
325
  if (mark.unknown !== undefined) return { kept: mark.unknown };
317
- if (mark.marked) return { kept: `already evicted: ${join(mark.dir, EVICTED)} is there` };
326
+ // A marked tree is judged like any other once it is known to hold ignored
327
+ // paths; one that holds none is the eviction done.
328
+ let ignored;
329
+ if (mark.marked) {
330
+ try {
331
+ ignored = ignoredPaths(w.path);
332
+ } catch (e) {
333
+ return { kept: e.message };
334
+ }
335
+ if (ignored.length === 0) return { kept: `already evicted: ${join(mark.dir, EVICTED)} is there` };
336
+ }
318
337
  const status = git(w.path, ["status", "--porcelain", "-uall"]);
319
338
  if (status.error || status.status !== 0) return { kept: `cannot read its status (${how(status)})` };
320
339
  if (status.stdout !== "") return { kept: `git status is not clean (first: ${status.stdout.split("\n")[0]})` };
@@ -329,22 +348,27 @@ function judge(w, ctx) {
329
348
  const last = Math.max(moved, restored ?? 0);
330
349
  const what = restored !== null && restored >= moved ? "restored" : "HEAD last moved";
331
350
  if (!isIdle(ctx.now, last)) return { kept: `${what} ${new Date(last).toISOString()}, within ${IDLE_MS / DAY_MS} days` };
332
- let ignored;
333
- try {
334
- ignored = ignoredPaths(w.path);
335
- } catch (e) {
336
- return { kept: e.message };
351
+ if (!mark.marked) {
352
+ try {
353
+ ignored = ignoredPaths(w.path);
354
+ } catch (e) {
355
+ return { kept: e.message };
356
+ }
357
+ if (ignored.length === 0) return { kept: `it ignores nothing but ${RUNNER}` };
337
358
  }
338
- if (ignored.length === 0) return { kept: `it ignores nothing but ${RUNNER}` };
339
- return { evict: { reason: `${what} ${new Date(last).toISOString()}, over ${IDLE_MS / DAY_MS} days ago`, ignored, dir: admin.dir } };
359
+ const idle = `${what} ${new Date(last).toISOString()}, over ${IDLE_MS / DAY_MS} days ago`;
360
+ return { evict: { reason: mark.marked ? `already evicted, ignored paths left — ${idle}` : idle, ignored, dir: admin.dir, marked: mark.marked } };
340
361
  }
341
362
 
342
- // Mark the tree, then remove each ignored path in it; null, or the error.
363
+ // Mark the tree, unless it carries the mark already, then remove each ignored
364
+ // path in it; null, or the error.
343
365
  function evictTree(path, verdict, now) {
344
- try {
345
- writeFileSync(join(verdict.dir, EVICTED), `${new Date(now).toISOString()}\n`);
346
- } catch (e) {
347
- return `could not write ${join(verdict.dir, EVICTED)} (${e.code ?? e.message}), so nothing was removed`;
366
+ if (!verdict.marked) {
367
+ try {
368
+ writeFileSync(join(verdict.dir, EVICTED), `${new Date(now).toISOString()}\n`);
369
+ } catch (e) {
370
+ return `could not write ${join(verdict.dir, EVICTED)} (${e.code ?? e.message}), so nothing was removed`;
371
+ }
348
372
  }
349
373
  const errors = [];
350
374
  for (const p of verdict.ignored) {
@@ -403,17 +427,21 @@ function sweep({ afterRotate, apply }) {
403
427
  * derive derive-testcmd.sh would not name the Install step
404
428
  * status-before the tree state could not be read before the Install step
405
429
  * dirty-before the tree was not clean before it: nothing ran
430
+ * before-run `beforeRun` refused: nothing ran
406
431
  * not-run the Install step could not be started, or exited 126 or 127
407
432
  * failed it was killed by a signal, or exited non-zero
408
433
  * status-after the tree state could not be read after it
409
434
  * dirtied it left the tree changed
410
435
  * `verb` names the operation in the dirty-before refusal, and `retry` whether
411
436
  * that refusal tells its reader to clear the change and run the operation again:
412
- * a restore's caller may, the finisher may not. `install` is null in a refusal
413
- * that came before the command was read. Nothing here writes a mark or a
414
- * restore time, and it never exits the process.
437
+ * a restore's caller may, the finisher may not. `beforeRun`, when given, is
438
+ * called with `apply` set, after every check ahead of the Install step has
439
+ * passed and just before it starts; it returns null, or the message of a
440
+ * refusal, which then keeps the Install step from running. `install` is null in
441
+ * a refusal that came before the command was read. Nothing here writes a mark
442
+ * or a restore time, and it never exits the process.
415
443
  */
416
- export function installIn(tree, apply, { verb = "restore", retry = true } = {}) {
444
+ export function installIn(tree, apply, { verb = "restore", retry = true, beforeRun = () => null } = {}) {
417
445
  const refuse = (kind, message, install = null, exit = null) => ({ refusal: { kind, message, install, exit } });
418
446
  const derived = run("sh", [join(SCRIPT_DIR, "derive-testcmd.sh"), tree, "install", "--at", "origin/main"]);
419
447
  const install = String(derived.stdout ?? "").replace(/\n$/, "");
@@ -429,6 +457,8 @@ export function installIn(tree, apply, { verb = "restore", retry = true } = {})
429
457
  return refuse("dirty-before", `${tree} is not clean before the ${verb} (first: ${before.stdout.split("\n")[0]}) — the Install step did not run${then}`, install);
430
458
  }
431
459
  if (!apply) return { install };
460
+ const stopped = beforeRun();
461
+ if (stopped !== null) return refuse("before-run", stopped, install);
432
462
  // Through `sh -c` with `CI` unset and the output dropped, as claim-ticket.sh
433
463
  // runs it; no timeout, as there.
434
464
  const r = run("sh", ["-c", install], { cwd: tree, drop: ["CI"], stdio: "ignore", timeout: 0 });
@@ -453,18 +483,23 @@ function restore(tree, apply) {
453
483
  const mark = evictionMark(tree);
454
484
  if (mark.unknown !== undefined) die(`cannot tell whether ${tree} is evicted: ${mark.unknown}`);
455
485
  if (!mark.marked) die(`${tree} is not evicted (no ${join(mark.dir, EVICTED)}) — nothing to restore`);
456
- const done = installIn(tree, apply);
457
- if (done.refusal) die(done.refusal.message);
458
- const { install } = done;
459
- if (apply) {
460
- // The restore time first: a mark removed with no time beside it would read
461
- // the tree idle by its HEAD alone and evict it again at once.
462
- const restored = join(mark.dir, RESTORED);
486
+ const restored = join(mark.dir, RESTORED);
487
+ // The restore time first, once the checks ahead of the Install step pass: the
488
+ // idle gate then holds the tree while it installs and, when the Install step
489
+ // is refused, for IDLE_MS after, and a mark removed with no time beside it
490
+ // would read the tree idle by its HEAD alone and evict it again at once.
491
+ const record = () => {
463
492
  try {
464
493
  writeFileSync(restored, `${new Date().toISOString()}\n`);
465
494
  } catch (e) {
466
- die(`installed in ${tree}, but could not record the restore in ${restored} (${e.code ?? e.message}) — the mark stays`);
495
+ return `could not record the restore in ${restored} (${e.code ?? e.message}), so the Install step did not run — the mark stays`;
467
496
  }
497
+ return null;
498
+ };
499
+ const done = installIn(tree, apply, { beforeRun: record });
500
+ if (done.refusal) die(done.refusal.message);
501
+ const { install } = done;
502
+ if (apply) {
468
503
  try {
469
504
  unlinkSync(join(mark.dir, EVICTED));
470
505
  } catch (e) {
@@ -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