@feigi/fleet-ctl 3.56.0 → 3.57.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.56.0",
3
+ "version": "3.57.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": {
@@ -47,6 +47,16 @@
47
47
  // never when. Pruned to the live set on every tick, so a settled
48
48
  // member's stamp does not outlive it. Carried, never written, by
49
49
  // the heartbeat and by ledger.mjs.
50
+ // applied fleet-tick only, and only under --apply. {run, reapAfter}: the
51
+ // merge-bot numbers whose `merge-bot-<n>=done` the tick has already
52
+ // run reap.sh and reclaim-scratch.mjs after, and the controller
53
+ // record's `at` they belong to. Written only under a record: with
54
+ // none, nothing tells one run from the next. Merge-bot numbering
55
+ // restarts at 1 in a run that carries no bot forward, and this
56
+ // file outlives the rotation, so a list whose `run` is not the
57
+ // current record's `at` is the previous run's and names nothing in
58
+ // this one. Carried, never written, by the heartbeat and by
59
+ // ledger.mjs.
50
60
  //
51
61
  // One writer per key. A key two scripts wrote would need locking to be
52
62
  // correct, and none of them is in a position to hold one. That holds per key,
@@ -119,7 +129,7 @@ export function readState(path, name) {
119
129
  // to judge and nothing to report. A zeroed mark would date the beat to the
120
130
  // epoch and read as decades overdue on a run that has simply not started
121
131
  // one — the cry-wolf direction this key must never fail in.
122
- const fresh = { quiet: 0, elapsed: 0, digest: "", beat: null, ticked: null, acted: null, controller: null, seen: {}, rest: {} };
132
+ const fresh = { quiet: 0, elapsed: 0, digest: "", beat: null, ticked: null, acted: null, controller: null, seen: {}, applied: null, rest: {} };
123
133
  // The same state, flagged: the file EXISTS and could not be used. A caller
124
134
  // that acts on the absence of a record — ledger.mjs rotate — must tell this
125
135
  // from `fresh`, which is a run that has simply not written one yet. The
@@ -227,7 +237,18 @@ export function readState(path, name) {
227
237
  for (const [member, at] of Object.entries(v)) if (Number.isInteger(at) && at > 0) out[member] = at;
228
238
  return out;
229
239
  };
230
- const { quiet, elapsed, digest, beat, ticked, acted, controller, seen, ...rest } = parsed;
240
+ // `applied` is validated as a unit for the controller record's reason: a
241
+ // list is only read against the run it names, so one whose `run` is not a
242
+ // positive integer belongs to no run and reads as absent. Absent is the
243
+ // safe direction: the duties it records are idempotent, and the next
244
+ // --apply tick runs them again. A junk entry in the list costs that entry
245
+ // alone.
246
+ const done = (v) => {
247
+ if (!isRecord(v) || !Array.isArray(v.reapAfter)) return null;
248
+ if (!(Number.isInteger(v.run) && v.run > 0)) return null;
249
+ return { run: v.run, reapAfter: v.reapAfter.filter((n) => Number.isInteger(n) && n > 0) };
250
+ };
251
+ const { quiet, elapsed, digest, beat, ticked, acted, controller, seen, applied, ...rest } = parsed;
231
252
  // A controller key that ctl() rejects is a record someone wrote and nobody
232
253
  // can judge, not the absence of one — announced like the other degraded
233
254
  // causes, and flagged.
@@ -245,6 +266,7 @@ export function readState(path, name) {
245
266
  acted: tick(acted),
246
267
  controller: record,
247
268
  seen: stamps(seen),
269
+ applied: done(applied),
248
270
  rest,
249
271
  };
250
272
  }
@@ -301,6 +323,9 @@ export function writeState(path, name, prev, patch) {
301
323
  // `seen` is fleet-tick's, and the heartbeat and ledger.mjs write this file
302
324
  // too: carried the same way, so neither erases the ages the tick keeps.
303
325
  ...(prev.seen && Object.keys(prev.seen).length > 0 ? { seen: prev.seen } : {}),
326
+ // `applied` too: a heartbeat write that dropped it would have the next
327
+ // --apply tick reap again after every merge pass it already reaped after.
328
+ ...(prev.applied ? { applied: prev.applied } : {}),
304
329
  ...patch,
305
330
  };
306
331
  const tmp = `${path}.${process.pid}.tmp`;
@@ -207,9 +207,10 @@ function implementers(s, left) {
207
207
  }
208
208
  // Held until tier-check.mjs has run on the newest implementer and written
209
209
  // its verdict to the ledger — a Pull on top of an unchecked
210
- // dispatch repeats whatever it got wrong. Running the check is the
211
- // controller's own step, so it is asked to act, with the command in the
212
- // detail.
210
+ // dispatch repeats whatever it got wrong. `--apply` runs the check itself
211
+ // before this row is read; the row is the controller's to act on when the
212
+ // tick ran without `--apply`, or the check wrote no verdict, so it asks to
213
+ // act, with the command in the detail.
213
214
  if (s.tierUnchecked.length) {
214
215
  return row(`HOLD (tier unchecked ${s.tierUnchecked.join(" ")})`, { acts: true, extra: tierCheckStep(s.tierUnchecked, s.phase0?.session) });
215
216
  }
@@ -886,6 +887,9 @@ export function deriveRun({ rows, dispatched, drain }, prs, closed = new Set(),
886
887
  implLive: live("impl"),
887
888
  fixLive: live("fix-pr"),
888
889
  mergeBotLive,
890
+ // The number of every merge bot settled `done`: each is a merge pass
891
+ // `--apply` reaps and reclaims after, once (reapDue).
892
+ mergeBotDone: all.filter((m) => m.family === "merge-bot" && m.outcome === "done").map((m) => m.number).sort(asc),
889
893
  reviewsLive: liveReviews.length,
890
894
  // The in-flight reviews of PRs the open list does not carry: the ones
891
895
  // `finished` could retire, so the caller asks gh about these and no others.
@@ -1073,20 +1077,77 @@ export function livenessLines({ live, seen, thresholds, now }) {
1073
1077
  return out;
1074
1078
  }
1075
1079
 
1080
+ // --apply's pure half. The merge-bot numbers `applied.reapAfter` names for
1081
+ // THIS run: none when its `run` is not the controller record's `at`, since
1082
+ // merge-bot numbering restarts with a run and the state file outlives it
1083
+ // (fleet-state.mjs's `applied`). `controllerAt` is null with no record, and
1084
+ // with no record nothing tells this run from the one before it: a list then
1085
+ // names nothing, and the sweeps run again on the next tick.
1086
+ export function reapedAfter(applied, controllerAt) {
1087
+ return applied !== null && controllerAt != null && applied.run === controllerAt ? applied.reapAfter : [];
1088
+ }
1089
+
1090
+ // The merge passes owed their reap and reclaim: every merge bot settled
1091
+ // `done` that reapedAfter() does not name.
1092
+ export function reapDue(done, applied, controllerAt) {
1093
+ const ran = new Set(reapedAfter(applied, controllerAt));
1094
+ return done.filter((n) => !ran.has(n));
1095
+ }
1096
+
1097
+ // The implementers the tick would print `HOLD (tier unchecked …)` for: read
1098
+ // off the rows reconcile() computed, so whatever outranks that hold — the
1099
+ // drain, a mismatch, phase 0, the main checkout — outranks the check too.
1100
+ export function tierCheckDue(rows, unchecked) {
1101
+ return rows.some((r) => r.role === "implementers" && r.action.startsWith("HOLD (tier unchecked ")) ? unchecked : [];
1102
+ }
1103
+
1104
+ // The one JSON line a receipt-printing script ends on, or null.
1105
+ function receiptOf(stdout) {
1106
+ try {
1107
+ const r = JSON.parse(String(stdout).trim().split("\n").at(-1));
1108
+ return r !== null && typeof r === "object" ? r : null;
1109
+ } catch {
1110
+ return null;
1111
+ }
1112
+ }
1113
+
1114
+ // reap.sh's receipt as `reaped <k>, kept <m>, worktreesRemoved <w>`, or null
1115
+ // for a stdout that carries none. A receipt with warnings adds `warnings
1116
+ // <n>: <first note>`: reap.sh exits 0 with them, and this line is the only
1117
+ // place an unattended tick can say so.
1118
+ export function reapSummary(stdout) {
1119
+ const r = receiptOf(stdout);
1120
+ if (r === null || ![r.reaped, r.kept, r.worktreesRemoved].every(Array.isArray)) return null;
1121
+ const warned = Array.isArray(r.warnings) ? r.warnings : [];
1122
+ const first = warned[0]?.note;
1123
+ return `reaped ${r.reaped.length}, kept ${r.kept.length}, worktreesRemoved ${r.worktreesRemoved.length}`
1124
+ + (warned.length ? `, warnings ${warned.length}${typeof first === "string" ? `: ${first}` : ""}` : "");
1125
+ }
1126
+
1127
+ // reclaim-scratch.mjs's receipt as `removed <k>, kept <m>, failed <f>`, or
1128
+ // null. A removal that failed is in the receipt and exits 0: it is reported
1129
+ // here, and the pass still counts as reclaimed after.
1130
+ export function reclaimSummary(stdout) {
1131
+ const r = receiptOf(stdout);
1132
+ if (r === null || ![r.removed, r.kept, r.failed].every(Array.isArray)) return null;
1133
+ return `removed ${r.removed.length}, kept ${r.kept.length}, failed ${r.failed.length}`;
1134
+ }
1135
+
1076
1136
  // --------------------------------------------------------------------------
1077
1137
  // I/O. Everything below runs only as a CLI — importing this file must never
1078
1138
  // parse argv or touch the network, or the pure half stops being unit-testable.
1079
1139
 
1080
1140
  import { execFileSync, spawnSync } from "node:child_process";
1081
1141
  import { createHash } from "node:crypto";
1082
- import { readFileSync } from "node:fs";
1142
+ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
1143
+ import { tmpdir } from "node:os";
1083
1144
  import { dirname, join } from "node:path";
1084
1145
  import { fileURLToPath } from "node:url";
1085
1146
  import { isCLI } from "./is-cli.mjs";
1086
1147
  import { parseArgs } from "node:util";
1087
1148
  import { makeDie, isDigits } from "./arg.mjs";
1088
1149
  import { gitEnv } from "./git-env.mjs";
1089
- import { fleetFile, FleetDirUnresolvable } from "./fleet-dir.mjs";
1150
+ import { fleetFile, FleetDirUnresolvable, scratchRoot } from "./fleet-dir.mjs";
1090
1151
  import { statePath, readState, writeState, assessBeat, isStalled, isReported, stallReport, stallOwner } from "./fleet-state.mjs";
1091
1152
  import { checkMainCheckout, describe } from "./main-checkout.mjs";
1092
1153
  import { readRunReceipt, phase0Gate } from "./phase0-receipt.mjs";
@@ -1149,6 +1210,13 @@ const OPTIONS = {
1149
1210
  // unattended night affordable. Opt-in because folding is wrong on an edge:
1150
1211
  // a controller that just acted needs the full rows.
1151
1212
  "fold-unchanged": { type: "boolean", default: false },
1213
+ // `--apply` runs the idempotent follow-ups whose trigger the ledger and the
1214
+ // state file show, before the rows: reap.sh and reclaim-scratch.mjs after
1215
+ // every merge pass settled `done`, and tier-check.mjs on every implementer
1216
+ // the tick would hold as unchecked. It never dispatches, never settles a
1217
+ // member and writes no ledger row but through those scripts. Without it the
1218
+ // tick is read-only.
1219
+ apply: { type: "boolean", default: false },
1152
1220
  // Path override, for tests. An empty value cannot be told from an absent one
1153
1221
  // under parseArgs, and no path is legitimately empty, so empty resolves to
1154
1222
  // the default.
@@ -1184,7 +1252,7 @@ function options() {
1184
1252
  return {
1185
1253
  implCap: positive("implementer-cap"), reviewerCap,
1186
1254
  maxReviews: values["max-reviews"] === undefined ? reviewerCap : positive("max-reviews"),
1187
- fold: values["fold-unchanged"], state: values.state || statePath(NAME),
1255
+ fold: values["fold-unchanged"], apply: values.apply, state: values.state || statePath(NAME),
1188
1256
  liveness: Object.fromEntries(Object.entries(LIVENESS_FLAGS).map(([family, flag]) => [family, positive(flag)])),
1189
1257
  };
1190
1258
  }
@@ -1411,6 +1479,94 @@ function refresh() {
1411
1479
  return { ok: true, ...p };
1412
1480
  }
1413
1481
 
1482
+ // A sibling script --apply runs, the way refresh() runs shortlist.mjs: stdout
1483
+ // kept for its receipt, stderr captured so only a failure's last line rides
1484
+ // along. A `.mjs` runs under this node, reap.sh by its own shebang.
1485
+ function runSibling(file, args) {
1486
+ const opts = { encoding: "utf8", maxBuffer: MAX_BUFFER, stdio: ["ignore", "pipe", "pipe"] };
1487
+ return file.endsWith(".mjs")
1488
+ ? spawnSync(process.execPath, [join(SCRIPT_DIR, file), ...args], opts)
1489
+ : spawnSync(join(SCRIPT_DIR, file), args, opts);
1490
+ }
1491
+
1492
+ // One duty's line: `APPLIED <label>: <receipt summary>`, or `APPLY FAILED
1493
+ // <duty>: <why>` for a script that did not exit 0 or printed no receipt.
1494
+ // True when it applied.
1495
+ function reportDuty(r, { label, duty, what, summarise }) {
1496
+ const ran = !r.error && r.status === 0;
1497
+ const summary = ran ? summarise(r.stdout) : null;
1498
+ console.log(summary !== null ? `APPLIED ${label}: ${summary}`
1499
+ : `APPLY FAILED ${duty}: ${ran ? `${what} printed no receipt` : failure(r, what)}`);
1500
+ return summary !== null;
1501
+ }
1502
+
1503
+ // Reap, then reclaim, after the merge passes in `due` — once however many
1504
+ // there are, since both sweep the whole repository and scratch root rather
1505
+ // than one pass's share. Reclaim runs whether or not reap did: neither reads
1506
+ // the other's result. True only when both applied, the one case `due` is
1507
+ // recorded as reaped after; otherwise the next --apply tick runs both again.
1508
+ function applyReap(due) {
1509
+ const label = `reap after ${due.map((n) => `merge-bot-${n}`).join(" ")}`;
1510
+ const reaped = reportDuty(runSibling("reap.sh", ["--apply"]), { label, duty: "reap", what: "reap.sh", summarise: reapSummary });
1511
+ let root;
1512
+ try {
1513
+ root = scratchRoot();
1514
+ } catch (e) {
1515
+ if (!(e instanceof FleetDirUnresolvable)) throw e;
1516
+ console.log(`APPLY FAILED reclaim: ${e.message}`);
1517
+ return false;
1518
+ }
1519
+ const reclaimed = reportDuty(runSibling("reclaim-scratch.mjs", ["--root", root, "--apply"]),
1520
+ { label: "reclaim", duty: "reclaim", what: "reclaim-scratch.mjs", summarise: reclaimSummary });
1521
+ return reaped && reclaimed;
1522
+ }
1523
+
1524
+ // tier-check.mjs's verdict by its exit status, each one a token the check
1525
+ // writes on the ledger itself. Exit 2 writes nothing. Exit 1 is the check's
1526
+ // mismatch and also what node exits with on a throw, so it stands as a
1527
+ // verdict only once the ledger carries it.
1528
+ const TIER_VERDICTS = new Map([[0, "tier-ok"], [1, "tier-mismatch"], [3, "tier-unverifiable"]]);
1529
+
1530
+ // Whether the ledger holds tier-check.mjs's mismatch for `member`: the token
1531
+ // on a row, or the member itself settled `tier-mismatch`.
1532
+ function mismatchOnLedger(member) {
1533
+ const { rows, dispatched } = readLedger();
1534
+ return [...rows, ...dispatched].some((text) => text.split(/\s+/)
1535
+ .some((tok) => tok === `${member}=tier-mismatch` || tok.startsWith(`tier-mismatch=${member}:`)));
1536
+ }
1537
+
1538
+ // tier-check.mjs on each member, a batch of one apiece in a temporary file,
1539
+ // `session` the phase-0 receipt's — left out when the receipt records none,
1540
+ // which the check refuses by name. True when any check wrote a verdict, so
1541
+ // the caller reads the ledger it changed again.
1542
+ function applyTierChecks(members, session) {
1543
+ let wrote = false;
1544
+ for (const member of members) {
1545
+ const dir = mkdtempSync(join(tmpdir(), "fleet-tick-tier-"));
1546
+ let r;
1547
+ try {
1548
+ const batch = join(dir, "batch.json");
1549
+ writeFileSync(batch, JSON.stringify([session === null ? { member } : { member, session }]));
1550
+ r = runSibling("tier-check.mjs", ["--batch", batch]);
1551
+ } finally {
1552
+ rmSync(dir, { recursive: true, force: true });
1553
+ }
1554
+ const verdict = r.error ? undefined : TIER_VERDICTS.get(r.status);
1555
+ if (verdict !== undefined && (r.status !== 1 || mismatchOnLedger(member))) {
1556
+ wrote = true;
1557
+ console.log(`APPLIED tier-check ${member}: ${verdict}`);
1558
+ } else if (!r.error && r.status === 2) {
1559
+ // No verdict — most often a live member with no transcript yet — so
1560
+ // the hold stands, and the check's own line says why.
1561
+ const last = String(r.stderr ?? "").trim().split("\n").at(-1);
1562
+ console.log(`APPLIED tier-check ${member}: no verdict${last ? ` — ${last}` : ""}`);
1563
+ } else {
1564
+ console.log(`APPLY FAILED tier-check ${member}: ${failure(r, "tier-check.mjs")}`);
1565
+ }
1566
+ }
1567
+ return wrote;
1568
+ }
1569
+
1414
1570
  // How many tickets a dead run stranded. `in-progress` is the claim label
1415
1571
  // claim-ticket.sh adds and candidates.mjs's query EXCLUDES — which is why a
1416
1572
  // stranded ticket is invisible to the next run's scans, and why this count is
@@ -1450,8 +1606,23 @@ function controllerState(controller) {
1450
1606
  }
1451
1607
  }
1452
1608
 
1609
+ // The run off the ledger, with the closed tickets and finished reviews gh
1610
+ // says the ledger cannot. A ledger it cannot read refuses the tick.
1611
+ function readRun(prs) {
1612
+ try {
1613
+ const ledger = readLedger();
1614
+ const run = deriveRun(ledger, prs);
1615
+ const closed = closedTickets(run.tierMismatch);
1616
+ const finished = finishedReviewPrs(run.reviewsOffList);
1617
+ return closed.size || finished.size ? deriveRun(ledger, prs, closed, finished) : run;
1618
+ } catch (e) {
1619
+ if (e instanceof LedgerError) die(e.message);
1620
+ throw e;
1621
+ }
1622
+ }
1623
+
1453
1624
  function main() {
1454
- const { fold, state: path, liveness, ...caps } = options();
1625
+ const { fold, apply, state: path, liveness, ...caps } = options();
1455
1626
  const listPath = shortlistPath();
1456
1627
  const current = readShortlist(listPath);
1457
1628
  // Beside the shortlist, off the same git probe rather than a second one.
@@ -1485,18 +1656,49 @@ function main() {
1485
1656
  }
1486
1657
 
1487
1658
  // Every read happens before anything prints: a partial tick is worse than no
1488
- // tick, because half a reconcile still reads like a reconcile.
1659
+ // tick, because half a reconcile still reads like a reconcile. The APPLIED
1660
+ // lines are the exception, printed as each duty runs: they say what was
1661
+ // done, which is true whether or not the reconcile after them lands.
1489
1662
  const prs = openPrs();
1490
- let run;
1491
- try {
1492
- const ledger = readLedger();
1493
- run = deriveRun(ledger, prs);
1494
- const closed = closedTickets(run.tierMismatch);
1495
- const finished = finishedReviewPrs(run.reviewsOffList);
1496
- if (closed.size || finished.size) run = deriveRun(ledger, prs, closed, finished);
1497
- } catch (e) {
1498
- if (e instanceof LedgerError) die(e.message);
1499
- throw e;
1663
+ let run = readRun(prs);
1664
+
1665
+ // The main checkout against the run's baseline, on every tick — the
1666
+ // backstop for what member-write-guard cannot see. Never a refusal of the tick:
1667
+ // every answer but `clean` is a hold on the dispatching rows plus one line
1668
+ // saying why, so the rest of the run keeps reporting.
1669
+ const mainCheckout = checkMainCheckout();
1670
+ // This run's phase 0, off its receipt: unfinished holds the same rows the
1671
+ // main checkout does, and never refuses the tick either. Judged against
1672
+ // the controller record this tick started from, and against whether that
1673
+ // record's process is still there: a finished receipt of the run before
1674
+ // carries the same `at` until this run's rotation writes the next.
1675
+ const receipt = readRunReceipt();
1676
+ const phase0 = phase0Gate(receipt.read, {
1677
+ path: receipt.path, controllerAt: controller?.at, controller: controllerState(controller),
1678
+ });
1679
+
1680
+ if (apply) {
1681
+ // Reap and reclaim after every merge pass settled `done` since the last
1682
+ // time they ran. Recorded only once both applied, on a fresh read of the
1683
+ // state file so nothing the heartbeat wrote meanwhile is reverted, never
1684
+ // onto a file that could not be read, and never with no controller
1685
+ // record: nothing could tell a list recorded then from the next run's.
1686
+ const run0 = controller?.at ?? null;
1687
+ const due = reapDue(run.mergeBotDone, priorState.applied, run0);
1688
+ if (due.length && applyReap(due) && run0 !== null) {
1689
+ const now = readState(path, NAME);
1690
+ if (!now.degraded) {
1691
+ writeState(path, NAME, now, { applied: { run: run0, reapAfter: [...new Set([...reapedAfter(now.applied, run0), ...due])] } });
1692
+ }
1693
+ }
1694
+ // The tier check, on exactly the members the implementer row would hold
1695
+ // as unchecked — that row reads the same before the refresh as after it.
1696
+ // A verdict written changes the ledger, so the run is read again.
1697
+ const unchecked = tierCheckDue(reconcile({
1698
+ ...caps, ...run, heads: unclaimed(current.entries, run), supply: current.scanned, dropped: current.dropped,
1699
+ shortlistStatus: current.status, refresh: null, mainCheckout, phase0, router,
1700
+ }), run.tierUnchecked);
1701
+ if (unchecked.length && applyTierChecks(unchecked, phase0.session)) run = readRun(prs);
1500
1702
  }
1501
1703
 
1502
1704
  // Pull from the current file first; refresh when it is short, absent, an
@@ -1528,21 +1730,6 @@ function main() {
1528
1730
  }
1529
1731
  }
1530
1732
 
1531
- // The main checkout against the run's baseline, on every tick — the
1532
- // backstop for what member-write-guard cannot see. Never a refusal of the tick:
1533
- // every answer but `clean` is a hold on the dispatching rows plus one line
1534
- // saying why, so the rest of the run keeps reporting.
1535
- const mainCheckout = checkMainCheckout();
1536
- // This run's phase 0, off its receipt: unfinished holds the same rows the
1537
- // main checkout does, and never refuses the tick either. Judged against
1538
- // the controller record this tick started from, and against whether that
1539
- // record's process is still there: a finished receipt of the run before
1540
- // carries the same `at` until this run's rotation writes the next.
1541
- const receipt = readRunReceipt();
1542
- const phase0 = phase0Gate(receipt.read, {
1543
- path: receipt.path, controllerAt: controller?.at, controller: controllerState(controller),
1544
- });
1545
-
1546
1733
  const rows = reconcile({
1547
1734
  ...caps, ...run, heads, supply, dropped, shortlistStatus: current.status, refresh: fresh, mainCheckout, phase0, router,
1548
1735
  });
@@ -1224,9 +1224,12 @@ that the tier it resolves to is now declared and pinned rather than inherited by
1224
1224
  accident. Keep `name: impl-<N>`: the name is what makes a member, and both the
1225
1225
  spend classifier and `member-outcomes.mjs` read it.
1226
1226
 
1227
- **After every Pull's dispatch, run the tier check — a scripted step, never a
1228
- prose reminder.** `~/.fleet/bin/fleet-run tier-check.mjs --batch <path-to-batch.json>`
1229
- judges the implementer just dispatched on the ledger's terms. The definition it
1227
+ **After every Pull's dispatch, the tier check runs — a scripted step, never a
1228
+ prose reminder.** `tick --apply` runs it itself, a batch of one apiece, on every
1229
+ implementer it would print `HOLD (tier unchecked impl-<N>)` for, `session` off
1230
+ the phase-0 receipt, and prints `APPLIED tier-check impl-<N>: <verdict>`. By
1231
+ hand it is `~/.fleet/bin/fleet-run tier-check.mjs --batch <path-to-batch.json>`,
1232
+ which judges the implementer just dispatched on the ledger's terms. The definition it
1230
1233
  should have run under comes off its ticket row's `tier=` token: none means the
1231
1234
  policy cell, `fleet-implementer-slow-high`; `tier=<cell>` means
1232
1235
  `fleet-implementer-<cell>` — the same mapping `ledger.mjs dispatch` prints its
@@ -1262,8 +1265,9 @@ verdicts, whether that member is still running or already settled `bailed`,
1262
1265
  one. Only the newest member counts, so a replacement (`impl-<N>-b`) is what
1263
1266
  clears a mismatch — and is then owed its own check. A mismatch on a ticket
1264
1267
  whose issue is already CLOSED holds nothing: the tick probes that issue and
1265
- drops it, since there is nothing left to replace. The tick never reads a
1266
- transcript: clear an unchecked hold by running the check on that member. A
1268
+ drops it, since there is nothing left to replace. The tick reads no transcript
1269
+ itself: `tick --apply` runs the check, and an unchecked hold it leaves is
1270
+ cleared by running the check on that member by hand. A
1267
1271
  settled member's check works only when its transcript exists;
1268
1272
  without one, the verdict is `tier-unverifiable` for a member settled `killed`
1269
1273
  or `released`, and exit 2 naming the wrong session for any other. Clear a
@@ -1724,7 +1728,7 @@ ticket's line — never a hand edit.
1724
1728
  | Finisher report (failed / killed) | `ledger.mjs settle finisher-pr-<M>=failed` for a finisher that crashed or gave up, `=killed` for one that was killed; no label, and the tick prints no dispatch for it. The cockpit flags the PR `finisher:failed` / `finisher:killed` at severity 4 and you resolve it by hand (**Resolving a finisher that died**, below) |
1725
1729
  | Label seen (persistent Monitor) | nothing to record |
1726
1730
  | CI run terminal | `ci=<run-id>:<attempt>:<conclusion>` on the row; then the finisher gate (below) |
1727
- | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n>=done`; `reap.sh --apply`; `reclaim-scratch.mjs --root <scratch> --apply`. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — a token the bot wrote in this pass, never one `reap.sh` writes.) |
1731
+ | Merge-bot pass report | `held-behind:#<lower>` rows; `ledger.mjs settle merge-bot-<n>=done`; `tick --apply` runs the reap and the reclaim. (The bot may also have written `conflict-hold:#<pr>` onto a held PR's own row earlier in this same pass, before reporting — a token the bot wrote in this pass, never one `reap.sh` writes.) |
1728
1732
  | Drain | `ledger.mjs drain "<reason>"`; release the claims (below); `settle impl-<N>=released`; then the rest of **End of run** (below), `--stop` last |
1729
1733
  | Heartbeat | nothing to record |
1730
1734
 
@@ -1782,10 +1786,13 @@ owes beyond its row:
1782
1786
  - **Merge-bot pass reports done** → write each `held-behind-#<lower>` it reports
1783
1787
  into that ticket's row as `held-behind:#<lower>` — the verdict moves no label
1784
1788
  and leaves nothing in the repo, so the row is the only place the tick can read
1785
- it from — settle `merge-bot-<n>=done`, reap merged branches and worktrees with
1786
- `reap.sh --apply` (below) — always, even when the pass merged nothing — then
1787
- reclaim their scratch with `reclaim-scratch.mjs --root <scratch> --apply`
1788
- (below), and then run the tick. A label that landed at the last moment reads `DISPATCH
1789
+ it from — settle `merge-bot-<n>=done`, and then run the tick: `tick --apply`
1790
+ reaps merged branches and worktrees with `reap.sh --apply` (below), then
1791
+ reclaims their scratch with `reclaim-scratch.mjs --root <scratch> --apply`
1792
+ (below), once for every merge bot settled `done` — always, even when the pass
1793
+ merged nothing — and runs both again on the next tick after an `APPLY FAILED`
1794
+ line, and on every tick while this run has no controller record to remember
1795
+ the pass by. A label that landed at the last moment reads `DISPATCH
1789
1796
  merge-bot` again: dispatch the next bot straight away. A `rebase-fallback-#<pr>`
1790
1797
  on a conflict needs no record from you — the bot already appended
1791
1798
  `conflict-hold:#<pr>` to that PR's row, and the tick turns it into `DISPATCH
@@ -1884,7 +1891,7 @@ owes beyond its row:
1884
1891
  **Every wake ends in the tick.** One invocation, and you act on what it prints:
1885
1892
 
1886
1893
  ```
1887
- ~/.fleet/bin/fleet-run fleet-tick.mjs [--implementer-cap <n>] [--reviewer-cap <n>] [--max-reviews <n>]
1894
+ ~/.fleet/bin/fleet-run fleet-tick.mjs --apply [--implementer-cap <n>] [--reviewer-cap <n>] [--max-reviews <n>]
1888
1895
  ```
1889
1896
 
1890
1897
  It reads the run itself, and nobody states a count. Live implementers, live
@@ -1960,16 +1967,18 @@ depth** guard table applied in code. Act on each line as it reads:
1960
1967
  - `HOLD (…)` — the row is held and says why: draining, a tier mismatch, an
1961
1968
  unchecked tier, a saturated review side, `--max-reviews` in flight, or every
1962
1969
  queued merge candidate held behind a lower PR or on a conflict hold no
1963
- fix-applier has cleared. The two tier holds are yours to clear — an
1964
- unchecked tier by running `tier-check.mjs --batch` on the member it names
1965
- (its `tier-ok=`, or `tier-unverifiable=` for a member settled `killed` or
1966
- `released` with no transcript, clears it), a mismatch by dispatching the
1967
- replacement at the right tier (phase 2). Each
1968
- prints its clearing step in the row's detail: the `tier-check.mjs` command
1970
+ fix-applier has cleared. An unchecked tier is `tick --apply`'s to check, and
1971
+ the hold stays while the check writes no verdict (its `tier-ok=`, or
1972
+ `tier-unverifiable=` for a member settled `killed` or `released` with no
1973
+ transcript, clears it); a mismatch is yours to clear, by dispatching the
1974
+ replacement at the right tier (phase 2). Each prints its clearing step in
1975
+ the row's detail. For a mismatch that is the replacement's name —
1976
+ `impl-<N>-b` on a first retry, else one letter past the highest the ticket
1977
+ has used, or that no retry letter is left. For an unchecked tier, which
1978
+ `tick --apply` has already tried, it is the `tier-check.mjs` command to run
1979
+ by hand when the tick ran without `--apply` or the check wrote no verdict,
1969
1980
  with a batch entry per member it names (fill in `<file>`; `<session>` too
1970
- when no receipt of this run records one),
1971
- or the replacement's name — `impl-<N>-b` on a first retry, else one letter
1972
- past the highest the ticket has used, or that no retry letter is left.
1981
+ when no receipt of this run records one).
1973
1982
  - `AT CAP`, `IDLE OK` — nothing to do on that row.
1974
1983
  - `MAIN-CHECKOUT-DIRTY <paths> …`, printed above the rows, with every
1975
1984
  dispatching row (implementers, reviewers, merge-bot) reading
@@ -2032,7 +2041,7 @@ depth** guard table applied in code. Act on each line as it reads:
2032
2041
  `--liveness-merge-bot` and `--liveness-review` set the thresholds, in minutes.
2033
2042
 
2034
2043
  **Tier guards under Pull.** The per-dispatch `tier-check.mjs --batch` is
2035
- phase 2's own step: a mismatch it finds is the
2044
+ phase 2's own step, run by `tick --apply`: a mismatch it finds is the
2036
2045
  `HOLD (tier mismatch impl-<N>)` above, and a member it has no verdict on is
2037
2046
  the `HOLD (tier unchecked impl-<N>)`. Nothing else in the loop owns it.
2038
2047
 
@@ -3709,8 +3718,9 @@ worktree — and its installed dependencies — still on disk. Reap after **each
3709
3718
  not once at the end: a stale worktree still answers `git worktree list`, so the
3710
3719
  in-flight probe (`inflight.sh`, run by the Shortlist and by every Pull) reads an
3711
3720
  already-merged ticket as taken and the queue quietly shrinks. The trigger is the
3712
- bot's one exit report, and it reaps every time — a pass that merged nothing
3713
- included (phase 3, **Merge-bot pass reports done**). See references/reaping.md.
3721
+ bot's `merge-bot-<n>=done`, and `tick --apply` reaps once for every one — a pass
3722
+ that merged nothing included (phase 3, **Merge-bot pass reports done**). See
3723
+ references/reaping.md.
3714
3724
 
3715
3725
  `~/.fleet/bin/fleet-run reap.sh --apply` recomputes every precondition
3716
3726
  inside the same invocation as the delete — `for-each-ref` for `[gone]`, `git
@@ -3738,7 +3748,7 @@ See references/reaping.md.
3738
3748
 
3739
3749
  ### Reclaim scratch after each merge pass
3740
3750
 
3741
- Right after `reap.sh --apply`, every pass:
3751
+ `tick --apply` runs it right after `reap.sh --apply`, every pass:
3742
3752
  `~/.fleet/bin/fleet-run reclaim-scratch.mjs --root <scratch> --apply`,
3743
3753
  `<scratch>` the path `scratch-root.mjs` prints. Reap authorizes on git's
3744
3754
  evidence and never removes scratch; Reclaim authorizes on GitHub state and