@zerwiz/ymir 0.1.4 → 0.1.7

package/.agents/backend/fm-remote-home-provision.sh

@@ -0,0 +1,259 @@
+#!/usr/bin/env bash
+# Provision the FM_HOME selected by the fixed remote entrypoint.
+#
+# Usage:
+#   fm-remote-home-provision.sh < manifest
+#
+# Manifest schema fm-remote-home-provision.v1 carries a base64 charter, the
+# base64 parent SSH alias, and one base64 project record per line. Each project
+# record's origin is the URL the parent resolved and named, so this host clones
+# from it and re-validates it through bin/fm-project-origin-lib.sh instead of
+# trusting the sender. The remote code root is cloned into an absent home,
+# project origins are cloned on this host, the project registry and charter are
+# published, the durable .fm-secondmate-parent record names this home's route to its parent as
+# "remote" - read by bin/fm-teardown.sh's cleanup gate so a delegated public
+# reply promise, which the subsystem can only carry on the parent's own
+# filesystem, is never mistaken for one this child could hold - and the
+# .fm-secondmate-home marker commits the complete seed last.
+# A newly created home is removed on failure. An existing matching seeded home
+# is converged only through guarded ordinary-file updates and new project clones.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+FM_HOME=${FM_HOME:?FM_HOME is required}
+MAX_MANIFEST_BYTES=1048576
+
+# shellcheck source=bin/fm-project-origin-lib.sh
+. "$SCRIPT_DIR/fm-project-origin-lib.sh"
+
+die() { printf 'error: %s\n' "$1" >&2; exit 1; }
+
+base64_decode_to() {
+  if printf '%s' "$1" | base64 --decode > "$2" 2>/dev/null; then return 0; fi
+  if printf '%s' "$1" | base64 -D > "$2" 2>/dev/null; then return 0; fi
+  return 1
+}
+
+manifest_value() { # <file> <key>
+  local count
+  count=$(grep -c "^$2=" "$1" 2>/dev/null || true)
+  [ "$count" -eq 1 ] || return 1
+  grep "^$2=" "$1" | cut -d= -f2-
+}
+
+safe_id() { case "$1" in ''|*[!A-Za-z0-9._-]*) return 1 ;; esac; }
+
+TMP=$(mktemp -d "${TMPDIR:-/tmp}/fm-remote-provision.XXXXXX") || die "cannot create provisioning state"
+CREATED_HOME=0
+CREATED_BACKLOG=0
+EXISTING_HOME=0
+PUBLISHED=0
+PROVISION_LOCK=
+PROVISION_LOCK_HELD=0
+CREATED_PROJECTS="$TMP/created-projects"
+: > "$CREATED_PROJECTS"
+release_provision_lock() {
+  if [ "$PROVISION_LOCK_HELD" -eq 1 ]; then
+    fm_lock_release "$PROVISION_LOCK"
+    PROVISION_LOCK_HELD=0
+  fi
+}
+restore_owned_file() { # <relative-path>
+  local rel=$1 dest="$FM_HOME/$1" backup="$TMP/before/$1"
+  if [ -f "$backup.present" ]; then
+    mkdir -p "$(dirname "$dest")" || return 1
+    cp -p -- "$backup" "$dest.tmp.rollback.$$" || return 1
+    mv -f -- "$dest.tmp.rollback.$$" "$dest"
+  else
+    rm -f -- "$dest"
+  fi
+}
+rollback() {
+  local status=$? project
+  if [ "$status" -ne 0 ] && [ "$PUBLISHED" -eq 0 ]; then
+    if [ "$CREATED_HOME" -eq 1 ]; then
+      rm -rf -- "$FM_HOME"
+    elif [ "$EXISTING_HOME" -eq 1 ]; then
+      while IFS= read -r project; do
+        [ -n "$project" ] && rm -rf -- "$FM_HOME/projects/$project"
+      done < "$CREATED_PROJECTS"
+      restore_owned_file data/charter.md || true
+      restore_owned_file data/projects.md || true
+      restore_owned_file .fm-secondmate-home || true
+      restore_owned_file .fm-secondmate-parent || true
+      [ "$CREATED_BACKLOG" -eq 0 ] || rm -f -- "$FM_HOME/data/backlog.md"
+    fi
+  fi
+  release_provision_lock
+  rm -rf -- "$TMP"
+  exit "$status"
+}
+trap rollback EXIT
+trap 'exit 1' HUP INT TERM
+head -c "$((MAX_MANIFEST_BYTES + 1))" > "$TMP/manifest" || die "cannot read provisioning manifest"
+MANIFEST_BYTES=$(LC_ALL=C wc -c < "$TMP/manifest" | tr -d ' ')
+[ "$MANIFEST_BYTES" -le "$MAX_MANIFEST_BYTES" ] || die "provisioning manifest exceeds its byte bound"
+SCHEMA=$(manifest_value "$TMP/manifest" schema || true)
+[ "$SCHEMA" = fm-remote-home-provision.v1 ] || die "incompatible provisioning manifest"
+ID_B64=$(manifest_value "$TMP/manifest" id_b64 || true)
+CHARTER_B64=$(manifest_value "$TMP/manifest" charter_b64 || true)
+# Optional so a manifest sent by a not-yet-updated parent (predating this
+# field) still provisions; the durable parent record below simply omits the
+# host in that case rather than refusing the whole seed.
+PARENT_HOST_B64=$(manifest_value "$TMP/manifest" parent_host_b64 || true)
+COUNT=$(manifest_value "$TMP/manifest" project_count || true)
+base64_decode_to "$ID_B64" "$TMP/id" || die "manifest id is not valid base64"
+base64_decode_to "$CHARTER_B64" "$TMP/charter" || die "manifest charter is not valid base64"
+PARENT_HOST=
+if [ -n "$PARENT_HOST_B64" ]; then
+  base64_decode_to "$PARENT_HOST_B64" "$TMP/parent-host" || die "manifest parent host is not valid base64"
+  PARENT_HOST=$(cat "$TMP/parent-host")
+fi
+ID=$(cat "$TMP/id")
+safe_id "$ID" || die "manifest carries an unsafe secondmate id"
+case "$COUNT" in ''|*[!0-9]*) die "manifest project count is invalid" ;; esac
+[ -s "$TMP/charter" ] || die "manifest charter is empty"
+[ -z "$(LC_ALL=C tr -cd '\000' < "$TMP/charter")" ] || die "manifest charter contains NUL bytes"
+RECORDS=$(grep -c '^project=' "$TMP/manifest" 2>/dev/null || true)
+[ "$RECORDS" -eq "$COUNT" ] || die "manifest project count does not match its records"
+
+HOME_PARENT=$(dirname "$FM_HOME")
+HOME_PARENT_REAL=$(CDPATH='' cd -- "$HOME_PARENT" 2>/dev/null && pwd -P) \
+  || die "remote home parent is unavailable"
+[ "$HOME_PARENT_REAL" = "$HOME_PARENT" ] || die "remote home parent is not canonical"
+PROVISION_LOCK_STATE="$HOME_PARENT/.firstmate-provision-locks"
+if [ -e "$PROVISION_LOCK_STATE" ] || [ -L "$PROVISION_LOCK_STATE" ]; then
+  [ -d "$PROVISION_LOCK_STATE" ] && [ ! -L "$PROVISION_LOCK_STATE" ] \
+    || die "remote provisioning lock root is unsafe"
+else
+  mkdir "$PROVISION_LOCK_STATE" 2>/dev/null || true
+  [ -d "$PROVISION_LOCK_STATE" ] && [ ! -L "$PROVISION_LOCK_STATE" ] \
+    || die "cannot create remote provisioning lock root"
+fi
+if command -v shasum >/dev/null 2>&1; then
+  HOME_LOCK_KEY=$(printf '%s' "$FM_HOME" | shasum -a 256 | awk '{print $1}')
+elif command -v sha256sum >/dev/null 2>&1; then
+  HOME_LOCK_KEY=$(printf '%s' "$FM_HOME" | sha256sum | awk '{print $1}')
+else
+  die "no SHA-256 tool is available for provisioning serialization"
+fi
+FM_STATE_OVERRIDE="$PROVISION_LOCK_STATE"
+# shellcheck source=bin/fm-wake-lib.sh
+. "$SCRIPT_DIR/fm-wake-lib.sh"
+PROVISION_LOCK="$STATE/.remote-home-provision-$HOME_LOCK_KEY.lock"
+fm_lock_acquire_wait "$PROVISION_LOCK"
+PROVISION_LOCK_HELD=1
+
+if [ -e "$FM_HOME" ] || [ -L "$FM_HOME" ]; then
+  [ -d "$FM_HOME" ] && [ ! -L "$FM_HOME" ] || die "remote home exists but is not a safe directory"
+  [ -f "$FM_HOME/AGENTS.md" ] && [ ! -L "$FM_HOME/AGENTS.md" ] \
+    && [ -d "$FM_HOME/bin" ] && [ ! -L "$FM_HOME/bin" ] || die "existing remote home is not a safe Firstmate checkout"
+  for operational_dir in data state config projects; do
+    operational_path="$FM_HOME/$operational_dir"
+    if [ -e "$operational_path" ] || [ -L "$operational_path" ]; then
+      [ -d "$operational_path" ] && [ ! -L "$operational_path" ] \
+        || die "remote home has unsafe operational directory: $operational_dir"
+    fi
+  done
+  mkdir -p "$TMP/before/data"
+  for rel in data/charter.md data/projects.md .fm-secondmate-home .fm-secondmate-parent; do
+    existing="$FM_HOME/$rel"
+    if [ -e "$existing" ] || [ -L "$existing" ]; then
+      [ -f "$existing" ] && [ ! -L "$existing" ] || die "existing remote home has unsafe owned file: $rel"
+      mkdir -p "$(dirname "$TMP/before/$rel")"
+      cp -p -- "$existing" "$TMP/before/$rel" || die "cannot snapshot existing remote home file: $rel"
+      : > "$TMP/before/$rel.present"
+    fi
+  done
+  EXISTING_HOME=1
+  if [ -f "$FM_HOME/.fm-secondmate-home" ]; then
+    [ "$(cat "$FM_HOME/.fm-secondmate-home")" = "$ID" ] || die "existing remote home belongs to another secondmate"
+  elif find "$FM_HOME/data" "$FM_HOME/state" "$FM_HOME/projects" -mindepth 1 -maxdepth 1 -print -quit 2>/dev/null | grep -q .; then
+    die "unmarked existing remote home contains operational data"
+  fi
+else
+  CREATED_HOME=1
+  git clone --quiet -- "$FM_ROOT" "$FM_HOME" || die "could not clone the remote Firstmate home"
+fi
+for operational_dir in data state config projects; do
+  operational_path="$FM_HOME/$operational_dir"
+  if [ -e "$operational_path" ] || [ -L "$operational_path" ]; then
+    [ -d "$operational_path" ] && [ ! -L "$operational_path" ] \
+      || die "remote home has unsafe operational directory: $operational_dir"
+  else
+    mkdir "$operational_path" || die "cannot create remote operational directory: $operational_dir"
+  fi
+done
+if [ -e "$FM_HOME/data/backlog.md" ] || [ -L "$FM_HOME/data/backlog.md" ]; then
+  [ -f "$FM_HOME/data/backlog.md" ] && [ ! -L "$FM_HOME/data/backlog.md" ] \
+    || die "remote backlog is not a safe regular file"
+else
+  printf '## In flight\n\n## Queued\n\n## Done\n' > "$FM_HOME/data/backlog.md"
+  CREATED_BACKLOG=1
+fi
+
+PROJECT_REG="$TMP/projects.md"
+: > "$PROJECT_REG"
+while IFS= read -r record; do
+  [ -n "$record" ] || continue
+  encoded=${record#project=}
+  old_ifs=$IFS
+  IFS='|'
+  read -r NAME_B64 ORIGIN_B64 REGISTRY_B64 MODE_B64 <<EOF
+$encoded
+EOF
+  IFS=$old_ifs
+  for field in NAME_B64 ORIGIN_B64 REGISTRY_B64 MODE_B64; do
+    eval "value=\${$field}"
+    [ -n "$value" ] || die "project manifest record is incomplete"
+  done
+  base64_decode_to "$NAME_B64" "$TMP/name" || die "project name is not valid base64"
+  base64_decode_to "$ORIGIN_B64" "$TMP/origin" || die "project origin is not valid base64"
+  base64_decode_to "$REGISTRY_B64" "$TMP/registry" || die "project registry line is not valid base64"
+  base64_decode_to "$MODE_B64" "$TMP/mode" || die "project mode is not valid base64"
+  NAME=$(cat "$TMP/name")
+  ORIGIN=$(cat "$TMP/origin")
+  REGISTRY_LINE=$(cat "$TMP/registry")
+  MODE=$(cat "$TMP/mode")
+  safe_id "$NAME" || die "project name is unsafe: $NAME"
+  [ -n "$ORIGIN" ] || die "project $NAME has no origin"
+  fm_project_origin_safe "$ORIGIN" || die "project $NAME origin is not an accepted clone URL: $ORIGIN"
+  case "$MODE" in no-mistakes|direct-PR) ;; *) die "project $NAME has unsupported remote mode: $MODE" ;; esac
+  case "$REGISTRY_LINE" in "- $NAME "*) ;; *) die "project $NAME registry line is malformed" ;; esac
+  DEST="$FM_HOME/projects/$NAME"
+  if [ -e "$DEST" ] || [ -L "$DEST" ]; then
+    [ -d "$DEST" ] && [ ! -L "$DEST" ] && [ -d "$DEST/.git" ] \
+      || die "project destination exists but is not a safe clone: $DEST"
+    EXISTING_ORIGIN=$(git -C "$DEST" remote get-url origin 2>/dev/null || true)
+    [ "$EXISTING_ORIGIN" = "$ORIGIN" ] || die "project $NAME origin differs from the requested route"
+  else
+    printf '%s\n' "$NAME" >> "$CREATED_PROJECTS"
+    git clone --quiet -- "$ORIGIN" "$DEST" || die "could not clone project $NAME on the remote host"
+    if [ "$MODE" = no-mistakes ]; then
+      command -v no-mistakes >/dev/null 2>&1 || die "no-mistakes is unavailable for project $NAME"
+      (cd "$DEST" && no-mistakes init >/dev/null && no-mistakes doctor >/dev/null) \
+        || die "no-mistakes initialization failed for project $NAME"
+    fi
+  fi
+  printf '%s\n' "$REGISTRY_LINE" >> "$PROJECT_REG"
+done < <(grep '^project=' "$TMP/manifest")
+
+cp "$TMP/charter" "$FM_HOME/data/charter.md.tmp.$$"
+chmod 600 "$FM_HOME/data/charter.md.tmp.$$"
+mv -f -- "$FM_HOME/data/charter.md.tmp.$$" "$FM_HOME/data/charter.md"
+cp "$PROJECT_REG" "$FM_HOME/data/projects.md.tmp.$$"
+mv -f -- "$FM_HOME/data/projects.md.tmp.$$" "$FM_HOME/data/projects.md"
+{
+  printf 'schema=fm-secondmate-parent.v1\n'
+  printf 'route=remote\n'
+  [ -z "$PARENT_HOST" ] || printf 'parent_host=%s\n' "$PARENT_HOST"
+} > "$FM_HOME/.fm-secondmate-parent.tmp.$$"
+mv -f -- "$FM_HOME/.fm-secondmate-parent.tmp.$$" "$FM_HOME/.fm-secondmate-parent"
+printf '%s\n' "$ID" > "$FM_HOME/.fm-secondmate-home.tmp.$$"
+mv -f -- "$FM_HOME/.fm-secondmate-home.tmp.$$" "$FM_HOME/.fm-secondmate-home"
+PUBLISHED=1
+release_provision_lock
+trap - EXIT
+rm -rf -- "$TMP"
+printf 'provisioned: %s projects=%s\n' "$FM_HOME" "$COUNT"

package/.agents/backend/fm-remote-home-seed.sh

@@ -0,0 +1,259 @@
+#!/usr/bin/env bash
+# Register and provision a whole secondmate home on an SSH-reachable host.
+#
+# Usage:
+#   fm-remote-home-seed.sh <id> <ssh-alias> <remote-root> <remote-home> {<project>[=<origin-url>]...|--no-projects}
+#
+# The SSH alias must already reach a host whose non-interactive PATH exposes the
+# fixed fm-remote-entrypoint.sh from <remote-root>. The command records the
+# remote host dimension in data/secondmates.md, gates the host on
+# fm-remote-doctor.sh readiness before touching it, sends a bounded provisioning
+# manifest through fm-on.sh, and lets the remote host clone its own Firstmate
+# home and project origins. No project tree or secret environment is copied.
+#
+# Each project needs an origin the remote account can clone. Firstmate resolves
+# that origin and names it as <project>=<origin-url>, so seeding never requires
+# a clone of that project in this home; a bare <project> is accepted only when
+# this home already has projects/<project>, whose origin is then read instead.
+# bin/fm-project-origin-lib.sh owns which URLs are accepted, and this home's
+# data/projects.md still owns the project's registered delivery mode, so an
+# unregistered or local-only project is refused rather than provisioned.
+# Seeding writes nothing under projects/ and needs no fleet sync first.
+#
+# Known provisioning failure rolls the registry back. SSH status 255 preserves
+# the route and any newly scaffolded brief because completion is unknown and a same-route rerun converges.
+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}"
+PROJECTS="${FM_PROJECTS_OVERRIDE:-$FM_HOME/projects}"
+STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
+REG="$DATA/secondmates.md"
+MAX_MANIFEST_BYTES=1048576
+
+# shellcheck source=bin/fm-secondmate-registry-lib.sh
+. "$SCRIPT_DIR/fm-secondmate-registry-lib.sh"
+# shellcheck source=bin/fm-secondmate-charter-lib.sh
+. "$SCRIPT_DIR/fm-secondmate-charter-lib.sh"
+# shellcheck source=bin/fm-wake-lib.sh
+. "$SCRIPT_DIR/fm-wake-lib.sh"
+# shellcheck source=bin/fm-remote-readiness-lib.sh
+. "$SCRIPT_DIR/fm-remote-readiness-lib.sh"
+# shellcheck source=bin/fm-project-origin-lib.sh
+. "$SCRIPT_DIR/fm-project-origin-lib.sh"
+
+die() { printf 'error: %s\n' "$1" >&2; exit 1; }
+usage() { sed -n '2,21p' "$0" | sed 's/^# \{0,1\}//'; exit 2; }
+encode() { base64 | tr -d '\n'; }
+safe_id() { case "$1" in ''|*[!A-Za-z0-9._-]*) return 1 ;; esac; }
+
+TMP=
+REGISTRY_LOCK=
+REGISTRY_LOCK_HELD=0
+cleanup() {
+  [ -z "$TMP" ] || rm -rf -- "$TMP"
+  if [ "$REGISTRY_LOCK_HELD" -eq 1 ]; then
+    fm_lock_release "$REGISTRY_LOCK"
+    REGISTRY_LOCK_HELD=0
+  fi
+}
+trap cleanup EXIT
+
+[ "$#" -ge 5 ] || usage
+ID=$1
+HOST=$2
+REMOTE_ROOT=$3
+REMOTE_HOME=$4
+shift 4
+safe_id "$ID" || die "invalid secondmate id: $ID"
+case "$HOST" in ''|-*|*[!A-Za-z0-9._-]*) die "invalid SSH config alias: $HOST" ;; esac
+for path in "$REMOTE_ROOT" "$REMOTE_HOME"; do
+  case "$path" in /*) ;; *) die "remote root and home must be absolute paths" ;; esac
+  case "$path" in *';'*|*')'*|*$'\n'*|*$'\r'*|*$'\t'*) die "remote root or home contains a registry delimiter" ;; esac
+  case "/$path/" in */../*|*/./*) die "remote root or home contains traversal components" ;; esac
+  case "$path" in *'//'*) die "remote root or home contains an empty path component" ;; esac
+done
+[ "$REMOTE_ROOT" != "$REMOTE_HOME" ] || die "remote root and home must be separate"
+case "$REMOTE_HOME/" in "$REMOTE_ROOT/"*) die "remote home must not be inside the remote code root" ;; esac
+case "$REMOTE_ROOT/" in "$REMOTE_HOME/"*) die "remote code root must not be inside the remote home" ;; esac
+
+NO_PROJECTS=0
+PROJECT_NAMES=()
+PROJECT_ORIGINS=()
+for arg in "$@"; do
+  if [ "$arg" = --no-projects ]; then
+    NO_PROJECTS=1
+  else
+    name=${arg%%=*}
+    origin=
+    case "$arg" in *=*) origin=${arg#*=} ;; esac
+    safe_id "$name" || die "invalid project name: $name"
+    case "$arg" in
+      *=*) fm_project_origin_safe "$origin" \
+        || die "project $name origin is not an accepted clone URL: $origin" ;;
+    esac
+    PROJECT_NAMES+=("$name")
+    PROJECT_ORIGINS+=("$origin")
+  fi
+done
+if [ "$NO_PROJECTS" -eq 1 ]; then
+  [ "${#PROJECT_NAMES[@]}" -eq 0 ] || die "--no-projects cannot be combined with project names"
+else
+  [ "${#PROJECT_NAMES[@]}" -gt 0 ] || die "at least one project or --no-projects is required"
+fi
+
+mkdir -p "$STATE" || die "cannot create parent state directory"
+REGISTRY_LOCK=$(secondmate_registry_lock_path "$STATE")
+fm_lock_acquire_wait "$REGISTRY_LOCK" || die "cannot lock the secondmate registry"
+REGISTRY_LOCK_HELD=1
+
+if [ -e "$REG" ] || [ -L "$REG" ]; then
+  [ -f "$REG" ] && [ ! -L "$REG" ] || die "secondmate registry is unavailable or unsafe: $REG"
+  secondmate_registry_validate_bindings "$REG" secondmate_registry_path_key \
+    || die "$SECONDMATE_REGISTRY_ERROR"
+  if secondmate_registry_line_for_id "$REG" "$ID"; then
+    [ "$SECONDMATE_REGISTRY_REMOTE" -eq 1 ] \
+      && [ "$SECONDMATE_REGISTRY_HOST" = "$HOST" ] \
+      && [ "$SECONDMATE_REGISTRY_ROOT" = "$REMOTE_ROOT" ] \
+      && [ "$SECONDMATE_REGISTRY_HOME" = "$REMOTE_HOME" ] \
+      || die "secondmate $ID is already registered to a different local or remote home"
+  fi
+fi
+
+mkdir -p "$DATA"
+BRIEF="$DATA/$ID/brief.md"
+BRIEF_CREATED=0
+if [ ! -f "$BRIEF" ]; then
+  [ -n "${FM_SECONDMATE_CHARTER:-}" ] || die "no filled charter at $BRIEF; set FM_SECONDMATE_CHARTER or scaffold one first"
+  if [ "$NO_PROJECTS" -eq 1 ]; then
+    "$SCRIPT_DIR/fm-brief.sh" "$ID" --secondmate --no-projects >/dev/null
+  else
+    "$SCRIPT_DIR/fm-brief.sh" "$ID" --secondmate "${PROJECT_NAMES[@]}" >/dev/null
+  fi
+  BRIEF_CREATED=1
+fi
+if grep -F '{TASK}' "$BRIEF" >/dev/null 2>&1; then
+  [ "$BRIEF_CREATED" -eq 0 ] || rm -f -- "$BRIEF"
+  die "secondmate charter still contains {TASK}: $BRIEF"
+fi
+SUMMARY=$(registry_summary_for_brief "$BRIEF")
+SCOPE=$(registry_scope_for_brief "$BRIEF")
+[ -n "$SUMMARY" ] && [ -n "$SCOPE" ] || die "charter summary and routing scope must be nonempty"
+
+TMP=$(mktemp -d "${TMPDIR:-/tmp}/fm-remote-home-seed.XXXXXX") || die "cannot create seed staging directory"
+REG_EXISTED=0
+[ -f "$REG" ] && { cp "$REG" "$TMP/registry.before"; REG_EXISTED=1; }
+
+# Keep the parent charter as its durable source, but publish a remote copy whose
+# status path is the remote append-only relay log rather than a local Mac path.
+PARENT_STATUS="$STATE/$ID.status"
+REMOTE_STATUS="$REMOTE_HOME/state/parent-replies.status"
+while IFS= read -r line || [ -n "$line" ]; do
+  printf '%s\n' "${line//"$PARENT_STATUS"/"$REMOTE_STATUS"}"
+done < "$BRIEF" > "$TMP/charter.remote"
+
+PROJECTS_CSV=
+: > "$TMP/project.records"
+PROJECT_INDEX=0
+for project in "${PROJECT_NAMES[@]}"; do
+  ORIGIN=${PROJECT_ORIGINS[$PROJECT_INDEX]}
+  PROJECT_INDEX=$((PROJECT_INDEX + 1))
+  MODE_LINE=$(FM_HOME="$FM_HOME" FM_DATA_OVERRIDE="$DATA" "$SCRIPT_DIR/fm-project-mode.sh" "$project")
+  read -r MODE _ <<EOF
+$MODE_LINE
+EOF
+  case "$MODE" in
+    no-mistakes|direct-PR) ;;
+    local-only) die "project $project is local-only and cannot be provisioned remotely" ;;
+    *) die "project $project has unsupported delivery mode: $MODE" ;;
+  esac
+  # An origin named on the command line is authoritative. Reading one from a
+  # clone this home happens to have is only a convenience for the already-cloned
+  # case; it is never a reason to create one.
+  if [ -z "$ORIGIN" ] && [ -d "$PROJECTS/$project/.git" ]; then
+    ORIGIN=$(git -C "$PROJECTS/$project" remote get-url origin 2>/dev/null || true)
+  fi
+  [ -n "$ORIGIN" ] \
+    || die "project $project has no origin; pass $project=<origin-url> so the remote host can clone it"
+  fm_project_origin_safe "$ORIGIN" \
+    || die "project $project origin is not an accepted clone URL: $ORIGIN"
+  REGISTRY_LINE=$(awk -v p="$project" '$1 == "-" && $2 == p { print; exit }' "$DATA/projects.md" 2>/dev/null || true)
+  [ -n "$REGISTRY_LINE" ] || die "project $project has no registry record"
+  NAME_B64=$(printf '%s' "$project" | encode)
+  ORIGIN_B64=$(printf '%s' "$ORIGIN" | encode)
+  PROJECT_REG_B64=$(printf '%s' "$REGISTRY_LINE" | encode)
+  MODE_B64=$(printf '%s' "$MODE" | encode)
+  printf 'project=%s|%s|%s|%s\n' "$NAME_B64" "$ORIGIN_B64" "$PROJECT_REG_B64" "$MODE_B64" >> "$TMP/project.records"
+  PROJECTS_CSV="${PROJECTS_CSV}${PROJECTS_CSV:+, }$project"
+done
+
+{
+  printf 'schema=fm-remote-home-provision.v1\n'
+  printf 'id_b64=%s\n' "$(printf '%s' "$ID" | encode)"
+  printf 'charter_b64=%s\n' "$(encode < "$TMP/charter.remote")"
+  # The SSH alias reaching this host from the parent's own config, carried
+  # only so the remote-provisioned home can record durably that its parent
+  # lives on another machine (bin/fm-teardown.sh's cleanup gate). It is
+  # diagnostic identity, never a route the remote host could use to reach
+  # back; the parent's real filesystem path is never sent, since it names
+  # nothing on the remote filesystem.
+  printf 'parent_host_b64=%s\n' "$(printf '%s' "$HOST" | encode)"
+  printf 'project_count=%s\n' "${#PROJECT_NAMES[@]}"
+  cat "$TMP/project.records"
+} > "$TMP/manifest"
+MANIFEST_BYTES=$(LC_ALL=C wc -c < "$TMP/manifest" | tr -d ' ')
+[ "$MANIFEST_BYTES" -le "$MAX_MANIFEST_BYTES" ] \
+  || die "remote provisioning manifest exceeds the $MAX_MANIFEST_BYTES-byte bound"
+
+TODAY=$(date +%F)
+REG_TMP="$TMP/secondmates.next"
+if [ -f "$REG" ]; then grep -vE "^- $ID( |$)" "$REG" > "$REG_TMP" || true; else : > "$REG_TMP"; fi
+printf -- '- %s - %s (host: %s; root: %s; home: %s; scope: %s; projects: %s; added %s)\n' \
+  "$ID" "$SUMMARY" "$HOST" "$REMOTE_ROOT" "$REMOTE_HOME" "$SCOPE" "$PROJECTS_CSV" "$TODAY" >> "$REG_TMP"
+mv -f -- "$REG_TMP" "$REG"
+if ! secondmate_registry_validate_bindings "$REG" secondmate_registry_path_key "$ID" "$REMOTE_HOME"; then
+  if [ "$REG_EXISTED" -eq 1 ]; then cp "$TMP/registry.before" "$REG"; else rm -f -- "$REG"; fi
+  die "$SECONDMATE_REGISTRY_ERROR"
+fi
+
+restore_registry_and_brief() {
+  if [ "$REG_EXISTED" -eq 1 ]; then cp "$TMP/registry.before" "$REG"; else rm -f -- "$REG"; fi
+  [ "$BRIEF_CREATED" -eq 0 ] || rm -f -- "$BRIEF"
+}
+
+# Preflight and, where it can, repair the remote runtime before anything is
+# created on that host. The doctor runs through the same fixed entrypoint as
+# every later call, so it sees the exact PATH the remote home will run under.
+set +e
+fm_remote_readiness_ensure "$SCRIPT_DIR" "$ID"
+PREFLIGHT_RC=$?
+set -e
+if [ "$PREFLIGHT_RC" -ne 0 ]; then
+  if [ "$PREFLIGHT_RC" -ne 255 ]; then
+    restore_registry_and_brief
+  fi
+  [ -z "$FM_REMOTE_READINESS_OUT" ] || printf '%s\n' "$FM_REMOTE_READINESS_OUT" >&2
+  if [ "$PREFLIGHT_RC" -eq 255 ]; then
+    die "remote readiness completion is unknown; route and brief preserved for same-host reconciliation"
+  fi
+  die "remote runtime preflight failed; nothing was provisioned. Close the gaps listed above, or update the remote code root if it predates the current fm-remote-doctor.sh"
+fi
+
+set +e
+PROVISION_OUT=$("$SCRIPT_DIR/fm-on.sh" --stdin "$ID" fm-remote-home-provision.sh < "$TMP/manifest" 2>&1)
+PROVISION_RC=$?
+set -e
+if [ "$PROVISION_RC" -ne 0 ]; then
+  if [ "$PROVISION_RC" -ne 255 ]; then
+    restore_registry_and_brief
+  fi
+  [ -z "$PROVISION_OUT" ] || printf '%s\n' "$PROVISION_OUT" >&2
+  if [ "$PROVISION_RC" -eq 255 ]; then
+    die "remote provisioning completion is unknown; route preserved for same-host reconciliation"
+  fi
+  die "remote provisioning failed; registry restored"
+fi
+printf '%s\n' "$PROVISION_OUT"
+printf 'home=%s:%s\n' "$HOST" "$REMOTE_HOME"

package/.agents/backend/fm-remote-inherit-push.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Push the declared inherited-material allowlist to one remote secondmate route.
+# Usage: fm-remote-inherit-push.sh <secondmate-id> <generation>
+#
+# The item set is derived from the ONE declared owner
+# (FM_INHERITABLE_CONFIG in bin/fm-config-inherit-lib.sh), the same declaration
+# the receiving bin/fm-remote-inherit.sh enforces, so the two implementations in
+# one code revision cannot drift silently. Different local and remote revisions
+# fail closed as documented by that owner. FM_CONFIG_INHERIT_LIVE=1 marks a live
+# convergence push into an already-running home and skips session-scoped items,
+# exactly as the local propagation path does.
+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}}"
+CONFIG="${FM_CONFIG_OVERRIDE:-$FM_HOME/config}"
+DATA="${FM_DATA_OVERRIDE:-$FM_HOME/data}"
+
+# shellcheck source=bin/fm-secondmate-registry-lib.sh
+. "$SCRIPT_DIR/fm-secondmate-registry-lib.sh"
+# shellcheck source=bin/fm-config-inherit-lib.sh
+. "$SCRIPT_DIR/fm-config-inherit-lib.sh"
+
+die() { printf 'error: %s\n' "$1" >&2; exit 1; }
+sha256_file() {
+  if command -v shasum >/dev/null 2>&1; then shasum -a 256 "$1" | awk '{print $1}'; else sha256sum "$1" | awk '{print $1}'; fi
+}
+file_link_count() {
+  if [ "$(uname)" = Darwin ]; then stat -f %l "$1" 2>/dev/null; else stat -c %h "$1" 2>/dev/null; fi
+}
+shared_captain_header_valid() {
+  local head
+  head=$(sed -n '1,12p' "$1" 2>/dev/null) || return 1
+  case "$head" in *main-authoritative*) ;; *) return 1 ;; esac
+  case "$head" in *"read-only in secondmate homes"*) ;; *) return 1 ;; esac
+  case "$head" in *"must not be edited there"*) ;; *) return 1 ;; esac
+  case "$head" in *"main firstmate"*) ;; *) return 1 ;; esac
+  case "$head" in *"marked status"*|*"document pointer"*) ;; *) return 1 ;; esac
+}
+[ "$#" -eq 2 ] || { echo "usage: fm-remote-inherit-push.sh <secondmate-id> <generation>" >&2; exit 2; }
+ID=$1
+GENERATION=$2
+case "$ID" in ''|*[!A-Za-z0-9._-]*) die "invalid secondmate id: $ID" ;; esac
+case "$GENERATION" in ''|*[!0-9]*) die "generation must be a positive integer" ;; esac
+[ "${#GENERATION}" -le 18 ] && [ "$GENERATION" -ge 1 ] || die "generation is outside the supported range"
+REMOTE=$(secondmate_registry_field "$DATA/secondmates.md" "$ID" remote 2>/dev/null || true)
+[ "$REMOTE" = 1 ] || die "secondmate $ID is not a remote route"
+TMP=$(mktemp -d "${TMPDIR:-/tmp}/fm-remote-inherit-push.XXXXXX") || die "cannot create inheritance staging directory"
+trap 'rm -rf -- "$TMP"' EXIT
+EMPTY="$TMP/empty"
+: > "$EMPTY"
+EMPTY_HASH=$(sha256_file "$EMPTY") || die "cannot hash empty inheritance payload"
+
+ITEMS=$(fm_config_inherit_items)
+while IFS= read -r rel; do
+  [ -n "$rel" ] || continue
+  if [ "${FM_CONFIG_INHERIT_LIVE:-0}" = 1 ]; then
+    case "$rel" in
+      config/*)
+        if fm_config_inherit_item_session_scoped "${rel#config/}"; then
+          printf 'unchanged: %s\n' "$rel"
+          continue
+        fi
+        ;;
+    esac
+  fi
+  case "$rel" in
+    config/*) source="$CONFIG/${rel#config/}" ;;
+    data/*) source="$DATA/${rel#data/}" ;;
+  esac
+  if [ -e "$source" ] || [ -L "$source" ]; then
+    [ -f "$source" ] && [ ! -L "$source" ] || die "inherited source is unsafe: $source"
+    [ "$(file_link_count "$source")" = 1 ] || die "inherited source is hardlinked: $source"
+    if [ "$rel" = data/captain-shared.md ]; then
+      shared_captain_header_valid "$source" || die "shared captain preferences have no valid primary-authoritative header"
+    fi
+    snapshot="$TMP/$(printf '%s' "$rel" | tr '/' '_')"
+    cp -p -- "$source" "$snapshot" || die "cannot snapshot inherited source: $source"
+    [ -f "$snapshot" ] && [ ! -L "$snapshot" ] || die "inherited source snapshot is unsafe: $source"
+    bytes=$(LC_ALL=C wc -c < "$snapshot" | tr -d ' ')
+    hash=$(sha256_file "$snapshot") || die "cannot hash inherited source: $source"
+    "$SCRIPT_DIR/fm-on.sh" --stdin "$ID" fm-remote-inherit.sh put "$rel" "$bytes" "$hash" "$GENERATION" < "$snapshot"
+  else
+    # This loop's heredoc is its control stream, not remote command input.
+    "$SCRIPT_DIR/fm-on.sh" "$ID" fm-remote-inherit.sh absent "$rel" 0 "$EMPTY_HASH" "$GENERATION" < /dev/null
+  fi
+done <<EOF
+$ITEMS
+EOF