@zerwiz/ymir 0.1.3 → 0.1.5

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

@@ -0,0 +1,432 @@
+#!/usr/bin/env bash
+# Turn-end guard for any firstmate PRIMARY session: the main home OR a
+# secondmate's own home. A secondmate runs its own primary firstmate session and
+# is guarded exactly like the main primary; only child crew/scout worktrees are
+# exempt (see the scoping block below and docs/turnend-guard.md).
+#
+# fm-guard.sh (bin/fm-guard.sh) is pull-based: it only warns when some other
+# supervision script happens to run. A primary session that ends a turn without
+# resuming its harness supervision protocol, and then never runs another
+# fleet-touching command itself, can sit blind for hours.
+# This script is push-based: verified harness turn-end hooks invoke it every time
+# the primary is about to end a turn.
+# Claude and codex can block directly by preserving exit status 2 and stderr.
+# OpenCode and pi adapters use the same predicate and force one bounded
+# follow-up because their turn-end events are passive. Grok delegates native
+# blocking when its running Stop payload advertises that capability, with one
+# bounded resume fallback for payloads from pre-native processes. Cursor calls
+# this guard back with --cursor from bin/fm-turnend-guard-cursor.sh and renders
+# exit 2 as one bounded follow-up, because exit 2 is a silent no-op on Cursor's
+# stop step; without that flag a Cursor-shaped payload is the Claude-settings
+# duplicate Cursor also loads, and this guard stands down.
+# See docs/turnend-guard.md for the per-harness mechanics, validation evidence,
+# and fail-open tradeoffs.
+#
+# Ships with TRACKED harness hook files at the repo root, so this file is
+# checked out into every worktree of this repo: the primary checkout, every
+# secondmate home (treehouse-leased or git-cloned), and any crewmate/scout task
+# worktree spawned to work on firstmate itself (the recursive "firstmate
+# improving itself" case). A secondmate home runs its OWN primary firstmate
+# session, so it must be guarded like the main primary; only child crew/scout
+# worktrees are exempt. It must therefore scope itself at runtime to a real
+# primary checkout - the main home or a genuinely marked secondmate home - and
+# stay a silent, fast no-op inside child task worktrees.
+#
+# Loop-guard, codex/Grok (default) mode: never block twice in the same turn.
+# Codex uses stop_hook_active and Grok uses stopHookActive; typed camel-case
+# takes precedence when both spellings are present. A true value means the
+# current stop attempt already follows a block, so this guard always allows it.
+# Passive harness adapters provide their own one-follow-up guard before calling
+# this script.
+# That bounds those harnesses to at most one forced continuation per turn -
+# never a wedged, un-endable session - while still nagging again on a later turn
+# if the problem persists.
+#
+# Loop-guard, --claude mode (Stop-owned auto-arm cooperation): Claude Code
+# marks EVERY stop after ANY stop-hook-driven continuation stop_hook_active=true,
+# including turns started by the asyncRewake auto-arm, so the one-shot allow
+# would re-open the exact blind window this guard exists to close
+# (docs/turnend-guard.md records the 2026-07-21 incident). In --claude mode this
+# guard ignores stop_hook_active and instead cooperates with the Stop-owned
+# auto-arm (bin/fm-claude-stop-autoarm.sh), which fires on the same Stop event:
+#   1. a live identity-matched watcher with a fresh beacon allows immediately;
+#   2. otherwise wait briefly (FM_CLAUDE_AUTOARM_SYNC_WAIT_MS, default 800ms)
+#      for the auto-arm to claim this home (a live OPEN generation claim in the
+#      state/.claude-autoarm-epoch ledger - fm_autoarm_claim_open - or a legacy
+#      build's lock-holding claim under the legacy abandonment proof) or to
+#      record a fresh actionable exit-2 outcome
+#      (state/.claude-autoarm-epoch) for this event epoch - either proof allows
+#      without consuming a continuation, so one event epoch yields exactly one recovery turn;
+#      the first fresh exhausted-failure epoch preserves the bounded progression,
+#      while later fresh failed epochs consume it instead of resetting it;
+#   3. only when neither materializes is the auto-arm genuinely absent: re-block
+#      with the repair banner, bounded to FM_CLAUDE_TURNEND_BLOCK_BUDGET
+#      (default 3) consecutive blocks per session - safely below Claude Code's
+#      hard 8-consecutive-block override - then allow one loud attended
+#      fail-open only for an already verified failure episode.
+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}"
+GRACE=${FM_GUARD_GRACE:-300}
+WATCH="$SCRIPT_DIR/fm-watch.sh"
+CLAUDE_MODE=0
+CURSOR_MODE=0
+SYNC_WAIT_MS=${FM_CLAUDE_AUTOARM_SYNC_WAIT_MS:-800}
+EPOCH_FRESH=${FM_CLAUDE_AUTOARM_EPOCH_FRESH:-15}
+BLOCK_BUDGET=${FM_CLAUDE_TURNEND_BLOCK_BUDGET:-3}
+case "$SYNC_WAIT_MS" in ''|*[!0-9]*) SYNC_WAIT_MS=800 ;; esac
+case "$EPOCH_FRESH" in ''|*[!0-9]*|0) EPOCH_FRESH=15 ;; esac
+case "$BLOCK_BUDGET" in ''|*[!0-9]*|0) BLOCK_BUDGET=3 ;; esac
+
+for arg in "$@"; do
+  case "$arg" in
+    --claude) CLAUDE_MODE=1 ;;
+    --cursor) CURSOR_MODE=1 ;;
+    *) echo "usage: $(basename "$0") [--claude|--cursor]" >&2; exit 2 ;;
+  esac
+done
+
+# shellcheck source=bin/fm-supervision-lib.sh
+. "$SCRIPT_DIR/fm-supervision-lib.sh"
+# shellcheck source=bin/fm-primary-scope-lib.sh
+. "$SCRIPT_DIR/fm-primary-scope-lib.sh"
+# shellcheck source=bin/fm-hook-host-lib.sh
+. "$SCRIPT_DIR/fm-hook-host-lib.sh"
+
+# Read the whole turn-end hook payload once; never block on unreadable/absent
+# stdin.
+PAYLOAD=$(cat 2>/dev/null || true)
+[ -n "$PAYLOAD" ] || exit 0
+
+# jq is the repo's established JSON dependency (bin/fm-x-poll.sh uses the same
+# "missing jq -> silent no-op" degrade). Without it we cannot safely read the
+# loop-guard field, so we must never block - fail open, not noisy.
+command -v jq >/dev/null 2>&1 || exit 0
+
+# A Cursor primary also loads the tracked Claude settings, and Cursor's own
+# registration owns its turn boundary through bin/fm-turnend-guard-cursor.sh,
+# which calls this guard back with --cursor. Without that flag a Cursor-delivered
+# payload is the Claude-compatibility duplicate and must not create a second
+# continuation path (docs/turnend-guard.md "Harness integrations").
+if [ "$CURSOR_MODE" -eq 0 ] && fm_hook_payload_is_foreign_host "$PAYLOAD"; then
+  exit 0
+fi
+
+STOP_HOOK_ACTIVE=$(printf '%s' "$PAYLOAD" | jq -r '
+  if type != "object" then error("payload")
+  elif has("stopHookActive") then
+    if ((.stopHookActive | type) == "boolean") then .stopHookActive else error("stopHookActive") end
+  elif has("stop_hook_active") then
+    if ((.stop_hook_active | type) == "boolean") then .stop_hook_active else error("stop_hook_active") end
+  else false
+  end
+' 2>/dev/null) || exit 0
+if [ "$CLAUDE_MODE" -eq 0 ] && [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  exit 0
+fi
+
+# --- scope precisely to a PRIMARY checkout ----------------------------------
+# A genuinely-marked secondmate home runs its OWN primary firstmate session, so
+# force-INCLUDE it as a guarded primary whether treehouse leased it as a linked
+# worktree (git-dir != git-common-dir) or it is a git-cloned plain checkout. This
+# mirrors the cd-guard's intent that a secondmate's own session is a guarded
+# primary. Only an UNMARKED checkout (or one with an invalid marker) falls
+# through to the linked-worktree exemption: firstmate hands out crewmate/scout
+# task worktrees as genuine linked `git worktree`s (bin/fm-spawn.sh aborts
+# otherwise), whose git-dir lives under the parent repo's .git/worktrees/<name>
+# and differs from the common (shared) git-dir, while a main, non-worktree
+# checkout has the two equal. Child worktrees never carry the gitignored marker,
+# so this exempts them while guarding every real secondmate home.
+fm_primary_scope_matches "$FM_ROOT" "$STATE" || exit 0
+
+# --- the actual predicate ----------------------------------------------------
+# shellcheck source=bin/fm-wake-lib.sh
+. "$SCRIPT_DIR/fm-wake-lib.sh"
+
+BUDGET_FILE="$STATE/.turnend-claude-blocks"
+BUDGET_LOCK="$STATE/.turnend-claude-blocks.lock"
+OWNER_LOCK="$STATE/.claude-autoarm.lock"
+FAILURE_NOTICE="$STATE/.claude-autoarm-failure-notified"
+FAILURE_ALARM="$STATE/.claude-autoarm-failure-alarmed"
+SESSION_ID=$(printf '%s' "$PAYLOAD" | jq -r '.session_id // "unknown"' 2>/dev/null || printf 'unknown')
+budget_reset() {
+  [ "$CLAUDE_MODE" -eq 1 ] || return 0
+  fm_lock_try_acquire "$BUDGET_LOCK" || return 0
+  rm -f "$BUDGET_FILE" 2>/dev/null || true
+  fm_lock_release "$BUDGET_LOCK"
+}
+
+fm_supervision_status "$STATE" "$GRACE"
+if [ "$FM_SUP_NEEDED" = false ]; then
+  [ -e "$FAILURE_NOTICE" ] || budget_reset
+  exit 0
+fi
+if fm_watcher_healthy "$STATE" "$WATCH" "$GRACE" "$FM_HOME"; then
+  [ "$CLAUDE_MODE" -eq 1 ] || exit 0
+  fm_failure_episode_reset "$STATE" && exit 0
+  exit 2
+fi
+
+block_stop() {
+  local afk x_mode reason rule
+  afk=0
+  [ -e "$STATE/.afk" ] && afk=1
+  x_mode=0
+  [ -f "$CONFIG/x-mode.env" ] && x_mode=1
+  reason=$("$SCRIPT_DIR/fm-supervision-instructions.sh" --afk "$afk" --x-mode "$x_mode" --repair-line 2>/dev/null \
+    || printf '%s\n' 'tasks in flight, no live watcher - repair missing watcher supervision according to the session-start operating block before ending the turn')
+  rule='━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'
+  {
+    printf '●%s\n' "$rule"
+    printf '●  TURN WOULD END BLIND - SUPERVISION IS OFF\n'
+    if [ "$FM_SUP_IN_FLIGHT" -gt 0 ]; then
+      printf '●  %s task(s) in flight, but no live watcher holds this home lock (last beat: %s).\n' "$FM_SUP_IN_FLIGHT" "$FM_SUP_BEACON_DESC"
+    elif [ "$FM_SUP_SOURCES" -gt 0 ]; then
+      printf '●  %s process-event source(s) registered, but no live watcher holds this home lock (last beat: %s).\n' "$FM_SUP_SOURCES" "$FM_SUP_BEACON_DESC"
+    else
+      printf '●  X-mode relay polling needs supervision, but no live watcher holds this home lock (last beat: %s).\n' "$FM_SUP_BEACON_DESC"
+    fi
+    if [ "$CLAUDE_MODE" -eq 1 ]; then
+      printf '●  The Stop-owned auto-arm did not claim this home either, so recovery is NOT already under way.\n'
+    fi
+    printf '●  %s\n' "$reason"
+    printf '●%s\n' "$rule"
+  } >&2
+  exit 2
+}
+
+if [ "$CLAUDE_MODE" -eq 0 ]; then
+  block_stop
+fi
+
+# --- --claude cooperative path -----------------------------------------------
+# The Stop-owned auto-arm fires on the same Stop event. Give it a brief bounded
+# window to prove it owns recovery for this event epoch before consuming one of
+# Claude's bounded continuations.
+budget_account_current_epoch() {
+  local current_epoch outcome old_session old_count old_epoch tmp initialized
+  fm_lock_try_acquire "$BUDGET_LOCK" || return 1
+  current_epoch=$(sed -n '1s/^epoch=\([0-9][0-9]*\) .*/\1/p' "$STATE/.claude-autoarm-epoch" 2>/dev/null || true)
+  outcome=$(sed -n '1s/^.*outcome=\([a-z][a-z-]*\) .*$/\1/p' "$STATE/.claude-autoarm-epoch" 2>/dev/null || true)
+  initialized=0
+  COUNT=0
+  if [ -f "$BUDGET_FILE" ]; then
+    old_session=$(sed -n '1s/^session=//p' "$BUDGET_FILE" 2>/dev/null || true)
+    old_count=$(sed -n '2s/^count=//p' "$BUDGET_FILE" 2>/dev/null || true)
+    old_epoch=$(sed -n '3s/^epoch=//p' "$BUDGET_FILE" 2>/dev/null || true)
+    case "$old_count" in
+      ''|*[!0-9]*) old_count=0 ;;
+    esac
+    if [ "$old_session" = "$SESSION_ID" ]; then
+      COUNT=$old_count
+      if [ -n "$current_epoch" ] && [ "$old_epoch" = "$current_epoch" ]; then
+        :
+      else
+        COUNT=$((COUNT + 1))
+      fi
+    fi
+  fi
+  if [ ! -f "$BUDGET_FILE" ] || [ "${old_session:-}" != "$SESSION_ID" ]; then
+    case "$outcome" in
+      failed|failed-suppressed)
+        if [ -e "$FAILURE_NOTICE" ]; then
+          initialized=1
+          COUNT=0
+        else
+          COUNT=1
+        fi
+        ;;
+      *) COUNT=1 ;;
+    esac
+  fi
+  tmp="$BUDGET_FILE.tmp.$$"
+  if ! printf 'session=%s\ncount=%s\nepoch=%s\n' "$SESSION_ID" "$COUNT" "$current_epoch" > "$tmp" 2>/dev/null \
+    || ! mv -f "$tmp" "$BUDGET_FILE" 2>/dev/null; then
+    rm -f "$tmp" 2>/dev/null || true
+    fm_lock_release "$BUDGET_LOCK"
+    return 1
+  fi
+  rm -f "$tmp" 2>/dev/null || true
+  BUDGET_INITIALIZED_FAILURE=$initialized
+  fm_lock_release "$BUDGET_LOCK"
+  return 0
+}
+
+autoarm_owns_recovery() {
+  local pid role outcome age
+  fm_watcher_healthy "$STATE" "$WATCH" "$GRACE" "$FM_HOME" && return 0
+  # A live OPEN generation claim owns recovery: the ledger names a live,
+  # identity-matched owner still arming that is not stuck (fm_autoarm_claim_open
+  # in bin/fm-wake-lib.sh owns that predicate). A finished, dead,
+  # identity-mismatched, or stuck claim deliberately fails it and falls
+  # through, because treating such a claim as ownership is what let a dead
+  # watcher go unnoticed for turn after turn; the outcome cases below still
+  # cover a claim that finished moments ago, so a genuine handoff is not
+  # duplicated, while a stale one now reaches the block.
+  if fm_autoarm_claim_open "$STATE" "$GRACE"; then
+    [ ! -e "$FAILURE_NOTICE" ] || budget_account_current_epoch || true
+    return 0
+  fi
+  # Legacy shim: a pre-generation build's claim holds the owner lock with the
+  # autoarm role for its whole cycle; defer to it under the legacy abandonment
+  # proof so an upgrade mid-session cannot double-arm.
+  pid=$(cat "$OWNER_LOCK/pid" 2>/dev/null || true)
+  role=$(fm_lock_role "$OWNER_LOCK" 2>/dev/null || true)
+  if fm_pid_alive "$pid" && [ "$role" = autoarm ] \
+    && ! fm_autoarm_claim_abandoned "$STATE" "$GRACE"; then
+    [ ! -e "$FAILURE_NOTICE" ] || budget_account_current_epoch || true
+    return 0
+  fi
+  outcome=$(sed -n '1s/^.*outcome=\([a-z][a-z-]*\) .*$/\1/p' "$STATE/.claude-autoarm-epoch" 2>/dev/null || true)
+  case "$outcome" in
+    rewake)
+      age=$(fm_path_age "$STATE/.claude-autoarm-epoch")
+      if [ "$age" -lt "$EPOCH_FRESH" ]; then
+        [ ! -e "$FAILURE_NOTICE" ] || budget_account_current_epoch || true
+        return 0
+      fi
+      ;;
+    failed)
+      age=$(fm_path_age "$STATE/.claude-autoarm-epoch")
+      if [ "$age" -lt "$EPOCH_FRESH" ] && [ -e "$FAILURE_NOTICE" ] \
+        && budget_account_current_epoch; then
+        [ "$BUDGET_INITIALIZED_FAILURE" -eq 1 ] && return 0
+      fi
+      ;;
+    failed-suppressed)
+      age=$(fm_path_age "$STATE/.claude-autoarm-epoch")
+      if [ "$age" -lt "$EPOCH_FRESH" ] && [ -e "$FAILURE_NOTICE" ] \
+        && budget_account_current_epoch; then
+        :
+      fi
+      ;;
+  esac
+  return 1
+}
+
+terminal_fail_open() {
+  local pid role old_session old_count
+  [ "$COUNT" -gt "$BLOCK_BUDGET" ] || return 1
+  failure_episode_verified || return 1
+  [ ! -e "$FAILURE_ALARM" ] || return 1
+  # A live open generation claim is a concurrent recovery decision to step
+  # aside for, exactly like the legacy live-owner case below.
+  fm_autoarm_claim_open "$STATE" "$GRACE" && return 2
+  if ! fm_lock_try_acquire "$OWNER_LOCK"; then
+    pid=$(cat "$OWNER_LOCK/pid" 2>/dev/null || true)
+    role=$(fm_lock_role "$OWNER_LOCK" 2>/dev/null || true)
+    # Same legacy abandonment test as autoarm_owns_recovery: a claim whose
+    # ledger entry is already terminal, or whose recorded pid-identity no
+    # longer matches the live pid, is not a concurrent owner to step aside
+    # for. Stepping aside for one here allows the stop silently, and the
+    # episode's one attended alarm would never fire, so clear the abandoned
+    # claim and let this decision finish instead. Failing to clear it
+    # re-blocks rather than allowing.
+    if fm_pid_alive "$pid" && [ "$role" = autoarm ] \
+      && ! fm_autoarm_claim_abandoned "$STATE" "$GRACE"; then
+      return 2
+    fi
+    fm_autoarm_release_abandoned "$STATE" "$GRACE" || return 1
+    fm_lock_try_acquire "$OWNER_LOCK" || return 1
+  fi
+  if ! fm_lock_set_role "$OWNER_LOCK" terminal-check; then
+    fm_lock_release "$OWNER_LOCK"
+    return 1
+  fi
+  if ! fm_lock_try_acquire "$BUDGET_LOCK"; then
+    fm_lock_release "$OWNER_LOCK"
+    return 1
+  fi
+  old_session=$(sed -n '1s/^session=//p' "$BUDGET_FILE" 2>/dev/null || true)
+  old_count=$(sed -n '2s/^count=//p' "$BUDGET_FILE" 2>/dev/null || true)
+  case "$old_count" in
+    ''|*[!0-9]*) old_count=0 ;;
+  esac
+  role=$(fm_lock_role "$OWNER_LOCK" 2>/dev/null || true)
+  if [ "$role" != terminal-check ] || [ "$old_session" != "$SESSION_ID" ] \
+    || [ "$old_count" -le "$BLOCK_BUDGET" ] || ! failure_episode_verified \
+    || [ -e "$FAILURE_ALARM" ]; then
+    fm_lock_release "$BUDGET_LOCK"
+    fm_lock_release "$OWNER_LOCK"
+    return 1
+  fi
+  if fm_watcher_healthy "$STATE" "$WATCH" "$GRACE" "$FM_HOME"; then
+    if ! fm_failure_episode_reset "$STATE" held; then
+      fm_lock_release "$BUDGET_LOCK"
+      fm_lock_release "$OWNER_LOCK"
+      return 1
+    fi
+    fm_lock_release "$BUDGET_LOCK"
+    fm_lock_release "$OWNER_LOCK"
+    return 2
+  fi
+  # Re-check for a live open generation claim now that both locks are held: a
+  # claimant that published "arming" between the pre-check above and the lock
+  # acquisition is active recovery, and alarming over it would fire the
+  # episode's one attended fail-open while a continuation is under way.
+  if fm_autoarm_claim_open "$STATE" "$GRACE"; then
+    fm_lock_release "$BUDGET_LOCK"
+    fm_lock_release "$OWNER_LOCK"
+    return 2
+  fi
+  if ! (set -C; : > "$FAILURE_ALARM") 2>/dev/null; then
+    fm_lock_release "$BUDGET_LOCK"
+    fm_lock_release "$OWNER_LOCK"
+    return 1
+  fi
+  fm_lock_release "$BUDGET_LOCK"
+  fm_lock_release "$OWNER_LOCK"
+  return 0
+}
+
+failure_episode_verified() {
+  local outcome
+  [ ! -e "$STATE/.afk" ] || return 1
+  [ -e "$FAILURE_NOTICE" ] || return 1
+  outcome=$(sed -n '1s/^.*outcome=\([a-z][a-z-]*\) .*$/\1/p' "$STATE/.claude-autoarm-epoch" 2>/dev/null || true)
+  case "$outcome" in
+    failed|failed-suppressed) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+i=0
+while [ "$i" -lt $((SYNC_WAIT_MS / 100)) ]; do
+  if autoarm_owns_recovery; then
+    if fm_watcher_healthy "$STATE" "$WATCH" "$GRACE" "$FM_HOME"; then
+      fm_failure_episode_reset "$STATE" || exit 2
+    fi
+    exit 0
+  fi
+  sleep 0.1
+  i=$((i + 1))
+done
+if autoarm_owns_recovery; then
+  if fm_watcher_healthy "$STATE" "$WATCH" "$GRACE" "$FM_HOME"; then
+    fm_failure_episode_reset "$STATE" || exit 2
+  fi
+  exit 0
+fi
+
+# The auto-arm genuinely failed to establish: consume the bounded re-block
+# budget before considering the verified one-time attended fail-open.
+budget_account_current_epoch || block_stop
+terminal_fail_open
+terminal_status=$?
+if [ "$terminal_status" -eq 0 ]; then
+  if [ "$FM_SUP_IN_FLIGHT" -gt 0 ]; then
+    NEED_DESC="$FM_SUP_IN_FLIGHT task(s) in flight"
+  elif [ "$FM_SUP_SOURCES" -gt 0 ]; then
+    NEED_DESC="$FM_SUP_SOURCES process-event source(s) registered"
+  else
+    NEED_DESC="X-mode relay polling active"
+  fi
+  printf '{"systemMessage":"FIRSTMATE SUPERVISION IS GENUINELY DOWN: %s, the Stop-owned auto-arm exhausted its bounded retries and one failure notice, no watcher or automatic continuation exists, and the block budget is exhausted. Keep this session attended and diagnose the automatic Stop-hook and watcher startup before relying on unattended supervision."}\n' "$NEED_DESC"
+  exit 0
+fi
+[ "$terminal_status" -eq 2 ] && exit 0
+block_stop

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

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# Self-update a running firstmate and its secondmates to the latest origin.
+#
+# Mechanical half of the /updatefirstmate skill. Fast-forwards the running
+# firstmate repo's default branch from origin, then fast-forwards every
+# registered secondmate home. Local homes are treehouse worktrees or standalone
+# clones; remote routes update their configured code root on that host and then
+# fast-forward the persistent home to that root. FAST-FORWARD ONLY, exactly like
+# fm-fleet-sync.sh: never force, never create a merge commit, never stash;
+# advance a target only when it is a clean fast-forward, otherwise skip and
+# report. A tracked-files fast-forward never touches the gitignored operational
+# dirs (data/, state/, config/, projects/, .no-mistakes/), so a secondmate's
+# in-flight work is never disrupted. Worktrees of this repo share one object
+# store, so a single fetch refreshes them all; standalone-clone homes are
+# fetched on their own. Secondmate homes are leased at a detached HEAD on the
+# default branch, so a fast-forward there advances HEAD only and never touches
+# any other worktree's checkout or the shared `main` branch.
+#
+# The fast-forward mechanics live in bin/fm-ff-lib.sh (base_mode "origin" here);
+# the same library drives the local-HEAD secondmate sync used by fm-spawn.sh and
+# fm-bootstrap.sh, so there is one ff implementation, not several.
+#
+# It does NOT re-read AGENTS.md or nudge secondmates itself - those are LLM /
+# tmux actions the skill performs. The script's job is the safe git mechanics
+# plus a parseable summary telling the caller what to do next:
+#   - one status line per target (updated/already current/skipped)
+#   - reread-firstmate: yes|no    (did the running firstmate's instructions change)
+#   - nudge-secondmates: fm-<id>...|none   (updated live secondmates to nudge)
+#
+# Usage: fm-update.sh [--help]
+set -eu
+
+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}"
+SECONDMATES_MD="$FM_HOME/data/secondmates.md"
+# shellcheck source=bin/fm-ff-lib.sh
+. "$SCRIPT_DIR/fm-ff-lib.sh"
+
+"$SCRIPT_DIR/fm-guard.sh" || true
+
+usage() { echo "usage: fm-update.sh [--help]" >&2; }
+
+if [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
+  usage
+  exit 0
+fi
+[ $# -eq 0 ] || { usage; exit 1; }
+
+# --- main firstmate repo ---------------------------------------------------
+
+reread_firstmate="no"
+ff_target "$FM_ROOT" "firstmate" origin no no
+if [ "$FF_STATUS" = "updated" ] && [ -n "$FF_INSTR" ]; then
+  reread_firstmate="yes"
+fi
+
+# --- secondmates -----------------------------------------------------------
+# An updated live secondmate is nudged whenever it advanced (nudge_requires_instr
+# is "no" here): /updatefirstmate's nudge is a gentle re-read steer, kept on the
+# same condition it has always used.
+
+FF_NUDGE_WINDOWS=""
+FF_SEEN_HOMES=""
+
+# Live direct reports first: state/<id>.meta with kind=secondmate carries the
+# authoritative home= path.
+sweep_live_secondmate_metas "$STATE" origin no
+
+# Registry backstop: a secondmate registered in data/secondmates.md but without
+# a live meta (e.g. between restarts) is still its persistent on-disk home.
+if [ -f "$SECONDMATES_MD" ]; then
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      "- "*) ;;
+      *) continue ;;
+    esac
+    if ! secondmate_registry_parse_line "$line"; then
+      echo "secondmate registry: skipped malformed entry: $line" >&2
+      continue
+    fi
+    id=$SECONDMATE_REGISTRY_ID
+    home=$SECONDMATE_REGISTRY_HOME
+    if [ "$SECONDMATE_REGISTRY_REMOTE" -eq 1 ]; then
+      if remote_out=$("$SCRIPT_DIR/fm-on.sh" "$id" fm-remote-secondmate-control.sh update "$id" < /dev/null 2>&1); then
+        remote_result=$(printf '%s\n' "$remote_out" | tail -1)
+        case "$remote_result" in
+          synced:*)
+            echo "remote secondmate $id: updated on $SECONDMATE_REGISTRY_HOST (${remote_result#synced: })"
+            if [ -f "$STATE/$id.meta" ] && grep -qx 'kind=secondmate' "$STATE/$id.meta"; then
+              FF_NUDGE_WINDOWS="$FF_NUDGE_WINDOWS fm-$id"
+            fi
+            ;;
+          current:*) echo "remote secondmate $id: already current on $SECONDMATE_REGISTRY_HOST (${remote_result#current: })" ;;
+          *) echo "remote secondmate $id: skipped on $SECONDMATE_REGISTRY_HOST: malformed update result" >&2 ;;
+        esac
+      else
+        echo "remote secondmate $id: skipped on $SECONDMATE_REGISTRY_HOST: ${remote_out%%$'\n'*}" >&2
+      fi
+    else
+      process_secondmate "$id" "$home" "" origin no
+    fi
+  done < "$SECONDMATES_MD"
+fi
+
+# --- caller action summary -------------------------------------------------
+
+echo "reread-firstmate: $reread_firstmate"
+echo "nudge-secondmates:${FF_NUDGE_WINDOWS:- none}"