@cohortapp/agent-sdk 2.18.14 → 2.18.16

package/lib/session/revive.mjs

@@ -22,9 +22,10 @@
  *
  * The daemon is the honest home for this. It is a separate process, it is
  * already alive on every seat that beats, it already reads the front-door
- * state every poll to decide who owns the inbox, and it runs every thirty
- * seconds. A seat whose door shuts is then measured in a minute rather than a
- * day, by something the shut door cannot take down with it.
+ * state every poll to decide who owns the inbox, and it re-checks the door on
+ * its own sixty-second cadence (REVIVE_CHECK_INTERVAL_MS). A seat whose door
+ * shuts is then measured in a minute or two rather than a day, by something
+ * the shut door cannot take down with it.
  *
  * Pure: the decision only. The daemon owns the kickstart.
  */
@@ -38,19 +39,33 @@ export const DEFAULT_REVIVE_BACKOFF_MS = 15 * 60 * 1000;
 /** How many restarts before the daemon stops and leaves it to a person. */
 export const DEFAULT_REVIVE_MAX = 3;
 
+/**
+ * Consecutive not-live reads required before the FIRST kickstart.
+ *
+ * A kickstart drops whatever the session was doing. One bad read is not
+ * enough evidence to pay that cost — a heartbeat file can be caught
+ * mid-write, or a poll can land in the one second between a session ending
+ * a tool call and starting the next. Two reads in a row, SIXTY seconds
+ * apart at the daemon's revive-check cadence (REVIVE_CHECK_INTERVAL_MS), is
+ * the line Ravi drew after the fleet had already seen what a single-read
+ * trigger costs.
+ */
+export const DEFAULT_REVIVE_CONFIRM_READS = 2;
+
 /**
  * Should the daemon restart the front door right now?
  *
  * The caller supplies the front-door state it already reads for dispatch, the
  * age of the session heartbeat, and what this daemon has already tried. Every
  * bound is explicit because the failure mode of getting this wrong is a seat
- * that restarts its own session every thirty seconds forever — which is worse
+ * that restarts its own session every sixty seconds forever — which is worse
  * than the shut door, and is the reason the ladder ends in "stop and say so"
  * rather than in another attempt.
  *
  * @param {{frontDoor?:string, sessionLive?:boolean, silentMs?:number|null,
  *          attempts?:number, lastAttemptAt?:number|null, now:number,
- *          reviveAfterMs?:number, backoffMs?:number, maxAttempts?:number}} a
+ *          reviveAfterMs?:number, backoffMs?:number, maxAttempts?:number,
+ *          notLiveReads?:number, confirmReads?:number}} a
  * @returns {{revive:boolean, reason:string}}
  */
 export function shouldReviveFrontDoor(a) {
@@ -59,6 +74,7 @@ export function shouldReviveFrontDoor(a) {
   const after = Number.isFinite(x.reviveAfterMs) && x.reviveAfterMs > 0 ? x.reviveAfterMs : DEFAULT_REVIVE_AFTER_MS;
   const backoff = Number.isFinite(x.backoffMs) && x.backoffMs > 0 ? x.backoffMs : DEFAULT_REVIVE_BACKOFF_MS;
   const max = Number.isFinite(x.maxAttempts) && x.maxAttempts >= 0 ? x.maxAttempts : DEFAULT_REVIVE_MAX;
+  const confirm = Number.isFinite(x.confirmReads) && x.confirmReads > 0 ? x.confirmReads : DEFAULT_REVIVE_CONFIRM_READS;
 
   // A seat whose lane is the daemon has no front door to revive: the daemon
   // itself is answering, and restarting a session job it does not depend on
@@ -82,6 +98,16 @@ export function shouldReviveFrontDoor(a) {
   if (!Number.isFinite(silentMs)) return { revive: false, reason: "silence-unknown" };
   if (silentMs < after) return { revive: false, reason: "within-grace" };
 
+  // Two-read hysteresis, gating only the FIRST kickstart: a kickstart drops
+  // whatever the session was mid-way through, so the daemon must not act on
+  // a single not-live read before it has confirmed the verdict on the next
+  // poll. `notLiveReads` undefined means a caller that predates this streak
+  // (every existing test above) — treat it as already confirmed so those
+  // callers see no change in behaviour; the daemon is the one caller that
+  // threads the real streak through.
+  const reads = x.notLiveReads === undefined ? confirm : Number(x.notLiveReads);
+  if (!(reads >= confirm)) return { revive: false, reason: "confirming" };
+
   const attempts = Number(x.attempts) || 0;
   if (attempts >= max) return { revive: false, reason: "budget-spent" };
 
@@ -93,6 +119,277 @@ export function shouldReviveFrontDoor(a) {
   return { revive: true, reason: `front door silent ${Math.round(silentMs / 1000)}s (attempt ${attempts + 1}/${max})` };
 }
 
+/**
+ * Should this seat's daemon job be restarted? Local check only — the
+ * reciprocal of `shouldReviveFrontDoor`'s job, but it CANNOT be run by the
+ * daemon on itself: a process that is alive to ask the question is a process
+ * launchctl reports a live pid for, so a live daemon can never observe its own
+ * down state. The actor is therefore the hourly `autoupdate.sh` backstop (it
+ * already parses `launchctl list` for `daemon_last_exit`), which is exactly
+ * the seat-local watchdog that catches a daemon that has stopped while the
+ * front door kept beating (Jacob's 2026-09-25 case: heartbeat.json ticking, no
+ * overdue handoff, daemon dead). `autoupdate.sh#revive_daemon` is the caller.
+ *
+ * `launchctl` is read by the caller from `launchctl list`, the same source
+ * `sibling_job_audit` and `autoupdate.sh` already parse: "pid" when the
+ * column holds a number, "dash" when it holds `-` (loaded, no pid), "absent"
+ * when the label is not in the list at all.
+ *
+ * PHANTOM PID: a silent crash loop can leave `launchctl list` holding a pid
+ * whose process has genuinely exited — the label still carries a number, but a
+ * `kill -0` on that pid fails because no such process is running, a kickstart
+ * yields another dead pid, and nothing lands on stderr. A LISTED pid is not a
+ * RUNNING daemon. So the caller decides liveness by `kill -0` on the pid and
+ * passes `pidAlive`; a phantom pid (`launchctl:"pid"` but `pidAlive:false`) is
+ * treated exactly like "dash" — loaded with no live process — and the beat age
+ * decides, instead of the listed pid rubber-stamping the daemon as alive.
+ *
+ * @param {{launchctl?:string, beatAgeMs?:number, staleMs?:number, pidAlive?:boolean}} a
+ * @returns {{revive:boolean, reason:string}}
+ */
+export function shouldReviveDaemon(a) {
+  const x = a && typeof a === "object" ? a : {};
+  const stale = Number.isFinite(x.staleMs) && x.staleMs > 0 ? x.staleMs : DEFAULT_REVIVE_AFTER_MS;
+
+  // A pid that launchctl lists but the OS does not actually run is a phantom —
+  // the same down state as a dash, dressed up as alive. Only an EXPLICIT
+  // `pidAlive === false` demotes it; a caller that does not probe liveness
+  // (`pidAlive` undefined) keeps the old behaviour, so nothing that never
+  // measured it changes.
+  const phantom = x.launchctl === "pid" && x.pidAlive === false;
+  const state = phantom ? "dash" : x.launchctl;
+
+  if (state === "pid") return { revive: false, reason: "daemon-alive" };
+
+  // No job at all is not a wedge to clear — it is a seat that was never
+  // provisioned with one, or had it removed, and a kickstart has nothing to
+  // aim at.
+  if (state === "absent") return { revive: false, reason: "daemon-job-absent" };
+
+  if (state === "dash") {
+    const beatAgeMs = Number(x.beatAgeMs);
+    // A loaded job with no live pid and a beat that has gone stale is the down
+    // state this exists to catch. A fresh beat under the same launchctl
+    // reading means the prior instance is still exiting, not that this one
+    // needs help.
+    if (!(beatAgeMs > stale)) return { revive: false, reason: "daemon-settling" };
+    return { revive: true, reason: phantom ? "daemon-phantom-pid" : "daemon-down" };
+  }
+
+  // Anything else — missing, empty, an error string from a failed parse — is
+  // a reading this cannot name a state from, and an unnamed state is never
+  // grounds to act.
+  return { revive: false, reason: "daemon-state-unknown" };
+}
+
+/** How many consecutive observations across the settle window prove continuity. */
+export const DEFAULT_CONFIRM_SAMPLES = 2;
+
+/**
+ * Did a revive attempt actually work? Checked from OUTSIDE the restart helper,
+ * on purpose: a helper that exits 0 has told you it ran, not that it succeeded,
+ * and trusting that exit code is the gap that let a shut front door sit
+ * unrestarted for days while the job meant to fix it kept reporting clean.
+ *
+ * ── WHY A ONE-SHOT PID CHECK IS NOT ENOUGH (Jacob, incident-validated) ──────
+ *
+ * A single "is there a pid, is the beat fresh" read passes two things that are
+ * NOT a revive: a PHANTOM pid (launchctl lists it, the process is dead),
+ * and a COME-UP-THEN-CRASH loop that beats once, dies, and is relaunched — its
+ * local beat file always looks fresh because the crash-looping restart keeps
+ * re-stamping it. The bar is "alive-AND-still-beating-server-side", proven two
+ * ways, either of which alone is sufficient:
+ *
+ *   1. UPTIME CONTINUITY — the one thing a crash loop cannot fake. One pid,
+ *      alive on every read (`pidAlive`), the SAME process identity (start-time,
+ *      `ps -o lstart`) across the whole settle window: no restart boundary. A
+ *      crash loop moves its start-time on every restart, so identity drift is
+ *      the tell. This alone still admits an alive-but-WEDGED process, so it is
+ *      paired with a fresh presence beat read back FROM THE SERVER — not the
+ *      local beat file, which the wedged/crash-looping process keeps stamping.
+ *      `serverBeatFresh:false` (server reachable, beat stale = alive-but-not-
+ *      publishing) blocks; `undefined` (could not reach the server) does NOT —
+ *      recovery is never held hostage to org reachability, continuity carries.
+ *
+ *   2. A COMPLETED UNIT OF WORK — the STRONGER signal when it exists, and
+ *      SUFFICIENT on its own (Jacob's positive control: A001 recovered dark →
+ *      12 authored posts). A crash loop cannot author a real unit of work.
+ *
+ * Work is sufficient, not necessary: a seat that recovered into an EMPTY queue
+ * does real nothing and MUST still pass on continuity alone — an assert that
+ * demanded work would fire a revive on every idle seat overnight and get
+ * itself disabled at 3am. Continuity-OR-work separates busy-recovered,
+ * crash-loop, phantom, AND quiet-recovered.
+ *
+ * ── THREE COMPLEMENTARY WITHIN-WINDOW CONDITIONS ────────────────────────────
+ *
+ * Continuity is three independent checks, each catching a failure the other two
+ * cannot: pid-recycling breaks start-time, a crash loop breaks pid, and a WRONG
+ * process (right pid, wrong binary) breaks comm. The third exists because `ps`
+ * is aliased to `pnpm start` on this fleet — a stray match on the wrong process
+ * would otherwise read as a revive. When the caller supplies `expectedComm` and
+ * a `comm` per sample (from `/bin/ps -p <pid> -o comm=`), a mismatch fails and
+ * NAMES `wrong-comm`; a null comm is unknown, not wrong, and continuity carries
+ * it. A caller that passes no `expectedComm` sees the pre-comm-check behaviour.
+ *
+ * @param {{
+ *   samples?:Array<{pid?:number, alive?:boolean, startTime?:string|null, comm?:string|null}>,
+ *   serverBeatFresh?:boolean, workObserved?:boolean, minSamples?:number,
+ *   expectedComm?:string
+ * }} a  `samples` are the per-read observations across the settle window;
+ *   `serverBeatFresh` is a fresh presence beat read back from the SERVER;
+ *   `workObserved` is a completed unit of work since the kickstart;
+ *   `expectedComm` is the binary name the revived pid must be running.
+ * @returns {{ok:boolean, reason:string}}
+ */
+export function confirmRevived(a) {
+  const x = a && typeof a === "object" ? a : {};
+
+  // Work is sufficient on its own and is the strongest evidence there is — a
+  // crash loop cannot produce a completed unit of work.
+  if (x.workObserved === true) return { ok: true, reason: "revived-work" };
+
+  const min = Number.isFinite(x.minSamples) && x.minSamples > 0 ? x.minSamples : DEFAULT_CONFIRM_SAMPLES;
+  const samples = Array.isArray(x.samples) ? x.samples : null;
+
+  // Fewer reads than the settle window needs cannot establish continuity: the
+  // process may be about to crash on its next breath. Not a failure to
+  // escalate — just not yet confirmed, so the caller re-checks within budget.
+  if (!samples || samples.length < min) return { ok: false, reason: "settling" };
+
+  // A live pid must appear SOMEWHERE in the window. If none ever did — every
+  // read dead — the helper claimed a process that is not there: a phantom pid
+  // (launchctl lists it, `kill -0` says dead) or an exit-0-with-no-pid. That is
+  // the failure-to-escalate that hands the seat to a person.
+  const isAlive = (s) => s && Number.isInteger(s.pid) && s.pid > 0 && s.alive === true;
+  const aliveSamples = samples.filter(isAlive);
+  if (aliveSamples.length === 0) return { ok: false, reason: "no-pid" };
+
+  // A dead read FOLLOWED BY a live one is a daemon mid-boot, not a failed
+  // revive. The first settle sample is taken the instant the kickstart returns,
+  // before a normal slow boot has drawn its first breath — so a dead first read
+  // then an alive one is boot-in-progress. Latching that as terminal aborts a
+  // revive that was working. A window that is not yet all-alive is still
+  // SETTLING: re-check within budget rather than escalate. Only two genuinely
+  // ALIVE reads can prove — or refute — continuity.
+  if (aliveSamples.length < samples.length) return { ok: false, reason: "settling" };
+
+  // Every read is alive. Same pid AND same start-time across the window = one
+  // instance that never restarted. A restart boundary between two ALIVE reads —
+  // a different pid, or the same pid with a different start-time (PID reuse by
+  // the relaunched process) — is the fingerprint of a crash loop, never a
+  // revive. `startTime` may be null on both when `ps` was unavailable;
+  // identical-null still agrees, and the pid continuity carries the degraded
+  // case.
+  const first = aliveSamples[0];
+  const continuous = aliveSamples.every((s) => s.pid === first.pid && s.startTime === first.startTime);
+  if (!continuous) return { ok: false, reason: "restart-boundary" };
+
+  // THIRD within-window condition: the binary under the pid must be the one we
+  // kickstarted. Right pid, right start-time, WRONG process is still not a
+  // revive — and `ps` aliased to `pnpm start` on this fleet makes a stray match
+  // real. Opt-in: only when the caller supplies `expectedComm`. A null comm is
+  // unknown (ps unavailable / pid vanished), not wrong — continuity carries it,
+  // as a null start-time does; only an OBSERVED, mismatching comm fails. Matched
+  // by suffix because `ps -o comm=` prints the absolute path and the expected
+  // value is a bare binary name.
+  if (x.expectedComm) {
+    const want = String(x.expectedComm);
+    const observed = aliveSamples.filter((s) => s.comm != null);
+    const commOk = observed.every((s) => {
+      const got = String(s.comm);
+      return got === want || got.endsWith(`/${want}`) || want.endsWith(`/${got}`);
+    });
+    if (!commOk) return { ok: false, reason: "wrong-comm" };
+  }
+
+  // Alive and continuous, but is it actually WORKING? The local beat file lies
+  // in a wedge, so the confirming signal is the presence beat the server
+  // recorded. An explicit stale reading (reachable, not publishing) blocks; an
+  // unknown reading (unreachable) does not — continuity carries it.
+  if (x.serverBeatFresh === false) return { ok: false, reason: "beat-not-advancing" };
+
+  return { ok: true, reason: "revived" };
+}
+
+/**
+ * A confirm outcome that must STOP the revive and hand the seat to a person,
+ * rather than fire another blind kickstart. A second attempt after a crash-loop
+ * assert buries the FIRST failure's log under the loop, so these outcomes are
+ * terminal: `no-pid` (phantom / exit-0-with-no-pid), `restart-boundary`
+ * (came-up-then-crashed within the settle window), `wrong-comm` (a live pid
+ * running the wrong binary — not the process we kickstarted), and
+ * `crash-loop-cross-poll` (an unrequested restart caught a poll later — the
+ * crash loop whose period outran the settle window). `settling` and
+ * `beat-not-advancing` are "not yet" — the caller may re-check within budget.
+ *
+ * @param {{ok?:boolean, reason?:string}} confirmed
+ * @returns {boolean}
+ */
+export function isTerminalReviveFailure(confirmed) {
+  const r = confirmed && confirmed.reason;
+  return r === "no-pid" || r === "restart-boundary" || r === "wrong-comm" || r === "crash-loop-cross-poll";
+}
+
+/**
+ * Did the session job restart WITHOUT this daemon asking it to, BETWEEN two
+ * daemon polls? The unbounded companion to `confirmRevived`'s within-window
+ * continuity check.
+ *
+ * ── WHY WITHIN-WINDOW CONTINUITY IS NOT ENOUGH ──────────────────────────────
+ *
+ * `confirmRevived` proves continuity across a SETTLE WINDOW (a few seconds). A
+ * crash loop whose period EXCEEDS that window shows the SAME identity twice
+ * inside it — two alive reads, same pid, same start-time — and false-confirms
+ * "revived". A 25s crash-loop period against a 5s settle window is invisible to
+ * a within-window check, and WIDENING the window only relocates the threshold:
+ * a 65s period beats a 60s window just as cleanly.
+ *
+ * The fix has no threshold to tune. The daemon persists the last-confirmed
+ * {pid, startTime} between its 60s poll iterations. On the NEXT poll, if the job
+ * holds a DIFFERENT identity (a different pid, OR the same pid with a moved
+ * start-time from PID reuse by the relaunched process) AND this daemon issued NO
+ * kickstart in the interval, that is an UNREQUESTED restart — the crash loop, at
+ * ANY period. A changed identity WITH a kickstart in between is exactly what a
+ * legitimate revive looks like and is never flagged.
+ *
+ * Pure: the verdict only. The daemon owns the persistence, the kickstart flag,
+ * and the halt.
+ *
+ * @param {{prev?:{pid?:number, startTime?:string|null}|null,
+ *          curr?:{pid?:number, startTime?:string|null}|null,
+ *          kickstartIssuedSince?:boolean}} a
+ *   `prev` is the last poll's confirmed identity (null on the first poll);
+ *   `curr` is this poll's observed identity; `kickstartIssuedSince` is whether
+ *   THIS daemon kickstarted the job between the two polls.
+ * @returns {{restarted:boolean, reason:string}}
+ */
+export function detectUnrequestedRestart(a) {
+  const x = a && typeof a === "object" ? a : {};
+  const prev = x.prev && typeof x.prev === "object" ? x.prev : null;
+  const curr = x.curr && typeof x.curr === "object" ? x.curr : null;
+
+  // Nothing to compare against yet — the first poll after boot establishes the
+  // baseline, it cannot judge drift from one.
+  if (!prev || !(Number.isInteger(prev.pid) && prev.pid > 0)) return { restarted: false, reason: "no-prior" };
+
+  // No live identity this poll is a DOWN door, not an identity change — that is
+  // the revive ladder's job. This function speaks only to drift between two
+  // observed identities.
+  if (!curr || !(Number.isInteger(curr.pid) && curr.pid > 0)) return { restarted: false, reason: "no-current" };
+
+  const sameIdentity = curr.pid === prev.pid && curr.startTime === prev.startTime;
+  if (sameIdentity) return { restarted: false, reason: "continuous" };
+
+  // Identity changed. If this daemon asked for it, that is a legitimate revive,
+  // not the loop.
+  if (x.kickstartIssuedSince === true) return { restarted: false, reason: "kickstart-issued" };
+
+  // Changed identity, no kickstart in between: an unrequested restart — the
+  // crash loop, at whatever period it runs.
+  return { restarted: true, reason: "unrequested-restart" };
+}
+
 /**
  * The command that restarts the front-door job. Pure — the caller runs it.
  *

package/lib/telemetry/alerts.mjs

@@ -19,6 +19,10 @@
  *   - subAgentsRunning over the cap      → INFO (more children than expected).
  *   - machine.sessionNote present        → WARNING/CRITICAL (frontdoor) — the
  *                                          seat's front door is not answering.
+ *   - machine.upgrade.failStreak >= N    → WARNING/CRITICAL (rollout) — N
+ *                                          consecutive attempts to reach
+ *                                          @latest have failed; the seat is
+ *                                          stranded on old code.
  *
  * Output: a deterministic array `[{ id, severity, kind, detail }, ...]` (the
  * snapshot's alert shape) sorted critical→warning→info then by id, so identical
@@ -90,6 +94,30 @@ export const DEFAULT_THRESHOLDS = Object.freeze({
     warnMs: 15 * 60 * 1000,
     critMs: 2 * 60 * 60 * 1000,
   }),
+  /**
+   * How many CONSECUTIVE failed attempts to reach @latest make a seat STUCK.
+   *
+   * `warnStreak` 3, not 1: one failure is a bad release or a slow mirror and
+   * the hourly job is entitled to try again; the failed-target hold already
+   * spaces those out. Three separate, completed attempts have failed, which
+   * means every fix the seat can apply to itself has been applied three times
+   * and the seat is still where it was.
+   *
+   * `critStreak` 6: past this the seat has been refusing @latest for the best
+   * part of a week under the default 24 h hold — which is exactly how long
+   * three seats sat on 2.17.0 while every hourly log line was individually
+   * correct. A release that cannot reach a colleague is not a machine problem
+   * that resolves itself; it waits for a person, like a scope fault.
+   */
+  upgradeStuck: Object.freeze({
+    // THE ONE DEFINITION of the stuck threshold. scripts/fleet/rollout.mjs
+    // imports `warnStreak` as its STUCK_STREAK rather than restating it, and
+    // the shell copy (autoupdate.sh) is pinned against this value by a
+    // source-reading test — because three literals agreeing by comment is the
+    // prose-promise-instead-of-a-check pattern this repo bans.
+    warnStreak: 3,
+    critStreak: 6,
+  }),
   replyDebt: Object.freeze({
     // ONE withheld reply is already worth saying. This is not a resource gauge
     // where a low reading is normal noise — it counts people who asked this
@@ -175,6 +203,7 @@ export function deriveAlerts(status, thresholds, now = Date.now()) {
     push(alerts, frontDoorRule(machine, t.frontDoor, now));
     push(alerts, scopeFaultRule(machine));
     push(alerts, repliesWithheldRule(machine, t.replyDebt));
+    push(alerts, upgradeStuckRule(machine, t.upgradeStuck, now));
 
     alerts.sort((a, b) => {
       const r = (SEVERITY_RANK[a.severity] ?? 9) - (SEVERITY_RANK[b.severity] ?? 9);
@@ -282,6 +311,71 @@ function repliesWithheldRule(machine, cfg = {}) {
   };
 }
 
+/**
+ * THIS SEAT CANNOT GET TO @latest, AND HAS PROVED IT N TIMES.
+ *
+ * Every other rule in this file reads a gauge. This one reads a COUNT of
+ * completed failures, because the failure it names has no gauge: on 2026-09-25
+ * three seats were found sitting on 2.17.0 while the fleet ran 2.18.13, and
+ * nothing anywhere was in an error state. The launchd job fired hourly, npm
+ * answered, the install ran, the health gate did its job, the rollback worked,
+ * `last.json` recorded the outcome honestly and the beat carried it. Each hour
+ * was a correct, self-contained failure — and the org has no way to see the
+ * difference between the first one and the fortieth, which is the only thing
+ * that distinguishes "a release is settling" from "a colleague is stranded on
+ * code from three weeks ago and will never leave it unaided".
+ *
+ * WHY THIS RIDES THE EXISTING BEAT AND NOTHING ELSE. The seats this rule is
+ * about are, by construction, running the OLDEST code in the fleet — so any
+ * new channel it might use is the one channel they do not have. `machine.upgrade`
+ * is a field their beat already carries; the count is added to it, and this
+ * rule turns it into an alert on the seats new enough to run this file.
+ *
+ * FOR THE ONES THAT ARE NOT, THIS RULE IS STRUCTURALLY BLIND AND SAYING SO IS
+ * PART OF THE DESIGN. A seat too stale to install the SDK runs a collector that
+ * never writes `failStreak` and an alerts file that has never heard of this
+ * rule — so the alert cannot reach exactly the seats it was written for. The
+ * fleet-side derivation covers them from outside: `seatStuck()` in
+ * scripts/fleet/rollout.mjs reads the same fact out of a 2.17-era beat, and
+ * `propagationOutcome()` there returns reason `"stuck"` so that stage 3 of
+ * every publish exits non-zero and names the machine. That path is automatic
+ * because publishing is; nobody has to decide to go looking.
+ *
+ * Both answer (d) the same way: a streak counts ATTEMPTS, and a seat that has
+ * not been asked has made none.
+ *
+ * DISTINCT FROM DRIFT. A `stranded` seat (framework paths pinned in
+ * `.maestroignore`, `machine.stranded`) cannot RECEIVE parts of a release it
+ * did install; a STUCK seat never installs the release at all. Different
+ * cause, different fix, different alert id — they can be true at once.
+ */
+function upgradeStuckRule(machine, cfg = {}, now = Date.now()) {
+  const u = machine && machine.upgrade;
+  if (!u || typeof u !== "object") return null;
+  // Strict: the producer (autoupdate.sh via collect.upgradeSummary) writes an
+  // integer, and both validate it. A string here means something else wrote
+  // this record, and a rule that coerces would be reporting on a shape it does
+  // not understand.
+  const n = Number.isInteger(u.failStreak) ? u.failStreak : 0;
+  if (!(n > 0)) return null;
+  const sev = severityFor(n, num(cfg.warnStreak, Infinity), num(cfg.critStreak, Infinity));
+  if (!sev) return null;
+  const target = typeof u.streakTarget === "string" && u.streakTarget ? u.streakTarget : (typeof u.to === "string" ? u.to : "@latest");
+  // A DURATION, not only a tally: four attempts since Monday and four attempts
+  // in the last hour are different seats with different urgency, and the count
+  // alone cannot tell them apart.
+  const sinceMs = typeof u.stuckSince === "string" ? Date.parse(u.stuckSince) : NaN;
+  const days = Number.isFinite(sinceMs) ? Math.floor((now - sinceMs) / 86400000) : null;
+  const forHow = days === null ? "" : days >= 1 ? ` over ${days} ${days === 1 ? "day" : "days"}` : " today";
+  const why = typeof u.reason === "string" && u.reason ? ` Last failure: ${u.reason.split(":")[0]}.` : "";
+  return {
+    id: "upgrade_stuck",
+    severity: sev,
+    kind: "rollout",
+    detail: `${n} consecutive upgrade attempts to ${target} have failed${forHow} — this seat is running ${typeof u.from === "string" && u.from ? u.from : "older code"} and will not arrive on its own.${why} It needs a person at the machine.`,
+  };
+}
+
 function subAgentsRule(status, cfg = {}) {
   const v = num(status.subAgentsRunning);
   const cap = num(cfg.infoCap, Infinity);