@zerwiz/ymir 0.1.4 → 0.1.5

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

@@ -0,0 +1,346 @@
+#!/usr/bin/env bash
+# Provision and operate an isolated Herdr lab session without risking the live
+# default session.
+#
+# Usage:
+#   fm-herdr-lab.sh name <label>
+#   fm-herdr-lab.sh prepare <session>
+#   fm-herdr-lab.sh provision <session>
+#   fm-herdr-lab.sh run <session> <herdr arguments...>
+#   fm-herdr-lab.sh stop <session>
+#   fm-herdr-lab.sh teardown <session>
+#
+# Session names must begin with "fm-lab-" and can never be "default".
+# The name command sanitizes the label, caps it at 16 characters, and appends
+# process/random suffixes to keep generated socket paths short.
+# Every Herdr call made here carries a trailing --session <session>.
+# The run command rejects caller-supplied --session flags, any leading option
+# before the subcommand, all session lifecycle operations, and every server
+# operation.
+# Session stop is available only through guarded stop or teardown, and session
+# delete is available only through teardown.
+# Both paths perform a fresh refuse-default check immediately before each
+# destructive call.
+# Provision records the running default session as a fleet-state tripwire and
+# teardown requires that record to be identical afterward.
+set -u
+
+fm_herdr_lab_error() {
+  echo "fm-herdr-lab: $*" >&2
+}
+
+fm_herdr_lab_validate_name() { # <session>
+  local name=${1:-}
+  [[ "$name" =~ ^fm-lab-[a-zA-Z0-9][a-zA-Z0-9_-]*$ ]] && return 0
+  case "$name" in
+    default) fm_herdr_lab_error "refusing session name 'default'" ;;
+    '') fm_herdr_lab_error "refusing an empty session name" ;;
+    *) fm_herdr_lab_error "session name must start with 'fm-lab-' and contain only letters, digits, underscores, or dashes: $name" ;;
+  esac
+  return 1
+}
+
+fm_herdr_lab_state_dir() {
+  printf '%s' "${FM_HERDR_LAB_STATE_DIR:-${TMPDIR:-/tmp}/fm-herdr-lab-${UID}}"
+}
+
+fm_herdr_lab_tripwire_path() { # <session>
+  printf '%s/%s.fleet-state.json' "$(fm_herdr_lab_state_dir)" "$1"
+}
+
+fm_herdr_lab_raw() { # <session> <herdr arguments...>
+  local name=$1
+  shift
+  HERDR_SESSION="$name" herdr "$@" --session "$name"
+}
+
+fm_herdr_lab_session_list() { # <session>
+  fm_herdr_lab_raw "$1" session list --json
+}
+
+fm_herdr_lab_fleet_state() { # <session>
+  local name=$1 sessions snapshot
+  sessions=$(fm_herdr_lab_session_list "$name" 2>/dev/null) || {
+    fm_herdr_lab_error "cannot read Herdr sessions for the fleet-state tripwire"
+    return 1
+  }
+  snapshot=$(printf '%s' "$sessions" | jq -c '
+    [.sessions[]? | select(.default == true)]
+    | if length == 1 and .[0].name == "default" and .[0].running == true
+      then .[0] | {name, default, running, socket_path}
+      else empty
+      end
+  ' 2>/dev/null)
+  [ -n "$snapshot" ] || {
+    fm_herdr_lab_error "fleet-state tripwire requires exactly one running default session"
+    return 1
+  }
+  printf '%s\n' "$snapshot"
+}
+
+fm_herdr_lab_prepare() { # <session>
+  local name=$1 sessions state_dir tripwire
+  fm_herdr_lab_validate_name "$name" || return 1
+  command -v herdr >/dev/null 2>&1 || { fm_herdr_lab_error "herdr is required"; return 1; }
+  command -v jq >/dev/null 2>&1 || { fm_herdr_lab_error "jq is required"; return 1; }
+
+  sessions=$(fm_herdr_lab_session_list "$name" 2>/dev/null) || {
+    fm_herdr_lab_error "cannot list Herdr sessions before provisioning '$name'"
+    return 1
+  }
+  if printf '%s' "$sessions" | jq -e --arg name "$name" '.sessions[]? | select(.name == $name)' >/dev/null 2>&1; then
+    fm_herdr_lab_error "session '$name' already exists; refusing to adopt or overwrite it"
+    return 1
+  fi
+
+  state_dir=$(fm_herdr_lab_state_dir)
+  tripwire=$(fm_herdr_lab_tripwire_path "$name")
+  mkdir -p "$state_dir" || return 1
+  [ ! -e "$tripwire" ] || {
+    fm_herdr_lab_error "tripwire already exists for '$name'; refusing ambiguous ownership"
+    return 1
+  }
+  fm_herdr_lab_fleet_state "$name" > "$tripwire" || {
+    rm -f "$tripwire"
+    return 1
+  }
+}
+
+fm_herdr_lab_refuse_if_default() { # <session>
+  local name=$1 info flag
+  fm_herdr_lab_validate_name "$name" || return 1
+  info=$(fm_herdr_lab_session_list "$name" 2>/dev/null) || {
+    fm_herdr_lab_error "refusing destructive call because session list failed"
+    return 1
+  }
+  flag=$(printf '%s' "$info" | jq -r --arg name "$name" \
+    '.sessions[]? | select(.name == $name) | .default' 2>/dev/null)
+  [ "$flag" = false ] && return 0
+  fm_herdr_lab_error "refusing destructive call for '$name': session is absent or default (default=${flag:-<not found>})"
+  return 1
+}
+
+fm_herdr_lab_cli() { # <session> <herdr arguments...>
+  local name=$1 arg
+  shift
+  fm_herdr_lab_validate_name "$name" || return 1
+  [ "$#" -gt 0 ] || { fm_herdr_lab_error "run requires Herdr arguments"; return 1; }
+  case "$1" in
+    -*)
+      fm_herdr_lab_error "run forbids a leading option before the Herdr subcommand; it could shift a server or session lifecycle operation past the guard or subvert session isolation"
+      return 1
+      ;;
+  esac
+  for arg in "$@"; do
+    case "$arg" in
+      --session|--session=*)
+        fm_herdr_lab_error "run forbids caller-supplied --session; the helper appends the lab session"
+        return 1
+        ;;
+    esac
+  done
+  case "$1 ${2:-}" in
+    "server "*)
+      fm_herdr_lab_error "run forbids server operations; use provision for the named lab server"
+      return 1
+      ;;
+    "session list") ;;
+    "session "*)
+      fm_herdr_lab_error "run forbids session lifecycle operations; use guarded teardown"
+      return 1
+      ;;
+  esac
+  fm_herdr_lab_raw "$name" "$@"
+}
+
+fm_herdr_lab_cancel_provision() { # <pid>
+  local pid=$1 attempt=0
+  if kill -0 "$pid" 2>/dev/null; then
+    kill -TERM "$pid" 2>/dev/null || true
+    while kill -0 "$pid" 2>/dev/null && [ "$attempt" -lt 10 ]; do
+      sleep 0.1
+      attempt=$((attempt + 1))
+    done
+    if kill -0 "$pid" 2>/dev/null; then
+      kill -KILL "$pid" 2>/dev/null || true
+    fi
+  fi
+  wait "$pid" 2>/dev/null || true
+}
+
+fm_herdr_lab_provision() { # <session>
+  local name=$1 sessions tripwire running attempt server_pid max_attempts timeout_seconds
+  fm_herdr_lab_validate_name "$name" || return 1
+  command -v herdr >/dev/null 2>&1 || { fm_herdr_lab_error "herdr is required"; return 1; }
+  command -v jq >/dev/null 2>&1 || { fm_herdr_lab_error "jq is required"; return 1; }
+
+  sessions=$(fm_herdr_lab_session_list "$name" 2>/dev/null) || {
+    fm_herdr_lab_error "cannot list Herdr sessions before provisioning '$name'"
+    return 1
+  }
+  if printf '%s' "$sessions" | jq -e --arg name "$name" '.sessions[]? | select(.name == $name)' >/dev/null 2>&1; then
+    tripwire=$(fm_herdr_lab_tripwire_path "$name")
+    [ -f "$tripwire" ] || {
+      fm_herdr_lab_error "missing fleet-state tripwire for existing session '$name'; refusing to adopt it"
+      return 1
+    }
+    fm_herdr_lab_refuse_if_default "$name" || return 1
+    running=$(printf '%s' "$sessions" | jq -r --arg name "$name" \
+      '.sessions[]? | select(.name == $name) | .running' 2>/dev/null)
+    [ "$running" = false ] || {
+      fm_herdr_lab_error "session '$name' is not stopped; refusing to re-provision it"
+      return 1
+    }
+    fm_herdr_lab_check_tripwire "$name" || return 1
+  else
+    fm_herdr_lab_prepare "$name" || return 1
+  fi
+  fm_herdr_lab_raw "$name" server >/dev/null 2>&1 &
+  server_pid=$!
+  attempt=0
+  max_attempts=300
+  timeout_seconds=60
+  while [ "$attempt" -lt "$max_attempts" ]; do
+    running=$(fm_herdr_lab_cli "$name" status --json 2>/dev/null | jq -r '.server.running // false' 2>/dev/null) || running=false
+    if [ "$running" = true ]; then
+      fm_herdr_lab_refuse_if_default "$name" || {
+        fm_herdr_lab_cancel_provision "$server_pid"
+        return 1
+      }
+      return 0
+    fi
+    sleep 0.2
+    attempt=$((attempt + 1))
+  done
+  fm_herdr_lab_cancel_provision "$server_pid"
+  fm_herdr_lab_error "lab session '$name' did not report running within $timeout_seconds seconds"
+  return 1
+}
+
+fm_herdr_lab_check_tripwire() { # <session>
+  local name=$1 tripwire before after
+  tripwire=$(fm_herdr_lab_tripwire_path "$name")
+  [ -f "$tripwire" ] || {
+    fm_herdr_lab_error "missing fleet-state tripwire for '$name'; refusing unverified teardown"
+    return 1
+  }
+  before=$(cat "$tripwire")
+  after=$(fm_herdr_lab_fleet_state "$name") || return 1
+  [ "$before" = "$after" ] || {
+    fm_herdr_lab_error "FLEET-STATE TRIPWIRE FAILED: default session changed during lab work"
+    fm_herdr_lab_error "before: $before"
+    fm_herdr_lab_error "after:  $after"
+    return 1
+  }
+}
+
+fm_herdr_lab_verify_tripwire() { # <session>
+  local name=$1 tripwire
+  fm_herdr_lab_check_tripwire "$name" || return 1
+  tripwire=$(fm_herdr_lab_tripwire_path "$name")
+  rm -f "$tripwire"
+}
+
+fm_herdr_lab_stop() { # <session>
+  local name=$1 tripwire
+  fm_herdr_lab_validate_name "$name" || return 1
+  tripwire=$(fm_herdr_lab_tripwire_path "$name")
+  [ -f "$tripwire" ] || {
+    fm_herdr_lab_error "missing fleet-state tripwire for '$name'; refusing stop"
+    return 1
+  }
+  fm_herdr_lab_refuse_if_default "$name" || return 1
+  fm_herdr_lab_raw "$name" session stop "$name" --json
+}
+
+fm_herdr_lab_teardown() { # <session>
+  local name=$1 tripwire sessions delete_status=0
+  fm_herdr_lab_validate_name "$name" || return 1
+  tripwire=$(fm_herdr_lab_tripwire_path "$name")
+  [ -f "$tripwire" ] || {
+    fm_herdr_lab_error "missing fleet-state tripwire for '$name'; refusing destructive calls"
+    return 1
+  }
+  sessions=$(fm_herdr_lab_session_list "$name" 2>/dev/null) || {
+    fm_herdr_lab_error "cannot list Herdr sessions before teardown"
+    return 1
+  }
+  if ! printf '%s' "$sessions" | jq -e --arg name "$name" '.sessions[]? | select(.name == $name)' >/dev/null 2>&1; then
+    fm_herdr_lab_verify_tripwire "$name"
+    return
+  fi
+  fm_herdr_lab_stop "$name" >/dev/null 2>&1 || true
+  sleep 0.5
+  fm_herdr_lab_refuse_if_default "$name" || return 1
+  fm_herdr_lab_raw "$name" session delete "$name" --json >/dev/null 2>&1 || delete_status=$?
+  sessions=$(fm_herdr_lab_session_list "$name" 2>/dev/null) || {
+    fm_herdr_lab_error "cannot confirm removal of lab session '$name' after teardown"
+    return 1
+  }
+  if printf '%s' "$sessions" | jq -e --arg name "$name" '.sessions[]? | select(.name == $name)' >/dev/null 2>&1; then
+    if [ "$delete_status" -ne 0 ]; then
+      fm_herdr_lab_error "session delete failed for '$name' and the lab session remains"
+    else
+      fm_herdr_lab_error "lab session '$name' remains after teardown"
+    fi
+    return 1
+  fi
+  fm_herdr_lab_verify_tripwire "$name"
+}
+
+fm_herdr_lab_name() { # <label>
+  local label=${1:-lab}
+  label=$(printf '%s' "$label" | tr -cd 'a-zA-Z0-9_-' | sed 's/^[^a-zA-Z0-9]*//; s/-*$//')
+  [ -n "$label" ] || label=lab
+  label=${label:0:16}
+  label=${label%-}
+  [ -n "$label" ] || label=lab
+  printf 'fm-lab-%s-%s-%s\n' "$label" "$$" "$RANDOM"
+}
+
+fm_herdr_lab_usage() {
+  sed -n '2,13p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+fm_herdr_lab_main() {
+  local command=${1:-}
+  case "$command" in
+    name)
+      [ "$#" -eq 2 ] || { fm_herdr_lab_usage >&2; return 2; }
+      fm_herdr_lab_name "$2"
+      ;;
+    prepare)
+      [ "$#" -eq 2 ] || { fm_herdr_lab_usage >&2; return 2; }
+      fm_herdr_lab_prepare "$2"
+      ;;
+    provision)
+      [ "$#" -eq 2 ] || { fm_herdr_lab_usage >&2; return 2; }
+      fm_herdr_lab_provision "$2"
+      ;;
+    run)
+      [ "$#" -ge 3 ] || { fm_herdr_lab_usage >&2; return 2; }
+      shift
+      fm_herdr_lab_cli "$@"
+      ;;
+    stop)
+      [ "$#" -eq 2 ] || { fm_herdr_lab_usage >&2; return 2; }
+      fm_herdr_lab_stop "$2"
+      ;;
+    teardown)
+      [ "$#" -eq 2 ] || { fm_herdr_lab_usage >&2; return 2; }
+      fm_herdr_lab_teardown "$2"
+      ;;
+    -h|--help|help)
+      fm_herdr_lab_usage
+      ;;
+    *)
+      fm_herdr_lab_usage >&2
+      return 2
+      ;;
+  esac
+}
+
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+  set -e
+  fm_herdr_lab_main "$@"
+fi

package/.agents/backend/fm-herdr-session-cleanup.sh

@@ -0,0 +1,337 @@
+#!/usr/bin/env bash
+# Retire stale restored-shell Herdr presentation children at locked session start.
+#
+# Usage: fm-herdr-session-cleanup.sh
+#
+# The caller must already own this Firstmate home's session lock. This script is
+# home-local and considers only the current named Herdr session and ordinary
+# state/*.herdr-presentation journals in the effective FM_HOME. Each candidate
+# is additionally serialized by the existing state/.spawn-<task>.lock and the
+# shared named-session Herdr presentation lock, in that order.
+#
+# A visible title is discovery only. Cleanup requires the exact current
+# "└ <concise-task> · p:<22-char-token>" grammar, one token occurrence across
+# the named-session snapshot, exactly one matching home-local journal, one tab,
+# one pane, absent task metadata, no registered agent, and a process proof that
+# the pane contains only one idle recognized shell with no child process. A
+# version 2 journal must also bind the exact workspace, tab, and pane.
+# Topology is first checked from one locked API snapshot, then every mutation
+# prerequisite is immediately rechecked before the existing exact-pane
+# focus-preserving close helper is called.
+# The script never closes a workspace. It removes only the matching journal,
+# and only after the exact pane is confirmed gone. Every error warns and returns
+# success so session startup continues conservatively.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FM_ROOT="${FM_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+FM_HOME="${FM_HOME:-${FM_ROOT_OVERRIDE:-$FM_ROOT}}"
+STATE="${FM_STATE_OVERRIDE:-$FM_HOME/state}"
+
+# shellcheck source=bin/fm-wake-lib.sh
+. "$SCRIPT_DIR/fm-wake-lib.sh"
+# shellcheck source=bin/fm-backend.sh
+. "$SCRIPT_DIR/fm-backend.sh"
+fm_backend_source herdr
+# shellcheck source=bin/fm-pr-lib.sh
+. "$SCRIPT_DIR/fm-pr-lib.sh"
+
+fm_herdr_cleanup_warn() {
+  printf 'warning: herdr session-start projection cleanup: %s\n' "$*" >&2
+}
+
+fm_herdr_cleanup_title_token() { # <workspace-title>
+  local title=$1 prefix token rest
+  case "$title" in
+    '└ '*' · p:'*) ;;
+    *) return 1 ;;
+  esac
+  token=${title##*' · p:'}
+  prefix=${title%" · p:$token"}
+  [ "$prefix" != "$title" ] && [ -n "${prefix#'└ '}" ] || return 1
+  [ "${#token}" -eq 22 ] || return 1
+  case "$token" in *[!A-Za-z0-9_-]*) return 1 ;; esac
+  rest=${title#*p:}
+  [ "$rest" != "$title" ] || return 1
+  case "$rest" in *p:*) return 1 ;; esac
+  printf '%s' "$token"
+}
+
+fm_herdr_cleanup_home_identity() {
+  [ -d "$FM_HOME" ] && [ ! -L "$FM_HOME" ] || return 1
+  (cd "$FM_HOME" 2>/dev/null && pwd -P)
+}
+
+fm_herdr_cleanup_journal_matches() { # <title> <session> <home-real>
+  local title=$1 session=$2 home_real=$3 journal id expected journal_home
+  [ -d "$STATE" ] && [ ! -L "$STATE" ] || return 1
+  for journal in "$STATE"/*"$FM_BACKEND_HERDR_PRESENTATION_JOURNAL_SUFFIX"; do
+    [ -f "$journal" ] && [ ! -L "$journal" ] || continue
+    id=$(basename "$journal" "$FM_BACKEND_HERDR_PRESENTATION_JOURNAL_SUFFIX")
+    fm_task_id_creation_valid "$id" || continue
+    fm_backend_herdr_projection_journal_snapshot "$journal" "$id" || continue
+    if [ "$FM_BACKEND_HERDR_JOURNAL_VERSION" = 2 ]; then
+      journal_home=$(fm_backend_herdr_projection_home_identity \
+        "$FM_BACKEND_HERDR_JOURNAL_HOME" 2>/dev/null) || continue
+      [ "$journal_home" = "$home_real" ] \
+        && [ "$FM_BACKEND_HERDR_JOURNAL_SESSION" = "$session" ] || continue
+    fi
+    expected=$(fm_backend_herdr_projection_workspace_label \
+      "$id" "$FM_BACKEND_HERDR_JOURNAL_PROJECTION_ID")
+    [ "$expected" = "$title" ] || continue
+    printf '%s\t%s\t%s\n' "$journal" "$id" "$FM_BACKEND_HERDR_JOURNAL_PROJECTION_ID"
+  done
+}
+
+fm_herdr_cleanup_unique_match() { # <title> <session> <home-real>
+  local title=$1 session=$2 home_real=$3 matches count record
+  FM_HERDR_CLEANUP_JOURNAL=
+  FM_HERDR_CLEANUP_ID=
+  FM_HERDR_CLEANUP_TOKEN=
+  FM_HERDR_CLEANUP_VERSION=
+  FM_HERDR_CLEANUP_BOUND_WORKSPACE=
+  FM_HERDR_CLEANUP_BOUND_TAB=
+  FM_HERDR_CLEANUP_BOUND_PANE=
+  matches=$(fm_herdr_cleanup_journal_matches "$title" "$session" "$home_real") || return 1
+  count=$(printf '%s\n' "$matches" | awk 'NF { n++ } END { print n+0 }')
+  [ "$count" -eq 1 ] || return 1
+  record=$(printf '%s\n' "$matches" | awk 'NF { print; exit }')
+  FM_HERDR_CLEANUP_JOURNAL=${record%%$'\t'*}
+  record=${record#*$'\t'}
+  FM_HERDR_CLEANUP_ID=${record%%$'\t'*}
+  FM_HERDR_CLEANUP_TOKEN=${record#*$'\t'}
+  [ -n "$FM_HERDR_CLEANUP_JOURNAL" ] \
+    && [ -n "$FM_HERDR_CLEANUP_ID" ] \
+    && [ -n "$FM_HERDR_CLEANUP_TOKEN" ] || return 1
+  fm_backend_herdr_projection_journal_snapshot \
+    "$FM_HERDR_CLEANUP_JOURNAL" "$FM_HERDR_CLEANUP_ID" || return 1
+  [ "$FM_BACKEND_HERDR_JOURNAL_PROJECTION_ID" = "$FM_HERDR_CLEANUP_TOKEN" ] || return 1
+  FM_HERDR_CLEANUP_VERSION=$FM_BACKEND_HERDR_JOURNAL_VERSION
+  if [ "$FM_HERDR_CLEANUP_VERSION" = 2 ]; then
+    FM_HERDR_CLEANUP_BOUND_WORKSPACE=$FM_BACKEND_HERDR_JOURNAL_WORKSPACE_ID
+    FM_HERDR_CLEANUP_BOUND_TAB=$FM_BACKEND_HERDR_JOURNAL_TAB_ID
+    FM_HERDR_CLEANUP_BOUND_PANE=$FM_BACKEND_HERDR_JOURNAL_PANE_ID
+  fi
+}
+
+fm_herdr_cleanup_snapshot_candidate() { # <snapshot> <workspace> <title> <token> <bound-workspace> <bound-tab> <bound-pane>
+  local snapshot=$1 workspace=$2 title=$3 token=$4
+  local bound_workspace=$5 bound_tab=$6 bound_pane=$7 record
+  FM_HERDR_CLEANUP_TAB=
+  FM_HERDR_CLEANUP_PANE=
+  record=$(printf '%s' "$snapshot" | jq -er \
+    --arg workspace "$workspace" --arg title "$title" --arg token "$token" \
+    --arg bound_workspace "$bound_workspace" --arg bound_tab "$bound_tab" \
+    --arg bound_pane "$bound_pane" '
+    .result.snapshot as $s
+    | [$s.workspaces[]? | select(.workspace_id == $workspace)] as $workspaces
+    | [$s.tabs[]? | select(.workspace_id == $workspace)] as $tabs
+    | [$s.panes[]? | select(.workspace_id == $workspace)] as $panes
+    | ([ $s.workspaces[]?.label? // "" |
+         ((split("p:" + $token) | length) - 1) ] | add // 0) as $token_count
+    | select($workspaces | length == 1)
+    | select($workspaces[0].label == $title)
+    | select($workspaces[0].tab_count == 1 and $workspaces[0].pane_count == 1)
+    | select($tabs | length == 1)
+    | select($panes | length == 1)
+    | select($panes[0].tab_id == $tabs[0].tab_id)
+    | select($bound_workspace == "" or $workspace == $bound_workspace)
+    | select($bound_tab == "" or $tabs[0].tab_id == $bound_tab)
+    | select($bound_pane == "" or $panes[0].pane_id == $bound_pane)
+    | select($token_count == 1)
+    | select(($s.focused_workspace_id | type) == "string")
+    | select(($s.focused_tab_id | type) == "string")
+    | select(($s.focused_pane_id | type) == "string")
+    | select($s.focused_tab_id != $tabs[0].tab_id)
+    | [$tabs[0].tab_id, $panes[0].pane_id] | @tsv
+  ' 2>/dev/null) || return 1
+  [ -n "$record" ] && [ "${record#*$'\t'}" != "$record" ] || return 1
+  FM_HERDR_CLEANUP_TAB=${record%%$'\t'*}
+  FM_HERDR_CLEANUP_PANE=${record#*$'\t'}
+  [ -n "$FM_HERDR_CLEANUP_TAB" ] && [ -n "$FM_HERDR_CLEANUP_PANE" ]
+}
+
+fm_herdr_cleanup_revalidate() { # <session> <workspace> <tab> <pane> <title> <token> <home-real> <journal> <task-id> <version> <bound-workspace> <bound-tab> <bound-pane>
+  local session=$1 workspace=$2 tab=$3 pane=$4 title=$5 token=$6 home_real=$7
+  local journal=$8 id=$9 version=${10} bound_workspace=${11} bound_tab=${12} bound_pane=${13}
+  local workspaces workspace_info tabs panes focus
+  [ ! -e "$STATE/$id.meta" ] && [ ! -L "$STATE/$id.meta" ] || return 1
+  fm_herdr_cleanup_unique_match "$title" "$session" "$home_real" || return 1
+  [ "$FM_HERDR_CLEANUP_JOURNAL" = "$journal" ] \
+    && [ "$FM_HERDR_CLEANUP_ID" = "$id" ] \
+    && [ "$FM_HERDR_CLEANUP_TOKEN" = "$token" ] \
+    && [ "$FM_HERDR_CLEANUP_VERSION" = "$version" ] \
+    && [ "$FM_HERDR_CLEANUP_BOUND_WORKSPACE" = "$bound_workspace" ] \
+    && [ "$FM_HERDR_CLEANUP_BOUND_TAB" = "$bound_tab" ] \
+    && [ "$FM_HERDR_CLEANUP_BOUND_PANE" = "$bound_pane" ] || return 1
+
+  workspaces=$(fm_backend_herdr_cli "$session" workspace list 2>/dev/null) || return 1
+  printf '%s' "$workspaces" | jq -e --arg workspace "$workspace" --arg title "$title" --arg token "$token" '
+    ([.result.workspaces[]? | select(.workspace_id == $workspace and .label == $title)] | length) == 1
+    and ([.result.workspaces[]?.label? // "" |
+          ((split("p:" + $token) | length) - 1)] | add // 0) == 1
+  ' >/dev/null 2>&1 || return 1
+  workspace_info=$(fm_backend_herdr_cli "$session" workspace get "$workspace" 2>/dev/null) || return 1
+  printf '%s' "$workspace_info" | jq -e --arg workspace "$workspace" --arg title "$title" '
+    .result.workspace.workspace_id == $workspace
+    and .result.workspace.label == $title
+    and .result.workspace.tab_count == 1
+    and .result.workspace.pane_count == 1
+  ' >/dev/null 2>&1 || return 1
+  tabs=$(fm_backend_herdr_cli "$session" tab list --workspace "$workspace" 2>/dev/null) || return 1
+  printf '%s' "$tabs" | jq -e --arg workspace "$workspace" --arg tab "$tab" '
+    (.result.tabs | type) == "array"
+    and (.result.tabs | length) == 1
+    and .result.tabs[0].workspace_id == $workspace
+    and .result.tabs[0].tab_id == $tab
+  ' >/dev/null 2>&1 || return 1
+  panes=$(fm_backend_herdr_cli "$session" pane list --workspace "$workspace" 2>/dev/null) || return 1
+  printf '%s' "$panes" | jq -e --arg workspace "$workspace" --arg tab "$tab" --arg pane "$pane" '
+    (.result.panes | type) == "array"
+    and (.result.panes | length) == 1
+    and .result.panes[0].workspace_id == $workspace
+    and .result.panes[0].tab_id == $tab
+    and .result.panes[0].pane_id == $pane
+  ' >/dev/null 2>&1 || return 1
+  [ "$(fm_backend_herdr_pane_agent_state "$session" "$pane")" = no-agent ] || return 1
+  fm_backend_herdr_pane_idle_shell_pid "$session" "$pane" >/dev/null || return 1
+  focus=$(fm_backend_herdr_projection_focus_snapshot "$session") || return 1
+  [ "${focus#*$'\t'}" != "$tab" ]
+}
+
+fm_herdr_cleanup_one() { # <session> <workspace> <title> <home-real>
+  local session=$1 workspace=$2 title=$3 home_real=$4 token journal id task_lock
+  local version bound_workspace bound_tab bound_pane presentation_lock snapshot
+  local tab pane state close_status=0
+  token=$(fm_herdr_cleanup_title_token "$title") || return 0
+  if ! fm_herdr_cleanup_unique_match "$title" "$session" "$home_real"; then
+    return 0
+  fi
+  journal=$FM_HERDR_CLEANUP_JOURNAL
+  id=$FM_HERDR_CLEANUP_ID
+  version=$FM_HERDR_CLEANUP_VERSION
+  bound_workspace=$FM_HERDR_CLEANUP_BOUND_WORKSPACE
+  bound_tab=$FM_HERDR_CLEANUP_BOUND_TAB
+  bound_pane=$FM_HERDR_CLEANUP_BOUND_PANE
+  [ "$FM_HERDR_CLEANUP_TOKEN" = "$token" ] || return 0
+  task_lock="$STATE/.spawn-$id.lock"
+  if ! fm_lock_try_acquire "$task_lock"; then
+    fm_herdr_cleanup_warn "$id skipped because its task lock is busy"
+    return 0
+  fi
+  presentation_lock=$(fm_backend_herdr_presentation_session_lock_path "$session" 2>/dev/null) || {
+    fm_lock_release "$task_lock" || true
+    fm_herdr_cleanup_warn "$id skipped because the shared presentation lock is unavailable"
+    return 0
+  }
+  if ! fm_lock_try_acquire "$presentation_lock"; then
+    fm_lock_release "$task_lock" || true
+    fm_herdr_cleanup_warn "$id skipped because the shared presentation lock is busy"
+    return 0
+  fi
+
+  if [ -e "$STATE/$id.meta" ] || [ -L "$STATE/$id.meta" ]; then
+    fm_lock_release "$presentation_lock" || true
+    fm_lock_release "$task_lock" || true
+    return 0
+  fi
+  snapshot=$(fm_backend_herdr_cli "$session" api snapshot 2>/dev/null) || snapshot=
+  if [ -z "$snapshot" ] \
+    || ! fm_herdr_cleanup_snapshot_candidate \
+      "$snapshot" "$workspace" "$title" "$token" \
+      "$bound_workspace" "$bound_tab" "$bound_pane"; then
+    fm_herdr_cleanup_warn "$id preserved because its locked candidate snapshot was ambiguous"
+    fm_lock_release "$presentation_lock" || true
+    fm_lock_release "$task_lock" || true
+    return 0
+  fi
+  tab=$FM_HERDR_CLEANUP_TAB
+  pane=$FM_HERDR_CLEANUP_PANE
+  if [ "$(fm_backend_herdr_pane_agent_state "$session" "$pane")" != no-agent ] \
+    || ! fm_backend_herdr_pane_idle_shell_pid "$session" "$pane" >/dev/null; then
+    fm_herdr_cleanup_warn "$id preserved because its pane is not a provably idle childless shell"
+    fm_lock_release "$presentation_lock" || true
+    fm_lock_release "$task_lock" || true
+    return 0
+  fi
+  if ! fm_herdr_cleanup_revalidate \
+    "$session" "$workspace" "$tab" "$pane" "$title" "$token" "$home_real" \
+    "$journal" "$id" "$version" "$bound_workspace" "$bound_tab" "$bound_pane"; then
+    fm_herdr_cleanup_warn "$id preserved because immediate revalidation changed or was unreadable"
+    fm_lock_release "$presentation_lock" || true
+    fm_lock_release "$task_lock" || true
+    return 0
+  fi
+
+  # This unconditional retirement is the authorized containment documented
+  # with the presentation floor ownership in bin/backends/herdr.sh.
+  fm_backend_herdr_projection_close_pane_focus_preserving \
+    "$session" "$pane" no-agent || close_status=$?
+  state=$(fm_backend_herdr_pane_agent_state "$session" "$pane")
+  if [ "$state" = dead ]; then
+    if [ -f "$journal" ] && [ ! -L "$journal" ] \
+      && fm_herdr_cleanup_unique_match "$title" "$session" "$home_real" \
+      && [ "$FM_HERDR_CLEANUP_JOURNAL" = "$journal" ] \
+      && [ "$FM_HERDR_CLEANUP_ID" = "$id" ] \
+      && [ "$FM_HERDR_CLEANUP_VERSION" = "$version" ] \
+      && [ "$FM_HERDR_CLEANUP_BOUND_WORKSPACE" = "$bound_workspace" ] \
+      && [ "$FM_HERDR_CLEANUP_BOUND_TAB" = "$bound_tab" ] \
+      && [ "$FM_HERDR_CLEANUP_BOUND_PANE" = "$bound_pane" ] \
+      && [ ! -e "$STATE/$id.meta" ] && [ ! -L "$STATE/$id.meta" ]; then
+      rm -f -- "$journal" || fm_herdr_cleanup_warn "$id pane closed but its journal could not be retired"
+    else
+      fm_herdr_cleanup_warn "$id pane closed but its journal changed and was preserved"
+    fi
+  elif [ "$close_status" -ne 0 ]; then
+    fm_herdr_cleanup_warn "$id preserved because exact focus-safe pane closure was refused or unconfirmed"
+  else
+    fm_herdr_cleanup_warn "$id preserved because exact pane closure could not be confirmed"
+  fi
+  fm_lock_release "$presentation_lock" || true
+  fm_lock_release "$task_lock" || true
+  return 0
+}
+
+fm_herdr_session_cleanup() {
+  local session home_real list candidates workspace title journal found=0
+  [ -d "$STATE" ] && [ ! -L "$STATE" ] || return 0
+  for journal in "$STATE"/*"$FM_BACKEND_HERDR_PRESENTATION_JOURNAL_SUFFIX"; do
+    if [ -f "$journal" ] && [ ! -L "$journal" ]; then
+      found=1
+      break
+    fi
+  done
+  [ "$found" -eq 1 ] || return 0
+  command -v herdr >/dev/null 2>&1 \
+    && command -v jq >/dev/null 2>&1 || return 0
+  home_real=$(fm_herdr_cleanup_home_identity) || {
+    fm_herdr_cleanup_warn 'home identity is unreadable; preserving every candidate'
+    return 0
+  }
+  session=$(fm_backend_herdr_session)
+  list=$(fm_backend_herdr_cli "$session" workspace list 2>/dev/null) || {
+    fm_herdr_cleanup_warn "session '$session' workspace discovery failed; preserving every candidate"
+    return 0
+  }
+  candidates=$(printf '%s' "$list" | jq -er '
+    .result.workspaces
+    | select(type == "array")
+    | .[]
+    | select((.workspace_id | type) == "string" and (.workspace_id | length) > 0)
+    | select((.label | type) == "string" and (.label | length) > 0)
+    | [.workspace_id, .label] | @tsv
+  ' 2>/dev/null) || {
+    fm_herdr_cleanup_warn "session '$session' workspace discovery was unreadable; preserving every candidate"
+    return 0
+  }
+  while IFS=$'\t' read -r workspace title; do
+    [ -n "$workspace" ] && [ -n "$title" ] || continue
+    fm_herdr_cleanup_one "$session" "$workspace" "$title" "$home_real"
+  done <<< "$candidates"
+  return 0
+}
+
+if [ "${FM_HERDR_SESSION_CLEANUP_SOURCE_ONLY:-0}" != 1 ]; then
+  fm_herdr_session_cleanup
+  exit 0
+fi