@feigi/fleet-ctl 3.47.1 → 3.47.3

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.47.1",
3
+ "version": "3.47.3",
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": {
@@ -193,7 +193,13 @@ function main() {
193
193
  // No hold, and `elapsed` untouched: this invocation is not a beat, it is
194
194
  // the run saying why there will not be another one. Leaving the partial
195
195
  // interval where it is costs nothing — the next run reads a stopped mark
196
- // and knows the streak behind it is a dead run's.
196
+ // and knows the streak behind it is a dead run's. Leave degraded files
197
+ // byte-identical, so a same-session rotate still refuses rather than
198
+ // judges none.
199
+ if (state.degraded) {
200
+ console.log(`heartbeat: stop NOT recorded (${stop}) — the heartbeat file is degraded and was left as it is, so a same-session rotate refuses on it until it is repaired`);
201
+ return;
202
+ }
197
203
  const persisted = writeState(path, NAME, state, { beat: mark(target, stop) });
198
204
  // Announced on stdout as well as through writeState's own stderr warning,
199
205
  // and still exit 0. An unrecorded stop is a real degradation — the next
@@ -231,13 +237,15 @@ function main() {
231
237
  // taking one of its own. One write per invocation means a mark can never
232
238
  // land while the progress it was taken beside did not, and the two can
233
239
  // never disagree about which invocation they came from. It also keeps the
234
- // failure story single: the warning below covers both keys at once.
240
+ // failure story single: the warning below covers both keys at once. Leave
241
+ // degraded files byte-identical, so a same-session rotate still refuses
242
+ // rather than judges none — a skipped write reports a fire like a failed one.
235
243
  //
236
244
  // `stopped: ""` on every ordinary beat, never carried forward: a run that
237
245
  // recorded a stop and then kept beating is a run that did not stop, and a
238
246
  // stale reason surviving into a live beat would have the next reader
239
247
  // announcing a death that already un-happened.
240
- const persisted = writeState(path, NAME, now, { elapsed: reached ? 0 : elapsed, beat: mark(target, "") });
248
+ const persisted = !now.degraded && writeState(path, NAME, now, { elapsed: reached ? 0 : elapsed, beat: mark(target, "") });
241
249
  // A failed write is itself a fire. With nothing persisting the remainder,
242
250
  // every invocation reads the same elapsed total, holds the same seconds and
243
251
  // prints the same remainder: the interval can never complete, so fleet-tick
@@ -263,8 +271,13 @@ function main() {
263
271
  // `quiet=` is the pre-hold streak, the one the interval was DERIVED from: a
264
272
  // fresh streak printed beside a target computed from the old one would be two
265
273
  // numbers that do not explain each other.
274
+ //
275
+ // A skipped write says so, on the fire it reports: the interval did not
276
+ // elapse, the file could not keep its progress, and this call fires again
277
+ // on every hold until the file is repaired.
278
+ const skippedNote = now.degraded ? " — the heartbeat file is degraded and was left as it is, so interval progress is not kept and every hold fires" : "";
266
279
  console.log(done
267
- ? `heartbeat: held ${held}s, ${target}s interval elapsed (quiet=${state.quiet}) → run fleet-tick`
280
+ ? `heartbeat: held ${held}s, ${target}s interval elapsed (quiet=${state.quiet}) → run fleet-tick${skippedNote}`
268
281
  : `heartbeat: held ${held}s, ${target - elapsed}s of ${target}s remain (quiet=${state.quiet}) → re-issue this command now, do not end your turn`);
269
282
  }
270
283
 
@@ -108,9 +108,11 @@ const PRIORS = ["dead", "ancestor", "none"];
108
108
  // Absent is the ONLY silent case, because it is the only one that is not a
109
109
  // fault: a fresh run legitimately has no file yet. An unreadable file and a
110
110
  // corrupt one are both announced — each discards real state, and silence about
111
- // a degraded read is the failure class this whole ticket exists to close. Both
112
- // come back flagged `degraded`, for the one caller that must not read them as
113
- // a file with nothing in it.
111
+ // a degraded read is the failure class this whole ticket exists to close. So
112
+ // is a file that parses but whose `controller` key holds no record `ctl`
113
+ // below accepts: it reads as no record, and the next write would drop the
114
+ // key. All of them come back flagged `degraded`, for the one caller that
115
+ // must not read them as a file with nothing in it.
114
116
  export function readState(path, name) {
115
117
  // `beat: null` is the absent MARK, and it is not the same value as a mark
116
118
  // whose fields are zero: nothing has been seen beating, so there is nothing
@@ -120,8 +122,10 @@ export function readState(path, name) {
120
122
  const fresh = { quiet: 0, elapsed: 0, digest: "", beat: null, ticked: null, acted: null, controller: null, seen: {}, rest: {} };
121
123
  // The same state, flagged: the file EXISTS and could not be used. A caller
122
124
  // that acts on the absence of a record — ledger.mjs rotate — must tell this
123
- // from `fresh`, which is a run that has simply not written one yet.
124
- const degraded = { ...fresh, degraded: true };
125
+ // from `fresh`, which is a run that has simply not written one yet. The
126
+ // `degraded` field is absent on a fresh read, else a phrase for the cause
127
+ // that completes "<file> …" in rotate's refusal.
128
+ const makeDegraded = (cause) => ({ ...fresh, degraded: cause });
125
129
  let raw;
126
130
  try {
127
131
  raw = readFileSync(path, "utf8");
@@ -136,7 +140,7 @@ export function readState(path, name) {
136
140
  // whole ticket exists to close.
137
141
  if (e.code !== "ENOENT") {
138
142
  console.error(`${name}: WARNING could not read ${path} (${e.message}) — restarting at the base interval`);
139
- return degraded;
143
+ return makeDegraded("exists but cannot be read");
140
144
  }
141
145
  return fresh;
142
146
  }
@@ -145,14 +149,16 @@ export function readState(path, name) {
145
149
  parsed = JSON.parse(raw);
146
150
  } catch (e) {
147
151
  console.error(`${name}: WARNING ${path} is not JSON (${e.message}) — restarting at the base interval`);
148
- return degraded;
152
+ return makeDegraded("is not JSON");
149
153
  }
150
154
  if (!isRecord(parsed)) {
151
155
  console.error(`${name}: WARNING ${path} is not an object — restarting at the base interval`);
152
- return degraded;
156
+ return makeDegraded("is not a JSON object");
153
157
  }
154
158
  // Per-field validation, not all-or-nothing: a file carrying a good `quiet`
155
159
  // and a junk `elapsed` keeps the streak instead of losing both to one key.
160
+ // The exception is `controller`, below: a record that cannot be judged
161
+ // flags the whole file, because a write that dropped it is the loss.
156
162
  const num = (v) => (typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : 0);
157
163
  // `rest` is strictly what lies OUTSIDE the schema, which is what makes the
158
164
  // patch write below a patch rather than a laundering step. A raw copy of
@@ -193,12 +199,13 @@ export function readState(path, name) {
193
199
  };
194
200
  // `controller` is validated as a unit for the mark's reason: a pid without
195
201
  // the start time it was recorded with cannot be told from a reused pid. A
196
- // pid outside the range a process id can take is no record either, since
197
- // no process could ever answer for it. `prior` degrades like `stopped`
198
- // does: a junk verdict proves nothing, so it reads as "none", and the
199
- // record around it still names a controller to judge. `at` degrades the
200
- // same way, to null: the record still names a controller, and only when it
201
- // was written is unknown.
202
+ // pid outside the range a process id can take is not a record either, since
203
+ // no process could ever answer for it. A `controller` key that fails this
204
+ // is not read as no record: it degrades the whole file, below. `prior`
205
+ // degrades like `stopped` does: a junk verdict proves nothing, so it reads
206
+ // as "none", and the record around it still names a controller to judge.
207
+ // `at` degrades the same way, to null: the record still names a
208
+ // controller, and only when it was written is unknown.
202
209
  const ctl = (v) => {
203
210
  if (!isRecord(v)) return null;
204
211
  if (!Number.isInteger(v.pid) || v.pid < 1 || v.pid > 0x7fffffff) return null;
@@ -221,6 +228,14 @@ export function readState(path, name) {
221
228
  return out;
222
229
  };
223
230
  const { quiet, elapsed, digest, beat, ticked, acted, controller, seen, ...rest } = parsed;
231
+ // A controller key that ctl() rejects is a record someone wrote and nobody
232
+ // can judge, not the absence of one — announced like the other degraded
233
+ // causes, and flagged.
234
+ const record = ctl(controller);
235
+ if ("controller" in parsed && record === null) {
236
+ console.error(`${name}: WARNING ${path} holds a controller record that cannot be judged — restarting at the base interval`);
237
+ return makeDegraded("holds a controller record that cannot be judged");
238
+ }
224
239
  return {
225
240
  quiet: num(quiet),
226
241
  elapsed: num(elapsed),
@@ -228,7 +243,7 @@ export function readState(path, name) {
228
243
  beat: mark(beat),
229
244
  ticked: tick(ticked),
230
245
  acted: tick(acted),
231
- controller: ctl(controller),
246
+ controller: record,
232
247
  seen: stamps(seen),
233
248
  rest,
234
249
  };
@@ -1526,14 +1526,18 @@ function main() {
1526
1526
  const digest = createHash("sha256").update(lines.join("\n")).digest("hex");
1527
1527
  const acts = actionable(rows) || over;
1528
1528
  // `seen` is pruned to the live set on the same write; an empty one removes
1529
- // the key. `ticked` was written at the top of the tick, unless the file
1530
- // could not be read then: this write replaces such a file, so it carries
1531
- // the stamp the top of the tick left out.
1532
- writeState(path, NAME, prev, {
1533
- quiet: acts ? 0 : prev.quiet + 1, digest,
1534
- seen: Object.keys(seen).length > 0 ? seen : undefined,
1535
- ...(priorState.degraded ? { ticked: { at: tickedAt } } : {}),
1536
- });
1529
+ // the key. A file that was degraded at this read is left byte-identical, so
1530
+ // a same-session rotate still refuses rather than judges none. `ticked` was
1531
+ // written at the top of the tick unless the file was degraded then; one
1532
+ // repaired since reaches this write without it, so this write carries the
1533
+ // stamp the top of the tick left out.
1534
+ if (!prev.degraded) {
1535
+ writeState(path, NAME, prev, {
1536
+ quiet: acts ? 0 : prev.quiet + 1, digest,
1537
+ seen: Object.keys(seen).length > 0 ? seen : undefined,
1538
+ ...(priorState.degraded ? { ticked: { at: tickedAt } } : {}),
1539
+ });
1540
+ }
1537
1541
 
1538
1542
  // Fold only when BOTH hold: nothing to act on, and nothing new to say. A
1539
1543
  // main-checkout hold still holding dispatch stays named on the folded line
@@ -1484,12 +1484,14 @@ function runCheck() {
1484
1484
  // allows the rotation. With no record the guard falls back to the mark, read
1485
1485
  // through fleet-state.mjs's own reader and verdict: still beating — a beat
1486
1486
  // inside its window, or past it with a tick or ledger write inside
1487
- // theirs — refuses; a stalled mark, a recorded stop, or no beat at all allows
1488
- // the rotation, and that fallback proves "not beating", never "dead".
1487
+ // theirs — refuses, and so does a tick or ledger write inside its window
1488
+ // with no beat at all; a stalled mark, a recorded stop, or no mark at all
1489
+ // allows the rotation, and that fallback proves "not beating", never "dead".
1489
1490
  //
1490
- // A heartbeat file that exists but cannot be read or parsed gets neither
1491
- // verdict: a record it may hold cannot be known, so rotate refuses rather
1492
- // than read the fault as "no record".
1491
+ // A heartbeat file that exists but cannot be used — unreadable, not JSON, not
1492
+ // a JSON object, or holding a `controller` key that cannot be judged — gets
1493
+ // neither verdict: a record it may hold cannot be known, so rotate refuses
1494
+ // rather than read the fault as "no record".
1493
1495
  //
1494
1496
  // Its last act, whether or not there was a ledger to move, replaces the
1495
1497
  // record with this run's own, carrying the verdict as `prior` — the next
@@ -1510,7 +1512,7 @@ function runRotate() {
1510
1512
  // reading it as "no record" would let a live controller's ledger be moved
1511
1513
  // by exactly the fault that hid its record.
1512
1514
  if (state.degraded) {
1513
- die(`refusing to rotate ${file}: ${beatFile} exists but cannot be read or parsed, so a controller record in it cannot be judged — repair or remove it`);
1515
+ die(`refusing to rotate ${file}: ${beatFile} ${state.degraded} — repair it so its controller record is intact. Removing it makes this rotate judge none: if the previous run was this omp session's, its live members and retired names are not carried forward, so this run can dispatch onto their work and reuse their names.`);
1514
1516
  }
1515
1517
  let prior, ours;
1516
1518
  try {
@@ -1527,9 +1529,17 @@ function runRotate() {
1527
1529
  }
1528
1530
  // The fallback guards a ledger, as it always has: with none to move there
1529
1531
  // is nothing for a beating mark to protect. A ledger write is the
1530
- // controller acting, and counts the way a beat does.
1532
+ // controller acting, and counts the way a beat does. Refuse when the beat
1533
+ // is beating, and also — the one state assessBeat reads as `none`, because
1534
+ // the cockpit shows no panel without a record — when there is no beat at
1535
+ // all and a tick or ledger write is still inside its window: a record lost
1536
+ // to a removed file leaves exactly that. A recorded stop reads `stopped`
1537
+ // through assessBeat, so it lets the rotation through.
1531
1538
  const exists = existsSync(file);
1532
- if (prior === "none" && exists && assessBeat({ beat, ticked, acted, now: Date.now() }).kind === "beating") {
1539
+ const judgedAt = Date.now();
1540
+ const markWindowEnd = beat === null ? stallsAt({ ticked, acted }) : null;
1541
+ const actingWithoutBeat = markWindowEnd !== null && judgedAt <= markWindowEnd;
1542
+ if (prior === "none" && exists && (actingWithoutBeat || assessBeat({ beat, ticked, acted, now: judgedAt }).kind === "beating")) {
1533
1543
  const [what, mark] = [["beat", beat], ["tick", ticked], ["ledger write", acted]]
1534
1544
  .filter(([, m]) => m !== null)
1535
1545
  .reduce((a, b) => (b[1].at > a[1].at ? b : a));
@@ -65,11 +65,12 @@
65
65
  // never a path.
66
66
  // unknown — some read failed: git, a hash, HEAD, `origin/main`, or a baseline
67
67
  // that EXISTS but cannot be read (unreadable file, unsearchable
68
- // `.fleet/`, dangling symlink, not written by --record) — or is a
69
- // v1 baseline, which says nothing of HEAD: re-record it — or names
70
- // a commit absent from the repository: examine HEAD, then
71
- // re-record it. "A failure is an unknown answer, never a 'no'" —
72
- // never `clean`.
68
+ // `.fleet/`, dangling symlink, not written by --record) — or is
69
+ // an older version's baseline, which this code cannot compare:
70
+ // re-record it — or is a newer version's, written by a newer
71
+ // plugin: run that plugin — or names a commit absent from the
72
+ // repository: examine HEAD, then re-record it. "A failure is an
73
+ // unknown answer, never a 'no'" — never `clean`.
73
74
  // absent — no baseline at all: the run never recorded one. A refusal
74
75
  // ("record at run start"), never `clean`.
75
76
  //
@@ -78,10 +79,11 @@
78
79
  // the maintainer's clear only AFTER the stray paths are resolved. Over `unknown`
79
80
  // it would walk the run from "could not look" to "certified clean" in one step,
80
81
  // so it refuses on every unknown cause it can see: a baseline that exists but
81
- // cannot be read, and any failed git or hash read (no snapshot, nothing to
82
- // write). A detached HEAD has no symbolic ref to record, so it refuses that
83
- // too. A v1 baseline, and one whose commit is gone (it never reads the
84
- // recorded commit), it overwrites without a word.
82
+ // cannot be read, one a newer plugin wrote (overwriting it would discard a
83
+ // baseline nobody read), and any failed git or hash read (no snapshot, nothing
84
+ // to write). A detached HEAD has no symbolic ref to record, so it refuses that
85
+ // too. An older version's baseline, and one whose commit is gone (it never
86
+ // reads the recorded commit), it overwrites without a word.
85
87
  //
86
88
  // A BASELINE COMMIT GONE FROM THE REPOSITORY is its own unknown. An amend or
87
89
  // reset leaves the baseline's commit unreachable, and once reflog expiry and
@@ -121,8 +123,12 @@ import { gitEnv, workspaceDirFromGitCommonDir } from "./git-env.mjs";
121
123
  export const BASELINE_FILE = "main-checkout.sha";
122
124
  export const RECORD_COMMAND = "~/.fleet/bin/fleet-run main-checkout.mjs --record";
123
125
  const RUN_BOOKKEEPING = new Set(["docs/metrics/tier-outcomes.tsv", "docs/metrics/member-outcomes.tsv", "docs/metrics/ticket-features.tsv"]);
124
- const HEADER_V1 = "fleet main-checkout baseline v1";
125
- const HEADER = "fleet main-checkout baseline v2";
126
+ // Any change to an entry's hash or to a line's format bumps VERSION: a
127
+ // baseline an older plugin wrote then reads `outdated` (re-record) and one a
128
+ // newer plugin wrote reads `newer`, never as a baseline this code wrote.
129
+ const VERSION = 2;
130
+ const HEADER = `fleet main-checkout baseline v${VERSION}`;
131
+ const HEADER_RE = /^fleet main-checkout baseline v(\d+)$/;
126
132
  const GIT_TIMEOUT_MS = 30_000;
127
133
  const MAX_BUFFER = 64 * 1024 * 1024;
128
134
  const NAME = "main-checkout";
@@ -320,7 +326,8 @@ function headMove(root, env, was, now) {
320
326
 
321
327
  /**
322
328
  * The run's baseline: `{status: "ok", entries, head}`, `{status: "absent"}`,
323
- * `{status: "outdated", why}` (a v1 file) or `{status: "unreadable", why}`.
329
+ * `{status: "outdated", why}` (an older VERSION's file), `{status: "newer",
330
+ * why}` (a newer VERSION's) or `{status: "unreadable", why}`.
324
331
  * ABSENT is only "nothing at that name": a
325
332
  * dangling symlink is present-but-broken, and an unsearchable `.fleet/`
326
333
  * answers EACCES rather than ENOENT, so neither can fall through to
@@ -343,7 +350,9 @@ export function readBaseline(path) {
343
350
  return { status: "unreadable", why: `${path} exists but cannot be read: ${e?.code ?? e?.message}` };
344
351
  }
345
352
  const lines = text.split("\n");
346
- if (lines[0] === HEADER_V1) return { status: "outdated", why: "baseline v1 — re-record" };
353
+ const version = HEADER_RE.exec(lines[0]);
354
+ if (version && Number(version[1]) < VERSION) return { status: "outdated", why: `baseline v${version[1]} — re-record` };
355
+ if (version && Number(version[1]) > VERSION) return { status: "newer", why: `baseline v${version[1]} written by a newer plugin` };
347
356
  const ref = lines[1]?.startsWith("ref ") ? lines[1].slice(4) : "";
348
357
  const oid = lines[2]?.startsWith("oid ") ? lines[2].slice(4) : "";
349
358
  if (lines[0] !== HEADER || lines.at(-1) !== "" || !ref || !/^[0-9a-f]{40,64}$/.test(oid)) {
@@ -370,10 +379,11 @@ export function changedPaths(baseline, current) {
370
379
 
371
380
  /**
372
381
  * The tick's question: `{state, root?, baseline?, changed?, headMove?, why?, cause?}`.
373
- * `cause` tells the four unknowns apart — `"baseline"` (it exists but cannot
374
- * be read), `"outdated"` (a v1 baseline: it says nothing of HEAD, so it can
375
- * answer nothing), `"missing"` (the baseline's commit is absent from the
376
- * repository) and `"read"` (git or a hash failed) — since each has its own
382
+ * `cause` tells the unknowns apart — `"baseline"` (it exists but cannot
383
+ * be read), `"outdated"` (an older version's baseline: this code cannot
384
+ * compare it, so it can answer nothing), `"newer"` (a newer plugin wrote it),
385
+ * `"missing"` (the baseline's commit is absent from the repository) and
386
+ * `"read"` (git or a hash failed) — since each has its own
377
387
  * message. The baseline is read before the tree, because without one there
378
388
  * is nothing to compare against and no reason to look.
379
389
  * A HEAD move is the first entry of `changed`, also named in `headMove`.
@@ -388,6 +398,7 @@ export function checkMainCheckout({ cwd = process.cwd(), env = process.env } = {
388
398
  const unknown = (why, cause = "read") => ({ state: "unknown", cause, root, baseline: path, why });
389
399
  if (base.status === "unreadable") return unknown(base.why, "baseline");
390
400
  if (base.status === "outdated") return unknown(base.why, "outdated");
401
+ if (base.status === "newer") return unknown(base.why, "newer");
391
402
  const now = readState(root, env);
392
403
  if (!now.ok) return unknown(now.why);
393
404
  const move = headMove(root, env, base.head, now.head);
@@ -426,6 +437,7 @@ export function describe(check, live = null) {
426
437
  return `MAIN-CHECKOUT-UNKNOWN ${check.why}${members}`
427
438
  + ` — dispatch held: resolve any stray paths FIRST, then re-record with ${RECORD_COMMAND} (it overwrites, it does not compare)`;
428
439
  }
440
+ if (check.cause === "newer") return `MAIN-CHECKOUT-UNKNOWN ${check.why}${members} — dispatch held: run the plugin that wrote it`;
429
441
  if (check.cause === "missing") {
430
442
  return `MAIN-CHECKOUT-UNKNOWN ${check.why}${members}`
431
443
  + " — dispatch held: examine HEAD against origin/main FIRST, since a missing baseline commit means HEAD moved off it by an amend or reset nobody has looked at, and resolve any stray paths;"
@@ -441,10 +453,11 @@ export function describe(check, live = null) {
441
453
 
442
454
  /**
443
455
  * Write the baseline: `{ok, path, entries, head}` or `{ok: false, why}`.
444
- * Refuses over a baseline that exists but cannot be read — overwriting it
445
- * blind discards evidence nobody read — and on any failed read of the tree, of
446
- * HEAD or of `origin/main`, and on a detached HEAD, which has no symbolic ref
447
- * to record. A v1 baseline is not unreadable: it is the one this overwrites.
456
+ * Refuses over a baseline that exists but cannot be read, and over one a
457
+ * newer plugin wrote — overwriting either blind discards evidence nobody
458
+ * read — and on any failed read of the tree, of HEAD or of `origin/main`, and
459
+ * on a detached HEAD, which has no symbolic ref to record. An older version's
460
+ * baseline is not unreadable: it is the one this overwrites.
448
461
  * Written to a temporary name and renamed, so a reader never sees half of it.
449
462
  */
450
463
  export function recordBaseline({ cwd = process.cwd(), env = process.env } = {}) {
@@ -455,6 +468,9 @@ export function recordBaseline({ cwd = process.cwd(), env = process.env } = {})
455
468
  if (prior.status === "unreadable") {
456
469
  return { ok: false, why: `${prior.why} — fix it first; do NOT --record over it, --record overwrites rather than compares` };
457
470
  }
471
+ if (prior.status === "newer") {
472
+ return { ok: false, why: `${prior.why} — run the plugin that wrote it; do NOT --record over it, --record overwrites rather than compares` };
473
+ }
458
474
  const now = readState(where.root, env);
459
475
  if (!now.ok) return { ok: false, why: `${now.why} — could not look, so there is nothing to record` };
460
476
  if (now.head.ref === null) {
@@ -307,10 +307,11 @@ phase, or in any later one, asks the maintainer which tickets to take.
307
307
  them — and only then re-runs `--record`; re-recording over unresolved paths
308
308
  certifies them. **Never re-record over `MAIN-CHECKOUT-UNKNOWN`**: that
309
309
  walks the run from "could not look" to "certified clean" in one step, so
310
- `--record` itself refuses over a baseline it cannot read and on any git
311
- read that fails. The exceptions are a v1 baseline and a baseline whose
312
- commit is missing from the repository; Phase 3's tick lines say how each
313
- is cleared. `main-checkout.mjs --check` prints the same answer
310
+ `--record` itself refuses over a baseline it cannot read, over one a newer
311
+ plugin wrote, and on any git read that fails. The exceptions are an
312
+ older-version baseline and a baseline whose commit is missing from the
313
+ repository; Phase 3's tick lines say how each is cleared.
314
+ `main-checkout.mjs --check` prints the same answer
314
315
  without a tick.
315
316
 
316
317
  **Run the pre-flight, once the pin and the baseline are recorded.**
@@ -450,16 +451,25 @@ phase, or in any later one, asks the maintainer which tickets to take.
450
451
  controller can stop beating and keep dispatching. A dead one, a pid
451
452
  reused by another process, or this session's own earlier run lets it
452
453
  rotate. With no record the heartbeat mark decides, as the only guard
453
- there is: still beating or acting refuses, naming the latest beat, tick or
454
- ledger write and when it would count as stalled; a stalled mark, a
455
- recorded `--stop`, or no beat at all lets it rotate — and that fallback
456
- proves "not beating", never "dead", and
454
+ there is: still beating or acting — a beat inside its window, or with no
455
+ beat at all a tick or ledger write inside its window — refuses, naming
456
+ the latest beat, tick or ledger write and when it would count as stalled;
457
+ a stalled mark, a recorded `--stop`, or no mark at all lets it rotate —
458
+ and that fallback proves "not beating", never "dead", and
457
459
  guards a ledger only: with none to move the mark is not consulted. With no
458
460
  ledger the record is still judged, so a live recorded controller refuses
459
461
  even then. It also refuses, nothing moved, when the stamped archive name
460
462
  already exists, when the process table cannot be read, or when
461
- `.fleet/heartbeat.json` exists but cannot be read or parsed — a record
462
- nobody could judge is never taken for no record. Its last act, ledger or none, is
463
+ `.fleet/heartbeat.json` exists but cannot be used — unreadable, not JSON,
464
+ not a JSON object, or holding a `controller` that cannot be judged — a
465
+ record nobody could judge is never taken for no record. On that refusal
466
+ phase 0 stops and the refusal goes to the maintainer verbatim: the
467
+ controller never edits or removes `.fleet/heartbeat.json`, because
468
+ removing it inside a live omp session makes this rotate judge `none` and
469
+ forfeits the carry — the live members and the retired names — so this
470
+ run could dispatch onto their work and reuse their names. Every writer
471
+ (`fleet-tick.mjs`, `fleet-heartbeat.mjs`, the ledger's write subcommands)
472
+ leaves such a file as it is. Its last act, ledger or none, is
463
473
  to replace the record with this run's own — the nearest `omp` process
464
474
  above it, its start time, as `prior` the verdict it reached on the
465
475
  record it found (`dead`, `ancestor` or `none`), and as `at` when it wrote
@@ -1963,13 +1973,15 @@ depth** guard table applied in code. Act on each line as it reads:
1963
1973
  could not look: a git or hash read failed (`could not look:`), or the
1964
1974
  baseline exists but cannot be read (`baseline unreadable:`). Never clean,
1965
1975
  and **never re-baseline over it** — `--record` overwrites, so that certifies
1966
- a tree nobody read. Fix what the line names and tick again. The exceptions
1967
- are the two whose remedy is `--record`: `baseline v1 — re-record`, an
1968
- old-format baseline that says nothing of HEAD; and `baseline commit <oid> is
1969
- missing from this repository`, which an amend or reset followed by gc
1970
- leaves — examine HEAD against `origin/main` FIRST, since HEAD moved off
1971
- that commit and nobody has looked at the move, and resolve any stray paths,
1972
- which the line does not name; only then re-record.
1976
+ a tree nobody read. Fix what the line names and tick again. `baseline v<n>
1977
+ written by a newer plugin` is a baseline a newer plugin version wrote:
1978
+ `--record` refuses over it too — run the plugin that wrote it. The
1979
+ exceptions are the two whose remedy is `--record`: `baseline v<n> —
1980
+ re-record`, an older-format baseline this plugin cannot compare; and
1981
+ `baseline commit <oid> is missing from this repository`, which an amend or
1982
+ reset followed by gc leaves — examine HEAD against `origin/main` FIRST,
1983
+ since HEAD moved off that commit and nobody has looked at the move, and
1984
+ resolve any stray paths, which the line does not name; only then re-record.
1973
1985
  - `MAIN-CHECKOUT-NO-BASELINE …` with `HOLD (main checkout no baseline)` — no
1974
1986
  baseline was recorded. Yours to fix: run Phase 0's `--record`. A baseline
1975
1987
  that vanished mid-run is not a fresh run — report it to the maintainer
@@ -4278,10 +4290,13 @@ live count from it, so nobody states one. Write neither by hand:
4278
4290
  `## Retired` (phase 0 says which). Refused
4279
4291
  while the recorded controller is alive and not this run's ancestor, ledger
4280
4292
  or none — or, with no record and a ledger to move, while the heartbeat mark
4281
- is still beating — or when the archive name already exists, the process
4282
- table or `.fleet/heartbeat.json` cannot be read; with no ledger and no such
4283
- refusal it moves nothing and exits 0. Then it records this run's controller
4284
- in `.fleet/heartbeat.json`. Phase 0 states the guard.
4293
+ is still beating, or a tick or ledger write is inside its window with no
4294
+ beat — or when the archive name already exists, the process
4295
+ table cannot be read, or `.fleet/heartbeat.json` exists but cannot be used
4296
+ (unreadable, not JSON, not an object, or a `controller` it cannot judge);
4297
+ with no ledger and no such refusal it moves nothing and exits 0. Then it
4298
+ records this run's controller in `.fleet/heartbeat.json`. Phase 0 states
4299
+ the guard.
4285
4300
 
4286
4301
  `row` refuses a malformed member token anywhere in its text — one whose outcome
4287
4302
  is outside the vocabulary above, e.g. `merge-bot-1=dispatched` — at exit 2,