@zerwiz/ymir 0.1.4 → 0.1.7

package/.agents/backend/fm-x-lib.sh

@@ -0,0 +1,1000 @@
+#!/usr/bin/env bash
+# Shared config resolution for the X-mode connector client (fm-x-poll.sh and
+# fm-x-reply.sh). X mode is opt-in: a user drops a non-empty FMX_PAIRING_TOKEN
+# into the firstmate home's .env. FMX_ENV_FILE can point direct client calls at
+# another .env-style file, but bootstrap activation still checks $FM_HOME/.env.
+# Until then polling is a hard no-op; replies can still run in FMX_DRY_RUN
+# preview mode without a token.
+#
+# This file is sourced, never executed. It defines:
+#   fmx_env_get <key> <file>   - read one KEY=VALUE from a .env-style file
+#   fmx_load_config            - resolve FMX_TOKEN, FMX_RELAY, FMX_DRY, FMX_MAX,
+#                                and FMX_THREAD_MAX (env wins over .env)
+#   fmx_auth_header_file       - write the bearer header to a 0600 temp file
+#   fmx_extract_reply_context <json-file> - the single owner of reply-context
+#                                extraction: infer {platform, reply_max_chars}
+#                                from any mention/relay payload file
+#   fmx_request_inbox_context <state> <request_id> - reply context from a stashed
+#                                mention payload (wrapper over the extractor)
+#   fmx_request_relay_context <request_id> - resolve reply platform/limit
+#                                AUTHORITATIVELY from the relay by request_id when
+#                                no local inbox payload survives
+#   fmx_context_registry_set <state> <request_id> <platform> <reply-max> [refresh]
+#                                - persist the durable per-request reply context;
+#                                refresh=1 resets its retention timestamp
+#   fmx_offer_registry_claim <state> <request_id> - atomically claim the durable
+#                                one-wake offer marker; 0=new, 1=existing, 2=error
+#   fmx_context_registry_prune <state> - remove records older than seven days
+#   fmx_context_registry_get <state> <request_id> - read the durable per-request
+#                                reply context, or the empty shape when absent
+#   fmx_context_registry_clear <state> <request_id> - drop the durable record
+#   fmx_resolve_reply_context <state> <request_id> <allow-relay> - resolve reply
+#                                context through registry -> inbox -> relay
+#   fmx_reply_limit_for_platform <platform> <explicit-limit> - pick split budget
+#   fmx_split_thread <max> <cap> - split a reply (stdin) into a numbered thread
+#   fmx_image_payload_file <path> <client> <payload-file> - encode one image
+#                                attachment to a JSON file and print preview JSON
+#   fmx_reply_payload_json <request_id> <chunks> <n> [image-json-file]
+#                                - build the answer/followup POST body
+#   fmx_reply_outbox_json <request_id> <chunks> <n> <followup-0|1> [image-preview-json]
+#                                - build the dry-run record without image bytes
+#   fmx_post_json <endpoint> <payload-file> [body-file] - POST JSON to the relay,
+#                                printing HTTP code and writing response body
+#   fmx_meta_get <meta> <key>  - read one key=value line from a task meta file
+#   fmx_meta_link_set <meta> <request_id> <epoch> [followups] [platform] [max]
+#                                - (re)write the X-request link, defaulting
+#                                followups to 0
+#   fmx_meta_followups_set <meta> <n> - rewrite just the follow-up counter
+#   fmx_meta_link_clear <meta> - remove the X-request link entirely
+# Callers must have FM_HOME set before calling fmx_load_config.
+
+_FM_X_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if ! command -v fm_backlog_atomic_transition >/dev/null 2>&1; then
+  # shellcheck source=bin/fm-tasks-axi-lib.sh
+  . "$_FM_X_LIB_DIR/fm-tasks-axi-lib.sh"
+  # shellcheck source=bin/fm-backlog-transition-lib.sh
+  . "$_FM_X_LIB_DIR/fm-backlog-transition-lib.sh"
+fi
+
+# Read the value of KEY from a .env-style file: last assignment wins; tolerates a
+# leading "export ", surrounding whitespace, and one layer of matching single or
+# double quotes. Prints nothing (and succeeds) when the file or key is absent, so
+# callers can treat empty output as "unset".
+fmx_env_get() {
+  local key=$1 file=$2 line val
+  [ -f "$file" ] || return 0
+  line=$(grep -E "^[[:space:]]*(export[[:space:]]+)?${key}=" "$file" 2>/dev/null | tail -n1) || return 0
+  [ -n "$line" ] || return 0
+  val=${line#*=}
+  val=${val#"${val%%[![:space:]]*}"}   # strip leading whitespace
+  val=${val%"${val##*[![:space:]]}"}   # strip trailing whitespace (incl. CR)
+  case "$val" in
+    \"*\") val=${val#\"}; val=${val%\"} ;;
+    \'*\') val=${val#\'}; val=${val%\'} ;;
+  esac
+  printf '%s' "$val"
+}
+
+fmx_poll_shim_content() {
+  local home=$1 root=$2
+  printf '%s\n' \
+    '#!/usr/bin/env bash' \
+    '# Auto-generated by fm-bootstrap.sh - X mode connector poll shim.' \
+    '# The watcher validates these bytes, then dispatches the trusted poll script.' \
+    "export FM_HOME=$(printf '%q' "$home")" \
+    "exec $(printf '%q' "$root/bin/fm-x-poll.sh")"
+}
+
+fmx_single_link_file_valid() {
+  local file=$1 expected_device=${2-} links device
+  [ -f "$file" ] && [ ! -L "$file" ] || return 1
+  if [ "$(uname)" = Darwin ]; then
+    links=$(stat -f %l "$file" 2>/dev/null) || return 1
+    device=$(stat -f %d "$file" 2>/dev/null) || return 1
+  else
+    links=$(stat -c %h "$file" 2>/dev/null) || return 1
+    device=$(stat -c %d "$file" 2>/dev/null) || return 1
+  fi
+  [ "$links" = 1 ] || return 1
+  [ -z "$expected_device" ] || [ "$device" = "$expected_device" ]
+}
+
+fmx_single_link_file_mode_valid() {
+  local file=$1 expected_mode=$2 expected_device=${3-} mode
+  fmx_single_link_file_valid "$file" "$expected_device" || return 1
+  if [ "$(uname)" = Darwin ]; then
+    mode=$(stat -f %Lp "$file" 2>/dev/null) || return 1
+  else
+    mode=$(stat -c %a "$file" 2>/dev/null) || return 1
+  fi
+  [ "$mode" = "$expected_mode" ]
+}
+
+fmx_private_artifact_dir_device() {
+  local dir=$1 mode device
+  [ -d "$dir" ] && [ ! -L "$dir" ] || return 1
+  if [ "$(uname)" = Darwin ]; then
+    mode=$(stat -f %Lp "$dir" 2>/dev/null) || return 1
+    device=$(stat -f %d "$dir" 2>/dev/null) || return 1
+  else
+    mode=$(stat -c %a "$dir" 2>/dev/null) || return 1
+    device=$(stat -c %d "$dir" 2>/dev/null) || return 1
+  fi
+  [ "$mode" = 700 ] || return 1
+  printf '%s\n' "$device"
+}
+
+fmx_private_artifact_dir_prepare() {
+  local dir=$1 parent
+  parent=${dir%/*}
+  if [ "$parent" != "$dir" ]; then
+    if [ -e "$parent" ] || [ -L "$parent" ]; then
+      [ -d "$parent" ] && [ ! -L "$parent" ] || return 1
+    else
+      (umask 077; mkdir -p "$parent" 2>/dev/null) || return 1
+      [ -d "$parent" ] && [ ! -L "$parent" ] || return 1
+    fi
+  fi
+  if [ -e "$dir" ] || [ -L "$dir" ]; then
+    [ -d "$dir" ] && [ ! -L "$dir" ] || return 1
+  else
+    (umask 077; mkdir -p "$dir" 2>/dev/null) || return 1
+  fi
+  fmx_private_artifact_dir_device "$dir"
+}
+
+fmx_private_artifact_publish_stdin() {
+  local dir=$1 base=$2 mode=$3 device tmp dest
+  case "$base" in
+    ''|.*|*/*) return 1 ;;
+  esac
+  case "$mode" in
+    600|700) ;;
+    *) return 1 ;;
+  esac
+  device=$(fmx_private_artifact_dir_prepare "$dir") || return 1
+  dest="$dir/$base"
+  tmp=$(umask 077; mktemp "$dir/.${base}.fm-x.XXXXXX" 2>/dev/null) || return 1
+  if ! cat > "$tmp" \
+    || ! chmod "$mode" "$tmp" 2>/dev/null \
+    || ! fmx_single_link_file_mode_valid "$tmp" "$mode" "$device"; then
+    rm -f -- "$tmp"
+    return 1
+  fi
+  if { [ -e "$dest" ] || [ -L "$dest" ]; } \
+    && ! fmx_single_link_file_mode_valid "$dest" "$mode" "$device"; then
+    rm -f -- "$tmp"
+    return 1
+  fi
+  if ! mv -f -- "$tmp" "$dest" 2>/dev/null; then
+    rm -f -- "$tmp"
+    return 1
+  fi
+  if ! fmx_single_link_file_mode_valid "$dest" "$mode" "$device"; then
+    rm -f -- "$dest"
+    return 1
+  fi
+}
+
+# Publish stdin as a new private artifact without replacing an existing path.
+# The hard-link claim is atomic within the prepared directory, so concurrent
+# callers cannot both create the destination. Returns 0 when this caller created
+# it, 1 when another valid private artifact already owns the path, and 2 on an
+# unsafe path or publication failure.
+fmx_private_artifact_publish_stdin_once() {
+  local dir=$1 base=$2 mode=$3 device tmp dest
+  case "$base" in
+    ''|.*|*/*) return 2 ;;
+  esac
+  case "$mode" in
+    600|700) ;;
+    *) return 2 ;;
+  esac
+  device=$(fmx_private_artifact_dir_prepare "$dir") || return 2
+  dest="$dir/$base"
+  tmp=$(umask 077; mktemp "$dir/.${base}.fm-x.XXXXXX" 2>/dev/null) || return 2
+  if ! cat > "$tmp" \
+    || ! chmod "$mode" "$tmp" 2>/dev/null \
+    || ! fmx_single_link_file_mode_valid "$tmp" "$mode" "$device"; then
+    rm -f -- "$tmp"
+    return 2
+  fi
+  if ln -- "$tmp" "$dest" 2>/dev/null; then
+    rm -f -- "$tmp"
+    if fmx_single_link_file_mode_valid "$dest" "$mode" "$device"; then
+      return 0
+    fi
+    rm -f -- "$dest"
+    return 2
+  fi
+  rm -f -- "$tmp"
+  if fmx_single_link_file_mode_valid "$dest" "$mode" "$device"; then
+    return 1
+  fi
+  return 2
+}
+
+fmx_private_artifact_file_valid() {
+  local dir=$1 base=$2 mode=$3 device
+  case "$base" in
+    ''|.*|*/*) return 1 ;;
+  esac
+  case "$mode" in
+    600|700) ;;
+    *) return 1 ;;
+  esac
+  device=$(fmx_private_artifact_dir_device "$dir") || return 1
+  fmx_single_link_file_mode_valid "$dir/$base" "$mode" "$device"
+}
+
+fmx_poll_shim_identity_valid() {
+  fmx_single_link_file_mode_valid "$1" "$2" "${3-}"
+}
+
+fmx_poll_shim_private_identity_valid() {
+  fmx_poll_shim_identity_valid "$1" 700
+}
+
+fmx_poll_shim_valid() {
+  local file=$1 home=$2 root=$3
+  fmx_poll_shim_private_identity_valid "$file" || return 1
+  cmp -s "$file" <(fmx_poll_shim_content "$home" "$root")
+}
+
+# Resolve the X-mode settings into FMX_TOKEN, FMX_RELAY, FMX_DRY, FMX_MAX,
+# FMX_DISCORD_MAX, and FMX_THREAD_MAX. An explicit environment variable always
+# wins over the .env file; the relay URL defaults to the production host so a
+# normal user configures only the token. FMX_RELAY has any trailing slash trimmed
+# so callers can append "/connector/..." cleanly.
+# FMX_DRY is set to "1" when FMX_DRY_RUN is a truthy value (anything other than
+# unset/empty/0/false/no/off), and "" otherwise: preview mode, where the client
+# composes a reply but records it instead of posting (see fm-x-reply.sh).
+fmx_load_config() {
+  local env_file="${FMX_ENV_FILE:-$FM_HOME/.env}" dry
+  if [ -n "${FMX_PAIRING_TOKEN+x}" ]; then
+    FMX_TOKEN=${FMX_PAIRING_TOKEN-}
+  else
+    FMX_TOKEN=$(fmx_env_get FMX_PAIRING_TOKEN "$env_file")
+  fi
+  if [ -n "${FMX_RELAY_URL+x}" ]; then
+    FMX_RELAY=${FMX_RELAY_URL-}
+  else
+    FMX_RELAY=$(fmx_env_get FMX_RELAY_URL "$env_file")
+  fi
+  [ -n "$FMX_RELAY" ] || FMX_RELAY="https://myfirstmate.io"
+  FMX_RELAY=${FMX_RELAY%/}
+  if [ -n "${FMX_DRY_RUN+x}" ]; then
+    dry=${FMX_DRY_RUN-}
+  else
+    dry=$(fmx_env_get FMX_DRY_RUN "$env_file")
+  fi
+  # shellcheck disable=SC2034 # FMX_DRY is read by callers (fm-x-reply.sh) after sourcing.
+  case "$(printf '%s' "$dry" | tr '[:upper:]' '[:lower:]')" in
+    ''|0|false|no|off) FMX_DRY="" ;;
+    *) FMX_DRY=1 ;;
+  esac
+
+  # Per-message character budgets for thread-splitting, and the maximum number
+  # of messages in one auto-split thread (anti-spam cap).
+  local maxraw discordraw threadraw
+  if [ -n "${FMX_X_REPLY_MAX_CHARS+x}" ]; then maxraw=${FMX_X_REPLY_MAX_CHARS-}; else maxraw=$(fmx_env_get FMX_X_REPLY_MAX_CHARS "$env_file"); fi
+  case "$maxraw" in ''|*[!0-9]*) maxraw=280 ;; esac
+  [ "$maxraw" -ge 50 ] 2>/dev/null || maxraw=50
+  # shellcheck disable=SC2034 # FMX_MAX is read by callers (fm-x-reply.sh) after sourcing.
+  FMX_MAX=$maxraw
+  if [ -n "${FMX_DISCORD_REPLY_MAX_CHARS+x}" ]; then discordraw=${FMX_DISCORD_REPLY_MAX_CHARS-}; else discordraw=$(fmx_env_get FMX_DISCORD_REPLY_MAX_CHARS "$env_file"); fi
+  case "$discordraw" in ''|*[!0-9]*) discordraw=1900 ;; esac
+  [ "$discordraw" -ge 50 ] 2>/dev/null || discordraw=50
+  [ "$discordraw" -le 2000 ] 2>/dev/null || discordraw=1900
+  # shellcheck disable=SC2034 # FMX_DISCORD_MAX is read by callers (fm-x-reply.sh) after sourcing.
+  FMX_DISCORD_MAX=$discordraw
+  if [ -n "${FMX_X_THREAD_MAX+x}" ]; then threadraw=${FMX_X_THREAD_MAX-}; else threadraw=$(fmx_env_get FMX_X_THREAD_MAX "$env_file"); fi
+  case "$threadraw" in ''|*[!0-9]*) threadraw=25 ;; esac
+  [ "$threadraw" -ge 1 ] 2>/dev/null || threadraw=25
+  # shellcheck disable=SC2034 # FMX_THREAD_MAX is read by callers (fm-x-reply.sh) after sourcing.
+  FMX_THREAD_MAX=$threadraw
+}
+
+# fmx_extract_reply_context <json-file>: the SINGLE owner of reply-context
+# extraction. Print {"platform":"...","reply_max_chars":"..."} inferred from a
+# mention/relay payload file. Explicit relay-provided platform/limit fields win;
+# absent those, the legacy tweet_id shape is used ("discord:<channel>:<message>"
+# means Discord, a numeric id means X). Empty fields mean unknown, and callers
+# must default safely. A missing file yields the empty shape. The inbox, relay,
+# and poll paths all feed their payload through this one function so platform
+# inference can never drift between them.
+fmx_extract_reply_context() {
+  local file=$1
+  if [ ! -f "$file" ]; then
+    printf '{"platform":"","reply_max_chars":""}\n'
+    return 0
+  fi
+  jq -c '
+    def norm_platform:
+      tostring | ascii_downcase
+      | if . == "discord" or . == "discordapp" then "discord"
+        elif . == "x" or . == "twitter" then "x"
+        else "" end;
+    def first_string($items):
+      [$items[] | select(type == "string" and length > 0)][0] // "";
+    def first_limit($items):
+      [$items[]
+        | select(type == "number" or type == "string")
+        | tostring
+        | select(test("^[0-9]+$"))][0] // "";
+    (first_string([.reply_platform, .platform, .target_platform, .source_platform, .provider]) | norm_platform) as $explicit_platform
+    | ((.tweet_id // "") | tostring) as $tweet_id
+    | {
+        platform: (if $explicit_platform != "" then $explicit_platform
+          elif ($tweet_id | startswith("discord:")) then "discord"
+          elif ($tweet_id | test("^[0-9]+$")) then "x"
+          else "" end),
+        reply_max_chars: first_limit([.reply_max_chars, .reply_max_characters, .message_max_chars, .message_limit, .max_chars])
+      }
+  ' "$file"
+}
+
+# fmx_request_inbox_context <state> <request_id>: reply context from a stashed
+# mention payload (state/x-inbox/<request_id>.json), or the empty shape when the
+# inbox file is absent. Thin wrapper over fmx_extract_reply_context.
+fmx_request_inbox_context() {
+  local state=$1 rid=$2
+  if ! fmx_private_artifact_file_valid "$state/x-inbox" "$rid.json" 600; then
+    printf '{"platform":"","reply_max_chars":""}\n'
+    return 0
+  fi
+  fmx_extract_reply_context "$state/x-inbox/$rid.json"
+}
+
+# fmx_request_relay_context <request_id>: resolve the reply platform/limit
+# AUTHORITATIVELY from the relay by request_id when local per-request registry or
+# inbox context is missing an axis. The request_id is the durable key the relay
+# still holds within the follow-up window, so live follow-ups can recover missing
+# context without using a local platform or budget default.
+#
+# POSTs {request_id} to $RELAY/connector/request-context and prints
+# {"platform":"...","reply_max_chars":"..."} in the SAME shape as
+# fmx_request_inbox_context, so callers feed both through the identical
+# normalization and fmx_reply_limit_for_platform path.
+#
+# Best-effort by design: it prints the empty-context shape and returns non-zero
+# when the query cannot run (no token, no curl/jq) or the relay does not resolve
+# it (non-2xx - e.g. an older relay without this endpoint, or a request already
+# swept past its window). Callers must treat that as "unknown" and warn loudly
+# rather than silently defaulting to the X budget. Requires fmx_load_config to
+# have populated FMX_TOKEN and FMX_RELAY first.
+fmx_request_relay_context() {
+  local rid=$1 payload_file body_file code rc ctx empty='{"platform":"","reply_max_chars":""}'
+  [ -n "${FMX_TOKEN:-}" ] || { printf '%s\n' "$empty"; return 1; }
+  command -v curl >/dev/null 2>&1 || { printf '%s\n' "$empty"; return 1; }
+  command -v jq >/dev/null 2>&1 || { printf '%s\n' "$empty"; return 1; }
+  payload_file=$(mktemp "${TMPDIR:-/tmp}/fm-x-reqctx.XXXXXX") || { printf '%s\n' "$empty"; return 1; }
+  body_file=$(mktemp "${TMPDIR:-/tmp}/fm-x-reqctx-body.XXXXXX") || { rm -f "$payload_file"; printf '%s\n' "$empty"; return 1; }
+  if ! jq -cn --arg rid "$rid" '{request_id:$rid}' > "$payload_file" 2>/dev/null; then
+    rm -f "$payload_file" "$body_file"; printf '%s\n' "$empty"; return 1
+  fi
+  code=$(fmx_post_json request-context "$payload_file" "$body_file"); rc=$?
+  rm -f "$payload_file"
+  if [ "$rc" != 0 ]; then rm -f "$body_file"; printf '%s\n' "$empty"; return 1; fi
+  case "$code" in
+    2[0-9][0-9]) ;;
+    *) rm -f "$body_file"; printf '%s\n' "$empty"; return 1 ;;
+  esac
+  # Same extraction as the inbox path, so a relay-resolved context and an
+  # inbox-resolved one normalize identically.
+  ctx=$(fmx_extract_reply_context "$body_file" 2>/dev/null) || ctx=
+  rm -f "$body_file"
+  [ -n "$ctx" ] || { printf '%s\n' "$empty"; return 1; }
+  # A 200 that resolved neither a platform nor a limit is treated as unresolved so
+  # the caller warns instead of recording a link with no split budget.
+  if [ "$(printf '%s' "$ctx" | jq -r '.platform // ""')" = "" ] \
+    && [ "$(printf '%s' "$ctx" | jq -r '.reply_max_chars // ""')" = "" ]; then
+    printf '%s\n' "$empty"; return 1
+  fi
+  printf '%s\n' "$ctx"
+}
+
+# --- durable per-request reply-context registry (state/x-context/<rid>.json) ---
+#
+# A single x_request per task collides across concurrent public requests routed
+# through one persistent secondmate: linking request B onto a task overwrites
+# request A's recorded platform/budget, so A's later follow-up loses its context.
+# And the inbox payload is drained right after the acknowledgement, so a delayed
+# request-id follow-up has no local platform source at all. This registry is the
+# durable fix: one small JSON per request_id, keyed independently of any task
+# link, written at poll time from the authoritative relay payload. It survives
+# inbox cleanup, process restart, and concurrent requests, so
+# fmx_resolve_reply_context can always recover the ORIGINAL platform/budget for a
+# request without depending on task-link state. Entries are volatile runtime
+# state under state/ and are pruned after the relay's 7-day follow-up window.
+
+fmx_context_registry_mtime() {
+  local file=$1 mtime
+  mtime=$(stat -f '%m' "$file" 2>/dev/null) || mtime=$(stat -c '%Y' "$file" 2>/dev/null) || return 1
+  case "$mtime" in
+    ''|*[!0-9]*) return 1 ;;
+  esac
+  printf '%s\n' "$mtime"
+}
+
+fmx_context_registry_recorded_at() {
+  local file=$1 now=${2:-} recorded_at
+  recorded_at=$(jq -r '
+    .recorded_at
+    | if type == "number" and floor == . and . >= 0 then tostring
+      elif type == "string" and test("^[0-9]+$") then .
+      else "" end
+  ' "$file" 2>/dev/null) || recorded_at=
+  case "$recorded_at" in
+    ''|*[!0-9]*) recorded_at= ;;
+  esac
+  [ "${#recorded_at}" -le 18 ] || recorded_at=
+  if [ -n "$recorded_at" ] && [ -n "$now" ] && [ "$recorded_at" -gt "$now" ]; then
+    recorded_at=
+  fi
+  if [ -z "$recorded_at" ]; then
+    recorded_at=$(fmx_context_registry_mtime "$file") || return 1
+    if [ -n "$now" ] && [ "$recorded_at" -gt "$now" ]; then
+      return 1
+    fi
+  fi
+  printf '%s\n' "$recorded_at"
+}
+
+fmx_context_registry_prune() {
+  local state=$1 dir now max_age file recorded_at age dir_device
+  dir="$state/x-context"
+  dir_device=$(fmx_private_artifact_dir_device "$dir" 2>/dev/null) || return 0
+  now=${FMX_NOW_OVERRIDE:-$(date +%s)}
+  case "$now" in
+    ''|*[!0-9]*) return 0 ;;
+  esac
+  [ "${#now}" -le 18 ] || return 0
+  max_age=${FMX_FOLLOWUP_MAX_AGE_SECS:-604800}
+  case "$max_age" in
+    ''|*[!0-9]*) max_age=604800 ;;
+  esac
+  [ "${#max_age}" -le 18 ] || max_age=604800
+  [ "$max_age" -le 604800 ] || max_age=604800
+  while IFS= read -r -d '' file; do
+    if ! fmx_single_link_file_mode_valid "$file" 600 "$dir_device"; then
+      rm -f -- "$file" 2>/dev/null || true
+      continue
+    fi
+    if ! recorded_at=$(fmx_context_registry_recorded_at "$file" "$now"); then
+      rm -f -- "$file" 2>/dev/null || true
+      continue
+    fi
+    age=$((10#$now - 10#$recorded_at))
+    if [ "$age" -gt "$max_age" ]; then
+      rm -f -- "$file" 2>/dev/null || true
+    fi
+  done < <(find "$dir" -type f -name '*.json' -print0 2>/dev/null)
+  return 0
+}
+
+# fmx_context_registry_set <state> <request_id> <platform> <reply-max> [refresh]:
+# persist the durable per-request reply context atomically. Normalizes platform
+# (twitter -> x, anything unrecognized -> empty) and requires a numeric budget.
+# A refresh value of 1 resets the retention timestamp; ordinary writes preserve
+# it. A no-op (success) when neither a platform nor a budget is known, so callers
+# never write an empty, useless record. Returns non-zero only on invalid input or
+# a write failure; callers treat the write as best-effort.
+fmx_context_registry_set() {
+  local state=$1 rid=$2 platform=${3:-} reply_max=${4:-} refresh=${5:-0} dir file dir_device now recorded_at
+  case "$rid" in
+    ''|.*|*[!A-Za-z0-9._-]*) return 1 ;;
+  esac
+  case "$platform" in
+    discord|x) ;;
+    twitter) platform=x ;;
+    *) platform= ;;
+  esac
+  case "$reply_max" in
+    ''|*[!0-9]*) reply_max= ;;
+  esac
+  case "$refresh" in
+    0|1) ;;
+    *) return 1 ;;
+  esac
+  if [ -z "$platform" ] && [ -z "$reply_max" ]; then
+    return 0
+  fi
+  dir="$state/x-context"
+  dir_device=$(fmx_private_artifact_dir_prepare "$dir") || return 1
+  file="$dir/$rid.json"
+  if { [ -e "$file" ] || [ -L "$file" ]; } \
+    && ! fmx_single_link_file_mode_valid "$file" 600 "$dir_device"; then
+    return 1
+  fi
+  fmx_context_registry_prune "$state"
+  now=${FMX_NOW_OVERRIDE:-$(date +%s)}
+  case "$now" in
+    ''|*[!0-9]*) return 1 ;;
+  esac
+  [ "${#now}" -le 18 ] || return 1
+  recorded_at=
+  if [ "$refresh" = 0 ] && [ -f "$file" ]; then
+    recorded_at=$(fmx_context_registry_recorded_at "$file" "$now") || recorded_at=
+  fi
+  if [ -z "$recorded_at" ]; then
+    recorded_at=$now
+  fi
+  (set -o pipefail; jq -cn --arg rid "$rid" --arg platform "$platform" --arg max "$reply_max" \
+    --argjson recorded_at "$recorded_at" \
+    '{request_id:$rid, platform:$platform, reply_max_chars:$max, recorded_at:$recorded_at}' \
+    | fmx_private_artifact_publish_stdin "$dir" "$rid.json" 600) || return 1
+}
+
+# fmx_offer_registry_claim <state> <request_id>: atomically claim the durable
+# one-wake marker at state/x-context/<request_id>.offered.json. The marker uses
+# the context registry's recorded_at retention contract, so its first claim
+# survives inbox cleanup and expires with the relay's bounded follow-up window.
+# Returns 0 only to the caller that created the marker, 1 when a valid marker
+# already exists, and 2 on invalid input or a publication failure.
+fmx_offer_registry_claim() {
+  local state=$1 rid=$2 dir now record rc
+  case "$rid" in
+    ''|.*|*[!A-Za-z0-9._-]*) return 2 ;;
+  esac
+  fmx_context_registry_prune "$state"
+  now=${FMX_NOW_OVERRIDE:-$(date +%s)}
+  case "$now" in
+    ''|*[!0-9]*) return 2 ;;
+  esac
+  [ "${#now}" -le 18 ] || return 2
+  record=$(jq -cn --arg rid "$rid" --argjson recorded_at "$now" \
+    '{request_id:$rid, recorded_at:$recorded_at}') || return 2
+  dir="$state/x-context"
+  printf '%s\n' "$record" \
+    | fmx_private_artifact_publish_stdin_once "$dir" "$rid.offered.json" 600
+  rc=$?
+  return "$rc"
+}
+
+# fmx_context_registry_get <state> <request_id>: print the durable per-request
+# reply context as {"platform":"...","reply_max_chars":"..."} (the same shape as
+# the inbox and relay extractors), or the empty shape when no record exists.
+fmx_context_registry_get() {
+  local state=$1 rid=$2 dir file
+  case "$rid" in
+    ''|.*|*[!A-Za-z0-9._-]*) printf '{"platform":"","reply_max_chars":""}\n'; return 0 ;;
+  esac
+  dir="$state/x-context"
+  file="$dir/$rid.json"
+  if ! fmx_private_artifact_file_valid "$dir" "$rid.json" 600; then
+    printf '{"platform":"","reply_max_chars":""}\n'
+    return 0
+  fi
+  fmx_context_registry_prune "$state"
+  jq -c '{platform:(.platform // ""), reply_max_chars:(.reply_max_chars // "")}' "$file" 2>/dev/null \
+    || printf '{"platform":"","reply_max_chars":""}\n'
+}
+
+# fmx_context_registry_clear <state> <request_id>: drop the durable record.
+# Idempotent and best-effort; a dismiss (no follow-up will ever come) uses it so
+# a skipped mention leaves no stray context behind.
+fmx_context_registry_clear() {
+  local state=$1 rid=$2 dir
+  case "$rid" in
+    ''|.*|*[!A-Za-z0-9._-]*) return 0 ;;
+  esac
+  dir="$state/x-context"
+  [ -d "$dir" ] && [ ! -L "$dir" ] || return 0
+  rm -f "$dir/$rid.json" 2>/dev/null || true
+  return 0
+}
+
+# fmx_resolve_reply_context <state> <request_id> <allow-relay>: resolve the reply
+# platform/budget for a request through the durable sources, in order:
+#   1. the per-request context registry (durable, survives inbox cleanup, restart,
+#      and concurrent requests - the primary source after this fix);
+#   2. the still-present inbox payload;
+#   3. when <allow-relay> is 1, an AUTHORITATIVE relay lookup by request_id.
+# Prints {"platform":"...","reply_max_chars":"..."}; each axis is filled from
+# the first source that provides it, continuing through later sources until both
+# are present or the sources are exhausted. <allow-relay>
+# must be 0 in dry-run / no-token / no-network contexts; the caller gates it
+# (typically: follow-up + live + token) so the answer path and dry-run stay
+# network-free. Requires fmx_load_config to have run when <allow-relay> is 1.
+fmx_resolve_reply_context() {
+  # Bash local accepts p= and m= as explicit empty assignment arguments.
+  # shellcheck disable=SC1007
+  local state=$1 rid=$2 allow_relay=${3:-0} src ctx source_p source_m p= m=
+  for src in registry inbox relay; do
+    case "$src" in
+      registry) ctx=$(fmx_context_registry_get "$state" "$rid" 2>/dev/null) || ctx= ;;
+      inbox)    ctx=$(fmx_request_inbox_context "$state" "$rid" 2>/dev/null) || ctx= ;;
+      relay)
+        [ "$allow_relay" = 1 ] || continue
+        ctx=$(fmx_request_relay_context "$rid" 2>/dev/null) || ctx=
+        ;;
+    esac
+    [ -n "$ctx" ] || continue
+    source_p=$(printf '%s' "$ctx" | jq -r '.platform // ""' 2>/dev/null) || source_p=
+    source_m=$(printf '%s' "$ctx" | jq -r '.reply_max_chars // ""' 2>/dev/null) || source_m=
+    case "$source_p" in discord|x) [ -n "$p" ] || p=$source_p ;; esac
+    case "$source_m" in ''|*[!0-9]*) ;; *) [ -n "$m" ] || m=$source_m ;; esac
+    [ -n "$p" ] && [ -n "$m" ] && break
+  done
+  jq -cn --arg platform "$p" --arg max "$m" \
+    '{platform:$platform, reply_max_chars:$max}'
+  return 0
+}
+
+# fmx_reply_limit_for_platform <platform> <explicit-limit>: choose the split
+# budget for one outbound message. X keeps the existing FMX_X_REPLY_MAX_CHARS
+# default of 280. Discord uses 1900 by default, below Discord's 2000-character
+# message limit so relay/client metadata or small counting differences have
+# headroom. A relay-provided explicit limit is honored when present.
+fmx_reply_limit_for_platform() {
+  local platform=${1:-} explicit=${2:-}
+  case "$explicit" in
+    ''|*[!0-9]*) ;;
+    *) [ "$explicit" -ge 50 ] 2>/dev/null && { printf '%s\n' "$explicit"; return 0; } ;;
+  esac
+  case "$platform" in
+    discord) printf '%s\n' "${FMX_DISCORD_MAX:-1900}" ;;
+    *) printf '%s\n' "${FMX_MAX:-280}" ;;
+  esac
+}
+
+# Split a reply into a numbered thread of <=<max>-codepoint chunks, packing first
+# on fenced-code, paragraph, and line boundaries, then on word boundaries, and
+# hard-splitting only a single over-long unit. A reply that already fits in one
+# message is returned as a single UNNUMBERED chunk; longer replies get " (k/n)"
+# suffixes. At most <cap> messages are produced; if the reply would need more,
+# the last kept message is marked with an ellipsis. Reads the reply text on stdin
+# and prints a compact JSON array of chunks. Length is codepoint-based (via jq);
+# the relay remains the final authority and trims.
+fmx_split_thread() {
+  jq -Rsc --argjson limit "$1" --argjson cap "$2" '
+    def trim: gsub("^[[:space:]]+|[[:space:]]+$"; "");
+    def fence_marker: test("^[[:space:]]*```");
+    def fence_count: ((split("```") | length) - 1);
+    def numbered($i; $n):
+      "(\($i + 1)/\($n))" as $mark
+      | if ((fence_count % 2) == 0) and (split("\n")[-1] | fence_marker)
+        then . + "\n" + $mark
+        else . + " " + $mark
+        end;
+    def hardsplit($b): . as $s | [range(0; ($s|length); $b) as $i | $s[$i:$i+$b]];
+    def wordsplit($b):
+      (gsub("[[:space:]]+"; " ") | trim) as $norm
+      | if ($norm | length) == 0 then []
+        else
+          [ $norm | split(" ")[] | if (length > $b) then hardsplit($b)[] else . end ] as $words
+          | (reduce $words[] as $w ({chunks: [], cur: ""};
+              (if .cur == "" then $w else .cur + " " + $w end) as $cand
+              | if ($cand | length) <= $b then .cur = $cand
+                else .chunks += (if .cur == "" then [] else [.cur] end) | .cur = $w end
+            )) as $st
+          | $st.chunks + (if $st.cur != "" then [$st.cur] else [] end)
+        end;
+    def split_units:
+      split("\n") as $lines
+      | (reduce $lines[] as $line ({units: [], cur: "", fence: false};
+          if .fence then
+            .cur = (if .cur == "" then $line else .cur + "\n" + $line end)
+            | if ($line | fence_marker) then .units += [.cur] | .cur = "" | .fence = false else . end
+          elif ($line | fence_marker) then
+            (if .cur != "" then .units += [.cur] | .cur = "" else . end)
+            | .cur = $line
+            | .fence = true
+          elif ($line | test("^[[:space:]]*$")) then
+            if .cur != "" then .units += [.cur] | .cur = "" else . end
+          else
+            ($line | trim) as $clean
+            | .cur = (if .cur == "" then $clean else .cur + " " + $clean end)
+          end
+        )) as $st
+      | ($st.units + (if $st.cur != "" then [$st.cur] else [] end))
+      | map(select((trim | length) > 0));
+    def pack_units($units; $b):
+      (reduce $units[] as $u ({chunks: [], cur: ""};
+        if ($u | length) > $b then
+          (if .cur != "" then .chunks += [.cur] | .cur = "" else . end)
+          | .chunks += ($u | wordsplit($b))
+        else
+          (if .cur == "" then $u else .cur + "\n\n" + $u end) as $cand
+          | if ($cand | length) <= $b then .cur = $cand
+            else .chunks += (if .cur == "" then [] else [.cur] end) | .cur = $u end
+        end
+      )) as $st
+      | $st.chunks + (if $st.cur != "" then [$st.cur] else [] end);
+    def split_thread($limit; $cap):
+      trim as $norm
+      | if ($norm | length) == 0 then []
+        elif ($norm | length) <= $limit then [$norm]
+        else
+          ($cap | tostring | length) as $digits
+          | (4 + 2 * $digits) as $suffixw
+          | (if ($limit - $suffixw - 1) < 1 then 1 else ($limit - $suffixw - 1) end) as $budget
+          | ($norm | split_units) as $units
+          | pack_units($units; $budget) as $raw
+          | (if ($raw | length) > $cap
+              then ($raw[0:$cap] | (.[($cap - 1)] += "…"))
+              else $raw end) as $kept
+          | ($kept | length) as $n
+          | [ range(0; $n) as $i | $kept[$i] | numbered($i; $n) ]
+        end;
+    split_thread($limit; $cap)
+  '
+}
+
+fmx_auth_header_file() {
+  local file
+  case "$FMX_TOKEN" in
+    *$'\n'*|*$'\r'*) return 1 ;;
+  esac
+  file=$(umask 077; mktemp "${TMPDIR:-/tmp}/fm-x-auth.XXXXXX") || return 1
+  chmod 600 "$file" 2>/dev/null || { rm -f "$file"; return 1; }
+  printf 'Authorization: Bearer %s\n' "$FMX_TOKEN" > "$file" || { rm -f "$file"; return 1; }
+  printf '%s\n' "$file"
+}
+
+fmx_image_media_type_from_path() {
+  local path=$1 lower detected
+  lower=$(printf '%s' "$path" | tr '[:upper:]' '[:lower:]')
+  case "$lower" in
+    *.png) printf 'image/png\n' ;;
+    *.jpg|*.jpeg) printf 'image/jpeg\n' ;;
+    *.gif) printf 'image/gif\n' ;;
+    *.webp) printf 'image/webp\n' ;;
+    *.bmp) printf 'image/bmp\n' ;;
+    *.tif|*.tiff) printf 'image/tiff\n' ;;
+    *)
+      if command -v file >/dev/null 2>&1; then
+        detected=$(file --mime-type -b -- "$path" 2>/dev/null | tr '[:upper:]' '[:lower:]')
+        case "$detected" in
+          image/png|image/jpeg|image/pjpeg|image/gif|image/webp|image/bmp|image/tiff) printf '%s\n' "$detected" ;;
+          *) return 1 ;;
+        esac
+      else
+        return 1
+      fi
+      ;;
+  esac
+}
+
+# fmx_image_payload_file <path> <client-name> <payload-file>: validate and encode
+# a local outbound image. The relay payload object is written to <payload-file>.
+# The compact preview object is printed for FMX_DRY_RUN outbox records.
+fmx_image_payload_file() {
+  local path=$1 client=${2:-fm-x-reply} payload_file=${3:-} media_type bytes
+  if [ -z "$payload_file" ]; then
+    echo "$client: missing image payload destination" >&2
+    return 1
+  fi
+  if [ ! -e "$path" ]; then
+    echo "$client: image file does not exist: $path" >&2
+    return 1
+  fi
+  if [ ! -f "$path" ]; then
+    echo "$client: image path is not a regular file: $path" >&2
+    return 1
+  fi
+  if [ ! -r "$path" ]; then
+    echo "$client: image file is not readable: $path" >&2
+    return 1
+  fi
+  media_type=$(fmx_image_media_type_from_path "$path") || {
+    echo "$client: unsupported image media type for: $path" >&2
+    return 1
+  }
+  command -v base64 >/dev/null 2>&1 || {
+    echo "$client: base64 not found" >&2
+    return 1
+  }
+  bytes=$(wc -c < "$path" | tr -d '[:space:]') || {
+    echo "$client: cannot stat image file: $path" >&2
+    return 1
+  }
+  if [ "$bytes" = 0 ]; then
+    echo "$client: image file is empty: $path" >&2
+    return 1
+  fi
+  if ! (set -o pipefail; base64 < "$path" | tr -d '\n\r' \
+    | jq -Rsc --arg media_type "$media_type" \
+      '{media_type:$media_type,data_base64:.}' > "$payload_file"); then
+    rm -f "$payload_file"
+    echo "$client: cannot read image file: $path" >&2
+    return 1
+  fi
+  jq -cn \
+    --arg media_type "$media_type" \
+    --arg source_path "$path" \
+    --argjson bytes "$bytes" \
+    '{media_type:$media_type,bytes:$bytes,source_path:$source_path}'
+}
+
+fmx_reply_payload_json() {
+  local rid=$1 chunks=$2 n=$3 image_json_file=${4:-}
+  if [ -n "$image_json_file" ]; then
+    if [ "$n" -le 1 ]; then
+      printf '%s' "$chunks" | jq -c --arg rid "$rid" --slurpfile image "$image_json_file" \
+        '{request_id:$rid, text:(.[0] // ""), image:$image[0]}'
+    else
+      printf '%s' "$chunks" | jq -c --arg rid "$rid" --slurpfile image "$image_json_file" \
+        '{request_id:$rid, text:.[0], texts:., image:$image[0]}'
+    fi
+  else
+    if [ "$n" -le 1 ]; then
+      printf '%s' "$chunks" | jq -c --arg rid "$rid" '{request_id:$rid, text:(.[0] // "")}'
+    else
+      printf '%s' "$chunks" | jq -c --arg rid "$rid" '{request_id:$rid, text:.[0], texts:.}'
+    fi
+  fi
+}
+
+fmx_reply_outbox_json() {
+  local rid=$1 chunks=$2 n=$3 followup=$4 image_preview_json=${5:-}
+  if [ -n "$image_preview_json" ]; then
+    if [ "$followup" = 1 ]; then
+      if [ "$n" -le 1 ]; then
+        printf '%s' "$chunks" | jq -c --arg rid "$rid" --argjson image "$image_preview_json" \
+          '{request_id:$rid, text:(.[0] // ""), image:$image, endpoint:"followup"}'
+      else
+        printf '%s' "$chunks" | jq -c --arg rid "$rid" --argjson image "$image_preview_json" \
+          '{request_id:$rid, text:.[0], texts:., image:$image, endpoint:"followup"}'
+      fi
+    else
+      if [ "$n" -le 1 ]; then
+        printf '%s' "$chunks" | jq -c --arg rid "$rid" --argjson image "$image_preview_json" \
+          '{request_id:$rid, text:(.[0] // ""), image:$image}'
+      else
+        printf '%s' "$chunks" | jq -c --arg rid "$rid" --argjson image "$image_preview_json" \
+          '{request_id:$rid, text:.[0], texts:., image:$image}'
+      fi
+    fi
+  else
+    if [ "$followup" = 1 ]; then
+      if [ "$n" -le 1 ]; then
+        printf '%s' "$chunks" | jq -c --arg rid "$rid" \
+          '{request_id:$rid, text:(.[0] // ""), endpoint:"followup"}'
+      else
+        printf '%s' "$chunks" | jq -c --arg rid "$rid" \
+          '{request_id:$rid, text:.[0], texts:., endpoint:"followup"}'
+      fi
+    else
+      if [ "$n" -le 1 ]; then
+        printf '%s' "$chunks" | jq -c --arg rid "$rid" '{request_id:$rid, text:(.[0] // "")}'
+      else
+        printf '%s' "$chunks" | jq -c --arg rid "$rid" '{request_id:$rid, text:.[0], texts:.}'
+      fi
+    fi
+  fi
+}
+
+fmx_post_json() (
+  local endpoint=$1 payload_file=$2 body_file=${3:-/dev/null} auth_header_file code rc
+  command -v curl >/dev/null 2>&1 || return 127
+  [ -r "$payload_file" ] || return 2
+  auth_header_file=$(fmx_auth_header_file) || return 3
+  trap 'rm -f "$auth_header_file"' EXIT
+  trap 'rm -f "$auth_header_file"; exit 143' HUP INT TERM
+  code=$(curl -m 10 -s -o "$body_file" -w '%{http_code}' \
+    -X POST \
+    -H "@$auth_header_file" \
+    -H 'Content-Type: application/json' \
+    --data-binary "@$payload_file" \
+    "$FMX_RELAY/connector/$endpoint" 2>/dev/null)
+  rc=$?
+  rm -f "$auth_header_file"
+  trap - EXIT HUP INT TERM
+  [ "$rc" = 0 ] || return 4
+  printf '%s\n' "$code"
+)
+
+# --- task <-> X-request link (state/<id>.meta backed) -----------------------
+#
+# When an X/Discord mention spawns real work, the task is linked to its
+# originating mention by state/<id>.meta lines:
+#   x_request=<request_id>     the relay-issued id the follow-up posts against
+#   x_request_ts=<epoch>       when the link was made, for the 7-day follow-up window
+#   x_followups=<n>            follow-ups already posted against this binding (0..3)
+#   x_platform=<platform>      optional reply platform for follow-up split budget
+#   x_reply_max_chars=<n>      optional recorded per-message split budget
+# fm-x-followup.sh posts against that link (within the window, up to the cap),
+# then either records the incremented count or clears the link. These helpers
+# own the read/write/clear so fm-x-link.sh and fm-x-followup.sh never hand-edit
+# meta and the rewrite stays atomic and preserves every other meta line.
+
+# fmx_meta_get <meta> <key>: print the value of the last "key=value" line in
+# <meta>, or nothing (and succeed) when the file or key is absent. Callers treat
+# empty output as "unset".
+fmx_meta_get() {
+  local meta=$1 key=$2 line
+  [ -f "$meta" ] || return 0
+  line=$(grep -E "^${key}=" "$meta" 2>/dev/null | tail -n1) || return 0
+  [ -n "$line" ] || return 0
+  printf '%s' "${line#*=}"
+}
+
+fmx_meta_tmp() {
+  local meta=$1 dir base
+  dir=${meta%/*}
+  base=${meta##*/}
+  [ "$dir" != "$meta" ] || dir=.
+  [ -d "$dir" ] || return 1
+  mktemp "$dir/.${base}.fm-x.XXXXXX"
+}
+
+# fmx_meta_link_set <meta> <request_id> <epoch> [followups] [platform] [max]:
+# atomically (re)write the x_request/x_request_ts/x_followups lines plus optional
+# reply-platform context, dropping any prior link and preserving every other meta
+# line. <followups> defaults to 0 (a fresh link); pass the prior task's count to
+# carry it forward onto a successor task instead of granting a fresh follow-up
+# budget against a binding the relay already knows about. Returns non-zero if
+# <meta> is missing or the rewrite fails.
+fmx_meta_link_set() {
+  local meta=$1 rid=$2 ts=$3 followups=${4:-0} platform=${5:-} reply_max=${6:-} tmp lock
+  [ -f "$meta" ] || return 1
+  lock=$(fm_meta_lock_path "$meta") || return 1
+  fm_lock_acquire_wait "$lock"
+  [ -f "$meta" ] || { fm_lock_release "$lock"; return 1; }
+  tmp=$(fmx_meta_tmp "$meta") || { fm_lock_release "$lock"; return 1; }
+  if ! { grep -vE '^x_request=|^x_request_ts=|^x_followups=|^x_platform=|^x_reply_max_chars=' "$meta" || true; } > "$tmp"; then
+    rm -f "$tmp"; fm_lock_release "$lock"; return 1
+  fi
+  printf 'x_request=%s\n' "$rid" >> "$tmp" || { rm -f "$tmp"; fm_lock_release "$lock"; return 1; }
+  printf 'x_request_ts=%s\n' "$ts" >> "$tmp" || { rm -f "$tmp"; fm_lock_release "$lock"; return 1; }
+  printf 'x_followups=%s\n' "$followups" >> "$tmp" || { rm -f "$tmp"; fm_lock_release "$lock"; return 1; }
+  if [ -n "$platform" ]; then
+    printf 'x_platform=%s\n' "$platform" >> "$tmp" || { rm -f "$tmp"; fm_lock_release "$lock"; return 1; }
+  fi
+  case "$reply_max" in
+    ''|*[!0-9]*) ;;
+    *) printf 'x_reply_max_chars=%s\n' "$reply_max" >> "$tmp" || { rm -f "$tmp"; fm_lock_release "$lock"; return 1; } ;;
+  esac
+  # STATE is the caller's authorized state directory, never dirname of $meta.
+  # shellcheck disable=SC2153
+  if ! fm_backlog_atomic_transition publish "$tmp" "$meta" "task record" "$STATE"; then
+    rm -f "$tmp"; fm_lock_release "$lock"; return 1
+  fi
+  fm_lock_release "$lock"
+}
+
+# fmx_meta_followups_set <meta> <n>: atomically rewrite just the x_followups
+# line, preserving every other meta line including link and reply context.
+# Returns non-zero if <meta> is missing or the rewrite fails.
+fmx_meta_followups_set() {
+  local meta=$1 n=$2 tmp lock
+  [ -f "$meta" ] || return 1
+  lock=$(fm_meta_lock_path "$meta") || return 1
+  fm_lock_acquire_wait "$lock"
+  [ -f "$meta" ] || { fm_lock_release "$lock"; return 1; }
+  tmp=$(fmx_meta_tmp "$meta") || { fm_lock_release "$lock"; return 1; }
+  if ! { grep -vE '^x_followups=' "$meta" || true; } > "$tmp"; then
+    rm -f "$tmp"; fm_lock_release "$lock"; return 1
+  fi
+  printf 'x_followups=%s\n' "$n" >> "$tmp" || { rm -f "$tmp"; fm_lock_release "$lock"; return 1; }
+  # shellcheck disable=SC2153
+  if ! fm_backlog_atomic_transition publish "$tmp" "$meta" "task record" "$STATE"; then
+    rm -f "$tmp"; fm_lock_release "$lock"; return 1
+  fi
+  fm_lock_release "$lock"
+}
+
+# fmx_meta_link_clear <meta>: atomically remove the x_request/x_request_ts/
+# x_followups and reply-platform lines while preserving every other meta line. Idempotent:
+# succeeds whether or not a link is present, and is a no-op when <meta> is
+# missing.
+fmx_meta_link_clear() {
+  local meta=$1 tmp lock
+  [ ! -L "$meta" ] || return 1
+  [ -f "$meta" ] || return 0
+  lock=$(fm_meta_lock_path "$meta") || return 1
+  fm_lock_acquire_wait "$lock"
+  [ ! -L "$meta" ] || { fm_lock_release "$lock"; return 1; }
+  [ -f "$meta" ] || { fm_lock_release "$lock"; return 0; }
+  tmp=$(fmx_meta_tmp "$meta") || { fm_lock_release "$lock"; return 1; }
+  if ! { grep -vE '^x_request=|^x_request_ts=|^x_followups=|^x_platform=|^x_reply_max_chars=' "$meta" || true; } > "$tmp"; then
+    rm -f "$tmp"; fm_lock_release "$lock"; return 1
+  fi
+  # shellcheck disable=SC2153
+  if ! fm_backlog_atomic_transition publish "$tmp" "$meta" "task record" "$STATE"; then
+    rm -f "$tmp"; fm_lock_release "$lock"; return 1
+  fi
+  fm_lock_release "$lock"
+}