@zerwiz/ymir 0.1.3 → 0.1.5

package/.agents/backend/fm-config-push.sh

@@ -0,0 +1,254 @@
+#!/usr/bin/env bash
+# Push declared inherited local material to live secondmate homes.
+# Usage: fm-config-push.sh [--help]
+#
+# Mid-session convergence for inherited local material such as
+# config/crew-dispatch.json, config/backend, or data/captain-shared.md updates.
+# This discovers live secondmate homes from state/*.meta, backfills
+# home= from data/secondmates.md for older meta records, and reuses the same
+# propagation machinery as bootstrap, but deliberately does not
+# fast-forward tracked files.
+# After a successful per-home propagation that changes any allowlisted config/*
+# item, local routes receive the generation-specific literal-content pointer from
+# fm-config-inherit-lib.sh. Remote routes receive one durable marked reread nudge
+# through their SSH route. Unchanged config and data/captain-shared.md-only
+# updates send no reread unless a previous send failure is pending for that home.
+# Warnings-only skips exit 0; real propagation or reread-send errors exit non-zero.
+set -u
+
+usage() {
+  cat <<'EOF'
+Usage: fm-config-push.sh [--help]
+
+Push the primary firstmate home's declared inherited local material into each
+live secondmate home.
+
+This is local-material-only:
+  - does not fast-forward tracked files
+  - after successful config/* changes, sends a local literal-content pointer or
+    one durable marked remote reread nudge
+    (no message when config is unchanged unless a previous send failure is pending)
+  - reports each live home and each inheritable item as pushed, unchanged,
+    skipped, or error
+  - exits non-zero for real propagation errors or reread-send failures
+
+Live homes come from state/*.meta records with kind=secondmate.
+data/secondmates.md is only a fallback for missing home= fields in older or
+incomplete meta records.
+
+Environment overrides follow the rest of firstmate:
+  FM_HOME            active firstmate home
+  FM_ROOT_OVERRIDE  firstmate repo root
+  FM_STATE_OVERRIDE state dir
+  FM_DATA_OVERRIDE  data dir
+  FM_CONFIG_OVERRIDE config dir
+EOF
+}
+
+case "${1:-}" in
+  -h|--help)
+    usage
+    exit 0
+    ;;
+  "")
+    ;;
+  *)
+    echo "usage: fm-config-push.sh [--help]" >&2
+    exit 2
+    ;;
+esac
+
+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}"
+STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
+DATA="${FM_DATA_OVERRIDE:-$FM_HOME/data}"
+SECONDMATES_MD="$DATA/secondmates.md"
+
+"$SCRIPT_DIR/fm-guard.sh" || true
+
+# shellcheck source=bin/fm-ff-lib.sh
+. "$SCRIPT_DIR/fm-ff-lib.sh"
+# shellcheck source=bin/fm-backend.sh
+. "$SCRIPT_DIR/fm-backend.sh"
+# shellcheck source=bin/fm-wake-lib.sh
+. "$SCRIPT_DIR/fm-wake-lib.sh"
+# shellcheck source=bin/fm-config-inherit-lib.sh
+. "$SCRIPT_DIR/fm-config-inherit-lib.sh"
+# shellcheck source=bin/fm-secondmate-nudge-lib.sh
+. "$SCRIPT_DIR/fm-secondmate-nudge-lib.sh"
+
+print_item_report() {
+  local report=$1 item status reason
+  while IFS=$'\t' read -r item status reason; do
+    [ -n "$item" ] || continue
+    if [ -n "$reason" ]; then
+      printf '  %s: %s - %s\n' "$item" "$status" "$reason"
+    else
+      printf '  %s: %s\n' "$item" "$status"
+    fi
+  done < "$report"
+}
+
+records=$(mktemp "${TMPDIR:-/tmp}/fm-config-push-records.XXXXXX" 2>/dev/null) || exit 1
+reports=""
+# shellcheck disable=SC2317,SC2329 # Invoked by trap handlers below.
+cleanup() {
+  local report_file
+  rm -f "$records"
+  for report_file in $reports; do
+    rm -f "$report_file"
+  done
+}
+trap cleanup EXIT
+
+live_secondmate_meta_records "$STATE" "$SECONDMATES_MD" > "$records"
+if [ ! -s "$records" ]; then
+  echo "config-push: no live secondmate homes found"
+  exit 0
+fi
+
+echo "config-push: $FM_HOME -> live secondmate homes"
+
+seen_homes=""
+errors=0
+while IFS='|' read -r id home _window meta; do
+  [ -n "$id" ] || continue
+  if [ -z "$home" ]; then
+    printf 'secondmate %s: skipped - no home= in %s and no registry home\n' "$id" "$meta"
+    continue
+  fi
+  remote_host=$(fm_meta_get "$meta" remote_host)
+  if [ -n "$remote_host" ]; then
+    printf 'secondmate %s (%s:%s):\n' "$id" "$remote_host" "$home"
+    remote_lock=$(fm_remote_inherit_transaction_lock_path "$STATE" "$id" 2>/dev/null || true)
+    if [ -z "$remote_lock" ] || ! fm_lock_acquire_wait "$remote_lock"; then
+      echo "  config-reread: transaction lock failed"
+      errors=1
+      continue
+    fi
+    remote_generation=$(fm_remote_inherit_generation_next "$STATE" "$id" 2>/dev/null || true)
+    if [ -z "$remote_generation" ]; then
+      echo "  config-reread: generation publication failed"
+      errors=1
+      fm_lock_release "$remote_lock" || true
+      continue
+    fi
+    remote_marker=$(fm_secondmate_nudge_marker_path "$STATE" "$id" 2>/dev/null || true)
+    remote_pending=0
+    if [ -f "$remote_marker" ] && [ "$(fm_meta_get "$remote_marker" remote)" = 1 ]; then remote_pending=1; fi
+    if ! fm_secondmate_nudge_write "$STATE" "$id" "$home" "" remote \
+      "$FM_REMOTE_SECOND_MATE_NUDGE_MESSAGE" 1; then
+      echo "  config-reread: retry marker failed"
+      errors=1
+      fm_lock_release "$remote_lock" || true
+      continue
+    fi
+    if remote_out=$(FM_CONFIG_INHERIT_LIVE=1 \
+      "$SCRIPT_DIR/fm-remote-inherit-push.sh" "$id" "$remote_generation" 2>&1); then
+      printf '%s\n' "$remote_out" | sed 's/^/  /'
+      remote_nudge=0
+      if printf '%s\n' "$remote_out" | grep -Eq '^(pushed|removed):'; then remote_nudge=1; fi
+      [ "$remote_pending" -eq 0 ] || remote_nudge=1
+      if [ "$remote_nudge" -eq 1 ]; then
+        if FM_HOME="$FM_HOME" FM_ROOT_OVERRIDE="$FM_ROOT" FM_STATE_OVERRIDE="$STATE" \
+          "$SCRIPT_DIR/fm-send.sh" "fm-$id" "$FM_REMOTE_SECOND_MATE_NUDGE_MESSAGE" >/dev/null 2>&1; then
+          rm -f -- "$remote_marker"
+          echo "  config-reread: sent"
+        else
+          echo "  config-reread: send failed; retry retained"
+          errors=1
+        fi
+      else
+        rm -f -- "$remote_marker"
+      fi
+    else
+      [ -z "$remote_out" ] || printf '%s\n' "$remote_out" | sed 's/^/  /'
+      errors=1
+    fi
+    fm_lock_release "$remote_lock" || true
+    continue
+  fi
+  if ! validate_secondmate_home "$id" "$home"; then
+    printf 'secondmate %s (%s): skipped - unsafe home: %s\n' "$id" "$home" "$VALIDATION_ERROR"
+    continue
+  fi
+  home_real="$VALIDATED_HOME"
+  case " $seen_homes " in
+    *" $home_real "*)
+      printf 'secondmate %s (%s): skipped - already processed for another live meta\n' "$id" "$home_real"
+      continue
+      ;;
+  esac
+  seen_homes="$seen_homes $home_real"
+
+  printf 'secondmate %s (%s):\n' "$id" "$home_real"
+  dirty=$(dirty_status "$home_real" yes || true)
+  if [ -n "$dirty" ]; then
+    echo "  home: dirty working tree - local-material push continuing"
+  fi
+
+  mkdir -p "$home_real/state" || {
+    echo "  config-reread: error - could not create state directory"
+    errors=1
+    continue
+  }
+  home_lock=$(fm_config_inherit_lock_path "$home_real") || {
+    echo "  config-reread: error - could not resolve per-home lock"
+    errors=1
+    continue
+  }
+  fm_lock_acquire_wait "$home_lock" || {
+    echo "  config-reread: error - could not acquire per-home lock"
+    errors=1
+    continue
+  }
+  if fm_config_reread_retry_queue_is_full "$FM_HOME" "$id"; then
+    fm_config_reread_retry_pending "$id" "$home_real" || true
+    if fm_config_reread_retry_queue_is_full "$FM_HOME" "$id"; then
+      echo "  config-reread: error - retry instruction queue is full"
+      errors=1
+      fm_lock_release "$home_lock" || true
+      continue
+    fi
+  fi
+
+  report=$(mktemp "${TMPDIR:-/tmp}/fm-config-push-report.XXXXXX" 2>/dev/null) || {
+    echo "  home: error - could not create report file"
+    errors=1
+    fm_lock_release "$home_lock" || true
+    continue
+  }
+  reports="$reports $report"
+  if FM_CONFIG_INHERIT_REPORT="$report" FM_CONFIG_INHERIT_LIVE=1 \
+    propagate_secondmate_inheritance "$FM_HOME" "$home_real" "$CONFIG" "$DATA"; then
+    :
+  else
+    errors=1
+  fi
+  print_item_report "$report"
+  reread_pending=0
+  if fm_config_reread_has_pending "$home_real" || fm_config_reread_has_staged "$FM_HOME" "$id"; then
+    reread_pending=1
+  fi
+  if reread_out=$(FM_HOME="$FM_HOME" FM_ROOT_OVERRIDE="$FM_ROOT" \
+    FM_STATE_OVERRIDE="$STATE" \
+    fm_config_send_reread_nudge "$id" "$home_real" "$report" 2>&1); then
+    if [ -n "$(fm_config_reread_changed_items "$report")" ] || [ "$reread_pending" -eq 1 ]; then
+      printf '  config-reread: sent\n'
+    fi
+    [ -z "$reread_out" ] || printf '%s\n' "$reread_out"
+  else
+    errors=1
+    if [ -n "$reread_out" ]; then
+      printf '%s\n' "$reread_out"
+    else
+      printf '  config-reread: send failed\n'
+    fi
+  fi
+  fm_lock_release "$home_lock" || true
+done < "$records"
+
+[ "$errors" -eq 0 ] || exit 1
+exit 0

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

@@ -0,0 +1,251 @@
+#!/usr/bin/env bash
+# fm-control-lib.sh - the ONE executable owner of firstmate's agent lifecycle
+# CONTROL-PLANE mechanics.
+#
+# Data plane vs control plane (captain-approved root architecture, 2026-07-13).
+# bin/fm-send.sh is the DATA plane: conversational text for the agent to read,
+# always routing-marked for a kind=secondmate target so the reply comes back
+# through the status path. That marking is exactly right for a message and
+# exactly wrong for a lifecycle command: a marked "/quit" arrives as ordinary
+# chat ("[fm-from-firstmate] /quit") that the agent reasons ABOUT instead of
+# executing. bin/fm-control.sh is the CONTROL plane: allowlisted lifecycle
+# verbs addressed to an exact task id, with the per-harness mechanics owned
+# here rather than improvised per harness in agent prose.
+#
+# This file owns three capability tables plus their pure artifact-path tables
+# and nothing else. It has no side effects, runs no backend command, and reads
+# no state, so it can be sourced by a test as a pure contract:
+#
+#   1. Verb allowlist. There is no arbitrary-text and no generic raw-key entry
+#      point on the control plane; a caller either names an allowlisted verb or
+#      is refused.
+#   2. Per-harness control mechanics: which key interrupts a running turn, how
+#      many times it must be sent, whether the composer needs clearing after
+#      that key, which adapter-owned cancellation acknowledgement is observable,
+#      which command exits the agent, and which task kinds the adapter is
+#      verified to run. These are the empirically verified facts previously
+#      carried only in the harness-adapters skill's per-adapter tables; that
+#      skill now points here so one executable owner holds them, and
+#      bin/fm-send.sh's --key path reads the same table rather than a second
+#      copy of it.
+#   3. Per-backend capability: which named keys a runtime backend can deliver,
+#      and whether the backend has a recovery-grade agent-state classifier
+#      (bin/fm-backend.sh's fm_backend_agent_state) able to PROVE that an agent
+#      stopped. A verb whose postcondition cannot be proven on the recorded
+#      backend is refused rather than performed blind.
+#
+# `resume` is deliberately NOT a verb. It is not deterministic across the
+# verified adapters: codex and grok resume only from a session id printed at
+# exit, opencode resumes the most recent session for the cwd with --continue,
+# and claude, pi, pi-signed, and kimi have no verified pane-resume contract at
+# all. `relaunch` covers the same need deterministically for every adapter,
+# because the brief on disk - not a harness-private session - is the durable
+# instruction.
+
+# The complete control-plane verb allowlist, one per line.
+fm_control_verbs() {
+  cat <<'EOF'
+interrupt
+exit
+relaunch
+EOF
+}
+
+fm_control_verb_allowed() {  # <verb>
+  case "${1-}" in
+    interrupt|exit|relaunch) return 0 ;;
+  esac
+  return 1
+}
+
+# The harnesses whose control mechanics are verified. Mirrors AGENTS.md
+# section 4's verified-adapter list; an unverified adapter is refused rather
+# than guessed at, exactly as a spawn on it would be.
+fm_control_harness_supported() {  # <harness>
+  case "${1-}" in
+    claude|codex|opencode|pi|pi-signed|grok|kimi|cursor|muse) return 0 ;;
+  esac
+  return 1
+}
+
+# The verified adapter a RECORDED harness value belongs to. Every table below
+# is keyed by the exact verified adapter name, but a task launched from a raw
+# command records the command's basename instead (bin/fm-spawn.sh derives
+# harness= that way), which is why the spawn adapters match `claude*`, `muse*`,
+# and friends. This is the one place that prefix rule is stated. `pi` and
+# `pi-signed` are exact because a `pi*` prefix would swallow the signed adapter,
+# and an unrecognized value returns nonzero rather than being guessed into a
+# family.
+fm_control_harness_family() {  # <recorded-harness>
+  case "${1-}" in
+    pi) printf 'pi' ;;
+    pi-signed) printf 'pi-signed' ;;
+    claude*) printf 'claude' ;;
+    codex*) printf 'codex' ;;
+    opencode*) printf 'opencode' ;;
+    grok*) printf 'grok' ;;
+    kimi*) printf 'kimi' ;;
+    cursor*) printf 'cursor' ;;
+    muse*) printf 'muse' ;;
+    *) return 1 ;;
+  esac
+}
+
+# Which task kinds an adapter is verified to run. muse is a crewmate/scout
+# adapter only: it has no primary supervision protocol, and bin/fm-spawn.sh
+# refuses a --secondmate launch on it. The control plane
+# asks this BEFORE it stops anything, so an incompatible relaunch target is
+# refused while the current agent is still running rather than after it has
+# been stopped.
+fm_control_harness_supports_kind() {  # <harness> <kind>
+  local harness=${1-} kind=${2-}
+  fm_control_harness_supported "$harness" || return 1
+  case "$harness" in
+    muse) [ "$kind" != secondmate ] || return 1 ;;
+  esac
+  return 0
+}
+
+# The key that cancels a running turn. Escape for every adapter except grok,
+# whose Esc only moves focus to the scrollback; grok cancels on Ctrl+C.
+fm_control_interrupt_key() {  # <harness>
+  case "${1-}" in
+    claude|codex|opencode|pi|pi-signed|kimi|cursor|muse) printf 'Escape' ;;
+    grok) printf 'C-c' ;;
+    *) return 1 ;;
+  esac
+}
+
+# How many times the interrupt key must be delivered. OpenCode needs a double
+# Escape; every other verified adapter interrupts on a single press.
+fm_control_interrupt_repeat() {  # <harness>
+  case "${1-}" in
+    opencode) printf '2' ;;
+    claude|codex|pi|pi-signed|grok|kimi|cursor|muse) printf '1' ;;
+    *) return 1 ;;
+  esac
+}
+
+# The key that must follow the interrupt key to leave the composer empty, or
+# nothing when the adapter needs none. muse is the one verified adapter that
+# RESTORES the cancelled prompt into its composer as real bright text, so an
+# interrupt is not complete until Ctrl+U has cleared it; leaving it there would
+# make the next submitted line - a steer, or this plane's own exit command -
+# concatenate onto it. cursor was checked for exactly that behaviour and does
+# NOT repollute: after a single Escape its composer shows only the `Add a
+# follow-up` placeholder, so it needs no clear key. Prints the key or nothing;
+# a harness with no verified mechanics returns nonzero, matching the tables
+# above.
+fm_control_interrupt_clear_key() {  # <harness>
+  case "${1-}" in
+    muse) printf 'C-u' ;;
+    claude|codex|opencode|pi|pi-signed|grok|kimi|cursor) ;;
+    *) return 1 ;;
+  esac
+}
+
+fm_control_interrupt_ack_source() {  # <harness>
+  case "${1-}" in
+    muse) printf 'muse-session-terminal' ;;
+    # cursor's transcript DOES type an aborted close, but its write latency
+    # after an interrupt was measured as variable - sometimes seconds, sometimes
+    # not within 20 - so a cancellation claim built on it would be unreliable.
+    # Normal turn completion is prompt, which is what the busy fold depends on.
+    claude|codex|opencode|pi|pi-signed|grok|kimi|cursor) printf 'none' ;;
+    *) return 1 ;;
+  esac
+}
+
+# The command that exits the agent from its own composer.
+fm_control_exit_command() {  # <harness>
+  case "${1-}" in
+    claude|opencode|grok|kimi|cursor|muse) printf '/exit' ;;
+    codex|pi|pi-signed) printf '/quit' ;;
+    *) return 1 ;;
+  esac
+}
+
+# Which named keys a backend adapter can deliver. Every session provider
+# normalizes Enter, Ctrl+C, and the Ctrl+U composer clear; Orca's terminal API
+# exposes only an interrupt and an Enter, so it can deliver neither Escape nor
+# Ctrl+U (bin/backends/orca.sh's fm_backend_orca_send_key).
+fm_control_backend_supports_key() {  # <backend> <key>
+  local backend=${1-} key=${2-}
+  case "$backend" in
+    tmux|herdr|zellij|cmux)
+      case "$key" in Escape|Enter|C-c|C-u) return 0 ;; esac
+      ;;
+    orca)
+      case "$key" in Enter|C-c) return 0 ;; esac
+      ;;
+  esac
+  return 1
+}
+
+# Whether <backend> has a recovery-grade agent-state classifier. Only tmux and
+# herdr implement fm_backend_agent_state; zellij, orca, and cmux report
+# `unverified`, so no reading of theirs can prove an agent stopped. The control
+# plane refuses a stop-proving verb there instead of reporting an unprovable
+# transition as success.
+fm_control_backend_state_verified() {  # <backend>
+  case "${1-}" in
+    tmux|herdr) return 0 ;;
+  esac
+  return 1
+}
+
+# The per-task wiring artifacts a harness leaves behind, so a relaunch that
+# changes harness (or re-arms the same one with a fresh busy generation) can
+# clear the previous incarnation's wiring instead of leaving a stale hook
+# pointing at a retired generation. Prints zero or more absolute paths, one per
+# line: worktree-resident hook files and firstmate-owned state tokens only,
+# never a harness's own managed config.
+fm_control_harness_wiring_paths() {  # <harness> <worktree> <state-dir> <id>
+  local harness=${1-} wt=${2-} state=${3-} id=${4-}
+  [ -n "$wt" ] && [ -n "$state" ] && [ -n "$id" ] || return 1
+  case "$harness" in
+    claude) printf '%s\n' "$wt/.claude/settings.local.json" ;;
+    opencode) printf '%s\n' "$wt/.opencode/plugins/fm-busy-state.js" ;;
+    pi|pi-signed) printf '%s\n' "$state/$id.pi-ext.ts" ;;
+    grok)
+      printf '%s\n' "$wt/.fm-grok-turnend"
+      printf '%s\n' "$state/$id.grok-turnend-token"
+      ;;
+    kimi)
+      printf '%s\n' "$wt/.fm-kimi-turnend"
+      printf '%s\n' "$state/$id.kimi-turnend-token"
+      ;;
+    muse)
+      # muse installs no hook: its busy source is its own session event log,
+      # bound to the pane by these two firstmate-owned sidecars. A relaunch
+      # ONTO muse rewrites them, but a relaunch AWAY from muse must retire them
+      # so no retired incarnation's session binding outlives the agent.
+      printf '%s\n' "$state/$id.muse-session"
+      printf '%s\n' "$state/$id.muse-session-current"
+      ;;
+    cursor) printf '%s\n' "$state/$id.cursor-session" ;;
+  esac
+}
+
+# The firstmate-owned global turn-end registry entry a harness mints per task.
+# grok and kimi are the two adapters whose turn-end hook is global and gated by
+# a private token file; every other adapter's wiring is fully covered by
+# fm_control_harness_wiring_paths. Prints the registry path or nothing.
+fm_control_harness_turnend_token_path() {  # <harness> <state-dir> <id>
+  local harness=${1-} state=${2-} id=${3-}
+  [ -n "$state" ] && [ -n "$id" ] || return 1
+  case "$harness" in
+    grok) printf '%s\n' "$state/$id.grok-turnend-token" ;;
+    kimi) printf '%s\n' "$state/$id.kimi-turnend-token" ;;
+  esac
+}
+
+fm_control_harness_turnend_auth_path() {  # <harness> <token>
+  local harness=${1-} token=${2-}
+  case "$token" in ''|*[!A-Za-z0-9._-]*) return 0 ;; esac
+  case "$harness" in
+    grok) printf '%s\n' "${GROK_HOME:-$HOME/.grok}/hooks/fm-turn-end.d/$token" ;;
+    kimi) printf '%s\n' "$HOME/.kimi-code/fm-turn-end.d/$token" ;;
+    *) return 0 ;;
+  esac
+}