@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/backend/backends/orca.sh

@@ -0,0 +1,290 @@
+#!/usr/bin/env bash
+# bin/backends/orca.sh - the Orca terminal session-provider adapter.
+#
+# Orca owns both the task worktree and the terminal endpoint. Escape key support
+# remains unsupported until Orca exposes a terminal-send primitive for it.
+#
+# Target string shape: the Orca terminal id accepted by `orca terminal ...`.
+
+# Shared composer-content classifier (empty|pending|unknown, and the fleet-wide
+# dead-shell-vs-agent-composer rule). Owned by bin/fm-composer-lib.sh, reused by
+# every backend so the decision cannot drift.
+# shellcheck source=bin/fm-composer-lib.sh
+. "$(dirname -- "${BASH_SOURCE[0]}")/../fm-composer-lib.sh"
+
+fm_backend_orca_tool_check() {
+  command -v orca >/dev/null 2>&1 || { echo "error: backend=orca selected but the 'orca' CLI is not installed" >&2; return 1; }
+}
+
+fm_backend_orca_runtime_check() {
+  fm_backend_orca_tool_check || return 1
+  local out
+  out=$(orca status --json 2>/dev/null) || {
+    echo "error: backend=orca selected but 'orca status --json' failed; start Orca and wait for the runtime to be ready" >&2
+    return 1
+  }
+  # shellcheck disable=SC2016  # Single quotes are deliberate: ${...} belongs to the Node snippet.
+  printf '%s' "$out" | node -e '
+const fs = require("fs");
+let data;
+try {
+  data = JSON.parse(fs.readFileSync(0, "utf8"));
+} catch (err) {
+  console.error("error: invalid Orca status JSON: " + err.message);
+  process.exit(1);
+}
+if (data.ok === false) {
+  const msg = data.error && (data.error.message || data.error.code);
+  console.error("error: Orca runtime is not ready" + (msg ? ": " + msg : ""));
+  process.exit(1);
+}
+const r = data.result || {};
+const runtime = r.runtime || {};
+const reachable = runtime.reachable ?? r.runtimeReachable;
+const state = runtime.state || r.runtimeState || "";
+if (reachable === true && state === "ready") process.exit(0);
+console.error(`error: backend=orca requires a ready Orca runtime (reachable=${String(reachable)}, state=${state || "unknown"})`);
+process.exit(1);
+'
+}
+
+fm_backend_orca_json_get() {  # <field> ; fields: worktree-id worktree-path terminal-handle worktree-terminal-handle repo-id
+  # Terminal handles are accepted only from verified terminal result shapes:
+  # result.terminal or a root terminal object with .handle. Undocumented
+  # result.id and result.worktree.terminal shapes are ignored until a real Orca
+  # smoke run proves them.
+  local field=$1
+  node -e '
+const fs = require("fs");
+const field = process.argv[1];
+const data = JSON.parse(fs.readFileSync(0, "utf8"));
+if (data.ok === false) {
+  const msg = data.error && (data.error.message || data.error.code);
+  if (msg) console.error(msg);
+  process.exit(2);
+}
+const r = data.result || {};
+const wt = r.worktree || r.item || r;
+const explicitTerm = r.terminal || null;
+const repo = r.repo || r.repository || r;
+function scalar(v) {
+  return (typeof v === "string" || typeof v === "number") ? String(v) : "";
+}
+function handle(obj) {
+  if (!obj) return "";
+  if (typeof obj === "string" || typeof obj === "number") return String(obj);
+  return scalar(obj.handle) || "";
+}
+let v = "";
+if (field === "worktree-id") v = wt.id || wt.worktreeId || r.worktreeId || "";
+if (field === "worktree-path") v = wt.path || (wt.git && wt.git.path) || r.path || "";
+if (field === "terminal-handle") v = handle(explicitTerm || r) || "";
+if (field === "worktree-terminal-handle") v = handle(explicitTerm) || "";
+if (field === "repo-id") v = repo.id || repo.repoId || r.repoId || "";
+if (!v) process.exit(1);
+process.stdout.write(String(v));
+' "$field"
+}
+
+fm_backend_orca_json_ok() {
+  node -e '
+const fs = require("fs");
+const input = fs.readFileSync(0, "utf8").trim();
+if (!input) process.exit(0);
+let data;
+try {
+  data = JSON.parse(input);
+} catch (err) {
+  console.error("invalid Orca JSON: " + err.message);
+  process.exit(2);
+}
+if (data.ok === false) {
+  const msg = data.error && (data.error.message || data.error.code);
+  if (msg) console.error(msg);
+  process.exit(2);
+}
+'
+}
+
+fm_backend_orca_run_json() {
+  local out
+  out=$("$@") || return 1
+  printf '%s' "$out" | fm_backend_orca_json_ok
+}
+
+fm_backend_orca_repo_ensure() {  # <project-path>
+  local project=$1 out repo_id
+  fm_backend_orca_tool_check || return 1
+  out=$(orca repo show --repo "path:$project" --json 2>/dev/null || true)
+  if repo_id=$(printf '%s' "$out" | fm_backend_orca_json_get repo-id 2>/dev/null); then
+    printf '%s' "$repo_id"
+    return 0
+  fi
+  out=$(orca repo add --path "$project" --json) || return 1
+  repo_id=$(printf '%s' "$out" | fm_backend_orca_json_get repo-id) || {
+    echo "error: orca repo add did not return a repo id for $project" >&2
+    return 1
+  }
+  printf '%s' "$repo_id"
+}
+
+fm_backend_orca_worktree_create() {  # <project-path> <name>
+  local project=$1 name=$2 repo_id out wt_id wt_path terminal
+  repo_id=$(fm_backend_orca_repo_ensure "$project") || return 1
+  out=$(orca worktree create --repo "id:$repo_id" --name "$name" --no-parent --setup skip --json) || return 1
+  wt_id=$(printf '%s' "$out" | fm_backend_orca_json_get worktree-id) || {
+    echo "error: orca worktree create did not return a worktree id for $name" >&2
+    return 1
+  }
+  terminal=$(printf '%s' "$out" | fm_backend_orca_json_get worktree-terminal-handle 2>/dev/null || true)
+  wt_path=$(printf '%s' "$out" | fm_backend_orca_json_get worktree-path) || {
+    echo "error: orca worktree create did not return a path for $name" >&2
+    [ -z "$terminal" ] || fm_backend_orca_kill "$terminal" >/dev/null 2>&1 || true
+    if fm_backend_orca_remove_worktree "$wt_id" >/dev/null; then
+      return 1
+    fi
+    if [ -n "$terminal" ]; then
+      printf '%s\t\t%s' "$wt_id" "$terminal"
+    else
+      printf '%s\t' "$wt_id"
+    fi
+    return 2
+  }
+  printf '%s\t%s' "$wt_id" "$wt_path"
+  [ -z "$terminal" ] || printf '\t%s' "$terminal"
+}
+
+fm_backend_orca_terminal_create() {  # <worktree-id> <title>
+  local worktree_id=$1 title=$2 out terminal
+  fm_backend_orca_tool_check || return 1
+  out=$(orca terminal create --worktree "id:$worktree_id" --title "$title" --json) || return 1
+  terminal=$(printf '%s' "$out" | fm_backend_orca_json_get terminal-handle) || {
+    echo "error: orca terminal create did not return a terminal handle for $title" >&2
+    return 1
+  }
+  printf '%s' "$terminal"
+}
+
+fm_backend_orca_send_text_line() {  # <terminal-id> <text>
+  local terminal=$1 text=$2
+  fm_backend_orca_tool_check || return 1
+  fm_backend_orca_run_json orca terminal send --terminal "$terminal" --text "$text" --enter --json
+}
+
+fm_backend_orca_send_literal() {  # <terminal-id> <text>
+  local terminal=$1 text=$2
+  fm_backend_orca_tool_check || return 1
+  fm_backend_orca_run_json orca terminal send --terminal "$terminal" --text "$text" --json
+}
+
+fm_backend_orca_remove_worktree() {  # <worktree-id>
+  local worktree_id=${1:-}
+  [ -n "$worktree_id" ] || { echo "error: missing Orca worktree id; cannot remove worktree" >&2; return 1; }
+  fm_backend_orca_tool_check || return 1
+  fm_backend_orca_run_json orca worktree rm --worktree "id:$worktree_id" --force --json
+}
+
+fm_backend_orca_worktree_path() {
+  local worktree_id=${1:-} out path
+  [ -n "$worktree_id" ] || { echo "error: missing Orca worktree id; cannot resolve worktree path" >&2; return 1; }
+  fm_backend_orca_tool_check || return 1
+  out=$(orca worktree show --worktree "id:$worktree_id" --json) || return 1
+  path=$(printf '%s' "$out" | fm_backend_orca_json_get worktree-path) || {
+    echo "error: orca worktree show did not return a path for $worktree_id" >&2
+    return 1
+  }
+  printf '%s' "$path"
+}
+
+fm_backend_orca_capture() {  # <terminal-id> <lines>
+  local terminal=$1 lines=${2:-40} out
+  fm_backend_orca_tool_check || return 1
+  out=$(orca terminal read --terminal "$terminal" --limit "$lines" --json) || return 1
+  fm_backend_orca_json_text "$out"
+}
+
+fm_backend_orca_json_text() {  # <json>
+  printf '%s' "$1" | node -e '
+const fs = require("fs");
+const data = JSON.parse(fs.readFileSync(0, "utf8"));
+if (data.ok === false) {
+  const msg = data.error && (data.error.message || data.error.code);
+  if (msg) console.error(msg);
+  process.exit(2);
+}
+const r = data.result || {};
+if (r.terminal && Array.isArray(r.terminal.tail)) {
+  process.stdout.write(r.terminal.tail.join("\n"));
+} else if (Array.isArray(r.tail)) {
+  process.stdout.write(r.tail.join("\n"));
+} else {
+  process.stdout.write(r.text || r.output || r.content || r.preview || "");
+}
+'
+}
+
+# fm_backend_orca_composer_capture: the orca composer screen - one bounded
+# tail read of the live terminal. Deliberately NOT the old 200-line
+# backward-paged read: the composer is bottom-anchored, and paging back into
+# scrollback is what let a stale startup banner (codex's bordered
+# "permissions" box) compete with - and once outrank - the live composer.
+fm_backend_orca_composer_capture() {  # <terminal-id> [expected-label]
+  fm_backend_orca_capture "$1" "$FM_COMPOSER_CAPTURE_LINES"
+}
+
+# fm_backend_orca_composer_caps: static capability facts, not logic (see the
+# capability model in bin/fm-composer-lib.sh). Orca's `terminal read` returns
+# plain text; whether it can emit ANSI is unverified (orca is not installed
+# on the verification machine), so styled stays 0 - the conservative
+# degradation - until a live capture proves otherwise.
+fm_backend_orca_composer_caps() {
+  printf 'styled=0\ncursor=0\nidentity=0\nrows=%s\n' "$FM_COMPOSER_CAPTURE_LINES"
+}
+
+# fm_backend_orca_composer_state: thin adapter - capture plus capabilities in,
+# shared verdict out. Every shape (bordered boxes AND the borderless bare-glyph
+# row this adapter never learned, which left every claude/codex/pi/muse steer
+# unconfirmed) lives in bin/fm-composer-lib.sh.
+fm_backend_orca_composer_state() {  # <terminal-id> [expected-label] -> empty|pending|pending-unproven|unknown
+  local cap verdict
+  cap=$(fm_backend_orca_composer_capture "$1") || { printf 'unknown'; return 0; }
+  verdict=$(fm_composer_classify_screen "$(fm_backend_orca_composer_caps)" "$cap")
+  [ "$verdict" != need-identity ] || verdict=unknown
+  printf '%s' "$verdict"
+}
+
+fm_backend_orca_send_key() {  # <terminal-id> <key>
+  local terminal=$1 key=$2
+  fm_backend_orca_tool_check || return 1
+  case "$key" in
+    C-c|ctrl+c|Ctrl-c|Ctrl-C)
+      fm_backend_orca_run_json orca terminal send --terminal "$terminal" --interrupt --json
+      ;;
+    Enter|enter)
+      fm_backend_orca_run_json orca terminal send --terminal "$terminal" --text "" --enter --json
+      ;;
+    *)
+      echo "error: unsupported Orca key '$key'" >&2
+      return 1
+      ;;
+  esac
+}
+
+# fm_backend_orca_send_text_submit: type <text> once, then drive the shared
+# verify-and-retry-Enter loop (bin/fm-composer-lib.sh:
+# fm_composer_submit_retry_core) against the shared composer verdict, so a
+# slash-command popup placeholder fill gets the required second Enter without
+# duplicating text.
+fm_backend_orca_send_text_submit() {  # <terminal-id> <text> <retries> <enter-sleep> <settle>
+  local terminal=$1 text=$2 retries=$3 sleep_s=$4 settle=$5
+  fm_backend_orca_tool_check || { printf 'send-failed'; return 0; }
+  fm_backend_orca_send_literal "$terminal" "$text" || { printf 'send-failed'; return 0; }
+  sleep "$settle"
+  fm_composer_submit_retry_core fm_backend_orca_send_key fm_backend_orca_composer_state \
+    "$terminal" "$retries" "$sleep_s"
+}
+
+fm_backend_orca_kill() {  # <terminal-id>
+  fm_backend_orca_tool_check || return 0
+  orca terminal close --terminal "$1" --json >/dev/null 2>&1 || true
+}

package/.agents/backend/backends/tmux.sh

@@ -0,0 +1,357 @@
+#!/usr/bin/env bash
+# bin/backends/tmux.sh - the tmux session-provider adapter.
+#
+# Reference backend (AGENTS.md section 8; data/fm-backend-design-d7). P1 moves
+# the tmux command sequences that fm-send.sh, fm-peek.sh, fm-watch.sh,
+# fm-spawn.sh, and fm-teardown.sh already ran inline into named functions
+# here, running the EXACT same commands in the EXACT same order, so the
+# default (tmux, `backend=` absent) path stays byte-identical. Sourced only
+# through bin/fm-backend.sh's fm_backend_source, never directly.
+#
+# Worktree acquisition (running `treehouse get` inside the pane, and polling
+# its cwd) is unchanged by this extraction: P1 scopes only the session
+# provider, not the worktree provider, so fm-spawn.sh still drives that part
+# inline with these same send/current-path primitives.
+#
+# The verified composer/busy-detection and verify-and-retry-submit primitives
+# already live in bin/fm-tmux-lib.sh, shared with the away-mode daemon
+# (bin/fm-supervise-daemon.sh); this adapter sources that file and re-exports
+# its submit core under the backend's naming convention rather than
+# duplicating it, so the two consumers cannot drift apart.
+# shellcheck source=bin/fm-tmux-lib.sh
+. "$FM_BACKEND_LIB_DIR/fm-tmux-lib.sh"
+# shellcheck source=bin/fm-session-lock-lib.sh
+. "$FM_BACKEND_LIB_DIR/fm-session-lock-lib.sh"
+# shellcheck source=bin/fm-cursor-lib.sh
+. "$FM_BACKEND_LIB_DIR/fm-cursor-lib.sh"
+
+# fm_backend_tmux_resolve_bare_selector: the live-window-listing fallback for a
+# selector that is neither an explicit target nor a task selector routed
+# through meta - an ad hoc window name with no recorded task. Mirrors the
+# `tmux list-windows -a ... | grep` pipeline that used to live inline in
+# fm-send.sh's and fm-peek.sh's own (until now duplicated) resolve().
+fm_backend_tmux_resolve_bare_selector() {  # <name>
+  local name=$1
+  tmux list-windows -a -F '#{session_name}:#{window_name}' | grep -m1 ":$name\$" \
+    || { echo "error: no window named $name" >&2; return 1; }
+}
+
+# fm_backend_tmux_capture: bounded plain-text pane capture. Mirrors
+# fm-peek.sh's and fm-watch.sh's `tmux capture-pane -p -t "$T" -S -"$N"`.
+fm_backend_tmux_capture() {  # <target> <lines>
+  tmux capture-pane -p -t "$1" -S -"$2"
+}
+
+# fm_backend_tmux_send_key: one named key. Mirrors fm-send.sh's --key path:
+# `tmux display-message -p -t "$T" '#{pane_id}' >/dev/null`, then
+# `tmux send-keys -t "$T" "$2"`.
+fm_backend_tmux_send_key() {  # <target> <key>
+  tmux display-message -p -t "$1" '#{pane_id}' >/dev/null
+  tmux send-keys -t "$1" "$2"
+}
+
+# fm_backend_tmux_send_text_submit: type <text> into <target> once, then
+# submit with Enter, retried (Enter only, never retyped) until the composer
+# clears. Re-exports fm_tmux_submit_core (bin/fm-tmux-lib.sh) verbatim; see
+# that file for the composer-verification contract and echoed verdicts.
+fm_backend_tmux_send_text_submit() {  # <target> <text> <retries> <enter-sleep> <settle>
+  fm_tmux_submit_core "$@"
+}
+
+# fm_backend_tmux_container_ensure: reuse the current tmux session when
+# firstmate itself runs inside tmux, else ensure a dedicated detached
+# "firstmate" session exists. Mirrors fm-spawn.sh's container-ensure block;
+# prints the resolved session name.
+fm_backend_tmux_container_ensure() {
+  if [ -n "${TMUX:-}" ]; then
+    tmux display-message -p '#S'
+  else
+    tmux has-session -t firstmate 2>/dev/null || tmux new-session -d -s firstmate
+    printf 'firstmate'
+  fi
+}
+
+# fm_backend_tmux_create_task: create the task's window in <proj-abs>,
+# refusing an existing <window-name> in <session>. Mirrors fm-spawn.sh's
+# duplicate-check-then-new-window sequence, including the exact error text
+# (session:window, matching how fm-spawn.sh composed its own $T). Prints the
+# created window's stable window id on stdout for the caller to target.
+#
+# Robustness (fm-spawn tmux window handling under a non-default captain config):
+#   - Capture a STABLE window id with -P -F '#{window_id}', and let tmux append
+#     at the next free index by targeting the session with a trailing colon
+#     ("$ses:"), so a non-default base-index (e.g. base-index 1) cannot collide.
+#   - PIN the window name by disabling automatic-rename and allow-rename on the
+#     new window: the captain's tmux may rename the window away from fm-<id> once
+#     treehouse cd's into the worktree, which would break name-based targeting.
+# The returned window id lets callers target the window even if its name is ever
+# lost, so worktree discovery cannot fall back to the active client's window.
+fm_backend_tmux_create_task() {  # <session> <window-name> <proj-abs> -> prints window id
+  local ses=$1 wname=$2 proj_abs=$3 wid
+  if tmux list-windows -t "$ses" -F '#{window_name}' | grep -qx "$wname"; then
+    echo "error: window $ses:$wname already exists" >&2
+    return 1
+  fi
+  wid=$(tmux new-window -dP -F '#{window_id}' -t "$ses:" -n "$wname" -c "$proj_abs") || return 1
+  tmux set-window-option -t "$wid" automatic-rename off 2>/dev/null || true
+  tmux set-window-option -t "$wid" allow-rename off 2>/dev/null || true
+  printf '%s\n' "$wid"
+}
+
+# fm_backend_tmux_current_path: the live pane's current working directory, or
+# empty on any tmux error. Mirrors fm-spawn.sh's worktree-discovery poll:
+# `tmux display-message -p -t "$T" '#{pane_current_path}'`.
+fm_backend_tmux_current_path() {  # <target>
+  tmux display-message -p -t "$1" '#{pane_current_path}' 2>/dev/null
+}
+
+# fm_backend_tmux_send_text_line: send one line of TEXT then Enter, with no
+# composer verification - used for the fixed spawn-time commands
+# (`treehouse get`, the GOTMPDIR export) that already ran this exact sequence
+# inline in fm-spawn.sh. Mirrors `tmux send-keys -t "$T" "<text>" Enter`.
+fm_backend_tmux_send_text_line() {  # <target> <text>
+  tmux send-keys -t "$1" "$2" Enter
+}
+
+# fm_backend_tmux_send_literal: send TEXT as literal bytes with no
+# submission - the caller sends Enter separately (fm-spawn.sh's launch-command
+# send pauses between the literal send and Enter for the harness to settle).
+# Mirrors `tmux send-keys -t "$T" -l "<text>"`.
+fm_backend_tmux_send_literal() {  # <target> <text>
+  tmux send-keys -t "$1" -l "$2"
+}
+
+# fm_backend_tmux_kill: remove one explicitly named task window, best-effort.
+# Empty, omitted, and malformed targets return nonzero before invoking tmux so
+# tmux can never interpret an empty target as the caller's current window.
+fm_backend_tmux_kill() {  # <target>
+  local target=${1:-} session window
+  case "$target" in
+    *:*)
+      session=${target%%:*}
+      window=${target#*:}
+      ;;
+    *) return 1 ;;
+  esac
+  case "$session:$window" in
+    :*|*:|*:*:*) return 1 ;;
+  esac
+  tmux kill-window -t "=$session:=$window" 2>/dev/null || true
+}
+
+# fm_backend_tmux_current_command: <target>'s live foreground process name -
+# tmux's own `#{pane_current_command}`, already resolved from the pty's
+# foreground process group (verified empirically with real tmux 3.6a: a
+# harness invoked interactively stays the reported command even while it
+# shells out to subcommands that do not take over the pty - e.g. `bash -c
+# "sleep 30"` alone reports "sleep" because bash execs directly into it, but
+# a persisting parent script running `sleep` as a child reports the PARENT's
+# own name throughout; the value reverts to the shell's own name only once
+# the foreground command actually exits). Empty on any tmux error.
+fm_backend_tmux_current_command() {  # <target>
+  tmux display-message -p -t "$1" '#{pane_current_command}' 2>/dev/null
+}
+
+# fm_backend_tmux_classify_process_name: the single owner of the process-name
+# vocabulary shared by every liveness signal below - `agent` for a verified
+# harness, `shell` for an idle login/interactive shell, `other` for anything
+# else. Keeping one classifier means the two independent name sources can never
+# drift into disagreeing about what a given name means.
+fm_backend_tmux_classify_process_name() {  # <path> [argv0] -> agent|shell|other
+  local path=$1 argv0=${2:-} base
+  base=${path##*/}
+  base=${base#-}
+  case "$base" in
+    # muse is anchored rather than globbed like its neighbours: its installed
+    # binary is muse-bin-<version> (the launcher execs it, so the version is the
+    # live process name and changes on every auto-update), and unlike `claude` or
+    # `codex` the substring `muse` is a common English fragment - a *muse* glob
+    # would classify musescore or amuse as a live agent pane. The install path
+    # cannot carry it either: ~/.local/bin/muse-bin-<version> has no `muse` path
+    # COMPONENT, so the fm_harness_path_name fallback below never fires for it.
+    muse|muse-bin-*) printf 'agent' ;;
+    *claude*|*codex*|*opencode*|*grok*|*kimi*|pi|pi-signed|pi-launcher|Pi) printf 'agent' ;;
+    zsh|bash|sh|dash|ash|ksh|mksh|tcsh|csh|fish) printf 'shell' ;;
+    *)
+      if fm_harness_path_name "$path" >/dev/null || fm_harness_path_name "$argv0" >/dev/null; then
+        printf 'agent'
+      # cursor-agent runs as a bundled node script, so tmux reports the pane
+      # command as a bare `node` that no name pattern above can own, and its
+      # other installed name is the far-too-generic `agent` (verified live on
+      # cursor-agent 2026.08.11-e8db854: #{pane_current_command} is `node` while
+      # `ps -o comm=` carries the cursor-agent install path). Identity therefore
+      # comes from the narrowed structural rule in bin/fm-cursor-lib.sh, which
+      # demands Cursor's own name or install tree in the path or argv[0]. An
+      # unrelated `node` or `agent` matches nothing here and stays `other`,
+      # which the callers above fold into `ambiguous` rather than `dead`, so a
+      # stranger's node pane is never reported as an agent-free pane.
+      elif fm_cursor_process_matches "${path:-$argv0}" '' "$argv0"; then
+        printf 'agent'
+      else
+        printf 'other'
+      fi
+      ;;
+  esac
+}
+
+# fm_backend_tmux_foreground_comms: the kernel-side names of every process in
+# <target>'s pane tty foreground process group, one full value per line.
+# Empty on any failure.
+#
+# This is the foreground-process-group half of the liveness probe, and it exists
+# because `#{pane_current_command}` and `ps -o comm=` expose different name
+# fields whose roles vary by platform. On macOS the tmux field can carry a
+# harness-rewritten title (Claude Code 2.1.220 reports `2.1.220`) while `comm`
+# retains executable identity; the portable Linux regression observes the
+# reverse for its version-named executable. Reading both `comm` and argv[0]
+# preserves an identifying install path without making either platform's field
+# assignment load-bearing.
+#
+# Scoping to the foreground process group rather than to the pane's descendants
+# is what keeps the probe honest in the other direction: a harness-named process
+# left running in the background of an otherwise idle pane is deliberately NOT
+# reported, so a genuinely agent-free pane still classifies `dead`. It also
+# reports every member of a multi-process launcher (the Pi Launcher path runs a
+# `pi-signed` wrapper and a `pi` engine in one group), so no launcher needs its
+# own special case here.
+#
+# Like fm_backend_tmux_current_command this is a RAW pane read: tmux answers an
+# absent target from the client's active window rather than failing, so callers
+# must confirm exact window membership first, exactly as the classifier below
+# does, or they will describe some other pane entirely.
+fm_backend_tmux_foreground_comms() {  # <target>
+  local target=$1 tty pid pgid tpgid comm
+  tty=$(tmux display-message -p -t "$target" '#{pane_tty}' 2>/dev/null) || return 0
+  [ -n "$tty" ] || return 0
+  LC_ALL=C ps -t "${tty#/dev/}" -o pid=,pgid=,tpgid=,comm= 2>/dev/null \
+    | while read -r pid pgid tpgid comm; do
+        [ -n "$comm" ] || continue
+        [ "$pgid" = "$tpgid" ] || continue
+        printf '%s\n' "$comm"
+      done
+}
+
+fm_backend_tmux_foreground_argv0s() {  # <target>
+  local target=$1 tty pid pgid tpgid comm args argv0
+  tty=$(tmux display-message -p -t "$target" '#{pane_tty}' 2>/dev/null) || return 0
+  [ -n "$tty" ] || return 0
+  LC_ALL=C ps -t "${tty#/dev/}" -o pid=,pgid=,tpgid=,comm= 2>/dev/null \
+    | 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) || continue
+        args=${args#"${args%%[![:space:]]*}"}
+        argv0=${args%%[[:space:]]*}
+        [ -n "$argv0" ] && printf '%s\n' "$argv0"
+      done
+}
+
+# fm_backend_tmux_agent_state: recovery-grade harness-agent state for one
+# recorded target. See bin/fm-backend.sh's fm_backend_agent_state for the
+# shared state vocabulary and docs/tmux-backend.md "Agent liveness probe" for
+# the empirical basis. Tmux silently falls back to the active window when a
+# named target is absent, so the exact recorded window must appear in a
+# successful session inventory before its foreground command can be trusted.
+# An omitted window or a definitive missing-session/server response is
+# `missing`; any other inventory or pane read failure is `unreadable`, so a
+# transient tmux problem never licenses a duplicate.
+#
+# The verdict combines two independent name sources rather than trusting either
+# alone. Either source naming a verified harness is enough for `alive`, because
+# a false `dead` is the one outcome that can launch a duplicate agent onto a
+# live worktree, while the foreground process group - when it is readable - is
+# authoritative for the negative verdicts, since it is the only source that can
+# distinguish a truly idle pane from a rewritten process title.
+fm_backend_tmux_agent_state() {  # <target>
+  local target=$1 comm session window windows inventory_status
+  local foreground argv0s name fg_seen=0 fg_shell=0 fg_other=0
+  case "$target" in
+    *:*:*|'':*|*:'') printf 'unreadable'; return 0 ;;
+    *:*) ;;
+    *) printf 'unreadable'; return 0 ;;
+  esac
+  session=${target%%:*}
+  window=${target#*:}
+  if windows=$(LC_ALL=C tmux list-windows -t "$session" -F '#{window_name}' 2>&1); then
+    inventory_status=0
+  else
+    inventory_status=$?
+  fi
+  if [ "$inventory_status" -ne 0 ]; then
+    case "$windows" in
+      *"can't find session:"*|*"no server running on "*|*"error connecting to "*" (No such file or directory)"|*"error connecting to "*" (Connection refused)")
+        printf 'missing'
+        ;;
+      *)
+        printf 'unreadable'
+        ;;
+    esac
+    return 0
+  fi
+  if ! printf '%s\n' "$windows" | grep -Fqx "$window"; then
+    printf 'missing'
+    return 0
+  fi
+
+  foreground=$(fm_backend_tmux_foreground_comms "$target")
+  while IFS= read -r name; do
+    [ -n "$name" ] || continue
+    fg_seen=1
+    case "$(fm_backend_tmux_classify_process_name "$name")" in
+      agent) printf 'alive'; return 0 ;;
+      shell) fg_shell=1 ;;
+      *) fg_other=1 ;;
+    esac
+  done <<EOF
+$foreground
+EOF
+
+  argv0s=$(fm_backend_tmux_foreground_argv0s "$target")
+  while IFS= read -r name; do
+    [ -n "$name" ] || continue
+    if [ "$(fm_backend_tmux_classify_process_name '' "$name")" = agent ]; then
+      printf 'alive'
+      return 0
+    fi
+  done <<EOF
+$argv0s
+EOF
+
+  comm=$(fm_backend_tmux_current_command "$target") || {
+    printf 'unreadable'
+    return 0
+  }
+  if [ "$(fm_backend_tmux_classify_process_name "$comm")" = agent ]; then
+    printf 'alive'
+    return 0
+  fi
+
+  # A readable foreground process group settles the negative verdicts: only a
+  # group that is nothing but shells is confidently agent-free.
+  if [ "$fg_seen" -eq 1 ]; then
+    if [ "$fg_other" -eq 0 ] && [ "$fg_shell" -eq 1 ]; then
+      printf 'dead'
+    else
+      printf 'ambiguous'
+    fi
+    return 0
+  fi
+
+  case "$comm" in
+    '') printf 'unreadable'; return 0 ;;
+  esac
+  case "$(fm_backend_tmux_classify_process_name "$comm")" in
+    shell) printf 'dead' ;;
+    *) printf 'ambiguous' ;;
+  esac
+}
+
+# Backward-compatible three-state view for callers that only need a yes/no
+# agent verdict. The detailed state contract is owned by fm_backend_agent_state.
+fm_backend_tmux_agent_alive() {  # <target>
+  case "$(fm_backend_tmux_agent_state "$1")" in
+    alive) printf 'alive' ;;
+    dead|missing) printf 'dead' ;;
+    *) printf 'unknown' ;;
+  esac
+}