@zerwiz/ymir 0.1.3 → 0.1.5

package/.agents/backend/fm-afk-return.sh

@@ -0,0 +1,241 @@
+#!/usr/bin/env bash
+# fm-afk-return.sh - deterministic away-mode return catch-up gate.
+#
+# Usage:
+#   fm-afk-return.sh          Stop away mode, present catch-up, and open/check gate.
+#   fm-afk-return.sh begin    Same as the default command.
+#   fm-afk-return.sh check    Re-present and close the gate only after blockers resolve.
+#   fm-afk-return.sh guard    Read-only refusal while away or catch-up is pending.
+#
+# `blocked:` is the crewmate protocol's firstmate-actionable verb. A live task's
+# open blocked event must be remediated and closed with `resolved [key=...]`, or
+# explicitly reclassified in the status stream with a durable reason, before an
+# ordinary captain request may proceed. `needs-decision:` is deliberately not
+# part of this blocker gate.
+#
+# The durable state/.afk-return-catchup file is written BEFORE daemon shutdown,
+# so a crash between stopping, wake presentation, and blocker handling fails closed.
+# It retains the presented wake, buffered-escalation, and wedge-marker evidence
+# until every live open blocker is closed and `check` succeeds. Repeated begin/check
+# calls are idempotent. `guard` never mutates state and is suitable for ordinary
+# read entrypoints such as fm-bearings-snapshot.sh.
+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}"
+GATE="$STATE/.afk-return-catchup"
+LOCK="$STATE/.afk-return-catchup.lock"
+
+usage() {
+  sed -n '2,7p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+clean_field() {
+  LC_ALL=C tr '\t\r\n' '   '
+}
+
+append_evidence() {  # <kind> <text> <file>
+  local kind=$1 text=$2 file=$3 clean record
+  [ -n "$text" ] || return 0
+  while IFS= read -r line || [ -n "$line" ]; do
+    [ -n "$line" ] || continue
+    clean=$(printf '%s' "$line" | clean_field)
+    record=$(printf 'evidence\t%s\t%s' "$kind" "$clean")
+    grep -Fqx "$record" "$file" 2>/dev/null || printf '%s\n' "$record" >> "$file"
+  done <<EOF
+$text
+EOF
+}
+
+preserve_evidence() {  # <destination>
+  local destination=$1
+  [ -f "$GATE" ] || return 0
+  grep '^evidence'"$(printf '\t')" "$GATE" >> "$destination" 2>/dev/null || true
+}
+
+scan_open_blockers() {  # -> tab-separated blocker rows
+  local meta id status key verb summary clean_summary
+  for meta in "$STATE"/*.meta; do
+    [ -f "$meta" ] || continue
+    id=$(basename "$meta")
+    id=${id%.meta}
+    status="$STATE/$id.status"
+    [ -f "$status" ] || continue
+    while IFS="$(printf '\t')" read -r key verb summary; do
+      [ "$verb" = blocked ] || continue
+      clean_summary=$(printf '%s' "$summary" | clean_field)
+      printf 'blocker\t%s\t%s\t%s\n' "$id" "$key" "$clean_summary"
+    done <<EOF
+$(status_open_decisions "$status")
+EOF
+  done
+}
+
+write_pending_seed() {  # Fail-closed marker before any lifecycle mutation.
+  local pending started
+  mkdir -p "$STATE" || return 1
+  started=$(awk -F '\t' '$1 == "started" { print $2; exit }' "$GATE" 2>/dev/null || true)
+  [ -n "$started" ] || started=$(date +%s)
+  pending=$(mktemp "$STATE/.afk-return-catchup.pending.XXXXXX") || return 1
+  {
+    printf 'schema\tfm-afk-return.v1\n'
+    printf 'started\t%s\n' "$started"
+    printf 'phase\tstopping-and-draining\n'
+    preserve_evidence /dev/stdout
+  } > "$pending" || { rm -f "$pending"; return 1; }
+  mv "$pending" "$GATE"
+}
+
+write_gate() {  # <evidence-file> <blockers-file>
+  local evidence=$1 blockers=$2 pending started
+  pending=$(mktemp "$STATE/.afk-return-catchup.pending.XXXXXX") || return 1
+  started=$(awk -F '\t' '$1 == "started" { print $2; exit }' "$GATE" 2>/dev/null || true)
+  [ -n "$started" ] || started=$(date +%s)
+  {
+    printf 'schema\tfm-afk-return.v1\n'
+    printf 'started\t%s\n' "$started"
+    printf 'phase\tblocked\n'
+    cat "$evidence" 2>/dev/null || true
+    cat "$blockers" 2>/dev/null || true
+  } > "$pending" || { rm -f "$pending"; return 1; }
+  mv "$pending" "$GATE"
+}
+
+print_evidence() {  # <file>
+  local file=$1 kind text
+  while IFS="$(printf '\t')" read -r tag kind text; do
+    [ "$tag" = evidence ] || continue
+    printf 'catch-up %s: %s\n' "$kind" "$text"
+  done < "$file"
+}
+
+print_blockers() {  # <file>
+  local file=$1 tag id key summary
+  while IFS="$(printf '\t')" read -r tag id key summary; do
+    [ "$tag" = blocker ] || continue
+    printf 'firstmate-actionable blocker: %s [key=%s] %s\n' "$id" "$key" "$summary"
+  done < "$file"
+}
+
+clear_delivery_artifacts() {
+  rm -f \
+    "$STATE/.subsuper-escalations" \
+    "$STATE/.subsuper-escalations.since" \
+    "$STATE/.subsuper-inject-wedged"
+}
+
+return_guard() {
+  if [ -e "$STATE/.afk" ]; then
+    printf 'fm-afk-return: away mode is still active; run bin/fm-afk-return.sh before ordinary captain work\n' >&2
+    return 3
+  fi
+  if [ -e "$GATE" ]; then
+    printf 'fm-afk-return: return catch-up is pending; remediate or durably reclassify every listed blocker, then run bin/fm-afk-return.sh check\n' >&2
+    print_blockers "$GATE" >&2
+    return 3
+  fi
+  return 0
+}
+
+return_reconcile() {
+  local evidence blockers drain_err drained wake_ack_line wake_ack_through wake_ack_generation wedge escalations lifecycle_ok=1
+  evidence=$(mktemp "$STATE/.afk-return-evidence.XXXXXX") || return 1
+  blockers=$(mktemp "$STATE/.afk-return-blockers.XXXXXX") || { rm -f "$evidence"; return 1; }
+  drain_err=$(mktemp "$STATE/.afk-return-drain.XXXXXX") || { rm -f "$evidence" "$blockers"; return 1; }
+  preserve_evidence "$evidence"
+
+  if [ -e "$STATE/.afk" ] || [ -e "$STATE/.afk-daemon-terminal" ]; then
+    if ! "$SCRIPT_DIR/fm-afk-launch.sh" stop; then
+      lifecycle_ok=0
+      append_evidence lifecycle 'away-mode shutdown failed; lifecycle state preserved for retry' "$evidence"
+    fi
+  fi
+
+  drained=$("$SCRIPT_DIR/fm-wake-drain.sh" 2> "$drain_err") || {
+    append_evidence lifecycle 'durable wake drain failed; retry catch-up before ordinary work' "$evidence"
+    lifecycle_ok=0
+    drained=""
+  }
+  grep -v '^WAKE_ACK_REQUIRED:' "$drain_err" >&2 || true
+  wake_ack_line=$(grep '^WAKE_ACK_REQUIRED:' "$drain_err" | tail -1)
+  wake_ack_through=$(sed -n 's/^WAKE_ACK_REQUIRED:.*--ack-through \([0-9][0-9]*\) --recovery-generation [A-Za-z0-9._-][A-Za-z0-9._-]*$/\1/p' "$drain_err" | tail -1)
+  wake_ack_generation=$(sed -n 's/^WAKE_ACK_REQUIRED:.*--ack-through [0-9][0-9]* --recovery-generation \([A-Za-z0-9._-][A-Za-z0-9._-]*\)$/\1/p' "$drain_err" | tail -1)
+  if [ -n "$wake_ack_line" ] && { [ -z "$wake_ack_through" ] || [ -z "$wake_ack_generation" ]; }; then
+    append_evidence lifecycle 'durable wake drain returned an invalid acknowledgement; retry catch-up before ordinary work' "$evidence"
+    lifecycle_ok=0
+  fi
+  append_evidence wake "$drained" "$evidence"
+
+  if [ -s "$STATE/.subsuper-inject-wedged" ]; then
+    wedge=$(head -1 "$STATE/.subsuper-inject-wedged" 2>/dev/null || true)
+    append_evidence wedge "$wedge" "$evidence"
+  fi
+  if [ -s "$STATE/.subsuper-escalations" ]; then
+    escalations=$(cat "$STATE/.subsuper-escalations" 2>/dev/null || true)
+    append_evidence escalation "$escalations" "$evidence"
+  fi
+
+  scan_open_blockers > "$blockers"
+  if [ "$lifecycle_ok" -ne 1 ] || [ -s "$blockers" ]; then
+    write_gate "$evidence" "$blockers" || { rm -f "$evidence" "$blockers" "$drain_err"; return 1; }
+    printf 'fm-afk-return: catch-up must finish before the captain request\n' >&2
+    print_evidence "$GATE" >&2
+    print_blockers "$GATE" >&2
+    printf 'fm-afk-return: handle each blocker now, or close it with resolved [key=...] and append a durable reclassification reason, then run bin/fm-afk-return.sh check\n' >&2
+    rm -f "$evidence" "$blockers" "$drain_err"
+    return 3
+  fi
+
+  if ! print_evidence "$evidence"; then
+    append_evidence lifecycle 'recovery evidence publication failed; retry catch-up before ordinary work' "$evidence"
+    write_gate "$evidence" "$blockers" || { rm -f "$evidence" "$blockers" "$drain_err"; return 1; }
+    printf 'fm-afk-return: recovery evidence could not be published; catch-up remains pending\n' >&2
+    rm -f "$evidence" "$blockers" "$drain_err"
+    return 3
+  fi
+
+  if [ -n "$wake_ack_line" ] && ! printf '%s\n' "$wake_ack_line" >&2; then
+    append_evidence lifecycle 'durable wake acknowledgement command publication failed; retry catch-up before ordinary work' "$evidence"
+    write_gate "$evidence" "$blockers" || { rm -f "$evidence" "$blockers" "$drain_err"; return 1; }
+    rm -f "$evidence" "$blockers" "$drain_err"
+    return 3
+  fi
+
+  rm -f "$GATE"
+  clear_delivery_artifacts
+  rm -f "$evidence" "$blockers" "$drain_err"
+  printf 'fm-afk-return: catch-up clear; ordinary captain work may proceed\n'
+  return 0
+}
+
+main() {
+  local mode=${1:-begin} rc
+  case "$mode" in
+    begin|check) ;;
+    guard) return_guard; return ;;
+    -h|--help|help) usage; return 0 ;;
+    *) usage >&2; return 2 ;;
+  esac
+
+  # The mutating begin/check paths need locks and the keyed status fold.
+  # `guard` returned above without sourcing fm-wake-lib.sh, whose initialization
+  # creates the state directory, so the advertised read-only guard is literal.
+  # shellcheck source=bin/fm-wake-lib.sh
+  . "$SCRIPT_DIR/fm-wake-lib.sh"
+  # shellcheck source=bin/fm-classify-lib.sh
+  . "$SCRIPT_DIR/fm-classify-lib.sh"
+
+  mkdir -p "$STATE" || return 1
+  fm_lock_acquire_wait "$LOCK"
+  trap 'fm_lock_release "$LOCK"' EXIT
+  write_pending_seed || { fm_lock_release "$LOCK"; trap - EXIT; return 1; }
+  return_reconcile
+  rc=$?
+  fm_lock_release "$LOCK"
+  trap - EXIT
+  return "$rc"
+}
+
+main "$@"

package/.agents/backend/fm-afk-start.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# Enter away mode and run the sub-supervisor daemon in a harness-tracked
+# foreground process when one is not already alive.
+#
+# Usage: fm-afk-start.sh
+#   Sets state/.afk unless FM_AFK_STATE_PREPARED=1, checks
+#   state/.supervise-daemon.lock, and:
+#     - prints "afk: daemon already running pid=<pid>" then exits 0 when that
+#       lock is held by a live daemon (a REFRESH: no stale-artifact clear);
+#     - otherwise clears any prior away session's stale escalation artifacts
+#       (fm_afk_clear_stale_artifacts) for a direct, non-prepared start, then
+#       execs bin/fm-supervise-daemon.sh in the foreground. A prepared start was
+#       already cleared transactionally by bin/fm-afk-launch.sh.
+#
+# This file is sourceable: its BASH_SOURCE guard keeps main from running, while
+# exposing the daemon-lock helpers and fm_afk_clear_stale_artifacts. Sourcing it
+# enables nounset and errexit; callers that need different shell options must
+# restore them explicitly.
+#
+# This is the COMMON daemon entry for every backend. HOW it becomes a tracked
+# background process differs by harness/backend and is owned elsewhere:
+#   - Harnesses with a native in-pane tracked-background tool (e.g. claude, grok)
+#     run this directly via that tool, so the daemon inherits the captain pane's
+#     env and auto-discovers it.
+#   - Harnesses with NO native background mechanism (e.g. pi) run this THROUGH
+#     bin/fm-afk-launch.sh, which creates a non-visible tracked terminal per
+#     backend (herdr tab/workspace, tmux detached session) and passes the
+#     captain pane in as FM_SUPERVISOR_TARGET so injection targets it, not the
+#     daemon's own new pane.
+# Do not wrap this in `nohup ... &`: Codex/herdr can reap fire-and-forget shell
+# children after the tool call returns, while a tracked background terminal stays
+# attached and has a real lifecycle.
+set -eu
+
+FM_AFK_START_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$FM_AFK_START_DIR/.." && pwd)}"
+FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}"
+FM_AFK_STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
+FM_AFK_LOCK="$FM_AFK_STATE/.supervise-daemon.lock"
+FM_AFK_DAEMON="$FM_AFK_START_DIR/fm-supervise-daemon.sh"
+
+# shellcheck source=bin/fm-wake-lib.sh
+. "$FM_AFK_START_DIR/fm-wake-lib.sh"
+
+fm_afk_start_usage() {
+  sed -n '2,14p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+# fm_afk_clear_stale_artifacts: on a FRESH away-session entry (the daemon is not
+# already running), drop the previous away session's leftover escalation-delivery
+# artifacts so they cannot surface as stale escalations under the new session.
+# These are session-scoped by timing: a fresh entry owns a new supervision
+# session and the new daemon has not produced anything yet, so anything present
+# here belongs to a PRIOR session. This never drops a genuinely-pending
+# escalation - the delivery buffer is a transient cache, and any condition still
+# true (a crew still blocked, a check still firing) is re-derived and re-escalated
+# fresh by the daemon's heartbeat catch-all scan and the durable
+# state/.wake-queue replay (see docs/herdr-backend.md "Away-mode stale-artifact
+# lifecycle" and bin/fm-supervise-daemon.sh's escalate_add/inject_wedge_alarm).
+# NOT called on a refresh (daemon already alive), so the current session's own
+# buffered escalations are preserved.
+fm_afk_clear_stale_artifacts() {  # <state-dir>
+  local state=$1
+  rm -f "$state/.subsuper-escalations" \
+        "$state/.subsuper-escalations.since" \
+        "$state/.subsuper-inject-wedged" 2>/dev/null
+}
+
+daemon_lock_owner() {
+  local owner
+  if [ -L "$FM_AFK_LOCK" ]; then
+    owner=$(readlink "$FM_AFK_LOCK" 2>/dev/null) || return 1
+    [ -n "$owner" ] || return 1
+    case "$owner" in
+      /*) printf '%s\n' "$owner" ;;
+      *) printf '%s/%s\n' "$(dirname "$FM_AFK_LOCK")" "$owner" ;;
+    esac
+    return 0
+  fi
+  [ -d "$FM_AFK_LOCK" ] || return 1
+  printf '%s\n' "$FM_AFK_LOCK"
+}
+
+daemon_pid_matches() {
+  local pid=$1 owner=$2 identity current command
+  identity=$(cat "$owner/pid-identity" 2>/dev/null || true)
+  if [ -n "$identity" ]; then
+    current=$(fm_pid_identity "$pid") || return 1
+    [ "$current" = "$identity" ]
+    return
+  fi
+  command=$(ps -p "$pid" -o command= 2>/dev/null || true)
+  case "$command" in
+    *"$FM_AFK_DAEMON"*|*"fm-supervise-daemon.sh"*) return 0 ;;
+  esac
+  return 1
+}
+
+daemon_lock_pid() {
+  local owner
+  owner=$(daemon_lock_owner) || return 1
+  cat "$owner/pid" 2>/dev/null || true
+}
+
+daemon_lock_held_by_live_daemon() {
+  local owner pid
+  owner=$(daemon_lock_owner) || return 1
+  pid=$(cat "$owner/pid" 2>/dev/null || true)
+  fm_pid_alive "$pid" || return 1
+  daemon_pid_matches "$pid" "$owner"
+}
+
+fm_afk_flag_write() {  # <state-dir>
+  local state=$1 lock="$1/.cursor-park-owner.lock" pending attempt=0 status=1
+  mkdir -p "$state" || return 1
+  [ ! -d "$state/.afk" ] || return 1
+  pending=$(mktemp "$state/.afk.pending.XXXXXX") || return 1
+  date '+%s' > "$pending" || { rm -f "$pending"; return 1; }
+  while [ "$attempt" -lt 50 ]; do
+    attempt=$((attempt + 1))
+    if fm_lock_try_acquire "$lock"; then
+      mv "$pending" "$state/.afk" && status=0
+      fm_lock_release "$lock"
+      rm -f "$pending" 2>/dev/null || true
+      return "$status"
+    fi
+    [ "$attempt" -lt 50 ] && sleep 0.1
+  done
+  rm -f "$pending" 2>/dev/null || true
+  return 1
+}
+
+fm_afk_start_main() {
+  case "${1:-}" in
+    '' ) ;;
+    -h|--help) fm_afk_start_usage; return 0 ;;
+    * ) echo "usage: $(basename "${BASH_SOURCE[1]:-fm-afk-start.sh}")" >&2; return 2 ;;
+  esac
+
+  mkdir -p "$FM_AFK_STATE"
+  if [ "${FM_AFK_STATE_PREPARED:-0}" = 1 ]; then
+    [ -f "$FM_AFK_STATE/.afk" ] || { echo "afk: launcher-prepared state is missing" >&2; return 1; }
+  else
+    fm_afk_flag_write "$FM_AFK_STATE" || { echo "afk: failed to write away-mode flag" >&2; return 1; }
+  fi
+
+  local pid
+  pid=$(daemon_lock_pid 2>/dev/null || true)
+  if daemon_lock_held_by_live_daemon; then
+    echo "afk: daemon already running pid=$pid"
+    return 0
+  fi
+
+  if fm_pid_alive "$pid" && [ -n "$pid" ]; then
+    fm_lock_remove_path "$FM_AFK_LOCK" 2>/dev/null || true
+  fi
+
+  # Fresh start: clear the previous away session's stale delivery artifacts
+  # before the new daemon can surface them (fix for the leaked-artifact defect).
+  if [ "${FM_AFK_STATE_PREPARED:-0}" != 1 ]; then
+    fm_afk_clear_stale_artifacts "$FM_AFK_STATE"
+  fi
+
+  echo "afk: starting supervise daemon in foreground; keep this command as a tracked background session"
+  exec "$FM_AFK_DAEMON"
+}
+
+# Run only when executed, not when sourced (tests source fm_afk_clear_stale_artifacts
+# and the lock helpers directly).
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  fm_afk_start_main "$@"
+fi