@zerwiz/ymir 0.1.3 → 0.1.5

package/.agents/tests/gleipnir-guard-pretool-check.test.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Unit tests for the Sýn PreToolUse seatbelts:
+#   bin/syn-arm-pretool-check.sh   - the watcher arm is never backgrounded
+#   bin/syn-guard-pretool-check.sh - load-bearing invariants stay untouched
+set -u
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+ARM="$ROOT/bin/syn-arm-pretool-check.sh"
+GUARD="$ROOT/bin/syn-guard-pretool-check.sh"
+fail=0
+
+allows() {  # <script> <command>
+  if "$1" --command "$2" >/dev/null 2>&1; then :
+  else printf 'not ok - should allow: %s\n' "$2" >&2; fail=1; fi
+}
+denies() {  # <script> <command>
+  if "$1" --command "$2" >/dev/null 2>&1; then
+    printf 'not ok - should deny: %s\n' "$2" >&2; fail=1
+  fi
+}
+
+# --- arm seatbelt: real backgrounding vs chaining and syntax checks ----------
+
+allows "$ARM" 'bash -n bin/syn-watch-arm.sh && echo "syntax OK"'
+allows "$ARM" 'cat bin/syn-watch-arm.sh'
+allows "$ARM" 'echo "chained" && ls'
+denies "$ARM" 'bin/syn-watch-arm.sh --restart &'
+denies "$ARM" 'nohup bin/syn-watch-arm.sh --restart'
+denies "$ARM" 'setsid bin/syn-watch-arm.sh --restart'
+denies "$ARM" 'disown; bin/syn-watch-arm.sh --restart'
+
+# --- invariant seatbelt: destructive shapes are denied -----------------------
+
+denies "$GUARD" 'rm -f state/.lock'
+denies "$GUARD" 'echo 123 > state/.supervision-armed'
+denies "$GUARD" 'sed -i s/x/y/ workspace/memory/runes_audit.md'
+denies "$GUARD" 'rm -f bin/syn-watch-arm.sh'
+denies "$GUARD" 'cat .env.local'
+denies "$GUARD" 'git add .env.realm'
+denies "$GUARD" 'echo x > config/cron.yaml'
+
+# --- invariant seatbelt: reads and ordinary work are allowed -----------------
+
+allows "$GUARD" 'cat state/.lock'
+allows "$GUARD" 'rg wake state/.wake-queue'
+allows "$GUARD" 'git status'
+allows "$GUARD" 'bin/runes-append.sh brokk test --message hi'
+allows "$GUARD" 'bash -n bin/syn-guard-pretool-check.sh'
+
+[ "$fail" = 0 ] && echo "ALL PASS" || echo "FAILURES"
+exit "$fail"

package/.agents/tests/gleipnir-machine-lock.test.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# Unit tests for the machine-scoped primary session lock (bin/gleipnir-lock-lib.sh).
+#
+# The primary holds ONE machine-global lock so a second checkout of the same
+# machine cannot run a competing session; an Eindri-home keeps its own per-home
+# lock so workers run in parallel. A pre-contract session lives at the legacy
+# state/.lock and must still resolve during migration.
+set -u
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+LIB="$ROOT/bin/gleipnir-lock-lib.sh"
+fail=0
+ok()  { printf 'ok - %s\n' "$1"; }
+bad() { printf 'not ok - %s\n' "$1" >&2; fail=1; }
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+# --- path resolution ---------------------------------------------------------
+
+out=$(BROKK_HOME="$TMP/home" BROKK_MACHINE_STATE_DIR="$TMP/machine" \
+  bash -c '. "$0"; gleipnir_lock_path p; printf "%s" "$p"' "$LIB")
+[ "$out" = "$TMP/machine/brokk.lock" ] && ok "primary lock is machine-global" \
+  || bad "primary lock path: $out"
+
+mkdir -p "$TMP/ehome/data"; : > "$TMP/ehome/data/eindri-home"
+out=$(BROKK_HOME="$TMP/ehome" BROKK_MACHINE_STATE_DIR="$TMP/machine" \
+  bash -c '. "$0"; gleipnir_lock_path p; printf "%s" "$p"' "$LIB")
+[ "$out" = "$TMP/ehome/state/.lock" ] && ok "Eindri-home marker keeps a per-home lock" \
+  || bad "Eindri-home lock path: $out"
+
+out=$(BROKK_HOME_KIND=eindri BROKK_HOME="$TMP/ehome2" BROKK_MACHINE_STATE_DIR="$TMP/machine" \
+  bash -c '. "$0"; gleipnir_lock_path p; printf "%s" "$p"' "$LIB")
+[ "$out" = "$TMP/ehome2/state/.lock" ] && ok "BROKK_HOME_KIND=eindri keeps a per-home lock" \
+  || bad "env Eindri-home lock path: $out"
+
+# --- acquire writes the machine lock and the pointer -------------------------
+
+mkdir -p "$TMP/home/state"
+BROKK_HOME="$TMP/home" BROKK_MACHINE_STATE_DIR="$TMP/machine" BROKK_SESSION_PID="$$" \
+  bash -c '. "$0"; gleipnir_lock_acquire; gleipnir_lock_owner o; printf "%s" "$o"' "$LIB" > "$TMP/owner"
+[ "$(cat "$TMP/owner")" = "$$" ] && ok "acquire records the session pid" \
+  || bad "owner: $(cat "$TMP/owner")"
+[ -f "$TMP/machine/brokk.lock" ] && ok "machine lock file written" \
+  || bad "machine lock file missing"
+[ "$(cat "$TMP/home/state/.lock-path" 2>/dev/null)" = "$TMP/machine/brokk.lock" ] \
+  && ok "pointer records the resolved lock path" \
+  || bad "pointer missing or wrong"
+
+# --- a second session on the same machine is refused -------------------------
+
+out=$(BROKK_HOME="$TMP/other" BROKK_MACHINE_STATE_DIR="$TMP/machine" BROKK_SESSION_PID="1" \
+  bash -c '. "$0"; if gleipnir_lock_acquire; then printf acquired; else printf refused; fi' "$LIB")
+[ "$out" = "refused" ] && ok "a live machine lock refuses a second session" \
+  || bad "second session: $out"
+
+# --- migration: a legacy home lock is still honored --------------------------
+
+rm -f "$TMP/machine/brokk.lock"; mkdir -p "$TMP/home2/state"; printf '%s\n' "$$" > "$TMP/home2/state/.lock"
+out=$(BROKK_HOME="$TMP/home2" BROKK_MACHINE_STATE_DIR="$TMP/machine" \
+  bash -c '. "$0"; gleipnir_lock_owner o; printf "%s" "$o"' "$LIB")
+[ "$out" = "$$" ] && ok "legacy home lock is honored during migration" \
+  || bad "legacy owner: $out"
+
+# --- reap clears a dead machine lock -----------------------------------------
+
+mkdir -p "$TMP/machine"; printf '999999\n' > "$TMP/machine/brokk.lock"
+BROKK_HOME="$TMP/home" BROKK_MACHINE_STATE_DIR="$TMP/machine" \
+  bash -c '. "$0"; gleipnir_lock_reap' "$LIB" >/dev/null 2>&1
+[ -e "$TMP/machine/brokk.lock" ] && bad "stale machine lock not reaped" \
+  || ok "a dead machine lock is reaped"
+
+# --- acquire records a starttime sidecar --------------------------------------
+
+BROKK_HOME="$TMP/home" BROKK_MACHINE_STATE_DIR="$TMP/machine" BROKK_SESSION_PID="$$" \
+  bash -c '. "$0"; gleipnir_lock_acquire' "$LIB" >/dev/null 2>&1
+[ -s "$TMP/machine/brokk.lock.starttime" ] && ok "acquire records a starttime sidecar" \
+  || bad "starttime sidecar missing after acquire"
+
+# --- reap clears a lock whose recorded starttime no longer matches (pid reuse) --
+
+# Use a live unrelated process (this shell) with a deliberately wrong starttime:
+# liveness sees the pid "alive" via kill(0) but the recorded starttime belongs
+# to a process that is no longer the owner — i.e. the kernel recycled the pid.
+mkdir -p "$TMP/machine"; printf '%s\n' "$$" > "$TMP/machine/brokk.lock"
+printf '0\n' > "$TMP/machine/brokk.lock.starttime"
+BROKK_HOME="$TMP/home" BROKK_MACHINE_STATE_DIR="$TMP/machine" \
+  bash -c '. "$0"; gleipnir_lock_reap' "$LIB" >/dev/null 2>&1
+[ -e "$TMP/machine/brokk.lock" ] && bad "recycled-pid lock not reaped" \
+  || ok "a lock whose pid was recycled is reaped"
+
+# --- reap clears a lock held by a real zombie ---------------------------------
+
+# Fork a child, kill it, and keep the parent alive WITHOUT waiting: the child
+# becomes a zombie. kill(0) on a zombie succeeds — the old liveness checked
+# only that and missed the death; reap must now see the Z state and clear it.
+python3 -c '
+import os, signal, sys, time
+p = os.fork()
+if p == 0:
+    time.sleep(10); os._exit(0)
+else:
+    time.sleep(0.3)
+    os.kill(p, signal.SIGKILL)
+    time.sleep(0.3)
+    with open(sys.argv[1], "w") as h:
+        h.write(str(p))
+    time.sleep(30)
+' "$TMP/zombie.pid" &
+zombie_keeper=$!
+for _i in 1 2 3 4 5 6 7 8 9 10; do
+  [ -s "$TMP/zombie.pid" ] && break
+  sleep 0.2
+done
+zombie_pid=$(cat "$TMP/zombie.pid" 2>/dev/null || true)
+state=$(awk '{print $3}' "/proc/$zombie_pid/stat" 2>/dev/null)
+if [ -n "$zombie_pid" ] && [ "$state" = "Z" ]; then
+  printf '%s\n' "$zombie_pid" > "$TMP/machine/brokk.lock"
+  rm -f "$TMP/machine/brokk.lock.starttime"
+  BROKK_HOME="$TMP/home" BROKK_MACHINE_STATE_DIR="$TMP/machine" \
+    bash -c '. "$0"; gleipnir_lock_reap' "$LIB" >/dev/null 2>&1
+  [ -e "$TMP/machine/brokk.lock" ] && bad "zombie-held lock not reaped" \
+    || ok "a zombie-held lock is reaped (kill(0) alone cannot see this)"
+else
+  bad "test setup: expected a zombie child (got state ${state:-none})"
+fi
+kill "$zombie_keeper" 2>/dev/null || true
+
+[ "$fail" = 0 ] && echo "ALL PASS" || echo "FAILURES"
+exit "$fail"

package/.agents/tests/herdr-test-safety.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Compatibility source for real-Herdr tests.
+# The production owner of the isolation, refuse-default, teardown, and
+# fleet-state tripwire contract is bin/fm-herdr-lab.sh.
+set -u
+
+# Herdr backend tests drive the real fm-spawn/fm-teardown but do not source
+# tests/lib.sh, so exempt them from the gate-lifecycle refusal here too (see
+# tests/lib.sh and bin/fm-gate-refuse-lib.sh for why firstmate's own suite,
+# which the no-mistakes gate runs from a gate worktree, must be exempt).
+export FM_GATE_REFUSE_BYPASS=1
+
+HERDR_TEST_SAFETY_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+# shellcheck source=/dev/null
+. "$HERDR_TEST_SAFETY_DIR/bin/fm-herdr-lab.sh"
+
+# herdr_forget_inherited_pane: drop the Herdr PANE identity this test process
+# inherited from whatever terminal it was started in.
+#
+# Herdr injects HERDR_ENV, HERDR_PANE_ID, HERDR_TAB_ID, HERDR_WORKSPACE_ID,
+# HERDR_SOCKET_PATH, and HERDR_SESSION into every process it manages a pane for
+# (verified 0.7.5 - docs/verification/runtime-backends.md), and a test run from
+# inside a Herdr pane inherits all of them. Spawn now treats that pane as the
+# authoritative parent to place workers next to, so a leaked identity from the
+# developer's own session would follow the test into its isolated lab session
+# and be refused there as a cross-session parent - a result that depends on
+# where the suite was launched from, not on what it asserts.
+#
+# Call this before exporting the lab HERDR_SESSION in any suite whose subject is
+# the per-home container path. A suite that means to exercise a launcher-bound
+# spawn sets HERDR_PANE_ID itself, to a pane it created in its own lab session.
+herdr_forget_inherited_pane() {
+  unset HERDR_ENV HERDR_PANE_ID HERDR_TAB_ID HERDR_WORKSPACE_ID HERDR_SOCKET_PATH HERDR_SESSION
+}
+
+herdr_refuse_if_default() { # <session>
+  fm_herdr_lab_refuse_if_default "$1"
+}
+
+herdr_safe_stop_and_delete() { # <session>
+  fm_herdr_lab_teardown "$1"
+}

package/.agents/tests/lib.sh

@@ -0,0 +1,315 @@
+#!/usr/bin/env bash
+# tests/lib.sh - shared primitives for firstmate behavior tests.
+#
+# Source this from a test file:
+#   # shellcheck source=tests/lib.sh
+#   . "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+#
+# It provides the boilerplate every test file used to re-roll: ok/not-ok
+# reporters, a self-cleaning temp root, fakebin/PATH-shim helpers, deterministic
+# git identity and fixture builders, state/<id>.meta writers, and the common
+# string/exit-code/file assertions. Shared fake-toolchain and spawn-world
+# builders live in tests/fixtures.sh; wake-queue mocks in wake-helpers.sh;
+# secondmate-lifecycle mocks in secondmate-helpers.sh. Suite-specific fakes
+# that encode a single test's terminal or lifecycle assumptions still belong
+# with the tests that own them.
+#
+# ROOT is exported as the firstmate repo root (this file lives in tests/), so a
+# sourcing test can use "$ROOT/bin/..." without recomputing it.
+
+# Idempotent guard: behavior-area helper files (secondmate-helpers.sh,
+# wake-helpers.sh, fixtures.sh) source this library for ROOT/fail/pass, and the
+# test that includes them may also source it directly. Re-sourcing must not wipe
+# the registered-cleanup array or reset state.
+if [ -n "${FM_TEST_LIB_SOURCED:-}" ]; then
+  return 0
+fi
+FM_TEST_LIB_SOURCED=1
+
+# Exempt firstmate's own test suite from the gate-lifecycle refusal
+# (bin/fm-gate-refuse-lib.sh). The no-mistakes gate runs this suite FROM a gate
+# worktree - the exact environment that guard refuses - so without this every
+# test that drives the real fm-spawn/fm-send/fm-teardown would be refused during
+# firstmate's own validation. A confused gate agent never sources this helper, so
+# the boundary against the real hazard is unaffected. tests/fm-gate-refuse.test.sh
+# strips this to verify real refusal.
+export FM_GATE_REFUSE_BYPASS=1
+
+# Resolve the repo root from this library's own location. Consumed by sourcing
+# test files, not by this library, so it reads as "unused" here.
+# shellcheck disable=SC2034
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# --- reporters --------------------------------------------------------------
+
+fail() {
+  printf 'not ok - %s\n' "$1" >&2
+  exit 1
+}
+
+pass() {
+  printf 'ok - %s\n' "$1"
+}
+
+# --- self-cleaning temp root ------------------------------------------------
+#
+# fm_test_tmproot <prefix> echoes a fresh temp dir and registers it for removal
+# on EXIT/INT/TERM. A test file that needs extra teardown (e.g. killing a
+# daemon) should define its own EXIT trap and call fm_test_cleanup from inside
+# it so registered dirs are still removed.
+#
+# The call site is almost always `TMP_ROOT=$(fm_test_tmproot prefix)`, which
+# forks a subshell to capture stdout. Anything that function does to the
+# current shell's state - an array append, a trap - dies with that subshell
+# and never reaches the real caller, so registration cannot go through
+# in-process state. `$$` is the one thing bash keeps stable across that
+# boundary (it always resolves to the invoking shell's PID, not the
+# subshell's - see `man bash` on `$$`), so fm_test_tmproot records the
+# directory in a `$$`-keyed registry file instead, and the trap that reaps
+# that file is armed once, here, at source time - which always runs in the
+# real caller, never a subshell.
+
+FM_TEST_CLEANUP_DIRS=()
+FM_TEST_CLEANUP_REGISTRY=$(mktemp "${TMPDIR:-/tmp}/.fm-test-cleanup.$$.XXXXXX") || return 1
+
+fm_test_pid_identity() {
+  local pid=$1
+  FM_STATE_OVERRIDE="${TMPDIR:-/tmp}" bash -c \
+    '. "$1"; fm_pid_identity "$2"' _ "$ROOT/bin/fm-wake-lib.sh" "$pid"
+}
+
+FM_TEST_OWNER_IDENTITY=$(fm_test_pid_identity "$$") || {
+  rm -f "$FM_TEST_CLEANUP_REGISTRY"
+  return 1
+}
+
+fm_test_cleanup() {
+  local d
+  for d in "${FM_TEST_CLEANUP_DIRS[@]:-}"; do
+    [ -n "$d" ] && rm -rf "$d"
+  done
+  if [ -f "$FM_TEST_CLEANUP_REGISTRY" ]; then
+    while IFS= read -r d; do
+      [ -n "$d" ] && rm -rf "$d"
+    done < "$FM_TEST_CLEANUP_REGISTRY"
+    rm -f "$FM_TEST_CLEANUP_REGISTRY"
+  fi
+}
+
+fm_test_tmproot() {
+  local prefix=${1:-fm-test} root
+  root=$(mktemp -d "${TMPDIR:-/tmp}/${prefix}.XXXXXX") || return 1
+  if ! printf '%s\n%s\n' "$$" "$FM_TEST_OWNER_IDENTITY" > "$root/.fm-test-fixture" ||
+    ! printf '%s\n' "$root" >> "$FM_TEST_CLEANUP_REGISTRY"; then
+    rm -rf "$root"
+    return 1
+  fi
+  printf '%s\n' "$root"
+}
+
+trap fm_test_cleanup EXIT
+trap 'fm_test_cleanup; exit 130' INT
+trap 'fm_test_cleanup; exit 143' TERM
+
+# fm_test_reap_orphans: best-effort sweep for fixture roots left behind by a
+# prior run that was killed hard enough to skip the traps above (e.g. a
+# SIGKILL timeout). Only removes directories carrying the .fm-test-fixture
+# marker fm_test_tmproot writes, so it never touches unrelated fm-* tmp dirs
+# from real (non-test) firstmate commands. The marker identifies the owning
+# shell across PID reuse, so the same live owner always wins over the age
+# fallback for dead or unowned roots.
+FM_TEST_ORPHAN_MAX_AGE_SECONDS=${FM_TEST_ORPHAN_MAX_AGE_SECONDS:-3600}
+
+fm_test_reap_orphans() {
+  local marker dir mtime now owner_pid owner_identity current_identity
+  now=$(date +%s)
+  for marker in "${TMPDIR:-/tmp}"/fm-*/.fm-test-fixture; do
+    [ -e "$marker" ] || continue
+    owner_pid=$(sed -n '1p' "$marker" 2>/dev/null) || owner_pid=
+    owner_identity=$(sed -n '2,$p' "$marker" 2>/dev/null) || owner_identity=
+    case "$owner_pid" in
+      '' | *[!0-9]*) ;;
+      *)
+        current_identity=$(fm_test_pid_identity "$owner_pid" 2>/dev/null) || current_identity=
+        if [ -n "$owner_identity" ] && [ "$current_identity" = "$owner_identity" ]; then
+          continue
+        fi
+        ;;
+    esac
+    mtime=$(stat -c %Y "$marker" 2>/dev/null || stat -f %m "$marker" 2>/dev/null) || continue
+    [ $((now - mtime)) -ge "$FM_TEST_ORPHAN_MAX_AGE_SECONDS" ] || continue
+    dir=$(dirname "$marker")
+    if [ -d "$dir" ] && [ ! -L "$dir" ]; then
+      find "$dir" -type d -exec chmod u+rwx {} + 2>/dev/null || true
+    fi
+    rm -rf "$dir"
+  done
+}
+
+# A parent coordinator can reap once before it starts isolated child sections.
+# Those children use their own EXIT cleanup and must not spend their bounded
+# execution window repeating the same global stale-fixture scan.
+if [ "${FM_TEST_SKIP_ORPHAN_REAP:-0}" != 1 ]; then
+  fm_test_reap_orphans
+fi
+
+# --- fakebin / PATH shims ---------------------------------------------------
+#
+# fm_fakebin <dir> creates <dir>/fakebin and echoes it; prepend it to PATH to
+# shadow real tools with stubs. fm_fake_exit0 drops trivial exit-0 stubs for the
+# named tools into a fakebin dir. fm_fake_version_tool drops a stub for a tool
+# whose installed version bootstrap gates, so a fixture cannot be reported as an
+# unparseable build simply for answering `--version` with nothing.
+
+fm_fakebin() {
+  local dir=$1 fakebin="$1/fakebin"
+  mkdir -p "$fakebin"
+  printf '%s\n' "$fakebin"
+}
+
+fm_fake_exit0() {
+  local fakebin=$1 tool
+  shift
+  for tool in "$@"; do
+    cat > "$fakebin/$tool" <<'SH'
+#!/usr/bin/env bash
+exit 0
+SH
+    chmod +x "$fakebin/$tool"
+  done
+}
+
+# fm_fake_version_tool <fakebin> <tool> <override-env-var> <default-version>
+# The stub answers `--version` with <override-env-var> when that variable is set
+# and non-empty, and with <default-version> otherwise; every other invocation
+# exits 0. A case that needs to drive a version floor exports the variable.
+fm_fake_version_tool() {
+  local fakebin=$1 tool=$2 override=$3 default=$4
+  cat > "$fakebin/$tool" <<SH
+#!/usr/bin/env bash
+if [ "\${1:-}" = --version ]; then
+  printf '%s\n' "\${$override:-$default}"
+  exit 0
+fi
+exit 0
+SH
+  chmod +x "$fakebin/$tool"
+}
+
+# --- deterministic git identity and fixtures --------------------------------
+
+# fm_git_identity [name] [email]: export a fixed author/committer identity so
+# fixture commits never depend on the host git config.
+fm_git_identity() {
+  export GIT_AUTHOR_NAME=${1:-fmtest} GIT_AUTHOR_EMAIL=${2:-fmtest@example.invalid}
+  export GIT_COMMITTER_NAME=$GIT_AUTHOR_NAME GIT_COMMITTER_EMAIL=$GIT_AUTHOR_EMAIL
+}
+
+# fm_git_init_commit <dir>: create a git repo at <dir> with a README and one
+# commit. Uses an inline identity so it works whether or not fm_git_identity was
+# called.
+fm_git_init_commit() {
+  local dir=$1
+  mkdir -p "$dir"
+  git -C "$dir" init -q
+  printf '# %s\n' "$(basename "$dir")" > "$dir/README.md"
+  git -C "$dir" add README.md
+  git -C "$dir" -c user.name='Firstmate Tests' -c user.email='tests@example.invalid' commit -qm initial
+}
+
+# fm_git_add_origin <repo> <bare>: clone <repo> bare into <bare> and register it
+# as <repo>'s origin via a file:// URL (so later clones resolve an absolute path).
+fm_git_add_origin() {
+  local repo=$1 remote=$2 remote_abs
+  git clone --quiet --bare "$repo" "$remote"
+  remote_abs=$(cd "$remote" && pwd)
+  git -C "$repo" remote add origin "file://$remote_abs"
+}
+
+# fm_git_worktree <repo> <worktree> <branch>: initialize <repo> with one commit
+# and a local bare origin, then add a worktree on a fresh branch.
+fm_git_worktree() {
+  local repo=$1 worktree=$2 branch=$3
+  fm_git_init_commit "$repo"
+  fm_git_add_origin "$repo" "$repo.origin.git"
+  git -C "$repo" worktree add --quiet -b "$branch" "$worktree"
+}
+
+# --- state/<id>.meta writers ------------------------------------------------
+
+# fm_write_meta <file> <key=val> ...: write the given key=val lines to a meta
+# file (truncating any prior content).
+fm_write_meta() {
+  local file=$1 kv
+  shift
+  : > "$file"
+  for kv in "$@"; do
+    printf '%s\n' "$kv" >> "$file"
+  done
+}
+
+# fm_write_secondmate_meta <file> <home> [window] [projects] [harness]: write the
+# standard kind=secondmate meta block used across the secondmate suites. Window
+# defaults to firstmate:fm-<id>, projects defaults to alpha, and harness defaults
+# to echo to match the common case.
+fm_write_secondmate_meta() {
+  local file=$1 home=$2 id window projects=${4:-alpha} harness=${5:-echo}
+  id=$(basename "$file" .meta)
+  window=${3:-firstmate:fm-$id}
+  fm_write_meta "$file" \
+    "window=$window" \
+    "endpoint_task_id=$id" \
+    "worktree=$home" \
+    "project=$home" \
+    "harness=$harness" \
+    "kind=secondmate" \
+    "mode=secondmate" \
+    "yolo=off" \
+    "home=$home" \
+    "projects=$projects"
+}
+
+# --- common assertions ------------------------------------------------------
+
+# assert_contains <haystack> <needle> <msg>
+assert_contains() {
+  case "$1" in
+    *"$2"*) : ;;
+    *) fail "$3 (missing: '$2')"$'\n'"--- output ---"$'\n'"$1" ;;
+  esac
+}
+
+# assert_not_contains <haystack> <needle> <msg>
+assert_not_contains() {
+  case "$1" in
+    *"$2"*) fail "$3 (unexpected: '$2')"$'\n'"--- output ---"$'\n'"$1" ;;
+    *) : ;;
+  esac
+}
+
+# expect_code <expected> <actual> <label>
+expect_code() {
+  local expected=$1 actual=$2 label=$3
+  [ "$actual" = "$expected" ] || fail "$label: expected exit $expected, got $actual"
+}
+
+# assert_grep <pattern> <file> <msg>: fixed-string grep must match in <file>.
+# `--` guards patterns that begin with '-' (e.g. backlog/registry lines).
+assert_grep() {
+  grep -F -- "$1" "$2" >/dev/null || fail "$3"
+}
+
+# assert_no_grep <pattern> <file> <msg>: fixed-string grep must NOT match.
+assert_no_grep() {
+  ! grep -F -- "$1" "$2" >/dev/null || fail "$3"
+}
+
+# assert_absent <path> <msg>: path must not exist.
+assert_absent() {
+  [ ! -e "$1" ] || fail "$2"
+}
+
+# assert_present <path> <msg>: path must exist.
+assert_present() {
+  [ -e "$1" ] || fail "$2"
+}

package/.agents/tests/remote-herdr-fixture.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# tests/remote-herdr-fixture.sh - the stateful herdr CLI fixture the remote
+# second-mate suites install on their fake remote host.
+#
+# A remote second mate always launches on the Herdr backend
+# (docs/remote-secondmates.md), so a remote-route test needs a herdr CLI on the
+# remote code root's own bin directory. This fixture models the workspace, tab,
+# pane, and agent facts bin/backends/herdr.sh actually reads, backed by a JSON
+# state file mutated with real jq, using the same verified herdr behaviors as
+# tests/fm-backend-herdr.test.sh's stateful fake: workspace create seeds one
+# default tab and returns its tab and root pane in the same response, closing a
+# tab's only pane closes the tab, and agent get reports agent_not_found for a
+# pane no agent has registered on.
+#
+# Beyond that it models the pane IO a real launch performs. A pane reports a
+# registered agent once anything has been typed into it, and submitting starts
+# one turn: the next agent read reports working and the pane settles back to
+# idle, which is the native transition the adapter confirms a submit with.
+#
+# Usage:
+#   . "$(dirname "${BASH_SOURCE[0]}")/remote-herdr-fixture.sh"
+#   install_remote_herdr_fixture <remote-root> <state-file> <log-file> \
+#     <send-fail-flag> <socket-path>
+#
+# Every invocation is appended verbatim to <log-file>, so a test reads back what
+# the remote pane received. Creating <send-fail-flag> makes every pane write
+# fail, which is how a test simulates an endpoint that cannot be reached.
+
+install_remote_herdr_fixture() { # <remote-root> <state> <log> <send-fail> <socket>
+  local remote_root=$1 state=$2 log=$3 send_fail=$4 socket=$5 script="$1/bin/herdr"
+  mkdir -p "$remote_root/bin"
+  cat > "$script" <<SH
+#!/usr/bin/env bash
+set -u
+STATE='$state'
+LOG='$log'
+SEND_FAIL='$send_fail'
+SOCKET='$socket'
+SH
+  cat >> "$script" <<'SH'
+printf '%s\n' "$*" >> "$LOG"
+jq_state() { jq "$@" "$STATE"; }
+save() { tmp="$STATE.tmp.$$"; cat > "$tmp" && mv "$tmp" "$STATE"; }
+ws=""; label=""; cwd=""
+args=("$@")
+for ((i=0; i<${#args[@]}; i++)); do
+  case "${args[$i]}" in
+    --workspace) ws=${args[$((i+1))]:-} ;;
+    --label) label=${args[$((i+1))]:-} ;;
+    --cwd) cwd=${args[$((i+1))]:-} ;;
+  esac
+done
+case "${1:-} ${2:-}" in
+  "status --json")
+    printf '{"client":{"version":"0.7.5","protocol":16},"server":{"running":true}}\n' ;;
+  "server "*|"server") : ;;
+  "workspace list") jq_state '{result:{workspaces:.workspaces}}' ;;
+  "workspace create")
+    n=$(jq_state -r '.next'); wsid="w$n"; dn=$((n + 1))
+    jq_state --arg wsid "$wsid" --arg wlabel "$label" --arg cwd "$cwd" \
+      --arg tabid "$wsid:t$dn" --arg paneid "$wsid:p$dn" \
+      '.workspaces += [{workspace_id:$wsid, label:$wlabel, cwd:$cwd}]
+       | .tabs += [{tab_id:$tabid, label:"1", workspace_id:$wsid, pane_id:$paneid}]
+       | .next = (.next + 2)' | save
+    printf '{"result":{"workspace":{"workspace_id":"%s","label":"%s"},"tab":{"tab_id":"%s"},"root_pane":{"pane_id":"%s"}}}\n' \
+      "$wsid" "$label" "$wsid:t$dn" "$wsid:p$dn"
+    ;;
+  "tab list") jq_state --arg w "$ws" '{result:{tabs:[.tabs[]|select(.workspace_id==$w)]}}' ;;
+  "tab create")
+    n=$(jq_state -r '.next'); tabid="$ws:t$n"; paneid="$ws:p$n"
+    jq_state --arg w "$ws" --arg wlabel "$label" --arg cwd "$cwd" --arg tabid "$tabid" --arg paneid "$paneid" \
+      '.tabs += [{tab_id:$tabid, label:$wlabel, workspace_id:$w, pane_id:$paneid, cwd:$cwd}]
+       | .next = (.next + 1)' | save
+    printf '{"result":{"tab":{"tab_id":"%s"},"root_pane":{"pane_id":"%s"}}}\n' "$tabid" "$paneid"
+    ;;
+  "tab close")
+    jq_state --arg t "${3:-}" '.tabs |= [.[]|select(.tab_id != $t)]' | save ;;
+  "pane list")
+    jq_state --arg w "$ws" '{result:{panes:[.tabs[]|select(.workspace_id==$w)|{pane_id:.pane_id, tab_id:.tab_id}]}}' ;;
+  "pane get")
+    pane=${3:-}
+    if [ "$(jq_state -r --arg p "$pane" '[.tabs[]|select(.pane_id==$p)]|length')" = 0 ]; then
+      printf '{"error":{"code":"pane_not_found","message":"%s"}}\n' "$pane"
+    else
+      printf '{"result":{"pane":{"pane_id":"%s"}}}\n' "$pane"
+    fi
+    ;;
+  "pane close")
+    jq_state --arg p "${3:-}" \
+      '.tabs |= [.[]|select(.pane_id != $p)]
+       | .typed |= with_entries(select(.key != $p))
+       | .working |= with_entries(select(.key != $p))' | save ;;
+  "pane send-text")
+    [ ! -f "$SEND_FAIL" ] || exit 1
+    jq_state --arg p "${3:-}" '.typed[$p] = true' | save ;;
+  "pane send-keys")
+    [ ! -f "$SEND_FAIL" ] || exit 1
+    jq_state --arg p "${3:-}" '.typed[$p] = true | .working[$p] = true' | save ;;
+  "pane read") printf '\n' ;;
+  "pane process-info") printf '{"result":{"process":{"name":"codex"}}}\n' ;;
+  "agent get")
+    pane=${3:-}
+    if [ "$(jq_state -r --arg p "$pane" '.working[$p] // false')" = true ]; then
+      jq_state --arg p "$pane" '.working |= with_entries(select(.key != $p))' | save
+      printf '{"result":{"agent":{"agent_status":"working"}}}\n'
+    elif [ "$(jq_state -r --arg p "$pane" '.typed[$p] // false')" = true ]; then
+      printf '{"result":{"agent":{"agent_status":"idle"}}}\n'
+    else
+      printf '{"error":{"code":"agent_not_found","message":"%s"}}\n' "$pane"
+    fi
+    ;;
+  "session list"*)
+    printf '{"sessions":[{"name":"default","running":true,"socket_path":"%s"},{"name":"fm-remote","running":true,"socket_path":"%s"}]}\n' "$SOCKET" "$SOCKET" ;;
+esac
+exit 0
+SH
+  chmod +x "$script"
+  reset_remote_herdr_fixture "$state"
+}
+
+# reset_remote_herdr_fixture <state>: return the fake host to "no workspaces,
+# tabs, or panes", which is what a test means by "the previous endpoint is gone".
+reset_remote_herdr_fixture() { # <state>
+  printf '{"next":1,"workspaces":[],"tabs":[],"typed":{},"working":{}}\n' > "$1"
+}