@feigi/fleet-ctl 3.87.1 → 3.88.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feigi/fleet-ctl",
-  "version": "3.87.1",
+  "version": "3.88.0",
   "description": "Agent fleet: run-team controller, merge bot, PR reviewer, and the ticket pipeline they share",
   "license": "Apache-2.0",
   "repository": {

package/scripts/fleet-event.mjs

@@ -126,8 +126,8 @@
 //   heartbeat
 //       No write: the tick runs with `--fold-unchanged`, which prints one line
 //       instead of the rows when the tick asks for nothing and says what the
-//       last one said. The hold itself stays `fleet-heartbeat.mjs`, whose
-//       interval-elapsed line names this command.
+//       last one said. The alarm turn that runs it is started by
+//       `controller-alarm.mjs`, once the beat `fleet-heartbeat.mjs` marked falls due.
 //   drain --reason "<reason>"
 //       `closeout.mjs begin --reason "<reason>"`, its output printed as it
 //       stands, then the tick.

package/scripts/fleet-heartbeat.mjs

@@ -6,37 +6,39 @@
 // every other invocation is a wake: a member report, a label, a CI run ending.
 // A drained fleet emits no wakes at all — no implementer completions, no merge
 // activity — so nothing calls the tick and the stall is silent again. This
-// script is the level-check that needs no
-// event: it holds the controller's turn for an interval and then tells it to
-// run the tick.
+// script is the level-check that needs no event: it marks when the controller
+// went idle and how long the next level-check may wait, and the controller then
+// ends its turn. The alarm (controller-alarm.mjs, an omp extension loaded into
+// the controller's own session) starts the next turn once the mark has fallen
+// due, and that turn runs the tick.
 //
-// WHY A HOLD AND NOT A WATCHER — the ruling, measured before it was made:
+// WHY AN ALARM AND NOT A WATCHER — the ruling, measured before it was made:
 //
 //   A backgrounded watcher does not wake an idle agent. Measured twice in one
 //   run (run-team/references/member-lifecycle.md, "A member runs its test suite in the foreground"):
 //   `fix-pr-1184` backgrounded its suite plus a Monitor and sat idle for
 //   roughly two hours; neither ever woke it. run-merge-bot.md's CI gate states
 //   the same rule as a rule — "whatever wakes you is external and may never
-//   come" — and cures it the same way this file does, by holding the wait
-//   inside one blocking call.
+//   come".
 //
-//   So the heartbeat is not a Monitor, not a cron entry and not a paragraph of
+//   So the alarm is not a Monitor, not a cron entry and not a paragraph of
 //   prose. A cron entry that ran the reconcile would print its rows to nobody:
 //   the tick reads the run for itself, but only the controller can act
-//   on what it prints. An external scheduler can only WAKE the controller,
-//   which is the one thing the measurement above says it cannot be trusted to
-//   do.
+//   on what it prints. Nothing outside the omp process can start a turn in an
+//   idle session, which is the one thing the measurement above says an
+//   external watcher cannot be trusted to do — so the alarm is an in-process
+//   extension, which can.
 //
-// WHY IT TAKES NO CONTROLLER STATE — every flag below has a default. A monitor
-// event is a wake-up, never a verdict (run-team/SKILL.md, "A monitor event is a wake-up, never a verdict"), so this
-// script never reads or reports fleet state: counts captured before a
-// twenty-minute hold and printed after it are a stale verdict, and a stale
+// WHY IT TAKES NO CONTROLLER STATE — every flag below has a default. An alarm
+// turn is a wake-up, never a verdict (run-team/SKILL.md, "A monitor event is a wake-up, never a verdict"), so this
+// script never reads or reports fleet state: counts captured when the beat was
+// marked and printed twenty minutes later are a stale verdict, and a stale
 // verdict is how a reconcile prints an ACTION nobody can take. The controller
 // runs `fleet-event.mjs heartbeat` itself at wake time, which ticks and so reads the run as it stands then.
-// It also makes a late hold harmless: if a member reports at minute two and
-// the controller acts, the hold that fires afterwards is a free extra tick.
+// It also makes a late alarm harmless: if a member reports at minute two and
+// the controller acts, the alarm that fires afterwards is a free extra tick.
 //
-// The pure half is interval() and heldThisCall(); main() does the I/O.
+// The pure half is interval(); main() does the I/O.
 
 // Back-off. The interval doubles while the fleet has nothing to act on, so a
 // quiet night costs a few wakes instead of one every five minutes — and stops
@@ -58,20 +60,6 @@ export function interval({ quiet, base, ceiling, multiplier }) {
   return Math.min(base * multiplier ** quiet, ceiling);
 }
 
-// How long THIS invocation may block, which is not the same as the interval.
-//
-// Nothing lets one command block for twenty minutes. Measured: omp
-// auto-backgrounds any foreground command at 60s (`bash.autoBackground`), and
-// its command deadline defaults to 300s (the bash tool's default
-// `timeout`).
-//
-// So a long interval is served by SEVERAL holds, and the elapsed total is
-// persisted rather than counted in prose: the script says how much remains, so
-// the controller re-issues without tracking arithmetic across turns.
-export function heldThisCall({ elapsed, target, hold }) {
-  return Math.min(hold, Math.max(0, target - elapsed));
-}
-
 // --------------------------------------------------------------------------
 // I/O. Everything below runs only as a CLI — importing this file must never
 // parse argv or touch the filesystem, or the pure half stops being unit-testable.
@@ -79,7 +67,7 @@ export function heldThisCall({ elapsed, target, hold }) {
 import { isCLI } from "./is-cli.mjs";
 import { parseArgs } from "node:util";
 import { makeDie, isDigits } from "./arg.mjs";
-import { statePath, readState, writeState, DEFAULT_CEILING_S } from "./fleet-state.mjs";
+import { resolveStatePath, readState, writeState, DEFAULT_CEILING_S } from "./fleet-state.mjs";
 
 const NAME = "fleet-heartbeat";
 const die = makeDie(NAME);
@@ -95,11 +83,6 @@ const OPTIONS = {
   // header's "never a copy of it" rule exists to close.
   ceiling: { type: "string", default: String(DEFAULT_CEILING_S) },
   multiplier: { type: "string", default: "2" },
-  // Per-invocation blocking budget, under omp's defaults. 240s leaves
-  // headroom below omp's 300s command deadline, which is itself shorter than
-  // the 5-6 minute CI cycle run-merge-bot.md's CI wait rule states. Raise
-  // it only together with the tool call's own timeout.
-  hold: { type: "string", default: "240" },
   // The deliberate stop. No default and no boolean spelling: the flag
   // IS the reason, and a `--stop` that recorded an empty string would be the
   // abrupt-death case wearing a deliberate stop's clothes — a reader would
@@ -114,19 +97,8 @@ const OPTIONS = {
 };
 
 // State path, read and write all come from fleet-state.mjs, which owns the key
-// ownership rule this script depends on: it writes `elapsed` and `beat` and
-// nothing else, so fleet-tick's `quiet` and `digest` survive every hold.
-// main() re-reads the file after its hold to keep that true across the hold
-// itself, and treats a write that did not land as a fire rather than as
-// progress.
-
-// A blocking sleep, not a poll loop. Atomics.wait on a SharedArrayBuffer parks
-// the thread; `while (Date.now() < end) {}` would burn a core for the whole
-// hold, and setTimeout would need the event loop to stay alive and would let
-// anything else queued run first.
-function block(seconds) {
-  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, seconds * 1000);
-}
+// ownership rule this script depends on: it writes `beat` and
+// nothing else, so fleet-tick's `quiet` and `digest` survive every call.
 
 function args() {
   let values;
@@ -142,7 +114,7 @@ function args() {
     const raw = String(values[name]).trim();
     // Digits, not Number(): `Number("")` is 0, so `--base ""` — the shape an
     // unset shell variable produces — would read as a real zero and turn the
-    // hold into a no-op that looks like a working heartbeat.
+    // interval into a no-op that looks like a working heartbeat.
     if (!isDigits(raw)) die(`--${name} must be a non-negative integer, got '${values[name]}'`);
     const n = Number(raw);
     if (n < min) die(`--${name} must be at least ${min}, got ${n}`);
@@ -151,7 +123,6 @@ function args() {
   const base = int("base", 1);
   const ceiling = int("ceiling", 1);
   const multiplier = int("multiplier", 1);
-  const hold = int("hold", 1);
   // A ceiling under the base is not a slow heartbeat, it is a back-off that
   // runs backwards — min() would clamp every interval to the ceiling and the
   // base would never be honoured. Refuse rather than silently reinterpret.
@@ -167,7 +138,8 @@ function args() {
   if (values.stop !== undefined && values.stop.trim() === "") {
     die("--stop must carry the reason the run is stopping, e.g. --stop 'budget exhausted'");
   }
-  return { base, ceiling, multiplier, hold, stop: values.stop?.trim(), state: values.state || statePath(NAME) };
+  const { path: state, fellBack } = values.state ? { path: values.state, fellBack: false } : resolveStatePath(NAME);
+  return { base, ceiling, multiplier, stop: values.stop?.trim(), state, fellBack };
 }
 
 // The mark: when this beat was seen and the interval that was in effect
@@ -176,26 +148,21 @@ function args() {
 //
 // The interval travels WITH the time because a reader comparing an age
 // against a fixed threshold either cries wolf on a quiet night at the ceiling
-// or misses a death during a busy one at the base. It is the target interval
-// and not the hold: the hold is this harness's blocking budget, an
-// implementation detail of how one interval gets served, while the interval
-// is the beat the run actually promised.
+// or misses a death during a busy one at the base. It is the beat the run
+// actually promised: the alarm fires once `at` plus the interval has passed.
 function mark(target, stopped) {
   return { at: Date.now(), interval: target, stopped };
 }
 
 function main() {
-  const { base, ceiling, multiplier, hold, stop, state: path } = args();
+  const { base, ceiling, multiplier, stop, state: path, fellBack } = args();
   const state = readState(path, NAME);
   const target = interval({ quiet: state.quiet, base, ceiling, multiplier });
 
   if (stop !== undefined) {
-    // No hold, and `elapsed` untouched: this invocation is not a beat, it is
-    // the run saying why there will not be another one. Leaving the partial
-    // interval where it is costs nothing — the next run reads a stopped mark
-    // and knows the streak behind it is a dead run's. Leave degraded files
-    // byte-identical, so a same-session rotate still refuses rather than
-    // judges none.
+    // This invocation is not a beat, it is the run saying why there will not
+    // be another one. Leave degraded files byte-identical, so a same-session
+    // rotate still refuses rather than judges none.
     if (state.degraded) {
       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`);
       return;
@@ -213,72 +180,44 @@ function main() {
     return;
   }
 
-  const held = heldThisCall({ elapsed: state.elapsed, target, hold });
-
-  block(held);
-  // Re-read AFTER the hold, and patch THAT rather than the pre-hold snapshot.
-  // fleet-tick can run while this call is blocked — up to --hold seconds, 240
-  // by default — and it owns both keys this script must not touch. Writing the
-  // snapshot back reverts them: a busy stretch that reset `quiet` to 0 would find
-  // the long interval re-armed the moment the hold ended, and a reverted
-  // `digest` reads as "the output changed" on the next tick, un-folding the
-  // quiet night the digest exists to fold. `elapsed` is still one of the keys
-  // this script writes; it is now read fresh rather than remembered across a
-  // hold long enough for the file to have moved underneath it.
-  const now = readState(path, NAME);
-  const elapsed = now.elapsed + held;
-  const reached = elapsed >= target;
-  // Reset on fire, so the next interval starts from zero rather than from a
-  // total that has already elapsed. Only `elapsed` and `beat` are written —
-  // fleet-tick owns `quiet` and `digest`, and fleet-state.mjs's patch write
-  // preserves them.
-  //
-  // The mark rides the SAME write as `elapsed`, deliberately, rather than
-  // taking one of its own. One write per invocation means a mark can never
-  // land while the progress it was taken beside did not, and the two can
-  // never disagree about which invocation they came from. It also keeps the
-  // failure story single: the warning below covers both keys at once. Leave
-  // degraded files byte-identical, so a same-session rotate still refuses
-  // rather than judges none — a skipped write reports a fire like a failed one.
+  // Leave degraded files byte-identical, so a same-session rotate still
+  // refuses rather than judges none — a skipped write is a mark that was not
+  // recorded, like a failed one.
   //
   // `stopped: ""` on every ordinary beat, never carried forward: a run that
   // recorded a stop and then kept beating is a run that did not stop, and a
   // stale reason surviving into a live beat would have the next reader
   // announcing a death that already un-happened.
-  const persisted = !now.degraded && writeState(path, NAME, now, { elapsed: reached ? 0 : elapsed, beat: mark(target, "") });
-  // A failed write is itself a fire. With nothing persisting the remainder,
-  // every invocation reads the same elapsed total, holds the same seconds and
-  // prints the same remainder: the interval can never complete, so fleet-tick
-  // is never run at all — the drained-queue stall itself, reached through a line that reads
-  // like a working heartbeat. Beating too often is the harmless direction;
-  // never beating is the one this script exists to prevent.
-  //
-  // The mark fails the same way and on purpose: writeState has already said
-  // so on stderr, this process keeps beating, and a reader that never sees a
-  // mark reports a stall it cannot explain — loud and wrong in the safe
-  // direction — rather than this script dying to protect its own telemetry.
-  // A liveness mark that killed the beat it measures would be that same stall
-  // wearing a new hat.
-  const done = reached || !persisted;
+  const persisted = !state.degraded && writeState(path, NAME, state, { beat: mark(target, "") });
 
   // One line either way, and never zero lines. Silence is the failure mode this
-  // whole ticket is about: a heartbeat that printed nothing would be
+  // whole script is about: a heartbeat that printed nothing would be
   // indistinguishable from a heartbeat that died, which is the same
   // "indistinguishable from a working one" the member-idle measurement names.
-  // The partial line says what to do next in the imperative, because the one
-  // thing that must not happen here is the controller ending its turn.
   //
-  // `quiet=` is the pre-hold streak, the one the interval was DERIVED from: a
-  // fresh streak printed beside a target computed from the old one would be two
-  // numbers that do not explain each other.
+  // The line that tells the controller to end its turn is printed ONLY when
+  // the mark is on disk where the alarm reads. The alarm's gate reads `beat`;
+  // with none recorded it never passes, so that line would send the controller
+  // idle into a session nothing will wake — the drained-queue stall, reached
+  // through a line that reads like a working heartbeat. A mark that failed to
+  // land says so, says no alarm is armed for it (an earlier mark still on disk
+  // is all the alarm can fire on), and exits 0 like the stop path: writeState
+  // has already said so on stderr, and the controller can repair the file and
+  // beat again. A mark written through statePath's cwd-relative fallback is
+  // treated the same way: the alarm resolves the run's `.fleet` for itself and
+  // may never read that file.
   //
-  // A skipped write says so, on the fire it reports: the interval did not
-  // elapse, the file could not keep its progress, and this call fires again
-  // on every hold until the file is repaired.
-  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" : "";
-  console.log(done
-    ? `heartbeat: held ${held}s, ${target}s interval elapsed (quiet=${state.quiet}) → run fleet-event.mjs heartbeat${skippedNote}`
-    : `heartbeat: held ${held}s, ${target - elapsed}s of ${target}s remain (quiet=${state.quiet}) → re-issue this command now, do not end your turn`);
+  // `quiet=` is the streak the interval was DERIVED from, printed beside the
+  // number it explains.
+  if (persisted && fellBack) {
+    console.log(`heartbeat: WARNING beat NOT marked in a resolved heartbeat file — the run's .fleet directory could not be resolved, so the mark went to a cwd-relative .fleet/heartbeat.json the alarm may not read; fix the resolution and run this again`);
+  } else if (persisted) {
+    console.log(`heartbeat: beat marked, alarm due in ${target}s (quiet=${state.quiet}) → end your turn`);
+  } else if (state.degraded) {
+    console.log(`heartbeat: WARNING beat NOT marked — the heartbeat file is degraded and was left as it is, so no alarm is armed; repair the file and run this again`);
+  } else {
+    console.log(`heartbeat: WARNING beat NOT marked — the heartbeat file could not be written, so no alarm is armed for this beat; fix the write and run this again`);
+  }
 }
 
 if (isCLI(import.meta.url)) main();

package/scripts/fleet-state.mjs

@@ -11,9 +11,6 @@
 //            nothing. Drives the back-off interval.
 //   digest   fleet-tick only. The last tick's own output, so an unchanged
 //            quiet tick can fold to one line instead of three.
-//   elapsed  fleet-heartbeat only. Seconds already held toward the current
-//            interval, because no harness lets one command block long enough
-//            to serve a twenty-minute interval in a single call.
 //   beat     fleet-heartbeat only. The liveness mark: when the beat
 //            was last seen, the interval that was in effect when it was, and
 //            a deliberate stop's reason if one was recorded. Written by the
@@ -87,20 +84,28 @@ export function stateFileIn(fleetDir) {
 // There is ONE heartbeat per run and its state lives in the main checkout.
 // Members run from their own worktrees, where a cwd-relative `.fleet/` does not
 // exist, so a cwd-relative path would give every worktree a private back-off
-// streak and a private elapsed total — the run's beat would be whichever
+// streak — the run's beat would be whichever
 // worktree happened to call last. fleet-dir.mjs's fleetFile() resolves it the
 // way it resolves the ledger, scrubbed and bounded: a `git` that never answers
 // is killed rather than holding the beat. Only the warning and the fallback
 // below are this caller's own.
 export function statePath(name) {
+  return resolveStatePath(name).path;
+}
+
+// The same resolution, saying whether it fell back. fleet-heartbeat needs the
+// flag: a beat marked in the cwd-relative file is one the alarm, which resolves
+// the run's `.fleet` for itself, may never read, so that beat must not tell the
+// controller to end its turn.
+export function resolveStatePath(name) {
   try {
-    return stateFileIn(fleetFile(null));
+    return { path: stateFileIn(fleetFile(null)), fellBack: false };
   } catch (e) {
     if (!(e instanceof FleetDirUnresolvable)) throw e;
     // Announced, never silent: a cwd-relative fallback re-opens exactly the
     // per-worktree split this resolution exists to close.
     console.error(`${name}: WARNING ${e.message}; using cwd-relative .fleet/heartbeat.json`);
-    return stateFileIn(".fleet");
+    return { path: stateFileIn(".fleet"), fellBack: true };
   }
 }
 
@@ -134,7 +139,7 @@ export function readState(path, name, warn = console.error) {
   // to judge and nothing to report. A zeroed mark would date the beat to the
   // epoch and read as decades overdue on a run that has simply not started
   // one — the cry-wolf direction this key must never fail in.
-  const fresh = { quiet: 0, elapsed: 0, digest: "", beat: null, ticked: null, acted: null, controller: null, seen: {}, applied: null, rest: {} };
+  const fresh = { quiet: 0, digest: "", beat: null, ticked: null, acted: null, controller: null, seen: {}, applied: null, rest: {} };
   // The same state, flagged: the file EXISTS and could not be used. A caller
   // that acts on the absence of a record — ledger.mjs rotate — must tell this
   // from `fresh`, which is a run that has simply not written one yet. The
@@ -149,7 +154,7 @@ export function readState(path, name, warn = console.error) {
     // fault: a fresh run legitimately has no file yet. Every other errno is a
     // file that EXISTS and could not be read — EACCES on a chmod'ed state
     // file, EISDIR on a path something else claimed, EIO on a bad disk — and
-    // each of those discards a real back-off streak and a real elapsed total.
+    // each of those discards a real back-off streak.
     // Swallowing them with the same bare catch the absent case uses is a
     // degraded read reported as a fresh run, which is the failure class this
     // whole ticket exists to close.
@@ -171,13 +176,13 @@ export function readState(path, name, warn = console.error) {
     return makeDegraded("is not a JSON object");
   }
   // Per-field validation, not all-or-nothing: a file carrying a good `quiet`
-  // and a junk `elapsed` keeps the streak instead of losing both to one key.
+  // and a junk `digest` keeps the streak instead of losing both to one key.
   // The exception is `controller`, below: a record that cannot be judged
   // flags the whole file, because a write that dropped it is the loss.
   const num = (v) => (typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : 0);
   // `rest` is strictly what lies OUTSIDE the schema, which is what makes the
   // patch write below a patch rather than a laundering step. A raw copy of
-  // quiet/elapsed/digest in here would be written straight back by whichever
+  // quiet/digest in here would be written straight back by whichever
   // script does not own the key, so a junk value would survive every write
   // that sanitized it in memory — validation that only ever holds inside one
   // process is not validation of the file.
@@ -253,7 +258,7 @@ export function readState(path, name, warn = console.error) {
     if (!(Number.isInteger(v.run) && v.run > 0)) return null;
     return { run: v.run, reapAfter: v.reapAfter.filter((n) => Number.isInteger(n) && n > 0) };
   };
-  const { quiet, elapsed, digest, beat, ticked, acted, controller, seen, applied, ...rest } = parsed;
+  const { quiet, digest, beat, ticked, acted, controller, seen, applied, ...rest } = parsed;
   // A controller key that ctl() rejects is a record someone wrote and nobody
   // can judge, not the absence of one — announced like the other degraded
   // causes, and flagged.
@@ -264,7 +269,6 @@ export function readState(path, name, warn = console.error) {
   }
   return {
     quiet: num(quiet),
-    elapsed: num(elapsed),
     digest: typeof digest === "string" ? digest : "",
     beat: mark(beat),
     ticked: tick(ticked),
@@ -284,11 +288,9 @@ export function readState(path, name, warn = console.error) {
 // A failed write is reported and SURVIVED, never fatal, for the same reason a
 // failed read is. But survived is not the same as ignored: it returns whether
 // the write landed, because the two cases call for different behaviour from
-// the caller and only the caller can act. An unpersisted `elapsed` means the
-// next invocation re-reads the same total, holds again and reports the same
-// remainder — an interval that can never complete — so fleet-heartbeat treats
-// a failed write as a fire instead of counting progress that nothing is
-// keeping.
+// the caller and only the caller can act. An unpersisted `beat` is one the
+// alarm's gate never passes on, so fleet-heartbeat says no alarm is armed for
+// it instead of telling the controller to end its turn.
 //
 // The write is a sibling temp file renamed over the target, ledger.mjs save()'s
 // convention, because the readers do not hold still for it. A plain
@@ -307,16 +309,16 @@ export function writeState(path, name, prev, patch) {
   // from the raw parse: see `rest` in readState above.
   const next = {
     ...(prev.rest ?? {}),
-    quiet: prev.quiet, elapsed: prev.elapsed, digest: prev.digest,
-    // Carried like the other three, and omitted rather than written as
+    quiet: prev.quiet, digest: prev.digest,
+    // Carried like the other two, and omitted rather than written as
     // `null` when there is none: fleet-tick patches `quiet`/`digest` on every
     // tick and would otherwise erase the heartbeat's mark on the first tick
     // after it was written — one script deleting another's key, which is the
     // failure the ownership rule exists to prevent and which no reader could
     // tell from a run that never beat.
     ...(prev.beat ? { beat: prev.beat } : {}),
-    // Same reason, same shape: fleet-heartbeat patches `elapsed`/`beat` on
-    // every hold and would otherwise erase fleet-tick's `ticked` the first
+    // Same reason, same shape: fleet-heartbeat patches `beat` on
+    // every call and would otherwise erase fleet-tick's `ticked` the first
     // time a heartbeat lands after a busy stretch.
     ...(prev.ticked ? { ticked: prev.ticked } : {}),
     // And again for ledger.mjs's `controller` and `acted`, which both scripts
@@ -371,10 +373,10 @@ export function writeState(path, name, prev, patch) {
 //
 // The grace multiplier is the only constant, and it is a multiplier ON the
 // recorded interval rather than a duration added to it, so it scales with the
-// promise instead of drowning it. One whole extra interval of silence: a beat
-// is served by SEVERAL holds (see fleet-heartbeat.mjs's heldThisCall), the
-// controller's own turn sits between the last hold and the next invocation,
-// and neither is bounded tightly enough to call a run dead the second one
+// promise instead of drowning it. One whole extra interval of silence: the
+// alarm only fires once the controller is idle, so the controller's own turn
+// sits between the beat falling due and the next invocation, and that turn is
+// not bounded tightly enough to call a run dead the second one
 // interval lapses. It is the same shape board.html already uses to call its
 // own data stale (`interval * 1000 * 2`), kept deliberately: an operator
 // reading two "stale" verdicts on one page should not have to learn two rules.
@@ -499,16 +501,16 @@ export function isReported(verdict) {
 
 // Whole minutes, floored, because the numbers here are tens of minutes to
 // hours and a seconds-precise age in a stall line is false precision: the
-// mark is written once per hold, so its resolution is minutes anyway. That
+// mark is written once per idle, so its resolution is minutes anyway. That
 // holds for production (--base 300, --ceiling 1200 — SKILL.md's only
 // documented values) but not for every value the CLI guard actually accepts:
 // fleet-heartbeat.mjs's own guard refuses `--ceiling < --base` the same way
 // this file refuses other invalid shapes, and mirroring that refusal onto
 // sub-60s `--base`/`--ceiling` was the first fix tried for the "0m" floor —
 // until the heartbeat's own test suite turned out to lean on 2s/3s/8s/9s/64s intervals
-// throughout, deliberately, to keep its real `Atomics.wait` holds fast. A
-// CLI-level refusal would force that whole suite onto minute-plus real
-// holds for no behavioural gain, so the fix lives here instead: a value
+// throughout, deliberately, to keep its time-travelled marks small. A
+// CLI-level refusal would force that whole suite onto minute-plus
+// intervals for no behavioural gain, so the fix lives here instead: a value
 // under a minute is still a real value, not an invalid one, and flooring it
 // to "0m" is what read as a division-by-zero defect, not the sub-minute
 // input itself.

package/skills/run-team/SKILL.md

@@ -111,7 +111,7 @@ phase, or in any later one, asks the maintainer which tickets to take.
 
 ## The wake table
 
-A wake is done when its one `fleet-event.mjs` call has run and you have acted on every line it printed, the tick's last; with nothing left to act on, arm the heartbeat and hold rather than end your turn. What a wake owes beyond its call is under **What a wake owes beyond its call**, below. The loop has no exit but the run's own end: drain the run when it ends (**End of run**).
+A wake is done when its one `fleet-event.mjs` call has run and you have acted on every line it printed, the tick's last; with nothing left to act on, mark the beat and end your turn. What a wake owes beyond its call is under **What a wake owes beyond its call**, below. The loop has no exit but the run's own end: drain the run when it ends (**End of run**).
 
 React to events; never block on one.
 
@@ -146,14 +146,14 @@ Run each as `~/.fleet/bin/fleet-run fleet-event.mjs <kind> <args>`, from the mai
 | CI run terminal | `fleet-event.mjs ci <pr>` |
 | Label seen (persistent Monitor) | `fleet-event.mjs label <pr>` |
 | `CONFLICT` line | `fleet-event.mjs conflict <pr>` |
-| Heartbeat | `fleet-event.mjs heartbeat` |
+| Alarm (a [fleet-alarm] turn) | `fleet-event.mjs heartbeat` |
 | Drain | `fleet-event.mjs drain --reason "<reason>"` |
 | Undrain | `fleet-event.mjs undrain --reason "<reason>"` |
 | Member confirmed dead or never dispatched | `fleet-event.mjs member-died <member>` |
 
 ### What a wake owes beyond its call
 
-Act on every line the call prints, the tick's last, and arm the beat. What a wake
+Act on every line the call prints, the tick's last, and mark the beat. What a wake
 owes beyond its call:
 
 - **Implementer report** → the PR is owed a review from here on:
@@ -305,25 +305,25 @@ it; never type a tier in over that. That append is the whole duty. See reference
 
 **A verdict is a measurement only if it post-dates the run that produced it.** See references/reviewers.md.
 
-### Nothing to do: arm the beat
+### Nothing to do: mark the beat and end your turn
 
-- **Nothing to do right now** → **do not end your turn.** Arm the heartbeat
-  below: nothing external will wake you. See references/ci-and-staleness.md.
+- **Nothing to do right now** → mark the beat, then end your turn.
 
-**Beat when there is nothing to do, and never end your turn on a drained queue.** See references/ci-and-staleness.md.
+**Mark the beat when there is nothing to do, and end your turn.** See references/ci-and-staleness.md.
 
 ```bash
 ~/.fleet/bin/fleet-run fleet-heartbeat.mjs \
-  [--base 300] [--ceiling 1200] [--multiplier 2] [--hold 240]
+  [--base 300] [--ceiling 1200] [--multiplier 2]
 ```
 
-It blocks, then prints one line. Which line it is, is the whole protocol:
+It returns at once and prints one line. Which line it is, is the whole protocol:
 
-- `… interval elapsed (quiet=<n>) → run fleet-event.mjs heartbeat` — the level-check
-  is due. Run that command and act on what the tick it ends in prints.
-  Then arm the beat again.
-- `… Ns of Ms remain → re-issue this command now, do not end your turn` —
-  issue it again: still one blocking call per turn, never an idle turn.
+- `… beat marked, alarm due in <N>s (quiet=<n>) → end your turn` — the mark is
+  recorded. The alarm's turn arrives as a user message that
+  starts `[fleet-alarm]` and names `fleet-event.mjs heartbeat`: run that
+  command and act on what the tick it ends in prints. Then mark the beat again.
+- `… beat NOT marked …` — this beat arms no alarm you can count on, so ending
+  your turn could be the stall. Fix what it names; rerun.
 
 **Do not raise `--ceiling` past 30 minutes.** See references/ci-and-staleness.md.
 

package/skills/run-team/references/ci-and-staleness.md

@@ -3,7 +3,7 @@
 Why green not verdict, why absence is its own verdict, why conclusion not
 stable, why behind-count only honest signal, why the tick runs on every wake
 and why the beat is shaped as it is. Assertions live in SKILL.md's wake table,
-**Nothing to do: arm the beat** and **Own the CI waits**; evidence here.
+**Nothing to do: mark the beat and end your turn** and **Own the CI waits**; evidence here.
 
 ## Own the CI waits — members cannot hold across a run
 
@@ -96,14 +96,17 @@ time enough: reviewers label on own green without requiring currency, and
 requiring it earlier costs full CI cycle per sibling merge — six wasted cycles
 in one run. Any behind-count you hand bot expired on arrival.
 
-## Beat when there is nothing to do, and never end your turn on a drained queue
+## Mark the beat when there is nothing to do, and end your turn
 
-**Beat when there is nothing to do, and never end your turn on a drained
-queue.** You cannot be woken. A backgrounded Monitor does not wake an idle
+**Mark the beat when there is nothing to do, and end your turn.** Nothing
+outside your own process can start a turn in an idle session. A backgrounded
+Monitor does not wake an idle
 agent — measured twice, see **A member runs its test suite in the foreground** in references/member-lifecycle.md, where `fix-pr-<M>` backgrounded a suite plus a Monitor and sat idle for
 roughly two hours — and `run-merge-bot.md`'s CI gate states the general rule:
-"whatever wakes you is external and may never come". So hold the wait yourself,
-exactly the way that gate does:
+"whatever wakes you is external and may never come". So the wake-up is not a
+watcher and not a cron entry. It is an omp extension loaded into your own
+session, the alarm, which polls from inside the process and starts a turn once
+the beat has fallen due.
 
 ## Tick on every wake
 
@@ -126,7 +129,7 @@ Do not raise it past 30 minutes.
 
 ## When you stop on purpose, say why
 
-The beat leaves a dated mark on every hold, so a run
+The beat leaves a dated mark on every call, so a run
 that dies abruptly (a crashed harness, a closed terminal, an OOM kill) is
 detected by its mark going stale. A run that stops KNOWINGLY can do better
 than being detected, and nothing else can write the reason afterwards:
@@ -141,17 +144,20 @@ honestly say about a death that named nothing.
 
 ## Nothing to do: why the beat, and what its lines mean
 
-- **Nothing to do right now** → **do not end your turn.** Arm the heartbeat
-  (SKILL.md's **Nothing to do: arm the beat**). A turn that ends on a drained
-  queue is the stall itself: nothing external will wake you, and the
-  level-check you are one command away from never runs. Listed on its own
-  because it is the only wake with no trigger — every other row of SKILL.md's
-  wake list arrives; this one is the absence of one.
-
-- `… Ns of Ms remain → re-issue this command now, do not end your turn` — no
-  command blocks for a whole interval (omp backgrounds one at 60s, which is
-  why the CI gate holds its wait in one `eval` cell polling `gh run view`).
-  Issue it again. That is still one blocking call per turn, never an idle turn.
+- **Nothing to do right now** → mark the beat and end your turn (SKILL.md's
+  **Nothing to do: mark the beat and end your turn**). The beat is what the
+  alarm reads: with no recorded mark its gate never passes, so a turn that
+  ends without one is the stall itself — the level-check you are one command
+  away from never runs. Listed on its own because it is the only wake that is
+  not an event — every other row of SKILL.md's wake list reports something
+  that happened; this one is the beat falling due.
+
+- `… beat NOT marked …` — the write did not land, the file is degraded and
+  was left as it is, or the run's `.fleet` directory could not be resolved and
+  the mark went to a cwd-relative file the alarm may not read. No alarm is
+  armed for this beat (an earlier mark still on disk is all the alarm can fire
+  on), so do not take the line as a beat; fix what it names and run the
+  command again.
 
 **The beat does not stop on idleness.** An empty shortlist and an empty supply are
 not a reason to end the run; they are the state a newly triaged ticket arrives