@cohortapp/agent-sdk 2.18.14 → 2.18.15

package/scripts/fleet/rollout.mjs

@@ -102,6 +102,7 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
+import { DEFAULT_THRESHOLDS } from "../../lib/telemetry/alerts.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const REPO_ROOT = resolvePath(dirname(__filename), "..", "..");
@@ -394,6 +395,130 @@ export function seatVersions(entry) {
   return { installed, running, version, basis: version === null ? null : running ? "running" : "installed" };
 }
 
+/**
+ * How long a failed upgrade attempt may stand, unrepeated, before a seat that
+ * is still on the version it failed FROM counts as stuck rather than merely
+ * recovering. Two full failed-target holds (the autoupdater's default is 24 h):
+ * one hold is the seat being deliberately left alone, two means the retry it
+ * was owed has been and gone.
+ */
+export const ATTEMPT_STALE_MS = 48 * 60 * 60 * 1000;
+
+/**
+ * Consecutive failed attempts that make a seat stuck.
+ *
+ * DERIVED, NOT RESTATED. This used to be `= 3` with a comment promising it
+ * "matches lib/telemetry/alerts.mjs upgradeStuck.warnStreak" — a prose promise
+ * about a literal, which is the exact shape the repo doctrine bans and which no
+ * test could have caught: this file's own tests use the constant symbolically
+ * (`at(STUCK_STREAK - 1)` / `at(STUCK_STREAK)`), so they pass at ANY value and
+ * the two copies could have drifted silently. The seat-side alert rule is the
+ * authority — it is what actually fires on a live beat — so this reads it.
+ *
+ * The third copy lives in the shell (`STUCK_STREAK` in
+ * scripts/local-triggers/autoupdate.sh), which cannot import this; it is pinned
+ * against this value by a source-reading test instead
+ * (scripts/local-triggers/autoupdate.test.mjs, "source: the shell's streak
+ * threshold is the same number the alert fires on").
+ */
+export const STUCK_STREAK = DEFAULT_THRESHOLDS.upgradeStuck.warnStreak;
+
+/**
+ * The first SDK release whose `write_last` keeps a `failStreak` in
+ * state/autoupdate/last.json. A seat below this reports one upgrade outcome and
+ * no count — not because its beat is stale, but because the collector that
+ * would write the count is the code it has not got.
+ *
+ * This exists because the "attempt" basis used to explain itself with "this
+ * seat's beat is too old to carry a count", attached unconditionally to every
+ * attempt-basis row. At rollout time NO released SDK wrote `failStreak`, so
+ * every seat in the fleet — including ones beating every 30 seconds with
+ * `reason` and `healthy` on the record — was told its beat was too old. The
+ * beat age was never the reason; the seat's VERSION is.
+ */
+export const FAILSTREAK_SINCE = "2.18.15";
+
+/**
+ * IS THIS SEAT STUCK — i.e. has it tried to reach @latest and failed, and will
+ * it keep failing?
+ *
+ * `classifySeat` says a seat is `stale`. That is a snapshot and it is not the
+ * finding: a seat is stale for twenty minutes after every publish, and three
+ * seats were stale for three weeks. What separates them is whether the seat has
+ * ATTEMPTED the hop and failed, and how many times — and that fact has always
+ * been in the beat (`machine.upgrade`) without anything reading it.
+ *
+ * TWO BASES, BECAUSE THE SEATS THIS MATTERS FOR REPORT THE LEAST. A seat that
+ * has been left behind for weeks is by definition running the oldest collector
+ * in the fleet, so it emits the smallest beat: on 2026-09-25 the three seats on
+ * 2.17.0 were the only three in the org with no `machine.daemon` block and no
+ * `machine.stranded` — staleness hides itself by removing the fields that would
+ * announce it. So this reads what a 2.17-era beat DOES carry, and names which
+ * basis it used rather than pretending to one answer:
+ *
+ *   basis "streak"  — the seat counted its own consecutive failures
+ *                     (`machine.upgrade.failStreak`, SDK {@link FAILSTREAK_SINCE}
+ *                     and later). Stuck at {@link STUCK_STREAK}. The real signal.
+ *   basis "attempt" — an old beat, which carries one outcome and no count. A
+ *                     failed attempt (`ok:false`, `to` != `from`) with the seat
+ *                     STILL reporting `from` proves the hop did not take; older
+ *                     than {@link ATTEMPT_STALE_MS} it also proves the retry it
+ *                     was owed came and went. Below that age it is `failing`,
+ *                     not `stuck` — which is the same rule the streak obeys and
+ *                     the same rule (d) asks for: a seat that has not been
+ *                     ASKED again is not a stuck seat.
+ *
+ * Returns null when the beat carries no upgrade record at all: never tried is
+ * not the same as tried and failed, and must not print as one.
+ *
+ * Pure; `now` is a parameter because the "attempt" basis is about a duration.
+ *
+ * @param {object} entry   a directory member, or anything {@link seatVersions} accepts
+ * @param {number} [now]   epoch ms
+ * @returns {{verdict:"stuck"|"failing", basis:"streak"|"attempt", failStreak:number|null,
+ *            target:string|null, since:string|null, ageMs:number|null}|null}
+ */
+export function seatStuck(entry, now = Date.now()) {
+  const e = entry && typeof entry === "object" ? entry : {};
+  const st = (e.status && typeof e.status === "object" && e.status) || {};
+  const mach = (st.machine && typeof st.machine === "object" && st.machine) || (e.machine && typeof e.machine === "object" && e.machine) || {};
+  const u = mach.upgrade && typeof mach.upgrade === "object" ? mach.upgrade : null;
+  if (!u) return null;
+
+  const streak = Number.isInteger(u.failStreak) && u.failStreak > 0 ? u.failStreak : null;
+  const target = firstString([u.streakTarget, u.to]);
+  if (streak !== null) {
+    const sinceS = firstString([u.stuckSince, u.at]);
+    const sinceMs = sinceS ? Date.parse(sinceS) : NaN;
+    return {
+      verdict: streak >= STUCK_STREAK ? "stuck" : "failing",
+      basis: "streak",
+      failStreak: streak,
+      target,
+      since: sinceS,
+      ageMs: Number.isFinite(sinceMs) ? now - sinceMs : null,
+    };
+  }
+
+  // Degraded read: one outcome, no count.
+  if (u.ok !== false) return null;
+  const from = typeof u.from === "string" ? u.from : "";
+  const to = typeof u.to === "string" ? u.to : "";
+  if (!from || !to || from === to) return null;           // not an upgrade attempt
+  const installed = seatVersions(e).installed;
+  if (installed && installed !== from) return null;       // it has moved since; whatever failed is history
+  const atMs = typeof u.at === "string" ? Date.parse(u.at) : NaN;
+  const ageMs = Number.isFinite(atMs) ? now - atMs : null;
+  return {
+    verdict: ageMs !== null && ageMs > ATTEMPT_STALE_MS ? "stuck" : "failing",
+    basis: "attempt",
+    failStreak: null,
+    target: to,
+    since: typeof u.at === "string" ? u.at : null,
+    ageMs,
+  };
+}
+
 /**
  * The single version a seat is judged on, or null when the read carries none.
  * Kept as its own export because it is the whole of what `classifySeat` needs;
@@ -421,7 +546,7 @@ export function seatVersion(entry) {
  * not written for.
  *
  * @param {object[]} members
- * @param {{seatWindowMs?:number}} [o]
+ * @param {{seatWindowMs?:number, now?:number}} [o]
  * @returns {{seats:object[], nonSeats:object[], readCarriesVersionField:boolean}}
  */
 export function toSeats(members, o = {}) {
@@ -446,6 +571,7 @@ export function toSeats(members, o = {}) {
       detail: (p && p.detail) || "",
       lastBeatMs: beatMs,
       ...seatVersions(m),
+      stuck: seatStuck(m, o.now),
     };
     if (beatMs !== null && beatMs <= windowMs) seats.push(row);
     else nonSeats.push(row);
@@ -480,15 +606,38 @@ export function summarise(fleet, target) {
   const rows = (fleet.seats || []).map((s) => ({ ...s, verdict: classifySeat(s, target) }));
   const counts = { current: 0, stale: 0, unverifiable: 0 };
   for (const r of rows) counts[r.verdict] += 1;
+  // Behind AND proved it cannot arrive — a strictly stronger statement than
+  // `stale`, which clears itself on the next hourly run.
+  //
+  // `stuck` IS NOT A SUBSET OF `stale`, and the code used to assume it was. A
+  // seat's verdict is about THIS run's target; its streak is about whatever
+  // `@latest` was when it last tried, and the two are different versions
+  // whenever a rollout is verified against anything but the registry's head —
+  // `--dry-run`, `--verify-only`, or simply a publish that has since been
+  // followed by another. Demonstrated: one seat on target 2.18.14 whose record
+  // is {ok:false, from:"2.18.14", to:"2.18.15", failStreak:5} classifies
+  // `current`, so `stale` is empty, `done` was true, and renderVerdict's early
+  // return printed "All 1 seat(s) report 2.18.14." — five consecutive failed
+  // upgrades reported as a fully current fleet. So the two sets are kept and
+  // named apart, and `done` answers BOTH questions: every seat is on the target
+  // AND no seat is known to be unable to move.
+  const stuck = rows.filter((r) => r.stuck && r.stuck.verdict === "stuck");
+  const stale = rows.filter((r) => r.verdict === "stale");
+  const staleSlugs = new Set(stale.map((r) => r.slug));
   return {
     target,
     rows,
     counts,
     nonSeats: fleet.nonSeats || [],
-    stale: rows.filter((r) => r.verdict === "stale"),
+    stale,
     unverifiable: rows.filter((r) => r.verdict === "unverifiable"),
+    stuck,
+    /** The stuck seats that are ALSO behind this run's target — "N of those". */
+    stuckBehind: stuck.filter((r) => staleSlugs.has(r.slug)),
+    /** Stuck against some other version while current on this one. Still a finding. */
+    stuckElsewhere: stuck.filter((r) => !staleSlugs.has(r.slug)),
     readCarriesVersionField: fleet.readCarriesVersionField === true,
-    done: rows.length > 0 && counts.current === rows.length,
+    done: rows.length > 0 && counts.current === rows.length && stuck.length === 0,
   };
 }
 
@@ -518,7 +667,7 @@ export function renderSeatTable(summary, o = {}) {
     r.slug,
     ageLabel(r.lastBeatMs),
     r.version ? (r.basis === "installed" ? `${r.version} (installed)` : r.version) : "unknown",
-    r.verdict,
+    r.stuck ? `${r.verdict} · ${r.stuck.verdict}${r.stuck.failStreak ? ` ×${r.stuck.failStreak}` : ""}` : r.verdict,
   ]);
   const widths = head.map((h, i) => Math.max(h.length, ...body.map((row) => row[i].length), 0));
   const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
@@ -538,9 +687,19 @@ export function renderSeatTable(summary, o = {}) {
   return out.join("\n");
 }
 
-/** The closing sentence naming exactly which seats are behind. Pure. */
+/**
+ * The closing sentence naming exactly which seats are behind, and which of them
+ * will never arrive unaided. Pure.
+ *
+ * NO EARLY RETURN ON `done`. It used to open with
+ * `if (summary.done) return "All N seat(s) report X."`, which swallowed the
+ * STUCK line whole for any seat that was stuck against a version other than
+ * this run's target — see the note in {@link summarise}. `done` now accounts
+ * for stuck seats, and the "all clear" sentence is built at the END, from the
+ * absence of every finding, so a future finding cannot be skipped past by a
+ * `done` that did not learn about it.
+ */
 export function renderVerdict(summary) {
-  if (summary.done) return `All ${summary.rows.length} seat(s) report ${summary.target}.`;
   const parts = [];
   if (summary.stale.length) {
     parts.push(
@@ -548,6 +707,27 @@ export function renderVerdict(summary) {
         summary.stale.map((r) => `${r.name} (${r.slug}, reports ${r.version})`).join(", ")
     );
   }
+  const stuck = (summary.stuck && summary.stuck.length ? summary.stuck : []);
+  if (stuck.length) {
+    // Said SEPARATELY from "behind", and after it, because the response is
+    // different: a behind seat is waited on, a stuck one is visited. The line
+    // that was missing for three weeks is this one.
+    const behind = summary.stuckBehind || stuck.filter((r) => r.verdict === "stale");
+    const elsewhere = summary.stuckElsewhere || stuck.filter((r) => r.verdict !== "stale");
+    // "N of those" is only true of the ones that ARE among the seats just named
+    // as behind. A seat that is current on this target and stuck against a
+    // later one is not "one of those" and must not be counted as if it were.
+    const head =
+      elsewhere.length === 0
+        ? `${behind.length} of those ${behind.length === 1 ? "is" : "are"} STUCK`
+        : behind.length === 0
+          ? `${elsewhere.length} seat(s) ${elsewhere.length === 1 ? "is" : "are"} STUCK — on ${summary.target}, but unable to move off it`
+          : `${stuck.length} seat(s) are STUCK (${behind.length} of those just named as behind, ${elsewhere.length} current on ${summary.target} but unable to move off it)`;
+    parts.push(
+      `${head} — attempted and failed, and will not arrive unaided: ` +
+        stuck.map((r) => `${r.name} (${r.slug}, ${stuckClause(r, summary.target)})`).join(", ")
+    );
+  }
   if (summary.unverifiable.length) {
     parts.push(
       `${summary.unverifiable.length} seat(s) could not be verified — the org read carries no sdkVersion: ` +
@@ -555,9 +735,46 @@ export function renderVerdict(summary) {
     );
   }
   if (!summary.rows.length) parts.push("no beating seats found in the org directory — nothing to verify.");
+  if (!parts.length) return `All ${summary.rows.length} seat(s) report ${summary.target}.`;
   return parts.join("\n");
 }
 
+/**
+ * One stuck seat's parenthetical: what it tried, how many times, and — only
+ * when it is true — why it cannot say how many times.
+ *
+ * THE "no count" SENTENCE IS GATED ON THE SEAT'S VERSION, NOT ON THE BRANCH
+ * THAT PRODUCED THE VERDICT. It used to hang off `basis === "attempt"` and
+ * read "this seat's beat is too old to carry a count". Every attempt-basis row
+ * got it, which at the time this landed was every row in the fleet — no
+ * released SDK wrote `failStreak` yet — including seats beating every thirty
+ * seconds whose records demonstrably carried `reason` and `healthy`. The beat
+ * was never old; the seat's SDK simply predates {@link FAILSTREAK_SINCE}. When
+ * the seat is new enough to count and still did not, that is a DIFFERENT and
+ * more interesting fact, so it gets its own words. Pure.
+ *
+ * @param {object} row  a summarise() row with a non-null `stuck`
+ * @param {string} target
+ * @returns {string}
+ */
+export function stuckClause(row, target) {
+  const st = row.stuck;
+  const attempts = st.failStreak ? `${st.failStreak} consecutive failed attempts` : "a failed attempt";
+  const oldest = Number.isFinite(st.ageMs) ? `, oldest ${ageLabel(st.ageMs)} ago` : "";
+  let why = "";
+  if (st.basis === "attempt") {
+    const v = row.version;
+    if (v && compareVersions(v, FAILSTREAK_SINCE) < 0) {
+      why = `; it reports ${v}, which predates the failure count (SDK ${FAILSTREAK_SINCE}), so one attempt is all it can report`;
+    } else if (v) {
+      why = `; it reports ${v}, new enough to count its failures, but this record carries none — read state/autoupdate/last.json on the machine`;
+    } else {
+      why = "; this seat reports no version, so there is no telling whether it could have counted";
+    }
+  }
+  return `${attempts} to ${st.target || target}${oldest}${why}`;
+}
+
 /**
  * What stage 3's exit code will be, and WHY — as data, so a caller can tell the
  * three very different things a `3` means apart.
@@ -579,7 +796,7 @@ export function renderVerdict(summary) {
  * Pure.
  *
  * @param {ReturnType<typeof summarise>|null|undefined} summary
- * @returns {{code:number, reason:"verified"|"behind"|"unverifiable"|"empty-fleet"|"no-fleet-read", note:string|null}}
+ * @returns {{code:number, reason:"verified"|"stuck"|"behind"|"unverifiable"|"empty-fleet"|"no-fleet-read", note:string|null}}
  */
 export function propagationOutcome(summary) {
   if (!summary || !Array.isArray(summary.rows)) {
@@ -590,6 +807,28 @@ export function propagationOutcome(summary) {
     };
   }
   if (summary.done) return { code: 0, reason: "verified", note: null };
+  // STUCK OUTRANKS BEHIND, and is checked before both `empty-fleet` and the
+  // unverifiable branch, because it is the only one of the three that a person
+  // must ACT on rather than wait out.
+  //
+  // This is also the automation the seat-side alert cannot provide. `upgrade_stuck`
+  // is derived by lib/telemetry/alerts.mjs running ON the seat, so a seat too
+  // stale to install the SDK never emits it — by construction the alert cannot
+  // reach the seats it is for. What CAN reach them is this: the fleet-side
+  // derivation runs on every publish, because stage 3 runs on every publish,
+  // and a stuck seat now makes the release command exit non-zero and name the
+  // machine. Nobody has to decide to go looking.
+  if (summary.stuck && summary.stuck.length) {
+    return {
+      code: 3,
+      reason: "stuck",
+      note:
+        `${summary.stuck.length} seat(s) have attempted @latest and failed repeatedly. They will not arrive on their own: ` +
+        `each needs a person at the machine (maestro doctor; state/autoupdate/last.json carries the reason). ` +
+        `Stage 3 still polls to its deadline in case someone clears one while it runs, but it will not clear itself. ` +
+        renderVerdict(summary),
+    };
+  }
   if (!summary.rows.length) {
     return {
       code: 3,

package/scripts/local-triggers/autoupdate.sh

@@ -481,18 +481,133 @@ write_notice(){ # $1 = from, $2 = to, [$3 = reason → healthy:false] — tell t
 }
 write_upgrade_notice(){ write_notice "$1" "$2"; }
 LAST_JSON="$AGENT_DIR/state/autoupdate/last.json"
-write_last(){ # $1 from, $2 to, $3 ok, $4 healthy, $5 reason — state/autoupdate/last.json (→ beat machine.upgrade)
-  local dir="$AGENT_DIR/state/autoupdate" tmp
+# How many CONSECUTIVE failed attempts to reach @latest make a seat STUCK, and
+# at what point it stops being a warning. See the `failStreak` block below.
+STUCK_STREAK="${MAESTRO_AUTOUPDATE_STUCK_STREAK:-3}"
+# ── failStreak — "this seat cannot get to @latest" is a FACT, not a discovery ─
+# The fleet learned on 2026-09-25 that three seats had sat on 2.17.0 for days.
+# Nothing was broken in the sense anything reports: the launchd job fired every
+# hour, npm answered, the install ran, the health gate failed, the rollback
+# worked, last.json recorded it honestly, and the beat carried it. Each hour was
+# a correct, self-contained failure — and a correct failure repeated forty times
+# is a different fact from a correct failure once. Only the REPETITION says the
+# seat will never arrive on its own, and no single record can hold it, so the
+# count lives in last.json and rides the beat the rest of that record already
+# rides. There is no second channel here and there must not be one: the seats
+# this is about are, by construction, the ones running the oldest code.
+#
+# WHAT COUNTS AS AN ATTEMPT — the whole honesty of the number:
+#   · An ATTEMPT is a record whose `to` differs from its `from`: the upgrade
+#     path actually installed (or tried to install) a different version. Those
+#     are the only records that move the streak.
+#   · A FAILED attempt (`ok:false`) increments it and stamps `stuckSince` with
+#     the first failure of the run of failures, so a reader gets a DURATION and
+#     not merely a tally — "4 attempts since Monday" and "4 attempts in the last
+#     hour" are different seats.
+#   · A SUCCEEDED attempt (`ok:true`) clears all three fields. Arrival is the
+#     only thing that resets it; a fleet-wide publish does not, because a seat
+#     that fails 2.18.12, 2.18.13 and 2.18.14 in turn has failed three times to
+#     do the one thing asked of it, and restarting the count on every release
+#     would guarantee the number never reaches any threshold.
+#   · Everything else PRESERVES the fields untouched. A `to == from` record is
+#     a report on the installed version, not an attempt to leave it, so it must
+#     not move a count of ATTEMPTS in either direction. (Every such call site
+#     today sits on the up-to-date branch and therefore takes the arrival path
+#     below instead — this rule governs the writer, for the next caller that
+#     does not.) And a run that SKIPS writes no record at all, which is the
+#     same preservation by a shorter route. THIS IS THE POINT OF (d): a seat that has not been ASKED —
+#     nothing newer published, or held for the day after its last failure — is
+#     not a stuck seat, and must never accumulate a streak for sitting still.
+#     Only a real, completed, failed attempt does.
+#   · WHICH RUNS ACTUALLY SKIP — the exact list, because a wrong one was
+#     written here first. The paths that reach `exit 0` with NO write_last are:
+#     the failed-target hold, the overlap lock, the kill-switch, and a failed
+#     `npm view`. "SIMPLY BEING UP TO DATE" IS NOT AMONG THEM and never was —
+#     the up-to-date branch is the daemon health gate, and it calls write_last
+#     on every one of its outcomes (healthy, unhealthy-current,
+#     ahead-of-registry, recovered, and the stale-daemon kickstart). The
+#     original text claimed otherwise; nothing checked it, and the streak
+#     arithmetic on that branch is not what the sentence implied.
+#   · ARRIVAL IS BEING AT @latest, NOT MERELY INSTALLING IT. Every write on the
+#     up-to-date branch passes `at_latest=true`, which clears all three fields
+#     — because that branch is only entered when `CUR >= LATEST`, i.e. there is
+#     nothing left for this seat to reach. That covers the case the increment
+#     rule alone gets wrong: if a bad release is YANKED and @latest rolls back
+#     to the version a seat already runs, the seat stops attempting anything,
+#     so nothing would ever reset it and `upgrade_stuck` would fire forever
+#     (critical past 6) on a seat that is in fact perfectly current. It also
+#     makes the stale-daemon kickstart record honest rather than accidental:
+#     that hop really is an arrival.
+# The write is done in node rather than printf because the record now depends on
+# the record before it; a shell that reads a file it is about to overwrite gets
+# that wrong at exactly the moments it matters.
+write_last(){ # $1 from, $2 to, $3 ok, $4 healthy, $5 reason, [$6 at_latest] — state/autoupdate/last.json (→ beat machine.upgrade)
+  local dir="$AGENT_DIR/state/autoupdate" tmp streak at_latest="${6:-false}"
   mkdir -p "$dir" 2>/dev/null || return 0
   tmp="$(mktemp "$dir/.last.XXXXXX" 2>/dev/null)" || return 0
-  printf '{\n  "from": "%s",\n  "to": "%s",\n  "at": "%s",\n  "ok": %s,\n  "healthy": %s,\n  "reason": "%s"\n}\n' \
-    "$1" "$2" "$(date -u +%FT%TZ)" "$3" "$4" "$(json_str "$5")" > "$tmp" && mv -f "$tmp" "$LAST_JSON"
+  streak="$(node -e '
+    const fs = require("fs");
+    const [file, tmp, from, to, okS, healthyS, reason, stuckStreakS, atLatestS] = process.argv.slice(1);
+    const ok = okS === "true";
+    const at = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    let prev = null;
+    try { prev = JSON.parse(fs.readFileSync(file, "utf8")); } catch {}
+    if (!prev || typeof prev !== "object") prev = {};
+    const prevStreak = Number.isInteger(prev.failStreak) && prev.failStreak > 0 ? prev.failStreak : 0;
+    const attempt = from !== to;               // an upgrade was actually tried
+    const atLatest = atLatestS === "true";     // this seat is AT or past @latest — nothing left to reach
+    let failStreak, stuckSince, streakTarget;
+    if (atLatest || (attempt && ok)) {         // arrival, by install OR because @latest came back to us (a yank)
+      failStreak = 0; stuckSince = ""; streakTarget = "";
+    } else if (!attempt) {                     // a report on the installed version — carry the count, do not touch it
+      failStreak = prevStreak;
+      stuckSince = typeof prev.stuckSince === "string" ? prev.stuckSince : "";
+      streakTarget = typeof prev.streakTarget === "string" ? prev.streakTarget : "";
+    } else {
+      failStreak = prevStreak + 1;
+      stuckSince = typeof prev.stuckSince === "string" && prev.stuckSince ? prev.stuckSince : at;
+      streakTarget = to;
+    }
+    const rec = { from, to, at, ok, healthy: healthyS === "true", reason };
+    if (failStreak > 0) {
+      rec.failStreak = failStreak;
+      if (stuckSince) rec.stuckSince = stuckSince;
+      if (streakTarget) rec.streakTarget = streakTarget;
+    }
+    fs.writeFileSync(tmp, JSON.stringify(rec, null, 2) + "\n");
+    // stdout is the shell'"'"'s only view of what was decided: "<streak> <target> <since>"
+    process.stdout.write(failStreak >= Number(stuckStreakS) && attempt && !ok ? `STUCK ${failStreak} ${streakTarget} ${stuckSince}` : "");
+  ' "$LAST_JSON" "$tmp" "$1" "$2" "$3" "$4" "$5" "$STUCK_STREAK" "$at_latest" 2>/dev/null)" || streak=""
+  if [ -s "$tmp" ]; then
+    mv -f "$tmp" "$LAST_JSON"
+  else
+    # The node writer produced nothing. Before this branch existed the tmp was
+    # simply removed and last.json was LEFT AT ITS PREVIOUS VALUE — so a write
+    # failure did not lose a record, it published a STALE one, and the 24 h
+    # failed-target hold (which reads `to` and `reason` out of this file) then
+    # made its decision from a previous run's outcome while believing it was
+    # this run's. A missing record is fail-open by design here; a wrong one is
+    # not. So write the event itself with printf, which needs no interpreter,
+    # and say loudly that the count did not survive: the streak is the one
+    # field that cannot be reconstructed without reading the old file, and a
+    # silently reset counter is the failure this whole block exists to prevent.
+    log "WARN: write_last could not run node — recording the bare outcome without the failStreak. The count restarts from this run; see state/autoupdate/last.json."
+    printf '{\n  "from": "%s",\n  "to": "%s",\n  "at": "%s",\n  "ok": %s,\n  "healthy": %s,\n  "reason": "%s"\n}\n' \
+      "$1" "$2" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$3" "$4" "$(printf '%s' "$5" | sed 's/[\\"]/\\&/g')" > "$LAST_JSON" 2>/dev/null || true
+  fi
   rm -f "$tmp" 2>/dev/null
+  if [ -n "$streak" ]; then
+    set -- $streak
+    log "STUCK: $2 consecutive failed attempts to reach $3 (since $4). This seat will not arrive on its own — the org now carries machine.upgrade.failStreak=$2 and an \`upgrade_stuck\` alert on every beat. maestro doctor; then rm state/autoupdate/last.json to retry immediately."
+  fi
   return 0
 }
 last_reason(){ # the reason field of last.json, or nothing
   node -e 'try { process.stdout.write(String(JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).reason || "")); } catch {}' "$LAST_JSON" 2>/dev/null
 }
+last_streak(){ # the failStreak of last.json as a positive integer, or nothing
+  node -e 'try { const n = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).failStreak; if (Number.isInteger(n) && n > 0) process.stdout.write(String(n)); } catch {}' "$LAST_JSON" 2>/dev/null
+}
 # The version the RUNNING daemon started on. scripts/daemon/health.mjs resolves
 # sdk_version once at load and writes it to state/dashboards/daemon-health.yaml
 # with its pid, precisely so a reader can tell the installed package from the
@@ -595,13 +710,13 @@ if [ "$CUR" = "$LATEST" ] || [ "$(printf '%s\n%s\n' "$CUR" "$LATEST" | sort -V |
       # the notice tells the session to restart itself onto the new code.
       log "OK: daemon now on $CUR (was $STALE_FROM) — the manual upgrade is complete"
       write_upgrade_notice "$STALE_FROM" "$CUR"
-      write_last "$STALE_FROM" "$CUR" true true ""
+      write_last "$STALE_FROM" "$CUR" true true "" true
     elif [ -n "$STALE_FROM" ]; then
       # Same version, newer files: the daemon is reconciled; the session is
       # not told to restart (a touched or restored file must not cost it its
       # context — the version did not change).
       log "OK: daemon restarted onto the installed $CUR code; no session notice (same version)"
-      write_last "$CUR" "$CUR" true true ""
+      write_last "$CUR" "$CUR" true true "" true
     elif [ -n "$AHEAD" ]; then
       # The DAEMON is well; the FLEET is not. Recorded as ok/healthy — because
       # it is — with the finding in `reason`, so the org learns that this seat
@@ -609,14 +724,32 @@ if [ "$CUR" = "$LATEST" ] || [ "$(printf '%s\n%s\n' "$CUR" "$LATEST" | sort -V |
       # per episode: unlike an unhealthy daemon this does not clear itself, and
       # a fact that ages out of one log file is how six days went by.
       log "OK: healthy on $CUR, but AHEAD of the registry ($LATEST) — recorded for the org as ahead-of-registry"
-      write_last "$CUR" "$CUR" true true "ahead-of-registry: npm latest is $LATEST"
+      write_last "$CUR" "$CUR" true true "ahead-of-registry: npm latest is $LATEST" true
     else
-      case "$PREV_REASON" in unhealthy-current*)
+      case "$PREV_REASON" in
+      unhealthy-current*)
         log "recovered: last.json no longer reports unhealthy-current"
-        write_last "$CUR" "$CUR" true true "" ;;
+        write_last "$CUR" "$CUR" true true "" true ;;
       ahead-of-registry*)
         log "recovered: $CUR is on the registry now (latest $LATEST) — last.json no longer reports ahead-of-registry"
-        write_last "$CUR" "$CUR" true true "" ;;
+        write_last "$CUR" "$CUR" true true "" true ;;
+      *)
+        # A healthy seat that is simply up to date writes NOTHING — there is
+        # nothing to report and an empty last.json is the honest state.
+        #
+        # The one exception is a standing failStreak, and it is the reason this
+        # branch exists at all. A streak only ever reset on ARRIVAL, i.e. on a
+        # successful hop. If a bad release is YANKED and @latest rolls back to
+        # the version this seat already runs, the seat stops attempting
+        # anything: every hour it takes this quiet path, writes nothing, and the
+        # count stands for ever — `upgrade_stuck` firing critical on a seat that
+        # is, in fact, exactly where the registry wants it. Being AT @latest is
+        # an arrival however you got there, so record one and say so.
+        STREAK="$(last_streak)"
+        if [ -n "$STREAK" ]; then
+          log "streak cleared: $CUR is @latest and this seat is healthy on it, but last.json still carried failStreak=$STREAK — @latest has come back to this version (a yank or a withdrawn release). Recording the arrival so the upgrade_stuck alert stops."
+          write_last "$CUR" "$CUR" true true "" true
+        fi ;;
       esac
     fi
   else
@@ -625,7 +758,7 @@ if [ "$CUR" = "$LATEST" ] || [ "$(printf '%s\n%s\n' "$CUR" "$LATEST" | sort -V |
     # and failed_hold_reason both match on it), so the ahead-of-registry fact
     # is appended, never prepended — an unpublished build that is also sick is
     # the worst case and must say both things.
-    write_last "$CUR" "$CUR" false false "unhealthy-current: $HEALTH_REASON${AHEAD:+ (and ahead-of-registry: npm latest is $LATEST)}"
+    write_last "$CUR" "$CUR" false false "unhealthy-current: $HEALTH_REASON${AHEAD:+ (and ahead-of-registry: npm latest is $LATEST)}" true
     case "$PREV_REASON" in
       unhealthy-current*) log "session already notified this episode (last.json was unhealthy-current); notice not rewritten" ;;
       *) write_notice "$CUR" "$CUR" "unhealthy-current: $HEALTH_REASON" ;;