@feigi/fleet-ctl 3.158.39 → 3.159.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.158.39",
3
+ "version": "3.159.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": {
@@ -45,17 +45,21 @@
45
45
  // member's stamp does not outlive it. Carried, never written, by
46
46
  // the heartbeat and by ledger.mjs.
47
47
  // applied fleet-tick only, and only under --apply. {run, reapAfter,
48
- // sweptAfter}: the merge-bot numbers whose `merge-bot-<n>=done` the
49
- // tick has already run reap.sh, reclaim-scratch.mjs and evict.mjs
50
- // after (`reapAfter`), the fix-applier, finisher and failed review
51
- // launch names whose settle it has already run reclaim-scratch.mjs
52
- // after (`sweptAfter`, left out while empty), and the controller
53
- // record's `at` they belong to. Written only under a record: with none, nothing tells
54
- // one run from the next. Merge-bot numbering restarts at 1 in a run
55
- // that carries no bot forward, and this file outlives the rotation,
56
- // so a list whose `run` is not the current record's `at` is the
57
- // previous run's and names nothing in this one. Carried, never
58
- // written, by the heartbeat and by ledger.mjs.
48
+ // reapAfterPrs, sweptAfter}: the merge-bot numbers whose
49
+ // `merge-bot-<n>=done` the tick has already run reap.sh,
50
+ // reclaim-scratch.mjs and evict.mjs after (`reapAfter`); in a run
51
+ // whose merge bot is off, the PR numbers it read MERGED and has
52
+ // already run them after (`reapAfterPrs`, left out while empty);
53
+ // the fix-applier, finisher and failed review launch names whose
54
+ // settle it has already run reclaim-scratch.mjs after
55
+ // (`sweptAfter`, left out while empty); and the controller record's
56
+ // `at` they belong to. Written only under a record: with none,
57
+ // nothing tells one run from the next. Merge-bot numbering
58
+ // restarts at 1 in a run that carries no bot forward, and this
59
+ // file outlives the rotation, so a list whose `run` is not the
60
+ // current record's `at` is the previous run's and names nothing in
61
+ // this one. Carried, never written, by the heartbeat and by
62
+ // ledger.mjs.
59
63
  //
60
64
  // One writer per key. A key two scripts wrote would need locking to be
61
65
  // correct, and none of them is in a position to hold one. That holds per key,
@@ -259,7 +263,11 @@ export function readState(path, name, warn = console.error) {
259
263
  if (!isRecord(v) || !Array.isArray(v.reapAfter)) return null;
260
264
  if (!(Number.isInteger(v.run) && v.run > 0)) return null;
261
265
  const swept = Array.isArray(v.sweptAfter) ? v.sweptAfter.filter((m) => typeof m === "string" && m !== "") : [];
262
- return { run: v.run, reapAfter: v.reapAfter.filter((n) => Number.isInteger(n) && n > 0), ...(swept.length > 0 ? { sweptAfter: swept } : {}) };
266
+ const prs = Array.isArray(v.reapAfterPrs) ? v.reapAfterPrs.filter((n) => Number.isInteger(n) && n > 0) : [];
267
+ return {
268
+ run: v.run, reapAfter: v.reapAfter.filter((n) => Number.isInteger(n) && n > 0),
269
+ ...(prs.length > 0 ? { reapAfterPrs: prs } : {}), ...(swept.length > 0 ? { sweptAfter: swept } : {}),
270
+ };
263
271
  };
264
272
  const { quiet, digest, beat, ticked, acted, controller, seen, applied, ...rest } = parsed;
265
273
  // A controller key that ctl() rejects is a record someone wrote and nobody
@@ -86,7 +86,16 @@
86
86
  // holds every dispatching row, ahead of the main-checkout reason;
87
87
  // it never refuses the tick. A step's `drift` or `unanswered` is
88
88
  // advice, named on the line and holding nothing. The receipt's
89
- // `session` fills the tier hold's step.
89
+ // `session` fills the tier hold's step. Its `merge` says whether
90
+ // the run's merge bot merges (true when it records none) and is
91
+ // read from the receipt alone, never from a flag: with it off the
92
+ // merge-bot row prints `IDLE (merging off)` whatever the queue
93
+ // holds, the in-flight hold reads `HOLD (in-flight n/B, awaiting
94
+ // human merge)`, a draining run is over with only
95
+ // `ready-to-merge` PRs open (one GitHub has not read MERGEABLE,
96
+ // one on a conflict hold, and one a member is still at work on
97
+ // each still hold it), and `--apply` reaps after each PR the
98
+ // ledger tracks that gh reads MERGED.
90
99
  // guard `.fleet/cost-guard.json` beside the shortlist, pr-cost.mjs
91
100
  // --guard's verdict on the implementer cells. Printed as the
92
101
  // `router` row and never acted on here: a missing or unreadable
@@ -384,7 +393,8 @@ function implementers(s) {
384
393
  // ready-to-merge queue adds no rebases per PR, and a review owed is the
385
394
  // reviewer row's DISPATCH on this same tick.
386
395
  if (s.inFlight >= s.bound) {
387
- const hold = `HOLD (in-flight ${s.inFlight}/${s.bound})`;
396
+ // With merging off the merge that brings n below B is the maintainer's.
397
+ const hold = `HOLD (in-flight ${s.inFlight}/${s.bound}${s.merging === true ? "" : ", awaiting human merge"})`;
388
398
  return s.owedCounted.length ? row(hold, { acts: true, extra: replaceStep(s.owedCounted, s.implNames) }) : row(hold);
389
399
  }
390
400
 
@@ -469,6 +479,10 @@ function mergeBot(s) {
469
479
  const parked = s.mergeParked;
470
480
  const row = mkRow("merge-bot", s.mergeBotLive, 1,
471
481
  `merge-queue=${s.mergeQueue} held=${s.mergeHeld}${parked.length > 0 ? ` parked=${parked.length}` : ""}`);
482
+ // A run whose merge bot is off dispatches none, whatever the queue holds:
483
+ // the maintainer merges what carries `ready-to-merge`. Only an explicit
484
+ // `true` turns the bot on, so a state that names no merging has none.
485
+ if (s.merging !== true) return row("IDLE (merging off)");
472
486
  if (s.mergeBotLive >= 1) return row("AT CAP");
473
487
  if (s.mergeQueue === 0) return row("IDLE OK");
474
488
  // `ready-to-merge` is the author's sign-off and nothing more. A bot
@@ -1083,6 +1097,9 @@ export const reviewOwed = (st, members, head) => st === undefined
1083
1097
  // The states a PR-state probe answers: anything else is no answer.
1084
1098
  const PR_STATES = ["OPEN", "MERGED", "CLOSED"];
1085
1099
 
1100
+ // Whether `pr` (an open PR as openPrs() reads it) carries the label `name`.
1101
+ const hasLabel = (pr, name) => pr.labels.some((l) => l && l.name === name);
1102
+
1086
1103
  export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queuedLabel, closed = new Set(), prStates = new Map()) {
1087
1104
  // `queuedLabel` is the tracker's string for the `ready-to-merge` role, from
1088
1105
  // the Label map the caller read (label-map.mjs) — this fold reads no cache.
@@ -1174,7 +1191,7 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1174
1191
  const owedReplacement = newest.filter(owesReplacement).map((m) => m.name);
1175
1192
  const owedCounted = newest.filter((m) => owesReplacement(m) && !closed.has(m.number)).map((m) => m.name);
1176
1193
  const inFlightImpl = newest.filter((m) => m.outcome === null && !closing.has(m.number)).length + owedCounted.length;
1177
- const isQueued = (p) => p.labels.some((l) => l && l.name === queuedLabel);
1194
+ const isQueued = (p) => hasLabel(p, queuedLabel);
1178
1195
  const queued = prs.filter(isQueued);
1179
1196
  const asc = (a, b) => a - b;
1180
1197
  const state = (n) => byPr.get(n);
@@ -1264,6 +1281,7 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1264
1281
  const finished = (n) => prStates.get(n) === "MERGED" || prStates.get(n) === "CLOSED";
1265
1282
  const liveReviews = reviewing.filter(([n]) => open.has(n) || !finished(n));
1266
1283
  const unsettled = all.filter((m) => m.outcome === null).map((m) => m.name);
1284
+ const prTracked = [...byPr.keys()].filter((n) => !open.has(n)).sort(asc);
1267
1285
  return {
1268
1286
  implLive: live("impl"),
1269
1287
  inFlight: inFlightImpl + prsIn.length,
@@ -1280,6 +1298,13 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1280
1298
  // anything above.
1281
1299
  prClosed: prSurfaced.filter((k) => prStates.get(k.pr) === "CLOSED").map((k) => ({ ...k, live: liveOn(k.pr) })),
1282
1300
  prUnchecked: prSurfaced.filter((k) => !PR_STATES.includes(prStates.get(k.pr))),
1301
+ // Every PR the ledger tracks — a row resolves to it — that the open list
1302
+ // does not carry, ascending: with merging off, the PRs the caller probes
1303
+ // beside the keyed ones, since the maintainer merges them. `prMerged` is
1304
+ // those the probe read MERGED: each is a merge `--apply` reaps, reclaims
1305
+ // and evicts after, once (reapDuePrs).
1306
+ prTracked,
1307
+ prMerged: prTracked.filter((n) => prStates.get(n) === "MERGED"),
1283
1308
  fixLive: live("fix-pr"),
1284
1309
  mergeBotLive,
1285
1310
  // The number of every merge bot settled `done`: each is a merge pass
@@ -1293,6 +1318,12 @@ export function deriveRun({ rows, dispatched, drain, retired = [] }, prs, queued
1293
1318
  // The in-flight reviews of PRs the open list does not carry: the ones
1294
1319
  // the probe could retire, so the caller asks gh about these and no others.
1295
1320
  reviewsOffList: reviewing.filter(([n]) => !open.has(n)).map(([n]) => n).sort(asc),
1321
+ // Every PR a member is still at work on, ascending: an unsettled
1322
+ // fix-applier or finisher bound to it, or an in-flight review of it.
1323
+ prsWorked: [...new Set([
1324
+ ...all.filter((m) => m.outcome === null && (m.family === "fix-pr" || m.family === "finisher-pr")).map((m) => m.number),
1325
+ ...liveReviews.map(([n]) => n),
1326
+ ])].sort(asc),
1296
1327
  // Each PR a fix-applier is owed on (`fixOwed`), unless two fix-appliers
1297
1328
  // have settled `failed` on it since its latest review with none landed
1298
1329
  // after them — that PR is `fixEscalate`'s instead — or it is itself owed
@@ -1626,6 +1657,17 @@ export function reapDue(done, applied, controllerAt) {
1626
1657
  return notIn(done, reapedAfter(applied, controllerAt));
1627
1658
  }
1628
1659
 
1660
+ // The PR numbers `applied.reapAfterPrs` names for THIS run.
1661
+ export function reapedAfterPrs(applied, controllerAt) {
1662
+ return ofThisRun(applied, controllerAt)?.reapAfterPrs ?? [];
1663
+ }
1664
+
1665
+ // The merges owed their reap, reclaim and evict in a run whose merge bot is
1666
+ // off: every PR `merged` (run.prMerged) that reapedAfterPrs() does not name.
1667
+ export function reapDuePrs(merged, applied, controllerAt) {
1668
+ return notIn(merged, reapedAfterPrs(applied, controllerAt));
1669
+ }
1670
+
1629
1671
  // The members `applied.sweptAfter` names for THIS run.
1630
1672
  export function sweptAfter(applied, controllerAt) {
1631
1673
  return ofThisRun(applied, controllerAt)?.sweptAfter ?? [];
@@ -1704,7 +1746,7 @@ import { fleetFile, FleetDirUnresolvable, scratchRoot } from "./fleet-dir.mjs";
1704
1746
  import { LABEL_MAP_FILE, LabelMapUnreadable, readLabelMap } from "./label-map.mjs";
1705
1747
  import { statePath, readState, writeState, assessBeat, isStalled, isReported, stallReport, stallOwner } from "./fleet-state.mjs";
1706
1748
  import { checkMainCheckout, describe } from "./main-checkout.mjs";
1707
- import { readRunReceipt, phase0Gate, IN_FLIGHT_DEFAULT } from "./phase0-receipt.mjs";
1749
+ import { readRunReceipt, phase0Gate, mergingOf, IN_FLIGHT_DEFAULT } from "./phase0-receipt.mjs";
1708
1750
  import { judgeRecord, ProcUnreadable } from "./proc.mjs";
1709
1751
  import { reportFamily, readReport, reportPath, reportsDir } from "./report-files.mjs";
1710
1752
  import { ownClosingIssues } from "./closing-refs.mjs";
@@ -1724,8 +1766,9 @@ const MERGEABLE_STATES = ["MERGEABLE", "CONFLICTING", "UNKNOWN"];
1724
1766
  // cap, because refusing would suppress the one announcement a dead run leaves
1725
1767
  // behind. So it discloses instead — the line says the count is a floor.
1726
1768
  const CLAIMED_LIMIT = 200;
1727
- // The tick's last line once a draining run has nothing left in flight. The
1728
- // tick cannot write the stop — `beat` is fleet-heartbeat's — so it names it.
1769
+ // The tick's last line once a draining run has nothing left in flight (with
1770
+ // merging off, nothing but PRs the maintainer is to merge). The tick cannot
1771
+ // write the stop — `beat` is fleet-heartbeat's — so it names it.
1729
1772
  export const RUN_OVER = `ACTION: run over → fleet-heartbeat.mjs --stop "<reason>"`;
1730
1773
  const MAX_BUFFER = 64 * 1024 * 1024;
1731
1774
  // Every gh spawn below is killed at this bound, so a gh that never answers is
@@ -1764,12 +1807,13 @@ const OPTIONS = {
1764
1807
  "fold-unchanged": { type: "boolean", default: false },
1765
1808
  // `--apply` runs the idempotent follow-ups whose trigger the ledger and the
1766
1809
  // state file show, before the rows: reap.sh, reclaim-scratch.mjs and
1767
- // evict.mjs after every merge pass settled `done`, reclaim-scratch.mjs
1768
- // alone after every settle of a fix-applier, a finisher or a review launch
1769
- // `=failed`, and tier-check.mjs on every implementer
1770
- // the tick would hold as unchecked. It never dispatches, never settles a
1771
- // member and writes no ledger row but through those scripts. Without it the
1772
- // tick is read-only.
1810
+ // evict.mjs after every merge pass settled `done` — and, in a run whose
1811
+ // merge bot is off, after every PR its ledger tracks that gh reads MERGED
1812
+ // — reclaim-scratch.mjs alone after every settle of a fix-applier, a
1813
+ // finisher or a review launch `=failed`, and tier-check.mjs on every
1814
+ // implementer the tick would hold as unchecked. It never dispatches, never
1815
+ // settles a member and writes no ledger row but through those scripts.
1816
+ // Without it the tick is read-only.
1773
1817
  apply: { type: "boolean", default: false },
1774
1818
  // Path override, for tests. An empty value cannot be told from an absent one
1775
1819
  // under parseArgs, and no path is legitimately empty, so empty resolves to
@@ -2056,19 +2100,21 @@ function closedTickets(mismatched, owed, surfacing) {
2056
2100
  // The state of each PR the tick asks gh about, one aliased `gh api graphql`
2057
2101
  // read per hundred PRs however many readings need them: `reviews`, the PRs
2058
2102
  // whose review the ledger reads as in flight yet the open list does not carry,
2059
- // and `keyed`, each ticket's keyed PR the open list does not carry (deriveRun's
2060
- // `prKeyed`). The answer is OPEN, MERGED or CLOSED. A probe that could not
2103
+ // `keyed`, each ticket's keyed PR the open list does not carry (deriveRun's
2104
+ // `prKeyed`), and `tracked`, every PR the ledger tracks that the open list
2105
+ // does not carry (`prTracked`), asked only in a run whose merge bot is off.
2106
+ // The answer is OPEN, MERGED or CLOSED. A probe that could not
2061
2107
  // answer — a failed call, an alias GitHub errored on or answered with nothing,
2062
2108
  // a node carrying no state, a state that is none of the three — leaves its PR
2063
2109
  // out of the map and is disclosed, per PR, with what it leaves standing; a
2064
2110
  // call killed at GH_TIMEOUT_MS is disclosed with that bound.
2065
- function prStates(reviews, keyed) {
2111
+ function prStates(reviews, keyed, tracked = []) {
2066
2112
  const states = new Map();
2067
2113
  const reviewed = new Set(reviews);
2068
2114
  // Two tickets can be keyed on one PR: each is named, on its one probe.
2069
2115
  const ticketsOf = new Map();
2070
2116
  for (const k of keyed) ticketsOf.set(k.pr, [...(ticketsOf.get(k.pr) ?? []), k.n]);
2071
- const numbers = [...new Set([...reviews, ...ticketsOf.keys()])].sort((a, b) => a - b);
2117
+ const numbers = [...new Set([...reviews, ...ticketsOf.keys(), ...tracked])].sort((a, b) => a - b);
2072
2118
  const read = ghAliasedRead(numbers, { field: "pullRequest", selection: "{state}", timeoutMs: GH_TIMEOUT_MS });
2073
2119
  for (const number of numbers) {
2074
2120
  const r = read.get(number);
@@ -2080,9 +2126,10 @@ function prStates(reviews, keyed) {
2080
2126
  const unconfirmed = [
2081
2127
  ...(reviewed.has(number) ? [`review on PR#${number} unconfirmed finished, its unit stands`] : []),
2082
2128
  ...(ticketsOf.get(number) ?? []).map((n) => `#${n}'s PR#${number} unconfirmed closed, printed as pr-unchecked`),
2083
- ].join("; ");
2129
+ ...(tracked.includes(number) ? [`PR#${number} unconfirmed merged, its reap waits`] : []),
2130
+ ];
2084
2131
  const why = r.unreachable === "ETIMEDOUT" ? TIMED_OUT : r.unreachable ?? (r.notFound ? "no such pull request" : "no PR state");
2085
- console.error(`${NAME}: gh api graphql gave no answer for PR#${number} (${why}) — ${unconfirmed}`);
2132
+ console.error(`${NAME}: gh api graphql gave no answer for PR#${number} (${why}) — ${unconfirmed.join("; ")}`);
2086
2133
  }
2087
2134
  return states;
2088
2135
  }
@@ -2121,15 +2168,17 @@ function reportDuty(r, { label, duty, what, summarise }) {
2121
2168
  return summary !== null;
2122
2169
  }
2123
2170
 
2124
- // Reap, then reclaim, then evict, after the merge passes in `due` — once
2125
- // however many there are, since each sweeps the whole repository, scratch
2126
- // root or set of claim trees rather than one pass's share. Each runs whether
2127
- // or not the one before it did: none reads another's result. True only when
2128
- // all three applied, the one case `due` is recorded as reaped after; otherwise
2129
- // the next --apply tick runs them again. `{all, reclaimed}`: the second is true
2130
- // when the root sweep applied, which is also the sweep a settled member owes.
2131
- function applyReap(due) {
2132
- const label = `reap after ${due.map((n) => `merge-bot-${n}`).join(" ")}`;
2171
+ // Reap, then reclaim, then evict, after the merge passes and merges in `due` —
2172
+ // once however many there are, since each sweeps the whole repository, scratch
2173
+ // root or set of claim trees rather than one pass's or one merge's share. Each
2174
+ // runs whether or not the one before it did: none reads another's result. True
2175
+ // only when all three applied, the one case `due` is recorded as reaped after;
2176
+ // otherwise the next --apply tick runs them again. `{all, reclaimed}`: the
2177
+ // second is true when the root sweep applied, which is also the sweep a
2178
+ // settled member owes. `due` is merge-bot numbers, `duePrs` the PRs a
2179
+ // maintainer merged in a run whose merge bot is off.
2180
+ function applyReap(due, duePrs) {
2181
+ const label = `reap after ${[...due.map((n) => `merge-bot-${n}`), ...duePrs.map((n) => `PR#${n}`)].join(" ")}`;
2133
2182
  const reaped = reportDuty(runSibling("reap.sh", ["--apply"]), { label, duty: "reap", what: "reap.sh", summarise: reapSummary });
2134
2183
  const reclaimed = applySweep("reclaim");
2135
2184
  const evicted = reportDuty(runSibling("evict.mjs", ["--apply"]),
@@ -2261,12 +2310,15 @@ export function controllerState(controller, name = NAME) {
2261
2310
  // review unit; an unread state is never read as finished. The issue probe asks
2262
2311
  // only about the tickets whose keyed PR read CLOSED or could not be read: OPEN
2263
2312
  // and MERGED print nothing whatever the issue says. A ledger it cannot read
2264
- // refuses the tick.
2265
- function readRun(prs, queuedLabel) {
2313
+ // refuses the tick. `trackMerged` also asks the state of every other PR the
2314
+ // ledger tracks that the open list does not carry, which is how a PR the
2315
+ // maintainer merged is read MERGED (`prMerged`): a run whose merge bot is off
2316
+ // and that `--apply` reaps after hand merges.
2317
+ function readRun(prs, queuedLabel, { trackMerged = false } = {}) {
2266
2318
  try {
2267
2319
  const ledger = readLedger();
2268
2320
  const run = deriveRun(ledger, prs, queuedLabel);
2269
- const states = prStates(run.reviewsOffList, run.prKeyed);
2321
+ const states = prStates(run.reviewsOffList, run.prKeyed, trackMerged ? run.prTracked : []);
2270
2322
  const surfacing = run.prKeyed.filter((k) => states.get(k.pr) !== "OPEN" && states.get(k.pr) !== "MERGED").map((k) => k.n);
2271
2323
  const closed = closedTickets(run.tierMismatch, run.owedReplacement, surfacing);
2272
2324
  return deriveRun(ledger, prs, queuedLabel, closed, states);
@@ -2426,6 +2478,9 @@ function main() {
2426
2478
  const phase0 = phase0Gate(receipt.read, {
2427
2479
  path: receipt.path, controllerAt: controller?.at, controller: controllerState(controller),
2428
2480
  });
2481
+ // Whether the run's merge bot merges is the receipt's word and no flag's: a
2482
+ // tick that forgot an argument must never be the one that dispatches a bot.
2483
+ const merging = mergingOf(receipt.read);
2429
2484
  // The session directory's listing, ahead of every ledger read: a dispatch is
2430
2485
  // written to the ledger before its `task` call makes the transcript, so a
2431
2486
  // stem listed here is on whatever ledger is read after. Listed later, a
@@ -2440,7 +2495,10 @@ function main() {
2440
2495
  // lines are the exception, printed as each duty runs: they say what was
2441
2496
  // done, which is true whether or not the reconcile after them lands.
2442
2497
  const prs = openPrs();
2443
- let run = readRun(prs, labels["ready-to-merge"]);
2498
+ // A run whose merge bot is off learns of a hand merge through the state of
2499
+ // the PRs its ledger tracks, so `--apply` asks for them.
2500
+ const readOpts = { trackMerged: apply && !merging };
2501
+ let run = readRun(prs, labels["ready-to-merge"], readOpts);
2444
2502
 
2445
2503
  // The main checkout against the run's baseline, on every tick — the
2446
2504
  // backstop for what member-write-guard cannot see. Never a refusal of the tick:
@@ -2450,36 +2508,47 @@ function main() {
2450
2508
 
2451
2509
  if (apply) {
2452
2510
  // Reap, reclaim and evict after every merge pass settled `done` since the
2453
- // last time they ran, and the root sweep after every settle `sweepAfter`
2454
- // names that `sweptAfter` does not. A merge pass is recorded in `reapAfter`
2455
- // only once all three applied, and a settle in `sweptAfter` once a root
2456
- // sweep applied, the merge pass's own included; each on a fresh read of the
2457
- // state file so nothing the heartbeat wrote meanwhile is reverted, never
2458
- // onto a file that could not be read, and never with no controller
2459
- // record: nothing could tell a list recorded then from the next run's.
2511
+ // last time they ran — and, with merging off, after every PR the ledger
2512
+ // tracks that read MERGED since — and the root sweep after every settle
2513
+ // `sweepAfter` names that `sweptAfter` does not. A merge pass is recorded
2514
+ // in `reapAfter` and a merged PR in `reapAfterPrs` only once all three
2515
+ // applied, and a settle in `sweptAfter` once a root sweep applied, the
2516
+ // merge pass's own included; each on a fresh read of the state file so
2517
+ // nothing the heartbeat wrote meanwhile is reverted, never onto a file
2518
+ // that could not be read, and never with no controller record: nothing
2519
+ // could tell a list recorded then from the next run's.
2460
2520
  const run0 = controller?.at ?? null;
2461
2521
  const due = reapDue(run.mergeBotDone, priorState.applied, run0);
2522
+ const duePrs = merging ? [] : reapDuePrs(run.prMerged, priorState.applied, run0);
2462
2523
  const owed = sweepDue(run.sweepAfter, priorState.applied, run0);
2463
- const reap = due.length ? applyReap(due) : null;
2524
+ const reap = due.length || duePrs.length ? applyReap(due, duePrs) : null;
2464
2525
  // The root sweep a merge pass ran is the one a settled member owes too.
2465
2526
  const swept = owed.length > 0 && (reap?.reclaimed || applySweep(`reclaim after ${owed.join(" ")}`));
2466
2527
  const reaped = reap?.all ? due : [];
2467
- if (run0 !== null && (reaped.length > 0 || swept)) {
2528
+ const reapedPrs = reap?.all ? duePrs : [];
2529
+ if (run0 !== null && (reaped.length > 0 || reapedPrs.length > 0 || swept)) {
2468
2530
  const now = readState(path, NAME);
2469
2531
  if (!now.degraded) {
2470
2532
  const reapAfter = [...new Set([...reapedAfter(now.applied, run0), ...reaped])];
2533
+ const reapAfterPrs = [...new Set([...reapedAfterPrs(now.applied, run0), ...reapedPrs])];
2471
2534
  const sweptNames = [...new Set([...sweptAfter(now.applied, run0), ...(swept ? owed : [])])];
2472
- writeState(path, NAME, now, { applied: { run: run0, reapAfter, ...(sweptNames.length > 0 ? { sweptAfter: sweptNames } : {}) } });
2535
+ writeState(path, NAME, now, {
2536
+ applied: {
2537
+ run: run0, reapAfter,
2538
+ ...(reapAfterPrs.length > 0 ? { reapAfterPrs } : {}),
2539
+ ...(sweptNames.length > 0 ? { sweptAfter: sweptNames } : {}),
2540
+ },
2541
+ });
2473
2542
  }
2474
2543
  }
2475
2544
  // The tier check, on exactly the members the implementer row would hold
2476
2545
  // as unchecked — that row reads the same before the refresh as after it.
2477
2546
  // A verdict written changes the ledger, so the run is read again.
2478
2547
  const unchecked = tierCheckDue(reconcile({
2479
- ...caps, ...run, heads: unclaimed(current.entries, run), supply: current.scanned, dropped: current.dropped,
2548
+ ...caps, ...run, merging, heads: unclaimed(current.entries, run), supply: current.scanned, dropped: current.dropped,
2480
2549
  shortlistStatus: current.status, refresh: null, mainCheckout, phase0, router,
2481
2550
  }), run.tierUnchecked);
2482
- if (unchecked.length && applyTierChecks(unchecked, phase0.session)) run = readRun(prs, labels["ready-to-merge"]);
2551
+ if (unchecked.length && applyTierChecks(unchecked, phase0.session)) run = readRun(prs, labels["ready-to-merge"], readOpts);
2483
2552
  }
2484
2553
 
2485
2554
  // The scratch root of the report files and the Pull records alike.
@@ -2536,7 +2605,7 @@ function main() {
2536
2605
  }
2537
2606
 
2538
2607
  const rows = reconcile({
2539
- ...caps, ...run, heads, supply, dropped, shortlistStatus: current.status, refresh: fresh, mainCheckout, phase0, router, pulls,
2608
+ ...caps, ...run, merging, heads, supply, dropped, shortlistStatus: current.status, refresh: fresh, mainCheckout, phase0, router, pulls,
2540
2609
  });
2541
2610
  const said = describe(mainCheckout, run.live);
2542
2611
  // The report files of the live members, read before the state file for the
@@ -2570,10 +2639,20 @@ function main() {
2570
2639
  const above = [...(phase0.line === null ? [] : [phase0.line]), ...(said === null ? [] : [said]), ...stale.map((s) => s.line)];
2571
2640
  const rowLines = formatLines(rows);
2572
2641
  // The run is over once it is draining and nothing is left in flight: no
2573
- // open PR and no implementer still holding a claim. Printed last and read
2574
- // as actionable, so it never folds away: the stop it names is the run's
2575
- // last act, and only the controller can write it.
2576
- const over = run.draining !== null && prs.length === 0 && run.implLive === 0;
2642
+ // open PR and no implementer still holding a claim. With merging off a PR
2643
+ // carrying `ready-to-merge` is the maintainer's to merge and holds nothing
2644
+ // once GitHub reads it MERGEABLE, no conflict hold stands on it and no
2645
+ // member is at work on it. One GitHub reads CONFLICTING, or that a conflict
2646
+ // hold stands on, is owed a fix-applier first; one GitHub has not read yet
2647
+ // (UNKNOWN) is read again next tick; and a finisher, fix-applier or review
2648
+ // still live on one has not finished with it. Every other open PR,
2649
+ // unreviewed or unlabelled, still holds it. Printed last and read as
2650
+ // actionable, so it never folds away: the stop it names is the run's last
2651
+ // act, and only the controller can write it.
2652
+ const awaitsMaintainer = (p) => hasLabel(p, labels["ready-to-merge"]) && p.mergeable === "MERGEABLE"
2653
+ && !run.conflictHeld.includes(p.number) && !run.prsWorked.includes(p.number);
2654
+ const holding = merging ? prs : prs.filter((p) => !awaitsMaintainer(p));
2655
+ const over = run.draining !== null && holding.length === 0 && run.implLive === 0;
2577
2656
  if (over) rowLines.push(RUN_OVER);
2578
2657
  const advice = [...transcribed, ...reported];
2579
2658
  const lines = [...above, ...advice.map((a) => a.line), ...rowLines];
@@ -2,9 +2,11 @@
2
2
  // after every step (its header gives the shape); this module is its readers'
3
3
  // half: the tick's dispatch gate, the session directory tier-check.mjs
4
4
  // and ticket-router.mjs take when their own flag is omitted, the Objective
5
- // ticket-router.mjs takes likewise, with its default, and the In-flight
6
- // bound the drivers hand the tick, with its default. One reading of the file,
7
- // so the gate and the session readers cannot disagree about what a receipt is.
5
+ // ticket-router.mjs takes likewise, with its default, the In-flight
6
+ // bound the drivers hand the tick, with its default, and whether the run's
7
+ // merge bot merges, which the tick reads from the receipt alone. One reading
8
+ // of the file, so the gate and the session readers cannot disagree about what
9
+ // a receipt is.
8
10
  //
9
11
  // Zero deps: node builtins and sibling modules only.
10
12
 
@@ -164,6 +166,26 @@ export function objectiveFromReceipt(opts) {
164
166
  throw new Error(`no objective given and none in the phase-0 receipt ${path} (${why}) — give one (${OBJECTIVES.join(" or ")}), or run ${phase0Command(null)} first`);
165
167
  }
166
168
 
169
+ // Whether a run's merge bot merges when nobody says: phase0.mjs records the
170
+ // run's choice in its receipt as `merge`, and a receipt written before it
171
+ // recorded one is read as the default when phase 0 resumes it.
172
+ export const MERGE_DEFAULT = true;
173
+
174
+ /**
175
+ * Whether the run's merge bot merges, read off `read` (readRunReceipt()'s
176
+ * `read`): the receipt's `merge`, and the default (on) when there is no
177
+ * receipt, it cannot be read, or it records none. With no usable receipt
178
+ * phase0Gate holds every dispatching row, so that default dispatches no bot.
179
+ * The tick reads this every pass, so it meets what a hand left in the file:
180
+ * a `merge` present but not a boolean reads as off, since a bot dispatched on
181
+ * a value nobody can read is the failure the switch exists to prevent, while
182
+ * a merge not made waits for the maintainer or a later run.
183
+ */
184
+ export function mergingOf(read) {
185
+ if (read.state !== "ok" || read.receipt.merge === undefined) return MERGE_DEFAULT;
186
+ return read.receipt.merge === true;
187
+ }
188
+
167
189
  // The In-flight bound a run takes when nobody gives one: the most tickets
168
190
  // between Claim and merge at once. Its one definition — phase0.mjs and the
169
191
  // tick's own flag default both read it from here.
@@ -2,7 +2,7 @@
2
2
  // Phase 0 as one command: the run's start sequence, in order, with a receipt.
3
3
  //
4
4
  // phase0.mjs [--session <dir>] [--in-flight n] [--objective cost|speed]
5
- // [--spend-dir <dir>]
5
+ // [--merge | --no-merge] [--spend-dir <dir>]
6
6
  // [--workflow <name> | --declare-no-ci]
7
7
  //
8
8
  // The session directory is `--session`, else `PI_ARTIFACTS_DIR`, which omp
@@ -125,7 +125,7 @@
125
125
  // THE RECEIPT is `.fleet/phase0.json` (resolved through fleet-dir.mjs, so a
126
126
  // worktree and the main checkout name one file):
127
127
  //
128
- // { run, session, scratch, inFlight, objective, pluginVersion,
128
+ // { run, session, scratch, inFlight, objective, merge, pluginVersion,
129
129
  // steps: { <name>: { status, at, output } } }
130
130
  //
131
131
  // `status` is ok, pending, failed, drift or unanswered; `at` an ISO time;
@@ -142,6 +142,14 @@
142
142
  // default when it records none — and a resume whose `--objective` names the
143
143
  // other one exits 2 naming both, leaving the receipt as it was. A resumed
144
144
  // receipt recording a value that is not an Objective exits 3 naming it.
145
+ // `merge` is whether the run's merge bot merges: `false` under `--no-merge`,
146
+ // `true` under `--merge` or with neither (MERGE_DEFAULT in
147
+ // phase0-receipt.mjs). `--merge` and `--no-merge` together exit 2. Like the
148
+ // Objective it is fixed for the run: a resumed receipt keeps the one it
149
+ // records — `true` when it records none — and a resume that names the other
150
+ // one exits 2 naming both, leaving the receipt as it was. A resumed receipt
151
+ // recording a value that is not a boolean exits 3 naming it. The tick reads
152
+ // it from this receipt and from no flag of its own.
145
153
  // `pluginVersion` is the version the pin recorded, null when it recorded
146
154
  // none; a resumed receipt keeps it.
147
155
  //
@@ -207,7 +215,7 @@ import { isCLI } from "./is-cli.mjs";
207
215
  import { GH_LOGIN_ARGS, isOwnedPr, loginOf, ownershipReadable } from "./owned-pr.mjs";
208
216
  import { OBJECTIVES, RECEIPT, RECEIPT_HELD, archiveStamp, receiptArchiveName, rowNums } from "./ledger-grammar.mjs";
209
217
  import { ancestry, controllerOf, processSource, ProcUnreadable } from "./proc.mjs";
210
- import { IN_FLIGHT_DEFAULT, OBJECTIVE_DEFAULT } from "./phase0-receipt.mjs";
218
+ import { IN_FLIGHT_DEFAULT, MERGE_DEFAULT, OBJECTIVE_DEFAULT } from "./phase0-receipt.mjs";
211
219
  import { readRecipe } from "./recipe-read.mjs";
212
220
  import { gather, recordChanges, refusedLine, unclosedRecords } from "./run-records.mjs";
213
221
 
@@ -707,7 +715,7 @@ function main() {
707
715
  const die = makeDie(NAME);
708
716
  const F = defineFlags(die, {
709
717
  flags: {
710
- session: "value", "in-flight": "value", objective: "value",
718
+ session: "value", "in-flight": "value", objective: "value", merge: "bool", "no-merge": "bool",
711
719
  "spend-dir": "value", workflow: "value", "declare-no-ci": "bool",
712
720
  },
713
721
  });
@@ -747,6 +755,8 @@ function main() {
747
755
  const inFlight = positive("in-flight") ?? IN_FLIGHT_DEFAULT;
748
756
  const named = F.arg("objective");
749
757
  if (named !== null && !OBJECTIVES.includes(named)) die(`--objective needs ${OBJECTIVES.join(" or ")}, got ${named}`);
758
+ if (F.has("merge") && F.has("no-merge")) die("--merge and --no-merge are alternatives, not a pair");
759
+ const mergeNamed = F.has("no-merge") ? false : F.has("merge") ? true : null;
750
760
  if (F.has("declare-no-ci") && !absent("workflow")) die("--workflow and --declare-no-ci are alternatives, not a pair");
751
761
  const ci = F.has("declare-no-ci") ? "CI: declared absent (--declare-no-ci)" : absent("workflow") ? null : `CI: workflow ${F.arg("workflow")} (--workflow)`;
752
762
  const spendDir = absent("spend-dir") ? null : resolve(F.arg("spend-dir"));
@@ -812,6 +822,20 @@ function main() {
812
822
  die(`--objective ${named}: this run's receipt ${receiptPath} records the objective ${kept}, fixed for the run — run phase 0 again without --objective, or with --objective ${kept}`);
813
823
  }
814
824
  const objective = kept ?? named ?? OBJECTIVE_DEFAULT;
825
+ // The merge switch is fixed for the run the same way: a resumed receipt's
826
+ // stands, and one that records none resumes as merge. One recording
827
+ // anything but a boolean is refused, never read as merge.
828
+ if (resumed && previous.merge !== undefined && typeof previous.merge !== "boolean") {
829
+ process.stderr.write(`${NAME}: this run's receipt ${receiptPath} records merge ${JSON.stringify(previous.merge)}, which is not true or false — set it to the value this run began with and re-run\n`);
830
+ process.exitCode = 3;
831
+ return;
832
+ }
833
+ const keptMerge = resumed ? previous.merge ?? MERGE_DEFAULT : null;
834
+ if (keptMerge !== null && mergeNamed !== null && mergeNamed !== keptMerge) {
835
+ const flag = (m) => (m ? "--merge" : "--no-merge");
836
+ die(`${flag(mergeNamed)}: this run's receipt ${receiptPath} records ${keptMerge ? "merge" : "no-merge"}, fixed for the run — run phase 0 again without ${flag(mergeNamed)}, or with ${flag(keptMerge)}`);
837
+ }
838
+ const merge = keptMerge ?? mergeNamed ?? MERGE_DEFAULT;
815
839
  if (rotated && !resumed) {
816
840
  if (existsSync(held)) {
817
841
  process.stderr.write(`${NAME}: cannot hold the previous run's receipt for the rotation: ${held} already holds another\n`);
@@ -822,7 +846,7 @@ function main() {
822
846
  }
823
847
 
824
848
  const pluginVersion = resumed && typeof previous.pluginVersion === "string" ? previous.pluginVersion : null;
825
- const receipt = { run: resumed ? previous.run : null, session, scratch, inFlight, objective, pluginVersion, steps: {} };
849
+ const receipt = { run: resumed ? previous.run : null, session, scratch, inFlight, objective, merge, pluginVersion, steps: {} };
826
850
  for (const name of STEP_NAMES) {
827
851
  // `alarm` checks the omp running this invocation, so its `ok` is never carried.
828
852
  const was = resumed && name !== "alarm" ? previous.steps[name] : undefined;
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: run-team
3
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] [cost|speed]"
4
+ argument-hint: "[in-flight] [cost|speed] [merge|no-merge]"
5
5
  disable-model-invocation: true
6
6
  ---
7
7
 
@@ -10,9 +10,8 @@ Label names in this file are roles; the Label map gives the string to type; a me
10
10
  Run `next-ticket`, `review-and-fix`, `run-merge-bot` as one fleet. You are the
11
11
  **controller**, in the main thread, never a member.
12
12
 
13
- `$ARGUMENTS` = `[in-flight] [cost|speed]`, both optional: the In-flight bound,
14
- a positive integer, default 5, and the Objective, default `cost`.
15
- Merge bot is at most one, not configurable.
13
+ `$ARGUMENTS` = `[in-flight] [cost|speed] [merge|no-merge]`, all optional: the In-flight bound, a positive integer, default 5, the Objective, default `cost`, and Merging, default `merge`.
14
+ Merge bot is at most one, none under `no-merge`.
16
15
 
17
16
  A rule ending `See references/<file>` keeps its war story there, read only for the *why*; a rule without that line carries its reasoning inline.
18
17
 
@@ -40,8 +39,8 @@ Nothing in this phase, or in any later one, asks the maintainer which tickets to
40
39
  0. **Once per run, before anything else.** Run phase 0 from a Python eval
41
40
  cell in this main checkout, without `--session`:
42
41
  `subprocess.run([os.path.expanduser("~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run"),
43
- "phase0.mjs", …], stderr=subprocess.STDOUT)`. Add `--in-flight <n>` and
44
- `--objective <o>` as `$ARGUMENTS` gave them, `--spend-dir <dir>` for the
42
+ "phase0.mjs", …], stderr=subprocess.STDOUT)`. Add `--in-flight <n>`,
43
+ `--objective <o>` and `--merge` or `--no-merge` as `$ARGUMENTS` gave them, `--spend-dir <dir>` for the
45
44
  spend panel, and `--workflow <name>` or `--declare-no-ci`
46
45
  when the repository has no workflow named CI. Its steps and receipt: See
47
46
  references/phase-0.md. Dispatch nothing before it exits 0. Exit 4 is a
@@ -167,8 +166,7 @@ owes beyond its call:
167
166
  on `DISPATCH merge-bot` dispatch the next `merge-bot-<n>` (**The merge bot**).
168
167
  **You own the watcher, not the bot.** Arm one yourself,
169
168
  `persistent: true`, seeded before the loop so handled PRs do not re-fire.
170
- **One rebase per PR, at merge time.** Any behind-count you hand a bot is
171
- expired on arrival; say so. See references/ci-and-staleness.md.
169
+ Under `no-merge` arm none. See references/ci-and-staleness.md.
172
170
  - **Merge-bot pass reports done** → `fleet-event.mjs merge-bot-report merge-bot-<n>`. A label that
173
171
  landed at the last moment reads `DISPATCH
174
172
  merge-bot` again: dispatch the next bot straight away. A conflict needs no
@@ -195,7 +193,7 @@ owes beyond its call:
195
193
  release the rest by hand and run `begin` again.
196
194
  2. Act on the review, fix-applier and merge rows until the tick prints
197
195
  `ACTION: run over → fleet-heartbeat.mjs --stop "<reason>"`, which it does
198
- once the run is draining with no open PR and no live implementer.
196
+ once a draining run has no PR holding it and no live implementer.
199
197
  3. `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run closeout.mjs finish --reason "<reason>"`, which
200
198
  records `fleet-heartbeat.mjs --stop` and then merges the Close-out PR. On `NEED merge-wait PR #<n>`,
201
199
  run `finish` again at once. A PR it names `left open` is the next run's: you never label or merge it.
@@ -381,7 +379,7 @@ It prints `actual/target` and a named ACTION per role. Act on each line as it re
381
379
  - `specs-dropped=#<N> …` — never actionable: log those tickets as specs awaiting to-tickets, not as no work.
382
380
  - `DISPATCH fix-pr PR#<M> …` — a fix-applier for that PR (review findings, a dispositions mismatch no retry has answered, or a conflict hold): render its brief with `dispatch-prompt.mjs render fix-applier --kind <kind>`, `ledger.mjs dispatch <M> fix-pr-<M>` (the next suffix when that name is already on record), then the `task` call.
383
381
  - `DISPATCH review PR#<M> …` — a review per PR, oldest first, off your turn: record `review=member:review-pr-<M>` with `ledger.mjs review <M> …`, then dispatch `review-pr-<M>`.
384
- - `DISPATCH merge-bot` — the next `merge-bot-<n>`: render its brief with `dispatch-prompt.mjs render merge-bot --member merge-bot-<n> …`, `ledger.mjs dispatch merge-bot`, then the `task` call.
382
+ - `DISPATCH merge-bot` — the next `merge-bot-<n>` (**The merge bot**).
385
383
  - `DISPATCH finisher PR#<M> …` — a finisher settled `labelled` with no label on the PR and no `label-off=` to account for it: apply the finisher gate, render the next-suffix finisher's brief with `dispatch-prompt.mjs render finisher --kind repair --member finisher-pr-<M>-<x> …`, `ledger.mjs dispatch <M> finisher-pr-<M>-<x>`, and never add the label yourself.
386
384
  - `ESCALATE unlabelled PR#<M> …` — a second finisher settled `labelled` and the label is still off: not actionable, the maintainer's.
387
385
  - `CONFLICT PR#<M> …` — record the hold with `fleet-event.mjs conflict <M>`, never with the `ledger.mjs row` form; the tick then prints `DISPATCH fix-pr`.
@@ -390,6 +388,7 @@ It prints `actual/target` and a named ACTION per role. Act on each line as it re
390
388
  - `ESCALATE pr-closed #<N> PR#<M>`, `… pr-unchecked …` — the maintainer's: tell them once per ticket per run; no dispatch or comment for #N. Reopening M or closing #N clears it. Only `replace #N` (`NEED resume`, same row) or `release #N` (closed-PR `release-ticket.sh --apply`, settle `released`) acts, once no live member names M.
391
389
  - `HOLD (…)` — the row is held and its detail names the clearing step: dispatch nothing on that row until it clears; a tier mismatch is yours to clear by dispatching the replacement.
392
390
  - `AT CAP`, `IDLE OK` — nothing to do on that row.
391
+ - `IDLE (merging off)` — nothing to do on that row: the maintainer merges.
393
392
  - `MAIN-CHECKOUT-DIRTY …` — dispatch nothing new and tell the maintainer; once they have resolved the paths, `main-checkout.mjs --record`; never revert the paths or re-baseline over them yourself.
394
393
  - `MAIN-CHECKOUT-UNKNOWN …` — the tick could not look: fix what the line names and tick again, and never `--record` over it unless the line itself says re-record (an older-format baseline, or a baseline commit missing from this repository), and then only after resolving the stray paths.
395
394
  - `MAIN-CHECKOUT-NO-BASELINE …` — yours: run `main-checkout.mjs --record`, after reporting a baseline that vanished mid-run.
@@ -751,7 +750,7 @@ decides the rest — two resolve automatically, every other one escalates:
751
750
  | `rebase` | **Escalate** — comment and flag, nothing more. The report's `evidence.replay` reads `pure` only when `git range-diff origin/main <pin> HEAD` pairs every pinned commit with an unchanged one; `changed` (a commit dropped, edited or added, or a stale `origin/main`) or `unknown` means read `evidence.rangeDiff` before acting, and `evidence.remote.state` says whether that head is on the PR. No automatic rule until a live halt shows the case recurring. |
752
751
  | `stray` | **Escalate** — comment and flag; nothing pushes it automatically. Read `evidence.cherry`, `.content` and `.remote`. Push or discard is yours, or the maintainer's if they cannot settle it. A pushed stray is unreviewed: `ledger.mjs review <M>` first. |
753
752
  | `unreadable`, `missing`, `absent`, `other` | **Escalate** — comment and flag, no automatic retry. |
754
- | `human` | **Escalate** — no retry. A Ticketless PR whose diff is not inert: the maintainer labels it (references/finisher.md). |
753
+ | `human` | **Escalate** — no retry. A Ticketless PR whose diff is not inert: the maintainer labels it (references/finisher.md), or under `no-merge` merges it by hand. |
755
754
 
756
755
  ### Resolving a finisher that died
757
756
 
@@ -189,3 +189,4 @@ worktree has to happen first. **You own the watcher, not the bot.** Arm one
189
189
  yourself, `persistent: true`, seeded before the loop so handled PRs do not
190
190
  re-fire. **One rebase per PR, at merge time.** Any behind-count you hand a bot
191
191
  is expired on arrival; say so.
192
+ Under `no-merge` there is no bot, so arm no watcher.
@@ -1,5 +1,7 @@
1
1
  # Close-out: what each metrics step does and why
2
2
 
3
+ Label names in this file are roles; the Label map gives the string to type; a member never derives the map.
4
+
3
5
  `closeout.mjs finish` runs the scrape, the tier-outcomes check, the metrics refresh, the gather of the run records and the review evidence, the commit of the metrics and record files, and the phase-0 receipt move, and SKILL.md's **End of run** says how to drive it. This file is how each of those works, for the controller to read when a step refuses, and how `closeout.mjs reopen` undoes a drain. The verdict rules — what `closed_own_ticket` and `minted_false_claim` mean, and that a value not in hand is left blank — stay in SKILL.md under **Guard: accumulate per PR**, because the controller still rules them.
4
6
 
5
7
  - **The run ends, or the maintainer says drain** → `fleet-event.mjs drain --reason "<reason>"`
@@ -17,6 +19,10 @@
17
19
  2. Act on the review, fix-applier and merge rows until the tick prints
18
20
  `ACTION: run over → fleet-heartbeat.mjs --stop "<reason>"`, which it does
19
21
  once the run is draining with no open PR and no live implementer.
22
+ Under `no-merge` a PR carrying `ready-to-merge` holds nothing once GitHub reads it
23
+ MERGEABLE, no conflict hold stands on it and no finisher, fix-applier or review is
24
+ still at work on it: those PRs stay open for the maintainer, or for a later run's
25
+ phase 0 to fold in.
20
26
  3. `~/.omp/plugins/node_modules/@feigi/fleet-ctl/scripts/fleet-run closeout.mjs finish --reason "<reason>"` — scrapes
21
27
  the run's member facts, checks the tier-outcomes rows, refreshes the
22
28
  metrics, gathers the earlier runs' records and the review evidence,
@@ -392,6 +392,7 @@ as for a `past-pin` re-review below, before any finisher is dispatched.
392
392
  A `human` halt is a Ticketless PR whose diff is not inert: the maintainer adds
393
393
  `ready-to-merge` at the pinned head, which the merge bot merges off the
394
394
  finisher's `ready-to-merge-head:` comment; a moved head is merged by hand.
395
+ Under `no-merge` no bot runs: the maintainer merges it by hand, labelled or not.
395
396
 
396
397
  The tick prints `DISPATCH review PR#<M>` for a PR whose latest finisher is `halted:past-pin` and whose latest `reviewed=<head>` is not its current head, until a review of it is running or has returned; record that review's launch as any review's, with `ledger.mjs review <M>` onto the PR's row, its runner under the next letter the PR's rows do not carry yet (`review-pr-<M>-b`, or `-c` where a retry already took `-b`) — `review` refuses a second `review-pr-<M>` and names the free one — and its result, recorded by the `review-result` wake, reaches a fresh finisher through the same gate.
397
398
 
@@ -23,6 +23,17 @@ by it. It is fixed for the run: a resumed receipt keeps the one it records —
23
23
  other exits 2 naming both, leaving the receipt as it was. A resumed receipt
24
24
  recording anything other than `cost` or `speed` exits 3 naming the value.
25
25
 
26
+ `--merge` or `--no-merge` is whether the run's merge bot merges, which phase 0
27
+ records in its receipt as `merge: true` or `merge: false`, `true` when neither
28
+ is given; both together exit 2. With `no-merge` the fleet takes each PR as far
29
+ as `ready-to-merge` and the maintainer merges it: the tick dispatches no merge
30
+ bot, a draining run can be over with `ready-to-merge` PRs still open, and it reaps
31
+ after each PR it reads merged. It is fixed for the run: a resumed receipt keeps
32
+ the one it records — `merge` when it records none — and a resume that names the
33
+ other exits 2 naming both, leaving the receipt as it was. A resumed receipt
34
+ recording anything but `true` or `false` exits 3 naming the value. The tick
35
+ reads it from this receipt and from no flag of its own.
36
+
26
37
  Exit 3 is a step that failed: its line carries the refusal, so fix the cause
27
38
  and run it again.
28
39
 
@@ -163,7 +163,21 @@ The full text of each row `fleet-tick.mjs` prints and what it asks of the contro
163
163
  caller's. `transcript`/`session` resolve relative to `--repo` (defaults to
164
164
  the plugin's own root), and the check reads and writes the run's own ledger
165
165
  unless `--ledger` names another.
166
+ With merging off the In-flight hold reads `HOLD (in-flight <n>/<B>, awaiting
167
+ human merge)`: the merge that brings n below B is the maintainer's, and
168
+ a replacement the detail names is still yours to dispatch.
166
169
  - `AT CAP`, `IDLE OK` — nothing to do on that row.
170
+ - `IDLE (merging off)` — the run's merge bot is off (`--no-merge`, which phase
171
+ 0 records in its receipt as `merge: false`), so the merge-bot row prints it
172
+ whatever the queue holds and never `DISPATCH merge-bot`. Nothing to do on
173
+ that row: the maintainer merges what carries `ready-to-merge`. Such a PR
174
+ still counts toward the In-flight bound until then, a `CONFLICT PR#<M> …`
175
+ line still reaches a fix-applier, and `tick --apply` reaps, reclaims and
176
+ evicts once after each PR the run tracks that gh reads MERGED. A draining
177
+ run is over with only `ready-to-merge` PRs open; one that GitHub has not
178
+ read MERGEABLE (CONFLICTING, or UNKNOWN until it answers), one a conflict
179
+ hold stands on, and one a finisher, fix-applier or review is still at work
180
+ on each still hold it.
167
181
  - `MAIN-CHECKOUT-DIRTY <paths> …`, printed above the rows, with every
168
182
  dispatching row (implementers, reviewers, merge-bot) reading
169
183
  `HOLD (main checkout dirty)` — the main checkout changed since the Phase 0
@@ -299,6 +313,8 @@ a guess is the over- or under-dispatch it exists to prevent — so correct that
299
313
  row with `ledger.mjs row` and tick again. The In-flight bound defaults to 5
300
314
  and is fixed for the run: pass `--in-flight` on every tick when `$ARGUMENTS`
301
315
  set it, and never otherwise.
316
+ Whether the merge bot merges is the phase-0 receipt's `merge`, `true` when it
317
+ records none, and never a flag of the tick's.
302
318
 
303
319
  ## Refresh is the tick's
304
320