@feigi/fleet-ctl 3.65.0 → 3.66.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.65.0",
3
+ "version": "3.66.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": {
@@ -22,8 +22,8 @@
22
22
  //
23
23
  // `finish` steps, in order, because the order is the point:
24
24
  //
25
- // tick `fleet-tick.mjs`, with the In-flight bound the caps
26
- // `.fleet/phase0.json` records add up to, when it names them.
25
+ // tick `fleet-tick.mjs`, with the In-flight bound
26
+ // `.fleet/phase0.json` records, when it records one.
27
27
  // Failed unless its last line is `ACTION: run over`.
28
28
  // scrape `member-outcomes.mjs <dir>` for every session directory
29
29
  // omp keeps for this cwd, each scraper's own yield line as the
@@ -50,7 +50,7 @@
50
50
  // so a run that ended here leaves no phase-0 receipt for the
51
51
  // next run in this session to resume, and that run's rotation
52
52
  // files it as `phase0.<UTC stamp>.json` beside the ledger
53
- // archive. After the tick, which reads the caps from it, and
53
+ // archive. After the tick, which reads the bound from it, and
54
54
  // before the stop. No `phase0.json` is nothing to move and is
55
55
  // `ok`; a held receipt already there that is not this one is
56
56
  // a failed step.
@@ -6,8 +6,8 @@
6
6
  //
7
7
  // Reached through the Resolver and run from the main checkout. Every kind
8
8
  // performs its writes, then runs `fleet-tick.mjs --apply` with the In-flight
9
- // bound — `--in-flight` as given, else the one `.fleet/phase0.json`'s caps
10
- // add up to, else the tick's own default — and prints one
9
+ // bound — `--in-flight` as given, else the one `.fleet/phase0.json` records,
10
+ // else the tick's own default — and prints one
11
11
  // `event: <kind>: <summary>` line with the tick's output verbatim after it.
12
12
  // Every kind is idempotent: a second run finds its writes made and only ticks
13
13
  // again.
@@ -1285,7 +1285,7 @@ import { gitEnv } from "./git-env.mjs";
1285
1285
  import { fleetFile, FleetDirUnresolvable, scratchRoot } from "./fleet-dir.mjs";
1286
1286
  import { statePath, readState, writeState, assessBeat, isStalled, isReported, stallReport, stallOwner } from "./fleet-state.mjs";
1287
1287
  import { checkMainCheckout, describe } from "./main-checkout.mjs";
1288
- import { readRunReceipt, phase0Gate } from "./phase0-receipt.mjs";
1288
+ import { readRunReceipt, phase0Gate, IN_FLIGHT_DEFAULT } from "./phase0-receipt.mjs";
1289
1289
  import { judgeRecord, ProcUnreadable } from "./proc.mjs";
1290
1290
  import { reportPath, reportsDir } from "./report-files.mjs";
1291
1291
 
@@ -1334,9 +1334,10 @@ const die = makeDie(NAME);
1334
1334
  // is left is configuration, and all of it defaults.
1335
1335
  const OPTIONS = {
1336
1336
  // The In-flight bound: the most tickets between Claim and merge at once. The
1337
- // default lives here and nowhere else in code, declared this way so it still
1338
- // goes through the guard below, where a hand-passed default went round it.
1339
- "in-flight": { type: "string", default: "5" },
1337
+ // default is phase0-receipt.mjs's, the one phase 0 also takes, declared this
1338
+ // way so it still goes through the guard below, where a hand-passed default
1339
+ // went round it.
1340
+ "in-flight": { type: "string", default: String(IN_FLIGHT_DEFAULT) },
1340
1341
  // `--fold-unchanged` prints ONE line instead of the rows when this tick asks
1341
1342
  // for nothing and says exactly what the last one said — what makes an
1342
1343
  // unattended night affordable. Opt-in because folding is wrong on an edge:
@@ -2,8 +2,8 @@
2
2
  // after every step (its header gives the shape); this module is its readers'
3
3
  // half: the tick's dispatch gate, the session directory tier-check.mjs
4
4
  // and ticket-router.mjs take when their own flag is omitted, and the In-flight
5
- // bound the drivers hand the tick. One reading of the file, so the gate and
6
- // the session readers cannot disagree about what a receipt is.
5
+ // bound the drivers hand the tick, with its default. One reading of the file,
6
+ // so the gate and the session readers cannot disagree about what a receipt is.
7
7
  //
8
8
  // Zero deps: node builtins and sibling modules only.
9
9
 
@@ -145,18 +145,17 @@ export function sessionFromReceipt(opts) {
145
145
  throw new Error(`no session given and none in the phase-0 receipt ${path} (${why}) — give one, or run ${phase0Command(null)} first`);
146
146
  }
147
147
 
148
- // What the tick's two retired cap flags defaulted to, which is what a cap the
149
- // receipt leaves unset counts as in the bound its caps add up to.
150
- const RETIRED_IMPL_CAP = 2;
151
- const RETIRED_REVIEW_CAP = 6;
148
+ // The In-flight bound a run takes when nobody gives one: the most tickets
149
+ // between Claim and merge at once. Its one definition — phase0.mjs and the
150
+ // tick's own flag default both read it from here.
151
+ export const IN_FLIGHT_DEFAULT = 5;
152
152
 
153
153
  /**
154
154
  * The bound the receipt in `fleetDir` records, as the tick's own flag:
155
- * `{ args }`, none when there is no receipt or it names no cap, or `{ error }`
156
- * for a receipt that is there and cannot be read. The tick takes one
157
- * In-flight bound, `--in-flight <B>`; a receipt that recorded the two caps
158
- * phase 0 was given maps to their sum, an unset one at what its flag
159
- * defaulted to.
155
+ * `{ args }` — `--in-flight <B>` for the `inFlight` phase 0 ran with, none
156
+ * when there is no receipt or it records no bound — or `{ error }` for a
157
+ * receipt that is there and cannot be read. The caps the receipt records
158
+ * play no part: the bound counts tickets, not members.
160
159
  */
161
160
  export function tickCaps(fleetDir) {
162
161
  let phase0;
@@ -166,7 +165,6 @@ export function tickCaps(fleetDir) {
166
165
  if (e.code === "ENOENT") return { args: [] };
167
166
  return { error: `cannot read ${join(fleetDir, RECEIPT)}: ${e.message}` };
168
167
  }
169
- const { impl, review } = phase0?.caps ?? {};
170
- if (impl == null && review == null) return { args: [] };
171
- return { args: ["--in-flight", String((impl ?? RETIRED_IMPL_CAP) + (review ?? RETIRED_REVIEW_CAP))] };
168
+ const bound = phase0?.inFlight;
169
+ return { args: bound == null ? [] : ["--in-flight", String(bound)] };
172
170
  }
@@ -2,7 +2,7 @@
2
2
  // Phase 0 as one command: the run's start sequence, in order, with a receipt.
3
3
  //
4
4
  // phase0.mjs --session <dir> [--implementer-cap n] [--reviewer-cap n]
5
- // [--plugin-checkout <dir>] [--spend-dir <dir>]
5
+ // [--in-flight n] [--plugin-checkout <dir>] [--spend-dir <dir>]
6
6
  // [--workflow <name> | --declare-no-ci]
7
7
  //
8
8
  // Reached through the Resolver and run from the MAIN checkout (a linked
@@ -31,7 +31,11 @@
31
31
  // output), exit 2 or anything else `unanswered`; neither stops
32
32
  // the run — reconciling is a write to the gate and the
33
33
  // maintainer's.
34
- // tier-roles `tier-roles.mjs --check`.
34
+ // tier-roles `tier-roles.mjs --check --in-flight <B>`. <B> is `--in-flight`
35
+ // when given, else the In-flight bound's default
36
+ // (IN_FLIGHT_DEFAULT in phase0-receipt.mjs); the caps play no
37
+ // part in it. A notice tier-roles prints on a pass is part of
38
+ // the step's output.
35
39
  // metrics `metrics-refresh.mjs`. A non-zero exit fails the step.
36
40
  // cockpit `board.mjs serve --open` launched detached, `--spend-dir`
37
41
  // passed through. Recorded; never fails the run.
@@ -55,7 +59,7 @@
55
59
  // THE RECEIPT is `.fleet/phase0.json` (resolved through fleet-dir.mjs, so a
56
60
  // worktree and the main checkout name one file):
57
61
  //
58
- // { run, session, scratch, caps: {impl, review},
62
+ // { run, session, scratch, caps: {impl, review}, inFlight,
59
63
  // steps: { <name>: { status, at, output } } }
60
64
  //
61
65
  // `status` is ok, pending, failed, drift or unanswered; `at` an ISO time;
@@ -66,7 +70,8 @@
66
70
  // run. `session` is `--session`, the one place the controller states its
67
71
  // session directory. `scratch` is what `scratch-root.mjs` prints. `caps` are
68
72
  // the flags as given, null for one not given: the tick's own defaults apply to
69
- // a cap nobody set, and a number here would pretend somebody had.
73
+ // a cap nobody set, and a number here would pretend somebody had. `inFlight`
74
+ // is the In-flight bound this run used — `--in-flight`, or its default.
70
75
  //
71
76
  // RESUMABLE. A re-run reads the receipt. It continues it — skipping every `ok`
72
77
  // step and re-running the rest — only when its `run` equals the `at` the
@@ -124,6 +129,7 @@ import { readState, stateFileIn } from "./fleet-state.mjs";
124
129
  import { gitEnv } from "./git-env.mjs";
125
130
  import { isCLI } from "./is-cli.mjs";
126
131
  import { RECEIPT, RECEIPT_HELD, archiveStamp, receiptArchiveName, rowNums } from "./ledger-grammar.mjs";
132
+ import { IN_FLIGHT_DEFAULT } from "./phase0-receipt.mjs";
127
133
 
128
134
  const NAME = "phase0";
129
135
  const SCRIPTS = dirname(fileURLToPath(import.meta.url));
@@ -222,10 +228,10 @@ function ruleset({ cwd }) {
222
228
  return { status: "unanswered", output: withText(`apply-ruleset.sh --check could not answer (${r.how})`, r) };
223
229
  }
224
230
 
225
- function tierRoles({ cwd }) {
226
- const r = node("tier-roles.mjs", ["--check"], { cwd });
231
+ function tierRoles({ cwd, receipt }) {
232
+ const r = node("tier-roles.mjs", ["--check", "--in-flight", String(receipt.inFlight)], { cwd });
227
233
  if (r.status !== 0) return refusal("tier-roles.mjs --check failed:", r);
228
- return ok("every tier route resolves");
234
+ return ok(withText(`every tier route resolves (in-flight bound ${receipt.inFlight})`, r));
229
235
  }
230
236
 
231
237
  function metrics({ cwd }) {
@@ -430,7 +436,7 @@ function main() {
430
436
  const die = makeDie(NAME);
431
437
  const F = defineFlags(die, {
432
438
  flags: {
433
- session: "value", "implementer-cap": "value", "reviewer-cap": "value", "plugin-checkout": "value",
439
+ session: "value", "implementer-cap": "value", "reviewer-cap": "value", "in-flight": "value", "plugin-checkout": "value",
434
440
  "spend-dir": "value", workflow: "value", "declare-no-ci": "bool",
435
441
  },
436
442
  });
@@ -451,6 +457,7 @@ function main() {
451
457
  return n;
452
458
  };
453
459
  const caps = { impl: positive("implementer-cap"), review: positive("reviewer-cap") };
460
+ const inFlight = positive("in-flight") ?? IN_FLIGHT_DEFAULT;
454
461
  if (F.has("declare-no-ci") && !absent("workflow")) die("--workflow and --declare-no-ci are alternatives, not a pair");
455
462
  const ci = F.has("declare-no-ci") ? "CI: declared absent (--declare-no-ci)" : absent("workflow") ? null : `CI: workflow ${F.arg("workflow")} (--workflow)`;
456
463
  const pathOf = (name) => (absent(name) ? null : resolve(F.arg(name)));
@@ -514,7 +521,7 @@ function main() {
514
521
  renameSync(receiptPath, held);
515
522
  }
516
523
 
517
- const receipt = { run: resumed ? previous.run : null, session, scratch, caps, steps: {} };
524
+ const receipt = { run: resumed ? previous.run : null, session, scratch, caps, inFlight, steps: {} };
518
525
  for (const name of STEP_NAMES) {
519
526
  const was = resumed ? previous.steps[name] : undefined;
520
527
  receipt.steps[name] = was?.status === "ok" ? was : { status: "pending", at: now, output: "not run" };
@@ -25,8 +25,15 @@
25
25
  // silently (`claude-haiku-4-5` has no `max`, so `@smol:max` would run
26
26
  // at something else), tier-check would then read a level the
27
27
  // definition never declared, and every row the definition ran would
28
- // be inadmissible. A target the catalog does
29
- // not list cannot be checked, so it fails too;
28
+ // be inadmissible. The one exception is an implementer definition
29
+ // whose cell the router never selects (not in the router table's
30
+ // `cells`, in none of its `rows` values, and not the policy cell): a
31
+ // cell can be defined before the router may pick it, so its mismatch
32
+ // is a notice. The router table is `router-table.json` beside this
33
+ // script, or the file `--table <path>` names; one that cannot be read,
34
+ // or that lacks a `cells` array or a `rows` object of cell names,
35
+ // refuses. A target the catalog does not list cannot be checked, so it
36
+ // fails too;
30
37
  // (e) `modelRoles.slow`/`modelRoles.task` resolving to the same model is
31
38
  // flagged as a notice — legal, but every `slow-*` cell then measures
32
39
  // the same model as its `task-*` twin;
@@ -48,6 +55,7 @@ import { join, dirname } from "node:path";
48
55
  import { fileURLToPath } from "node:url";
49
56
  import { isCLI } from "./is-cli.mjs";
50
57
  import { makeDie, defineFlags } from "./arg.mjs";
58
+ import { CELL_DEF, POLICY_CELL } from "./ledger-grammar.mjs";
51
59
 
52
60
  const NAME = "tier-roles";
53
61
  const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
@@ -122,6 +130,28 @@ export function expectedOmpModel(declaredModel, modelRoles) {
122
130
  return { role, level, model: role ? resolveRole(role, modelRoles) : null };
123
131
  }
124
132
 
133
+ // A definition file name -> the implementer cell it is (`task-max` for
134
+ // `fleet-implementer-task-max.agent.md`), `null` for any other definition,
135
+ // including one whose name is not a cell.
136
+ export function implementerCell(file) {
137
+ const name = file.replace(/\.agent\.md$/, "");
138
+ return CELL_DEF.test(name) ? name.slice("fleet-implementer-".length) : null;
139
+ }
140
+
141
+ // The cells the router can select from a parsed router table: the pool it
142
+ // explores (`cells`), the cell each stratum's row names (`rows` values) and the
143
+ // policy cell, which every Pull falls back to whatever the table says. An
144
+ // Error saying why when the table lacks a `cells` array of names or a `rows`
145
+ // object of names — a table that cannot be read must refuse, never quietly
146
+ // make every cell non-routable.
147
+ export function routableCells(table) {
148
+ const bad = (why) => new Error(`router table: ${why}`);
149
+ if (!isJsonObject(table)) return bad("not a JSON object");
150
+ if (!Array.isArray(table.cells) || !table.cells.every((c) => typeof c === "string")) return bad("`cells` is not an array of cell names");
151
+ if (!isJsonObject(table.rows) || !Object.values(table.rows).every((c) => typeof c === "string")) return bad("`rows` is not an object of cell names");
152
+ return new Set([POLICY_CELL, ...table.cells, ...Object.values(table.rows)]);
153
+ }
154
+
125
155
  // Tolerates a role value written without its provider prefix — omp's
126
156
  // `resolvedModelIdentity` is always provider-prefixed, a plain `modelRoles`
127
157
  // entry may not be.
@@ -210,8 +240,11 @@ function kindOf(v) {
210
240
  // leftover `task.agentModelOverrides`) against what the fleet's own
211
241
  // definitions need. `violations` stop a run; `notices` never do —
212
242
  // they flag a hazard (two roles' cells measuring one model) that is legal
213
- // configuration, just probably not what the operator meant.
214
- export function checkRoutes({ agentsDir, agentsSource = `--agents ${agentsDir}`, modelRoles, overrides, catalog }) {
243
+ // configuration, just probably not what the operator meant. `routable` is
244
+ // the set `routableCells` returns: the router never selects an implementer
245
+ // definition outside it, so an unsupported level there is a notice; `null`
246
+ // is no table at all, and then every definition is held to the level check.
247
+ export function checkRoutes({ agentsDir, agentsSource = `--agents ${agentsDir}`, modelRoles, overrides, catalog, routable = null }) {
215
248
  const violations = [];
216
249
  const notices = [];
217
250
  const usedBy = {}; // role -> [{ file, level }, ...]
@@ -276,8 +309,13 @@ export function checkRoutes({ agentsDir, agentsSource = `--agents ${agentsDir}`,
276
309
  }
277
310
  const efforts = entry.thinking ?? [];
278
311
  for (const { file, level } of usedBy[role]) {
279
- if (!efforts.includes(level)) {
280
- violations.push(`${file}: level ${level} is not one modelRoles.${role}'s target ${model} runs at (thinking: ${efforts.join(", ") || "none"}) — omp would clamp it silently`);
312
+ if (efforts.includes(level)) continue;
313
+ const mismatch = `${file}: level ${level} is not one modelRoles.${role}'s target ${model} runs at (thinking: ${efforts.join(", ") || "none"})`;
314
+ const cell = implementerCell(file);
315
+ if (routable !== null && cell !== null && !routable.has(cell)) {
316
+ notices.push(`${mismatch} — cell ${cell} is not one the router selects; omp would clamp this level silently once it does`);
317
+ } else {
318
+ violations.push(`${mismatch} — omp would clamp it silently`);
281
319
  }
282
320
  }
283
321
  }
@@ -340,6 +378,7 @@ const { arg, numArg, has, sweep, stray } = defineFlags(die, {
340
378
  overrides: "value",
341
379
  "model-roles": "value",
342
380
  catalog: "value",
381
+ table: "value",
343
382
  "max-concurrency": "value",
344
383
  },
345
384
  });
@@ -377,7 +416,7 @@ function main() {
377
416
  stray();
378
417
 
379
418
  const check = has("check");
380
- if (!check) die("--check --in-flight <B> is required (usage: tier-roles.mjs --check --in-flight <B> [--agents <dir>] [--model-roles <path>] [--overrides <path>] [--catalog <path>] [--max-concurrency <path>])");
419
+ if (!check) die("--check --in-flight <B> is required (usage: tier-roles.mjs --check --in-flight <B> [--agents <dir>] [--model-roles <path>] [--overrides <path>] [--catalog <path>] [--table <path>] [--max-concurrency <path>])");
381
420
 
382
421
  // numArg() is the fleet's digits rule (arg.mjs): `0x5`, `1e1`, ` 5`, `5.0`
383
422
  // and `+5` are refused where `Number()` would have read a bound the caller
@@ -392,6 +431,15 @@ function main() {
392
431
  const overrides = loadJsonObject(arg("overrides"), ...config("task.agentModelOverrides"), "overrides");
393
432
  const modelRoles = loadJsonObject(arg("model-roles"), ...config("modelRoles"), "model-roles");
394
433
  const catalog = loadJsonObject(arg("catalog"), readOmpModelCatalog, "omp models --json", "catalog");
434
+ const tablePath = arg("table") ?? join(SCRIPT_DIR, "router-table.json");
435
+ let table;
436
+ try {
437
+ table = JSON.parse(readFileSync(tablePath, "utf8"));
438
+ } catch (e) {
439
+ die(`cannot read the router table ${tablePath}: ${e.message}`);
440
+ }
441
+ const routable = routableCells(table);
442
+ if (routable instanceof Error) die(`${tablePath}: ${routable.message}`);
395
443
 
396
444
  const { violations, notices } = checkRoutes({
397
445
  agentsDir,
@@ -399,8 +447,8 @@ function main() {
399
447
  modelRoles,
400
448
  overrides,
401
449
  catalog,
450
+ routable,
402
451
  });
403
-
404
452
  const notice = semaphoreNotice({ inFlight: inFlightBound, read: readMaxConcurrency(arg("max-concurrency")) });
405
453
  if (notice !== null) notices.push(notice);
406
454
 
@@ -1006,7 +1006,9 @@ Before the run's first dispatch run `~/.fleet/bin/fleet-run tier-roles.mjs
1006
1006
  --check`; exit 1 names every definition whose `model:` is not a route,
1007
1007
  every unset `modelRoles.<role>` a definition needs, every definition whose
1008
1008
  `:<level>` its role's target does not run at (omp's model catalog — omp
1009
- would clamp it silently), every
1009
+ would clamp it silently), except an implementer definition whose cell the
1010
+ router never selects (not in `router-table.json`'s `cells` or `rows` values,
1011
+ and not the policy cell), which is a notice and never stops the run; every
1010
1012
  `task.agentModelOverrides` entry that would shadow a fleet definition, and
1011
1013
  an `--agents` directory holding no `*.agent.md` definition,
1012
1014
  prints the exact remedy, and **stops the run** before any member is