@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 +1 -1
- package/scripts/fleet-tick.mjs +15 -0
- package/scripts/phase0-receipt.mjs +1 -2
- package/scripts/phase0.mjs +8 -11
- package/skills/run-team/SKILL.md +120 -74
package/package.json
CHANGED
package/scripts/fleet-tick.mjs
CHANGED
|
@@ -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.
|
|
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;
|
package/scripts/phase0.mjs
CHANGED
|
@@ -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> [--
|
|
5
|
-
// [--
|
|
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)
|
|
37
|
-
//
|
|
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,
|
|
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. `
|
|
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", "
|
|
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,
|
|
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" };
|
package/skills/run-team/SKILL.md
CHANGED
|
@@ -1,15 +1,16 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: run-team
|
|
3
|
-
description: Run an agent fleet — implementers, reviewers
|
|
4
|
-
argument-hint: "[
|
|
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` = `[
|
|
12
|
-
|
|
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 `--
|
|
262
|
-
|
|
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
|
|
356
|
-
|
|
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
|
|
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 `
|
|
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
|
|
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
|
|
997
|
-
|
|
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 [--
|
|
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.
|
|
1145
|
-
|
|
1146
|
-
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1152
|
-
|
|
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
|
|
1156
|
-
and
|
|
1157
|
-
|
|
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
|
|
1191
|
-
prints whatever the
|
|
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,
|
|
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
|
-
**`--
|
|
1315
|
-
|
|
1316
|
-
|
|
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
|
-
**
|
|
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
|
|
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
|
|
1764
|
-
|
|
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
|
|
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
|
|
2747
|
-
|
|
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
|
-
|
|
2759
|
-
|
|
2760
|
-
|
|
2761
|
-
|
|
2762
|
-
|
|
2763
|
-
|
|
2764
|
-
|
|
2765
|
-
|
|
2766
|
-
|
|
2767
|
-
|
|
2768
|
-
|
|
2769
|
-
|
|
2770
|
-
|
|
2771
|
-
|
|
2772
|
-
|
|
2773
|
-
|
|
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
|
|
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 (
|
|
2809
|
-
|
|
2810
|
-
|
|
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
|
-
-
|
|
2825
|
-
|
|
2826
|
-
|
|
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
|
|
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`
|