@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/backend/fm-supervision-instructions.sh

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+# Render the primary-harness supervision operating block for session start and
+# the short repair line used by guards and turn-end hooks.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+FM_ROOT="${FM_ROOT_OVERRIDE:-$REPO_ROOT}"
+FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}"
+CONFIG="${FM_CONFIG_OVERRIDE:-$FM_HOME/config}"
+DOC_DIR="$REPO_ROOT/docs/supervision-protocols"
+
+HARNESS=
+READ_ONLY=0
+AFK=0
+X_MODE=0
+REPAIR_LINE=0
+QUEUE_PENDING=0
+
+usage() {
+  cat <<'EOF'
+Usage: fm-supervision-instructions.sh [--harness <name>] [--read-only 0|1] [--afk 0|1] [--x-mode 0|1] [--repair-line] [--queue-pending 0|1]
+
+Print the current primary harness's supervision operating instructions.
+With --repair-line, print one concise repair instruction for guard and hook messages.
+EOF
+}
+
+bool_value() {
+  case "$1" in
+    1|true|TRUE|yes|YES) printf '1\n' ;;
+    *) printf '0\n' ;;
+  esac
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --harness)
+      [ "$#" -gt 1 ] || { echo "error: --harness requires a value" >&2; exit 2; }
+      HARNESS=$2
+      shift 2
+      ;;
+    --read-only)
+      [ "$#" -gt 1 ] || { echo "error: --read-only requires 0 or 1" >&2; exit 2; }
+      READ_ONLY=$(bool_value "$2")
+      shift 2
+      ;;
+    --afk)
+      [ "$#" -gt 1 ] || { echo "error: --afk requires 0 or 1" >&2; exit 2; }
+      AFK=$(bool_value "$2")
+      shift 2
+      ;;
+    --x-mode)
+      [ "$#" -gt 1 ] || { echo "error: --x-mode requires 0 or 1" >&2; exit 2; }
+      X_MODE=$(bool_value "$2")
+      shift 2
+      ;;
+    --queue-pending)
+      [ "$#" -gt 1 ] || { echo "error: --queue-pending requires 0 or 1" >&2; exit 2; }
+      QUEUE_PENDING=$(bool_value "$2")
+      shift 2
+      ;;
+    --repair-line)
+      REPAIR_LINE=1
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "error: unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [ -z "$HARNESS" ]; then
+  HARNESS=$("$SCRIPT_DIR/fm-harness.sh" 2>/dev/null || printf unknown)
+fi
+
+case "$HARNESS" in
+  claude|codex|opencode|pi|grok|cursor) SNIPPET="$DOC_DIR/$HARNESS.md" ;;
+  pi-signed) SNIPPET="$DOC_DIR/pi.md" ;;
+  *) HARNESS=unknown; SNIPPET="$DOC_DIR/unknown.md" ;;
+esac
+[ -f "$SNIPPET" ] || SNIPPET="$DOC_DIR/unknown.md"
+
+checkpoint_seconds=${FM_CODEX_WATCH_CHECKPOINT:-180}
+pi_ext="$FM_ROOT/.pi/extensions/fm-primary-pi-watch.ts"
+pi_turnend_ext="$FM_ROOT/.pi/extensions/fm-primary-turnend-guard.ts"
+x_mode_env="$CONFIG/x-mode.env"
+
+shell_quote() {
+  printf "'"
+  printf '%s' "$1" | sed "s/'/'\\\\''/g"
+  printf "'"
+}
+
+x_mode_env_sh=$(shell_quote "$x_mode_env")
+
+if [ "$X_MODE" -eq 0 ] && [ -f "$x_mode_env" ]; then
+  X_MODE=1
+fi
+
+render_snippet() {
+  local line
+  while IFS= read -r line || [ -n "$line" ]; do
+    line=${line//__FM_PI_EXT__/$pi_ext}
+    line=${line//__FM_PI_TURNEND_EXT__/$pi_turnend_ext}
+    line=${line//__FM_X_MODE_ENV_SH__/$x_mode_env_sh}
+    line=${line//__FM_X_MODE_ENV__/$x_mode_env}
+    printf '%s\n' "$line"
+  done < "$SNIPPET"
+}
+
+repair_line() {
+  if [ "$READ_ONLY" -eq 1 ]; then
+    printf '%s\n' 'Watcher repair belongs to the session holding the fleet lock; do not drain, arm, or repair from this read-only session.'
+    return 0
+  fi
+  if [ "$AFK" -eq 1 ]; then
+    printf '%s\n' 'Away mode owns watcher supervision; load /afk and ensure the daemon is running instead of starting normal supervision directly.'
+    return 0
+  fi
+
+  prefix=
+  if [ "$QUEUE_PENDING" -eq 1 ]; then
+    prefix='After draining queued wakes, '
+  fi
+  if [ "$X_MODE" -eq 1 ]; then
+    prefix="${prefix}source ${x_mode_env_sh} first, then "
+  fi
+
+  case "$HARNESS" in
+    claude)
+      printf '%s%s\n' "$prefix" 'watcher supervision needs Stop-owned automatic recovery; inspect the hook registration and startup status before ending the turn.'
+      ;;
+    codex)
+      printf '%s%s%s%s\n' "$prefix" 'repair missing watcher supervision with a foreground checkpoint: bin/fm-watch-checkpoint.sh --seconds ' "$checkpoint_seconds" '.'
+      ;;
+    pi|pi-signed)
+      printf '%s%s%s%s%s%s\n' "$prefix" 'repair a missing or failed watcher cycle with the Pi tool fm_watch_arm_pi, or restart Pi with -e ' "$pi_turnend_ext" ' -e ' "$pi_ext" ' if the extensions are not loaded.'
+      ;;
+    opencode)
+      printf '%s%s\n' "$prefix" 'repair missing watcher supervision by letting the OpenCode TUI plugin arm after idle; use bin/fm-watch-arm.sh only as a manual recovery probe if the plugin reports failure.'
+      ;;
+    grok)
+      printf '%s%s\n' "$prefix" 'repair missing watcher supervision with bin/fm-watch-arm.sh as its own Grok tracked background task, never shell &.'
+      ;;
+    cursor)
+      printf '%s%s\n' "$prefix" 'watcher supervision is owned by the stop-hook park; inspect the hook registration and watcher startup path before ending the turn.'
+      ;;
+    *)
+      printf '%s%s\n' "$prefix" 'repair missing watcher supervision according to the session-start block for this harness; do not use shell &.'
+      ;;
+  esac
+}
+
+ordinary_wake_line() {
+  case "$HARNESS" in
+    claude)
+      printf '%s\n' '- Ordinary wake: the Stop-owned auto-arm (bin/fm-claude-stop-autoarm.sh) already owns watcher continuity; drain and handle the wake, and do not arm another cycle yourself.'
+      ;;
+    codex)
+      printf '%s\n' '- Ordinary wake: take the next foreground bin/fm-watch-checkpoint.sh checkpoint as directed below.'
+      ;;
+    pi|pi-signed)
+      printf '%s\n' '- Ordinary wake: the Pi extension already owns watcher continuity; do not arm another cycle.'
+      ;;
+    opencode)
+      printf '%s\n' '- Ordinary wake: the OpenCode TUI plugin already owns watcher continuity; do not arm manually.'
+      ;;
+    grok)
+      printf '%s\n' '- Ordinary wake: re-arm exactly one bin/fm-watch-arm.sh Grok tracked background task as directed below.'
+      ;;
+    cursor)
+      printf '%s\n' '- Ordinary wake: the stop-hook park (bin/fm-turnend-guard-cursor.sh) already owns watcher continuity; drain and handle the wake, and do not arm another cycle yourself.'
+      ;;
+    *)
+      printf '%s\n' '- Ordinary wake: follow the continuation in the harness protocol below; do not use shell &.'
+      ;;
+  esac
+}
+
+if [ "$REPAIR_LINE" -eq 1 ]; then
+  repair_line
+  exit 0
+fi
+
+RULE='================================================================================'
+printf '%s\n' "$RULE"
+printf 'SUPERVISION OPERATING INSTRUCTIONS - primary harness: %s\n' "$HARNESS"
+printf '%s\n' "$RULE"
+printf 'Current state:\n'
+if [ "$READ_ONLY" -eq 1 ]; then
+  printf '%s\n' '- Lock: read-only; do not drain, arm, spawn, steer, merge, or repair fleet state here.'
+else
+  printf '%s\n' '- Lock: held by this session; this session owns normal supervision unless away mode says otherwise.'
+fi
+if [ "$AFK" -eq 1 ]; then
+  printf '%s\n' '- Away mode: active; load /afk and keep normal harness supervision paused while the daemon owns the watcher.'
+else
+  printf '%s\n' '- Away mode: inactive.'
+fi
+if [ "$X_MODE" -eq 1 ]; then
+  printf '%s%s%s\n' '- X mode: active; source ' "$x_mode_env" ' before launching any watcher process so the 30s cadence is inherited.'
+else
+  printf '%s\n' '- X mode: inactive; use the default watcher cadence.'
+fi
+ordinary_wake_line
+printf '\n'
+render_snippet
+printf '\n'

package/.agents/backend/fm-supervision-lib.sh

@@ -0,0 +1,90 @@
+# shellcheck shell=bash
+# Shared "supervision missing" predicate.
+# Usage: . bin/fm-supervision-lib.sh
+#
+# Reports whether a firstmate home needs supervision because it has in-flight
+# work (a state/<id>.meta exists) or an X-mode relay poll
+# (state/x-watch.check.sh), and whether its watcher has a fresh liveness beacon
+# (state/.last-watcher-beat, touched every poll cycle, within the grace window).
+# bin/fm-turnend-guard.sh uses the PID-strict fm_watcher_healthy from
+# bin/fm-wake-lib.sh for its block decision. bin/fm-guard.sh uses the model-aware
+# fm_watcher_supervision_verdict (also in bin/fm-wake-lib.sh), which owns what a
+# live watcher process means per supervision model. The status fields here retain
+# the beacon-age details used in their messages.
+
+# Portable mtime; Linux stat lacks -f, macOS stat lacks -c.
+fm_sup_stat_mtime() {
+  if [ "$(uname)" = Darwin ]; then
+    stat -f %m "$1" 2>/dev/null
+  else
+    stat -c %Y "$1" 2>/dev/null
+  fi
+}
+
+# fm_supervision_status <state-dir> [grace-seconds]
+# Populates, for the state dir at $1:
+#   FM_SUP_IN_FLIGHT      count of state/*.meta (in-flight tasks)
+#   FM_SUP_SOURCES        count of registered process-to-event sources
+#   FM_SUP_NEEDED         true/false - in-flight work, an X-mode relay poll, or a
+#                         registered event source (a source is a wait on an
+#                         external process, not a task, so it has no metadata)
+#   FM_SUP_WATCHER_FRESH  true/false - a watcher beacon within the grace window
+#   FM_SUP_BEACON_DESC    human-readable beacon age, for banners ("never" if absent)
+#   FM_SUP_QUEUE_PENDING  true/false - state/.wake-queue has unread records
+# grace-seconds defaults to $FM_GUARD_GRACE, then 300, matching fm-guard.sh.
+# Always returns 0; callers read the vars, or use fm_supervision_unhealthy below.
+fm_supervision_status() {
+  local state=$1 grace=${2:-${FM_GUARD_GRACE:-300}} meta source beat m age
+  FM_SUP_IN_FLIGHT=0
+  FM_SUP_NEEDED=false
+  FM_SUP_WATCHER_FRESH=false
+  FM_SUP_BEACON_DESC=never
+  FM_SUP_QUEUE_PENDING=false
+
+  for meta in "$state"/*.meta; do
+    [ -e "$meta" ] || continue
+    FM_SUP_IN_FLIGHT=$((FM_SUP_IN_FLIGHT + 1))
+  done
+  FM_SUP_SOURCES=0
+  for source in "$state"/procevent/*.source; do
+    [ -e "$source" ] || continue
+    FM_SUP_SOURCES=$((FM_SUP_SOURCES + 1))
+  done
+  if [ "$FM_SUP_IN_FLIGHT" -gt 0 ] \
+    || [ -f "$state/x-watch.check.sh" ] \
+    || [ "$FM_SUP_SOURCES" -gt 0 ]; then
+    FM_SUP_NEEDED=true
+  fi
+
+  beat="$state/.last-watcher-beat"
+  if [ -e "$beat" ]; then
+    m=$(fm_sup_stat_mtime "$beat")
+    if [ -n "$m" ]; then
+      age=$(( $(date +%s) - m ))
+      FM_SUP_BEACON_DESC="${age}s ago"
+      [ "$age" -lt "$grace" ] && FM_SUP_WATCHER_FRESH=true
+    else
+      # shellcheck disable=SC2034 # Read by callers (fm-guard.sh) after sourcing.
+      FM_SUP_BEACON_DESC=unknown
+    fi
+  fi
+
+  # shellcheck disable=SC2034 # Read by callers (fm-guard.sh) after sourcing.
+  [ -s "$state/.wake-queue" ] && FM_SUP_QUEUE_PENDING=true
+  return 0
+}
+
+# fm_supervision_needed <state-dir> [grace-seconds]
+# Exit 0 (true) exactly when the home needs a watcher.
+fm_supervision_needed() {
+  fm_supervision_status "$@"
+  [ "$FM_SUP_NEEDED" = true ]
+}
+
+# fm_supervision_unhealthy <state-dir> [grace-seconds]
+# Exit 0 (true) exactly when supervision is needed and no watcher has a fresh
+# beacon. Exit 1 (false) otherwise.
+fm_supervision_unhealthy() {
+  fm_supervision_status "$@"
+  [ "$FM_SUP_NEEDED" = true ] && [ "$FM_SUP_WATCHER_FRESH" = false ]
+}

package/.agents/backend/fm-supervisor-target-lib.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# fm-supervisor-target-lib.sh - the single owner of supervisor-pane discovery.
+#
+# The away-mode daemon (bin/fm-supervise-daemon.sh) must know which pane runs
+# firstmate itself, both to inject escalations into it and, for the daemon, to
+# validate that target at startup. The script-owned away launcher
+# (bin/fm-afk-launch.sh) must resolve the SAME captain pane BEFORE it creates a
+# separate, non-visible terminal for the daemon, so it can pass that pane in as
+# FM_SUPERVISOR_TARGET (otherwise the daemon, running in its own terminal, would
+# auto-discover its OWN pane and inject there instead of into the captain's).
+#
+# Because both callers need the identical resolution, it lives here once. The
+# function names and precedence are unchanged from when this logic lived inline
+# in bin/fm-supervise-daemon.sh, so its unit tests (tests/fm-daemon.test.sh)
+# keep exercising the same names after the daemon sources this file.
+
+# Default supervisor pane target/backend when nothing is configured or detected.
+# "firstmate:0" is a tmux session:window name, so the bare fallback (nothing
+# configured, nothing detected) assumes tmux - matching the daemon's pre-herdr
+# behavior byte-for-byte when run outside both tmux and herdr.
+FM_SUPERVISOR_TARGET_DEFAULT="firstmate:0"
+FM_SUPERVISOR_BACKEND_DEFAULT="tmux"
+
+# discover_supervisor_target: resolve the pane running firstmate. Priority:
+#   1. FM_SUPERVISOR_TARGET env (explicit override) - may be a tmux target or a
+#      herdr "<session>:<pane-id>" target (paired with discover_supervisor_backend
+#      to know which).
+#   2. $TMUX_PANE - tmux sets this in every pane's environment; inherited by a
+#      process launched from firstmate's own pane.
+#   3. $HERDR_ENV=1 + $HERDR_PANE_ID - herdr injects both into every process it
+#      manages a pane for; compose the "<session>:<pane-id>" target from
+#      $HERDR_SESSION (defaulting to "default", mirroring bin/backends/herdr.sh's
+#      fm_backend_herdr_session) and $HERDR_PANE_ID. Checked after $TMUX_PANE so a
+#      tmux pane nested inside herdr still resolves to tmux, matching
+#      fm_backend_detect's innermost-first rule.
+#   4. FM_SUPERVISOR_TARGET_DEFAULT - legacy tmux fallback (may not resolve if the
+#      session is named differently). Returns 1 so the caller can warn.
+discover_supervisor_target() {
+  if [ -n "${FM_SUPERVISOR_TARGET:-}" ]; then
+    printf '%s' "$FM_SUPERVISOR_TARGET"
+    return 0
+  fi
+  if [ -n "${TMUX_PANE:-}" ]; then
+    printf '%s' "$TMUX_PANE"
+    return 0
+  fi
+  if [ "${HERDR_ENV:-}" = "1" ] && [ -n "${HERDR_PANE_ID:-}" ]; then
+    printf '%s:%s' "${HERDR_SESSION:-default}" "$HERDR_PANE_ID"
+    return 0
+  fi
+  printf '%s' "$FM_SUPERVISOR_TARGET_DEFAULT"
+  return 1
+}
+
+# discover_supervisor_backend: resolve the supervisor pane's BACKEND, independent
+# of the target string so an explicit FM_SUPERVISOR_TARGET override still knows
+# which primitives (tmux vs herdr) to dispatch through. Priority mirrors
+# discover_supervisor_target and bin/fm-backend.sh's fm_backend_detect:
+#   1. FM_SUPERVISOR_BACKEND env (explicit override).
+#   2. $TMUX_PANE set - tmux.
+#   3. $HERDR_ENV=1 (with $HERDR_PANE_ID present) - herdr.
+#   4. FM_SUPERVISOR_BACKEND_DEFAULT (tmux) - matches the target fallback. Returns 1.
+discover_supervisor_backend() {
+  if [ -n "${FM_SUPERVISOR_BACKEND:-}" ]; then
+    printf '%s' "$FM_SUPERVISOR_BACKEND"
+    return 0
+  fi
+  if [ -n "${TMUX_PANE:-}" ]; then
+    printf 'tmux'
+    return 0
+  fi
+  if [ "${HERDR_ENV:-}" = "1" ] && [ -n "${HERDR_PANE_ID:-}" ]; then
+    printf 'herdr'
+    return 0
+  fi
+  printf '%s' "$FM_SUPERVISOR_BACKEND_DEFAULT"
+  return 1
+}

package/.agents/backend/fm-tangle-lib.sh

@@ -0,0 +1,53 @@
+# shellcheck shell=bash
+# Shared worktree-tangle guard for the firstmate-on-itself case.
+# Usage: . bin/fm-tangle-lib.sh
+#
+# Firstmate is a treehouse-pooled git repo of itself: crewmate worktrees and
+# secondmate homes are all linked `git worktree`s of the same repo, while the
+# PRIMARY checkout (the repo root firstmate operates from) is a normal checkout
+# on a real branch - normally the default branch, main. The "worktree tangle"
+# failure mode is a crewmate spawned to work on firstmate ITSELF branching and
+# committing in the primary checkout instead of its own disposable worktree,
+# stranding the primary on a feature branch (e.g. fm/readme-restructure-d3).
+#
+# fm_primary_tangle_branch detects exactly that and nothing else: a NAMED,
+# non-default branch checked out in the given root. It is deliberately silent for
+# every legitimate state - the primary on its default branch, and detached HEAD,
+# which is how every linked worktree and secondmate home legitimately sits on the
+# default branch. Detached HEAD on the default is fine; a feature branch in a
+# primary checkout is the alarm.
+
+# Resolve the default branch name of the git repo at <dir>: prefer origin/HEAD,
+# then fall back to a local main/master. Echoes the name, or returns 1.
+fm_default_branch() {
+  local dir=$1 ref branch
+  ref=$(git -C "$dir" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)
+  if [ -n "$ref" ]; then
+    printf '%s\n' "${ref#origin/}"
+    return 0
+  fi
+  for branch in main master; do
+    if git -C "$dir" show-ref --verify --quiet "refs/heads/$branch"; then
+      printf '%s\n' "$branch"
+      return 0
+    fi
+  done
+  return 1
+}
+
+# If the git checkout at <root> is tangled - on a NAMED branch that is not its
+# default branch - echo the offending branch name and return 0. For every healthy
+# state (not a git work tree, detached HEAD, or already on the default branch)
+# echo nothing and return 1. Detached HEAD is how linked worktrees and secondmate
+# homes legitimately sit, so they never trip this; only a feature branch checked
+# out in a primary checkout does.
+fm_primary_tangle_branch() {
+  local root=$1 cur default
+  git -C "$root" rev-parse --is-inside-work-tree >/dev/null 2>&1 || return 1
+  cur=$(git -C "$root" symbolic-ref --quiet --short HEAD 2>/dev/null || true)
+  [ -n "$cur" ] || return 1
+  default=$(fm_default_branch "$root") || return 1
+  [ "$cur" = "$default" ] && return 1
+  printf '%s\n' "$cur"
+  return 0
+}