@zerwiz/ymir 0.1.4 → 0.1.7

package/.agents/backend/fm-guard.sh

@@ -0,0 +1,242 @@
+#!/usr/bin/env bash
+# Watcher liveness and worktree-tangle guard, called by supervision scripts, by
+# fm-wake-drain.sh after it empties queued wakes, and by fm-session-start.sh in
+# read-only advisory mode whenever session-lock ownership was not verified.
+# First, always warn if the firstmate primary checkout (FM_ROOT) is on a named
+# non-default branch, because that means firstmate-on-itself work landed in the
+# primary instead of an isolated worktree.
+# Then, if a task is in flight (a state/<id>.meta exists) or X-mode relay
+# polling is active (state/x-watch.check.sh exists) and supervision is not
+# healthy, prints a loud, clearly delimited banner so the agent cannot skim past
+# it in the tool output of whatever it was doing - the one channel every harness
+# has. Supervision health is MODEL-AWARE (fm_watcher_supervision_verdict in
+# bin/fm-wake-lib.sh): under the Claude Stop auto-arm model the watcher runs only
+# between turns, so mid-turn a fresh beacon with no live watcher is healthy and
+# only a stale beacon (beyond FM_GUARD_GRACE) is a genuine lapse; under the Pi
+# extension model the extension tears the watcher down and respawns it on every
+# actionable wake, so a fresh beacon with a genuinely unheld lock is healthy
+# while that live Pi session provably owns continuity; any held but unhealthy
+# lock is down; under every
+# persistent-watcher harness a live identity-matched watcher with a fresh beacon
+# is required. The banner names the true failing condition (a missing live
+# watcher process vs a genuinely stale beacon). The full banner is emitted once
+# per distinct down-episode in this FM_HOME (keyed to the failing condition, not
+# the beacon mtime, which a healthy between-turns watcher advances every poll);
+# later guarded commands in the same episode print a one-line reminder instead.
+# Episode state lives only under state/.guard-watcher-stale-banner (volatile,
+# bounded). Independent alarms (queued wakes, worktree tangle) are never
+# suppressed by that dedup. Normal wake handling (watcher briefly down between a
+# wake and the next supervision resume) stays inside the grace window and stays
+# silent. Always exits 0: the guard warns, it never blocks.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}"
+STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
+CONFIG="${FM_CONFIG_OVERRIDE:-$FM_HOME/config}"
+WATCH="$SCRIPT_DIR/fm-watch.sh"
+GRACE=${FM_GUARD_GRACE:-300}
+queue_pending=false
+READ_ONLY=${FM_GUARD_READ_ONLY:-0}
+case "$READ_ONLY" in 1|true|TRUE|yes|YES) READ_ONLY=1 ;; *) READ_ONLY=0 ;; esac
+CONTINUE_LINE=${FM_GUARD_CONTINUE_LINE:-This is a supervision warning only; the guarded operation WILL still run.}
+
+# Volatile, home-scoped episode marker: one line = the current stale-episode key.
+# Cleared when the home leaves the unhealthy state so a later episode re-arms.
+STALE_BANNER_MARKER="$STATE/.guard-watcher-stale-banner"
+
+# shellcheck source=bin/fm-wake-lib.sh
+. "$SCRIPT_DIR/fm-wake-lib.sh"
+# shellcheck source=bin/fm-tangle-lib.sh
+. "$SCRIPT_DIR/fm-tangle-lib.sh"
+# shellcheck source=bin/fm-supervision-lib.sh
+. "$SCRIPT_DIR/fm-supervision-lib.sh"
+
+# Deterministic episode key from the qualitative down-state (the failing
+# condition), NOT the beacon mtime: under the auto-arm model a healthy
+# between-turns watcher advances that mtime every poll, which made the "same
+# episode" key change every turn and re-print the full banner. Keying on the
+# failing condition keeps one continuous down-episode stable, while positive
+# recovery clears the marker (below) and re-arms the next episode.
+fm_guard_stale_episode_key() {
+  printf '%s\n' "$1"
+}
+
+# Claim the full banner for this episode. Exit 0 = print full banner (this call
+# owns the first announcement). Exit 1 = same episode already announced (print
+# reminder). The shared wake lock helper owns the race-safety mechanics; the
+# re-check under the lock makes concurrent claims idempotent.
+fm_guard_claim_stale_banner() {
+  local state=$1 key=$2
+  local marker="$state/.guard-watcher-stale-banner"
+  local lock="$state/.guard-watcher-stale-banner.lock"
+  local seen i
+
+  seen=$(cat "$marker" 2>/dev/null || true)
+  # Strip a single trailing newline so key comparison is line-content based.
+  seen=${seen%$'\n'}
+  if [ "$seen" = "$key" ]; then
+    return 1
+  fi
+
+  i=0
+  while [ "$i" -lt 50 ]; do
+    if fm_lock_try_acquire "$lock"; then
+      seen=$(cat "$marker" 2>/dev/null || true)
+      seen=${seen%$'\n'}
+      if [ "$seen" = "$key" ]; then
+        fm_lock_release "$lock" 2>/dev/null || true
+        return 1
+      fi
+      # Bounded write: one line, no growth across episodes (overwrite).
+      printf '%s\n' "$key" > "$marker" || true
+      fm_lock_release "$lock" 2>/dev/null || true
+      return 0
+    fi
+    seen=$(cat "$marker" 2>/dev/null || true)
+    seen=${seen%$'\n'}
+    if [ "$seen" = "$key" ]; then
+      return 1
+    fi
+    # Brief yield; 0.02s is fine on macOS/Linux sleep, fall back to 1s.
+    sleep 0.02 2>/dev/null || sleep 1
+    i=$((i + 1))
+  done
+  # Contended past the spin budget: stay loud rather than dropping the alarm.
+  return 0
+}
+
+fm_guard_stale_banner_seen() {
+  local state=$1 key=$2
+  local marker="$state/.guard-watcher-stale-banner"
+  local seen
+
+  seen=$(cat "$marker" 2>/dev/null || true)
+  seen=${seen%$'\n'}
+  [ "$seen" = "$key" ]
+}
+
+fm_guard_clear_stale_banner() {
+  rm -f "$STALE_BANNER_MARKER" 2>/dev/null || true
+}
+
+# Worktree-tangle alarm, checked FIRST and independent of in-flight tasks: the
+# firstmate PRIMARY checkout (FM_ROOT) must stay on its default branch. If a
+# crewmate's branch/commits landed here instead of in its own isolated worktree,
+# the primary is stranded on a feature branch - surface it loudly on the very next
+# fleet action, the same way the watcher-down banner does. Scoped to the primary
+# only: detached HEAD (linked worktrees, secondmate homes) never trips this.
+tangle_branch=$(fm_primary_tangle_branch "$FM_ROOT" || true)
+if [ -n "$tangle_branch" ]; then
+  tangle_default=$(fm_default_branch "$FM_ROOT" 2>/dev/null || echo main)
+  trule='━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'
+  {
+    printf '●%s\n' "$trule"
+    printf '●  WORKTREE TANGLE - PRIMARY CHECKOUT IS ON A FEATURE BRANCH\n'
+    printf "●  %s is on '%s', not its default branch '%s'.\n" "$FM_ROOT" "$tangle_branch" "$tangle_default"
+    printf '●  A crewmate likely branched/committed in the primary instead of its own worktree.\n'
+    printf "●  The work is SAFE on the '%s' ref.\n" "$tangle_branch"
+    if [ "$READ_ONLY" -eq 1 ]; then
+      printf '●  This read-only session must leave restore work to a session with verified fleet-lock ownership.\n'
+    else
+      printf "●  Restore the primary to '%s':\n" "$tangle_default"
+      printf '●      git -C %s checkout %s\n' "$FM_ROOT" "$tangle_default"
+      printf "●  then re-validate '%s' in a proper isolated worktree.\n" "$tangle_branch"
+    fi
+    printf '●%s\n' "$trule"
+  } >&2
+fi
+
+# Compute supervision need and watcher-beacon freshness via the shared
+# grace-based predicate (bin/fm-supervision-lib.sh). Act when work, an event
+# source, or an X-mode relay poll needs supervision.
+fm_supervision_status "$STATE" "$GRACE"
+in_flight=$FM_SUP_IN_FLIGHT
+sources=$FM_SUP_SOURCES
+needed=$FM_SUP_NEEDED
+beacon_desc=$FM_SUP_BEACON_DESC
+fm_watcher_supervision_verdict "$STATE" "$WATCH" "$GRACE" "$FM_HOME" "$FM_ROOT"
+watcher_healthy=$FM_WATCHER_VERDICT_OK
+watcher_down_reason=$FM_WATCHER_VERDICT_REASON
+if [ "$needed" = false ]; then
+  # Leave the unhealthy state (nothing riding on the watcher): clear so a later
+  # work or X-mode need + stale combination is a fresh episode even if the
+  # beacon is still absent with the same key string.
+  [ "$READ_ONLY" -eq 1 ] || fm_guard_clear_stale_banner
+  exit 0
+fi
+
+[ -s "$FM_WAKE_QUEUE" ] && queue_pending=true
+
+# No fresh watcher with tasks in flight is the dangerous state: emit a prominent,
+# bordered banner FIRST so it reads as an alarm, not a buried stderr line. Later
+# calls in the same episode get a one-line reminder only.
+if [ "$watcher_healthy" = false ]; then
+  episode_key=$(fm_guard_stale_episode_key "$watcher_down_reason")
+  episode_key=${episode_key%$'\n'}
+  print_full_banner=0
+  if [ "$READ_ONLY" -eq 1 ]; then
+    fm_guard_stale_banner_seen "$STATE" "$episode_key" || print_full_banner=1
+  elif fm_guard_claim_stale_banner "$STATE" "$episode_key"; then
+    print_full_banner=1
+  fi
+  if [ "$print_full_banner" -eq 1 ]; then
+    afk=0
+    [ -e "$STATE/.afk" ] && afk=1
+    queue_arg=0
+    "$queue_pending" && queue_arg=1
+    x_mode=0
+    [ -f "$CONFIG/x-mode.env" ] && x_mode=1
+    fix=$("$SCRIPT_DIR/fm-supervision-instructions.sh" \
+      --read-only "$READ_ONLY" \
+      --afk "$afk" \
+      --x-mode "$x_mode" \
+      --queue-pending "$queue_arg" \
+      --repair-line 2>/dev/null || printf '%s\n' 'Repair missing watcher supervision according to the session-start operating block.')
+    rule='━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'
+    {
+      printf '●%s\n' "$rule"
+      printf '●  WATCHER DOWN - SUPERVISION IS OFF\n'
+      if [ "$watcher_down_reason" = no-watcher ]; then
+        watcher_cause=$(printf 'no live watcher process holds this home lock (last beat: %s)' "$beacon_desc")
+      else
+        watcher_cause=$(printf 'no watcher has a fresh beacon (last beat: %s, grace %ss)' "$beacon_desc" "$GRACE")
+      fi
+      if [ "$in_flight" -gt 0 ]; then
+        printf '●  %s task(s) in flight, but %s.\n' "$in_flight" "$watcher_cause"
+      elif [ "$sources" -gt 0 ]; then
+        printf '●  %s process-event source(s) registered, but %s.\n' "$sources" "$watcher_cause"
+      else
+        printf '●  X-mode relay polling needs supervision, but %s.\n' "$watcher_cause"
+      fi
+      if [ "$READ_ONLY" -eq 1 ]; then
+        printf '●  This read-only session should report the lapse, not repair it.\n'
+      else
+        printf '●  Trust the emitted supervision protocol for this harness; do not use shell & for watcher repair.\n'
+      fi
+      printf '●  %s\n' "$CONTINUE_LINE"
+      printf '●  %s\n' "$fix"
+      printf '●%s\n' "$rule"
+    } >&2
+  else
+    printf 'WARNING: watcher still down (same stale episode; last beat: %s, grace %ss) - full banner already printed this episode.\n' \
+      "$beacon_desc" "$GRACE" >&2
+  fi
+else
+  # Healthy again while work is still in flight: end the episode so a later
+  # restale re-prints the full banner.
+  [ "$READ_ONLY" -eq 1 ] || fm_guard_clear_stale_banner
+fi
+
+# Queued wakes are an independent hazard; warn whenever they are pending, even if
+# a watcher is alive. Kept after the banner so the no-watcher alarm reads first.
+# Dedup of the watcher-down banner never suppresses this warning.
+if "$queue_pending"; then
+  if [ "$READ_ONLY" -eq 1 ]; then
+    echo "WARNING: queued wakes pending - left untouched because this session lacks verified fleet-lock ownership." >&2
+  else
+    echo "WARNING: queued wakes pending - drain them with bin/fm-wake-drain.sh before anything else." >&2
+  fi
+fi
+exit 0

package/.agents/backend/fm-harness.sh

@@ -0,0 +1,195 @@
+#!/usr/bin/env bash
+# Detect the agent harness this process tree runs on.
+# Usage: fm-harness.sh                  print own harness: claude|codex|opencode|pi|pi-signed|grok|kimi|cursor|muse|unknown
+#        fm-harness.sh crew             print the effective CREWMATE harness
+#                                        (config/crew-harness; "default" resolves to own)
+#        fm-harness.sh secondmate       print the harness the PRIMARY uses to launch
+#                                        SECONDMATE agents: config/secondmate-harness ->
+#                                        config/crew-harness -> own. "default" or absent
+#                                        defers to the crew resolution, so an unset
+#                                        secondmate-harness behaves exactly as the crew
+#                                        harness did before this knob existed.
+#        fm-harness.sh secondmate-model    print the optional MODEL token from
+#                                        config/secondmate-harness, or empty when absent.
+#        fm-harness.sh secondmate-effort   print the optional EFFORT token from
+#                                        config/secondmate-harness, or empty when absent.
+# config/secondmate-harness format: a single line "<harness> [<model>] [<effort>]",
+# whitespace-separated. A bare "<harness>" (today's format) behaves exactly as before:
+# harness only, no model/effort. Only the first non-empty, non-comment line is parsed.
+# Model/effort come ONLY from this file - config/crew-harness stays a bare adapter
+# name and is never parsed for a model.
+# Detection layers: verified environment markers first, then process ancestry.
+# Record each newly verified env marker here.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}"
+CONFIG="${FM_CONFIG_OVERRIDE:-$FM_HOME/config}"
+
+# shellcheck source=bin/fm-cursor-lib.sh
+. "$SCRIPT_DIR/fm-cursor-lib.sh"
+
+detect_own() {
+  # Layer 1: environment markers for verified harnesses.
+  # Keep marker detection before ancestry detection as an explicit precedence rule.
+  # Claude, Pi, Grok, and Cursor set verified markers of their own; codex,
+  # opencode, Kimi, and Muse are markerless, so a foreign marker retained in a terminal
+  # multiplexer's stored environment can silently misidentify one of them before
+  # ancestry is consulted. This is a precedence hazard, not evidence that
+  # CLAUDECODE inheritance into a kimi child was observed; it was not observed.
+  # Cursor is checked BEFORE claude, deliberately. cursor-agent does NOT clear
+  # an inherited CLAUDECODE, so a cursor worker launched from a claude primary
+  # carries BOTH markers and whichever is tested first wins. Cursor's own
+  # markers are unambiguous when present, so ordering them first is what makes
+  # the verdict correct; bin/fm-spawn.sh additionally clears the foreign markers
+  # at the launch boundary. Both are kept: the launch sanitization only covers
+  # sessions fm-spawn started, while this ordering also covers a cursor session
+  # a human started by hand. Verified live on cursor-agent 2026.08.11-e8db854:
+  # CURSOR_INVOKED_AS=cursor-agent is set on the agent process itself, and
+  # CURSOR_AGENT=1 is set for the child/tool processes this script runs as.
+  [ "${CURSOR_AGENT:-}" = "1" ] && { echo cursor; return; }
+  [ "${CURSOR_INVOKED_AS:-}" = "cursor-agent" ] && { echo cursor; return; }
+  [ "${CLAUDECODE:-}" = "1" ] && { echo claude; return; }
+  if [ "${PI_CODING_AGENT:-}" = "true" ]; then
+    if [ "${FM_PI_HARNESS:-}" = pi-signed ]; then echo pi-signed; else echo pi; fi
+    return
+  fi
+  # grok set GROK_AGENT=1 for its child/tool processes (verified, grok 0.2.73).
+  # It does NOT set CLAUDECODE despite being Claude-Code-compatible, so the marker
+  # is unambiguous WHEN PRESENT - but it is not guaranteed present. A grok 1.0.0
+  # hook process carries GROK_HOOK_EVENT, GROK_HOOK_NAME, GROK_SESSION_ID, and
+  # GROK_WORKSPACE_ROOT with no GROK_AGENT at all (verified from the live process
+  # environment of a wedged grok 1.0.0 Stop hook, 2026-08-07). Treat this marker as
+  # a fast path only; the ancestry walk below is what actually guarantees grok is
+  # identified, and any rule that must be RELIABLE under grok has to test the hook
+  # markers too (see .claude/settings.json Stop entries, docs/turnend-guard.md).
+  [ "${GROK_AGENT:-}" = "1" ] && { echo grok; return; }
+  # muse (Muse Code) publishes no harness-identity marker of its own. The only
+  # MUSE_* variable it is documented to hand a child is MUSE_CURRENT_SESSION_LOG,
+  # a per-session log PATH rather than an identity, and its export to tool
+  # subprocesses is unverified (verified: muse 0.1.0-R708.1), so muse is detected
+  # by ancestry alone below. Do NOT promote MUSE_CURRENT_SESSION_LOG to a marker
+  # without verifying it reaches children AND that it cannot survive in a
+  # multiplexer's stored environment, which is the precedence hazard above.
+  # Layer 2: walk the parent chain and match the command name.
+  local pid=$$ comm args argv0
+  for _ in 1 2 3 4 5 6 7 8; do
+    comm=$(ps -o comm= -p "$pid" 2>/dev/null) || break
+    argv0=$(fm_cursor_argv0_for_pid "$pid" "$comm" 2>/dev/null || true)
+    if fm_cursor_process_matches "$comm" '' "$argv0"; then
+      echo cursor
+      return
+    fi
+    case "$(basename -- "$comm")" in
+      *claude*) echo claude; return ;;
+      *codex*) echo codex; return ;;
+      *opencode*) echo opencode; return ;;
+      *grok*) echo grok; return ;;
+      kimi) echo kimi; return ;;
+      # muse's installed launcher ~/.local/bin/muse execs ~/.local/bin/muse-bin-<version>
+      # (verified in the published launcher, muse 0.1.0-R708.1), so the live process
+      # name carries the version and CHANGES on every auto-update. Match the stable
+      # prefix rather than any exact name. Deliberately anchored, never *muse*, so
+      # unrelated commands (musescore, amuse) cannot be misread as this harness.
+      muse|muse-bin-*) echo muse; return ;;
+      pi-signed) echo pi; return ;;
+      pi) echo pi; return ;;
+      node*|python*)
+        # Bare interpreter: match the harness name in its script path.
+        args=$(ps -o args= -p "$pid" 2>/dev/null)
+        case "$args" in
+          *claude*) echo claude; return ;;
+          *codex*) echo codex; return ;;
+          *opencode*) echo opencode; return ;;
+          *grok*) echo grok; return ;;
+          *" pi "*|*/pi) echo pi; return ;;
+        esac ;;
+    esac
+    pid=$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d ' ')
+    if [ -z "$pid" ] || [ "$pid" -le 1 ]; then
+      break
+    fi
+  done
+  echo unknown
+}
+
+# Resolve the effective crewmate harness: config/crew-harness (a bare adapter
+# name) wins; absent or "default" mirrors firstmate's own harness.
+resolve_crew() {
+  local crew=
+  [ -f "$CONFIG/crew-harness" ] && crew=$(tr -d '[:space:]' < "$CONFIG/crew-harness" || true)
+  if [ -z "$crew" ] || [ "$crew" = "default" ]; then detect_own; else echo "$crew"; fi
+}
+
+# Print the first non-empty, non-comment line of config/secondmate-harness
+# (leading/trailing whitespace trimmed), or nothing when the file is absent or
+# holds only blank/comment lines.
+secondmate_line() {
+  local line
+  [ -f "$CONFIG/secondmate-harness" ] || return 0
+  while IFS= read -r line || [ -n "$line" ]; do
+    line="${line#"${line%%[![:space:]]*}"}"
+    line="${line%"${line##*[![:space:]]}"}"
+    [ -n "$line" ] || continue
+    case "$line" in
+      '#'*) continue ;;
+    esac
+    printf '%s\n' "$line"
+    return 0
+  done < "$CONFIG/secondmate-harness"
+}
+
+# Print the 1-based whitespace-separated token (1=harness, 2=model, 3=effort) of
+# the resolved secondmate_line, or nothing if the line or that field is absent.
+secondmate_field() {
+  local idx=$1 line
+  line=$(secondmate_line)
+  [ -n "$line" ] || return 0
+  # shellcheck disable=SC2086  # deliberate word-splitting: tokenizing the line into fields
+  set -- $line
+  case "$idx" in
+    1) printf '%s\n' "${1:-}" ;;
+    2) printf '%s\n' "${2:-}" ;;
+    3) printf '%s\n' "${3:-}" ;;
+  esac
+}
+
+# Resolve the harness the PRIMARY uses to launch SECONDMATE agents: a fallback
+# chain config/secondmate-harness -> config/crew-harness -> own. An absent or
+# "default" secondmate-harness token defers to the crew resolution, so an unset
+# secondmate-harness behaves exactly as before this knob existed (a secondmate
+# launched on the crew harness). config/secondmate-harness is the PRIMARY's own
+# setting and is never inherited downstream - secondmates do not spawn secondmates.
+resolve_secondmate() {
+  local sm
+  sm=$(secondmate_field 1)
+  if [ -z "$sm" ] || [ "$sm" = "default" ]; then resolve_crew; else echo "$sm"; fi
+}
+
+# Print the optional model token (2nd field) from config/secondmate-harness, or
+# empty when the harness token is absent/"default" (harness-only file, same as
+# today) or when no model token is present.
+resolve_secondmate_model() {
+  local sm
+  sm=$(secondmate_field 1)
+  [ -n "$sm" ] && [ "$sm" != "default" ] || return 0
+  secondmate_field 2
+}
+
+# Print the optional effort token (3rd field) from config/secondmate-harness,
+# the same way.
+resolve_secondmate_effort() {
+  local sm
+  sm=$(secondmate_field 1)
+  [ -n "$sm" ] && [ "$sm" != "default" ] || return 0
+  secondmate_field 3
+}
+
+case "${1:-}" in
+  crew) resolve_crew ;;
+  secondmate) resolve_secondmate ;;
+  secondmate-model) resolve_secondmate_model ;;
+  secondmate-effort) resolve_secondmate_effort ;;
+  *) detect_own ;;
+esac

package/.agents/backend/fm-herdr-ci-cleanup.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# fm-herdr-ci-cleanup.sh - bounded cleanup of CI-owned Herdr lab sessions.
+#
+# Snapshot the session list before the real-Herdr suite, then at job end only
+# stop/delete sessions that:
+#   1. match the guarded fm-lab-* name pattern,
+#   2. were not present in the pre-suite snapshot (job-proven ownership),
+#   3. report default:false on a fresh session list.
+#
+# Never touches the default session. Never adopts or force-deletes non-lab
+# names. Missing herdr is a no-op (exit 0) so portable jobs can call this
+# harmlessly; destructive failures for known lab leftovers exit non-zero.
+#
+# Usage:
+#   fm-herdr-ci-cleanup.sh snapshot <path>
+#   fm-herdr-ci-cleanup.sh teardown <snapshot-path>
+set -eu
+
+die() {
+  printf 'fm-herdr-ci-cleanup.sh: %s\n' "$*" >&2
+  exit 1
+}
+
+log() {
+  printf 'fm-herdr-ci-cleanup.sh: %s\n' "$*" >&2
+}
+
+cmd=${1:-}
+path=${2:-}
+[ -n "$cmd" ] && [ -n "$path" ] || die "usage: fm-herdr-ci-cleanup.sh snapshot|teardown <path>"
+
+if ! command -v herdr >/dev/null 2>&1; then
+  log "herdr not on PATH; nothing to $cmd"
+  exit 0
+fi
+command -v jq >/dev/null 2>&1 || die "jq is required"
+
+list_sessions_json() {
+  herdr session list --json 2>/dev/null \
+    || die "could not list Herdr sessions"
+}
+
+is_lab_name() {
+  local name=$1
+  [[ "$name" =~ ^fm-lab-[a-zA-Z0-9][a-zA-Z0-9_-]*$ ]]
+}
+
+case "$cmd" in
+  snapshot)
+    list_sessions_json | jq -c '[.sessions[]? | .name] | unique | sort' >"$path" \
+      || die "failed to write session snapshot to $path"
+    log "wrote session snapshot to $path ($(jq -r 'length' "$path") names)"
+    ;;
+  teardown)
+    [ -f "$path" ] || die "snapshot file not found: $path"
+    before=$(cat "$path")
+    after_json=$(list_sessions_json)
+    # Candidates: lab-named, default:false, not in the pre-suite snapshot.
+    candidates=$(printf '%s' "$after_json" | jq -r --argjson before "$before" '
+      .sessions[]?
+      | select(.default == false)
+      | select(.name | test("^fm-lab-[a-zA-Z0-9][a-zA-Z0-9_-]*$"))
+      | select((.name as $n | $before | index($n) | not))
+      | .name
+    ')
+    failed=0
+    if [ -z "$candidates" ]; then
+      log "no job-owned fm-lab-* sessions to clean"
+      exit 0
+    fi
+    while IFS= read -r name; do
+      [ -n "$name" ] || continue
+      is_lab_name "$name" || {
+        log "refusing non-lab name from candidate set: $name"
+        failed=1
+        continue
+      }
+      # Fresh refuse-default check immediately before each destructive call.
+      flag=$(herdr session list --json 2>/dev/null \
+        | jq -r --arg n "$name" '.sessions[]? | select(.name == $n) | .default' 2>/dev/null || true)
+      if [ "$flag" != "false" ]; then
+        log "refusing cleanup of '$name' (default=${flag:-<not found>})"
+        failed=1
+        continue
+      fi
+      log "stopping job-owned lab session $name"
+      herdr session stop "$name" --json >/dev/null 2>&1 || true
+      sleep 0.3
+      flag=$(herdr session list --json 2>/dev/null \
+        | jq -r --arg n "$name" '.sessions[]? | select(.name == $n) | .default' 2>/dev/null || true)
+      if [ "$flag" != "false" ]; then
+        log "refusing delete of '$name' after stop (default=${flag:-<not found>})"
+        failed=1
+        continue
+      fi
+      if herdr session delete "$name" --json >/dev/null 2>&1; then
+        log "deleted job-owned lab session $name"
+      else
+        # Already gone is success; still present is failure.
+        still=$(herdr session list --json 2>/dev/null \
+          | jq -r --arg n "$name" '.sessions[]? | select(.name == $n) | .name' 2>/dev/null || true)
+        if [ -n "$still" ]; then
+          log "failed to delete lab session $name"
+          failed=1
+        else
+          log "lab session $name already absent after stop"
+        fi
+      fi
+    done <<<"$candidates"
+    [ "$failed" -eq 0 ] || die "one or more job-owned lab sessions could not be cleaned"
+    ;;
+  *)
+    die "unknown command: $cmd (use snapshot or teardown)"
+    ;;
+esac