@zerwiz/ymir 0.1.4 → 0.1.5

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

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# fm-timeout-lib.sh - the single owner of bounded command execution.
+#
+# Sourced, never executed. Provides one hard-bound runner so no caller has to
+# re-derive the coreutils/BSD/perl selection, and so every bounded call in this
+# repo agrees on what "the bound was hit" means.
+#
+#   fm_timeout_mechanism
+#       Prints the mechanism fm_run_timed will use on this host: "timeout",
+#       "gtimeout", "perl", or "bash". Set FM_TIMEOUT_MECHANISM_OVERRIDE=bash
+#       to force the dependency-free fallback.
+#
+#   fm_run_timed <seconds> <command> [args...]
+#       Runs the command with a hard bound. Exit status is the command's own,
+#       except 124, which means the bound was hit (GNU timeout's convention,
+#       reproduced by the perl and bash fallbacks).
+#
+# A non-positive bound is not a bound: `timeout 0` and the perl fallback's
+# `alarm 0` both disable the deadline, so callers must reject 0 before calling.
+#
+# All four mechanisms terminate the whole process GROUP, not just the direct
+# child, so a hung grandchild (a vendor CLI spawned by a wrapper script, a git
+# fetch spawned by a sweep) cannot outlive the bound. GNU/BSD `timeout` does
+# this by default because it does not run the command in the foreground process
+# group; the perl fallback does it explicitly with setpgrp plus a negative pid,
+# and the bash fallback uses monitor mode to give the bounded child its own
+# process group before signaling its negative pid.
+set -u
+
+fm_timeout_mechanism() {
+  if [ "${FM_TIMEOUT_MECHANISM_OVERRIDE:-}" = bash ]; then
+    printf 'bash\n'
+  elif command -v timeout >/dev/null 2>&1; then
+    printf 'timeout\n'
+  elif command -v gtimeout >/dev/null 2>&1; then
+    printf 'gtimeout\n'
+  elif command -v perl >/dev/null 2>&1; then
+    printf 'perl\n'
+  else
+    printf 'bash\n'
+  fi
+}
+
+fm_run_bash_timeout() {
+  local seconds=$1 command_status deadline_status child_pid watchdog_pid command_rc recorded_rc monitor_was_on=0
+  shift
+  command_status=$(mktemp "${TMPDIR:-/tmp}/fm-bash-timeout-command.XXXXXX" 2>/dev/null) || return 124
+  deadline_status="${command_status}.deadline"
+  case $- in *m*) monitor_was_on=1 ;; esac
+  set -m
+  (
+    set +m
+    "$@"
+    command_rc=$?
+    printf '%s\n' "$command_rc" > "$command_status"
+    exit "$command_rc"
+  ) &
+  child_pid=$!
+  (
+    set +m
+    sleep "$seconds"
+    printf 'expired\n' > "$deadline_status"
+    kill -TERM -- "-$child_pid" 2>/dev/null || true
+    sleep 0.2
+    kill -KILL -- "-$child_pid" 2>/dev/null || true
+    exit 124
+  ) &
+  watchdog_pid=$!
+  [ "$monitor_was_on" -eq 1 ] || set +m
+
+  if wait "$child_pid" 2>/dev/null; then
+    command_rc=0
+  else
+    command_rc=$?
+  fi
+  if [ -s "$deadline_status" ]; then
+    wait "$watchdog_pid" 2>/dev/null || true
+    command_rc=124
+  else
+    kill -TERM -- "-$watchdog_pid" 2>/dev/null || kill "$watchdog_pid" 2>/dev/null || true
+    wait "$watchdog_pid" 2>/dev/null || true
+    recorded_rc=$(cat "$command_status" 2>/dev/null || true)
+    case "$recorded_rc" in ''|*[!0-9]*) ;; *) command_rc=$recorded_rc ;; esac
+  fi
+  rm -f "$command_status" "$deadline_status" 2>/dev/null || true
+  return "$command_rc"
+}
+
+fm_run_external_timeout() {
+  local runner=$1 seconds=$2 status_file runner_pid runner_rc command_rc
+  shift 2
+  status_file=$(mktemp "${TMPDIR:-/tmp}/fm-timeout-status.XXXXXX" 2>/dev/null) || return 124
+  # Run timeout asynchronously so its pid - also the process-group id created
+  # by GNU/BSD timeout without --foreground - remains available for cleanup.
+  # A shell wrapper can exit promptly on TERM while one of its descendants
+  # ignores TERM; timeout then considers the command finished and does not send
+  # its configured KILL. Explicitly reap that leftover group on a real timeout.
+  # shellcheck disable=SC2016  # Expansion is deliberately deferred to the child shell.
+  "$runner" -k 1 "$seconds" bash -c '
+    status_file=$1
+    shift
+    "$@"
+    command_rc=$?
+    printf "%s\n" "$command_rc" > "$status_file"
+    exit "$command_rc"
+  ' _ "$status_file" "$@" &
+  runner_pid=$!
+  if wait "$runner_pid"; then
+    runner_rc=0
+  else
+    runner_rc=$?
+  fi
+  command_rc=$(cat "$status_file" 2>/dev/null || true)
+  rm -f "$status_file" 2>/dev/null || true
+  case "$command_rc" in
+    ''|*[!0-9]*) ;;
+    *) [ "$command_rc" -le 255 ] && return "$command_rc" ;;
+  esac
+  case "$runner_rc" in
+    124|137)
+      kill -KILL -- "-$runner_pid" 2>/dev/null || true
+      return 124
+      ;;
+    *) return "$runner_rc" ;;
+  esac
+}
+
+fm_run_timed() {  # <seconds> <command...>
+  local seconds=$1
+  shift
+  case "$(fm_timeout_mechanism)" in
+    timeout) fm_run_external_timeout timeout "$seconds" "$@" ;;
+    gtimeout) fm_run_external_timeout gtimeout "$seconds" "$@" ;;
+    perl)
+      perl -e 'my $t = shift; my $pid = fork; die "fork failed" unless defined $pid; if (!$pid) { setpgrp(0, 0); exec @ARGV } local $SIG{ALRM} = sub { kill "TERM", -$pid; select undef, undef, undef, 0.2; kill "KILL", -$pid; exit 124 }; alarm $t; waitpid $pid, 0; exit($? >> 8)' \
+        "$seconds" "$@"
+      ;;
+    bash) fm_run_bash_timeout "$seconds" "$@" ;;
+    *) return 124 ;;
+  esac
+}

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

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+# fm-timing-lib.sh - the single owner of the deferred network stage's elapsed-time
+# instrumentation.
+#
+# Sourced, never executed.
+#
+# WHY THIS EXISTS. The deferred stage (bin/fm-startup-network.sh) publishes one
+# aggregate started/finished pair, so a run that took a minute could not be
+# attributed to a phase, a host, or a clone without re-running it by hand under
+# manual tracing. These helpers record per-step elapsed times as the run happens,
+# so the next slow run is answerable from the durable record alone.
+#
+# OFF BY DEFAULT, AND INERT. Every helper is a no-op unless FM_TIMING_LOG names a
+# file. Nothing here talks to the network, waits, locks, or changes control flow:
+# a failed append is discarded rather than propagated, because losing a diagnostic
+# line must never change what a sweep does or how it exits.
+#
+# ENVIRONMENT, both exported by the stage that owns a run:
+#   FM_TIMING_LOG       append-only record file. Unset or empty disables recording.
+#                       Exported across process boundaries on purpose: the phases
+#                       being measured run in bin/fm-bootstrap.sh and
+#                       bin/fm-fleet-sync.sh, which are children of the stage.
+#   FM_TIMING_EPOCH_MS  the run's start instant, so every record carries an offset
+#                       from ONE origin even though the records are written by
+#                       several processes. Defaults to the first recording
+#                       process's own start, which keeps a hand-run child readable.
+#
+# RECORD FORMAT, one tab-separated line per measured step:
+#   v1 <TAB> scope <TAB> name <TAB> start-offset-ms <TAB> elapsed-ms <TAB> detail
+# Appends are single short lines opened O_APPEND, so concurrent writers interleave
+# whole lines rather than corrupting each other.
+#
+# NO SECRETS, BY CONSTRUCTION. `detail` names an identity - a secondmate id, a
+# host, a clone directory name - and identities never contain whitespace, while
+# the things that must never reach this file (a command line, an environment
+# dump, a captured error) always do. So a detail carrying ANY whitespace is not a
+# truncated identity, it is free text that arrived from somewhere it should not
+# have, and it is dropped entirely rather than cleaned up: cleaning would leave
+# the token in `KEY=secret` behind, because a credential is made of exactly the
+# characters an identity is made of. What remains is then narrowed to
+# [A-Za-z0-9._@:/+-] and truncated, which is what stops a detail from forging
+# extra tab-separated records. Enforcing this here rather than at each call site
+# is what makes "this file cannot carry a credential or an argv" checkable in one
+# place.
+set -u
+
+FM_TIMING_DETAIL_MAX=${FM_TIMING_DETAIL_MAX:-80}
+
+fm_timing_enabled() {
+  [ -n "${FM_TIMING_LOG:-}" ]
+}
+
+# Milliseconds since the epoch. EPOCHREALTIME is a bash builtin (no fork) whose
+# decimal separator follows the locale, so both forms are accepted. A shell
+# without it - macOS's system bash 3.2, which `env bash` still resolves to on a
+# host with no newer bash on PATH - degrades to whole-second granularity rather
+# than losing the timing entirely. That is a coarser answer to "which host was
+# slow", not a missing one, because the steps being measured are seconds-scale.
+fm_timing_now_ms() {
+  local raw sec frac
+  raw=${EPOCHREALTIME:-}
+  case "$raw" in
+    *[0-9][.,][0-9]*)
+      sec=${raw%%[.,]*}
+      frac=${raw#*[.,]}
+      frac="${frac}000"
+      frac=${frac:0:3}
+      case "$sec$frac" in
+        ''|*[!0-9]*) ;;
+        *) printf '%s\n' "$(( sec * 1000 + 10#$frac ))"; return 0 ;;
+      esac
+      ;;
+  esac
+  sec=$(date +%s 2>/dev/null || printf '0')
+  case "$sec" in ''|*[!0-9]*) sec=0 ;; esac
+  printf '%s\n' "$(( sec * 1000 ))"
+}
+
+# Ensure FM_TIMING_EPOCH_MS holds the origin every offset is measured from.
+# Callers that own a run export it up front; a process that starts recording
+# without one adopts its own first measurement so its records stay internally
+# consistent instead of being silently dropped.
+#
+# This SETS the variable rather than printing it, because the caller must read it
+# as "$FM_TIMING_EPOCH_MS" and not through a command substitution: a substitution
+# runs in a subshell, so the lazily chosen origin would be discarded and every
+# record would recompute it, flattening every start offset to zero.
+fm_timing_epoch_ensure() {
+  case "${FM_TIMING_EPOCH_MS:-}" in
+    ''|*[!0-9]*)
+      FM_TIMING_EPOCH_MS=$(fm_timing_now_ms)
+      export FM_TIMING_EPOCH_MS
+      ;;
+  esac
+}
+
+# Start a run: point recording at <file> and stamp the shared origin. The file is
+# created empty so a run that dies before its first record still publishes an
+# empty-but-present artifact rather than looking like it was never instrumented.
+fm_timing_start() {  # <file>
+  local file=$1
+  [ -n "$file" ] || return 0
+  : > "$file" 2>/dev/null || return 0
+  FM_TIMING_LOG=$file
+  FM_TIMING_EPOCH_MS=$(fm_timing_now_ms)
+  export FM_TIMING_LOG FM_TIMING_EPOCH_MS
+}
+
+fm_timing_sanitize() {  # <text>
+  local text=${1:-}
+  case "$text" in
+    *[[:space:]]*) printf '%s\n' 'unrecordable'; return 0 ;;
+  esac
+  text=${text//[!A-Za-z0-9._@:\/+-]/_}
+  printf '%s\n' "${text:0:$FM_TIMING_DETAIL_MAX}"
+}
+
+# Record one measured step. Never fails the caller: a missing log, an unwritable
+# path, or a malformed start stamp all resolve to "no record", never an error.
+fm_timing_record() {  # <scope> <name> <start-ms> [detail]
+  local scope=$1 name=$2 start=$3 detail=${4:-} now offset elapsed
+  fm_timing_enabled || return 0
+  case "$start" in ''|*[!0-9]*) return 0 ;; esac
+  now=$(fm_timing_now_ms)
+  fm_timing_epoch_ensure
+  offset=$(( start - FM_TIMING_EPOCH_MS ))
+  [ "$offset" -ge 0 ] || offset=0
+  elapsed=$(( now - start ))
+  [ "$elapsed" -ge 0 ] || elapsed=0
+  printf 'v1\t%s\t%s\t%s\t%s\t%s\n' \
+    "$(fm_timing_sanitize "$scope")" "$(fm_timing_sanitize "$name")" \
+    "$offset" "$elapsed" "$(fm_timing_sanitize "$detail")" \
+    >> "$FM_TIMING_LOG" 2>/dev/null || true
+  return 0
+}
+
+# Render a recorded run for a human. Prints nothing at all when the file is
+# missing or holds no record, so an uninstrumented or empty run adds no output.
+fm_timing_render() {  # <file>
+  local file=$1
+  [ -n "$file" ] && [ -s "$file" ] || return 0
+  awk -F'\t' '
+    $1 != "v1" || NF < 5 { next }
+    {
+      records++
+      scope[records] = $2; name[records] = $3
+      offset[records] = $4 + 0; elapsed[records] = $5 + 0
+      detail[records] = $6
+    }
+    END {
+      if (records == 0) exit 0
+      print "TIMINGS - where the deferred network checks spent their time (ms):"
+      for (i = 1; i <= records; i++) {
+        label = name[i]
+        if (detail[i] != "") label = label " " detail[i]
+        printf "  %-11s %-42s start=+%-7d elapsed=%d\n", scope[i], label, offset[i], elapsed[i]
+      }
+      for (i = 1; i <= records; i++) {
+        for (j = i + 1; j <= records; j++) {
+          if (elapsed[j] > elapsed[i]) {
+            t = scope[i]; scope[i] = scope[j]; scope[j] = t
+            t = name[i]; name[i] = name[j]; name[j] = t
+            t = offset[i]; offset[i] = offset[j]; offset[j] = t
+            t = elapsed[i]; elapsed[i] = elapsed[j]; elapsed[j] = t
+            t = detail[i]; detail[i] = detail[j]; detail[j] = t
+          }
+        }
+      }
+      top = records < 3 ? records : 3
+      line = ""
+      for (i = 1; i <= top; i++) {
+        label = name[i]
+        if (detail[i] != "") label = label " " detail[i]
+        line = line (line == "" ? "" : ", ") scope[i] " " label " " elapsed[i] "ms"
+      }
+      print "  slowest: " line
+    }
+  ' "$file" 2>/dev/null || true
+}

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

@@ -0,0 +1,291 @@
+#!/usr/bin/env bash
+# fm-tmux-lib.sh — shared tmux pane primitives for firstmate.
+#
+# ONE tmux source for delivery-busy detection, composer capture primitives,
+# and verified submit.
+# Both the away-mode daemon and bin/fm-send.sh reach these primitives through
+# backend dispatch, while bin/fm-composer-lib.sh owns the shared verdict.
+#
+# Composer shapes and verdicts are owned by bin/fm-composer-lib.sh.
+# This file owns only tmux's styled capture, cursor and Pi identity primitives,
+# delivery busy read, and submit conversions that consume the shared verdict.
+# Styled captures remain internal; fm-peek and every human-facing capture stay
+# plain.
+#
+# OpenCode's busy-queued Enter conversion accepts only structurally proven
+# pending text after retries, while the separate turn-started conversion accepts
+# an unknown post-Enter composer only after this submit observed an idle baseline
+# become busy.
+# The queued-Enter policy itself lives in fm_composer_queued_enter_verdict
+# (bin/fm-composer-lib.sh); this file supplies tmux's pane-busy primitive.
+#
+# FM_COMPOSER_IDLE_RE is interpreted by the shared classifier with its structural
+# and styling safety gates.
+# FM_BUSY_REGEX overrides the rendered delivery-busy matching used here.
+#
+# NOT a task-state source: task busy state is owned by bin/fm-busy-lib.sh's
+# semantic contract. The matching below serves only delivery guards: the submit
+# acknowledgement and the away-mode supervisor-pane busy guard. Both ask about
+# the pane receiving input, not the state of a recorded worker task. Matching
+# stays harness-scoped so one harness's output cannot make another read busy.
+#
+# All functions are `set -u` and `set -e` safe (guarded tmux calls, explicit
+# returns) so they can be sourced into either context.
+#
+# Composer classification is NOT owned here: every shape, glyph, border
+# family, geometry rule, and verdict decision lives in the shared
+# bin/fm-composer-lib.sh (fm_composer_classify_screen), sourced below and
+# reused by every backend adapter so the decision cannot drift. This file
+# keeps only tmux's genuine capture-side primitives - the styled pane
+# capture, the #{cursor_y} cursor read, the pi foreground-process identity
+# probe, and the capability descriptor - plus the busy detection and submit
+# cores that consume the shared verdict.
+
+# shellcheck source=bin/fm-composer-lib.sh
+. "$(dirname -- "${BASH_SOURCE[0]}")/fm-composer-lib.sh"
+# shellcheck source=bin/fm-cursor-lib.sh
+. "$(dirname -- "${BASH_SOURCE[0]}")/fm-cursor-lib.sh"
+
+
+# fm_tmux_strip_ghost: thin adapter over the shared, fleet-wide ghost extractor
+# fm_composer_strip_ghost (bin/fm-composer-lib.sh). It drops de-emphasised
+# ghost/placeholder runs - dim/faint (SGR 2, claude's/codex's/cursor's ghost) AND a
+# dark/muted truecolor foreground (grok's placeholder) - from one captured,
+# styled composer line and prints the plain, real-typed text. Kept as a named
+# tmux entry point (and for existing callers/tests) but owns no logic of its own,
+# so the tmux and herdr adapters cannot drift apart on what counts as ghost text.
+fm_tmux_strip_ghost() { fm_composer_strip_ghost; }
+
+# --- tmux composer capture and capability primitives ------------------------
+#
+# These four functions are the ONLY tmux-specific composer knowledge left:
+# how to capture a styled screen, how to read the cursor row, how to probe a
+# live pi agent, and the static capability facts. Every shape, glyph, border
+# family, and verdict decision lives in the shared owner
+# (bin/fm-composer-lib.sh, fm_composer_classify_screen), so a new harness
+# shape is taught there once and never here.
+
+# fm_tmux_composer_capture: the visible pane WITH ANSI styling. The styled
+# capture is consumed internally by the classifier and is NEVER surfaced
+# (fm-peek and every human/LLM-facing path stay plain).
+fm_tmux_composer_capture() {  # <target>
+  tmux capture-pane -e -p -t "$1" -S 0 -E - 2>/dev/null
+}
+
+# fm_tmux_composer_cursor_row: the pane's cursor row, zero-based, relative to
+# the visible pane - tmux's genuine primitive that no other backend has.
+fm_tmux_composer_cursor_row() {  # <target>
+  tmux display-message -p -t "$1" '#{cursor_y}' 2>/dev/null
+}
+
+# fm_tmux_composer_caps: the tmux capability descriptor - static data, not
+# logic (see the capability model in bin/fm-composer-lib.sh).
+fm_tmux_composer_caps() {
+  printf 'styled=1\ncursor=1\nidentity=1\nrows=0\n'
+}
+
+# fm_tmux_composer_identity: the tmux agent-identity probe backing the
+# separated (pi) composer shape, tmux's analogue of herdr's native
+# `agent get`. It answers only for pi, from two live signals:
+#   - identity: the pane tty's FOREGROUND process group (pgid = tpgid, the
+#     same scoping as fm_backend_tmux_foreground_comms) contains a pi-family
+#     process (pi, pi-signed, pi-launcher - docs/verification/
+#     runtime-backends.md "Agent liveness name sources"), falling back to
+#     tmux's own foreground-derived #{pane_current_command}. A pane whose
+#     agent died to a shell has no pi foreground process and gets NO identity,
+#     which is exactly what keeps the strict blank-row rule honest: a blank
+#     row between two stale rules stays unknown.
+#   - status: pi's verified busy footer via fm_pane_is_busy, mapped onto the
+#     idle/working vocabulary herdr's probe reports natively.
+# Prints "pi<TAB>idle" or "pi<TAB>working"; exits 1 when the pane is not a
+# live pi.
+fm_tmux_composer_identity() {  # <target>
+  local target=$1 tty pgid tpgid comm found=0 status
+  tty=$(tmux display-message -p -t "$target" '#{pane_tty}' 2>/dev/null) || tty=
+  case "$tty" in
+    /dev/*)
+      while read -r _ pgid tpgid comm; do
+        [ -n "$comm" ] || continue
+        [ "$pgid" = "$tpgid" ] || continue
+        case "${comm##*/}" in
+          pi|pi-signed|pi-launcher|Pi) found=1 ;;
+        esac
+      done <<EOF
+$(LC_ALL=C ps -t "${tty#/dev/}" -o pid=,pgid=,tpgid=,comm= 2>/dev/null)
+EOF
+      ;;
+  esac
+  if [ "$found" -ne 1 ]; then
+    comm=$(tmux display-message -p -t "$target" '#{pane_current_command}' 2>/dev/null) || comm=
+    case "${comm##*/}" in
+      pi|pi-signed|pi-launcher) found=1 ;;
+    esac
+  fi
+  [ "$found" -eq 1 ] || return 1
+  status=$(fm_pane_busy_state "$target" pi)
+  case "$status" in
+    busy) printf 'pi\tworking' ;;
+    idle) printf 'pi\tidle' ;;
+    *) return 1 ;;
+  esac
+}
+
+# fm_tmux_composer_state: the tmux composer verdict - a thin adapter over the
+# shared screen classifier. The verdict contract (empty | pending |
+# pending-unproven | unknown, positive proof required for empty, unrecognized
+# future verdicts failing safe) is owned by bin/fm-composer-lib.sh. Identity
+# is fetched lazily, only when the classifier reports the verdict depends on
+# it (a pi separator pair under the cursor), so the common read never pays
+# for the process probe.
+fm_tmux_composer_state() {  # <target> -> empty|pending|pending-unproven|unknown
+  local target=$1 cy pane verdict identity
+  cy=$(fm_tmux_composer_cursor_row "$target") || { printf 'unknown'; return 0; }
+  case "$cy" in ''|*[!0-9]*) printf 'unknown'; return 0 ;; esac
+  pane=$(fm_tmux_composer_capture "$target") || { printf 'unknown'; return 0; }
+  verdict=$(fm_composer_classify_screen "$(fm_tmux_composer_caps)" "$pane" "$cy")
+  if [ "$verdict" = need-identity ]; then
+    if ! identity=$(fm_tmux_composer_identity "$target") || [ -z "$identity" ]; then
+      identity=probe-absent
+    fi
+    verdict=$(fm_composer_classify_screen "$(fm_tmux_composer_caps)" "$pane" "$cy" "$identity")
+    [ "$verdict" != need-identity ] || verdict=unknown
+  fi
+  # Cursor Agent CLI parks its terminal cursor OUTSIDE its composer, below the
+  # footer, with #{cursor_flag} 0 - so on a Cursor pane tmux's cursor row is not
+  # a composer locator and the cursor-anchored read can only ever answer
+  # `unknown`. Reclassify that pane the way every cursorless backend already
+  # classifies it, letting the bottom-most shape win, which is the same rule
+  # herdr, zellij, cmux, and orca use for every harness including this one.
+  # Gated on Cursor's own structural process identity, never on the verdict
+  # alone, so the strict blank-row posture that owns `unknown` for every other
+  # harness is untouched.
+  if [ "$verdict" = unknown ] && fm_tmux_pane_is_cursor "$target"; then
+    verdict=$(fm_composer_classify_screen "$(fm_tmux_composer_caps)" "$pane" '')
+  fi
+  printf '%s' "$verdict"
+}
+
+# fm_tmux_pane_is_cursor: true when the pane's FOREGROUND process group contains
+# a genuine Cursor Agent CLI process. Cursor runs as a bundled node script, so
+# tmux's own #{pane_current_command} reports a bare `node`; identity therefore
+# comes from Cursor's name or install tree in the command path or argv[0], whose
+# single owner is bin/fm-cursor-lib.sh. The foreground scoping (pgid = tpgid)
+# matches fm_tmux_composer_identity, so a pane whose agent exited to a shell has
+# no Cursor foreground process and gets no reclassification.
+fm_tmux_pane_is_cursor() {  # <target>
+  local target=$1 tty pid pgid tpgid comm args argv0
+  tty=$(tmux display-message -p -t "$target" '#{pane_tty}' 2>/dev/null) || return 1
+  case "$tty" in /dev/*) ;; *) return 1 ;; esac
+  while read -r pid pgid tpgid comm; do
+    [ -n "$comm" ] || continue
+    [ "$pgid" = "$tpgid" ] || continue
+    args=$(LC_ALL=C ps -p "$pid" -o args= 2>/dev/null) || args=
+    args=${args#"${args%%[![:space:]]*}"}
+    argv0=${args%%[[:space:]]*}
+    fm_cursor_process_matches "$comm" '' "$argv0" && return 0
+  done <<EOF
+$(LC_ALL=C ps -t "${tty#/dev/}" -o pid=,pgid=,tpgid=,comm= 2>/dev/null)
+EOF
+  return 1
+}
+
+# fm_pane_input_pending: 0 when the composer is not proven empty, so pending
+# text, ambiguous structure, unreadable state, and future verdicts all defer.
+fm_pane_input_pending() {  # <target>
+  [ "$(fm_tmux_composer_state "$1")" != empty ]
+}
+
+# fm_pane_is_busy: 0 if the pane's last few non-blank lines show a busy footer
+# (an agent mid-turn). Scans a 40-line tail like fm-watch.sh.
+fm_pane_busy_state() {  # <target> [harness] -> busy|idle|unknown
+  local win=$1 harness=${2:-} tail40 visible
+  tail40=$(tmux capture-pane -p -t "$win" -S -40 2>/dev/null) \
+    || { printf 'unknown'; return 0; }
+  visible=$(printf '%s' "$tail40" | grep -v '^[[:space:]]*$' | tail -12)
+  [ -n "$visible" ] || { printf 'unknown'; return 0; }
+  if printf '%s' "$visible" | fm_busy_lines_match "$harness"; then
+    printf 'busy'
+  else
+    printf 'idle'
+  fi
+}
+
+fm_pane_is_busy() {  # <target> [harness]
+  [ "$(fm_pane_busy_state "$1" "${2:-}")" = busy ]
+}
+
+# fm_tmux_submit_core: type <text> into <target> ONCE, then submit with Enter,
+# verifying the composer cleared. Retries Enter ONLY — never retypes, because a
+# swallowed Enter leaves our text in the composer and retyping would duplicate
+# it. Echoes the final proof-carrying verdict on stdout so callers can require
+# exact `empty` before treating submission as confirmed.
+# Busy-queued Enter (opencode 1.18.4): the harness accepts Enter while mid-turn
+# and queues it for after the current turn, but keeps the typed text visible in
+# the composer. Once the Enter-retry budget is spent and a structurally proven
+# composer still reads "pending", the submit core falls back to
+# `fm_pane_is_busy`: a busy pane means the Enter was accepted and queued (report
+# `empty` so the caller does not re-send), while an idle pane keeps `pending` as
+# a genuine swallow. Pending-unproven receives the same Enter retry budget but
+# never reaches this exception.
+# Turn-started confirmation (the strict blank-row posture's counterpart): a
+# harness whose mid-turn screen the classifier cannot positively identify (pi
+# replaces its separated composer while working) reads `unknown` right after a
+# successful submit. When and only when the pane was IDLE before the text was
+# typed, an idle-to-busy transition across our Enter is proof the harness
+# accepted the submission - the same semantic signal herdr's native
+# agent-state confirmation uses, read from the pane's verified busy footer.
+# The busy read is polled across the remaining retry budget because the turn
+# takes a beat to render. Without the baseline (a direct
+# fm_tmux_submit_enter_core caller, or a pane already busy before typing) an
+# `unknown` verdict is preserved untouched: busy conversion without the
+# transition evidence could mark an undelivered message delivered.
+fm_tmux_submit_enter_core() {  # <target> <retries> <enter-sleep> [baseline-idle]
+  local target=$1 retries=$2 sleep_s=$3 baseline_idle=${4:-} i=0 j state busy_state
+  while :; do
+    tmux send-keys -t "$target" Enter 2>/dev/null || true
+    sleep "$sleep_s"
+    state=$(fm_tmux_composer_state "$target")
+    case "$state" in
+      pending|pending-unproven) ;;
+      unknown)
+        if [ "$baseline_idle" = 1 ]; then
+          j=0
+          while [ "$j" -lt "$retries" ]; do
+            if fm_pane_is_busy "$target"; then
+              printf 'empty'
+              return 0
+            fi
+            j=$((j + 1))
+            [ "$j" -ge "$retries" ] || sleep "$sleep_s"
+          done
+        fi
+        printf 'unknown'
+        return 0
+        ;;
+      *) printf '%s' "$state"; return 0 ;;
+    esac
+    i=$((i + 1))
+    [ "$i" -lt "$retries" ] || break
+  done
+  if [ "$state" != pending ]; then
+    printf '%s' "$state"
+    return 0
+  fi
+  # Retries exhausted, composer still shows proven pending.
+  # Busy conversion is owned by fm_composer_queued_enter_verdict.
+  busy_state=idle
+  fm_pane_is_busy "$target" && busy_state=busy
+  fm_composer_queued_enter_verdict "$state" "$busy_state"
+}
+
+fm_tmux_submit_core() {  # <target> <text> <retries> <enter-sleep> <settle>
+  local target=$1 text=$2 retries=$3 sleep_s=$4 settle=$5 baseline_idle='' baseline_state
+  # The turn-started baseline must predate our own typing: a pane already
+  # busy before the text lands can turn "busy" for reasons unrelated to our
+  # Enter, so only a clean idle-to-busy transition may confirm a submit.
+  baseline_state=$(fm_pane_busy_state "$target")
+  [ "$baseline_state" = idle ] && baseline_idle=1
+  tmux send-keys -t "$target" -l "$text" 2>/dev/null || { printf 'send-failed'; return 0; }
+  sleep "$settle"
+  fm_tmux_submit_enter_core "$target" "$retries" "$sleep_s" "$baseline_idle"
+}