@feigi/fleet-ctl 3.68.0 → 3.69.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.68.0",
3
+ "version": "3.69.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": {
@@ -1288,6 +1288,19 @@ export function noTranscriptLines({ live, seen, stems, session, after, now }) {
1288
1288
  return out;
1289
1289
  }
1290
1290
 
1291
+ // The age-based checks this tick would run: CHECK-LIVENESS on
1292
+ // a live name of a known family, NO-TRANSCRIPT on a live member token with no
1293
+ // transcript among `stems` (null when the session was not listed). main()
1294
+ // names them on stderr when the state file is degraded: its `seen` stamps
1295
+ // cannot be read, so every token reads as first seen now and neither fires.
1296
+ export function ageChecks({ live, stems }) {
1297
+ const has = new Set(stems);
1298
+ return [
1299
+ ...(live.some((name) => livenessFamily(name) !== null) ? ["CHECK-LIVENESS"] : []),
1300
+ ...(stems !== null && live.some((name) => parseMember(name) !== null && !has.has(name)) ? ["NO-TRANSCRIPT"] : []),
1301
+ ];
1302
+ }
1303
+
1291
1304
  // --apply's pure half. The merge-bot numbers `applied.reapAfter` names for
1292
1305
  // THIS run: none when its `run` is not the controller record's `at`, since
1293
1306
  // merge-bot numbering restarts with a run and the state file outlives it
@@ -2087,6 +2100,8 @@ function main() {
2087
2100
  // registry census. It is not a row — it resets no `quiet`, moves no count
2088
2101
  // and frees no slot — and nothing here settles, kills or writes the ledger.
2089
2102
  const seen = stampSeen({ live: run.live, prev: prev.seen, controller: prev.controller, now });
2103
+ const ageless = prev.degraded ? ageChecks({ live: run.live, stems }) : [];
2104
+ if (ageless.length) console.error(`${NAME}: ${ageless.join(" and ")} not checked — ${path} ${prev.degraded}, so first-seen ages are unavailable`);
2090
2105
  const stale = livenessLines({ live: run.live, seen, thresholds: liveness, now });
2091
2106
  // Advisory the same way: a report on disk prints the settle it is for, and
2092
2107
  // nothing here runs it.
@@ -154,8 +154,7 @@ export const IN_FLIGHT_DEFAULT = 5;
154
154
  * The bound the receipt in `fleetDir` records, as the tick's own flag:
155
155
  * `{ args }` — `--in-flight <B>` for the `inFlight` phase 0 ran with, none
156
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.
157
+ * receipt that is there and cannot be read.
159
158
  */
160
159
  export function tickCaps(fleetDir) {
161
160
  let phase0;
@@ -1,8 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  // Phase 0 as one command: the run's start sequence, in order, with a receipt.
3
3
  //
4
- // phase0.mjs --session <dir> [--implementer-cap n] [--reviewer-cap n]
5
- // [--in-flight n] [--plugin-checkout <dir>] [--spend-dir <dir>]
4
+ // phase0.mjs --session <dir> [--in-flight n] [--plugin-checkout <dir>]
5
+ // [--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
@@ -33,8 +33,8 @@
33
33
  // maintainer's.
34
34
  // tier-roles `tier-roles.mjs --check --in-flight <B>`. <B> is `--in-flight`
35
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
36
+ // (IN_FLIGHT_DEFAULT in phase0-receipt.mjs). A notice
37
+ // tier-roles prints on a pass is part of
38
38
  // the step's output.
39
39
  // metrics `metrics-refresh.mjs`. A non-zero exit fails the step.
40
40
  // cockpit `board.mjs serve --open` launched detached, `--spend-dir`
@@ -59,7 +59,7 @@
59
59
  // THE RECEIPT is `.fleet/phase0.json` (resolved through fleet-dir.mjs, so a
60
60
  // worktree and the main checkout name one file):
61
61
  //
62
- // { run, session, scratch, caps: {impl, review}, inFlight,
62
+ // { run, session, scratch, inFlight,
63
63
  // steps: { <name>: { status, at, output } } }
64
64
  //
65
65
  // `status` is ok, pending, failed, drift or unanswered; `at` an ISO time;
@@ -68,9 +68,7 @@
68
68
  // `pending`. `run` is the `at` that `ledger.mjs rotate` wrote into the
69
69
  // controller record in `.fleet/heartbeat.json`, null until the rotation has
70
70
  // run. `session` is `--session`, the one place the controller states its
71
- // session directory. `scratch` is what `scratch-root.mjs` prints. `caps` are
72
- // the flags as given, null for one not given: the tick's own defaults apply to
73
- // a cap nobody set, and a number here would pretend somebody had. `inFlight`
71
+ // session directory. `scratch` is what `scratch-root.mjs` prints. `inFlight`
74
72
  // is the In-flight bound this run used — `--in-flight`, or its default.
75
73
  //
76
74
  // RESUMABLE. A re-run reads the receipt. It continues it — skipping every `ok`
@@ -436,7 +434,7 @@ function main() {
436
434
  const die = makeDie(NAME);
437
435
  const F = defineFlags(die, {
438
436
  flags: {
439
- session: "value", "implementer-cap": "value", "reviewer-cap": "value", "in-flight": "value", "plugin-checkout": "value",
437
+ session: "value", "in-flight": "value", "plugin-checkout": "value",
440
438
  "spend-dir": "value", workflow: "value", "declare-no-ci": "bool",
441
439
  },
442
440
  });
@@ -456,7 +454,6 @@ function main() {
456
454
  if (n !== null && n < 1) die(`--${name} needs a positive number, got ${n}`);
457
455
  return n;
458
456
  };
459
- const caps = { impl: positive("implementer-cap"), review: positive("reviewer-cap") };
460
457
  const inFlight = positive("in-flight") ?? IN_FLIGHT_DEFAULT;
461
458
  if (F.has("declare-no-ci") && !absent("workflow")) die("--workflow and --declare-no-ci are alternatives, not a pair");
462
459
  const ci = F.has("declare-no-ci") ? "CI: declared absent (--declare-no-ci)" : absent("workflow") ? null : `CI: workflow ${F.arg("workflow")} (--workflow)`;
@@ -521,7 +518,7 @@ function main() {
521
518
  renameSync(receiptPath, held);
522
519
  }
523
520
 
524
- const receipt = { run: resumed ? previous.run : null, session, scratch, caps, inFlight, steps: {} };
521
+ const receipt = { run: resumed ? previous.run : null, session, scratch, inFlight, steps: {} };
525
522
  for (const name of STEP_NAMES) {
526
523
  const was = resumed ? previous.steps[name] : undefined;
527
524
  receipt.steps[name] = was?.status === "ok" ? was : { status: "pending", at: now, output: "not run" };
@@ -1,15 +1,16 @@
1
1
  ---
2
2
  name: run-team
3
- description: Run an agent fleet — implementers, reviewers (default 2 and 6), one merge bot — over the ready-for-agent queue. Invoke-only; the fleet writes to a live repo and must never start unasked.
4
- argument-hint: "[implementers] [reviewers]"
3
+ description: Run an agent fleet — implementers, reviewers, one merge bot — over the ready-for-agent queue. Invoke-only; the fleet writes to a live repo and must never start unasked.
4
+ argument-hint: "[in-flight]"
5
5
  disable-model-invocation: true
6
6
  ---
7
7
 
8
8
  Run `next-ticket`, `review-and-fix`, `run-merge-bot` as one fleet. You are the
9
9
  **controller**, in the main thread, never a member.
10
10
 
11
- `$ARGUMENTS` = `[implementers] [reviewers]`, both optional, default 2 and 6, no
12
- hard cap — they become the tick's `--implementer-cap` and `--reviewer-cap`.
11
+ `$ARGUMENTS` = `[in-flight]`, optional, one positive integer, default 5: the
12
+ In-flight bound, the most tickets between Claim and merge at once. It becomes
13
+ the tick's `--in-flight` and `tier-roles.mjs --check --in-flight`.
13
14
  Merge bot is at most one, not configurable.
14
15
 
15
16
  The war story behind a rule ending `See references/<file>` lives in that file; load
@@ -258,8 +259,8 @@ phase, or in any later one, asks the maintainer which tickets to take.
258
259
 
259
260
  0. **Once per run, before anything else.** Run `~/.fleet/bin/fleet-run
260
261
  phase0.mjs --session <session-dir>` from this main checkout, `<session-dir>`
261
- being this run's own session directory. Add `--implementer-cap <n>` and
262
- `--reviewer-cap <n>` for the caps `$ARGUMENTS` gave, `--plugin-checkout
262
+ being this run's own session directory. Add `--in-flight <n>` when
263
+ `$ARGUMENTS` gave one, `--plugin-checkout
263
264
  <dir>` when this workspace tracks no `plugin/…` of its own, `--spend-dir
264
265
  <dir>` to name the directory the cockpit's spend panel reads, and
265
266
  `--workflow <name>` or `--declare-no-ci` when the repository has no workflow
@@ -275,6 +276,13 @@ phase, or in any later one, asks the maintainer which tickets to take.
275
276
  `rotate` has run, a re-run skips every `ok` step and resumes where the last
276
277
  one stopped; before it, a re-run runs every step again.
277
278
 
279
+ The `tier-roles` step runs `~/.fleet/bin/fleet-run tier-roles.mjs --check
280
+ --in-flight <B>`, `<B>` being the `--in-flight` given, else the default
281
+ **Defaults** (**Queue depth**) states. What it checks is under **Phase 2**'s
282
+ tier routes. A line it prints on a pass about omp's `task.maxConcurrency`
283
+ is a notice in the step's output and never holds: read it, report it, and
284
+ go on — the fleet never writes that setting.
285
+
278
286
  - `NEED derive-recipe` — the Recipe cache holds nothing valid. Dispatch a
279
287
  `task` member named `derive-recipe`, agent `fleet-recipe-deriver`, its
280
288
  prompt the brief `~/.fleet/bin/fleet-run dispatch-prompt.mjs render
@@ -352,13 +360,15 @@ phase, or in any later one, asks the maintainer which tickets to take.
352
360
  `ready-for-human` and untriaged work you have no channel for. A partial
353
361
  drop, survivors and specs together, is named the same way.
354
362
  2. **Refresh is the tick's from here on.** `fleet-tick.mjs` runs
355
- `shortlist.mjs` itself when unclaimed entries fall below the implementer
356
- cap, when the file is missing or empty, when an `excluded` premise has
363
+ `shortlist.mjs` itself when unclaimed entries fall below the In-flight
364
+ bound, when the file is missing or empty, when an `excluded` premise has
357
365
  lifted, and when a branch-named `behind-pr` exclusion whose PR is not yet
358
366
  MERGED or CLOSED, or a `behind-issue` exclusion whose issue is not yet
359
367
  closed, names a ticket the file still carries, and prints
360
368
  `REFRESHED shortlist: <n> entries; <k> lifted`. Phase 0 runs it by hand
361
369
  once because a dead run's shortlist is stale by definition.
370
+ None of those triggers runs while `HOLD (in-flight <n>/<B>)` stands
371
+ (**Queue depth**).
362
372
 
363
373
  **No multi-select, no maintainer tick.** Selection and ordering are batched —
364
374
  one scan, oldest first; admission never is. The invariant this replaces — one
@@ -481,7 +491,7 @@ worktree re-created for an already-open PR is in references/isolation.md.
481
491
  ## Phase 2 — dispatch the Pull's implementer
482
492
 
483
493
  **A Pull is one claim followed by one dispatch of a new member under a name no
484
- member has held; nothing holds a queue.** The implementer cap is the fleet's
494
+ member has held; nothing holds a queue.** The In-flight bound is the fleet's
485
495
  own accounting rather than anything the runtime enforces, and the member is
486
496
  fresh and never a wake of one that already ran. Admission is per slot and
487
497
  never batched, so there is nothing to hand a freed slot its next ticket but
@@ -587,7 +597,7 @@ next member on top of an unchecked or mismatched dispatch multiplies whatever
587
597
  silently degraded. The tick prints `HOLD (tier unchecked impl-<N>)` for the
588
598
  newest `impl-` member of a ticket whose row carries none of the three
589
599
  verdicts, whether that member is still running or already settled `bailed`,
590
- `killed` or `released`, and `HOLD (tier mismatch impl-<N>)` for a mismatched
600
+ `killed`, `released` or `blocked`, and `HOLD (tier mismatch impl-<N>)` for a mismatched
591
601
  one. Only the newest member counts, so a replacement (`impl-<N>-b`) is what
592
602
  clears a mismatch — and is then owed its own check. A mismatch on a ticket
593
603
  whose issue is already CLOSED holds nothing: the tick probes that issue and
@@ -646,7 +656,8 @@ the role's baked one, and the tier check judges a member against the
646
656
  role's own target (`modelRoles.<role>`), never a model family.
647
657
 
648
658
  Before the run's first dispatch run `~/.fleet/bin/fleet-run tier-roles.mjs
649
- --check`; exit 1 names every definition whose `model:` is not a route,
659
+ --check --in-flight <B>`, `<B>` the run's In-flight bound (phase 0's
660
+ `tier-roles` step runs it); exit 1 names every definition whose `model:` is not a route,
650
661
  every unset `modelRoles.<role>` a definition needs, every definition whose
651
662
  `:<level>` its role's target does not run at (omp's model catalog — omp
652
663
  would clamp it silently), except an implementer definition whose cell the
@@ -655,7 +666,12 @@ and not the policy cell), which is a notice and never stops the run; every
655
666
  `task.agentModelOverrides` entry that would shadow a fleet definition, and
656
667
  an `--agents` directory holding no `*.agent.md` definition,
657
668
  prints the exact remedy, and **stops the run** before any member is
658
- dispatched — the fleet reads that config and never writes it.
669
+ dispatched — the fleet reads that config and never writes it. omp's
670
+ `task.maxConcurrency` is not the bound (it counts live members, not tickets,
671
+ queues at its ceiling rather than refusing, and is session-wide): below
672
+ 2·B+2, or when it cannot be read, the check prints a notice line and still
673
+ exits 0, so the notice is the operator's to read and report, never a reason to
674
+ stop the run.
659
675
 
660
676
  **Every 5th Pull by ledger count goes at an exploration cell.** Count the `impl-`
661
677
  rows in `.fleet/ledger.md` at Pull time; the Pull that creates row 5, 10, 15 …
@@ -993,8 +1009,8 @@ owes beyond its call:
993
1009
  never runs. Listed first because it is the only wake with no trigger —
994
1010
  every other row above arrives; this one is the absence of one.
995
1011
  - **Implementer report** → the PR is owed a review from here on:
996
- the tick names it as `DISPATCH review PR#<M>` once a reviewer slot is free,
997
- and it names the next shortlist head for the slot the implementer left. Pull
1012
+ the tick names it as `DISPATCH review PR#<M>`, and it names the next
1013
+ shortlist head whenever the In-flight count is below the bound. Pull
998
1014
  nothing the tick did not name.
999
1015
  - **Finisher reports halted** → the per-cause rule (**Resolving a finisher
1000
1016
  halt**, below).
@@ -1138,23 +1154,26 @@ owes beyond its call:
1138
1154
  **In one line, every wake is one `fleet-event.mjs` call, which ends in the tick.** One tick invocation, and you act on what it prints:
1139
1155
 
1140
1156
  ```
1141
- ~/.fleet/bin/fleet-run fleet-tick.mjs --apply [--implementer-cap <n>] [--reviewer-cap <n>] [--max-reviews <n>]
1157
+ ~/.fleet/bin/fleet-run fleet-tick.mjs --apply [--in-flight <n>]
1142
1158
  ```
1143
1159
 
1144
- It reads the run itself, and nobody states a count. Live implementers, live
1145
- review units (in-flight `review=` tokens plus unsettled `fix-pr-` ones), the
1146
- merge bot, merge holds, tier mismatches and the drain marker come off
1147
- `.fleet/ledger.md`; the unclaimed heads and the supply come off
1148
- `.fleet/shortlist.json`, which it refreshes itself when the unclaimed count is
1149
- below the implementer cap, when the file is missing or empty, when an
1150
- Exclusion's premise has lifted, or when a branch-named `behind-pr` or a
1151
- `behind-issue` Exclusion still not lifted names a ticket the file carries; the
1152
- open PRs come off `gh`. A ledger token it
1160
+ It reads the run itself, and nobody states a count. The In-flight count —
1161
+ every open PR that closes an issue off `gh`, plus every claimed ticket whose
1162
+ newest implementer is live or owed a replacement and has no such PR yet, off
1163
+ the ledger — sits beside the live review units (in-flight `review=` tokens
1164
+ plus unsettled `fix-pr-` ones), the merge bot, merge holds, tier mismatches
1165
+ and the drain marker, all off `.fleet/ledger.md`; the unclaimed heads and the
1166
+ supply come off `.fleet/shortlist.json`, which it refreshes itself when the
1167
+ unclaimed count is below the In-flight bound, when the file is missing or
1168
+ empty, when an Exclusion's premise has lifted, or when a branch-named
1169
+ `behind-pr` or a `behind-issue` Exclusion still not lifted names a ticket the
1170
+ file carries — never while the bound holds; the open PRs come off `gh`. A
1171
+ ledger token it
1153
1172
  cannot read, it refuses rather than guessing — a member counted live or gone on
1154
1173
  a guess is the over- or under-dispatch it exists to prevent — so correct that
1155
- row with `ledger.mjs row` and tick again. The caps default to 2 implementers
1156
- and 6 reviewers, and neither is a hard bound: pass `--implementer-cap` and
1157
- `--reviewer-cap` on every tick when `$ARGUMENTS` set them, and never otherwise.
1174
+ row with `ledger.mjs row` and tick again. The In-flight bound defaults to 5
1175
+ and is fixed for the run: pass `--in-flight` on every tick when `$ARGUMENTS`
1176
+ set it, and never otherwise.
1158
1177
 
1159
1178
  It prints `actual/target` and a named ACTION per role, with the whole **Queue
1160
1179
  depth** guard table applied in code. Act on each line as it reads:
@@ -1187,8 +1206,8 @@ depth** guard table applied in code. Act on each line as it reads:
1187
1206
  finisher-pr-<M>-<x> …`, then `ledger.mjs dispatch <M> finisher-pr-<M>-<x>`.
1188
1207
  Never add the label yourself. A head
1189
1208
  that moved is caught by the new finisher's duty 1 `past-pin` halt and the
1190
- re-review path that follows it. Finishers take no reviewer slot, so this
1191
- prints whatever the reviewer cap reads.
1209
+ re-review path that follows it. Finishers are not review units, so this
1210
+ prints whatever the unit count reads.
1192
1211
  - `ESCALATE unlabelled PR#<M> …` — a second finisher since the last `label-off=`
1193
1212
  settled `labelled` and the label is still not on: the tick dispatches no
1194
1213
  third. Not actionable; the maintainer's, through the cockpit's `unlabelled`
@@ -1213,7 +1232,9 @@ depth** guard table applied in code. Act on each line as it reads:
1213
1232
  actionable; it repeats while the PR reads CONFLICTING and clears once it
1214
1233
  stops, closes or merges.
1215
1234
  - `HOLD (…)` — the row is held and says why: draining, a tier mismatch, an
1216
- unchecked tier, a saturated review side, `--max-reviews` in flight, or every
1235
+ unchecked tier, the In-flight bound reached (`HOLD (in-flight <n>/<B>)` —
1236
+ nothing to do unless its detail names a replacement to dispatch, else a
1237
+ merge brings n below B), or every
1217
1238
  queued merge candidate held behind a lower PR or on a conflict hold no
1218
1239
  fix-applier has cleared. An unchecked tier is `tick --apply`'s to check, and
1219
1240
  the hold stays while the check writes no verdict (its `tier-ok=`, or
@@ -1304,19 +1325,23 @@ depth** guard table applied in code. Act on each line as it reads:
1304
1325
  `task` call, or settle the token `killed`. Advice the same way, folded as
1305
1326
  `…; NO-TRANSCRIPT <member> persists — …`. Both lines read the session
1306
1327
  directory this run's phase-0 receipt names, else `--session <dir>`; with
1307
- neither the tick skips them with one stderr line.
1328
+ neither the tick skips them with one stderr line. A heartbeat state file
1329
+ that exists but cannot be used — unreadable, not JSON, not a JSON object,
1330
+ or holding a `controller` that cannot be judged — holds no first-seen
1331
+ ages, and the tick never rewrites it, so every live token reads as first
1332
+ seen that tick and neither `CHECK-LIVENESS` nor `NO-TRANSCRIPT` can fire.
1333
+ The tick says so with one stderr line, `fleet-tick: CHECK-LIVENESS and
1334
+ NO-TRANSCRIPT not checked — <file> <cause>, so first-seen ages are
1335
+ unavailable`, naming only the checks that would have run that tick.
1308
1336
 
1309
1337
  **Tier guards under Pull.** The per-dispatch `tier-check.mjs --batch` is
1310
1338
  phase 2's own step, run by `tick --apply`: a mismatch it finds is the
1311
1339
  `HOLD (tier mismatch impl-<N>)` above, and a member it has no verdict on is
1312
1340
  the `HOLD (tier unchecked impl-<N>)`. Nothing else in the loop owns it.
1313
1341
 
1314
- **`--max-reviews <n>`** bounds how many reviews are in flight at once, inside
1315
- the reviewer cap. It defaults to the reviewer cap, and the reviewer slots it
1316
- leaves still serve fix-appliers. Leave it at its default: every review unit
1317
- already counts against the session's single `task.maxConcurrency` semaphore,
1318
- which queues at its ceiling rather than refusing, so reviews run up
1319
- to the reviewer cap without a tighter explicit bound.
1342
+ **`--in-flight <B>`** is the run's In-flight bound: leave it at its default
1343
+ unless `$ARGUMENTS` set it. omp's `task.maxConcurrency` is not the bound
1344
+ (**Phase 2** gives the reasons) — below 2·B+2 it is a notice, never a hold.
1320
1345
 
1321
1346
  **Why every wake.** A merge cascade is a firehose of merges, CI greens and
1322
1347
  rebases that holds your attention on the merge side while the implementer side
@@ -1752,19 +1777,16 @@ one-file rewrite trims too. An unknown profile widens to the full six, the safe
1752
1777
  direction, so a trim is never something to count on in advance — and a full six
1753
1778
  is never something to assume.
1754
1779
 
1755
- **The reviewer cap counts live review units.** A review in flight — a
1780
+ **Review units are counted, never capped.** A review in flight — a
1756
1781
  `review-pr-<pr#>` member still running — is one; each
1757
1782
  `fix-pr-<pr#>` is one; a finisher and a CI wait are zero; and a PR holds at most
1758
- one slot at a time. In-flight reviews are derived, never remembered: a row with
1783
+ one unit at a time. In-flight reviews are derived, never remembered: a row with
1759
1784
  `review=` and no `reviewed=` is one, which is why the token goes on before
1760
1785
  anything else. A review whose PR has left the open list is probed: when
1761
1786
  `gh pr view` reports that PR MERGED or CLOSED, the tick drops the review,
1762
1787
  since none runs against a finished PR, and a probe that
1763
- cannot answer keeps the slot. The defaults are 2 implementers and 6 reviewers,
1764
- and neither is a hard cap. The cap bounds units, not the agents a review fans
1765
- out to — 1 snapshot + up to 6 specialists + 2 refuters per critical/important finding — and
1766
- how many reviews may be in flight at once, inside it, is `--max-reviews`. The
1767
- slots a review does not hold still serve fix-appliers.
1788
+ cannot answer keeps the unit counted. A unit is not the agents a review fans
1789
+ out to — 1 snapshot + up to 6 specialists + 2 refuters per critical/important finding.
1768
1790
 
1769
1791
  It returns `{pr, head, resume, testEnvironment, dimensionsRun, dimensionsUnrun, cwdAudit, counts, snapshot, survived, refuted, unverified}` —
1770
1792
  the **digest** first, then the snapshot and the findings — and it lands as
@@ -1859,7 +1881,7 @@ token, then append `review=member:<that name>` after it, both in one
1859
1881
  call — `review` settles the dead launch in place, and refuses a new launch
1860
1882
  while the dead one still reads open, and the tick takes the last `review=`
1861
1883
  token on a row as the one in flight, so that order is what keeps the retry
1862
- counted against the cap. A
1884
+ counted as the live review unit. A
1863
1885
  runner member that is killed rather than failed follows **Failure
1864
1886
  handling** (fresh name, inherited state stated).
1865
1887
 
@@ -2743,8 +2765,8 @@ where the controller itself runs from.
2743
2765
  closing-issue test is what keeps it from widening: a PR that closes no issue
2744
2766
  — one you author yourself, for instance — is left unlabelled for the
2745
2767
  maintainer, so no member of the fleet will ever review it, and counting it
2746
- floors the backlog at a depth nothing in the run can drain — the implementer
2747
- gate then holds for the rest of the run against a queue of nothing.
2768
+ floors the backlog at a depth nothing in the run can drain — the reviewer
2769
+ row would then report a review owed for the rest of the run.
2748
2770
  GitHub's own linked-issue set decides that, not a keyword regex over the body.
2749
2771
  **That exemption is for a PR THIS run authors, never one a PRIOR run left
2750
2772
  open** — step 0 folds those into this run's review queue, so count one when
@@ -2754,23 +2776,35 @@ where the controller itself runs from.
2754
2776
  way — folding one in cannot reach the count. So the by-hand judgement and
2755
2777
  the script's output differ here, and such a PR's review is dispatched by
2756
2778
  hand.
2757
-
2758
- **Defaults: 2 implementers, 6 reviewers — no hard cap on either.** Reviewer
2759
- slots in use ≈ I·(T_review + 0.94·T_fix)/T_impl ≈ 1.95·I (medians since
2760
- 2026-08-07: T_impl 19.3 min, T_fix 21.0 min, T_review ~18
2761
- min, 0.94 fix-appliers per review), so at the default about four of the six
2762
- are busy, and an idle slot costs nothing. Re-derive it from the map's guard
2763
- once 20 or more PRs have merged under it, never from one run's rows.
2764
-
2765
- **The review-backlog gate is narrowed, and the merge-queue depth never gates.**
2766
- More PRs into a review-bound pipeline buy nothing, but the pipeline is
2767
- review-bound only when a PR is still owed its review after the tick's own
2768
- dispatches AND no reviewer slot is left for it — `HOLD (review side
2769
- saturated)`. A deep backlog with free slots is a `DISPATCH review` on the same
2770
- tick, never a reason to idle an implementer. A deep `ready-to-merge` queue is
2771
- *not* that signal at all: each PR rebases exactly once, when it becomes the
2772
- candidate, so producing more PRs adds no rebases-per-PR — it changes only
2773
- *when* a given PR is ready.
2779
+ - **In flight** — a ticket between its Claim and its PR's merge: an implementer
2780
+ live or owed a replacement on it, or an open PR closing it. A PR closing
2781
+ nothing is never in flight, and a ticket whose newest implementer settled
2782
+ `blocked` is not either. The tick's `n`; the implementer row's counts read it
2783
+ as `implementers=<i> prs=<p>`, n being i + p.
2784
+ - **In-flight bound** — the most tickets a run lets be In flight at once, fixed
2785
+ for the run, set by `/run-team`'s one argument. Reaching it holds every Pull
2786
+ until a merge brings the count below it; reviewers, finishers and the merge
2787
+ bot never slow for it. The tick's `B`.
2788
+
2789
+ **Default: In-flight bound 5, fixed for the run.** The level is set by load, not
2790
+ throughput: B caps live review units (≤ open PRs ≤ B), and the review side is
2791
+ about 84 % of cache-write tokens, fanning out to 1 snapshot + up to 6
2792
+ specialists + 2 refuters per finding. 5 keeps worst-case review concurrency
2793
+ below the former reviewer count of 6 and sits near the measured mean In flight
2794
+ of 5.6. On the means that allows ≈ 1.7 merges per open-time hour against 1.89
2795
+ measured, so the default does not rest on throughput headroom and the guard's
2796
+ throughput test may trip on it; the merge gate saturates near 10–11, so
2797
+ raising B past that buys nothing. 8 was rejected: peak review concurrency above
2798
+ the former reviewer count, for a throughput gain the backlog does not show it
2799
+ needs. Re-derive it from the map's guard once 20 or more PRs have merged under
2800
+ it, never from one run's rows.
2801
+
2802
+ **The review backlog never gates, and the merge-queue depth is still no
2803
+ signal.** The only gate on a Pull is the In-flight count. A deep backlog is a
2804
+ `DISPATCH review` on the same tick, never a reason to idle an implementer. A
2805
+ deep `ready-to-merge` queue adds no rebases per PR — each PR rebases exactly
2806
+ once, when it becomes the candidate — and those PRs count as In flight because
2807
+ they sit between Claim and merge, not because the queue is deep.
2774
2808
 
2775
2809
  **Reconcile, do not wait for an event.** "A slot is free and the shortlist is
2776
2810
  non-empty" is a *level* condition — re-derive the deficit on **every** tick,
@@ -2793,21 +2827,33 @@ never as a second, hand-run copy of it.
2793
2827
  | shortlist (unclaimed) | implementer row prints |
2794
2828
  |---|---|
2795
2829
  | ≥ 1 | `PULL #N …`, one head per free slot — a Pull each (phase 1) |
2796
- | below the cap, missing or empty | the tick refreshes first — `REFRESHED shortlist: n entries; k lifted` — and Pulls from what it found |
2830
+ | below the In-flight bound, missing or empty | the tick refreshes first — `REFRESHED shortlist: n entries; k lifted` — and Pulls from what it found |
2797
2831
  | 0 after that refresh | `SUGGEST /triage, hold idle` |
2798
2832
 
2799
2833
  Whatever the row prints, a `specs-dropped=#<N> (…)` at the end of its counts
2800
2834
  names the tickets the to-spec filter kept out of the shortlist — specs
2801
2835
  awaiting to-tickets, so an empty shortlist carrying one is not "no work".
2802
2836
 
2837
+ The refresh runs at unclaimed < B and, with every other refresh trigger, never
2838
+ while the bound holds: a refresh then cannot feed a Pull, and the first tick
2839
+ back under the bound refreshes and Pulls in the same tick.
2840
+
2803
2841
  Four holds outrank every row: `HOLD (draining)` once `ledger.mjs drain` has
2804
2842
  recorded the drain, `HOLD (tier mismatch impl-<N>)` until a replacement is
2805
2843
  dispatched at the right tier, `HOLD (tier unchecked impl-<N>)` until
2806
2844
  `tier-check.mjs` has written its verdict on the newest implementer —
2807
2845
  `tier-ok=`, `tier-mismatch=` or `tier-unverifiable=` — and
2808
- `HOLD (review side saturated)` when a PR is still owed its review and no
2809
- reviewer slot is left for it — refreshing to enable a Pull you are holding
2810
- buys nothing.
2846
+ `HOLD (in-flight <n>/<B>)` when n tickets are between Claim and merge and
2847
+ n ≥ B — refreshing to enable a Pull you are holding buys nothing.
2848
+
2849
+ `HOLD (in-flight <n>/<B>)` ranks last of the four: the other three print in
2850
+ its place. Its detail is the implementer row's counts, `implementers=<i>
2851
+ prs=<p> unclaimed=<k> supply=<s>`. It is quiet — a merge brings n below B and
2852
+ the next tick Pulls — except for a ticket whose newest implementer settled
2853
+ `killed` or `tier-mismatch`: it counts as In flight with no PR that could
2854
+ merge, so the row asks for the replacement's dispatch and names it in the
2855
+ detail. The reviewer row reads `<units>/<B>`, its live review units against
2856
+ the same bound, and never holds on it.
2811
2857
 
2812
2858
  A main checkout that is not `clean` against its Phase 0 baseline outranks all
2813
2859
  of them, and every dispatching row besides: `HOLD (main checkout dirty)`,
@@ -2821,9 +2867,9 @@ A starved implementer queue never stalls the review or merge side.
2821
2867
 
2822
2868
  ## Invariants
2823
2869
 
2824
- - Implementers and review units at their caps (default 2 and 6, no hard cap on
2825
- either), ≤ 1 merge bot. Caps bound *members* and review units, not live
2826
- agents — members fan out and their children consume slots you never dispatched.
2870
+ - In-flight tickets at most the bound (default 5), ≤ 1 merge bot. The bound
2871
+ counts tickets, not live agents — members fan out and their children consume
2872
+ slots you never dispatched.
2827
2873
  - A grandchild surfaces as its own task-notification. An unrecognized task-id is
2828
2874
  not a member reporting done.
2829
2875
  - A reviewer never reviews a PR it implemented.
@@ -3049,7 +3095,7 @@ Plan it as a PR the run's own merge queue lands, never as an edit-and-continue.
3049
3095
  |---|---|
3050
3096
  | SHA not on expected branch | Flag, do not enqueue, report |
3051
3097
  | Implementer bails before implementing | → `needs-triage` if under-specified, `ready-for-human` if it needs human hands or leaves a fork open; drop `in-progress`, comment the cause, release the claim, refill (phase 3) |
3052
- | Implementer blocked or ambiguous *mid-implementation* | Free the slot, leave `in-progress`, report — the row above is the pre-code bail, not this one |
3098
+ | Implementer blocked or ambiguous *mid-implementation* | Free the slot, `ledger.mjs settle impl-<N> blocked`, leave `in-progress`, report — the ticket is not In flight and waits for a human; the row above is the pre-code bail, not this one |
3053
3099
  | `review-pr` workflow throws or returns no tree | Retry once under the next letter (`review-pr-<pr#>-b`); still failing, report and leave the PR at review-due. Never enqueue the PR as reviewed — the workflow is not a member, so no other row here covers it |
3054
3100
  | Reviewer, fix-applier or red-check fixer cannot reach green | Report, leave the PR unlabeled, free the slot — a fix-applier or red-check fixer settles `failed` |
3055
3101
  | Merge bot hits the hold rule | Report `held-behind-#<lower>`, PR stays queued |
@@ -3164,7 +3210,7 @@ live count from it, so nobody states one. Write neither by hand:
3164
3210
  itself refuses.
3165
3211
  - **`ledger.mjs settle <member> <outcome>`** — rewrites the token to
3166
3212
  `<member>=<outcome>` in both places. Outcomes: `impl-N` = `PR#M | bailed |
3167
- released | killed | tier-mismatch`; `fix-pr-M` = `applied:<head> | no-op |
3213
+ released | killed | tier-mismatch | blocked`; `fix-pr-M` = `applied:<head> | no-op |
3168
3214
  failed | killed`; `finisher-pr-M` = `labelled | failed | killed |
3169
3215
  halted:<cause>`, `<cause>` one of `live-editor | rebase | past-pin |
3170
3216
  unreadable | missing | absent | other` (**Resolving a finisher halt**);
@@ -3246,7 +3292,7 @@ carry yet (`review-pr-<n>-b`, `-c`, …) for every later one,
3246
3292
  settled dead as `…=failed`, then `reviewed=<head>:<survived>/<refuted>/<unverified>:<run>`
3247
3293
  when the result lands, `<run>` the review's `run-XXXXXXXX` run root under
3248
3294
  `<scratch>/pr<n>/`, which holds its `review.json`. A row with `review=` and no `reviewed=` is a review in
3249
- flight, and the tick counts it against the reviewer cap unless gh reports its PR
3295
+ flight, and the tick counts it as a live review unit unless gh reports its PR
3250
3296
  MERGED or CLOSED. `ci=<run-id>:<attempt>:<conclusion>`
3251
3297
  and `held-behind:#<lower>` are row tokens the same way (Phase 3), and so is
3252
3298
  `conflict-hold:#<pr>` — written by the merge bot itself (`run-merge-bot.md`