@cohortapp/agent-sdk 2.18.13 → 2.18.14

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"

package/scripts/resume-operations.sh

@@ -3,12 +3,34 @@
 # Usage: ./scripts/resume-operations.sh
 #
 # Reverses emergency-stop.sh:
-#   1. Verifies health check passes.
+#   1. Verifies health check passes — EXCLUDING the stop flag itself.
 #   2. Removes the .emergency-stop flag.
 #   3. Reloads every installed `ai.maestro.<agent>-*` (and legacy
 #      `ai.adaptic.<agent>-*`) launchd job.
 #
 # Agent first-name slug resolved from config/agent.json (SOT).
+#
+# THE DEADLOCK THIS SCRIPT USED TO HAVE. healthcheck.sh counts an active
+# .emergency-stop flag as an ERROR; this script ran it bare and exited on any
+# non-zero. So the one tool whose entire purpose is lifting the stop could
+# never lift it — Eli Rosenberg's seat sat halted from 2026-09-24T08:16Z until
+# the flag was removed by hand. Two independent faults produced that:
+#
+#   (a) The stop flag was its own veto. Fixed by passing
+#       `--ignore-emergency-stop`, which demotes that ONE check to a note.
+#       It is a PUBLIC CLI flag — nothing refuses it to another caller, and
+#       nothing here pretends to (healthcheck.sh's header says so plainly).
+#       What makes it safe is scope, not exclusivity: it demotes exactly one
+#       check, every other check still gates the resume, and step 1b below
+#       VERIFIES that the healthcheck on this disk actually honoured it
+#       rather than assuming the two files are the same vintage.
+#   (b) DEGRADED was treated as failure. healthcheck exits 1 for warnings and
+#       2 for errors; `if ! healthcheck` refused on both, so seven warnings
+#       about optional repos and an uninstalled Slack.app were enough to keep
+#       a seat halted. Warnings are "operational with limitations" by
+#       healthcheck's own contract — they are reported loudly and resumed.
+#       Only CRITICAL (exit 2) still refuses, and the refusal names which
+#       condition blocked it.
 
 set -e
 
@@ -46,19 +68,92 @@ if [ ! -f "$AGENT_DIR/.emergency-stop" ]; then
             launchctl load "$plist" 2>/dev/null && loaded=$((loaded + 1))
         fi
     done
-    [ "$loaded" -gt 0 ] && echo "Loaded $loaded missing launchd job(s)"
+    # `if`, not `[ "$loaded" -gt 0 ] && echo ...` — but NOT for the reason
+    # first written here, which was wrong and would have seeded a wrong rule.
+    # `set -e` does not abort on the 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
+    # and the pre-fix script (which had `exit 0` on the next line) also
+    # exited 0 on a seat with nothing to load. The real hazard is narrower
+    # and has nothing to do with `set -e`: a false && list leaves status 1,
+    # so a script whose LAST command is one exits 1. `exit 0` follows today;
+    # the `if` keeps this line harmless if it ever stops following.
+    if [ "$loaded" -gt 0 ]; then echo "Loaded $loaded missing launchd job(s)"; fi
     exit 0
 fi
 
 echo "[$TIMESTAMP] RESUMING OPERATIONS (agent=$AGENT_FIRST)" | tee -a "$LOG_FILE"
 
-# 1. Run health check first.
-echo "Running health check..."
-if ! "$SCRIPT_DIR/healthcheck.sh"; then
-    echo "ERROR: Health check failed. Fix issues before resuming."
+# 1. Run health check first — with the stop flag exempted, since lifting it is
+#    this script's entire job. Every OTHER check still gates the resume.
+echo "Running health check (emergency-stop flag exempted)..."
+set +e
+HEALTH_OUTPUT=$("$SCRIPT_DIR/healthcheck.sh" --ignore-emergency-stop 2>&1)
+HEALTH_STATUS=$?
+set -e
+echo "$HEALTH_OUTPUT"
+
+# 1b. Prove the exemption was HONOURED before trusting the verdict.
+#
+#     Fault (a)'s fix is version-coupled: it only works if the healthcheck.sh
+#     next to this script understands --ignore-emergency-stop. A seat that
+#     pins framework files (.maestroignore) can carry the new resume script
+#     beside a pre-fix healthcheck, which has no argument parsing at all — it
+#     swallows the flag, still counts the stop as an error, and prints no
+#     `Blocking:` line. MEASURED on that exact pairing: the deadlock is back,
+#     and the refusal reads "(healthcheck named no condition; see output
+#     above)" — worse than the original, because it names nothing to fix.
+#     The seats most likely to be halted are the ones most likely to be
+#     pinned, so this has to be detected and named rather than inferred.
+#
+#     We are past the `[ -f .emergency-stop ]` guard, so a healthcheck that
+#     honoured the flag MUST have printed the NOTE line. Its absence means
+#     the exemption did not take: stale, missing, or not executable.
+if ! printf '%s\n' "$HEALTH_OUTPUT" | grep -q '^\[NOTE\] Emergency stop flag' ||
+    printf '%s\n' "$HEALTH_OUTPUT" | grep -q '^Blocking:.*emergency-stop-flag'; then
+    echo ""
+    echo "REFUSING TO RESUME — scripts/healthcheck.sh is stale."
+    echo "  --ignore-emergency-stop was ignored (healthcheck exit $HEALTH_STATUS): it did"
+    echo "  not report '[NOTE] Emergency stop flag ... not counted', so its verdict still"
+    echo "  counts the very flag this script exists to lift. Resuming on that verdict"
+    echo "  would be resuming on a health check nobody read."
+    echo "  Fix: run 'maestro upgrade' on this seat, then confirm .maestroignore is not"
+    echo "  pinning scripts/healthcheck.sh, and that the file exists and is executable."
+    echo "  The .emergency-stop flag has been LEFT IN PLACE."
+    echo "[$TIMESTAMP] Resume REFUSED — healthcheck.sh stale (exemption ignored, status $HEALTH_STATUS)" >> "$LOG_FILE"
     exit 1
 fi
 
+if [ "$HEALTH_STATUS" -ge 2 ]; then
+    # Name the blocking condition. The operator should never have to re-run
+    # the health check with a filter to learn which of "1 errors" stopped them.
+    BLOCKING=$(printf '%s\n' "$HEALTH_OUTPUT" | sed -n 's/^Blocking://p' | tr -s ' ' | sed 's/^ //')
+    [ -n "$BLOCKING" ] || BLOCKING="(healthcheck named no condition; see output above)"
+    echo ""
+    echo "REFUSING TO RESUME — health check is CRITICAL."
+    echo "  Blocking condition(s): $BLOCKING"
+    # Re-list the failing lines under the refusal, RE-PREFIXED. The whole
+    # health output is echoed above, so the previous `grep '^\[FAIL\]'` here
+    # emitted bytes indistinguishable from it — deleting the line left the
+    # test that claimed to pin it green. The `  FAIL: ` prefix is produced
+    # only here, which is what makes that assertion load-bearing.
+    printf '%s\n' "$HEALTH_OUTPUT" | sed -n 's/^\[FAIL\] /  FAIL: /p'
+    echo "  The .emergency-stop flag has been LEFT IN PLACE."
+    echo "  Fix the condition(s) above, then re-run: $0"
+    {
+        echo "[$TIMESTAMP] Resume REFUSED — blocking: $BLOCKING"
+    } >> "$LOG_FILE"
+    exit 1
+fi
+
+if [ "$HEALTH_STATUS" -eq 1 ]; then
+    DEGRADED=$(printf '%s\n' "$HEALTH_OUTPUT" | sed -n 's/^Warnings://p' | tr -s ' ' | sed 's/^ //')
+    echo ""
+    echo "NOTE: health check is DEGRADED — resuming anyway (warnings are not faults)."
+    echo "  Warning condition(s): $DEGRADED"
+    echo "[$TIMESTAMP] Resume proceeding DEGRADED — warnings: $DEGRADED" >> "$LOG_FILE"
+fi
+
 # 2. Remove stop flag.
 rm "$AGENT_DIR/.emergency-stop"
 echo "[$TIMESTAMP] Stop flag removed" >> "$LOG_FILE"