@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/tests/secondmate-helpers.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+# tests/secondmate-helpers.sh - shared fixtures and mocks for the secondmate
+# suites (fm-secondmate-lifecycle-e2e and fm-secondmate-safety).
+#
+# These mocks encode secondmate-lifecycle behavior (fake tmux that logs window
+# ops, fake treehouse that leases/returns homes, fake no-mistakes that records
+# init/doctor), so they live here rather than in the generic tests/lib.sh. The
+# generic git/identity/meta primitives come from lib.sh, which this file pulls in.
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+# A fake tmux (window ops are logged to FM_FAKE_TMUX_LOG, list-windows returns
+# FM_FAKE_TMUX_WINDOW, capture-pane echoes FM_FAKE_TMUX_CAPTURE) plus a fake
+# treehouse (durable lease of FM_FAKE_TREEHOUSE_HOME, recording the lease holder
+# to FM_FAKE_TREEHOUSE_LEASE_FILE; `return` removes the target and lease unless
+# FM_FAKE_TREEHOUSE_RETURN_FAIL is set). Echoes the fakebin dir.
+make_fake_tmux() {
+  local dir=$1 fakebin capture
+  fakebin=$(fm_fakebin "$dir")
+  capture="$dir/pane.txt"
+  # A real, positively identified empty agent composer. A blank capture is
+  # deliberately unknown under the fleet-wide strict blank-row posture.
+  printf '❯\n' > "$capture"
+  cat > "$fakebin/tmux" <<'SH'
+#!/usr/bin/env bash
+set -u
+case "${1:-}" in
+  has-session|new-session|new-window|send-keys|kill-window)
+    printf '%s\n' "$*" >> "$FM_FAKE_TMUX_LOG"
+    exit 0
+    ;;
+  list-windows)
+    if [ -n "${FM_FAKE_TMUX_WINDOW:-}" ]; then
+      printf '%s\n' "$FM_FAKE_TMUX_WINDOW"
+    fi
+    exit 0
+    ;;
+  display-message)
+    case "$*" in
+      *'#{cursor_y}'*) printf '0\n' ;;
+      *) printf 'firstmate\n' ;;
+    esac
+    exit 0
+    ;;
+  capture-pane)
+    printf '%s\n' "$*" >> "$FM_FAKE_TMUX_LOG"
+    cat "$FM_FAKE_TMUX_CAPTURE"
+    exit 0
+    ;;
+esac
+exit 1
+SH
+  cat > "$fakebin/treehouse" <<'SH'
+#!/usr/bin/env bash
+set -u
+printf 'treehouse %s\n' "$*" >> "${FM_FAKE_TMUX_LOG:-/dev/null}"
+case "${1:-}" in
+  get)
+    # Durable lease: print only the worktree path to stdout (banners to stderr),
+    # and record the lease holder so tests can assert it is set and later cleared.
+    shift
+    holder=
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --lease) ;;
+        --lease-holder) shift; holder=${1:-} ;;
+        --lease-holder=*) holder=${1#--lease-holder=} ;;
+      esac
+      shift
+    done
+    if [ -n "${FM_FAKE_TREEHOUSE_HOME:-}" ]; then
+      mkdir -p "$FM_FAKE_TREEHOUSE_HOME"
+      [ -n "${FM_FAKE_TREEHOUSE_LEASE_FILE:-}" ] && printf '%s\n' "$holder" > "$FM_FAKE_TREEHOUSE_LEASE_FILE"
+      printf 'leased worktree for %s\n' "${holder:-unknown}" >&2
+      printf '%s\n' "$FM_FAKE_TREEHOUSE_HOME"
+    fi
+    exit 0
+    ;;
+  return)
+    shift
+    target=
+    while [ $# -gt 0 ]; do
+      case "$1" in
+        --force) ;;
+        *) target=$1 ;;
+      esac
+      shift
+    done
+    [ -z "${FM_FAKE_TREEHOUSE_RETURN_FAIL:-}" ] || exit 17
+    [ -n "${FM_FAKE_TREEHOUSE_LEASE_FILE:-}" ] && rm -f "$FM_FAKE_TREEHOUSE_LEASE_FILE"
+    [ -n "$target" ] && rm -rf -- "$target"
+    exit 0
+    ;;
+esac
+exit 0
+SH
+  chmod +x "$fakebin/tmux"
+  chmod +x "$fakebin/treehouse"
+  : > "$dir/tmux.log"
+  printf '%s\n' "$fakebin"
+}
+
+# A fake no-mistakes that touches .no-mistakes-init / .no-mistakes-doctor markers.
+make_fake_no_mistakes() {
+  local dir=$1 fakebin
+  fakebin=$(fm_fakebin "$dir")
+  cat > "$fakebin/no-mistakes" <<'SH'
+#!/usr/bin/env bash
+set -eu
+case "${1:-}" in
+  init) touch .no-mistakes-init ;;
+  doctor) touch .no-mistakes-doctor ;;
+  *) exit 2 ;;
+esac
+SH
+  chmod +x "$fakebin/no-mistakes"
+  printf '%s\n' "$fakebin"
+}
+
+# A fake no-mistakes that records each "<pwd>\t<verb>" call to
+# FM_FAKE_NO_MISTAKES_LOG and fails for the project named FM_FAKE_NO_MISTAKES_FAIL_PROJECT.
+make_recording_no_mistakes() {
+  local dir=$1 fakebin
+  fakebin=$(fm_fakebin "$dir")
+  cat > "$fakebin/no-mistakes" <<'SH'
+#!/usr/bin/env bash
+set -eu
+printf '%s\t%s\n' "$PWD" "${1:-}" >> "$FM_FAKE_NO_MISTAKES_LOG"
+if [ "$(basename "$PWD")" = "${FM_FAKE_NO_MISTAKES_FAIL_PROJECT:-}" ]; then
+  exit 1
+fi
+case "${1:-}" in
+  init) touch .no-mistakes-init ;;
+  doctor) touch .no-mistakes-doctor ;;
+  *) exit 2 ;;
+esac
+SH
+  chmod +x "$fakebin/no-mistakes"
+  printf '%s\n' "$fakebin"
+}
+
+# Make a directory look like a minimal firstmate home (AGENTS.md + bin/).
+mark_firstmate_home() {
+  local home=$1
+  mkdir -p "$home/bin"
+  printf '# Firstmate\n' > "$home/AGENTS.md"
+}
+
+# A firstmate home that is also a real git repo (so it can host detached
+# worktrees for teardown/lease tests).
+make_firstmate_git_root() {
+  local home=$1
+  mkdir -p "$home/bin"
+  printf '# Firstmate\n' > "$home/AGENTS.md"
+  cat > "$home/bin/fm-guard.sh" <<'SH'
+#!/usr/bin/env bash
+exit 0
+SH
+  chmod +x "$home/bin/fm-guard.sh"
+  git -C "$home" init -q
+  git -C "$home" add AGENTS.md bin/fm-guard.sh
+  git -C "$home" -c user.name='Firstmate Tests' -c user.email='tests@example.invalid' commit -qm initial
+}
+
+# Scaffold a filled secondmate charter brief under <home>/data/<id>/brief.md.
+# Args: home id charter [project...]
+scaffold_secondmate_charter() {
+  local home=$1 id=$2 charter=$3
+  shift 3
+  FM_HOME="$home" FM_SECONDMATE_CHARTER="$charter" "$ROOT/bin/fm-brief.sh" "$id" --secondmate "$@" >/dev/null
+}
+
+# Make a directory look like a genuine seeded secondmate home (for handoff tests).
+seed_secondmate_home_marker() {
+  local home=$1 id=$2
+  mark_firstmate_home "$home"
+  mkdir -p "$home/data"
+  printf '%s\n' "$id" > "$home/.fm-secondmate-home"
+}
+
+# Wait up to <limit> 0.1s ticks while <pid> stays alive. Returns 1 if it dies.
+wait_live() {
+  local pid=$1 limit=${2:-30} i=0
+  while [ "$i" -lt "$limit" ]; do
+    if ! kill -0 "$pid" 2>/dev/null; then
+      return 1
+    fi
+    sleep 0.1
+    i=$((i + 1))
+  done
+  return 0
+}

package/.agents/tests/smoke.test.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# smoke.test.sh — the repo smoke test. Boots the Brokk runtime lifecycle and
+# asserts it holds together. Galdr-style TOON output; exit 1 on any failure.
+#
+# Usage: bash .agents/tests/smoke.test.sh [--quiet] ; --version
+set -u
+
+VERSION="1.0.0"
+TEST_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$TEST_DIR/../.." && pwd)"
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+esac
+QUIET=0; [ "${1-}" = "--quiet" ] && QUIET=1
+
+export BROKK_HOME="$ROOT"
+export BROKK_ROOT_OVERRIDE="$ROOT"
+export BROKK_CONFIG_OVERRIDE="$ROOT/.agents/config"
+export BROKK_STATE_OVERRIDE="$ROOT/state"
+export BROKK_SESSION_PID="$$"
+STATE="$BROKK_STATE_OVERRIDE"
+declare -a STEP S; fails=0
+add() { STEP+=("$1"); S+=("$2"); [ "$2" = FAIL ] && fails=$((fails + 1)); }
+say() { [ "$QUIET" = 1 ] || printf '%s\n' "$1"; }
+
+# 1. loader resolves agents
+if [ -f "$ROOT/bin/valknut-load.sh" ] && bash "$ROOT/bin/valknut-load.sh" --status >/dev/null 2>&1; then
+  add "loaders" OK
+else
+  add "loaders" FAIL
+fi
+
+# 2. Sága digest runs (starts Nornir + lock)
+if out=$(bash "$ROOT/bin/saga-session-start.sh" 2>&1); then
+  add "saga digest" OK
+else
+  add "saga digest" FAIL
+fi
+
+# 3. lock present and held by a live session (or this test)
+owner=$(tr -d "[:space:]" <"$STATE/.lock" 2>/dev/null)
+if [ -n "$owner" ] && { [ "$owner" = "$$" ] || kill -0 "$owner" 2>/dev/null; }; then
+  add "gleipnir lock" OK
+else
+  add "gleipnir lock" FAIL
+fi
+
+# 4. Nornir cron running
+if bash "$ROOT/bin/nornir-cron-start.sh" --status 2>/dev/null | grep -q 'running'; then
+  add "nornir cron" OK
+else
+  add "nornir cron" FAIL
+fi
+
+# 5. Sýn arms and exits on a signal
+touch "$STATE/smoke.signal"
+if out=$(timeout 8 bash "$ROOT/bin/syn-watch-arm.sh" --restart 2>&1) && printf '%s' "$out" | grep -q '^signal:'; then
+  add "syn watch-arm" OK
+else
+  add "syn watch-arm" FAIL
+fi
+rm -f "$STATE/smoke.signal" "$STATE/.supervision-armed"
+
+# 6. turn-end guard inert when not armed
+if echo '{}' | bash "$ROOT/bin/syn-turnend-guard.sh"; then
+  add "syn guard inert" OK
+else
+  add "syn guard inert" FAIL
+fi
+
+# 7. Galdr/Tyr compliance
+if bash "$ROOT/.agents/skills/galdr-ymirsystem/scripts/compliance-check.sh" >/dev/null 2>&1; then
+  add "galdr compliance" OK
+else
+  add "galdr compliance" FAIL
+fi
+
+# 8. config resolves under .agents/config (ro is now per-user in state/)
+if [ -f "$BROKK_CONFIG_OVERRIDE/cron.yaml" ] && [ -f "$BROKK_CONFIG_OVERRIDE/eindri-harness" ]; then
+  add "config repo-local" OK
+else
+  add "config repo-local" FAIL
+fi
+
+if [ "$QUIET" = 0 ]; then
+  printf 'smoke[%s]{step,status}:\n' "${#STEP[@]}"
+  for i in "${!STEP[@]}"; do printf '  "%s","%s"\n' "${STEP[$i]}" "${S[$i]}"; done
+fi
+if [ "$fails" -gt 0 ]; then
+  printf 'error: %s smoke step(s) failed\n' "$fails" >&2
+  exit 1
+fi
+exit 0

package/.agents/tests/wake-helpers.sh

@@ -0,0 +1,338 @@
+#!/usr/bin/env bash
+# tests/wake-helpers.sh - shared fixtures and mocks for the wake-queue,
+# watcher/lock, and supervise-daemon suites. The fake tmux surfaces here encode
+# watcher/daemon/composer behavior, so they live here rather than in the generic
+# tests/lib.sh. Generic reporters/assertions come from lib.sh, pulled in below.
+
+# shellcheck source=tests/lib.sh
+. "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+# fm-wake-drain.sh now calls fm-guard.sh to assert watcher liveness on every
+# drain. fm-guard.sh's first check warns when the firstmate PRIMARY checkout
+# (FM_ROOT) sits on a feature branch; with no override FM_ROOT resolves to the
+# test runner's own checkout, which during validation is on a feature branch, so
+# each drain would emit a spurious worktree-tangle banner. Point the tangle check
+# at a fresh non-git dir to keep it inert across these suites - the same trick the
+# direct fm-guard.sh tests use. A per-call FM_ROOT_OVERRIDE still wins where a
+# suite sets its own (e.g. the watcher-lock guard-banner cases).
+if [ -z "${FM_ROOT_OVERRIDE:-}" ]; then
+  FM_ROOT_OVERRIDE="$(fm_test_tmproot fm-wake-tangle-root)"
+  export FM_ROOT_OVERRIDE
+fi
+
+# Wedge-alarm notifier recorder (safety seam). The away-mode wedge alarm fires a
+# real OS-level desktop notification by default. Point its FM_WEDGE_ALARM_EXEC
+# seam at a recorder for every
+# daemon/wake suite, so no test - present or future - can post a real macOS,
+# herdr, or command: notification: it is impossible to forget, because sourcing this harness
+# installs it. The recorder is an on-disk script (a real daemon a test spawns
+# inherits the path and records too). It logs "<channel>\t<summary>" to
+# $FM_WEDGE_ALARM_LOG, which a test sets to its own file to assert on; unset means
+# /dev/null. FM_WEDGE_ALARM_FAIL=<channel> makes the recorder exit non-zero for
+# that channel, to exercise graceful degradation. Suites that do not source this
+# harness still cannot fire a real notification: the daemon defaults the seam to
+# "discard" whenever it is sourced (its library-mode guard).
+_fm_wedge_rec_dir=$(fm_test_tmproot fm-wedge-rec)
+cat > "$_fm_wedge_rec_dir/rec" <<'REC'
+#!/usr/bin/env bash
+printf '%s\t%s\n' "${1:-}" "${2:-}" >> "${FM_WEDGE_ALARM_LOG:-/dev/null}"
+case " ${FM_WEDGE_ALARM_FAIL:-} " in *" ${1:-} "*) exit 1 ;; esac
+exit 0
+REC
+chmod +x "$_fm_wedge_rec_dir/rec"
+export FM_WEDGE_ALARM_EXEC="$_fm_wedge_rec_dir/rec"
+
+# append_wake <state> <kind> <key> <payload>: append a wake record to the durable
+# queue in a subshell scoped to <state>, using the production wake library.
+append_wake() {
+  local state=$1 kind=$2 key=$3 payload=$4 lib="$ROOT/bin/fm-wake-lib.sh"
+  FM_STATE_OVERRIDE="$state" bash -c '
+    # shellcheck disable=SC1090,SC1091
+    . "$1"
+    fm_wake_append "$2" "$3" "$4"
+  ' _ "$lib" "$kind" "$key" "$payload"
+}
+
+make_case() {
+  local name=$1 dir fakebin
+  dir="$TMP_ROOT/$name"
+  fakebin="$dir/fakebin"
+  mkdir -p "$dir/state" "$fakebin"
+  cat > "$fakebin/tmux" <<'SH'
+#!/usr/bin/env bash
+set -u
+if [ "${1:-}" = "list-windows" ]; then
+  if [ -n "${FM_FAKE_TMUX_WINDOWS:-}" ]; then
+    printf '%s\n' "$FM_FAKE_TMUX_WINDOWS"
+  elif [ -n "${FM_FAKE_TMUX_WINDOW:-}" ]; then
+    printf '%s\n' "${FM_FAKE_TMUX_WINDOW#*:}"
+  fi
+  exit 0
+fi
+if [ "${1:-}" = "capture-pane" ]; then
+  if [ -n "${FM_FAKE_TMUX_CAPTURE_COUNT_FILE:-}" ]; then
+    _capture_count=$(cat "$FM_FAKE_TMUX_CAPTURE_COUNT_FILE" 2>/dev/null || echo 0)
+    printf '%s\n' "$((_capture_count + 1))" > "$FM_FAKE_TMUX_CAPTURE_COUNT_FILE"
+    if [ -n "${FM_FAKE_TMUX_CAPTURE_FAIL_AFTER:-}" ] \
+      && [ "$_capture_count" -ge "$FM_FAKE_TMUX_CAPTURE_FAIL_AFTER" ]; then
+      exit 1
+    fi
+  fi
+  if [ -n "${FM_FAKE_TMUX_FORBIDDEN_TARGET:-}" ]; then
+    _prev=
+    for _arg in "$@"; do
+      if [ "$_prev" = -t ] && [ "$_arg" = "$FM_FAKE_TMUX_FORBIDDEN_TARGET" ]; then
+        exit 1
+      fi
+      _prev=$_arg
+    done
+  fi
+  if [ -n "${FM_FAKE_TMUX_CAPTURE:-}" ]; then
+    cat "$FM_FAKE_TMUX_CAPTURE"
+  fi
+  exit 0
+fi
+if [ "${1:-}" = "display-message" ]; then
+  case "$*" in
+    *pane_current_command*) printf '%s\n' "${FM_FAKE_TMUX_CURRENT_COMMAND:-}"; exit 0 ;;
+  esac
+fi
+exit 1
+SH
+  chmod +x "$fakebin/tmux"
+  make_fake_crew_state "$fakebin" >/dev/null
+  printf '%s\n' "$dir"
+}
+
+# Install a hermetic fake fm-crew-state.sh into <fakebin> and echo its path. The
+# watcher's absorb-only-when-provably-working triage calls this (via
+# FM_CREW_STATE_BIN) to read a crew's current state on no-verb signal and stale
+# paths; the fake returns a canned "state: <s> · source: <src> · <detail>"
+# verdict line so a test can fix the provably-working decision without a real
+# worktree or no-mistakes.
+# A per-id override FM_FAKE_CREW_STATE_<sanitized-id> wins; otherwise the shared
+# FM_FAKE_CREW_STATE; otherwise an unknown verdict (NOT provably working), the
+# safe default so a test that forgets to set one surfaces rather than absorbs.
+make_fake_crew_state() {  # <fakebin>
+  local fakebin=$1
+  cat > "$fakebin/fm-crew-state.sh" <<'SH'
+#!/usr/bin/env bash
+set -u
+id=${1:-}
+key=$(printf '%s' "$id" | tr -c 'A-Za-z0-9' '_')
+var="FM_FAKE_CREW_STATE_$key"
+val=${!var:-${FM_FAKE_CREW_STATE:-}}
+printf '%s\n' "${val:-state: unknown · source: none · fake default}"
+exit 0
+SH
+  chmod +x "$fakebin/fm-crew-state.sh"
+  printf '%s\n' "$fakebin/fm-crew-state.sh"
+}
+
+# Prime <file>'s .seen-* marker to its CURRENT signature through the production
+# signature owner (bin/fm-wake-lib.sh), so a test can declare "everything in
+# this file was already surfaced or deliberately absorbed" before exercising
+# the next wake, self-announced append, or annotation decision.
+prime_status_seen() {  # <state> <file>
+  FM_STATE_OVERRIDE="$1" bash -c '
+    . "$1"
+    fm_wake_status_mark_current "$2" "$3"
+  ' _ "$ROOT/bin/fm-wake-lib.sh" "$1" "$2"
+}
+
+# Print the generation from a recovery marker token of any status/kind.
+recovery_marker_generation() {  # <marker-file>
+  sed -n 's/^[^:]*:[^:]*:\(.*\)$/\1/p' "$1"
+}
+
+# Acknowledge a drain from its captured stderr (the WAKE_ACK_REQUIRED line).
+ack_drain_err() {  # <state> <stderr-file>
+  local state=$1 err=$2 sequence generation
+  sequence=$(sed -n 's/^WAKE_ACK_REQUIRED:.*--ack-through \([0-9][0-9]*\) --recovery-generation [A-Za-z0-9._-][A-Za-z0-9._-]*$/\1/p' "$err")
+  generation=$(sed -n 's/^WAKE_ACK_REQUIRED:.*--ack-through [0-9][0-9]* --recovery-generation \([A-Za-z0-9._-][A-Za-z0-9._-]*\)$/\1/p' "$err")
+  [ -n "$sequence" ] && [ -n "$generation" ] || return 1
+  FM_STATE_OVERRIDE="$state" "$ROOT/bin/fm-wake-drain.sh" \
+    --ack-through "$sequence" --recovery-generation "$generation"
+}
+
+make_supercase() {
+  local name=$1 dir fakebin
+  dir="$TMP_ROOT/$name"
+  fakebin="$dir/fakebin"
+  mkdir -p "$dir/state" "$fakebin"
+  cat > "$fakebin/tmux" <<'SH'
+#!/usr/bin/env bash
+set -u
+case "${1:-}" in
+  display-message)
+    [ "${FM_FAKE_TMUX_PANE_ALIVE:-1}" = "1" ] || exit 1
+    _print=0
+    # Return cursor_y when the format asks for it (pane_input_pending).
+    for _a in "$@"; do
+      case "$_a" in *cursor_y*) printf '%s\n' "${FM_FAKE_TMUX_CURSOR_Y:-0}"; exit 0 ;; esac
+      [ "$_a" = "-p" ] && _print=1
+    done
+    [ "$_print" = 1 ] && printf 'fakepane\n'
+    exit 0 ;;
+  list-windows)
+    [ -n "${FM_FAKE_TMUX_WINDOW:-}" ] && printf '%s\n' "$FM_FAKE_TMUX_WINDOW"
+    exit 0 ;;
+  capture-pane)
+    # Honor a single-line band capture (-S N -E M, both non-negative) for the
+    # composer reader's non-bordered compatibility fallback; otherwise (e.g. its
+    # structural full-pane scan or fm_pane_is_busy's "-S -40" tail) return the whole capture. -e is accepted and
+    # ignored: this fake emits plain text, which the dim-stripper passes through.
+    _S=""; _E=""; shift
+    while [ "$#" -gt 0 ]; do
+      case "$1" in
+        -S) _S="${2:-}"; shift 2; continue ;;
+        -E) _E="${2:-}"; shift 2; continue ;;
+        *) shift ;;
+      esac
+    done
+    [ -n "${FM_FAKE_TMUX_CAPTURE:-}" ] || exit 0
+    if [ -n "$_S" ] && [ -n "$_E" ]; then
+      case "$_S$_E" in
+        *[!0-9]*) cat "$FM_FAKE_TMUX_CAPTURE" 2>/dev/null ;;
+        *) sed -n "$((_S + 1)),$((_E + 1))p" "$FM_FAKE_TMUX_CAPTURE" 2>/dev/null ;;
+      esac
+    else
+      cat "$FM_FAKE_TMUX_CAPTURE" 2>/dev/null
+    fi
+    exit 0 ;;
+  send-keys)
+    while [ "$#" -gt 0 ]; do
+      case "$1" in
+        -l) shift; [ "$#" -gt 0 ] && {
+          printf '%s\n' "$1" >> "${FM_FAKE_TMUX_SENT:-/dev/null}"
+          # Reflect sent text into capture so pane_input_pending sees it as
+          # pending input (text in the composer).
+          [ -n "${FM_FAKE_TMUX_CAPTURE:-}" ] && printf '%s\n' "$1" >> "$FM_FAKE_TMUX_CAPTURE"
+        } ;;
+        Enter)
+          # Optionally swallow Enter (file-based flag) to test the retry path.
+          if [ -n "${FM_FAKE_TMUX_SWALLOW_FILE:-}" ] && [ -f "$FM_FAKE_TMUX_SWALLOW_FILE" ]; then
+            rm -f "$FM_FAKE_TMUX_SWALLOW_FILE"
+          else
+            printf '[ENTER]\n' >> "${FM_FAKE_TMUX_SENT:-/dev/null}"
+            # Enter submits: clear the last line (the typed text) from the
+            # capture, simulating the composer being cleared on submit.
+            if [ -n "${FM_FAKE_TMUX_CAPTURE:-}" ] && [ -s "$FM_FAKE_TMUX_CAPTURE" ]; then
+              _tmp=$(mktemp 2>/dev/null) || _tmp="${FM_FAKE_TMUX_CAPTURE}.tmp"
+              sed '$d' "$FM_FAKE_TMUX_CAPTURE" > "$_tmp" 2>/dev/null && mv -f "$_tmp" "$FM_FAKE_TMUX_CAPTURE"
+              rm -f "$_tmp" 2>/dev/null
+            fi
+          fi
+          ;;
+      esac
+      shift
+    done
+    exit 0 ;;
+esac
+exit 1
+SH
+  chmod +x "$fakebin/tmux"
+  printf '%s\n' "$dir"
+}
+
+make_bordered_case() {
+  local name=$1 dir fakebin
+  dir="$TMP_ROOT/$name"; fakebin="$dir/fakebin"
+  mkdir -p "$dir/state" "$fakebin"
+  printf '╭─────╮\n│ >   │\n╰─────╯\n' > "$dir/composer"
+  cat > "$fakebin/tmux" <<'SH'
+#!/usr/bin/env bash
+set -u
+COMPOSER="${FM_FAKE_COMPOSER:?FM_FAKE_COMPOSER unset}"
+write_composer() {
+  text=$1
+  width=$((${#text} + 4))
+  border=
+  i=0
+  while [ "$i" -lt "$width" ]; do
+    border="${border}─"
+    i=$((i + 1))
+  done
+  printf '╭%s╮\n│ > %s │\n╰%s╯\n' "$border" "$text" "$border" > "$COMPOSER"
+}
+case "${1:-}" in
+  display-message)
+    print=0
+    for a in "$@"; do case "$a" in *cursor_y*) printf '1\n'; exit 0 ;; esac; done
+    for a in "$@"; do [ "$a" = "-p" ] && print=1; done
+    [ "$print" = 1 ] && printf 'fakepane\n'
+    exit 0 ;;
+  capture-pane) cat "$COMPOSER" 2>/dev/null; exit 0 ;;
+  list-windows) exit 0 ;;
+  send-keys)
+    shift
+    text=""; is_enter=0; lit=0
+    while [ "$#" -gt 0 ]; do
+      case "$1" in
+        -t) shift ;;
+        -l) lit=1 ;;
+        Enter) is_enter=1 ;;
+        *) [ "$lit" = 1 ] && text="$1" ;;
+      esac
+      shift
+    done
+    if [ "$is_enter" = 1 ]; then
+      if [ -n "${FM_FAKE_SWALLOW:-}" ] && [ -f "$FM_FAKE_SWALLOW" ]; then
+        [ "${FM_FAKE_PERSIST_SWALLOW:-0}" = 1 ] || rm -f "$FM_FAKE_SWALLOW"
+      else
+        [ -n "${FM_FAKE_SENT:-}" ] && printf '[ENTER]\n' >> "$FM_FAKE_SENT"
+        write_composer ""
+      fi
+    elif [ "$lit" = 1 ]; then
+      [ "${FM_FAKE_SEND_FAIL:-0}" = 1 ] && exit 1
+      [ -n "${FM_FAKE_SENT:-}" ] && printf '%s\n' "$text" >> "$FM_FAKE_SENT"
+      write_composer "$text"
+    fi
+    exit 0 ;;
+esac
+exit 1
+SH
+  chmod +x "$fakebin/tmux"
+  printf '%s\n' "$dir"
+}
+
+wait_for_exit() {
+  local pid=$1 limit=${2:-50} i=0
+  while [ "$i" -lt "$limit" ]; do
+    if ! is_live_non_zombie "$pid"; then
+      wait "$pid"
+      return "$?"
+    fi
+    sleep 0.1
+    i=$((i + 1))
+  done
+  kill "$pid" 2>/dev/null || true
+  wait "$pid" 2>/dev/null || true
+  return 124
+}
+
+is_live_non_zombie() {
+  local pid=$1 stat
+  kill -0 "$pid" 2>/dev/null || return 1
+  stat=$(ps -p "$pid" -o stat= 2>/dev/null || true)
+  case "$stat" in
+    Z*) return 1 ;;
+  esac
+  return 0
+}
+
+hash_text() {
+  if command -v md5 >/dev/null 2>&1; then
+    printf '%s' "$1" | md5 -q
+  else
+    printf '%s' "$1" | md5sum | cut -d' ' -f1
+  fi
+}
+
+dead_pid() {
+  local p=999999
+  while kill -0 "$p" 2>/dev/null; do
+    p=$((p + 1))
+  done
+  printf '%s\n' "$p"
+}

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

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# tests/zellij-test-safety.sh - shared hard guard against a real-zellij test's
+# cleanup ever touching the machine's real "firstmate" session (the default
+# session name bin/backends/zellij.sh uses for actual firstmate task tabs) or
+# running a fleet-wide destructive command. Mirrors
+# tests/herdr-test-safety.sh's guard, adapted to zellij's session model and
+# the safety rule this task was given directly (never `kill-all-sessions`,
+# the same discipline PR #199 established for herdr after two live-fleet
+# kills - see tests/herdr-test-safety.sh's incident note).
+#
+# Zellij's own risk shape differs from herdr's: there is no ambient
+# `server stop`-style command that silently resolves to "whatever session is
+# currently running" - `zellij kill-session <name>` and
+# `zellij delete-session <name>` both take an explicit, required name. So the
+# realistic failure mode here is not env-var-routing unreliability (herdr's
+# root cause) but a test accidentally reusing (and then killing) the real
+# "firstmate" session name, or a caller reaching for the fleet-wide
+# `kill-all-sessions`/`delete-all-sessions` commands. This guard defends
+# against both: it refuses to touch a session unless the caller can name it
+# explicitly, that name is NOT "firstmate" (the real default), and it is
+# currently listed as a session this test itself is responsible for.
+#
+# Fails CLOSED: any ambiguity (an empty name, the literal default name, a
+# failed/empty session list, a name that does not resolve) refuses rather
+# than proceeding, because the cost of a false refusal (a leaked test
+# session, cleaned up by hand later) is trivially recoverable, while the cost
+# of a false negative (deleting the real session) is not.
+set -u
+
+# zellij_refuse_if_unsafe: 0 (SAFE to proceed) only if <name> is non-empty,
+# is NOT the literal "firstmate" default session name, and IS currently
+# listed as an active zellij session. 1 (REFUSE) on anything else.
+zellij_refuse_if_unsafe() {  # <name>
+  local name=$1 listed
+  [ -n "$name" ] || { echo "zellij safety guard: refusing - empty session name" >&2; return 1; }
+  if [ "$name" = firstmate ]; then
+    echo "zellij safety guard: refusing - name is literally 'firstmate' (the real default session a live fleet may use)" >&2
+    return 1
+  fi
+  listed=$(zellij list-sessions --short --no-formatting 2>/dev/null | grep -qxF "$name" && echo yes || echo no)
+  if [ "$listed" != yes ]; then
+    echo "zellij safety guard: refusing - session '$name' not found in 'zellij list-sessions'" >&2
+    return 1
+  fi
+  return 0
+}
+
+# zellij_safe_delete: the ONLY sanctioned way for a test to tear down an
+# isolated session it created. Guards first (zellij_refuse_if_unsafe), then
+# uses the explicit-by-name `delete-session --force` form (kills if running,
+# then deletes in one call) - NEVER `kill-all-sessions` or
+# `delete-all-sessions`. Best-effort past the guard (a session already gone
+# must not fail the caller's cleanup trap) - but the guard itself is NOT
+# best-effort: a refusal here means cleanup leaves the isolated, throwaway,
+# never-"firstmate" session running rather than risk the wrong target.
+zellij_safe_delete() {  # <name>
+  local name=$1
+  zellij_refuse_if_unsafe "$name" || return 1
+  zellij delete-session "$name" --force >/dev/null 2>&1 || true
+}