@zerwiz/ymir 0.1.3 → 0.1.5

package/.agents/backend/fm-remote-readiness-lib.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# fm-remote-readiness-lib.sh - the remote second-mate readiness gate sequence.
+#
+# Source this file and call:
+#   fm_remote_readiness_ensure <bin-dir> <secondmate-id>
+#
+# It runs bin/fm-remote-doctor.sh on that route's configured host, and when the
+# read-only run reports any gap it runs the doctor again with --fix and then a
+# third read-only time. That last read-only run is the verdict, so a repair is
+# never trusted on its own word. bin/fm-remote-doctor.sh remains the single
+# owner of every check, every repair, and every message; nothing here restates
+# them.
+#
+# Returns 0 when the host is ready, 1 when a gap remains, and 255 when SSH could
+# not complete. 255 means unknown remote completion, so a caller preserves its
+# route and reconciles on the same host instead of treating it as a refusal.
+# FM_REMOTE_READINESS_OUT always holds the output of the last run, which carries
+# the check lines, the remaining human: gaps, and their exact operator actions.
+
+# Consumed by the sourcing caller, so every assignment reads as unused here.
+# shellcheck disable=SC2034
+FM_REMOTE_READINESS_OUT=
+
+fm_remote_readiness_ensure() { # <bin-dir> <secondmate-id>
+  local bin_dir=$1 id=$2 out rc
+
+  out=$("$bin_dir/fm-on.sh" "$id" fm-remote-doctor.sh < /dev/null 2>&1)
+  rc=$?
+  FM_REMOTE_READINESS_OUT=$out
+  [ "$rc" -ne 0 ] || return 0
+  [ "$rc" -ne 255 ] || return 255
+
+  out=$("$bin_dir/fm-on.sh" "$id" fm-remote-doctor.sh --fix < /dev/null 2>&1)
+  rc=$?
+  FM_REMOTE_READINESS_OUT=$out
+  [ "$rc" -ne 255 ] || return 255
+
+  out=$("$bin_dir/fm-on.sh" "$id" fm-remote-doctor.sh < /dev/null 2>&1)
+  rc=$?
+  FM_REMOTE_READINESS_OUT=$out
+  [ "$rc" -ne 255 ] || return 255
+  [ "$rc" -eq 0 ] || return 1
+  return 0
+}

package/.agents/backend/fm-remote-secondmate-control.sh

@@ -0,0 +1,340 @@
+#!/usr/bin/env bash
+# Host-local lifecycle control for the remote secondmate home selected by fm-on.
+#
+# Usage:
+#   fm-remote-secondmate-control.sh launch <id> <harness> <model|-> <effort|-> herdr [traceparent]
+#   fm-remote-secondmate-control.sh state <id>
+#   fm-remote-secondmate-control.sh route <id>
+#   fm-remote-secondmate-control.sh send <id> <message> [fire-and-forget]
+#   fm-remote-secondmate-control.sh key <id> <key>
+#   fm-remote-secondmate-control.sh capture <id> [lines]
+#   fm-remote-secondmate-control.sh observe <id>
+#   fm-remote-secondmate-control.sh sync <id>
+#   fm-remote-secondmate-control.sh update <id>
+#   fm-remote-secondmate-control.sh retire <id> [--force]
+#
+# Remote placement ends here, but the second-mate agent always runs on the
+# Herdr backend in the dedicated fm-remote session, so launch refuses any other
+# selection rather than reading this home's config/backend. The interactive
+# default session remains for the user's work.
+# fm-spawn/fm-send/fm-teardown keep owning the local endpoint mechanics.
+# The home's own workers keep their ordinary backend selection.
+# bin/fm-remote-doctor.sh owns that host's readiness for Herdr.
+# docs/remote-secondmates.md owns why.
+# A private parent-route state directory stores only the remote secondmate
+# agent's endpoint record; the home's own
+# state/*.meta remains reserved for workers the secondmate supervises.
+# Retirement closes only this secondmate's panes or workspace and never
+# stops fm-remote or removes a sibling secondmate's workspace or panes.
+#
+# The optional launch traceparent is the per-task W3C trace-context carrier the
+# PARENT home resolved for this secondmate; this host only delivers it to the
+# pane, and fm-spawn validates it (bin/fm-trace-context-lib.sh). Omitting it is
+# the default-off path. print_route echoes the carrier the endpoint actually
+# holds, including for an already-alive endpoint that was not relaunched, so the
+# parent records the identity the agent really received rather than an intent.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+TARGET_HOME=${FM_HOME:?FM_HOME is required}
+CONTROL_STATE="$TARGET_HOME/state/parent-route"
+CONTROL_DATA="$TARGET_HOME/data/.parent-route"
+REMOTE_HERDR_SESSION=fm-remote
+
+# shellcheck source=bin/fm-backend.sh
+. "$SCRIPT_DIR/fm-backend.sh"
+# shellcheck source=bin/fm-pending-reply-lib.sh
+. "$SCRIPT_DIR/fm-pending-reply-lib.sh"
+# shellcheck source=bin/fm-task-inbox-lib.sh
+. "$SCRIPT_DIR/fm-task-inbox-lib.sh"
+
+die() { printf 'error: %s\n' "$1" >&2; exit 1; }
+usage() { sed -n '2,23p' "$0" | sed 's/^# \{0,1\}//'; exit 2; }
+validate_id() { case "$1" in ''|*[!A-Za-z0-9._-]*) die "invalid secondmate id: $1" ;; esac; }
+
+validate_home() { # <id> [allow-absent]
+  local id=$1 allow_absent=${2:-no} marker
+  if [ ! -e "$TARGET_HOME" ] && [ ! -L "$TARGET_HOME" ] && [ "$allow_absent" = yes ]; then return 2; fi
+  [ -d "$TARGET_HOME" ] && [ ! -L "$TARGET_HOME" ] || die "remote secondmate home is unavailable or unsafe"
+  [ -f "$TARGET_HOME/.fm-secondmate-home" ] && [ ! -L "$TARGET_HOME/.fm-secondmate-home" ] \
+    || die "remote home is not a seeded secondmate home"
+  marker=$(cat "$TARGET_HOME/.fm-secondmate-home")
+  [ "$marker" = "$id" ] || die "remote home belongs to $marker, not $id"
+  [ -f "$TARGET_HOME/AGENTS.md" ] && [ -d "$TARGET_HOME/bin" ] || die "remote home is not a Firstmate checkout"
+}
+
+meta_path() { printf '%s/%s.meta\n' "$CONTROL_STATE" "$1"; }
+
+remote_endpoint_load() {
+  local id=$1 herdr_session
+  REMOTE_ENDPOINT_ERROR=
+  REMOTE_ENDPOINT_META=$(meta_path "$id")
+  if ! fm_backend_validate_task_endpoint "$REMOTE_ENDPOINT_META" "$id" 2>/dev/null; then
+    REMOTE_ENDPOINT_ERROR="remote secondmate $id endpoint metadata is invalid; refusing access until it is explicitly migrated"
+    return 1
+  fi
+  REMOTE_ENDPOINT_BACKEND=$FM_BACKEND_VALIDATED_BACKEND
+  REMOTE_ENDPOINT_TARGET=$FM_BACKEND_VALIDATED_TARGET
+  if [ "$REMOTE_ENDPOINT_BACKEND" != herdr ]; then
+    REMOTE_ENDPOINT_ERROR="remote secondmate $id endpoint is recorded on backend '$REMOTE_ENDPOINT_BACKEND', expected 'herdr'; refusing access until it is explicitly migrated"
+    return 1
+  fi
+  herdr_session=$(fm_backend_meta_exact_value "$REMOTE_ENDPOINT_META" herdr_session 2>/dev/null || true)
+  if [ "$herdr_session" != "$REMOTE_HERDR_SESSION" ]; then
+    REMOTE_ENDPOINT_ERROR="remote secondmate $id endpoint is recorded in Herdr session '${herdr_session:-missing}', expected '$REMOTE_HERDR_SESSION'; refusing access until it is explicitly migrated"
+    return 1
+  fi
+  case "$REMOTE_ENDPOINT_TARGET" in
+    "$REMOTE_HERDR_SESSION":?*) ;;
+    *)
+      REMOTE_ENDPOINT_ERROR="remote secondmate $id endpoint target '$REMOTE_ENDPOINT_TARGET' is outside Herdr session '$REMOTE_HERDR_SESSION'; refusing access until it is explicitly migrated"
+      return 1
+      ;;
+  esac
+}
+
+remote_endpoint_require() {
+  remote_endpoint_load "$1" || die "$REMOTE_ENDPOINT_ERROR"
+}
+
+state_value() { # <id>; prints recovery-grade state
+  local id=$1 meta
+  meta=$(meta_path "$id")
+  [ -f "$meta" ] && [ ! -L "$meta" ] || { printf 'missing\n'; return 0; }
+  if ! remote_endpoint_load "$id"; then
+    printf 'error: %s\n' "$REMOTE_ENDPOINT_ERROR" >&2
+    printf 'unverified\n'
+    return 0
+  fi
+  fm_backend_agent_state "$REMOTE_ENDPOINT_BACKEND" "$REMOTE_ENDPOINT_TARGET" 2>/dev/null || printf 'unreadable\n'
+}
+
+print_route() { # <id>
+  local id=$1 harness traceparent
+  remote_endpoint_require "$id"
+  harness=$(fm_meta_get "$REMOTE_ENDPOINT_META" harness)
+  traceparent=$(fm_meta_get "$REMOTE_ENDPOINT_META" traceparent)
+  printf 'schema=fm-remote-secondmate-control.v1\n'
+  printf 'backend=%s\n' "$REMOTE_ENDPOINT_BACKEND"
+  printf 'target=%s\n' "$REMOTE_ENDPOINT_TARGET"
+  printf 'herdr_session=%s\n' "$REMOTE_HERDR_SESSION"
+  printf 'harness=%s\n' "$harness"
+  [ -z "$traceparent" ] || printf 'traceparent=%s\n' "$traceparent"
+}
+
+cmd_route() {
+  local id=$1 meta
+  validate_id "$id"
+  validate_home "$id"
+  meta=$(meta_path "$id")
+  if [ ! -f "$meta" ] || [ -L "$meta" ]; then
+    die "remote secondmate has no endpoint metadata"
+  fi
+  print_route "$id"
+}
+
+cmd_launch() {
+  local id=$1 harness=$2 model=$3 effort=$4 selected_backend=$5 traceparent=${6:-}
+  local current meta out herdr_session
+
+  validate_id "$id"
+  validate_home "$id"
+  case "$harness" in
+    claude|codex|opencode|pi|pi-signed|grok|kimi|cursor) ;;
+    *) die "unverified remote secondmate harness: $harness" ;;
+  esac
+  case "$effort" in -|low|medium|high|xhigh|max) ;; *) die "invalid remote secondmate effort: $effort" ;; esac
+  # Herdr is required on this host, not merely preferred: its server belongs to
+  # the GUI login session, so the endpoint survives every SSH disconnection that
+  # a remote route depends on. bin/fm-remote-doctor.sh is the readiness owner.
+  case "$selected_backend" in herdr) ;; *) die "a remote secondmate runs only on the herdr backend, not '$selected_backend'" ;; esac
+  mkdir -p "$CONTROL_STATE" "$CONTROL_DATA"
+  meta=$(meta_path "$id")
+  if [ -f "$meta" ]; then
+    remote_endpoint_require "$id"
+    current=$(fm_backend_agent_state "$REMOTE_ENDPOINT_BACKEND" "$REMOTE_ENDPOINT_TARGET" 2>/dev/null || printf 'unreadable\n')
+    case "$current" in
+      alive)
+        print_route "$id"
+        return 0
+        ;;
+      dead)
+        fm_backend_kill "$REMOTE_ENDPOINT_BACKEND" "$REMOTE_ENDPOINT_TARGET" 2>/dev/null \
+          || die "could not remove the confirmed agent-less endpoint"
+        ;;
+      missing) ;;
+      *) die "remote endpoint state is $current; refusing duplicate launch" ;;
+    esac
+  fi
+  ARGS=("$id" "$TARGET_HOME" --secondmate --harness "$harness" --backend "$selected_backend")
+  [ "$model" = - ] || ARGS+=(--model "$model")
+  [ "$effort" = - ] || ARGS+=(--effort "$effort")
+  [ -z "$traceparent" ] || ARGS+=(--traceparent "$traceparent")
+  if ! out=$(HERDR_SESSION="$REMOTE_HERDR_SESSION" FM_HOME="$FM_ROOT" FM_ROOT_OVERRIDE="$FM_ROOT" \
+    FM_STATE_OVERRIDE="$CONTROL_STATE" FM_DATA_OVERRIDE="$CONTROL_DATA" \
+    FM_CONFIG_OVERRIDE="$TARGET_HOME/config" FM_SKIP_SECONDMATE_INHERIT=1 \
+    "$SCRIPT_DIR/fm-spawn.sh" "${ARGS[@]}" 2>&1); then
+    [ -z "$out" ] || printf '%s\n' "$out" >&2
+    die "remote host-local secondmate launch failed"
+  fi
+  [ -f "$meta" ] || die "remote launch returned without endpoint metadata"
+  herdr_session=$(fm_meta_get "$meta" herdr_session)
+  [ "$herdr_session" = "$REMOTE_HERDR_SESSION" ] \
+    || die "remote launch recorded Herdr session '${herdr_session:-missing}', expected '$REMOTE_HERDR_SESSION'"
+  print_route "$id"
+}
+
+cmd_send() {
+  local id=$1 message=$2 delivery_mode=${3:-} rec ring_rc=0 meta meta_lock
+  validate_id "$id"
+  [ -z "$delivery_mode" ] || [ "$delivery_mode" = fire-and-forget ] || die "invalid send delivery mode"
+  validate_home "$id"
+  meta=$(meta_path "$id")
+  meta_lock=$(fm_meta_lock_path "$meta") || die "remote secondmate metadata lock path is invalid"
+  fm_task_inbox_lock_acquire "$meta_lock" \
+    || die "remote secondmate endpoint metadata could not be locked for final delivery validation"
+  if ! remote_endpoint_load "$id"; then
+    fm_lock_release "$meta_lock"
+    die "$REMOTE_ENDPOINT_ERROR"
+  fi
+  # A remote steer is delivered by durable record, never by typing its payload
+  # into the pane: write it into this secondmate's host-local steering inbox,
+  # then ring the constant self-describing doorbell into the recorded pane,
+  # best-effort (bin/fm-task-inbox-lib.sh owns the record and doorbell). The
+  # write is idempotent - re-running the same request after an ambiguous
+  # transport failure lands on the existing record instead of a duplicate - so
+  # the parent may safely repeat this leg. Exit 0 once the record durably
+  # exists; no ring outcome changes it, because the parent transport owns any
+  # retry or reply-tracking policy from here.
+  if ! rec=$(fm_task_inbox_write_idempotent "$CONTROL_STATE" "$id" "$message" "$delivery_mode"); then
+    fm_lock_release "$meta_lock"
+    die "steering-inbox record could not be written under $CONTROL_STATE/$id.inbox"
+  fi
+  fm_lock_release "$meta_lock"
+  case "$rec" in
+    */handled/*)
+      # The dedup landed on a record the worker already acknowledged: the
+      # steer was delivered and acted on, so there is nothing to announce.
+      printf 'notice: this steer was already delivered and acknowledged at %s; nothing re-rung\n' "$rec" >&2
+      return 0
+      ;;
+  esac
+  fm_task_inbox_ring "$REMOTE_ENDPOINT_BACKEND" "$REMOTE_ENDPOINT_TARGET" "$rec" "fm-$id" || ring_rc=$?
+  case "$ring_rc" in
+    1) printf 'notice: doorbell skipped (composer visibly holds pending text); the steer is durably recorded at %s\n' "$rec" >&2 ;;
+    2) printf 'notice: doorbell did not reach %s; the steer is durably recorded at %s\n' "$REMOTE_ENDPOINT_TARGET" "$rec" >&2 ;;
+  esac
+}
+
+cmd_key() {
+  local id=$1 key=$2
+  validate_id "$id"
+  validate_home "$id"
+  remote_endpoint_require "$id"
+  FM_HOME="$TARGET_HOME" FM_ROOT_OVERRIDE="$FM_ROOT" FM_STATE_OVERRIDE="$TARGET_HOME/state" \
+    "$SCRIPT_DIR/fm-send.sh" "$REMOTE_ENDPOINT_TARGET" --key "$key"
+}
+
+cmd_capture() {
+  local id=$1 lines=${2:-20}
+  validate_id "$id"
+  validate_home "$id"
+  case "$lines" in ''|*[!0-9]*|0) die "capture line count must be positive" ;; esac
+  [ "$lines" -le 100 ] || die "capture line count exceeds 100"
+  remote_endpoint_require "$id"
+  fm_backend_capture "$REMOTE_ENDPOINT_BACKEND" "$REMOTE_ENDPOINT_TARGET" "$lines" "fm-$id" | head -c 65536
+}
+
+cmd_observe() {
+  local id=$1 harness
+  validate_id "$id"
+  validate_home "$id"
+  remote_endpoint_require "$id"
+  harness=$(fm_meta_get "$REMOTE_ENDPOINT_META" harness)
+  fm_pending_reply_backend_observation "$REMOTE_ENDPOINT_BACKEND" "$REMOTE_ENDPOINT_TARGET" "fm-$id" "$harness"
+  printf '\n'
+}
+
+cmd_sync() {
+  local id=$1 target dirty head current
+  validate_id "$id"
+  validate_home "$id"
+  target=$TARGET_HOME
+  dirty=$(git -C "$target" status --porcelain 2>/dev/null | awk '$0 != "?? .fm-secondmate-home" { print; exit }')
+  [ -z "$dirty" ] || die "remote secondmate checkout is dirty; sync skipped"
+  head=$(git -C "$FM_ROOT" rev-parse HEAD 2>/dev/null) || die "remote code root HEAD is unreadable"
+  current=$(git -C "$target" rev-parse HEAD 2>/dev/null) || die "remote home HEAD is unreadable"
+  if [ "$current" = "$head" ]; then
+    printf 'current: %s\n' "$head"
+    return 0
+  fi
+  if ! git -C "$target" cat-file -e "$head^{commit}" 2>/dev/null; then
+    git -C "$target" fetch --quiet --no-tags "$FM_ROOT" "$head" \
+      || die "remote home could not import the code-root commit"
+  fi
+  git -C "$target" cat-file -e "$head^{commit}" 2>/dev/null || die "remote home does not contain the code-root commit"
+  git -C "$target" merge-base --is-ancestor HEAD "$head" || die "remote secondmate checkout is not a fast-forward"
+  git -C "$target" checkout --detach -q "$head" || die "remote secondmate fast-forward failed"
+  printf 'synced: %s\n' "$head"
+}
+
+cmd_update() {
+  local id=$1 update_out root_status
+  validate_id "$id"
+  validate_home "$id"
+  if ! update_out=$(FM_HOME="$FM_ROOT" FM_ROOT_OVERRIDE="$FM_ROOT" \
+    "$SCRIPT_DIR/fm-update.sh" 2>&1); then
+    [ -z "$update_out" ] || printf '%s\n' "$update_out" >&2
+    die "remote code root update failed"
+  fi
+  root_status=$(printf '%s\n' "$update_out" | grep '^firstmate:' | tail -1)
+  case "$root_status" in
+    'firstmate: updated '*|'firstmate: already current'*) ;;
+    *)
+      [ -z "$update_out" ] || printf '%s\n' "$update_out" >&2
+      die "remote code root did not complete a safe origin update"
+      ;;
+  esac
+  cmd_sync "$id"
+}
+
+cmd_retire() {
+  local id=$1 force=${2:-} rc
+  validate_id "$id"
+  validate_home "$id" yes || rc=$?
+  if [ "${rc:-0}" -eq 2 ]; then
+    printf 'already-retired: %s\n' "$id"
+    return 0
+  fi
+  [ -z "$force" ] || [ "$force" = --force ] || usage
+  remote_endpoint_require "$id"
+  FM_HOME="$TARGET_HOME" FM_ROOT_OVERRIDE="$FM_ROOT" FM_STATE_OVERRIDE="$TARGET_HOME/state" \
+    FM_CONFIG_OVERRIDE="$TARGET_HOME/config" "$SCRIPT_DIR/fm-guard.sh" || true
+  if [ -n "$force" ]; then
+    FM_HOME="$FM_ROOT" FM_ROOT_OVERRIDE="$FM_ROOT" \
+      FM_STATE_OVERRIDE="$CONTROL_STATE" FM_DATA_OVERRIDE="$CONTROL_DATA" \
+      FM_CONFIG_OVERRIDE="$TARGET_HOME/config" FM_TEARDOWN_GUARD_DONE=1 \
+      "$SCRIPT_DIR/fm-teardown.sh" "$id" --force
+  else
+    FM_HOME="$FM_ROOT" FM_ROOT_OVERRIDE="$FM_ROOT" \
+      FM_STATE_OVERRIDE="$CONTROL_STATE" FM_DATA_OVERRIDE="$CONTROL_DATA" \
+      FM_CONFIG_OVERRIDE="$TARGET_HOME/config" FM_TEARDOWN_GUARD_DONE=1 \
+      "$SCRIPT_DIR/fm-teardown.sh" "$id"
+  fi
+}
+
+case "${1:-}" in
+  launch) shift; [ "$#" -ge 5 ] && [ "$#" -le 6 ] || usage; cmd_launch "$@" ;;
+  state) shift; [ "$#" -eq 1 ] || usage; validate_id "$1"; validate_home "$1"; state_value "$1" ;;
+  route) shift; [ "$#" -eq 1 ] || usage; cmd_route "$1" ;;
+  send) shift; [ "$#" -ge 2 ] && [ "$#" -le 3 ] || usage; cmd_send "$@" ;;
+  key) shift; [ "$#" -eq 2 ] || usage; cmd_key "$@" ;;
+  capture) shift; [ "$#" -ge 1 ] && [ "$#" -le 2 ] || usage; cmd_capture "$@" ;;
+  observe) shift; [ "$#" -eq 1 ] || usage; cmd_observe "$@" ;;
+  sync) shift; [ "$#" -eq 1 ] || usage; cmd_sync "$@" ;;
+  update) shift; [ "$#" -eq 1 ] || usage; cmd_update "$@" ;;
+  retire) shift; [ "$#" -ge 1 ] && [ "$#" -le 2 ] || usage; cmd_retire "$@" ;;
+  ''|-h|--help|help) usage ;;
+  *) die "unknown command: $1" ;;
+esac

package/.agents/backend/fm-review-diff.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# Review a crewmate branch against the authoritative base.
+#
+# Pooled project clones do not keep their local default branch current, so this
+# helper compares remote-backed projects against origin/<default> after fetching
+# the default branch, and local-only projects against the local default branch.
+# When state/<id>.meta records pr= (URL or number) for an open PR, the compare
+# side is ALWAYS a freshly fetched refs/pull/<n>/head by default so review stays
+# current after no-mistakes fix rounds push to the PR. A recorded pr_head= is
+# only a fallback when fetch fails (stale recorded SHAs must never win over a
+# reachable remote PR head). If neither PR head can be resolved, fall back to
+# the local branch with a warning. Without pr=, compare the local branch.
+# Usage: fm-review-diff.sh <task-id> [--stat]
+#   --stat prints only the stat summary; default prints stat summary plus full diff.
+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
+
+usage() {
+  echo "usage: fm-review-diff.sh <task-id> [--stat]" >&2
+}
+
+if [ "${1:-}" = "--help" ] || [ "${1:-}" = "-h" ]; then
+  usage
+  exit 0
+fi
+
+ID=${1:-}
+[ -n "$ID" ] || { usage; exit 1; }
+STAT_ONLY=false
+case "${2:-}" in
+  '') ;;
+  --stat) STAT_ONLY=true ;;
+  *) usage; exit 1 ;;
+esac
+[ $# -le 2 ] || { usage; exit 1; }
+
+META="$STATE/$ID.meta"
+[ -f "$META" ] || { echo "error: no meta for task $ID at $META" >&2; exit 1; }
+
+WT=$(grep '^worktree=' "$META" | cut -d= -f2-)
+PROJ=$(grep '^project=' "$META" | cut -d= -f2-)
+[ -n "$WT" ] || { echo "error: meta for task $ID is missing worktree=" >&2; exit 1; }
+[ -n "$PROJ" ] || { echo "error: meta for task $ID is missing project=" >&2; exit 1; }
+[ -d "$WT" ] || { echo "error: worktree for task $ID is missing: $WT" >&2; exit 1; }
+[ -d "$PROJ" ] || { echo "error: project for task $ID is missing: $PROJ" >&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
+}
+
+DEFAULT=$(default_branch) || { echo "error: cannot determine default branch for $PROJ; expected origin/HEAD, main, or master" >&2; exit 1; }
+
+BRANCH="fm/$ID"
+if ! git -C "$WT" rev-parse --verify --quiet "refs/heads/$BRANCH" >/dev/null; then
+  BRANCH=$(git -C "$WT" symbolic-ref --quiet --short HEAD 2>/dev/null || true)
+  [ -n "$BRANCH" ] || { echo "error: branch fm/$ID does not exist and worktree $WT is detached" >&2; exit 1; }
+  git -C "$WT" rev-parse --verify --quiet "refs/heads/$BRANCH" >/dev/null || { echo "error: branch $BRANCH does not exist in $WT" >&2; exit 1; }
+fi
+
+pr_number_from_target() {
+  local target=$1 n
+  case "$target" in
+    '' ) return 1 ;;
+    *"/pull/"*)
+      n=${target##*/pull/}
+      n=${n%%[!0-9]*}
+      ;;
+    [0-9]*)
+      n=${target%%[!0-9]*}
+      ;;
+    *) return 1 ;;
+  esac
+  [ -n "$n" ] || return 1
+  printf '%s' "$n"
+}
+
+fetch_pull_head() {
+  local n=$1 resolved
+  git -C "$WT" remote get-url origin >/dev/null 2>&1 || return 1
+  # Fetch into a private ref so a later base-branch fetch cannot clobber the
+  # compare tip via FETCH_HEAD, and so we never review a stale local object.
+  git -C "$WT" fetch --quiet origin \
+    "+refs/pull/$n/head:refs/fm-review/pull/$n/head" >/dev/null 2>&1 || return 1
+  resolved=$(git -C "$WT" rev-parse --verify "refs/fm-review/pull/$n/head^{commit}" 2>/dev/null) || return 1
+  [ -n "$resolved" ] || return 1
+  printf '%s' "$resolved"
+}
+
+resolve_pr_head() {
+  local pr_url=$1 recorded_head=$2 n resolved
+  n=$(pr_number_from_target "$pr_url") || true
+  if [ -n "$n" ]; then
+    if resolved=$(fetch_pull_head "$n"); then
+      printf '%s' "$resolved"
+      return 0
+    fi
+  fi
+  # Offline / unreachable remote: recorded pr_head is better than the local
+  # branch, but never preferred over a successful pull-head fetch above.
+  if [ -n "$recorded_head" ] \
+    && git -C "$WT" cat-file -e "$recorded_head^{commit}" 2>/dev/null; then
+    printf '%s' "$recorded_head"
+    return 0
+  fi
+  return 1
+}
+
+PR_URL=$(grep '^pr=' "$META" | tail -1 | cut -d= -f2- || true)
+PR_HEAD_RECORDED=$(grep '^pr_head=' "$META" | tail -1 | cut -d= -f2- || true)
+COMPARE_REF=$BRANCH
+if [ -n "$PR_URL" ]; then
+  if PR_HEAD=$(resolve_pr_head "$PR_URL" "$PR_HEAD_RECORDED"); then
+    COMPARE_REF=$PR_HEAD
+  else
+    echo "warning: PR head unavailable; diff may lag the open PR (using local branch $BRANCH)" >&2
+  fi
+fi
+
+if git -C "$PROJ" remote get-url origin >/dev/null 2>&1; then
+  # Update the remote-tracking ref itself; a bare single-branch fetch can leave
+  # origin/<default> stale on some Git versions and only refresh FETCH_HEAD.
+  git -C "$WT" fetch origin "+refs/heads/$DEFAULT:refs/remotes/origin/$DEFAULT" --quiet
+  BASE="origin/$DEFAULT"
+else
+  BASE="$DEFAULT"
+fi
+
+git -C "$WT" rev-parse --verify --quiet "$BASE^{commit}" >/dev/null || { echo "error: base $BASE does not exist in $WT" >&2; exit 1; }
+git -C "$WT" rev-parse --verify --quiet "$COMPARE_REF^{commit}" >/dev/null || { echo "error: compare ref $COMPARE_REF does not resolve in $WT" >&2; exit 1; }
+
+echo "diff base: $BASE"
+if git -C "$WT" diff --quiet "$BASE...$COMPARE_REF" --; then
+  echo "no changes vs $BASE"
+  exit 0
+fi
+
+git -C "$WT" diff --stat "$BASE...$COMPARE_REF" --
+if ! "$STAT_ONLY"; then
+  echo
+  git -C "$WT" diff "$BASE...$COMPARE_REF" --
+fi

package/.agents/backend/fm-secondmate-charter-lib.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Shared extraction of secondmate registry summary and scope from a charter.
+# Source only. FM_SECONDMATE_CHARTER and FM_SECONDMATE_SCOPE remain explicit
+# caller overrides; otherwise the named sections in the filled brief are used.
+
+normalize_registry_text() {
+  awk '
+    {
+      gsub(/[;()]/, " ")
+      gsub(/[[:space:]]+/, " ")
+      sub(/^ /, "")
+      sub(/ $/, "")
+      if ($0 != "") out = out (out == "" ? "" : " ") $0
+    }
+    END { print out }
+  '
+}
+
+brief_section_text() {
+  local brief=$1 heading=$2
+  awk -v heading="# $heading" '
+    $0 == heading { in_section=1; next }
+    in_section && /^# / { exit }
+    in_section { print }
+  ' "$brief"
+}
+
+registry_summary_for_brief() {
+  local brief=$1
+  if [ -n "${FM_SECONDMATE_CHARTER:-}" ]; then
+    printf '%s\n' "$FM_SECONDMATE_CHARTER" | normalize_registry_text
+  else
+    brief_section_text "$brief" "Charter" | normalize_registry_text
+  fi
+}
+
+registry_scope_for_brief() {
+  local brief=$1
+  if [ -n "${FM_SECONDMATE_SCOPE:-}" ]; then
+    printf '%s\n' "$FM_SECONDMATE_SCOPE" | normalize_registry_text
+  else
+    brief_section_text "$brief" "Routing scope" | normalize_registry_text
+  fi
+}

package/.agents/backend/fm-secondmate-nudge-lib.sh

@@ -0,0 +1,68 @@
+# shellcheck shell=bash disable=SC2034
+# Durable secondmate reread-nudge marker helpers. Source only.
+#
+# Both local tracked-file convergence and remote inherited-material transfer
+# publish the same bounded record before delivery. A failed send leaves the
+# record for the locked bootstrap retry; a successful send removes it.
+
+FM_SECOND_MATE_NUDGE_MESSAGE='firstmate was updated to the latest - please re-read your AGENTS.md to pick up the new instructions.'
+FM_REMOTE_SECOND_MATE_NUDGE_MESSAGE='Firstmate instructions or inherited config changed on this host. Re-read AGENTS.md and the inherited config files before further work.'
+
+fm_secondmate_nudge_marker_path() { # <state-dir> <id>
+  local state=$1 id=$2
+  case "$id" in *[!/A-Za-z0-9._-]*|''|*/*) return 1 ;; esac
+  printf '%s/.secondmate-nudge-pending/%s.pending\n' "$state" "$id"
+}
+
+fm_remote_inherit_transaction_lock_path() { # <state-dir> <id>
+  local state=$1 id=$2
+  case "$id" in *[!/A-Za-z0-9._-]*|''|*/*) return 1 ;; esac
+  printf '%s/.remote-inherit-%s.lock\n' "$state" "$id"
+}
+
+fm_remote_inherit_generation_next() { # <state-dir> <id>
+  local state=$1 id=$2 path current next tmp
+  case "$id" in *[!/A-Za-z0-9._-]*|''|*/*) return 1 ;; esac
+  [ -d "$state" ] && [ ! -L "$state" ] || return 1
+  path="$state/.remote-inherit-$id.generation"
+  current=0
+  if [ -e "$path" ] || [ -L "$path" ]; then
+    [ -f "$path" ] && [ ! -L "$path" ] || return 1
+    IFS= read -r current < "$path" || return 1
+    case "$current" in ''|*[!0-9]*) return 1 ;; esac
+    [ "${#current}" -le 17 ] || return 1
+  fi
+  next=$((current + 1))
+  tmp=$(umask 077; mktemp "$state/.remote-inherit-generation.XXXXXX") || return 1
+  printf '%s\n' "$next" > "$tmp" || { rm -f -- "$tmp"; return 1; }
+  chmod 600 "$tmp" || { rm -f -- "$tmp"; return 1; }
+  mv -f -- "$tmp" "$path" || { rm -f -- "$tmp"; return 1; }
+  printf '%s\n' "$next"
+}
+
+fm_secondmate_nudge_write() { # <state> <id> <home> <commit> <instructions> <message> <remote:0|1>
+  local state=$1 id=$2 home=$3 commit=$4 instructions=$5 message=$6 remote=$7
+  local marker parent tmp
+  case "$remote" in 0|1) ;; *) return 1 ;; esac
+  case "$home$commit$instructions$message" in *$'\n'*|*$'\r'*) return 1 ;; esac
+  marker=$(fm_secondmate_nudge_marker_path "$state" "$id") || return 1
+  parent=${marker%/*}
+  if [ -e "$parent" ] || [ -L "$parent" ]; then
+    [ -d "$parent" ] && [ ! -L "$parent" ] || return 1
+  else
+    mkdir -p "$parent" || return 1
+  fi
+  [ ! -L "$marker" ] || return 1
+  tmp=$(umask 077; mktemp "$parent/.nudge.XXXXXX" 2>/dev/null) || return 1
+  {
+    printf 'id=%s\n' "$id"
+    printf 'selector=fm-%s\n' "$id"
+    printf 'home=%s\n' "$home"
+    printf 'commit=%s\n' "$commit"
+    printf 'instructions=%s\n' "$instructions"
+    printf 'message=%s\n' "$message"
+    printf 'remote=%s\n' "$remote"
+  } > "$tmp" || { rm -f -- "$tmp"; return 1; }
+  chmod 600 "$tmp" || { rm -f -- "$tmp"; return 1; }
+  mv -f -- "$tmp" "$marker" || { rm -f -- "$tmp"; return 1; }
+}