@cohortapp/agent-sdk 2.18.13 → 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), "..", "..");
@@ -262,13 +263,20 @@ export function gateLine(r) {
 }
 
 /**
- * A note about paths the GATES themselves dirtied. `npm test` appends to a
- * tracked runtime ledger (.claude-flow/policy/state.json), so a second run in a
- * row would refuse on a file the first run wrote. The clean-tree gate is NOT
+ * A note about paths the GATES themselves dirtied: a second run in a row would
+ * otherwise refuse on a file the FIRST run wrote. The clean-tree gate is NOT
  * weakened for this — publishing a tree you cannot describe stays a refusal —
  * the run just says which paths are the gates' own leavings so the operator
  * reverts them instead of hunting them. Pure.
  *
+ * ~~"`npm test` appends to a tracked runtime ledger
+ * (.claude-flow/policy/state.json)"~~ — struck 2026-09-25: that file is the
+ * reason this function exists, and it is no longer tracked (it is a per-machine
+ * receipt chain, so it never should have been; `.gitignore` says why). This
+ * function stays because the SHAPE recurs — the next gate that writes into the
+ * tree will do the same thing — and because naming the paths beats hunting
+ * them. When it returns null for a whole rollout, that is the expected reading.
+ *
  * @param {string[]} before dirty paths before the gates ran
  * @param {string[]} after  dirty paths after
  * @returns {string|null}
@@ -387,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;
@@ -414,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 = {}) {
@@ -439,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);
@@ -473,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,
   };
 }
 
@@ -511,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();
@@ -531,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(
@@ -541,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: ` +
@@ -548,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.
@@ -572,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)) {
@@ -583,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/healthcheck.sh

@@ -1,24 +1,109 @@
 #!/bin/bash
 # Health Check — Verifies all Maestro agent subsystems are operational
-# Usage: ./scripts/healthcheck.sh
-# Exit codes: 0 = healthy, 1 = degraded, 2 = critical
+# Usage: ./scripts/healthcheck.sh [--ignore-emergency-stop] [--offline] [--help]
+# Exit codes: 0 = healthy, 1 = degraded (warnings only), 2 = critical (errors)
+#
+# A refusal NAMES what blocked it. The summary always prints a `Blocking:`
+# line listing the id of every failed check (and a `Warnings:` line for the
+# soft ones), because the operator's next question after "1 errors" is always
+# "which one?" — and on 2026-09-24 answering it cost a re-run with a filter
+# while a seat stayed halted.
+#
+# --ignore-emergency-stop
+#   Demote check 1 (the .emergency-stop flag) from ERROR to NOTE. It is meant
+#   for one caller: resume-operations.sh, whose whole job is to lift that
+#   flag. Counting the flag as a reason not to lift the flag deadlocked the
+#   only tool that can lift it (a seat sat halted from 2026-09-24T08:16Z
+#   until it was cleared by hand).
+#
+#   SCOPE, PLAINLY. This is a PUBLIC CLI flag. Any caller, script or operator
+#   can pass it; nothing refuses it, and nothing here pretends to. An earlier
+#   draft of this header said the exemption "is refused to everyone else" —
+#   it never was. The scoping is convention plus this comment, and a gate that
+#   exists only in a comment is exactly the thing this file was repaired for.
+#
+#   What keeps it honest is scope, not exclusivity:
+#     - It demotes exactly ONE check. Every other check runs at full severity,
+#       so an exempted run still cannot green-light a broken seat.
+#     - It is off by default, so an operator running healthcheck on a halted
+#       seat is still told it is halted — the first thing they need to know.
+#     - It is explicit, greppable, and reviewable at its single call site.
+#     - The demotion is ANNOUNCED in the output ([NOTE] ...). That line is the
+#       receipt resume-operations.sh checks before it trusts the verdict, so a
+#       run where the flag was silently swallowed is caught rather than obeyed.
+#   Requiring a second token (an env var alongside the flag) would add another
+#   thing to forge, not a boundary: anyone who can run this script can set an
+#   env var. The real boundary is permission to execute it at all.
+#
+#   The alternatives are worse on their merits, not on access control:
+#     - Dropping the check outright, or having it always ignore the flag, is
+#       wrong for the same reason as above: a halted seat must say so.
+#     - Re-ordering resume (remove flag, then check) is worse still: it lifts
+#       the stop on a genuinely broken seat and only then discovers it is
+#       broken, which is the failure the stop flag exists to prevent.
+#
+# --offline (or MAESTRO_HEALTHCHECK_SKIP_NETWORK=1)
+#   Record check 6 as SKIPPED instead of reaching the network. Not a weakening:
+#   the check is neither counted healthy nor counted failed, and the summary
+#   says it was skipped.
 
 set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-SOPHIE_AI_DIR="$(dirname "$SCRIPT_DIR")"
+AGENT_DIR="$(dirname "$SCRIPT_DIR")"
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-HEALTHY=0
 WARNINGS=0
 ERRORS=0
+BLOCKING=""   # space-separated ids of failed checks
+SOFT=""       # space-separated ids of warned checks
+
+IGNORE_STOP_FLAG=0
+SKIP_NETWORK=0
+case "${MAESTRO_HEALTHCHECK_SKIP_NETWORK:-0}" in 1 | true | yes) SKIP_NETWORK=1 ;; esac
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --ignore-emergency-stop) IGNORE_STOP_FLAG=1 ;;
+        --offline) SKIP_NETWORK=1 ;;
+        -h | --help)
+            sed -n '2,/^$/p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+            exit 0
+            ;;
+        *)
+            echo "healthcheck: unknown argument: $1" >&2
+            echo "Usage: healthcheck.sh [--ignore-emergency-stop] [--offline]" >&2
+            exit 2
+            ;;
+    esac
+    shift
+done
+
+# fail <id> <message> — record a blocking condition under a stable id.
+fail() {
+    echo "[FAIL] $2"
+    BLOCKING="$BLOCKING $1"
+    ERRORS=$((ERRORS + 1))
+}
+
+# warn <id> <message> — record a soft condition under a stable id.
+warn() {
+    echo "[WARN] $2"
+    SOFT="$SOFT $1"
+    WARNINGS=$((WARNINGS + 1))
+}
 
 echo "Maestro Health Check — $TIMESTAMP"
 echo "======================================="
 
 # Check 1: Emergency stop flag
-if [ -f "$SOPHIE_AI_DIR/.emergency-stop" ]; then
-    echo "[STOP] Emergency stop flag is active"
-    ERRORS=$((ERRORS + 1))
+if [ -f "$AGENT_DIR/.emergency-stop" ]; then
+    if [ "$IGNORE_STOP_FLAG" -eq 1 ]; then
+        echo "[NOTE] Emergency stop flag is active — not counted (--ignore-emergency-stop)"
+    else
+        echo "[STOP] Emergency stop flag is active"
+        BLOCKING="$BLOCKING emergency-stop-flag"
+        ERRORS=$((ERRORS + 1))
+    fi
 else
     echo "[OK]   No emergency stop flag"
 fi
@@ -30,22 +115,20 @@ fi
 # in .env strips the var and falls back to Keychain OAuth).
 if [ -n "${ANTHROPIC_API_KEY:-}" ]; then
     echo "[OK]   Environment variable: ANTHROPIC_API_KEY"
-elif [ -f "$SOPHIE_AI_DIR/.env" ] && grep -qE "^MAESTRO_PREFER_SUBSCRIPTION_AUTH=(1|true|yes)$" "$SOPHIE_AI_DIR/.env"; then
+elif [ -f "$AGENT_DIR/.env" ] && grep -qE "^MAESTRO_PREFER_SUBSCRIPTION_AUTH=(1|true|yes)$" "$AGENT_DIR/.env"; then
     echo "[OK]   Anthropic auth: subscription mode (.env: MAESTRO_PREFER_SUBSCRIPTION_AUTH=1)"
-elif [ -f "$SOPHIE_AI_DIR/.env" ] && grep -qE "^ANTHROPIC_API_KEY=." "$SOPHIE_AI_DIR/.env"; then
+elif [ -f "$AGENT_DIR/.env" ] && grep -qE "^ANTHROPIC_API_KEY=." "$AGENT_DIR/.env"; then
     echo "[OK]   Anthropic auth: ANTHROPIC_API_KEY in .env"
 else
-    echo "[FAIL] Anthropic auth not configured (.env needs either ANTHROPIC_API_KEY or MAESTRO_PREFER_SUBSCRIPTION_AUTH=1)"
-    ERRORS=$((ERRORS + 1))
+    fail "anthropic-auth" "Anthropic auth not configured (.env needs either ANTHROPIC_API_KEY or MAESTRO_PREFER_SUBSCRIPTION_AUTH=1)"
 fi
 
 # Check 3: Key directories exist and are writable
 for dir in logs outputs knowledge/memory config; do
-    if [ -d "$SOPHIE_AI_DIR/$dir" ] && [ -w "$SOPHIE_AI_DIR/$dir" ]; then
+    if [ -d "$AGENT_DIR/$dir" ] && [ -w "$AGENT_DIR/$dir" ]; then
         echo "[OK]   Directory writable: $dir"
     else
-        echo "[FAIL] Directory missing or not writable: $dir"
-        ERRORS=$((ERRORS + 1))
+        fail "dir:$dir" "Directory missing or not writable: $dir"
     fi
 done
 
@@ -54,8 +137,7 @@ for repo in company-web innovation-lab partner-framework company-legal regulator
     if [ -d "$HOME/$repo" ]; then
         echo "[OK]   Source repo accessible: ~/$repo"
     else
-        echo "[WARN] Source repo not found: ~/$repo"
-        WARNINGS=$((WARNINGS + 1))
+        warn "repo:$repo" "Source repo not found: ~/$repo"
     fi
 done
 
@@ -64,45 +146,61 @@ for app in Slack WhatsApp Safari; do
     if [ -d "/Applications/$app.app" ] || [ -d "$HOME/Applications/$app.app" ]; then
         echo "[OK]   Application installed: $app"
     else
-        echo "[WARN] Application not found: $app"
-        WARNINGS=$((WARNINGS + 1))
+        warn "app:$app" "Application not found: $app"
     fi
 done
 
 # Check 6: Network connectivity
-if curl -s --max-time 5 https://api.anthropic.com > /dev/null 2>&1; then
+if [ "$SKIP_NETWORK" -eq 1 ]; then
+    echo "[SKIP] Network: not probed (--offline)"
+elif curl -s --max-time 5 https://api.anthropic.com > /dev/null 2>&1; then
     echo "[OK]   Network: Anthropic API reachable"
 else
-    echo "[FAIL] Network: Cannot reach Anthropic API"
-    ERRORS=$((ERRORS + 1))
+    fail "network" "Network: Cannot reach Anthropic API"
 fi
 
-# Check 7: Disk space
-DISK_FREE=$(df -h "$SOPHIE_AI_DIR" | awk 'NR==2{print $5}' | tr -d '%')
-if [ "$DISK_FREE" -gt 90 ]; then
-    echo "[WARN] Disk usage: ${DISK_FREE}% — consider cleanup"
-    WARNINGS=$((WARNINGS + 1))
-elif [ "$DISK_FREE" -gt 95 ]; then
-    echo "[FAIL] Disk usage: ${DISK_FREE}% — critically low"
-    ERRORS=$((ERRORS + 1))
+# Check 7: Disk space. Ordered most-severe-first: the previous order tested
+# >90 before >95, so the critical branch could never be reached and disk was
+# warn-only in practice. Reaching it is a REAL severity change with a real
+# consequence — resume-operations.sh refuses on any exit 2, so a seat above
+# 95% can no longer be resumed until space is freed. That is deliberate, and
+# it is not the deadlock this trio was repaired for: unlike the stop flag
+# (which only resume could lift), a full disk is named, actionable, and
+# fixable without running this script. Both branches — >95 blocking and >90
+# warning — are pinned in resume-operations.test.mjs, at the healthcheck and
+# at the resume gate, because they are the only severities that changed.
+DISK_FREE=$(df -h "$AGENT_DIR" | awk 'NR==2{print $5}' | tr -d '%')
+if [ "$DISK_FREE" -gt 95 ]; then
+    fail "disk" "Disk usage: ${DISK_FREE}% — critically low"
+elif [ "$DISK_FREE" -gt 90 ]; then
+    warn "disk" "Disk usage: ${DISK_FREE}% — consider cleanup"
 else
     echo "[OK]   Disk usage: ${DISK_FREE}%"
 fi
 
 # Check 8: Config files present
 for config in priorities.yaml environment.yaml contacts.yaml; do
-    if [ -f "$SOPHIE_AI_DIR/config/$config" ]; then
+    if [ -f "$AGENT_DIR/config/$config" ]; then
         echo "[OK]   Config present: $config"
     else
-        echo "[FAIL] Config missing: $config"
-        ERRORS=$((ERRORS + 1))
+        fail "config:$config" "Config missing: $config"
     fi
 done
 
-# Summary
+# Summary. `Blocking:` / `Warnings:` are the machine-readable contract:
+# resume-operations.sh parses `Blocking:` to name the condition it refused on.
 echo ""
 echo "======================================="
 echo "Results: $ERRORS errors, $WARNINGS warnings"
+# `if`, not `[ ... ] && echo` — but NOT for the reason first written here,
+# which was false. `set -e` does NOT abort on a false short-circuit: bash
+# exempts a failing command that is not the last in an && list. MEASURED:
+#   bash -c 'set -e; n=0; [ "$n" -gt 0 ] && echo hi; exit 0'   → exit 0
+# The genuine hazard is only that a false && list leaves status 1, which a
+# script inherits if it is the last command run. The explicit exits below
+# make that moot here; `if` is kept because it says what is meant.
+if [ "$ERRORS" -gt 0 ]; then echo "Blocking:$BLOCKING"; fi
+if [ "$WARNINGS" -gt 0 ]; then echo "Warnings:$SOFT"; fi
 
 if [ "$ERRORS" -gt 0 ]; then
     echo "Status: CRITICAL — fix errors before operating"