@zerwiz/ymir 0.1.3 → 0.1.5

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

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# Acquire or inspect the per-home firstmate session lock.
+# Writes the harness (agent) process PID found by walking the shell's ancestry,
+# which lives as long as the firstmate session - unlike the transient subshell
+# PID of any one tool call, which is dead moments after it is written.
+# Usage: fm-lock.sh           acquire; exit 1 unless ownership is verified
+#        fm-lock.sh status    print holder and liveness; always exits 0
+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}"
+LOCK="$STATE/.lock"
+mkdir -p "$STATE" 2>/dev/null || {
+  echo "error: cannot create session-lock state directory $STATE; operate read-only until resolved" >&2
+  exit 1
+}
+
+# Harness identity (FM_HARNESS_RE, ancestry walk, holder liveness) is owned by
+# the shared session-lock lib so the Claude Stop auto-arm applies the exact
+# same identity contract.
+# shellcheck source=bin/fm-session-lock-lib.sh
+. "$SCRIPT_DIR/fm-session-lock-lib.sh"
+
+if [ "${1:-}" = "status" ]; then
+  if [ ! -f "$LOCK" ]; then echo "lock: free"; exit 0; fi
+  old=$(cat "$LOCK" 2>/dev/null) || {
+    echo "lock: unreadable"
+    exit 0
+  }
+  if fm_harness_pid_alive "$old"; then echo "lock: held by live harness pid $old"; else echo "lock: stale (pid $old dead or not a harness)"; fi
+  exit 0
+fi
+
+me=$(fm_harness_ancestry_pid) || { echo "error: cannot locate harness process in ancestry" >&2; exit 1; }
+probe=$(mktemp "$STATE/.lock-write.XXXXXX" 2>/dev/null) || {
+  echo "error: cannot write session lock; operate read-only until resolved" >&2
+  exit 1
+}
+rm -f "$probe" 2>/dev/null || {
+  echo "error: cannot clean session-lock publication probe; operate read-only until resolved" >&2
+  exit 1
+}
+# shellcheck source=bin/fm-wake-lib.sh
+. "$SCRIPT_DIR/fm-wake-lib.sh"
+CLAIM_LOCK="$STATE/.lock.acquire"
+CLAIM_LOCK_HELD=0
+release_claim_lock() {
+  if [ "$CLAIM_LOCK_HELD" -eq 1 ]; then
+    fm_lock_release "$CLAIM_LOCK"
+    CLAIM_LOCK_HELD=0
+  fi
+}
+trap release_claim_lock EXIT
+trap 'exit 1' HUP INT TERM
+
+if [ -f "$LOCK" ] && [ ! -L "$LOCK" ]; then
+  old=$(cat "$LOCK" 2>/dev/null || true)
+  if [ "$old" = "$me" ]; then
+    echo "lock acquired: harness pid $me"
+    exit 0
+  fi
+  if fm_harness_pid_alive "$old"; then
+    echo "error: another live firstmate session holds the lock (pid $old); operate read-only until resolved" >&2
+    exit 1
+  fi
+fi
+
+if ! fm_lock_try_acquire "$CLAIM_LOCK"; then
+  sweep_pid=$(sed -n 's/^pid=//p' "$STATE/.startup-network.status" 2>/dev/null | tail -1)
+  if [ -n "${FM_LOCK_HELD_PID:-}" ] && [ "$FM_LOCK_HELD_PID" = "$sweep_pid" ]; then
+    echo "error: the prior session's bounded startup sweep is finishing; operate read-only until it releases the fleet lock" >&2
+    exit 1
+  fi
+  fm_lock_acquire_wait "$CLAIM_LOCK"
+fi
+CLAIM_LOCK_HELD=1
+
+if [ -e "$LOCK" ] || [ -L "$LOCK" ]; then
+  if [ ! -f "$LOCK" ] || [ -L "$LOCK" ]; then
+    echo "error: session lock is not a regular file; operate read-only until resolved" >&2
+    exit 1
+  fi
+  old=$(cat "$LOCK" 2>/dev/null) || {
+    echo "error: session lock is unreadable; operate read-only until resolved" >&2
+    exit 1
+  }
+  if [ "$old" != "$me" ] && fm_harness_pid_alive "$old"; then
+    echo "error: another live firstmate session holds the lock (pid $old); operate read-only until resolved" >&2
+    exit 1
+  fi
+fi
+if ! { printf '%s\n' "$me" > "$LOCK"; } 2>/dev/null; then
+  echo "error: cannot write session lock; operate read-only until resolved" >&2
+  exit 1
+fi
+written=$(cat "$LOCK" 2>/dev/null) || {
+  echo "error: cannot verify session lock ownership; operate read-only until resolved" >&2
+  exit 1
+}
+if [ ! -f "$LOCK" ] || [ -L "$LOCK" ] || [ "$written" != "$me" ]; then
+  echo "error: session lock ownership verification failed; operate read-only until resolved" >&2
+  exit 1
+fi
+release_claim_lock
+echo "lock acquired: harness pid $me"

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# fm-marker-lib.sh - compatibility entry point for from-firstmate routing.
+#
+# bin/fm-operational-input.sh owns current operational-input construction,
+# parsing, marker bytes, and the established from-firstmate compatibility
+# carrier. Existing callers source this path so they do not need a flag-day
+# migration. No side effects on source. set -u / set -e safe.
+
+_FM_MARKER_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=bin/fm-operational-input.sh
+. "$_FM_MARKER_LIB_DIR/fm-operational-input.sh"
+unset _FM_MARKER_LIB_DIR

package/.agents/backend/fm-merge-local.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# Perform the approved local merge for a local-only ship task: fast-forward the
+# project's default branch to the crewmate's fm/<id> branch.
+#
+# This is firstmate's merge gate-action (the captain's merge authority applied
+# locally instead of via a GitHub PR). It is the one sanctioned exception to hard
+# rule #1 "never run state-changing git in projects/", and it is narrow: it only
+# runs for mode=local-only tasks, only after the captain approves (or yolo=on
+# auto-approves), and only as a clean fast-forward - it refuses a diverged branch
+# and tells you to have the crewmate rebase. See AGENTS.md prime directives,
+# project management, and task lifecycle.
+# Usage: fm-merge-local.sh <task-id>
+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}"
+"$FM_ROOT/bin/fm-guard.sh" || true
+# Role partition: landing local-only work is MAIN-owned; the Pi supervision
+# branch reports readiness and never lands (contract: bin/fm-lease-lib.sh;
+# no-op in homes without a branch actor).
+# shellcheck source=bin/fm-lease-lib.sh
+. "$SCRIPT_DIR/fm-lease-lib.sh"
+fm_lease_forbid_branch "local-only landing (fm-merge-local)"
+ID=${1:?usage: fm-merge-local.sh <task-id>}
+META="$STATE/$ID.meta"
+[ -f "$META" ] || { echo "error: no meta for task $ID at $META" >&2; exit 1; }
+
+PROJ=$(grep '^project=' "$META" | cut -d= -f2-)
+MODE=$(grep '^mode=' "$META" | cut -d= -f2- || true)
+[ "$MODE" = local-only ] || { echo "error: task $ID is mode=$MODE, not local-only; merge PR tasks with bin/fm-pr-merge.sh <id> <PR url> after approval" >&2; exit 1; }
+
+default_branch() {
+  local ref branch
+  ref=$(git -C "$PROJ" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null || true)
+  if [ -n "$ref" ]; then
+    echo "${ref#origin/}"
+    return 0
+  fi
+  for branch in main master; do
+    if git -C "$PROJ" show-ref --verify --quiet "refs/heads/$branch"; then
+      echo "$branch"
+      return 0
+    fi
+  done
+  return 1
+}
+
+BRANCH="fm/$ID"
+git -C "$PROJ" rev-parse --verify --quiet "refs/heads/$BRANCH" >/dev/null || { echo "error: branch $BRANCH does not exist in $PROJ" >&2; exit 1; }
+
+DEFAULT=$(default_branch) || { echo "error: cannot determine default branch for $PROJ; expected origin/HEAD, main, or master" >&2; exit 1; }
+
+# The project's main checkout must be on its default branch and clean, so the
+# fast-forward lands predictably (firstmate never writes here otherwise).
+cur=$(git -C "$PROJ" symbolic-ref --short HEAD 2>/dev/null || echo "")
+[ "$cur" = "$DEFAULT" ] || { echo "error: $PROJ is on '$cur', expected default branch '$DEFAULT'; cannot merge safely" >&2; exit 1; }
+if [ -n "$(git -C "$PROJ" status --porcelain 2>/dev/null | head -1)" ]; then
+  echo "error: $PROJ has a dirty working tree; refusing to merge into it" >&2
+  exit 1
+fi
+
+# Clean fast-forward only: DEFAULT must be an ancestor of BRANCH.
+if ! git -C "$PROJ" merge-base --is-ancestor "$DEFAULT" "$BRANCH"; then
+  echo "REFUSED: $BRANCH is not a fast-forward of $DEFAULT (it has diverged)." >&2
+  echo "Have the crewmate rebase $BRANCH onto $DEFAULT, then retry." >&2
+  exit 1
+fi
+
+before=$(git -C "$PROJ" rev-parse --short "$DEFAULT")
+git -C "$PROJ" merge --ff-only "$BRANCH" >/dev/null
+after=$(git -C "$PROJ" rev-parse --short "$DEFAULT")
+echo "merged $BRANCH into local $DEFAULT ($before -> $after) in $PROJ"

package/.agents/backend/fm-merge-outcome-lib.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# Shared durable, supervisor-facing outcome publication for a confirmed merge.
+#
+# Both a merge performed by this home and a merge detected by its existing poll
+# use this operation, so neither outcome depends on an agent remembering it.
+# This operation publishes the poll's local actionable row; the watcher
+# immediately delivers that row as observation handling, not a second outcome
+# path.
+#
+# The destination is the home's role, never the caller's choice:
+#   - a secondmate home reports upward to its parent on the same reply channel
+#     bin/fm-inactive-reconcile.sh's report_to_parent already uses, in the same
+#     "<state> [key=<slug>]: <note>" shape the charter contract defines;
+#   - a main home reports to the captain through the durable wake queue.
+# A poll observed in a secondmate home also receives a local durable wake after
+# the upward write, so the mate can handle its own poll observation.
+# No new state file and no new transport are involved.
+#
+# Normal operation deduplicates the task's latest canonical PR identity through
+# the merge-notification marker owned by bin/fm-pr-lib.sh. Main-home wake keys
+# also include that PR identity so distinct PRs for a reused task remain
+# distinct in queue presentation. The outcome is published before the marker
+# is committed, so a failed commit stays eligible for at-least-once retry and
+# may rarely duplicate rather than leave a merge silent.
+#
+# Sourced by bin/fm-pr-merge.sh, bin/fm-watch.sh, and tests. No side effects on
+# source beyond its sourced libraries.
+
+_FM_MERGE_OUTCOME_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=bin/fm-pr-lib.sh
+. "$_FM_MERGE_OUTCOME_LIB_DIR/fm-pr-lib.sh"
+# shellcheck source=bin/fm-secondmate-parent-lib.sh
+. "$_FM_MERGE_OUTCOME_LIB_DIR/fm-secondmate-parent-lib.sh"
+
+# The secondmate identity of the home reporting, or non-zero when this home is
+# a main home (1) or carries an unusable identity marker (2). Mirrors
+# bin/fm-inactive-reconcile.sh's home_secondmate_id, which owns the same
+# marker's contract.
+fm_merge_outcome_home_id() {  # <home>
+  local home=$1 marker id
+  marker="$home/.fm-secondmate-home"
+  if [ ! -e "$marker" ] && [ ! -L "$marker" ]; then
+    return 1
+  fi
+  [ -f "$marker" ] && [ ! -L "$marker" ] || return 2
+  [ "$(wc -c < "$marker")" -eq "$(LC_ALL=C tr -d '\0' < "$marker" | wc -c)" ] || return 2
+  id=$(cat "$marker" 2>/dev/null) || return 2
+  fm_pr_task_id_valid "$id" || return 2
+  printf '%s\n' "$id"
+}
+
+# Append <line> to <path> unless that exact line is already there, so a repeat
+# report of the same merge cannot duplicate it.
+fm_merge_outcome_append_once() {  # <path> <line>
+  local path=$1 line=$2
+  [ ! -L "$path" ] || return 1
+  mkdir -p "$(dirname "$path")" || return 1
+  if grep -Fqx -- "$line" "$path" 2>/dev/null; then
+    return 0
+  fi
+  printf '%s\n' "$line" >> "$path"
+}
+
+# shellcheck disable=SC2034 # Public result consumed by sourcing callers.
+FM_MERGE_OUTCOME_ALREADY_RECORDED=false
+
+# fm_merge_outcome_report <home> <state> <task-id> <pr-url> <origin>
+#
+# <origin> says who observed the merge, because that decides whether the
+# existing poll path also needs a local wake:
+#   self - this home performed the merge.
+#   poll - this home's merge poll detected the merge, so the canonical outcome
+#          also wakes this home after any upward hop needed by a secondmate.
+#
+# Returns 0 when the outcome is recorded (or already was), 2 on an invalid
+# request, 3 when this home's own role or parent binding cannot be read well
+# enough to say where the outcome belongs, and 1 on any other failure to
+# record. A caller that has already merged must report a non-zero return rather
+# than treat it as success: the merge landed and the record did not.
+fm_merge_outcome_report() {  # <home> <state> <task-id> <pr-url> <origin>
+  local home=$1 state=$2 id=$3 url=$4 origin=$5
+  local self='' self_rc=0 destination='' line lock status=0
+  local provider host path number
+  # shellcheck disable=SC2034 # Sourced wake helpers consume these scoped globals.
+  local STATE FM_WAKE_QUEUE FM_WAKE_QUEUE_LOCK
+  FM_MERGE_OUTCOME_ALREADY_RECORDED=false
+  case "$origin" in self|poll) ;; *) return 2 ;; esac
+  fm_pr_task_id_valid "$id" || return 2
+  fm_pr_url_parse "$url" || return 2
+  provider=$FM_PR_PROVIDER
+  host=$FM_PR_HOST
+  path=$FM_PR_PATH
+  number=$FM_PR_NUMBER
+  [ -d "$state" ] && [ ! -L "$state" ] || return 1
+
+  if self=$(fm_merge_outcome_home_id "$home"); then
+    fm_secondmate_parent_record_parse "$home/.fm-secondmate-parent" || return 3
+    case "$FM_SECONDMATE_PARENT_ROUTE" in
+      local)
+        [ -n "$FM_SECONDMATE_PARENT_HOME" ] || return 3
+        destination="$FM_SECONDMATE_PARENT_HOME/state/$self.status"
+        ;;
+      remote) destination="$state/parent-replies.status" ;;
+      *) return 3 ;;
+    esac
+    line="done [key=merged-$id]: merged $id $FM_PR_URL"
+  else
+    self_rc=$?
+    [ "$self_rc" -eq 1 ] || return 3
+  fi
+
+  STATE=$state
+  # shellcheck source=bin/fm-wake-lib.sh
+  . "$_FM_MERGE_OUTCOME_LIB_DIR/fm-wake-lib.sh"
+  lock="$state/$id.pr-poll-merge-notified.lock"
+  fm_lock_acquire_wait "$lock" || return 1
+  if fm_pr_poll_merge_already_notified "$state" "$id" \
+    "$provider" "$host" "$path" "$number"; then
+    # shellcheck disable=SC2034 # Public result consumed by sourcing callers.
+    FM_MERGE_OUTCOME_ALREADY_RECORDED=true
+    fm_lock_release "$lock"
+    return 0
+  fi
+
+  if [ -n "$destination" ]; then
+    fm_merge_outcome_append_once "$destination" "$line" || status=1
+  fi
+  if [ "$status" -eq 0 ] && { [ "$origin" = poll ] || [ -z "$destination" ]; }; then
+    fm_wake_append check "merged-$id-$FM_PR_URL" \
+      "check: merge landed: $id $FM_PR_URL" || status=1
+  fi
+  if [ "$status" -eq 0 ]; then
+    fm_pr_poll_merge_mark_notified "$state" "$id" \
+      "$provider" "$host" "$path" "$number" || status=1
+  fi
+  fm_lock_release "$lock"
+  return "$status"
+}

package/.agents/backend/fm-nm-run-lib.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# Shared no-mistakes axi run attribution primitives.
+#
+# ONE owner for the no-mistakes run-attribution primitives used by
+# fm-crew-state.sh (read-only current-state reporting) and fm-teardown.sh
+# (pre-teardown run abort, see its "Fix 1" header comment). Teardown uses only
+# strict branch-and-head identity; crew-state additionally permits the active
+# pipeline-owned exemption defined below. Getting this wrong in either
+# direction is unsafe: a false negative hides a genuinely parked run, and a
+# false positive lets teardown act on a run it does not own.
+#
+# Bounded call to `no-mistakes "$@"` in dir $1, timeout $2 seconds. The bounded
+# form preserves stdout, stderr, and exit status; the checked form discards
+# stderr, while fm_nm_run keeps the fail-open query contract for read-only callers.
+fm_nm_run_bounded() {  # <dir> <timeout_secs> <args...>
+  local dir=$1 timeout_secs=$2 have_timeout=none
+  shift 2
+  if command -v timeout >/dev/null 2>&1; then have_timeout=timeout
+  elif command -v gtimeout >/dev/null 2>&1; then have_timeout=gtimeout
+  elif command -v perl >/dev/null 2>&1; then have_timeout=perl
+  fi
+  case "$have_timeout" in
+    timeout)  ( cd "$dir" && timeout "$timeout_secs" no-mistakes "$@" ) ;;
+    gtimeout) ( cd "$dir" && gtimeout "$timeout_secs" no-mistakes "$@" ) ;;
+    perl)     ( cd "$dir" && perl -e 'my $t = shift; my $pid = fork; die "fork failed" unless defined $pid; if (!$pid) { setpgrp(0, 0); exec @ARGV } local $SIG{ALRM} = sub { kill "TERM", -$pid; select undef, undef, undef, 0.2; kill "KILL", -$pid; exit 124 }; alarm $t; waitpid $pid, 0; exit($? >> 8)' "$timeout_secs" no-mistakes "$@" ) ;;
+    *)        return 1 ;;
+  esac
+}
+
+fm_nm_run_checked() {  # <dir> <timeout_secs> <args...>
+  fm_nm_run_bounded "$@" 2>/dev/null
+}
+
+fm_nm_run() {  # <dir> <timeout_secs> <args...>
+  fm_nm_run_checked "$@" || true
+}
+
+fm_nm_trim() {
+  local s=${1:-}
+  s="${s#"${s%%[![:space:]]*}"}"
+  s="${s%"${s##*[![:space:]]}"}"
+  printf '%s' "$s"
+}
+
+fm_nm_strip_quotes() {
+  local s
+  s=$(fm_nm_trim "${1:-}")
+  case "$s" in
+    \"*\") s=${s#\"}; s=${s%\"} ;;
+  esac
+  fm_nm_trim "$s"
+}
+
+# Scalar value of a TOON key in captured `axi status` output $1.
+fm_nm_field() {  # <toon-output> <key>
+  printf '%s\n' "$1" | sed -n "s/^[[:space:]]*$2:[[:space:]]*\(.*\)/\1/p" | head -1
+}
+
+# 0 if run head $2 matches worktree $1's code identity, per the same rule
+# everywhere this attribution is needed:
+#   - missing/empty head: cannot bind; reject
+#   - equal commits (short or full SHA): match
+#   - worktree HEAD is an ancestor of run head: match (pipeline fix commits on
+#     the same history advanced the run tip past local HEAD)
+#   - run head is a strict ancestor of worktree HEAD, or diverged: no match
+#     (local work advanced outside the run, or the branch tip was rewritten)
+# fm_nm_run_is_pipeline_owned_active below carries the one exemption: a live
+# run whose pipeline currently owns the branch binds without head equality.
+fm_nm_head_matches_worktree() {  # <worktree> <run_head>
+  local wt=$1 run_head=$2 local_full run_full
+  [ -n "$run_head" ] || return 1
+  local_full=$(git -C "$wt" rev-parse HEAD 2>/dev/null) || return 1
+  run_full=$(git -C "$wt" rev-parse --verify "${run_head}^{commit}" 2>/dev/null) || return 1
+  [ "$run_full" = "$local_full" ] && return 0
+  git -C "$wt" merge-base --is-ancestor "$local_full" "$run_full" 2>/dev/null
+}
+
+# 0 if head $2 resolves to a commit object in worktree $1 at all. This
+# distinguishes a PROVEN mismatch (resolvable but not current: a historical or
+# diverged head fm_nm_head_matches_worktree correctly rejects) from UNKNOWN
+# attribution (unresolvable: e.g. a pipeline-owned lane head that never
+# reached this worktree). A caller scanning run rows newest-first must stop on
+# unknown attribution rather than surface an older, superseded run.
+fm_nm_head_resolvable() {  # <worktree> <head>
+  [ -n "$2" ] || return 1
+  git -C "$1" rev-parse --verify --quiet "$2^{commit}" >/dev/null 2>&1
+}
+
+# branch_sync.state from captured `axi status` TOON $1: the scalar directly
+# under the top-level `branch_sync:` block. The first `state:` inside the
+# block is the direct child (the nested local/pipeline/target/remote
+# sub-blocks carry no `state:` key). Empty when the block is absent: no run
+# on the current branch, another branch's run, or a CLI without branch sync.
+fm_nm_branch_sync_state() {  # <toon-output>
+  local s
+  s=$(printf '%s\n' "$1" \
+    | sed -n '/^[[:space:]]*branch_sync:[[:space:]]*$/,/^[^[:space:]][^:]*:/s/^[[:space:]]\{1,\}state:[[:space:]]*\(.*\)/\1/p' \
+    | head -1)
+  fm_nm_strip_quotes "$s"
+}
+
+# 0 if the run in captured `axi status` TOON $1 is still in flight: no
+# terminal outcome and no terminal status.
+fm_nm_run_is_active() {  # <toon-output>
+  local status outcome
+  status=$(fm_nm_strip_quotes "$(fm_nm_field "$1" status)")
+  outcome=$(fm_nm_strip_quotes "$(fm_nm_field "$1" outcome)")
+  [ -z "$outcome" ] || return 1
+  case "$status" in completed|failed|cancelled) return 1 ;; esac
+}
+
+# The one exemption to the head rule above: while the pipeline OWNS the branch
+# (branch_sync.state=pipeline_owned), the daemon's own branch attribution IS
+# the attribution for an ACTIVE run, and
+# head equality must not be required - the pipeline's lane head is routinely
+# not a git object in the task worktree (rebase and fix commits that were
+# never pushed back), so the head rule rejects exactly the run that is most
+# current. The exemption never applies to a terminal run: a terminal run has
+# released the branch, and binding one by branch name alone is the historical
+# reused-branch misattribution the head rule exists to prevent.
+fm_nm_run_is_pipeline_owned_active() {  # <toon-output>
+  [ "$(fm_nm_branch_sync_state "$1")" = pipeline_owned ] || return 1
+  fm_nm_run_is_active "$1"
+}

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

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# Execute one tracked Firstmate command in a configured remote secondmate home.
+#
+# Usage:
+#   fm-on.sh [--stdin] <secondmate-id|unambiguous-ssh-alias> <fm-command> [args...]
+#
+# Routes come only from remote records in data/secondmates.md. A record names an
+# SSH config alias, remote Firstmate code root, and remote FM_HOME. A host alias
+# may be used directly only when exactly one record selects it; an ambiguous
+# alias is refused. The command must be a genuine executable in this checkout's
+# bin/fm-*.sh namespace. No per-command table exists.
+#
+# argv is encoded as one NUL-delimited stream and passed through the fixed
+# fm-remote-entrypoint.sh. The remote command's stdin is /dev/null by default,
+# because remote staging captures stdin to EOF and an open caller stream would
+# block staging indefinitely; a payload caller passes --stdin to forward its
+# own stream as the job's bounded input. stdout and stderr remain separate, and
+# ssh's exit status is returned unchanged. OpenSSH never receives an auto-retry
+# instruction here. Exit 255 therefore means unavailable transport or unknown
+# remote completion and must be reconciled by the semantic caller, never
+# blindly repeated by this layer.
+#
+# The SSH alias keeps normal public-key and strict host-key policy in ~/.ssh.
+# This command explicitly disables agent forwarding, forwarding setup, and
+# configured SendEnv patterns. The remote entrypoint executes the selected
+# command under an empty environment with only its fixed runtime values.
+#
+# ServerAliveInterval/ServerAliveCountMax arm dead-peer detection so a vanished
+# peer (a reboot, a dropped link) becomes a bounded ssh failure (exit 255)
+# instead of an indefinite hang on a half-open TCP connection. The remote
+# sshd answers keepalive probes independently of whatever the remote command
+# is doing, so a legitimately long-but-alive remote command is never falsely
+# killed. FM_SSH_ALIVE_INTERVAL and FM_SSH_ALIVE_COUNT_MAX override the
+# defaults; the worst-case detection window is roughly interval * count.
+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}}"
+DATA="${FM_DATA_OVERRIDE:-$FM_HOME/data}"
+REG="$DATA/secondmates.md"
+PROTOCOL=1
+
+# shellcheck source=bin/fm-secondmate-registry-lib.sh
+. "$SCRIPT_DIR/fm-secondmate-registry-lib.sh"
+
+die() { printf 'error: %s\n' "$1" >&2; exit 1; }
+usage() { sed -n '2,25p' "$0" | sed 's/^# \{0,1\}//'; exit 2; }
+
+encode_base64() {
+  base64 | tr -d '\n'
+}
+
+STDIN_MODE=closed
+if [ "${1:-}" = --stdin ]; then
+  STDIN_MODE=caller
+  shift
+fi
+[ "$#" -ge 2 ] || usage
+ROUTE=$1
+COMMAND=$2
+shift 2
+
+case "$ROUTE" in ''|-*|*[!A-Za-z0-9._-]*) die "remote route must be a safe secondmate id or SSH alias: $ROUTE" ;; esac
+case "$COMMAND" in
+  fm-*.sh) ;;
+  *) die "remote command must be a basename in the fm-*.sh namespace: $COMMAND" ;;
+esac
+case "$COMMAND" in */*|*..*) die "remote command must not contain a path or traversal: $COMMAND" ;; esac
+LOCAL_COMMAND="$FM_ROOT/bin/$COMMAND"
+[ -f "$LOCAL_COMMAND" ] && [ ! -L "$LOCAL_COMMAND" ] && [ -x "$LOCAL_COMMAND" ] \
+  || die "remote command is not a genuine tracked executable in this Firstmate checkout: $COMMAND"
+git -C "$FM_ROOT" ls-files --error-unmatch "bin/$COMMAND" >/dev/null 2>&1 \
+  || die "remote command is not tracked by this Firstmate checkout: $COMMAND"
+[ -f "$REG" ] && [ ! -L "$REG" ] || die "no safe secondmate registry at $REG"
+
+MATCHES=0
+HOST=
+ROOT=
+HOME_PATH=
+while IFS= read -r line || [ -n "$line" ]; do
+  case "$line" in '- '*) ;; *) continue ;; esac
+  secondmate_registry_parse_line "$line" || die "malformed secondmate registry entry: $line"
+  [ "$SECONDMATE_REGISTRY_REMOTE" -eq 1 ] || continue
+  if [ "$SECONDMATE_REGISTRY_ID" = "$ROUTE" ] || [ "$SECONDMATE_REGISTRY_HOST" = "$ROUTE" ]; then
+    MATCHES=$((MATCHES + 1))
+    HOST=$SECONDMATE_REGISTRY_HOST
+    ROOT=$SECONDMATE_REGISTRY_ROOT
+    HOME_PATH=$SECONDMATE_REGISTRY_HOME
+  fi
+done < "$REG"
+[ "$MATCHES" -gt 0 ] || die "no remote secondmate or SSH alias matches '$ROUTE'"
+[ "$MATCHES" -eq 1 ] || die "remote route '$ROUTE' is ambiguous across $MATCHES configured secondmates; use a secondmate id"
+case "$HOST" in ''|-*|*[!A-Za-z0-9._-]*) die "configured SSH alias is unsafe: $HOST" ;; esac
+case "$ROOT" in /*) ;; *) die "configured remote root is not absolute: $ROOT" ;; esac
+case "$HOME_PATH" in /*) ;; *) die "configured remote home is not absolute: $HOME_PATH" ;; esac
+case "$ROOT$HOME_PATH" in *$'\n'*|*$'\r'*|*$'\t'*) die "configured remote root or home contains control characters" ;; esac
+for configured_path in "$ROOT" "$HOME_PATH"; do
+  case "/$configured_path/" in */../*|*/./*) die "configured remote root or home contains traversal components" ;; esac
+  case "$configured_path" in *'//'*) die "configured remote root or home contains an empty path component" ;; esac
+done
+
+ROOT_B64=$(printf '%s' "$ROOT" | encode_base64)
+HOME_B64=$(printf '%s' "$HOME_PATH" | encode_base64)
+ARGV_B64=$(printf '%s\0' "$COMMAND" "$@" | encode_base64)
+SSH_BIN=${FM_SSH_BIN:-ssh}
+ALIVE_INTERVAL=${FM_SSH_ALIVE_INTERVAL:-15}
+ALIVE_COUNT_MAX=${FM_SSH_ALIVE_COUNT_MAX:-3}
+case "$ALIVE_INTERVAL" in ''|*[!0-9]*) die "FM_SSH_ALIVE_INTERVAL must be a positive integer: $ALIVE_INTERVAL" ;; esac
+case "$ALIVE_COUNT_MAX" in ''|*[!0-9]*) die "FM_SSH_ALIVE_COUNT_MAX must be a positive integer: $ALIVE_COUNT_MAX" ;; esac
+[ "$ALIVE_INTERVAL" -gt 0 ] || die "FM_SSH_ALIVE_INTERVAL must be a positive integer: $ALIVE_INTERVAL"
+[ "$ALIVE_COUNT_MAX" -gt 0 ] || die "FM_SSH_ALIVE_COUNT_MAX must be a positive integer: $ALIVE_COUNT_MAX"
+
+SSH_ARGS=(
+  -o ForwardAgent=no
+  -o ClearAllForwardings=yes
+  -o 'SendEnv=-*'
+  -o "ServerAliveInterval=$ALIVE_INTERVAL"
+  -o "ServerAliveCountMax=$ALIVE_COUNT_MAX"
+  -- "$HOST" fm-remote-entrypoint.sh "$PROTOCOL" "$ROOT_B64" "$HOME_B64" "$ARGV_B64"
+)
+if [ "$STDIN_MODE" = caller ]; then
+  exec "$SSH_BIN" "${SSH_ARGS[@]}"
+fi
+exec "$SSH_BIN" "${SSH_ARGS[@]}" < /dev/null