@zerwiz/ymir 0.1.4 → 0.1.5

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

@@ -0,0 +1,399 @@
+#!/usr/bin/env bash
+# fm-inbox.sh - the captain's out-of-band capture surface.
+#
+# Solves three DIFFERENT problems with three different mechanisms, because they
+# are not the same problem:
+#
+#   note    Queue an idea for firstmate while firstmate is mid-turn and cannot
+#           answer. Writes a durable record and appends ONE `check` wake, so the
+#           note survives a crash and is presented at firstmate's next drain.
+#           This is the only subcommand that touches firstmate's wake queue.
+#   say     Same as `note`, but the body comes from spoken audio on stdin.
+#           Speech is an INPUT METHOD here, not an architecture: it transcribes
+#           and then takes exactly the `note` path.
+#   status  Answer "what is happening" from durable records ONLY. Reads no
+#           network and appends NO wake, so it never interrupts work and is safe
+#           to run in a loop.
+#   ask     Answer a side question with a one-shot model call that never touches
+#           firstmate, the backlog, or the wake queue. A side question is not
+#           fleet work and must not become fleet work.
+#
+# Usage:
+#   fm-inbox.sh note <text>...          | fm-inbox.sh note -   (body from stdin)
+#   fm-inbox.sh say  [<file.wav>]       (default: audio on stdin)
+#   fm-inbox.sh status
+#   fm-inbox.sh ask  <question>...
+#   fm-inbox.sh list
+#   fm-inbox.sh drain [--ack <id>...]
+#
+# Configuration. A region, a model id and an AWS profile name somebody's account
+# and somebody's choices, so this file carries no default for any of them. Each is
+# read from the home's gitignored config/ directory, or from the matching
+# environment variable, and the model-backed subcommands refuse with the path to
+# write rather than reaching for a value that belongs to another home. That
+# configuration is also the opt-in: `say` and `ask` are off until it exists.
+#
+#   config/inbox-region     FM_INBOX_REGION     AWS region.            required
+#   config/inbox-stt-model  FM_INBOX_STT_MODEL  speech-to-text model.  required by say
+#   config/inbox-ask-model  FM_INBOX_ASK_MODEL  side-question model.   required by ask
+#   config/inbox-profile    FM_INBOX_PROFILE    AWS profile.           optional
+#
+# An absent profile means the call uses whatever credentials are already in the
+# environment, which is also what FM_INBOX_PROFILE= (empty) forces.
+#
+# `note`, `status`, `list` and `drain` need NO configuration at all, because they
+# make no model call. The voice handover depends on `note`, so it keeps working in
+# a home that has configured nothing.
+#
+# Environment:
+#   FM_HOME              operational home whose state/ and data/ are used.
+#
+# PRIVACY: `say` sends your audio and `ask` sends your question to Bedrock.
+# `note`, `status`, `list` and `drain` make no network call at all.
+#
+# `note` is also the queueing half of the spoken interface: when the voice agent
+# in bin/fm-voice-relay.py hands real work over to firstmate, it runs this
+# subcommand rather than carrying a second queue of its own. Keep the `note`
+# contract stable for that caller. `status` is the HUMAN view of the records;
+# bin/fm_voice_records.py owns the scope-controlled machine view the voice agent
+# reads, because the voice agent must be able to answer without record free text
+# ever reaching a model.
+set -euo pipefail
+
+# A non-interactive `ssh host fm-inbox.sh ...` does NOT get a login shell, so it
+# does not get ~/.toolbox/bin on PATH. The AWS profile's credential_process is
+# the bare word `ada`, so without this the model-backed subcommands fail with
+# "[Errno 2] No such file or directory: 'ada'" while note/status still work.
+# Verified: this is exactly what happens over SSH without the fix.
+for _extra in "$HOME/.toolbox/bin" "$HOME/.local/bin"; do
+  case ":$PATH:" in
+    *":$_extra:"*) ;;
+    *) [ -d "$_extra" ] && PATH="$_extra:$PATH" ;;
+  esac
+done
+unset _extra
+export PATH
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FM_ROOT="$(cd "$SELF_DIR/.." && pwd)"
+FM_HOME="${FM_HOME:-$FM_ROOT}"
+STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
+DATA="${FM_DATA_OVERRIDE:-$FM_HOME/data}"
+INBOX="$STATE/inbox"
+
+CONFIG="${FM_CONFIG_OVERRIDE:-$FM_HOME/config}"
+
+die() { printf 'fm-inbox: %s\n' "$*" >&2; exit 1; }
+
+# First non-comment, non-blank line of a config file, or nothing.
+read_setting() {  # <file-name>
+  local path="$CONFIG/$1" line
+  [ -r "$path" ] || return 0
+  while IFS= read -r line || [ -n "$line" ]; do
+    line=${line%%#*}
+    line=${line#"${line%%[![:space:]]*}"}
+    line=${line%"${line##*[![:space:]]}"}
+    [ -n "$line" ] || continue
+    printf '%s' "$line"
+    return 0
+  done < "$path"
+}
+
+# Refuse by naming the file to write. A model call that guessed at a region or an
+# account would either fail confusingly or, worse, succeed against a stranger's.
+require_setting() {  # <file-name> <env-var> <what>
+  local value
+  value=$(read_setting "$1")
+  [ -n "$value" ] || die "no $3 is configured: write one line into $CONFIG/$1 or set $2"
+  printf '%s' "$value"
+}
+
+REGION="${FM_INBOX_REGION:-}"
+STT_MODEL="${FM_INBOX_STT_MODEL:-}"
+ASK_MODEL="${FM_INBOX_ASK_MODEL:-}"
+# Unset falls through to config; explicitly empty means "use ambient credentials".
+PROFILE="${FM_INBOX_PROFILE-$(read_setting inbox-profile)}"
+
+# Resolved only by the subcommands that make a model call, so note, status, list
+# and drain keep working in a home that has configured nothing.
+need_region() {
+  [ -n "$REGION" ] || REGION=$(require_setting inbox-region FM_INBOX_REGION "AWS region")
+}
+
+need_stt_model() {
+  need_region
+  [ -n "$STT_MODEL" ] || STT_MODEL=$(require_setting inbox-stt-model \
+    FM_INBOX_STT_MODEL "speech-to-text model")
+}
+
+need_ask_model() {
+  need_region
+  [ -n "$ASK_MODEL" ] || ASK_MODEL=$(require_setting inbox-ask-model \
+    FM_INBOX_ASK_MODEL "side-question model")
+}
+
+need() { command -v "$1" >/dev/null 2>&1 || die "required command not found: $1"; }
+
+# The profile's credential_process (`ada`) costs a MEASURED ~1030ms on every
+# single call, which is about half the wall time of `say` and `ask`. If real
+# credentials are already in the environment, skip --profile entirely and let the
+# ambient ones win. Set FM_INBOX_PROFILE= (empty) to force that even without env
+# credentials present.
+aws_call() {
+  if [ -z "$PROFILE" ] || [ -n "${AWS_ACCESS_KEY_ID:-}" ]; then
+    aws --region "$REGION" "$@"
+  else
+    aws --profile "$PROFILE" --region "$REGION" "$@"
+  fi
+}
+
+# ---------------------------------------------------------------- note
+
+# Append exactly one wake so firstmate picks the note up at its next drain.
+# Failure to wake is NOT allowed to lose the note: the record is already on
+# disk, so we report the wake failure and still exit non-zero loudly.
+wake_for() {
+  local id=$1 summary=$2 lib="$FM_ROOT/bin/fm-wake-lib.sh"
+  if [ ! -r "$lib" ]; then
+    printf 'fm-inbox: note saved but NOT announced (missing %s)\n' "$lib" >&2
+    return 1
+  fi
+  # shellcheck source=/dev/null
+  FM_ROOT_OVERRIDE="$FM_ROOT" FM_HOME="$FM_HOME" STATE="$STATE" . "$lib"
+  fm_wake_append check "inbox:$id" "check: captain inbox note $id - $summary"
+}
+
+queue_note() {
+  local source=$1 body=$2 extra=${3:-}
+  [ -n "${body//[[:space:]]/}" ] || die "refusing to queue an empty note"
+  mkdir -p "$INBOX"
+
+  local tmp id summary staging_name
+  tmp=$(mktemp "$INBOX/.staging-XXXXXX")
+  staging_name=$(basename "$tmp")
+  id="$(date +%s)-${staging_name#.staging-}"
+  {
+    printf 'id=%s\n' "$id"
+    printf 'at=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    printf 'source=%s\n' "$source"
+    [ -z "$extra" ] || printf '%s\n' "$extra"
+    printf -- '--\n'
+    printf '%s\n' "$body"
+  } >"$tmp"
+
+  # Publish the completed note atomically.
+  mv "$tmp" "$INBOX/$id.note"
+
+  # One-line summary for the wake payload; the full body stays in the file.
+  summary=$(printf '%s' "$body" | tr '\n\t' '  ' | cut -c1-100)
+  printf 'queued %s\n' "$id"
+  printf '  %s\n' "$summary"
+  if wake_for "$id" "$summary"; then
+    printf '  firstmate will pick this up at its next check.\n'
+  else
+    die "note $id is saved at $INBOX/$id.note but firstmate was NOT woken"
+  fi
+}
+
+cmd_note() {
+  local body
+  if [ "$#" -eq 0 ]; then
+    die "usage: fm-inbox.sh note <text>...   (or: note - to read stdin)"
+  elif [ "$1" = "-" ]; then
+    body=$(cat)
+  else
+    body="$*"
+  fi
+  queue_note text "$body"
+}
+
+# ---------------------------------------------------------------- say
+
+cmd_say() {
+  # Before the tool checks, so an unconfigured home is told what to configure
+  # rather than what to install for a call it is not yet allowed to make.
+  need_stt_model
+  need aws
+  need python3
+  need base64
+
+  local src wav raw transcript
+  raw=$(mktemp /tmp/fm-inbox-audio-XXXXXX)
+  wav=$(mktemp /tmp/fm-inbox-wav-XXXXXX.wav)
+  # shellcheck disable=SC2064
+  trap "rm -f '$raw' '$wav' '$wav.json'" EXIT
+
+  if [ "$#" -ge 1 ] && [ "$1" != "-" ]; then
+    src=$1
+    [ -r "$src" ] || die "cannot read audio file: $src"
+    cat "$src" >"$raw"
+  else
+    cat >"$raw"
+  fi
+  [ -s "$raw" ] || die "no audio received on stdin"
+
+  # Accept a real WAV as-is; wrap headerless 16kHz mono s16le PCM if that is
+  # what arrived. Anything else is rejected rather than silently mistranscribed.
+  python3 - "$raw" "$wav" <<'PY'
+import sys, wave
+src, dst = sys.argv[1], sys.argv[2]
+data = open(src, 'rb').read()
+if data[:4] == b'RIFF':
+    open(dst, 'wb').write(data)
+    sys.stderr.write("fm-inbox: input is WAV, passing through\n")
+elif data[:4] in (b'OggS', b'fLaC') or data[:3] == b'ID3':
+    sys.exit("fm-inbox: got Ogg/FLAC/MP3; re-encode to WAV first")
+else:
+    if len(data) % 2:
+        data = data[:-1]
+    w = wave.open(dst, 'wb')
+    w.setnchannels(1); w.setsampwidth(2); w.setframerate(16000)
+    w.writeframes(data); w.close()
+    sys.stderr.write("fm-inbox: input looked like raw PCM, wrapped as 16kHz mono WAV\n")
+PY
+
+  local secs
+  secs=$(python3 -c "
+import wave,sys
+w=wave.open('$wav'); print(round(w.getnframes()/w.getframerate(),2))")
+  printf 'fm-inbox: %ss of audio, transcribing with %s in %s\n' "$secs" "$STT_MODEL" "$REGION" >&2
+
+  python3 - "$wav" "$wav.json" <<'PY'
+import base64, json, sys
+b = base64.b64encode(open(sys.argv[1], 'rb').read()).decode()
+json.dump([{"role": "user", "content": [
+    {"audio": {"format": "wav", "source": {"bytes": b}}},
+    {"text": "Transcribe the speech exactly. Output only the transcript, nothing else."},
+]}], open(sys.argv[2], 'w'))
+PY
+
+  transcript=$(aws_call bedrock-runtime converse \
+    --model-id "$STT_MODEL" \
+    --messages "file://$wav.json" \
+    --inference-config '{"maxTokens":600,"temperature":0}' \
+    --query 'output.message.content[0].text' --output text) \
+    || die "transcription failed"
+
+  [ -n "${transcript//[[:space:]]/}" ] || die "transcription came back empty"
+  printf 'fm-inbox: heard: %s\n' "$transcript" >&2
+  queue_note voice "$transcript" "transcript_model=$STT_MODEL
+audio_seconds=$secs"
+}
+
+# ---------------------------------------------------------------- status
+
+cmd_status() {
+  local pending=0
+  [ -d "$INBOX" ] && pending=$(find "$INBOX" -maxdepth 1 -name '*.note' 2>/dev/null | wc -l | tr -d ' ')
+
+  printf '=== firstmate status (read-only, no wake sent) ===\n'
+  printf 'home     %s\n' "$FM_HOME"
+  printf 'time     %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  printf 'inbox    %s note(s) waiting for firstmate\n' "$pending"
+
+  if [ -f "$DATA/backlog.md" ]; then
+    printf '\n--- in flight ---\n'
+    awk '/^## In flight/{f=1;next} /^## /{f=0} f && /^- \[/{print}' \
+      "$DATA/backlog.md" | sed 's/^- \[ \] /  /' | cut -c1-150
+  else
+    printf '\n(no backlog at %s)\n' "$DATA/backlog.md"
+  fi
+
+  local any=0
+  for m in "$STATE"/*.meta; do
+    [ -e "$m" ] || break
+    if [ "$any" -eq 0 ]; then printf '\n--- workers ---\n'; any=1; fi
+    local id kind mode last
+    id=$(basename "$m" .meta)
+    kind=$(sed -n 's/^kind=//p' "$m" | head -1)
+    mode=$(sed -n 's/^mode=//p' "$m" | head -1)
+    last=""
+    [ -f "$STATE/$id.status" ] && last=$(tail -1 "$STATE/$id.status" 2>/dev/null | cut -c1-100)
+    printf '  %-42s %-6s %-10s %s\n' "$id" "${kind:-?}" "${mode:--}" "${last:-(no events yet)}"
+  done
+  [ "$any" -eq 1 ] || printf '\n(no workers on deck)\n'
+
+  printf '\nNote: the last event line is history, not current state.\n'
+}
+
+# ---------------------------------------------------------------- ask
+
+cmd_ask() {
+  [ "$#" -gt 0 ] || die "usage: fm-inbox.sh ask <question>..."
+  need_ask_model
+  need aws
+  need python3
+  local q="$*" msg
+  msg=$(mktemp /tmp/fm-inbox-ask-XXXXXX.json)
+  # shellcheck disable=SC2064
+  trap "rm -f '$msg'" EXIT
+
+  Q="$q" python3 - "$msg" <<'PY'
+import json, os, sys
+json.dump([{"role": "user", "content": [{"text": os.environ["Q"]}]}],
+          open(sys.argv[1], 'w'))
+PY
+
+  aws_call bedrock-runtime converse \
+    --model-id "$ASK_MODEL" \
+    --messages "file://$msg" \
+    --system '[{"text":"You are a terse engineering assistant answering a side question. Be direct and concrete. No preamble. If you are not sure, say so."}]' \
+    --inference-config '{"maxTokens":700,"temperature":0.2}' \
+    --query 'output.message.content[0].text' --output text \
+    || die "ask failed"
+}
+
+# ---------------------------------------------------------------- list / drain
+
+cmd_list() {
+  [ -d "$INBOX" ] || { printf '(inbox empty)\n'; return 0; }
+  local any=0
+  for f in "$INBOX"/*.note; do
+    [ -e "$f" ] || break
+    any=1
+    printf '%s\n' "$(basename "$f" .note)"
+    sed -n '/^--$/,$p' "$f" | tail -n +2 | sed 's/^/    /'
+  done
+  [ "$any" -eq 1 ] || printf '(inbox empty)\n'
+}
+
+cmd_drain() {
+  if [ "${1:-}" = "--ack" ]; then
+    shift
+    [ "$#" -gt 0 ] || die "usage: fm-inbox.sh drain --ack <id>..."
+    mkdir -p "$INBOX/handled"
+    local id
+    for id in "$@"; do
+      if [ -f "$INBOX/$id.note" ]; then
+        mv "$INBOX/$id.note" "$INBOX/handled/$id.note"
+        printf 'acked %s\n' "$id"
+      else
+        printf 'already-acked %s\n' "$id"
+      fi
+    done
+    return 0
+  fi
+  cmd_list
+  printf '\nAck with: fm-inbox.sh drain --ack <id>...\n'
+}
+
+# ---------------------------------------------------------------- dispatch
+
+case "${1:-}" in
+  note)   shift; cmd_note "$@" ;;
+  say)    shift; cmd_say "$@" ;;
+  status) shift; cmd_status ;;
+  ask)    shift; cmd_ask "$@" ;;
+  list)   shift; cmd_list ;;
+  drain)  shift; cmd_drain "$@" ;;
+  ''|-h|--help|help)
+    # The whole header block, found rather than counted: everything after the
+    # shebang up to the first line that is not a comment. A fixed line range
+    # silently truncates this help the next time the header grows, and the last
+    # thing to fall off the end is the PRIVACY paragraph, which is the one place
+    # a new operator is told which subcommands send anything off this host.
+    awk 'NR == 1 { next }
+         /^#/ { sub(/^# ?/, ""); print; next }
+         { exit }' "${BASH_SOURCE[0]}" ;;
+  *) die "unknown subcommand: $1 (try --help)" ;;
+esac

package/.agents/backend/fm-install-actionlint.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# fm-install-actionlint.sh - install CI's pinned, verified actionlint build.
+#
+# Downloads the official GitHub release archive for the host OS/arch, verifies
+# its per-archive SHA-256 pin, and installs the binary into the destination
+# directory. Supported platforms: linux amd64/x86_64, linux arm64/aarch64,
+# darwin amd64/x86_64, darwin arm64/aarch64. Pins come from the official
+# actionlint release checksums file. Verification uses sha256sum when present,
+# otherwise shasum -a 256. An unsupported OS/arch or a missing pin fails
+# without downloading.
+#
+# Usage:
+#   fm-install-actionlint.sh <destination-directory>
+set -eu
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+VERSION="$("$ROOT/bin/fm-lint-workflows.sh" --required-version)"
+
+die() {
+  printf 'fm-install-actionlint.sh: %s\n' "$*" >&2
+  exit 1
+}
+
+DESTINATION=${1:?usage: fm-install-actionlint.sh <destination-directory>}
+
+os=$(uname -s)
+arch=$(uname -m)
+# SHA-256 pins are from actionlint_1.7.12_checksums.txt on the official
+# v1.7.12 release (https://github.com/rhysd/actionlint/releases/tag/v1.7.12).
+case "${os}-${arch}" in
+  Linux-x86_64|Linux-amd64)
+    ARCHIVE="actionlint_${VERSION}_linux_amd64.tar.gz"
+    SHA256=8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8
+    ;;
+  Linux-aarch64|Linux-arm64)
+    ARCHIVE="actionlint_${VERSION}_linux_arm64.tar.gz"
+    SHA256=325e971b6ba9bfa504672e29be93c24981eeb1c07576d730e9f7c8805afff0c6
+    ;;
+  Darwin-x86_64|Darwin-amd64)
+    ARCHIVE="actionlint_${VERSION}_darwin_amd64.tar.gz"
+    SHA256=5b44c3bc2255115c9b69e30efc0fecdf498fdb63c5d58e17084fd5f16324c644
+    ;;
+  Darwin-arm64|Darwin-aarch64)
+    ARCHIVE="actionlint_${VERSION}_darwin_arm64.tar.gz"
+    SHA256=aba9ced2dee8d27fecca3dc7feb1a7f9a52caefa1eb46f3271ea66b6e0e6953f
+    ;;
+  *)
+    die "unsupported platform ${os}-${arch}; need linux or darwin on amd64/x86_64 or arm64/aarch64"
+    ;;
+esac
+[ -n "$SHA256" ] || die "no pinned checksum for ${os}-${arch}"
+
+URL="https://github.com/rhysd/actionlint/releases/download/v${VERSION}/${ARCHIVE}"
+TMP=$(mktemp -d "${RUNNER_TEMP:-${TMPDIR:-/tmp}}/fm-actionlint.XXXXXX")
+trap 'rm -rf "$TMP"' EXIT
+
+DOWNLOAD_ATTEMPTS=6
+download_attempt=1
+while ! curl -fsSL "$URL" -o "$TMP/$ARCHIVE"; do
+  [ "$download_attempt" -lt "$DOWNLOAD_ATTEMPTS" ] || {
+    printf 'fm-install-actionlint.sh: download failed after %s attempts\n' "$DOWNLOAD_ATTEMPTS" >&2
+    exit 1
+  }
+  printf 'fm-install-actionlint.sh: download attempt %s failed; retrying\n' "$download_attempt" >&2
+  sleep $((1 << (download_attempt - 1)))
+  download_attempt=$((download_attempt + 1))
+done
+
+if command -v sha256sum >/dev/null 2>&1; then
+  ACTUAL_SHA256=$(sha256sum "$TMP/$ARCHIVE" | awk '{print $1}')
+elif command -v shasum >/dev/null 2>&1; then
+  ACTUAL_SHA256=$(shasum -a 256 "$TMP/$ARCHIVE" | awk '{print $1}')
+else
+  die "need sha256sum or shasum to verify the actionlint archive"
+fi
+[ "$ACTUAL_SHA256" = "$SHA256" ] || {
+  printf 'fm-install-actionlint.sh: checksum mismatch for %s (expected %s, got %s)\n' \
+    "$ARCHIVE" "$SHA256" "$ACTUAL_SHA256" >&2
+  exit 1
+}
+tar -xzf "$TMP/$ARCHIVE" -C "$TMP"
+mkdir -p "$DESTINATION"
+install -m 0755 "$TMP/actionlint" "$DESTINATION/actionlint"
+"$DESTINATION/actionlint" -version

package/.agents/backend/fm-install-herdr.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# fm-install-herdr.sh - install CI's pinned, verified Herdr build.
+#
+# Single owner of the exact Herdr version, official release asset URL, and
+# SHA-256 pin used by the required real-Herdr CI lane. Never installs a
+# floating package-manager latest.
+#
+# Usage:
+#   fm-install-herdr.sh <destination-directory>
+#
+# Pins Herdr v0.7.4 (protocol 16), the suite-verified protocol-16 release.
+# Selects the official GitHub Releases asset for the host OS/arch, downloads
+# with a bounded max size, verifies SHA-256 before install, then refuses to
+# finish unless the binary reports the exact pin version and a client protocol
+# at or above the required floor (16 for the real-Herdr family).
+set -eu
+
+# Exact pin - change only with a re-verified real-Herdr matrix.
+FM_HERDR_CI_VERSION=0.7.4
+FM_HERDR_CI_TAG="v${FM_HERDR_CI_VERSION}"
+FM_HERDR_CI_MIN_PROTOCOL=16
+# Bounded download ceiling (bytes). The largest official 0.7.4 asset is under 20 MiB.
+FM_HERDR_CI_MAX_BYTES=25000000
+FM_HERDR_CI_REPO=ogulcancelik/herdr
+
+die() {
+  printf 'fm-install-herdr.sh: %s\n' "$*" >&2
+  exit 1
+}
+
+DESTINATION=${1:?usage: fm-install-herdr.sh <destination-directory>}
+
+os=$(uname -s)
+arch=$(uname -m)
+case "${os}-${arch}" in
+  Linux-x86_64)
+    ASSET=herdr-linux-x86_64
+    SHA256=bc0fc02d4ba500f9cac2353a43e67fe036785ecca6eb55378e050fac3c103059
+    ;;
+  Linux-aarch64|Linux-arm64)
+    ASSET=herdr-linux-aarch64
+    SHA256=544e0002de42806d1ab64ccdef3a7e7414f24717b0b6b022bc9e57d2eefd26a2
+    ;;
+  Darwin-arm64)
+    ASSET=herdr-macos-aarch64
+    SHA256=24992e1625dbdcb18354a59e299e4b263c312400b31396cdc07cd46ed57f24a7
+    ;;
+  Darwin-x86_64)
+    ASSET=herdr-macos-x86_64
+    SHA256=ddf430133352e1712413d5d865b34a485546f4658893fc89986257d65a7585a8
+    ;;
+  *)
+    die "unsupported platform ${os}-${arch}; official Herdr assets are linux/macos x86_64 and aarch64"
+    ;;
+esac
+
+URL="https://github.com/${FM_HERDR_CI_REPO}/releases/download/${FM_HERDR_CI_TAG}/${ASSET}"
+TMP=$(mktemp -d "${RUNNER_TEMP:-${TMPDIR:-/tmp}}/fm-herdr.XXXXXX")
+trap 'rm -rf "$TMP"' EXIT
+
+printf 'fm-install-herdr.sh: downloading %s from %s\n' "$ASSET" "$URL" >&2
+# --fail: HTTP errors; --location: follow redirects; --max-filesize: bound.
+curl -fsSL --max-filesize "$FM_HERDR_CI_MAX_BYTES" "$URL" -o "$TMP/$ASSET" \
+  || die "download failed for $URL (bounded at $FM_HERDR_CI_MAX_BYTES bytes)"
+
+if command -v sha256sum >/dev/null 2>&1; then
+  ACTUAL_SHA256=$(sha256sum "$TMP/$ASSET" | awk '{print $1}')
+elif command -v shasum >/dev/null 2>&1; then
+  ACTUAL_SHA256=$(shasum -a 256 "$TMP/$ASSET" | awk '{print $1}')
+else
+  die "need sha256sum or shasum to verify the Herdr asset"
+fi
+
+[ "$ACTUAL_SHA256" = "$SHA256" ] || die "checksum mismatch for $ASSET (expected $SHA256, got $ACTUAL_SHA256)"
+
+mkdir -p "$DESTINATION"
+install -m 0755 "$TMP/$ASSET" "$DESTINATION/herdr"
+
+# Post-install version and protocol gates (no floating latest).
+installed_version=$("$DESTINATION/herdr" --version 2>/dev/null | awk '{print $2; exit}')
+[ "$installed_version" = "$FM_HERDR_CI_VERSION" ] \
+  || die "installed herdr version is '${installed_version:-<empty>}', expected exact pin $FM_HERDR_CI_VERSION"
+
+status=$("$DESTINATION/herdr" status --json 2>/dev/null) \
+  || die "could not run 'herdr status --json' after install"
+protocol=$(printf '%s' "$status" | jq -r '.client.protocol // empty' 2>/dev/null) \
+  || die "jq is required to parse herdr status after install"
+case "$protocol" in
+  ''|*[!0-9]*) die "could not read herdr client protocol from status --json" ;;
+esac
+[ "$protocol" -ge "$FM_HERDR_CI_MIN_PROTOCOL" ] \
+  || die "herdr protocol $protocol is below the required floor $FM_HERDR_CI_MIN_PROTOCOL"
+
+printf 'fm-install-herdr.sh: installed herdr %s (protocol %s) to %s\n' \
+  "$installed_version" "$protocol" "$DESTINATION/herdr" >&2
+"$DESTINATION/herdr" --version

package/.agents/backend/fm-install-shellcheck.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# fm-install-shellcheck.sh - install CI's pinned, verified ShellCheck build.
+#
+# Downloads the official GitHub release archive for the host OS/arch, verifies
+# its per-archive SHA-256 pin, and installs the binary into the destination
+# directory. Supported platforms: linux amd64/x86_64, linux arm64/aarch64,
+# darwin amd64/x86_64, darwin arm64/aarch64. Pins come from the official
+# ShellCheck release asset digests. Verification uses sha256sum when present,
+# otherwise shasum -a 256. An unsupported OS/arch or a missing pin fails
+# without downloading.
+#
+# Usage:
+#   fm-install-shellcheck.sh <destination-directory>
+set -eu
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+VERSION="$("$ROOT/bin/fm-lint.sh" --required-version)"
+
+die() {
+  printf 'fm-install-shellcheck.sh: %s\n' "$*" >&2
+  exit 1
+}
+
+DESTINATION=${1:?usage: fm-install-shellcheck.sh <destination-directory>}
+
+os=$(uname -s)
+arch=$(uname -m)
+# SHA-256 pins are the GitHub release asset digests for shellcheck v0.11.0
+# .tar.xz archives (https://github.com/koalaman/shellcheck/releases/tag/v0.11.0).
+case "${os}-${arch}" in
+  Linux-x86_64|Linux-amd64)
+    ARCHIVE="shellcheck-v${VERSION}.linux.x86_64.tar.xz"
+    SHA256=8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198
+    ;;
+  Linux-aarch64|Linux-arm64)
+    ARCHIVE="shellcheck-v${VERSION}.linux.aarch64.tar.xz"
+    SHA256=12b331c1d2db6b9eb13cfca64306b1b157a86eb69db83023e261eaa7e7c14588
+    ;;
+  Darwin-x86_64|Darwin-amd64)
+    ARCHIVE="shellcheck-v${VERSION}.darwin.x86_64.tar.xz"
+    SHA256=3c89db4edcab7cf1c27bff178882e0f6f27f7afdf54e859fa041fca10febe4c6
+    ;;
+  Darwin-arm64|Darwin-aarch64)
+    ARCHIVE="shellcheck-v${VERSION}.darwin.aarch64.tar.xz"
+    SHA256=56affdd8de5527894dca6dc3d7e0a99a873b0f004d7aabc30ae407d3f48b0a79
+    ;;
+  *)
+    die "unsupported platform ${os}-${arch}; need linux or darwin on amd64/x86_64 or arm64/aarch64"
+    ;;
+esac
+[ -n "$SHA256" ] || die "no pinned checksum for ${os}-${arch}"
+
+URL="https://github.com/koalaman/shellcheck/releases/download/v${VERSION}/${ARCHIVE}"
+TMP=$(mktemp -d "${RUNNER_TEMP:-${TMPDIR:-/tmp}}/fm-shellcheck.XXXXXX")
+trap 'rm -rf "$TMP"' EXIT
+
+DOWNLOAD_ATTEMPTS=6
+download_attempt=1
+while ! curl -fsSL "$URL" -o "$TMP/$ARCHIVE"; do
+  [ "$download_attempt" -lt "$DOWNLOAD_ATTEMPTS" ] || {
+    printf 'fm-install-shellcheck.sh: download failed after %s attempts\n' "$DOWNLOAD_ATTEMPTS" >&2
+    exit 1
+  }
+  printf 'fm-install-shellcheck.sh: download attempt %s failed; retrying\n' "$download_attempt" >&2
+  sleep $((1 << (download_attempt - 1)))
+  download_attempt=$((download_attempt + 1))
+done
+
+if command -v sha256sum >/dev/null 2>&1; then
+  ACTUAL_SHA256=$(sha256sum "$TMP/$ARCHIVE" | awk '{print $1}')
+elif command -v shasum >/dev/null 2>&1; then
+  ACTUAL_SHA256=$(shasum -a 256 "$TMP/$ARCHIVE" | awk '{print $1}')
+else
+  die "need sha256sum or shasum to verify the ShellCheck archive"
+fi
+[ "$ACTUAL_SHA256" = "$SHA256" ] || {
+  printf 'fm-install-shellcheck.sh: checksum mismatch for %s (expected %s, got %s)\n' \
+    "$ARCHIVE" "$SHA256" "$ACTUAL_SHA256" >&2
+  exit 1
+}
+tar -xJf "$TMP/$ARCHIVE" -C "$TMP"
+mkdir -p "$DESTINATION"
+install -m 0755 "$TMP/shellcheck-v${VERSION}/shellcheck" "$DESTINATION/shellcheck"
+"$DESTINATION/shellcheck" --version