@zerwiz/ymir 0.1.4 → 0.1.7

package/.agents/tests/fm-remote-secondmate-parent-binding.test.sh

@@ -0,0 +1,326 @@
+#!/usr/bin/env bash
+# tests/fm-remote-secondmate-parent-binding.test.sh - regression coverage for the
+# fm-remote-sm-cleanup-parent-binding-s1 scout report: finished-worker cleanup
+# inside a REMOTE second-mate home refused forever with "cannot resolve the
+# primary home ... durable parent binding", because the remote launch hands the
+# child the remote code checkout as its parent home (bin/fm-spawn.sh's sole
+# writer of FM_PUBLIC_FOLLOWUP_PRIMARY_HOME receives FM_HOME=$FM_ROOT from
+# bin/fm-remote-secondmate-control.sh's host-local launch), and that path can
+# never carry the parent's real state or registry.
+#
+# The fix (report section 7, captain-approved same-machine scope): a durable
+# .fm-secondmate-parent record, written once at seeding next to the
+# .fm-secondmate-home identity marker, names this home's route to its parent as
+# "local" or "remote". bin/fm-teardown.sh's cleanup gate reads it and treats a
+# remote parent as OUT OF SCOPE (never refuses purely for being cross-machine,
+# since the whole promised-public-reply subsystem is same-filesystem by
+# construction) while still refusing on a genuine same-filesystem signal
+# committed directly to this home's own .env file - never on an unrelated
+# process-environment export, which is what let the remote host's own login
+# shell mask into this home's binding before.
+#
+# This drives the REAL remote route (fm-remote-home-seed.sh -> fm-on.sh ->
+# fm-remote-entrypoint.sh -> the host-local fm-remote-secondmate-control.sh ->
+# the real bin/fm-spawn.sh --secondmate) across the repo's own deterministic SSH
+# boundary and Herdr fixture, then runs the real bin/fm-teardown.sh for a
+# finished child worker inside the produced remote home - never source-text
+# matching.
+set -u
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+# shellcheck source=tests/remote-herdr-fixture.sh
+. "$(dirname "${BASH_SOURCE[0]}")/remote-herdr-fixture.sh"
+
+command -v jq >/dev/null 2>&1 || { echo "skip: jq not found"; exit 0; }
+
+TMP_ROOT=$(fm_test_tmproot fm-remote-parent-binding)
+mkdir -p "$TMP_ROOT"
+TMP_ROOT=$(cd "$TMP_ROOT" && pwd -P)
+PARENT="$TMP_ROOT/parent"
+REMOTE_ROOT="$TMP_ROOT/remote-root"
+REMOTE_HOME="$TMP_ROOT/remote-home"
+FAKEBIN=$(fm_fakebin "$TMP_ROOT/fake")
+SSH_COUNT="$TMP_ROOT/ssh.count"
+DOCTOR_LOG="$TMP_ROOT/doctor.log"
+HERDR_STATE="$TMP_ROOT/remote-herdr.state"
+HERDR_LOG="$TMP_ROOT/remote-herdr.log"
+CLAIMS="$TMP_ROOT/claims"
+PUBLISH_PID=
+mkdir -p "$PARENT/data" "$PARENT/state" "$PARENT/config" "$PARENT/projects" "$REMOTE_ROOT" "$CLAIMS"
+
+cleanup() {
+  local worker_pid=''
+  if [ -n "$PUBLISH_PID" ]; then
+    touch "$PUBLISH_RELEASE" 2>/dev/null || true
+    kill "$PUBLISH_PID" 2>/dev/null || true
+    wait "$PUBLISH_PID" 2>/dev/null || true
+  fi
+  FM_HOME="$PARENT" FM_PROCEVENT_CLAIM_ROOT="$CLAIMS" \
+    "$ROOT/bin/fm-procevent.sh" sweep-home >/dev/null 2>&1 || true
+  if [ -f "$TMP_ROOT/remote-jobs/worker.pid" ]; then
+    worker_pid=$(cat "$TMP_ROOT/remote-jobs/worker.pid")
+    kill "$worker_pid" 2>/dev/null || true
+  fi
+  rm -rf -- "$TMP_ROOT"
+}
+trap cleanup EXIT
+
+PUBLISH_HOME="$TMP_ROOT/publication-home"
+PUBLISH_FAKEBIN=$(fm_fakebin "$TMP_ROOT/publication-fake")
+PUBLISH_ENTERED="$TMP_ROOT/publication-marker-entered"
+PUBLISH_RELEASE="$TMP_ROOT/publication-marker-release"
+PUBLISH_MANIFEST="$TMP_ROOT/publication.manifest"
+REAL_MV=$(command -v mv)
+cat > "$PUBLISH_FAKEBIN/mv" <<'SH'
+#!/usr/bin/env bash
+destination=${!#}
+case "$destination" in
+  */.fm-secondmate-home)
+    touch "$FM_TEST_PUBLISH_ENTERED"
+    while [ ! -f "$FM_TEST_PUBLISH_RELEASE" ]; do sleep 0.02; done
+    ;;
+esac
+exec "$FM_TEST_REAL_MV" "$@"
+SH
+chmod +x "$PUBLISH_FAKEBIN/mv"
+printf 'schema=fm-remote-home-provision.v1\nid_b64=%s\ncharter_b64=%s\nparent_host_b64=%s\nproject_count=0\n' \
+  "$(printf publication | base64 | tr -d '\n')" \
+  "$(printf 'Publication-order regression charter.\n' | base64 | tr -d '\n')" \
+  "$(printf publish-host | base64 | tr -d '\n')" > "$PUBLISH_MANIFEST"
+PATH="$PUBLISH_FAKEBIN:$PATH" FM_HOME="$PUBLISH_HOME" FM_ROOT_OVERRIDE="$ROOT" \
+  FM_TEST_REAL_MV="$REAL_MV" FM_TEST_PUBLISH_ENTERED="$PUBLISH_ENTERED" \
+  FM_TEST_PUBLISH_RELEASE="$PUBLISH_RELEASE" \
+  "$ROOT/bin/fm-remote-home-provision.sh" < "$PUBLISH_MANIFEST" >/dev/null 2>&1 &
+PUBLISH_PID=$!
+publish_wait=0
+while [ ! -f "$PUBLISH_ENTERED" ]; do
+  kill -0 "$PUBLISH_PID" 2>/dev/null || fail "remote provisioning exited before its completion marker"
+  publish_wait=$((publish_wait + 1))
+  [ "$publish_wait" -le 250 ] || fail "remote provisioning never reached its completion marker"
+  sleep 0.02
+done
+cmp -s "$PUBLISH_HOME/.fm-secondmate-parent" <(
+  printf 'schema=fm-secondmate-parent.v1\nroute=remote\nparent_host=publish-host\n'
+) || fail "remote provisioning exposed completion before publishing the durable parent record"
+assert_absent "$PUBLISH_HOME/.fm-secondmate-home" \
+  "the remote identity marker must remain absent until durable parent publication completes"
+touch "$PUBLISH_RELEASE"
+wait "$PUBLISH_PID" || fail "remote provisioning failed after publishing durable state"
+PUBLISH_PID=
+assert_present "$PUBLISH_HOME/.fm-secondmate-home" \
+  "remote provisioning must publish its identity marker as the completion point"
+pass "remote provisioning publishes durable parent state before its completion marker"
+
+# --- the remote host's tracked code root, real git repos, one project --------
+(
+  cd "$ROOT" || exit
+  tar --exclude=.git --exclude=.no-mistakes --exclude=data --exclude=state --exclude=config -cf - .
+) | (cd "$REMOTE_ROOT" && tar -xf -)
+install_remote_herdr_fixture "$REMOTE_ROOT" "$HERDR_STATE" "$HERDR_LOG" \
+  "$TMP_ROOT/herdr-send-fail" "$TMP_ROOT/herdr.sock"
+git -C "$REMOTE_ROOT" init -q -b main
+git -C "$REMOTE_ROOT" config user.email test@example.com
+git -C "$REMOTE_ROOT" config user.name Test
+git -C "$REMOTE_ROOT" add .
+git -C "$REMOTE_ROOT" commit -qm 'remote fixture root'
+REMOTE_ORIGIN="$TMP_ROOT/firstmate-origin.git"
+git init -q --bare "$REMOTE_ORIGIN"
+git -C "$REMOTE_ROOT" remote add origin "file://$REMOTE_ORIGIN"
+git -C "$REMOTE_ROOT" push -q -u origin main
+git --git-dir="$REMOTE_ORIGIN" symbolic-ref HEAD refs/heads/main
+
+git init -q --bare "$TMP_ROOT/alpha.git"
+git -C "$PARENT/projects" init -q -b main alpha
+git -C "$PARENT/projects/alpha" config user.email test@example.com
+git -C "$PARENT/projects/alpha" config user.name Test
+printf 'alpha\n' > "$PARENT/projects/alpha/README.md"
+git -C "$PARENT/projects/alpha" add README.md
+git -C "$PARENT/projects/alpha" commit -qm init
+git -C "$PARENT/projects/alpha" remote add origin "file://$TMP_ROOT/alpha.git"
+git -C "$PARENT/projects/alpha" push -q -u origin main
+git --git-dir="$TMP_ROOT/alpha.git" symbolic-ref HEAD refs/heads/main
+printf -- '- alpha [direct-PR] - alpha project (added 2026-08-04)\n' > "$PARENT/data/projects.md"
+printf 'codex\n' > "$PARENT/config/secondmate-harness"
+printf 'tmux\n' > "$PARENT/config/backend"
+
+# The primary home is the X-mode / relay home: the captain's real activation.
+printf 'FMX_PAIRING_TOKEN=repro-token\n' > "$PARENT/.env"
+
+# --- deterministic SSH boundary, identical shape to the lifecycle e2e suite --
+cat > "$FAKEBIN/fake-ssh" <<'SH'
+#!/usr/bin/env bash
+count=$(cat "$FM_FAKE_SSH_COUNT" 2>/dev/null || echo 0)
+printf '%s\n' "$((count + 1))" > "$FM_FAKE_SSH_COUNT"
+while [ "$#" -gt 0 ]; do
+  case "$1" in -o) shift 2 ;; --) shift; break ;; *) exit 90 ;; esac
+done
+host=$1
+entry=$2
+shift 2
+[ "$host" = remote-mac ] || exit 91
+[ "$entry" = fm-remote-entrypoint.sh ] || exit 92
+cd "$FM_FAKE_REMOTE_CWD" || exit 93
+argv_b64=$4
+command_fields=$(perl -MMIME::Base64=decode_base64 -e '
+  my $data=decode_base64($ARGV[0]);
+  my @args=split(/\0/, $data);
+  print join("\t", map { defined $_ ? $_ : "" } @args[0..2]);
+' "$argv_b64")
+IFS=$'\t' read -r command_name _command_action command_rel <<EOF
+$command_fields
+EOF
+if [ "$command_name" = fm-remote-doctor.sh ]; then
+  printf 'check herdr=ok: /usr/bin/herdr\n'
+  printf 'ok: remote second-mate readiness confirmed on this host\n'
+  exit 0
+fi
+if [ "$command_name" = fm-remote-secondmate-control.sh ] \
+   && [ "$_command_action" = launch ] \
+   && [ -n "${FM_TEST_PUBLICATION_TARGET:-}" ]; then
+  out=$("$FM_FAKE_REMOTE_ENTRYPOINT" "$@")
+  rc=$?
+  rm -f "$FM_TEST_PUBLICATION_TARGET"
+  ln -s "$FM_TEST_PUBLICATION_FOREIGN" "$FM_TEST_PUBLICATION_TARGET" || exit 94
+  printf '%s\n' "$out"
+  exit "$rc"
+fi
+exec "$FM_FAKE_REMOTE_ENTRYPOINT" "$@"
+SH
+chmod +x "$FAKEBIN/fake-ssh"
+
+remote_env() {
+  FM_HOME="$PARENT" \
+  FM_ROOT_OVERRIDE="$REMOTE_ROOT" \
+  FM_PROCEVENT_CLAIM_ROOT="$CLAIMS" \
+  FM_SSH_BIN="$FAKEBIN/fake-ssh" \
+  FM_FAKE_SSH_COUNT="$SSH_COUNT" \
+  FM_FAKE_REMOTE_ENTRYPOINT="$REMOTE_ROOT/bin/fm-remote-entrypoint.sh" \
+  FM_REMOTE_JOB_PLATFORM_OVERRIDE=Linux \
+  FM_REMOTE_JOB_STATE_ROOT="$TMP_ROOT/remote-jobs" \
+  FM_FAKE_REMOTE_CWD="$TMP_ROOT" \
+  FM_FAKE_DOCTOR_LOG="$DOCTOR_LOG" \
+  FM_SEND_SETTLE=0 FM_SEND_SLEEP=0 \
+  "$@"
+}
+
+FM_SECONDMATE_CHARTER='Own iOS delivery on the build Mac.' \
+  FM_SECONDMATE_SCOPE='iOS implementation and Xcode validation' \
+  remote_env "$ROOT/bin/fm-remote-home-seed.sh" ios remote-mac "$REMOTE_ROOT" "$REMOTE_HOME" alpha \
+  >/dev/null || fail "real remote secondmate seeding failed"
+
+# --- the durable record itself: the fundamental part of the fix -------------
+assert_present "$REMOTE_HOME/.fm-secondmate-parent" \
+  "real remote provisioning must write a durable parent record"
+cmp -s "$REMOTE_HOME/.fm-secondmate-parent" <(
+  printf 'schema=fm-secondmate-parent.v1\nroute=remote\nparent_host=remote-mac\n'
+) || fail "real remote provisioning must write the exact durable remote parent record"
+
+remote_env "$ROOT/bin/fm-spawn.sh" ios --secondmate >/dev/null \
+  || fail "real remote secondmate launch failed"
+
+DELIVERED_LINE=$(grep -F 'FM_PUBLIC_FOLLOWUP_PRIMARY_HOME' "$HERDR_LOG" | tail -1 || true)
+DELIVERED=$(printf '%s\n' "$DELIVERED_LINE" | tr ' ' '\n' \
+  | sed -n "s/^FM_PUBLIC_FOLLOWUP_PRIMARY_HOME='\{0,1\}\([^']*\)'\{0,1\}\$/\1/p" | tail -1)
+[ -n "$DELIVERED" ] || fail "the remote launch did not deliver a primary-home binding to assert against"
+case "$DELIVERED" in
+  "$REMOTE_ROOT") : ;;
+  *) fail "test setup drifted: expected the remote code root to be delivered as the (wrong) parent binding, got: $DELIVERED" ;;
+esac
+
+# --- a finished child worker inside the remote secondmate home --------------
+CHILD_WT="$REMOTE_HOME/projects/alpha"
+mkdir -p "$REMOTE_HOME/state"
+# This regression exercises remote-parent binding, not backlog mutation. Keep
+# its synthetic child home on the supported hand-edited backend so teardown's
+# fused automatic close is correctly exempt without requiring a tasks-axi mock.
+printf '%s\n' manual > "$REMOTE_HOME/config/backlog-backend"
+write_child_meta() {
+  fm_write_meta "$REMOTE_HOME/state/work-child.meta" \
+    "window=firstmate:fm-work-child" "endpoint_task_id=work-child" \
+    "worktree=$CHILD_WT" "project=$CHILD_WT" "harness=codex" "kind=ship" \
+    "mode=local-only" "yolo=off"
+}
+mkdir -p "$TMP_ROOT/childfake"
+for t in tmux treehouse no-mistakes gh gh-axi tasks-axi; do
+  printf '#!/usr/bin/env bash\nexit 0\n' > "$TMP_ROOT/childfake/$t"
+  chmod +x "$TMP_ROOT/childfake/$t"
+done
+
+run_child_teardown() { # <extra env assignments...>
+  local out rc=0
+  write_child_meta
+  out=$(env "$@" PATH="$TMP_ROOT/childfake:$PATH" \
+    FM_HOME="$REMOTE_HOME" FM_STATE_OVERRIDE="$REMOTE_HOME/state" \
+    FM_DATA_OVERRIDE="$REMOTE_HOME/data" FM_CONFIG_OVERRIDE="$REMOTE_HOME/config" \
+    "$REMOTE_ROOT/bin/fm-teardown.sh" work-child 2>&1) || rc=$?
+  CHILD_TEARDOWN_OUT=$out
+  CHILD_TEARDOWN_RC=$rc
+}
+
+# Case B-equivalent: the delivered (wrong) binding points at the remote code
+# root, and that root itself carries an X-mode .env - a plausible real-world
+# state (a captain who also runs Firstmate directly on the build Mac). Before
+# the fix this refused; the durable record now makes it out of scope.
+printf 'FMX_PAIRING_TOKEN=remote-host-token\n' > "$REMOTE_ROOT/.env"
+run_child_teardown FM_PUBLIC_FOLLOWUP_PRIMARY_HOME="$DELIVERED"
+rm -f "$REMOTE_ROOT/.env"
+[ "$CHILD_TEARDOWN_RC" -eq 0 ] \
+  || fail "a remote-routed child must allow cleanup when only the remote code root looks relay-active (rc=$CHILD_TEARDOWN_RC): $CHILD_TEARDOWN_OUT"
+assert_not_contains "$CHILD_TEARDOWN_OUT" "cannot resolve the primary home" \
+  "a cross-machine parent must never be reported as an unresolved binding"
+pass "a remote secondmate's finished worker cleans up when the remote code root's own .env looked relay-active"
+
+# Case C-equivalent: FMX_PAIRING_TOKEN exported directly in the process
+# environment, simulating the remote host's own login-shell export reaching the
+# agent's pane. fm_pf_relay_active's environment-wins rule would make this look
+# identical to a genuine same-home commitment; the fix must tell them apart by
+# reading only $FM_HOME/.env, never the process environment, once the durable
+# record says the parent is remote.
+run_child_teardown FM_PUBLIC_FOLLOWUP_PRIMARY_HOME="$DELIVERED" FMX_PAIRING_TOKEN=ambient-login-token
+[ "$CHILD_TEARDOWN_RC" -eq 0 ] \
+  || fail "a remote-routed child must allow cleanup when only an ambient exported token looks relay-active (rc=$CHILD_TEARDOWN_RC): $CHILD_TEARDOWN_OUT"
+assert_not_contains "$CHILD_TEARDOWN_OUT" "cannot resolve the primary home" \
+  "an ambient exported token from the remote host's own shell must never bind this child"
+pass "a remote secondmate's finished worker cleans up when only an ambient exported token looked relay-active"
+
+# Baseline: no signal anywhere. Must keep succeeding exactly as before the fix.
+run_child_teardown
+[ "$CHILD_TEARDOWN_RC" -eq 0 ] \
+  || fail "a remote-routed child with no relay signal anywhere must allow cleanup (rc=$CHILD_TEARDOWN_RC): $CHILD_TEARDOWN_OUT"
+pass "a remote secondmate's finished worker cleans up with no relay signal anywhere"
+
+# Protection-preserved case: THIS home's own .env file (not the process
+# environment, not the remote code root) carries a real token. That is a
+# genuine same-filesystem signal this child's own home could hold, so it must
+# still refuse even though the parent route is remote.
+printf 'FMX_PAIRING_TOKEN=child-own-token\n' > "$REMOTE_HOME/.env"
+run_child_teardown
+rm -f "$REMOTE_HOME/.env"
+[ "$CHILD_TEARDOWN_RC" -ne 0 ] \
+  || fail "a remote secondmate's own committed .env token must still refuse cleanup, got rc=0: $CHILD_TEARDOWN_OUT"
+assert_contains "$CHILD_TEARDOWN_OUT" "cannot resolve the primary home" \
+  "a genuine same-filesystem token on this home must remain an actionable refusal"
+assert_present "$REMOTE_HOME/state/work-child.meta" \
+  "a genuine refusal must preserve the child work metadata"
+pass "a remote secondmate's own committed relay token still refuses cleanup"
+
+FOREIGN_META="$TMP_ROOT/foreign-ios.meta"
+LOCAL_META="$PARENT/state/ios.meta"
+printf 'foreign sentinel\n' > "$FOREIGN_META"
+rm -f "$LOCAL_META"
+PUBLICATION_RC=0
+PUBLICATION_OUT=$(FM_TEST_PUBLICATION_TARGET="$LOCAL_META" \
+  FM_TEST_PUBLICATION_FOREIGN="$FOREIGN_META" \
+  remote_env "$ROOT/bin/fm-spawn.sh" ios --secondmate 2>&1) || PUBLICATION_RC=$?
+[ "$PUBLICATION_RC" -ne 0 ] \
+  || fail "remote secondmate publication accepted a target resolving outside its home"
+assert_contains "$PUBLICATION_OUT" "task record could not be published" \
+  "remote secondmate publication did not report its record-boundary refusal"
+cmp -s "$FOREIGN_META" <(printf 'foreign sentinel\n') \
+  || fail "remote secondmate publication wrote through the foreign target"
+[ -L "$LOCAL_META" ] \
+  || fail "remote secondmate publication replaced the refused target boundary"
+pass "remote secondmate publication refuses targets outside its home"
+
+echo "ALL TESTS PASSED"

package/.agents/tests/fm-remote-secondmate-trace-context.test.sh

@@ -0,0 +1,310 @@
+#!/usr/bin/env bash
+# tests/fm-remote-secondmate-trace-context.test.sh - trace-context regressions for
+# the REMOTE second mate route, over the deterministic generic SSH boundary.
+#
+# The local spawn path's coverage lives in tests/fm-trace-context-spawn.test.sh.
+# A remote second mate never reaches that path: bin/fm-spawn.sh routes it through
+# spawn_remote_secondmate, which hands the launch to the remote host. These
+# assertions drive the real chain - parent fm-spawn -> fm-on -> the real remote
+# entrypoint -> fm-remote-secondmate-control -> the remote host's own fm-spawn -
+# against a fake herdr CLI, so the carrier the remote pane receives is observable.
+# See docs/verification/trace-context.md for the maintained coverage inventory.
+set -u
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+# shellcheck source=tests/remote-herdr-fixture.sh
+. "$(dirname "${BASH_SOURCE[0]}")/remote-herdr-fixture.sh"
+# shellcheck source=/dev/null
+. "$ROOT/bin/fm-trace-context-lib.sh"
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P)
+TMP_ROOT=$(fm_test_tmproot fm-remote-trace-context)
+mkdir -p "$TMP_ROOT"
+TMP_ROOT=$(cd "$TMP_ROOT" && pwd -P)
+PARENT="$TMP_ROOT/parent"
+REMOTE_ROOT="$TMP_ROOT/remote-root"
+REMOTE_HOME="$TMP_ROOT/remote-home"
+SECOND_HOME="$TMP_ROOT/remote-home-2"
+FAKEBIN=$(fm_fakebin "$TMP_ROOT/fake")
+HERDR_LOG="$TMP_ROOT/remote-herdr.log"
+HERDR_STATE="$TMP_ROOT/remote-herdr.state"
+TMUX_LOG="$TMP_ROOT/remote-tmux.log"
+TMUX_STATE="$TMP_ROOT/remote-tmux.state"
+CLAIMS="$TMP_ROOT/claims"
+mkdir -p "$PARENT/data" "$PARENT/state" "$PARENT/config" "$PARENT/projects" "$REMOTE_ROOT" "$CLAIMS"
+trap 'FM_HOME="$PARENT" FM_PROCEVENT_CLAIM_ROOT="$CLAIMS" "$ROOT/bin/fm-procevent.sh" sweep-home >/dev/null 2>&1 || true; if [ -f "$TMP_ROOT/remote-jobs/worker.pid" ]; then kill "$(cat "$TMP_ROOT/remote-jobs/worker.pid")" 2>/dev/null || true; fi; rm -rf -- "$TMP_ROOT"' EXIT
+
+# The remote host's tracked code root is this branch, as a real git repository:
+# fm-on and the remote entrypoint both require the dispatched command to be
+# tracked there, and the remote side runs the real scripts under test.
+(
+  cd "$ROOT" || exit
+  tar --exclude=.git --exclude=.no-mistakes --exclude=data --exclude=state --exclude=config -cf - .
+) | (cd "$REMOTE_ROOT" && tar -xf -)
+
+# The remote host runs the Herdr fixture, whose every invocation is logged
+# verbatim, so the pre-launch `export TRACEPARENT=` line and the launch
+# literal's FM_TRACE_CONTEXT prefix are both observable exactly as the pane
+# received them. The tmux fixture below only keeps the remote home's own
+# non-second-mate tooling resolvable.
+cat > "$REMOTE_ROOT/bin/tmux" <<SH
+#!/usr/bin/env bash
+set -u
+log='$TMUX_LOG'
+state='$TMUX_STATE'
+printf '%s\n' "\$*" >> "\$log"
+case "\${1:-}" in
+  has-session|new-session|set-window-option) exit 0 ;;
+  list-windows)
+    [ -f "\$state" ] || exit 0
+    name=\$(cut -d'|' -f1 "\$state")
+    case "\$*" in *'#{session_name}:#{window_name}'*) printf 'firstmate:%s\n' "\$name" ;; *) printf '%s\n' "\$name" ;; esac
+    exit 0
+    ;;
+  new-window)
+    name=; cwd=
+    while [ "\$#" -gt 0 ]; do
+      case "\$1" in -n) shift; name=\$1 ;; -c) shift; cwd=\$1 ;; esac
+      shift
+    done
+    printf '%s|%s\n' "\$name" "\$cwd" > "\$state"
+    printf '@1\n'
+    exit 0
+    ;;
+  display-message)
+    case "\$*" in
+      *'#{pane_current_path}'*) cut -d'|' -f2- "\$state" ;;
+      *'#{pane_current_command}'*) printf 'codex\n' ;;
+      *'#{cursor_y}'*) printf '0\n' ;;
+      *'#S'*) printf 'firstmate\n' ;;
+      *) printf '%%1\n' ;;
+    esac
+    exit 0
+    ;;
+  capture-pane) printf '❯\n'; exit 0 ;;
+  send-keys) exit 0 ;;
+  kill-window) rm -f -- "\$state"; exit 0 ;;
+  list-panes) printf 'codex\n'; exit 0 ;;
+esac
+exit 0
+SH
+chmod +x "$REMOTE_ROOT/bin/tmux"
+install_remote_herdr_fixture "$REMOTE_ROOT" "$HERDR_STATE" "$HERDR_LOG" \
+  "$TMP_ROOT/herdr-send-fail" "$TMP_ROOT/herdr.sock"
+git -C "$REMOTE_ROOT" init -q -b main
+git -C "$REMOTE_ROOT" config user.email test@example.com
+git -C "$REMOTE_ROOT" config user.name Test
+git -C "$REMOTE_ROOT" add .
+git -C "$REMOTE_ROOT" commit -qm 'remote fixture root'
+
+cat > "$FAKEBIN/fake-ssh" <<'SH'
+#!/usr/bin/env bash
+while [ "$#" -gt 0 ]; do
+  case "$1" in -o) shift 2 ;; --) shift; break ;; *) exit 90 ;; esac
+done
+host=$1
+entry=$2
+shift 2
+[ "$host" = remote-mac ] || exit 91
+[ "$entry" = fm-remote-entrypoint.sh ] || exit 92
+cd "$FM_FAKE_REMOTE_CWD" || exit 93
+# The readiness gate is answered here rather than by the real doctor, which
+# would inspect the RUNNER's own account; tests/fm-remote-doctor.test.sh owns
+# the doctor's behavior against controlled account fixtures.
+if printf '%s' "$4" | base64 --decode 2>/dev/null | tr '\0' '\n' | head -1 | grep -q '^fm-remote-doctor.sh$'; then
+  printf 'ok: remote second-mate readiness confirmed on this host\n'
+  exit 0
+fi
+exec "$FM_FAKE_REMOTE_ENTRYPOINT" "$@"
+SH
+chmod +x "$FAKEBIN/fake-ssh"
+
+printf 'codex\n' > "$PARENT/config/secondmate-harness"
+printf 'tmux\n' > "$PARENT/config/backend"
+printf 'codex\n' > "$PARENT/config/crew-harness"
+printf '## In flight\n\n## Queued\n\n## Done\n' > "$PARENT/data/backlog.md"
+
+remote_env() {
+  FM_HOME="$PARENT" \
+  FM_ROOT_OVERRIDE="$REMOTE_ROOT" \
+  FM_PROCEVENT_CLAIM_ROOT="$CLAIMS" \
+  FM_SSH_BIN="$FAKEBIN/fake-ssh" \
+  FM_FAKE_REMOTE_ENTRYPOINT="$REMOTE_ROOT/bin/fm-remote-entrypoint.sh" \
+  FM_REMOTE_JOB_PLATFORM_OVERRIDE=Linux \
+  FM_REMOTE_JOB_STATE_ROOT="$TMP_ROOT/remote-jobs" \
+  FM_FAKE_REMOTE_CWD="$TMP_ROOT" \
+  FM_SEND_SETTLE=0 FM_SEND_SLEEP=0 \
+  "$@"
+}
+
+# Freeze the parent home's trace-context decision the way a locked session start
+# does, hermetically against an ambient FM_TRACE_CONTEXT.
+freeze_parent_session() {
+  printf '%s\n' "$$" > "$PARENT/state/.lock"
+  (
+    unset FM_TRACE_CONTEXT
+    fm_trace_context_session_start "$PARENT/config" "$PARENT/state/.trace-context-effective"
+  )
+}
+
+# What the remote pane actually received, read back from the remote tmux log.
+remote_injected_traceparent() {
+  sed -n 's/.*export TRACEPARENT=\([0-9a-f-]*\).*/\1/p' "$HERDR_LOG" | tail -1
+}
+remote_launch_snapshot() {
+  grep -o 'FM_TRACE_CONTEXT=[a-z]*' "$HERDR_LOG" | tail -1 | cut -d= -f2
+}
+meta_traceparent() { sed -n 's/^traceparent=//p' "$1"; }
+
+# Provision and register the remote route from the captain-facing primary.
+FM_SECONDMATE_CHARTER='Own iOS delivery on the build Mac.' \
+  FM_SECONDMATE_SCOPE='iOS implementation and Xcode validation' \
+  remote_env "$ROOT/bin/fm-remote-home-seed.sh" ios remote-mac "$REMOTE_ROOT" "$REMOTE_HOME" --no-projects >/dev/null \
+  || fail "remote seed did not provision the traced route"
+
+# --- disabled: the remote route must stay byte-identically untraced ----------
+freeze_parent_session
+: > "$HERDR_LOG"
+remote_env "$ROOT/bin/fm-spawn.sh" ios --secondmate >/dev/null 2>&1 \
+  || fail "default-off remote secondmate spawn failed"
+assert_present "$PARENT/state/ios.meta" "default-off remote spawn published no parent metadata"
+! grep -q '^traceparent=' "$PARENT/state/ios.meta" \
+  || fail "default-off remote spawn must not record a traceparent= line"
+! grep -q 'export TRACEPARENT=' "$HERDR_LOG" \
+  || fail "default-off remote spawn must not export a carrier into the remote pane"
+! grep -q '^traceparent=' "$REMOTE_HOME/state/parent-route/ios.meta" \
+  || fail "default-off remote spawn must not record a carrier on the remote host"
+[ "$(remote_launch_snapshot)" = off ] \
+  || fail "default-off remote spawn must deliver FM_TRACE_CONTEXT=off (got '$(remote_launch_snapshot)')"
+assert_absent "$REMOTE_HOME/config/trace-context" "default-off remote spawn inherited an enablement flag"
+grep -q 'export GOTMPDIR=' "$HERDR_LOG" || fail "the remote spawn should still run (GOTMPDIR is always exported)"
+pass "disabled: a remote-routed second mate records and receives no carrier and stays enabled-off end to end"
+
+# --- enabled: one carrier is recorded by the parent and received remotely ----
+: > "$PARENT/config/trace-context"
+freeze_parent_session
+reset_remote_herdr_fixture "$HERDR_STATE"   # the previous endpoint is gone; this is an ordinary relaunch
+: > "$HERDR_LOG"
+remote_env "$ROOT/bin/fm-spawn.sh" ios --secondmate >/dev/null 2>&1 \
+  || fail "enabled remote secondmate spawn failed"
+
+PARENT_TP=$(meta_traceparent "$PARENT/state/ios.meta")
+REMOTE_TP=$(meta_traceparent "$REMOTE_HOME/state/parent-route/ios.meta")
+INJECTED_TP=$(remote_injected_traceparent)
+fm_trace_context_valid "$PARENT_TP" \
+  || fail "an enabled remote spawn must record a valid carrier in the parent metadata (got '$PARENT_TP')"
+fm_trace_context_valid "$INJECTED_TP" \
+  || fail "an enabled remote spawn must export a valid carrier into the remote pane (got '$INJECTED_TP')"
+[ "$PARENT_TP" = "$INJECTED_TP" ] \
+  || fail "the parent's recorded carrier and the remote pane's carrier must be identical (parent='$PARENT_TP' pane='$INJECTED_TP')"
+[ "$REMOTE_TP" = "$PARENT_TP" ] \
+  || fail "the remote endpoint record must carry the parent's identity (remote='$REMOTE_TP' parent='$PARENT_TP')"
+[ "$(remote_launch_snapshot)" = on ] \
+  || fail "an enabled remote spawn must deliver FM_TRACE_CONTEXT=on (got '$(remote_launch_snapshot)')"
+assert_present "$REMOTE_HOME/config/trace-context" \
+  "an enabled remote launch did not inherit the enablement flag into the remote home"
+GOTMP_LINE=$(grep -n 'export GOTMPDIR=' "$HERDR_LOG" | tail -1 | cut -d: -f1)
+TP_LINE=$(grep -n 'export TRACEPARENT=' "$HERDR_LOG" | tail -1 | cut -d: -f1)
+LAUNCH_LINE=$(grep -n 'FM_TRACE_CONTEXT=' "$HERDR_LOG" | tail -1 | cut -d: -f1)
+[ -n "$GOTMP_LINE" ] && [ -n "$TP_LINE" ] && [ -n "$LAUNCH_LINE" ] \
+  || fail "remote pane log missing GOTMPDIR/TRACEPARENT/launch lines"
+[ "$TP_LINE" -gt "$GOTMP_LINE" ] \
+  || fail "the remote TRACEPARENT export must ride the GOTMPDIR pre-launch site (gotmp=$GOTMP_LINE tp=$TP_LINE)"
+[ "$TP_LINE" -lt "$LAUNCH_LINE" ] \
+  || fail "the remote TRACEPARENT export must be sent before the launch command (tp=$TP_LINE launch=$LAUNCH_LINE)"
+pass "enabled: a remote-routed second mate receives one carrier in its pane, identical to the parent's recorded identity, before launch"
+
+# --- relaunch stability on the remote path ----------------------------------
+reset_remote_herdr_fixture "$HERDR_STATE"
+: > "$HERDR_LOG"
+remote_env "$ROOT/bin/fm-spawn.sh" ios --secondmate >/dev/null 2>&1 \
+  || fail "enabled remote secondmate relaunch failed"
+RELAUNCH_TP=$(meta_traceparent "$PARENT/state/ios.meta")
+RELAUNCH_INJECTED=$(remote_injected_traceparent)
+[ "$RELAUNCH_TP" = "$PARENT_TP" ] \
+  || fail "a remote relaunch must keep the task's recorded carrier (first='$PARENT_TP' relaunch='$RELAUNCH_TP')"
+[ "$RELAUNCH_INJECTED" = "$PARENT_TP" ] \
+  || fail "a remote relaunch must re-export the original carrier (first='$PARENT_TP' injected='$RELAUNCH_INJECTED')"
+pass "relaunch: a remote-routed second mate keeps one stable identity across restarts"
+
+# --- per-task boundary: ambient carriers are never adopted or shared ---------
+# A persistent supervisor exports its own launch-time TRACEPARENT for its whole
+# life. A second remote route resolved from that same environment must root its
+# own trace rather than chain onto it or onto the first route.
+AMBIENT='00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab-bbbbbbbbbbbbbbbb-01'
+FM_SECONDMATE_CHARTER='Own the second build Mac.' \
+  FM_SECONDMATE_SCOPE='second remote domain' \
+  TRACEPARENT="$AMBIENT" \
+  remote_env "$ROOT/bin/fm-remote-home-seed.sh" ios2 remote-mac "$REMOTE_ROOT" "$SECOND_HOME" --no-projects >/dev/null \
+  || fail "second remote seed failed"
+reset_remote_herdr_fixture "$HERDR_STATE"
+: > "$HERDR_LOG"
+TRACEPARENT="$AMBIENT" remote_env "$ROOT/bin/fm-spawn.sh" ios2 --secondmate >/dev/null 2>&1 \
+  || fail "second remote secondmate spawn failed"
+SECOND_TP=$(meta_traceparent "$PARENT/state/ios2.meta")
+fm_trace_context_valid "$SECOND_TP" \
+  || fail "the second remote route must record a valid carrier (got '$SECOND_TP')"
+[ "${SECOND_TP:3:32}" != "${AMBIENT:3:32}" ] \
+  || fail "a remote route must not adopt the spawning process's ambient trace id (got '$SECOND_TP')"
+[ "${SECOND_TP:3:32}" != "${PARENT_TP:3:32}" ] \
+  || fail "two remote routes must root distinct traces (first='$PARENT_TP' second='$SECOND_TP')"
+[ "$(remote_injected_traceparent)" = "$SECOND_TP" ] \
+  || fail "the second remote route's pane must receive its own recorded carrier"
+pass "boundary: each remote-routed second mate roots its own trace and never adopts the spawning environment's carrier"
+
+# --- the enablement flag is one allowlist, shared by both remote ends --------
+# config/trace-context reaches the remote home only because the sender and the
+# receiver derive the same declared inherited-material set. Prove the receiver
+# accepts it as ordinary inherited material rather than by name.
+PROTOCOL_HOME="$TMP_ROOT/protocol-home"
+mkdir -p "$PROTOCOL_HOME/config" "$PROTOCOL_HOME/data" "$PROTOCOL_HOME/state"
+: > "$TMP_ROOT/flag-payload"
+FLAG_BYTES=$(LC_ALL=C wc -c < "$TMP_ROOT/flag-payload" | tr -d ' ')
+if command -v shasum >/dev/null 2>&1; then
+  FLAG_HASH=$(shasum -a 256 "$TMP_ROOT/flag-payload" | awk '{print $1}')
+else
+  FLAG_HASH=$(sha256sum "$TMP_ROOT/flag-payload" | awk '{print $1}')
+fi
+FM_HOME="$PROTOCOL_HOME" "$REMOTE_ROOT/bin/fm-remote-inherit.sh" \
+  put config/trace-context "$FLAG_BYTES" "$FLAG_HASH" 1 < "$TMP_ROOT/flag-payload" >/dev/null \
+  || fail "the remote inherit receiver refused a declared inheritable item"
+assert_present "$PROTOCOL_HOME/config/trace-context" "the accepted inherited enablement flag was not published"
+if FM_HOME="$PROTOCOL_HOME" "$REMOTE_ROOT/bin/fm-remote-inherit.sh" \
+  put config/secondmate-harness "$FLAG_BYTES" "$FLAG_HASH" 1 < "$TMP_ROOT/flag-payload" >/dev/null 2>&1; then
+  fail "the remote inherit receiver accepted an item outside the declared set"
+fi
+assert_absent "$PROTOCOL_HOME/config/secondmate-harness" "a non-inheritable item was published remotely"
+pass "allowlist: the remote receiver accepts exactly the declared inherited-material set, including the enablement flag"
+
+# --- the delivery flag is the only caller-supplied path to a pane export -----
+# A remote host receives the carrier as an argument rather than resolving it, so
+# that argument is refused unless it is a secondmate launch carrying a strictly
+# valid W3C value. Nothing else may reach `export TRACEPARENT=`.
+FLAG_HOME="$TMP_ROOT/flag-home"
+mkdir -p "$FLAG_HOME/state" "$FLAG_HOME/data" "$FLAG_HOME/config" "$FLAG_HOME/projects" "$TMP_ROOT/flag-proj"
+VALID='00-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab-bbbbbbbbbbbbbbbb-01'
+try_flag() { # <expect-substring> <message> [extra args...]
+  local expect=$1 message=$2 out
+  shift 2
+  if out=$(FM_SPAWN_NO_GUARD=1 FM_HOME="$FLAG_HOME" "$ROOT/bin/fm-spawn.sh" \
+    flag-a-b1 "$TMP_ROOT/flag-proj" "$@" 2>&1); then
+    fail "$message (the spawn succeeded instead)"
+  fi
+  assert_contains "$out" "$expect" "$message"
+}
+try_flag 'applies only to --secondmate spawns' \
+  "a ship spawn must refuse a caller-supplied carrier" \
+  --mode no-mistakes --yolo off --traceparent "$VALID"
+try_flag 'not a valid W3C traceparent' \
+  "a shell-metacharacter carrier must be refused before any pane export" \
+  --secondmate --traceparent 'bogus; rm -rf /'
+try_flag 'not a valid W3C traceparent' \
+  "an all-zero trace id must be refused as W3C-invalid" \
+  --secondmate --traceparent '00-00000000000000000000000000000000-bbbbbbbbbbbbbbbb-01'
+try_flag 'requires a non-empty value' \
+  "an empty carrier must be refused rather than silently ignored" \
+  --secondmate --traceparent=
+pass "delivery: a parent-supplied carrier is accepted only for a secondmate launch and only as a strict W3C value"
+
+echo "ALL TESTS PASSED"